Add property preprocessors to @fedify/vocab-tools and normalize Link icon/image

CHANGES.md

@@ -341,6 +341,30 @@ To be released.
 
 [#489]: https://github.com/fedify-dev/fedify/issues/489
 
+### @fedify/vocab-runtime
+
+ -  Added `PropertyPreprocessor`, `PropertyPreprocessorContext`, and `Json`
+    types for normalizing wire-level JSON-LD property values before the
+    generated range decoder runs.  [[#792]]
+
+[#792]: https://github.com/fedify-dev/fedify/issues/792
+
+### @fedify/vocab
+
+ -  Explicit ActivityStreams `Link` objects in `icon` and `image` properties
+    are now normalized to `Image` during decoding via the new exported
+    `normalizeLinkToImage()` preprocessor.  The public `Image`-oriented
+    TypeScript API is unchanged.  [[#790], [#792]]
+
+[#790]: https://github.com/fedify-dev/fedify/issues/790
+
+### @fedify/vocab-tools
+
+ -  Property schemas now support a `preprocessors` field that lists
+    module/function pairs.  Generated decoders dynamically import and run
+    these preprocessors for each expanded JSON-LD property value before
+    falling back to the normal range decoder.  [[#792]]
+
 
 Version 2.2.5
 -------------

packages/vocab-runtime/src/mod.ts

@@ -44,6 +44,11 @@ export {
   type GetUserAgentOptions,
   logRequest,
 } from "./request.ts";
+export {
+  type Json,
+  type PropertyPreprocessor,
+  type PropertyPreprocessorContext,
+} from "./preprocessor.ts";
 export {
   expandIPv6Address,
   isValidPublicIPv4Address,

packages/vocab-runtime/src/preprocessor.ts

@@ -0,0 +1,43 @@
+import type { DocumentLoader } from "./docloader.ts";
+import type { TracerProvider } from "@opentelemetry/api";
+
+/**
+ * JSON value shape passed to property preprocessors.
+ * @since 2.3.0
+ */
+export type Json =
+  | string
+  | number
+  | boolean
+  | null
+  | readonly Json[]
+  | { readonly [key: string]: Json };
+
+/**
+ * Runtime context provided to property preprocessors.
+ * @since 2.3.0
+ */
+export interface PropertyPreprocessorContext {
+  /** Loader for remote JSON-LD documents. */
+  documentLoader?: DocumentLoader;
+  /** Loader for remote JSON-LD contexts. */
+  contextLoader?: DocumentLoader;
+  /** OpenTelemetry tracer provider for instrumentation. */
+  tracerProvider?: TracerProvider;
+  /** Base URL for resolving relative references. */
+  baseUrl?: URL;
+}
+
+/**
+ * Function signature for schema-configured property preprocessors.
+ *
+ * Receives an expanded JSON-LD property value and returns a vocabulary
+ * object when the value is handled, `undefined` when the value should
+ * fall through to the normal range decoder, or an `Error` when the value
+ * is recognized but cannot be converted.
+ * @since 2.3.0
+ */
+export type PropertyPreprocessor<T = unknown> = (
+  value: Json,
+  context: PropertyPreprocessorContext,
+) => T | undefined | Error | Promise<T | undefined | Error>;