@fedify/vocab-tools 2.4.0-dev.1666 → 2.4.0-dev.1727

package/README.md

@@ -25,3 +25,24 @@ pnpm add @fedify/vocab-tools
 ~~~~ bash
 yarn add @fedify/vocab-tools
 ~~~~
+
+
+Development
+-----------
+
+Run development tasks from the repository root with [mise].
+
+[mise]: https://mise.jdx.dev/
+
+### Updating snapshots
+
+The code generator has separate output snapshots for Deno, Node.js, and Bun.
+When a change affects generated output, update all three from the repository
+root:
+
+~~~~ bash
+mise run test:update_snapshots
+~~~~
+
+Review and commit every changed snapshot file.  Updating only one runtime
+leaves the other test suites with stale expectations.

package/deno.json

@@ -1,6 +1,6 @@
 {
   "name": "@fedify/vocab-tools",
-  "version": "2.4.0-dev.1666+690d9b28",
+  "version": "2.4.0-dev.1727+1eadcb04",
   "license": "MIT",
   "exports": {
     ".": "./src/mod.ts"

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.4.0-dev.1666+690d9b28";
+var version = "2.4.0-dev.1727+1eadcb04";
 //#endregion
 //#region src/type.ts
 const HEURISTICS_CONTEXTS = [
@@ -186,7 +186,8 @@ const scalarTypes = {
 		dataCheck(v) {
 			return `typeof ${v} === "object" && "@language" in ${v} && "@value" in ${v}
         && typeof ${v}["@language"] === "string"
-        && typeof ${v}["@value"] === "string"`;
+        && typeof ${v}["@value"] === "string"
+        && isValidLanguageTag(${v}["@language"])`;
 		},
 		decoder(v) {
 			return `new LanguageString(${v}["@value"], ${v}["@language"])`;
@@ -871,12 +872,17 @@ async function* generateEncoder(typeUri, types) {
 		yield `
     array = [];
     for (const v of this.${await getFieldName(property.uri)}) {
-      const element = (
+      let element = (
     `;
 		if (!areAllScalarTypes(property.range, types)) yield "v instanceof URL ? { \"@id\": formatIri(v) } : ";
 		for (const code of getEncoders(property.range, types, "v", "options")) yield code;
 		yield `
       );
+      if (Array.isArray(element)) {
+        if (element.length < 1) continue;
+        if (element.length == 1) element = element[0];
+      }
+      if (typeof element === "undefined") continue;
     `;
 		if (isNonFunctionalProperty(property) && property.container === "graph") yield `array.push({ "@graph": element });`;
 		else yield `array.push(element);`;
@@ -904,7 +910,10 @@ async function* generateEncoder(typeUri, types) {
     if (options.format === "expand") {
       return await jsonld.expand(
         values,
-        { documentLoader: options.contextLoader },
+        {
+          documentLoader: options.contextLoader,
+          keepFreeFloatingNodes: true,
+        },
       );
     }
     const docContext = options.context ??
@@ -1027,7 +1036,17 @@ async function* generateDecoder(typeUri, types, moduleVarNames) {
     // deno-lint-ignore no-explicit-any
     let values: Record<string, any[]> & { "@id"?: string };
     let expanded: unknown[];
-    if (globalThis.Object.keys(json).length == 0) {
+    if (
+      "_fromSubclass" in options &&
+      options._fromSubclass &&
+      typeof json === "object" &&
+      !Array.isArray(json)
+    ) {
+      values =
+        // deno-lint-ignore no-explicit-any
+        json as (Record<string, any[]> & { "@id"?: string });
+      expanded = [values];
+    } else if (globalThis.Object.keys(json).length == 0) {
       values = {};
       expanded = [values];
     } else {
@@ -1084,8 +1103,9 @@ async function* generateDecoder(typeUri, types, moduleVarNames) {
     );
     `;
 	else yield `
-    delete values["@type"];
-    const instance = await super.fromJsonLd(values, {
+    const superValues = structuredClone(values);
+    delete superValues["@type"];
+    const instance = await super.fromJsonLd(superValues, {
       ...options,
       // @ts-ignore: an internal option
       _fromSubclass: true,
@@ -1094,6 +1114,9 @@ async function* generateDecoder(typeUri, types, moduleVarNames) {
       throw new TypeError("Unexpected type: " + instance.constructor.name);
     }
     `;
+	yield `
+    let shouldCacheJsonLd = instance._shouldCacheJsonLd;
+  `;
 	for (const property of type.properties) {
 		const variable = await getFieldName(property.uri, "");
 		yield await generateField(property, types, "const ");
@@ -1106,13 +1129,20 @@ async function* generateDecoder(typeUri, types, moduleVarNames) {
           ${arrayVariable} = values[${JSON.stringify(prop.uri)}];
         }
         `;
+		let itemsExpression = `${arrayVariable}.length === 1 && "@list" in ${arrayVariable}[0]
+        ? ${arrayVariable}[0]["@list"]
+        : ${arrayVariable}`;
+		if (isNonFunctionalProperty(property) && property.container === "graph") itemsExpression = `(${itemsExpression}).flatMap((item: unknown) =>
+          item != null && typeof item === "object" && "@graph" in item &&
+            Array.isArray((item as { "@graph": unknown })["@graph"])
+            ? (item as { "@graph": unknown[] })["@graph"]
+            : [item]
+        )`;
 		yield `
     for (
       const v of ${arrayVariable} == null
         ? []
-        : ${arrayVariable}.length === 1 && "@list" in ${arrayVariable}[0]
-        ? ${arrayVariable}[0]["@list"]
-        : ${arrayVariable}
+        : ${itemsExpression}
     ) {
       if (v == null) continue;
     `;
@@ -1126,29 +1156,40 @@ async function* generateDecoder(typeUri, types, moduleVarNames) {
         continue;
       }
       `;
-		if (property.range.length == 1) yield `
-      const decoded = ${getDecoder(property.range[0], types, "v", "options", propertyBaseUrl)};
-      if (typeof decoded === "undefined") continue;
-      ${variable}.push(decoded);`;
-		else {
-			yield `
+		yield `
       const decoded =
-      `;
+    `;
+		if (property.range.length == 1) yield getDecoder(property.range[0], types, "v", "options", propertyBaseUrl);
+		else {
 			const decoders = getDecoders(property.range, types, "v", "options", propertyBaseUrl);
 			for (const code of decoders) yield code;
-			yield `
+		}
+		yield `
       ;
-      if (typeof decoded === "undefined") continue;
+    `;
+		yield `
+      if (typeof decoded === "undefined") {
+        shouldCacheJsonLd = false;
+        continue;
+      }
+    `;
+		yield `
+      if (!this._shouldCacheDecodedJsonLd(decoded)) {
+        shouldCacheJsonLd = false;
+      }
       ${variable}.push(decoded);
-      `;
-		}
+    `;
 		yield `
     }
     instance.${await getFieldName(property.uri)} = ${variable};
     `;
 	}
 	yield `
-    if (!("_fromSubclass" in options) || !options._fromSubclass) {
+    instance._shouldCacheJsonLd = shouldCacheJsonLd;
+    if (
+      shouldCacheJsonLd &&
+      (!("_fromSubclass" in options) || !options._fromSubclass)
+    ) {
       try {
         if (cacheJsonLd != null && cacheJsonLd !== expanded) {
           const compactArray = Array.isArray(json) && json.length === 1;
@@ -2016,6 +2057,7 @@ async function* generateClass(typeUri, types, moduleVarNames) {
     };
     #cachedJsonLd?: unknown;
     readonly #_baseUrl?: URL;
+    #shouldCacheJsonLd = true;
     readonly id: URL | null;
 
     protected get _documentLoader(): DocumentLoader | undefined {
@@ -2049,6 +2091,20 @@ async function* generateClass(typeUri, types, moduleVarNames) {
     protected get _baseUrl(): URL | undefined {
       return this.#_baseUrl;
     }
+
+    protected get _shouldCacheJsonLd(): boolean {
+      return this.#shouldCacheJsonLd;
+    }
+
+    protected set _shouldCacheJsonLd(value: boolean) {
+      this.#shouldCacheJsonLd = value;
+    }
+
+    protected static _shouldCacheDecodedJsonLd(value: unknown): boolean {
+      if (value == null || typeof value !== "object") return true;
+      if (!("_shouldCacheJsonLd" in value)) return true;
+      return (value as { _shouldCacheJsonLd: boolean })._shouldCacheJsonLd;
+    }
     `;
 	yield `
     /**
@@ -2139,7 +2195,19 @@ async function* generateClasses(types) {
     isTemporalDuration,
     isTemporalInstant,
 } from "@fedify/vocab-runtime/temporal";\n`;
-	const portableIriKeys = new Set(["@id", "id"]);
+	yield `
+function isValidLanguageTag(language: string): boolean {
+  try {
+    new Intl.Locale(language);
+    return true;
+  } catch (error) {
+    if (error instanceof RangeError) return false;
+    throw error;
+  }
+}
+`;
+	yield "\n\n";
+	const portableIriKeys = /* @__PURE__ */ new Set(["@id", "id"]);
 	for (const type of Object.values(types)) for (const property of type.properties) addPortableIriKeys(portableIriKeys, property, types);
 	yield "const PORTABLE_IRI_PATTERN = /^ap(?:\\+ef61)?:\\/\\//i;\n";
 	yield `const PORTABLE_IRI_KEYS: ReadonlySet<string> = new Set(${JSON.stringify([...portableIriKeys].sort())});\n\n`;

package/dist/mod.js

@@ -7,7 +7,7 @@ import { parse } from "yaml";
 import { pascalCase } from "es-toolkit";
 //#region deno.json
 var name = "@fedify/vocab-tools";
-var version = "2.4.0-dev.1666+690d9b28";
+var version = "2.4.0-dev.1727+1eadcb04";
 //#endregion
 //#region src/type.ts
 const HEURISTICS_CONTEXTS = [
@@ -185,7 +185,8 @@ const scalarTypes = {
 		dataCheck(v) {
 			return `typeof ${v} === "object" && "@language" in ${v} && "@value" in ${v}
         && typeof ${v}["@language"] === "string"
-        && typeof ${v}["@value"] === "string"`;
+        && typeof ${v}["@value"] === "string"
+        && isValidLanguageTag(${v}["@language"])`;
 		},
 		decoder(v) {
 			return `new LanguageString(${v}["@value"], ${v}["@language"])`;
@@ -870,12 +871,17 @@ async function* generateEncoder(typeUri, types) {
 		yield `
     array = [];
     for (const v of this.${await getFieldName(property.uri)}) {
-      const element = (
+      let element = (
     `;
 		if (!areAllScalarTypes(property.range, types)) yield "v instanceof URL ? { \"@id\": formatIri(v) } : ";
 		for (const code of getEncoders(property.range, types, "v", "options")) yield code;
 		yield `
       );
+      if (Array.isArray(element)) {
+        if (element.length < 1) continue;
+        if (element.length == 1) element = element[0];
+      }
+      if (typeof element === "undefined") continue;
     `;
 		if (isNonFunctionalProperty(property) && property.container === "graph") yield `array.push({ "@graph": element });`;
 		else yield `array.push(element);`;
@@ -903,7 +909,10 @@ async function* generateEncoder(typeUri, types) {
     if (options.format === "expand") {
       return await jsonld.expand(
         values,
-        { documentLoader: options.contextLoader },
+        {
+          documentLoader: options.contextLoader,
+          keepFreeFloatingNodes: true,
+        },
       );
     }
     const docContext = options.context ??
@@ -1026,7 +1035,17 @@ async function* generateDecoder(typeUri, types, moduleVarNames) {
     // deno-lint-ignore no-explicit-any
     let values: Record<string, any[]> & { "@id"?: string };
     let expanded: unknown[];
-    if (globalThis.Object.keys(json).length == 0) {
+    if (
+      "_fromSubclass" in options &&
+      options._fromSubclass &&
+      typeof json === "object" &&
+      !Array.isArray(json)
+    ) {
+      values =
+        // deno-lint-ignore no-explicit-any
+        json as (Record<string, any[]> & { "@id"?: string });
+      expanded = [values];
+    } else if (globalThis.Object.keys(json).length == 0) {
       values = {};
       expanded = [values];
     } else {
@@ -1083,8 +1102,9 @@ async function* generateDecoder(typeUri, types, moduleVarNames) {
     );
     `;
 	else yield `
-    delete values["@type"];
-    const instance = await super.fromJsonLd(values, {
+    const superValues = structuredClone(values);
+    delete superValues["@type"];
+    const instance = await super.fromJsonLd(superValues, {
       ...options,
       // @ts-ignore: an internal option
       _fromSubclass: true,
@@ -1093,6 +1113,9 @@ async function* generateDecoder(typeUri, types, moduleVarNames) {
       throw new TypeError("Unexpected type: " + instance.constructor.name);
     }
     `;
+	yield `
+    let shouldCacheJsonLd = instance._shouldCacheJsonLd;
+  `;
 	for (const property of type.properties) {
 		const variable = await getFieldName(property.uri, "");
 		yield await generateField(property, types, "const ");
@@ -1105,13 +1128,20 @@ async function* generateDecoder(typeUri, types, moduleVarNames) {
           ${arrayVariable} = values[${JSON.stringify(prop.uri)}];
         }
         `;
+		let itemsExpression = `${arrayVariable}.length === 1 && "@list" in ${arrayVariable}[0]
+        ? ${arrayVariable}[0]["@list"]
+        : ${arrayVariable}`;
+		if (isNonFunctionalProperty(property) && property.container === "graph") itemsExpression = `(${itemsExpression}).flatMap((item: unknown) =>
+          item != null && typeof item === "object" && "@graph" in item &&
+            Array.isArray((item as { "@graph": unknown })["@graph"])
+            ? (item as { "@graph": unknown[] })["@graph"]
+            : [item]
+        )`;
 		yield `
     for (
       const v of ${arrayVariable} == null
         ? []
-        : ${arrayVariable}.length === 1 && "@list" in ${arrayVariable}[0]
-        ? ${arrayVariable}[0]["@list"]
-        : ${arrayVariable}
+        : ${itemsExpression}
     ) {
       if (v == null) continue;
     `;
@@ -1125,29 +1155,40 @@ async function* generateDecoder(typeUri, types, moduleVarNames) {
         continue;
       }
       `;
-		if (property.range.length == 1) yield `
-      const decoded = ${getDecoder(property.range[0], types, "v", "options", propertyBaseUrl)};
-      if (typeof decoded === "undefined") continue;
-      ${variable}.push(decoded);`;
-		else {
-			yield `
+		yield `
       const decoded =
-      `;
+    `;
+		if (property.range.length == 1) yield getDecoder(property.range[0], types, "v", "options", propertyBaseUrl);
+		else {
 			const decoders = getDecoders(property.range, types, "v", "options", propertyBaseUrl);
 			for (const code of decoders) yield code;
-			yield `
+		}
+		yield `
       ;
-      if (typeof decoded === "undefined") continue;
+    `;
+		yield `
+      if (typeof decoded === "undefined") {
+        shouldCacheJsonLd = false;
+        continue;
+      }
+    `;
+		yield `
+      if (!this._shouldCacheDecodedJsonLd(decoded)) {
+        shouldCacheJsonLd = false;
+      }
       ${variable}.push(decoded);
-      `;
-		}
+    `;
 		yield `
     }
     instance.${await getFieldName(property.uri)} = ${variable};
     `;
 	}
 	yield `
-    if (!("_fromSubclass" in options) || !options._fromSubclass) {
+    instance._shouldCacheJsonLd = shouldCacheJsonLd;
+    if (
+      shouldCacheJsonLd &&
+      (!("_fromSubclass" in options) || !options._fromSubclass)
+    ) {
       try {
         if (cacheJsonLd != null && cacheJsonLd !== expanded) {
           const compactArray = Array.isArray(json) && json.length === 1;
@@ -2015,6 +2056,7 @@ async function* generateClass(typeUri, types, moduleVarNames) {
     };
     #cachedJsonLd?: unknown;
     readonly #_baseUrl?: URL;
+    #shouldCacheJsonLd = true;
     readonly id: URL | null;
 
     protected get _documentLoader(): DocumentLoader | undefined {
@@ -2048,6 +2090,20 @@ async function* generateClass(typeUri, types, moduleVarNames) {
     protected get _baseUrl(): URL | undefined {
       return this.#_baseUrl;
     }
+
+    protected get _shouldCacheJsonLd(): boolean {
+      return this.#shouldCacheJsonLd;
+    }
+
+    protected set _shouldCacheJsonLd(value: boolean) {
+      this.#shouldCacheJsonLd = value;
+    }
+
+    protected static _shouldCacheDecodedJsonLd(value: unknown): boolean {
+      if (value == null || typeof value !== "object") return true;
+      if (!("_shouldCacheJsonLd" in value)) return true;
+      return (value as { _shouldCacheJsonLd: boolean })._shouldCacheJsonLd;
+    }
     `;
 	yield `
     /**
@@ -2138,7 +2194,19 @@ async function* generateClasses(types) {
     isTemporalDuration,
     isTemporalInstant,
 } from "@fedify/vocab-runtime/temporal";\n`;
-	const portableIriKeys = new Set(["@id", "id"]);
+	yield `
+function isValidLanguageTag(language: string): boolean {
+  try {
+    new Intl.Locale(language);
+    return true;
+  } catch (error) {
+    if (error instanceof RangeError) return false;
+    throw error;
+  }
+}
+`;
+	yield "\n\n";
+	const portableIriKeys = /* @__PURE__ */ new Set(["@id", "id"]);
 	for (const type of Object.values(types)) for (const property of type.properties) addPortableIriKeys(portableIriKeys, property, types);
 	yield "const PORTABLE_IRI_PATTERN = /^ap(?:\\+ef61)?:\\/\\//i;\n";
 	yield `const PORTABLE_IRI_KEYS: ReadonlySet<string> = new Set(${JSON.stringify([...portableIriKeys].sort())});\n\n`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fedify/vocab-tools",
-  "version": "2.4.0-dev.1666+690d9b28",
+  "version": "2.4.0-dev.1727+1eadcb04",
   "description": "Code generator for Activity Vocabulary APIs",
   "homepage": "https://fedify.dev/",
   "repository": {