@fedify/vocab-tools 2.3.0-dev.994 → 2.3.0-pr.809.37

package/deno.json

@@ -1,6 +1,6 @@
 {
   "name": "@fedify/vocab-tools",
-  "version": "2.3.0-dev.994+9071ca0a",
+  "version": "2.3.0-pr.809.37+0574ba5c",
   "license": "MIT",
   "exports": {
     ".": "./src/mod.ts"
@@ -12,7 +12,7 @@
   },
   "imports": {
     "@cfworker/json-schema": "npm:@cfworker/json-schema@^4.1.1",
-    "yaml": "npm:yaml@^2.8.1"
+    "yaml": "npm:yaml@^2.9.0"
   },
   "exclude": [
     "dist",

package/dist/mod.cjs

@@ -8,7 +8,7 @@ let yaml = require("yaml");
 let es_toolkit = require("es-toolkit");
 //#region deno.json
 var name = "@fedify/vocab-tools";
-var version = "2.3.0-dev.994+9071ca0a";
+var version = "2.3.0-pr.809.37+0574ba5c";
 //#endregion
 //#region src/type.ts
 const HEURISTICS_CONTEXTS = [
@@ -208,7 +208,7 @@ const scalarTypes = {
 	"http://www.w3.org/2001/XMLSchema#dateTime": {
 		name: "Temporal.Instant",
 		typeGuard(v) {
-			return `${v} instanceof Temporal.Instant`;
+			return `isTemporalInstant(${v})`;
 		},
 		encoder(v) {
 			return `{
@@ -238,7 +238,7 @@ const scalarTypes = {
 	"http://www.w3.org/2001/XMLSchema#duration": {
 		name: "Temporal.Duration",
 		typeGuard(v) {
-			return `${v} instanceof Temporal.Duration`;
+			return `isTemporalDuration(${v})`;
 		},
 		encoder(v) {
 			return `{
@@ -712,6 +712,38 @@ async function loadSchemaFiles(dir) {
 }
 //#endregion
 //#region src/codec.ts
+function* generatePreprocessorBlock(property, rangeTypeName, variable, baseUrlExpr, moduleVarNames) {
+	if (property.preprocessors == null || property.preprocessors.length === 0) return;
+	yield `
+      {
+        let _handled: ${rangeTypeName} | undefined;
+      `;
+	for (const pp of property.preprocessors) {
+		const varName = moduleVarNames.get(pp.module);
+		if (varName == null) throw new Error(`Preprocessor module "${pp.module}" is not registered in the generated imports. Ensure all preprocessor modules used in property schemas are available.`);
+		yield `
+        if (_handled === undefined) {
+          const _result = await ${varName}[${JSON.stringify(pp.function)}](v, {
+            documentLoader: options.documentLoader,
+            contextLoader: options.contextLoader,
+            tracerProvider: options.tracerProvider,
+            baseUrl: ${baseUrlExpr},
+          });
+          if (_result instanceof Error) throw _result;
+          if (_result !== undefined) {
+            _handled = _result as ${rangeTypeName};
+          }
+        }
+      `;
+	}
+	yield `
+        if (_handled !== undefined) {
+          ${variable}.push(_handled);
+          continue;
+        }
+      }
+      `;
+}
 async function* generateEncoder(typeUri, types) {
 	const type = types[typeUri];
 	yield `
@@ -912,7 +944,7 @@ async function* generateEncoder(typeUri, types) {
   }
   `;
 }
-async function* generateDecoder(typeUri, types) {
+async function* generateDecoder(typeUri, types, moduleVarNames) {
 	const type = types[typeUri];
 	yield `
   /**
@@ -996,7 +1028,10 @@ async function* generateDecoder(typeUri, types) {
         // deno-lint-ignore no-explicit-any
         (expanded[0] ?? {}) as (Record<string, any[]> & { "@id"?: string });
     }
-    if (options.baseUrl == null && values["@id"] != null) {
+    if (values["@id"] != null && !values["@id"].startsWith("_:") && !URL.canParse(values["@id"], options.baseUrl)) {
+      throw new TypeError("Invalid @id: " + values["@id"]);
+    }
+    if (options.baseUrl == null && values["@id"] != null && !values["@id"].startsWith("_:") && URL.canParse(values["@id"])) {
       options = { ...options, baseUrl: new URL(values["@id"]) };
     }
   `;
@@ -1021,7 +1056,7 @@ async function* generateDecoder(typeUri, types) {
   `;
 	if (type.extends == null) yield `
     const instance = new this(
-      { id: "@id" in values ? new URL(values["@id"] as string) : undefined },
+      { id: values["@id"] != null && !values["@id"].startsWith("_:") && URL.canParse(values["@id"], options.baseUrl) ? new URL(values["@id"], options.baseUrl) : undefined },
       options,
     );
     `;
@@ -1058,26 +1093,29 @@ async function* generateDecoder(typeUri, types) {
     ) {
       if (v == null) continue;
     `;
+		const propertyBaseUrl = "options.baseUrl";
+		yield* generatePreprocessorBlock(property, getTypeNames(property.range, types), variable, propertyBaseUrl, moduleVarNames);
 		if (!areAllScalarTypes(property.range, types)) yield `
       if (typeof v === "object" && "@id" in v && !("@type" in v)
           && globalThis.Object.keys(v).length === 1) {
+        if (v["@id"].startsWith("_:")) continue;
         ${variable}.push(
-          !URL.canParse(v["@id"]) && v["@id"].startsWith("at://")
+          !URL.canParse(v["@id"], ${propertyBaseUrl}) && v["@id"].startsWith("at://")
             ? new URL("at://" + encodeURIComponent(v["@id"].substring(5)))
-            : new URL(v["@id"])
+            : new URL(v["@id"], ${propertyBaseUrl})
         );
         continue;
       }
       `;
 		if (property.range.length == 1) yield `
-      const decoded = ${getDecoder(property.range[0], types, "v", "options", `(values["@id"] == null ? options.baseUrl : new URL(values["@id"]))`)};
+      const decoded = ${getDecoder(property.range[0], types, "v", "options", propertyBaseUrl)};
       if (typeof decoded === "undefined") continue;
       ${variable}.push(decoded);`;
 		else {
 			yield `
       const decoded =
       `;
-			const decoders = getDecoders(property.range, types, "v", "options", `(values["@id"] == null ? options.baseUrl : new URL(values["@id"]))`);
+			const decoders = getDecoders(property.range, types, "v", "options", propertyBaseUrl);
 			for (const code of decoders) yield code;
 			yield `
       ;
@@ -1152,6 +1190,8 @@ async function* generateConstructor(typeUri, types) {
     this.#documentLoader = options.documentLoader;
     this.#contextLoader = options.contextLoader;
     this.#tracerProvider = options.tracerProvider;
+    const baseUrl = (options as { baseUrl?: URL }).baseUrl;
+    this.#_baseUrl = baseUrl == null ? undefined : new URL(baseUrl.href);
     if ("$warning" in options) {
       this.#warning = options.$warning as unknown as {
         category: string[];
@@ -1463,9 +1503,16 @@ function emitOverride(typeUri, types, property) {
 	}
 	return "";
 }
-async function* generateProperty(type, property, types) {
+async function* generateProperty(type, property, types, moduleVarNames) {
 	const override = emitOverride(type.uri, types, property);
 	const doc = `\n/** ${property.description.replaceAll("\n", "\n * ")}\n */\n`;
+	const cachedPropertyBaseUrl = `(options as { baseUrl?: URL }).baseUrl ??
+                this._baseUrl ??
+                (this.id != null &&
+                    (this.id.protocol === "http:" ||
+                      this.id.protocol === "https:")
+                  ? this.id
+                  : undefined)`;
 	if (areAllScalarTypes(property.range, types)) {
 		if (hasSingularAccessor(property)) {
 			yield doc;
@@ -1598,6 +1645,36 @@ async function* generateProperty(type, property, types) {
         this._tracerProvider ?? trace.getTracerProvider();
       const baseUrl = options.baseUrl;
     `;
+		if (property.preprocessors != null && property.preprocessors.length > 0) {
+			yield `
+        if (jsonLd != null && typeof jsonLd === "object") {
+          const _expanded = await jsonld.expand(jsonLd, {
+            documentLoader: contextLoader,
+            keepFreeFloatingNodes: true,
+          });
+          for (const _pp_obj of _expanded) {
+      `;
+			for (const pp of property.preprocessors) {
+				const varName = moduleVarNames.get(pp.module);
+				if (varName == null) throw new Error(`Preprocessor module "${pp.module}" is not registered in the generated imports. Ensure all preprocessor modules used in property schemas are available.`);
+				yield `
+            {
+              const _result = await ${varName}[${JSON.stringify(pp.function)}](_pp_obj, {
+                documentLoader,
+                contextLoader,
+                tracerProvider,
+                baseUrl,
+              });
+              if (_result instanceof Error) throw _result;
+              if (_result !== undefined) return _result as ${getTypeNames(property.range, types)};
+            }
+        `;
+			}
+			yield `
+          }
+        }
+      `;
+		}
 		for (const range of property.range) {
 			if (!(range in types)) continue;
 			yield `
@@ -1671,7 +1748,8 @@ async function* generateProperty(type, property, types) {
           return fetched;
         }
       `;
-			if (property.compactName != null) yield `
+			if (property.compactName != null) {
+				yield `
         if (
           this._cachedJsonLd != null &&
           typeof this._cachedJsonLd === "object" &&
@@ -1682,10 +1760,18 @@ async function* generateProperty(type, property, types) {
             ${JSON.stringify(property.compactName)}];
           const doc = Array.isArray(prop) ? prop[0] : prop;
           if (doc != null && typeof doc === "object" && "@context" in doc) {
-            v = await this.#${property.singularName}_fromJsonLd(doc, options);
+      `;
+				yield `
+            v = await this.#${property.singularName}_fromJsonLd(doc, {
+              ...options,
+              baseUrl: ${cachedPropertyBaseUrl},
+            });
+      `;
+				yield `
           }
         }
         `;
+			}
 			yield `
         if (options.crossOrigin !== "trust" && v?.id != null &&
             this.id != null && v.id.origin !== this.id.origin &&
@@ -1768,7 +1854,8 @@ async function* generateProperty(type, property, types) {
             continue;
           }
       `;
-			if (property.compactName != null) yield `
+			if (property.compactName != null) {
+				yield `
           if (
             this._cachedJsonLd != null &&
             typeof this._cachedJsonLd === "object" &&
@@ -1779,10 +1866,18 @@ async function* generateProperty(type, property, types) {
               ${JSON.stringify(property.compactName)}];
             const obj = Array.isArray(prop) ? prop[i] : prop;
             if (obj != null && typeof obj === "object" && "@context" in obj) {
-              v = await this.#${property.singularName}_fromJsonLd(obj, options);
+      `;
+				yield `
+              v = await this.#${property.singularName}_fromJsonLd(obj, {
+                ...options,
+                baseUrl: ${cachedPropertyBaseUrl},
+              });
+      `;
+				yield `
             }
           }
         `;
+			}
 			yield `
           if (options.crossOrigin !== "trust" && v?.id != null &&
               this.id != null && v.id.origin !== this.id.origin &&
@@ -1813,9 +1908,9 @@ async function* generateProperty(type, property, types) {
 		}
 	}
 }
-async function* generateProperties(typeUri, types) {
+async function* generateProperties(typeUri, types, moduleVarNames) {
 	const type = types[typeUri];
-	for (const property of type.properties) yield* generateProperty(type, property, types);
+	for (const property of type.properties) yield* generateProperty(type, property, types, moduleVarNames);
 }
 //#endregion
 //#region src/class.ts
@@ -1841,7 +1936,7 @@ function sortTopologically(types) {
 		sorted.push(node.uri);
 	}
 }
-async function* generateClass(typeUri, types) {
+async function* generateClass(typeUri, types, moduleVarNames) {
 	const type = types[typeUri];
 	yield `/** ${type.description.replaceAll("\n", "\n * ")}\n */\n`;
 	if (type.extends) {
@@ -1858,6 +1953,7 @@ async function* generateClass(typeUri, types) {
       values?: Record<string, unknown>;
     };
     #cachedJsonLd?: unknown;
+    readonly #_baseUrl?: URL;
     readonly id: URL | null;
 
     protected get _documentLoader(): DocumentLoader | undefined {
@@ -1887,6 +1983,10 @@ async function* generateClass(typeUri, types) {
     protected set _cachedJsonLd(value: unknown | undefined) {
       this.#cachedJsonLd = value;
     }
+
+    protected get _baseUrl(): URL | undefined {
+      return this.#_baseUrl;
+    }
     `;
 	yield `
     /**
@@ -1899,9 +1999,9 @@ async function* generateClass(typeUri, types) {
 	for await (const code of generateFields(typeUri, types)) yield code;
 	for await (const code of generateConstructor(typeUri, types)) yield code;
 	for await (const code of generateCloner(typeUri, types)) yield code;
-	for await (const code of generateProperties(typeUri, types)) yield code;
+	for await (const code of generateProperties(typeUri, types, moduleVarNames)) yield code;
 	for await (const code of generateEncoder(typeUri, types)) yield code;
-	for await (const code of generateDecoder(typeUri, types)) yield code;
+	for await (const code of generateDecoder(typeUri, types, moduleVarNames)) yield code;
 	for await (const code of generateInspector(typeUri, types)) yield code;
 	yield "}\n\n";
 	for await (const code of generateInspectorPostClass(typeUri, types)) yield code;
@@ -1970,15 +2070,29 @@ async function* generateClasses(types) {
 		"parseDecimal",
 		"type RemoteDocument"
 	];
-	yield "// deno-lint-ignore-file ban-unused-ignore no-unused-vars prefer-const verbatim-module-syntax\n";
+	yield "// deno-lint-ignore-file ban-unused-ignore no-explicit-any no-unused-vars prefer-const verbatim-module-syntax\n";
 	yield "import jsonld from \"@fedify/vocab-runtime/jsonld\";\n";
 	yield "import { getLogger } from \"@logtape/logtape\";\n";
 	yield `import { type Span, SpanStatusCode, type TracerProvider, trace }
     from "@opentelemetry/api";\n`;
 	yield `import {\n    ${runtimeImports.join(",\n    ")}\n} from "@fedify/vocab-runtime";\n`;
+	yield `import {
+    isTemporalDuration,
+    isTemporalInstant,
+} from "@fedify/vocab-runtime/temporal";\n`;
 	yield "\n\n";
+	const moduleVarNames = /* @__PURE__ */ new Map();
 	const sorted = sortTopologically(types);
-	for (const typeUri of sorted) for await (const code of generateClass(typeUri, types)) yield code;
+	for (const typeUri of sorted) for (const property of types[typeUri].properties) {
+		if (property.preprocessors == null) continue;
+		for (const pp of property.preprocessors) if (!moduleVarNames.has(pp.module)) {
+			const name = `_ppM${moduleVarNames.size}`;
+			moduleVarNames.set(pp.module, name);
+		}
+	}
+	for (const [modulePath, varName] of moduleVarNames) yield `import * as ${varName} from ${JSON.stringify(modulePath)};\n`;
+	if (moduleVarNames.size > 0) yield "\n";
+	for (const typeUri of sorted) for await (const code of generateClass(typeUri, types, moduleVarNames)) yield code;
 	for (const code of generateEntityTypeHelpers(sorted, types)) yield code;
 }
 //#endregion

package/dist/mod.d.cts

@@ -100,6 +100,30 @@ interface PropertySchemaBase {
     */
     inherit: true;
   };
+  /**
+  * Preprocessors for this property.  Each preprocessor receives an expanded
+  * JSON-LD property value and may return a vocabulary object matching the
+  * property's declared range, `undefined` when it did not handle the value,
+  * or an `Error` when it recognized the value but failed while converting it.
+  *
+  * `module` is resolved from the generated vocabulary source file
+  * and imported statically at the top of the generated file.
+  */
+  preprocessors?: PropertyPreprocessorSchema[];
+}
+/**
+* A schema for a property preprocessor that normalizes wire-level values
+* before the generated range decoder runs.
+*/
+interface PropertyPreprocessorSchema {
+  /**
+  * Module specifier resolved from the generated vocabulary source file.
+  */
+  module: string;
+  /**
+  * The name of the exported function in the module.
+  */
+  function: string;
 }
 type PropertySchemaTyping = {
   /**
@@ -196,4 +220,4 @@ declare function loadSchemaFiles(dir: string): Promise<Record<string, TypeSchema
 //#region src/type.d.ts
 declare function areAllScalarTypes(typeUris: string[], types: Record<string, TypeSchema>): boolean;
 //#endregion
-export { type PropertySchema, type TypeSchema, areAllScalarTypes, generateVocab, loadSchemaFiles };
+export { type PropertyPreprocessorSchema, type PropertySchema, type TypeSchema, areAllScalarTypes, generateVocab, loadSchemaFiles };

package/dist/mod.d.ts

@@ -100,6 +100,30 @@ interface PropertySchemaBase {
     */
     inherit: true;
   };
+  /**
+  * Preprocessors for this property.  Each preprocessor receives an expanded
+  * JSON-LD property value and may return a vocabulary object matching the
+  * property's declared range, `undefined` when it did not handle the value,
+  * or an `Error` when it recognized the value but failed while converting it.
+  *
+  * `module` is resolved from the generated vocabulary source file
+  * and imported statically at the top of the generated file.
+  */
+  preprocessors?: PropertyPreprocessorSchema[];
+}
+/**
+* A schema for a property preprocessor that normalizes wire-level values
+* before the generated range decoder runs.
+*/
+interface PropertyPreprocessorSchema {
+  /**
+  * Module specifier resolved from the generated vocabulary source file.
+  */
+  module: string;
+  /**
+  * The name of the exported function in the module.
+  */
+  function: string;
 }
 type PropertySchemaTyping = {
   /**
@@ -196,4 +220,4 @@ declare function loadSchemaFiles(dir: string): Promise<Record<string, TypeSchema
 //#region src/type.d.ts
 declare function areAllScalarTypes(typeUris: string[], types: Record<string, TypeSchema>): boolean;
 //#endregion
-export { type PropertySchema, type TypeSchema, areAllScalarTypes, generateVocab, loadSchemaFiles };
+export { type PropertyPreprocessorSchema, type PropertySchema, type TypeSchema, areAllScalarTypes, generateVocab, loadSchemaFiles };