@fedify/vocab-tools 2.2.0-dev.731 → 2.2.0-dev.766

package/src/class.test.ts

@@ -81,6 +81,47 @@ test("generateClasses() imports Decimal helpers for xsd:decimal", async () => {
   match(entireCode, /parseDecimal\(v\["@value"\]\)/);
 });
 
+test("generateClasses() emits $EntityType helpers for fedify:vocabEntityType", async () => {
+  const entireCode = await getEntityTypeFixtureCode();
+  match(
+    entireCode,
+    /export type \$EntityType =\s+\| typeof Entity\s+\| typeof ChildEntity\s+\| typeof Tombstone;/s,
+  );
+  match(
+    entireCode,
+    /const entityTypes: readonly \$EntityType\[\] = \[\s*Entity,\s*ChildEntity,\s*Tombstone,\s*\];/s,
+  );
+  match(
+    entireCode,
+    /const entityTypeSet: ReadonlySet<\$EntityType> = new Set\(entityTypes\);/,
+  );
+  match(
+    entireCode,
+    /export function isEntityType\(value: unknown\): value is \$EntityType/,
+  );
+  match(
+    entireCode,
+    /export function getEntityTypeById\(id: string \| URL\): \$EntityType \| undefined/,
+  );
+  match(
+    entireCode,
+    /const entityTypeIds: ReadonlyMap<string, \$EntityType> = new Map<string, \$EntityType>\(\s*\[\s*\["https:\/\/example.com\/entity", Entity\],\s*\["https:\/\/example.com\/child-entity", ChildEntity\],\s*\["https:\/\/example.com\/tombstone", Tombstone\],\s*\],\s*\);/s,
+  );
+  match(
+    entireCode,
+    /return entityTypeIds\.get\(typeof id === "string" \? id : id\?\.href\);/,
+  );
+});
+
+test("generateClasses() uses entity type helpers for fedify:vocabEntityType", async () => {
+  const entireCode = await getEntityTypeFixtureCode();
+  match(entireCode, /formerType\?: \$EntityType \| null;/);
+  match(entireCode, /formerTypes\?: \(\$EntityType\)\[\];/);
+  match(entireCode, /isEntityType\(values\.formerType\)/);
+  match(entireCode, /v\.typeId\.href/);
+  match(entireCode, /getEntityTypeById\(v\["@id"\]\)/);
+});
+
 test("getDataCheck() uses canParseDecimal() for xsd:decimal", () => {
   const check = getDataCheck(
     "http://www.w3.org/2001/XMLSchema#decimal",
@@ -177,6 +218,64 @@ async function getDecimalFixtureCode() {
   return (await Array.fromAsync(generateClasses(types))).join("");
 }
 
+async function getEntityTypeFixtureCode() {
+  const types: Record<string, TypeSchema> = {
+    "https://example.com/entity": {
+      name: "Entity",
+      uri: "https://example.com/entity",
+      compactName: "Entity",
+      entity: true,
+      description: "An entity.",
+      properties: [],
+      defaultContext:
+        "https://example.com/context" as TypeSchema["defaultContext"],
+    },
+    "https://example.com/child-entity": {
+      name: "ChildEntity",
+      uri: "https://example.com/child-entity",
+      compactName: "ChildEntity",
+      extends: "https://example.com/entity",
+      entity: true,
+      description: "A child entity.",
+      properties: [],
+      defaultContext:
+        "https://example.com/context" as TypeSchema["defaultContext"],
+    },
+    "https://example.com/value": {
+      name: "Value",
+      uri: "https://example.com/value",
+      compactName: "Value",
+      entity: false,
+      description: "A value type.",
+      properties: [],
+      defaultContext:
+        "https://example.com/context" as TypeSchema["defaultContext"],
+    },
+    "https://example.com/tombstone": {
+      name: "Tombstone",
+      uri: "https://example.com/tombstone",
+      compactName: "Tombstone",
+      extends: "https://example.com/entity",
+      entity: true,
+      description: "A tombstone.",
+      properties: [
+        {
+          singularName: "formerType",
+          pluralName: "formerTypes",
+          singularAccessor: true,
+          compactName: "formerType",
+          uri: "https://example.com/formerType",
+          description: "The former type.",
+          range: ["fedify:vocabEntityType"],
+        },
+      ],
+      defaultContext:
+        "https://example.com/context" as TypeSchema["defaultContext"],
+    },
+  };
+  return (await Array.fromAsync(generateClasses(types))).join("");
+}
+
 async function changeNodeSnapshotPath() {
   const { snapshot } = await import("node:test");
   snapshot.setResolveSnapshotPath(

package/src/class.ts

@@ -109,6 +109,56 @@ async function* generateClass(
   }
 }
 
+function* generateEntityTypeHelpers(
+  sortedTypeUris: string[],
+  types: Record<string, TypeSchema>,
+): Iterable<string> {
+  const entityTypes = sortedTypeUris.filter((typeUri) => types[typeUri].entity)
+    .map((typeUri) => ({ name: types[typeUri].name, uri: typeUri }));
+  const entityTypeNames = entityTypes.map((entityType) => entityType.name);
+  const entityTypeUnion = entityTypeNames.length < 1
+    ? " never"
+    : `\n  | typeof ${entityTypeNames.join("\n  | typeof ")}`;
+  yield `/**
+ * Constructor types for all generated vocabulary entity classes.
+ */
+export type $EntityType =${entityTypeUnion};
+
+const entityTypes: readonly $EntityType[] = [
+`;
+  for (const entityTypeName of entityTypeNames) {
+    yield `  ${entityTypeName},\n`;
+  }
+  yield `];
+
+const entityTypeSet: ReadonlySet<$EntityType> = new Set(entityTypes);
+
+const entityTypeIds: ReadonlyMap<string, $EntityType> = new Map<string, $EntityType>(
+  [
+`;
+  for (const entityType of entityTypes) {
+    yield `    [${JSON.stringify(entityType.uri)}, ${entityType.name}],\n`;
+  }
+  yield `  ],
+);
+
+/**
+ * Checks whether the given value is a generated vocabulary entity class.
+ */
+export function isEntityType(value: unknown): value is $EntityType {
+  return entityTypeSet.has(value as $EntityType);
+}
+
+/**
+ * Gets the generated vocabulary entity class for the given type URI.
+ */
+export function getEntityTypeById(id: string | URL): $EntityType | undefined {
+  return entityTypeIds.get(typeof id === "string" ? id : id?.href);
+}
+
+`;
+}
+
 /**
  * Generates the TypeScript classes from the given types.
  * @param types The types to generate classes from.
@@ -147,4 +197,5 @@ export async function* generateClasses(
   for (const typeUri of sorted) {
     for await (const code of generateClass(typeUri, types)) yield code;
   }
+  for (const code of generateEntityTypeHelpers(sorted, types)) yield code;
 }

package/src/codec.ts

@@ -440,7 +440,8 @@ export async function* generateDecoder(
       `;
     }
     if (property.range.length == 1) {
-      yield `${variable}.push(${
+      yield `
+      const decoded = ${
         getDecoder(
           property.range[0],
           types,
@@ -448,7 +449,9 @@ export async function* generateDecoder(
           "options",
           `(values["@id"] == null ? options.baseUrl : new URL(values["@id"]))`,
         )
-      })`;
+      };
+      if (typeof decoded === "undefined") continue;
+      ${variable}.push(decoded);`;
     } else {
       yield `
       const decoded =

package/src/schema.test.ts

@@ -1,10 +1,12 @@
-import { deepStrictEqual, ok } from "node:assert";
+import { deepStrictEqual, ok, throws } from "node:assert";
 import { test } from "node:test";
 import {
   hasSingularAccessor,
   isNonFunctionalProperty,
   type PropertySchema,
+  type TypeSchema,
   type TypeUri,
+  validateTypeSchemas,
 } from "./schema.ts";
 
 test(
@@ -201,3 +203,44 @@ test("Type guard combinations: untyped property", () => {
   ok(isNonFunctionalProperty(property));
   ok(!hasSingularAccessor(property));
 });
+
+test("validateTypeSchemas() rejects mixed fedify:vocabEntityType ranges", () => {
+  const types: Record<string, TypeSchema> = {
+    "https://example.com/tombstone": {
+      name: "Tombstone",
+      uri: "https://example.com/tombstone" as TypeUri,
+      compactName: "Tombstone",
+      entity: true,
+      description: "A tombstone.",
+      properties: [
+        {
+          singularName: "formerType",
+          pluralName: "formerTypes",
+          uri: "https://example.com/formerType",
+          compactName: "formerType",
+          description: "The former type.",
+          range: [
+            "fedify:vocabEntityType",
+            "http://www.w3.org/2001/XMLSchema#anyURI",
+          ] as [TypeUri, TypeUri],
+        },
+      ],
+      defaultContext:
+        "https://example.com/context" as TypeSchema["defaultContext"],
+    },
+  };
+
+  throws(
+    () => validateTypeSchemas(types),
+    (error) => {
+      ok(error instanceof TypeError);
+      deepStrictEqual(
+        error.message,
+        "The property Tombstone.formerType cannot mix fedify:vocabEntityType " +
+          "with other range types because the generated decoder cannot " +
+          "disambiguate entity type references from ordinary IRIs.",
+      );
+      return true;
+    },
+  );
+});

package/src/schema.ts

@@ -242,6 +242,7 @@ export function hasSingularAccessor(property: PropertySchema): boolean {
 
 const XSD_STRING_URI = "http://www.w3.org/2001/XMLSchema#string";
 const XSD_DECIMAL_URI = "http://www.w3.org/2001/XMLSchema#decimal";
+const FEDIFY_VOCAB_ENTITY_TYPE_URI = "fedify:vocabEntityType";
 
 /**
  * Validates schema combinations that cannot be represented safely by the
@@ -268,6 +269,17 @@ export function validateTypeSchemas(
             `generated encoder cannot disambiguate them at runtime.`,
         );
       }
+      if (
+        property.range.includes(FEDIFY_VOCAB_ENTITY_TYPE_URI) &&
+        property.range.length > 1
+      ) {
+        throw new TypeError(
+          `The property ${type.name}.${property.singularName} cannot mix ` +
+            `fedify:vocabEntityType with other range types because the ` +
+            `generated decoder cannot disambiguate entity type references ` +
+            `from ordinary IRIs.`,
+        );
+      }
     }
   }
 }

package/src/type.ts

@@ -163,7 +163,7 @@ const scalarTypes: Record<string, ScalarType> = {
       return `${v}.href`;
     },
     dataCheck(v) {
-      return `typeof ${v} === "object" && "@id" in ${v}
+      return `${v} != null && typeof ${v} === "object" && "@id" in ${v}
         && typeof ${v}["@id"] === "string"
         && ${v}["@id"] !== ""`;
     },
@@ -403,7 +403,7 @@ const scalarTypes: Record<string, ScalarType> = {
       return v;
     },
     dataCheck(v) {
-      return `typeof ${v} === "object" && "@id" in ${v}
+      return `${v} != null && typeof ${v} === "object" && "@id" in ${v}
         && typeof ${v}["@id"] === "string"
         && ${v}["@id"].startsWith("https://w3id.org/security#")
         && [
@@ -437,6 +437,36 @@ const scalarTypes: Record<string, ScalarType> = {
       return `${v}["@value"]`;
     },
   },
+  "fedify:vocabEntityType": {
+    name: "$EntityType",
+    typeGuard(v) {
+      return `isEntityType(${v})`;
+    },
+    encoder(v) {
+      return `{ "@id": ${v}.typeId.href }`;
+    },
+    dataCheck(v) {
+      return `${v} != null && typeof ${v} === "object" && "@id" in ${v}
+        && typeof ${v}["@id"] === "string"
+        && ${v}["@id"] !== ""`;
+    },
+    decoder(v) {
+      return `(() => {
+        if (${v} == null || typeof ${v} !== "object" || !("@id" in ${v}) ||
+            typeof ${v}["@id"] !== "string" || ${v}["@id"] === "") {
+          return undefined;
+        }
+        const entityType = getEntityTypeById(${v}["@id"]);
+        if (entityType == null) {
+          getLogger(["fedify", "vocab"]).warn(
+            "Ignoring unknown vocabulary entity type reference: {typeId}",
+            { typeId: ${v}["@id"] },
+          );
+        }
+        return entityType;
+      })()`;
+    },
+  },
 };
 
 export function getTypeName(