@fedify/vocab-tools 2.4.0 → 2.4.2-dev.2347

package/src/class.ts

@@ -58,6 +58,7 @@ const RUNTIME_IMPORTS = [
   "isDecimal",
   "isGatewayUrl",
   "LanguageString",
+  "normalizeLanguageTag",
   "parseDecimal",
   "parseGatewayUrl",
   "parseIri",
@@ -325,7 +326,7 @@ function inspectIri(iri: URL): string {
   yield `
 function isValidLanguageTag(language: string): boolean {
   try {
-    new Intl.Locale(language);
+    new Intl.Locale(normalizeLanguageTag(language));
     return true;
   } catch (error) {
     if (error instanceof RangeError) return false;

package/src/constructor.ts

@@ -179,7 +179,7 @@ export async function* generateConstructor(
           if (Array.isArray(values.${property.pluralName}) &&
               values.${property.pluralName}.every(v => ${typeGuards})) {
             // @ts-ignore: type is checked above.
-            this.${fieldName} = values.${property.pluralName};
+            this.${fieldName} = values.${property.pluralName}.slice();
       `;
       if (!allScalarTypes) {
         yield `
@@ -211,6 +211,19 @@ export async function* generateCloner(
   /**
    * Clones this instance, optionally updating it with the given values.
    *
+   * This is a shallow copy: property arrays are copied, but nested objects
+   * and URLs are shared with this instance.  Dereferencing accessors can cache
+   * fetched objects in the instance whose accessor is called.  Hydrating a
+   * shared nested object through the clone can affect the original as well,
+   * and can change JSON-LD output when either is embedded in another
+   * object.  Hydrating a top-level property of the clone does not update this
+   * instance's property.
+   *
+   * To resolve properties without sharing nested objects, serialize and
+   * re-parse the instance before hydration rather than using this method.
+   * See the [vocabulary manual](https://fedify.dev/manual/vocab#immutability)
+   * for details, including how cached JSON-LD affects serialization.
+   *
    * A clone never inherits a signed JSON-LD representation retained by
    * \`signObject()\`: the clone may differ from the document that the proof
    * covers, so embedding the original secured JSON in a parent document
@@ -219,7 +232,8 @@ export async function* generateCloner(
    *
    * @param values The values to update the clone with.
    * @param options The options to use for cloning.
-   * @returns The cloned instance.
+   * @returns The cloned instance with its own property arrays.  Nested objects
+   *          and URLs are shared with this instance.
    */
   ${emitOverride(typeUri, types)} clone(
     values:
@@ -258,7 +272,7 @@ export async function* generateCloner(
     const fieldName = await getFieldName(property.uri);
     const trustFieldName = await getFieldName(property.uri, "#_trust");
     const allScalarTypes = areAllScalarTypes(property.range, types);
-    yield `clone.${fieldName} = this.${fieldName};`;
+    yield `clone.${fieldName} = this.${fieldName}.slice();`;
     if (!allScalarTypes) {
       yield `clone.${trustFieldName} = new Set(this.${trustFieldName});`;
     }
@@ -322,7 +336,7 @@ export async function* generateCloner(
           if (Array.isArray(values.${property.pluralName}) &&
               values.${property.pluralName}.every(v => ${typeGuards})) {
             // @ts-ignore: type is checked above.
-            clone.${fieldName} = values.${property.pluralName};
+            clone.${fieldName} = values.${property.pluralName}.slice();
       `;
       if (!allScalarTypes) {
         yield `

package/src/type.ts

@@ -310,7 +310,7 @@ const scalarTypes: Record<string, ScalarType> = {
         && typeof ${v}["@value"] === "string" && !("@language" in ${v})`;
     },
     decoder(v) {
-      return `new Intl.Locale(${v}["@value"])`;
+      return `new Intl.Locale(normalizeLanguageTag(${v}["@value"]))`;
     },
   },
   "fedify:url": {