tagged-urn 0.40.107 → 0.41.110

package/package.json

@@ -28,5 +28,5 @@
   "scripts": {
     "test": "node tagged-urn.test.js"
   },
-  "version": "0.40.107"
+  "version": "0.41.110"
 }

package/tagged-urn.js

@@ -110,6 +110,25 @@ const Form = {
   MUST_NOT_HAVE: 6,        // "!"
 };
 
+const TaggedUrnRelationKind = Object.freeze({
+  EQUIVALENT: 'equivalent',
+  COMPARABLE: 'comparable',
+  INCOMPARABLE: 'incomparable',
+});
+
+class TaggedUrnCoordinateDelta {
+  constructor(prefix, removed = {}, added = {}, relationKind = TaggedUrnRelationKind.EQUIVALENT) {
+    this.prefix = prefix.toLowerCase();
+    this.removed = { ...removed };
+    this.added = { ...added };
+    this.relationKind = relationKind;
+  }
+
+  isEmpty() {
+    return Object.keys(this.removed).length === 0 && Object.keys(this.added).length === 0;
+  }
+}
+
 // Classify a stored value. Returns { kind, raw } — raw is the inner
 // v for ?=v and !=v, the literal value for exact, and '' otherwise.
 function classifyForm(value) {
@@ -828,6 +847,94 @@ class TaggedUrn {
     return this.isComparable(other);
   }
 
+  /**
+   * Compute the coordinate-space delta from `base` to `this`.
+   *
+   * Delta is defined over explicit canonical coordinates, not semantic
+   * equivalence classes. Equivalent URNs may still yield a non-empty delta if
+   * one side explicitly authors no-op coordinates.
+   *
+   * @param {TaggedUrn} base
+   * @returns {TaggedUrnCoordinateDelta}
+   * @throws {TaggedUrnError} If prefixes do not match
+   */
+  deltaFrom(base) {
+    if (!base) {
+      throw new TaggedUrnError(ErrorCodes.INVALID_FORMAT, 'cannot derive delta from null URN');
+    }
+    if (this.prefix !== base.prefix) {
+      throw new TaggedUrnError(
+        ErrorCodes.PREFIX_MISMATCH,
+        `Cannot compare URNs with different prefixes: '${base.prefix}' vs '${this.prefix}'`
+      );
+    }
+
+    const relationKind = this.isEquivalent(base)
+      ? TaggedUrnRelationKind.EQUIVALENT
+      : (this.isComparable(base)
+        ? TaggedUrnRelationKind.COMPARABLE
+        : TaggedUrnRelationKind.INCOMPARABLE);
+
+    const removed = {};
+    const added = {};
+    const allKeys = new Set([
+      ...Object.keys(base.tags),
+      ...Object.keys(this.tags),
+    ]);
+
+    for (const key of allKeys) {
+      const baseValue = Object.prototype.hasOwnProperty.call(base.tags, key)
+        ? base.tags[key]
+        : undefined;
+      const targetValue = Object.prototype.hasOwnProperty.call(this.tags, key)
+        ? this.tags[key]
+        : undefined;
+      if (baseValue === targetValue) {
+        continue;
+      }
+      if (baseValue !== undefined) {
+        removed[key] = baseValue;
+      }
+      if (targetValue !== undefined) {
+        added[key] = targetValue;
+      }
+    }
+
+    return new TaggedUrnCoordinateDelta(this.prefix, removed, added, relationKind);
+  }
+
+  /**
+   * Apply a coordinate-space delta to this tagged URN.
+   *
+   * Keys named in `removed` are deleted regardless of their current value,
+   * then keys named in `added` are inserted. Unrelated coordinates are
+   * preserved.
+   *
+   * @param {TaggedUrnCoordinateDelta} delta
+   * @returns {TaggedUrn}
+   * @throws {TaggedUrnError} If prefixes do not match
+   */
+  applyDelta(delta) {
+    if (!delta) {
+      throw new TaggedUrnError(ErrorCodes.INVALID_FORMAT, 'cannot apply null delta');
+    }
+    if (this.prefix !== delta.prefix) {
+      throw new TaggedUrnError(
+        ErrorCodes.PREFIX_MISMATCH,
+        `Cannot apply delta with different prefix: '${delta.prefix}' vs '${this.prefix}'`
+      );
+    }
+
+    const nextTags = { ...this.tags };
+    for (const key of Object.keys(delta.removed)) {
+      delete nextTags[key];
+    }
+    for (const [key, value] of Object.entries(delta.added)) {
+      nextTags[key] = value;
+    }
+    return new TaggedUrn(this.prefix, nextTags, true);
+  }
+
   /**
    * Create a new URN with a specific tag set to wildcard
    *
@@ -1075,6 +1182,8 @@ class UrnMatcher {
 // Export for CommonJS
 module.exports = {
   TaggedUrn,
+  TaggedUrnCoordinateDelta,
+  TaggedUrnRelationKind,
   TaggedUrnBuilder,
   UrnMatcher,
   TaggedUrnError,

package/tagged-urn.test.js

@@ -4,6 +4,7 @@
 
 const {
   TaggedUrn,
+  TaggedUrnRelationKind,
   TaggedUrnBuilder,
   UrnMatcher,
   TaggedUrnError,
@@ -1495,4 +1496,35 @@ module.exports = { runTests };
   );
 })();
 
+// TEST596: Empty delta preserves a more specific concrete instance.
+(() => {
+  const base = TaggedUrn.fromString('media:');
+  const target = TaggedUrn.fromString('media:');
+  const runtime = TaggedUrn.fromString('media:image;png');
+  const delta = target.deltaFrom(base);
+  assertEqual(delta.relationKind, TaggedUrnRelationKind.EQUIVALENT, 'TEST596: empty delta should be equivalent');
+  assert(delta.isEmpty(), 'TEST596: empty delta should have no edits');
+  assertEqual(runtime.applyDelta(delta).toString(), 'media:image;png', 'TEST596: empty delta should preserve runtime refinement');
+})();
+
+// TEST597: Incomparable replacement rewrites only declared coordinates.
+(() => {
+  const base = TaggedUrn.fromString('media:markdown;textable');
+  const target = TaggedUrn.fromString('media:html;textable');
+  const runtime = TaggedUrn.fromString('media:lang=en;markdown;textable');
+  const delta = target.deltaFrom(base);
+  assertEqual(delta.relationKind, TaggedUrnRelationKind.INCOMPARABLE, 'TEST597: markdown -> html should be incomparable');
+  assertEqual(runtime.applyDelta(delta).toString(), 'media:html;lang=en;textable', 'TEST597: unrelated runtime refinements must be preserved');
+})();
+
+// TEST598: Comparable removal drops only the declared key.
+(() => {
+  const base = TaggedUrn.fromString('media:image;png');
+  const target = TaggedUrn.fromString('media:image');
+  const runtime = TaggedUrn.fromString('media:author=me;image;png');
+  const delta = target.deltaFrom(base);
+  assertEqual(delta.relationKind, TaggedUrnRelationKind.COMPARABLE, 'TEST598: image;png -> image should be comparable');
+  assertEqual(runtime.applyDelta(delta).toString(), 'media:author=me;image', 'TEST598: only the declared key should be removed');
+})();
+
 console.log('All tests passed!');