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
 -------------

docs/.gitignore

@@ -1,5 +1,5 @@
 .jsr-cache.json
-.jsr-*-cache.json
+.jsr-cache-*.json
 .vitepress/cache/
 .vitepress/dist/
 node_modules/

docs/.vitepress/config.mts

@@ -1,4 +1,3 @@
-import taskLists from "@hackmd/markdown-it-task-lists";
 import { transformerTwoslash } from "@shikijs/vitepress-twoslash";
 import abbr from "markdown-it-abbr";
 import deflist from "markdown-it-deflist";
@@ -15,24 +14,15 @@ import {
 import llmstxt from "vitepress-plugin-llms";
 import { withMermaid } from "vitepress-plugin-mermaid";
 
-const jsrRefVersion = process.env.JSR_REF_VERSION ?? "unstable";
-const jsrRefPackages = [
-  ["@fedify/fedify", ".jsr-cache.json"],
-  ["@fedify/vocab", ".jsr-vocab-cache.json"],
-  ["@fedify/vocab-runtime", ".jsr-vocab-runtime-cache.json"],
-  ["@fedify/webfinger", ".jsr-webfinger-cache.json"],
-  ["@fedify/debugger", ".jsr-debugger-cache.json"],
-  ["@fedify/testing", ".jsr-testing-cache.json"],
-] as const;
-const jsrRefPlugins = await Promise.all(
-  jsrRefPackages.map(([packageName, cachePath]) =>
-    jsrRef({
-      package: packageName,
-      version: jsrRefVersion,
-      cachePath,
-    })
-  ),
-);
+const jsrRefPlugins: (Awaited<ReturnType<typeof jsrRef>>)[] = [];
+for (const pkg of ["fedify", "vocab", "vocab-runtime", "webfinger"]) {
+  const jsrRefPlugin = await jsrRef({
+    package: `@fedify/${pkg}`,
+    version: process.env.JSR_REF_VERSION ?? "unstable",
+    cachePath: `.jsr-cache-${pkg}.json`,
+  });
+  jsrRefPlugins.push(jsrRefPlugin);
+}
 
 let extraNav: { text: string; link: string }[] = [];
 if (process.env.EXTRA_NAV_TEXT && process.env.EXTRA_NAV_LINK) {
@@ -112,15 +102,6 @@ const TUTORIAL = {
     },
     { text: "Learning the basics", link: "/tutorial/basics.md" },
     { text: "Creating a microblog", link: "/tutorial/microblog.md" },
-    {
-      text: "Creating an image sharing service",
-      link: "/tutorial/content-sharing.md",
-    },
-    { text: "Building a federated blog", link: "/tutorial/astro-blog.md" },
-    {
-      text: "Building a threadiverse community",
-      link: "/tutorial/threadiverse.md",
-    },
   ],
   activeMatch: "/tutorial",
 };
@@ -134,7 +115,6 @@ const MANUAL = {
     { text: "Vocabulary", link: "/manual/vocab.md" },
     { text: "Actor dispatcher", link: "/manual/actor.md" },
     { text: "Inbox listeners", link: "/manual/inbox.md" },
-    { text: "Outbox listeners", link: "/manual/outbox.md" },
     { text: "Sending activities", link: "/manual/send.md" },
     { text: "Collections", link: "/manual/collections.md" },
     { text: "Object dispatcher", link: "/manual/object.md" },
@@ -145,16 +125,13 @@ const MANUAL = {
     { text: "Pragmatics", link: "/manual/pragmatics.md" },
     { text: "Key–value store", link: "/manual/kv.md" },
     { text: "Message queue", link: "/manual/mq.md" },
-    { text: "Circuit breaker", link: "/manual/circuit-breaker.md" },
     { text: "Integration", link: "/manual/integration.md" },
-    { text: "Migration", link: "/manual/migrate.md" },
     { text: "Relay", link: "/manual/relay.md" },
     { text: "Testing", link: "/manual/test.md" },
     { text: "Debugging", link: "/manual/debug.md" },
     { text: "Linting", link: "/manual/lint.md" },
     { text: "Logging", link: "/manual/log.md" },
     { text: "OpenTelemetry", link: "/manual/opentelemetry.md" },
-    { text: "Benchmarking", link: "/manual/benchmarking.md" },
     { text: "Deployment", link: "/manual/deploy.md" },
   ],
   activeMatch: "/manual",
@@ -292,15 +269,12 @@ export default withMermaid(defineConfig({
       transformerTwoslash({
         twoslashOptions: {
           compilerOptions: {
+            ignoreDeprecations: "6.0",
             moduleResolution: ModuleResolutionKind.Bundler,
             module: ModuleKind.ESNext,
             target: ScriptTarget.ESNext,
             experimentalDecorators: true, // For @fedify/nestjs
             emitDecoratorMetadata: true, // For @fedify/nestjs
-            // Silences TS5101 about the `baseUrl` injected by @typescript/vfs
-            // when Twoslash spins up its virtual TS environment; the option
-            // is deprecated in TypeScript 6.0 and removed in 7.0.
-            ignoreDeprecations: "6.0",
             lib: ["dom", "dom.iterable", "esnext"],
             types: [
               "dom",
@@ -321,7 +295,6 @@ export default withMermaid(defineConfig({
       md.use(abbr);
       md.use(deflist);
       md.use(footnote);
-      md.use(taskLists);
       md.use(groupIconMdPlugin);
       for (const jsrRefPlugin of jsrRefPlugins) {
         md.use(jsrRefPlugin);
@@ -336,20 +309,14 @@ export default withMermaid(defineConfig({
     plugins: [
       groupIconVitePlugin(),
       llmstxt({
-        ignoreFilesPerOutput: {
-          llmsTxt: [
-            "changelog.md",
-            "contribute.md",
-            "README.md",
-            "sponsors.md",
-          ],
-          llmsFullTxt: [
-            "changelog.md",
-            "contribute.md",
-            "README.md",
-            "sponsors.md",
-          ],
-        },
+        ignoreFiles: [
+          "changelog.md",
+          "contribute.md",
+          "README.md",
+          "security.md",
+          "sponsors.md",
+          "tutorial.md",
+        ],
       }),
     ],
   },

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>;