@fedify/vocab-tools 2.4.5 → 2.4.6-dev.2837

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/src/class.ts CHANGED
@@ -136,6 +136,12 @@ async function* generateClass(
136
136
  return this.#tracerProvider;
137
137
  }
138
138
 
139
+ /**
140
+ * Internal cross-package contract with @fedify/fedify and @fedify/testing,
141
+ * which read this through \`Reflect.get()\` to pass an object's default
142
+ * verifier on to its clones. Keep this accessor name and its semantics
143
+ * stable.
144
+ */
139
145
  protected get _verifyPortableObject(): PortableObjectVerifier | undefined {
140
146
  return this.#verifyPortableObject;
141
147
  }
@@ -230,8 +230,33 @@ export async function* generateCloner(
230
230
  * would be wrong. Sign the clone again if it has to be embedded as a
231
231
  * secured child.
232
232
  *
233
+ * The clone does not inherit this instance's default FEP-ef61 portable
234
+ * object verifier, i.e., the \`verifyPortableObject\` option given when this
235
+ * instance was constructed, parsed, or fetched by an accessor, nor its
236
+ * \`documentLoader\` or \`contextLoader\`. Without a verifier, the clone's
237
+ * accessors no longer verify embedded portable objects, and refuse to
238
+ * dereference portable references. To keep verifying them, pass
239
+ * \`verifyPortableObject\` in \`options\`, or serialize this instance and
240
+ * re-parse it with \`fromJsonLd()\` and the verifier. A verifier is only
241
+ * a policy for dereferencing; passing one does not verify the clone itself.
242
+ *
243
+ * Cloning an instance that has a default verifier without passing
244
+ * the \`verifyPortableObject\` option logs a warning in the
245
+ * \`["fedify", "vocab", "portable"]\` category. Pass
246
+ * \`verifyPortableObject: undefined\` to drop the verifier deliberately
247
+ * without the warning. Either way, nested objects shared with this
248
+ * instance keep their own defaults.
249
+ *
233
250
  * @param values The values to update the clone with.
234
251
  * @param options The options to use for cloning.
252
+ *
253
+ * - \`documentLoader\`: The document loader for the clone.
254
+ * - \`contextLoader\`: The JSON-LD context loader for
255
+ * the clone.
256
+ * - \`verifyPortableObject\`: The default FEP-ef61 portable
257
+ * object verifier for the clone. It is not inherited from
258
+ * this instance. Pass \`undefined\` explicitly to clone
259
+ * without a verifier and without a warning.
235
260
  * @returns The cloned instance with its own property arrays. Nested objects
236
261
  * and URLs are shared with this instance.
237
262
  */
@@ -244,7 +269,7 @@ export async function* generateCloner(
244
269
  options: {
245
270
  documentLoader?: DocumentLoader,
246
271
  contextLoader?: DocumentLoader,
247
- verifyPortableObject?: PortableObjectVerifier,
272
+ verifyPortableObject?: PortableObjectVerifier | undefined,
248
273
  } = {}
249
274
  ): ${type.name} {
250
275
  if (this._warning != null) {
@@ -252,8 +277,15 @@ export async function* generateCloner(
252
277
  this._warning.message,
253
278
  this._warning.values
254
279
  );
255
- // @ts-ignore: $warning is not recognized as a property, but it is.
256
- options = { ...options, $warning: this._warning };
280
+ // Keep an explicit verifyPortableObject option, even an inherited or
281
+ // non-enumerable one, since its presence decides whether to warn below:
282
+ options = {
283
+ ...options,
284
+ ...("verifyPortableObject" in options
285
+ ? { verifyPortableObject: options.verifyPortableObject }
286
+ : {}),
287
+ $warning: this._warning,
288
+ } as typeof options;
257
289
  }
258
290
  `;
259
291
  if (type.extends == null) {
@@ -357,6 +389,23 @@ export async function* generateCloner(
357
389
  `;
358
390
  }
359
391
  }
392
+ if (type.extends == null) {
393
+ yield `
394
+ if (
395
+ this._verifyPortableObject != null &&
396
+ !("verifyPortableObject" in options)
397
+ ) {
398
+ getLogger(["fedify", "vocab", "portable"]).warn(
399
+ "Cloning {typeName} {objectId} drops its default portable object " +
400
+ "verifier, since clone() does not inherit it. Pass " +
401
+ "the verifyPortableObject option to clone() to keep verifying " +
402
+ "portable objects, or verifyPortableObject: undefined to drop " +
403
+ "the verifier deliberately without this warning.",
404
+ { typeName: this.constructor.name, objectId: this.id?.href ?? "(no id)" },
405
+ );
406
+ }
407
+ `;
408
+ }
360
409
  yield `
361
410
  return clone;
362
411
  }