fiftyone.pipeline.did 4.5.35 → 4.5.36

package/didClient.js

@@ -776,7 +776,7 @@ function dateOf (fodId) {
 function payloadLengthValid (fodId) {
   const matchKeyLength = fodId.type === IdType.RANDOM
     ? FodId.GUID_LENGTH
-    : FodId.HASH_LENGTH;
+    : FodId.MATCH_KEY_LENGTH;
   return fodId.payload.length >= FodId.HEADER_LENGTH + matchKeyLength;
 }
 

package/examples/fodIdExample.js

@@ -50,7 +50,9 @@ function samplePayload () {
   p[FodId.LICENSE_ID_OFFSET + 1] = 0x56;
   p[FodId.LICENSE_ID_OFFSET + 2] = 0x34;
   p[FodId.LICENSE_ID_OFFSET + 3] = 0x12;
-  for (let i = 0; i < FodId.HASH_LENGTH; i++) { p[FodId.HASH_OFFSET + i] = 0x20 + i; }
+  for (let i = 0; i < FodId.MATCH_KEY_LENGTH; i++) {
+    p[FodId.MATCH_KEY_OFFSET + i] = 0x20 + i;
+  }
   return p;
 }
 

package/fodId.js

@@ -88,17 +88,35 @@ class FodId {
   static LICENSE_ID_OFFSET = 1;
   static LICENSE_ID_LENGTH = 4;
   /** Byte offset of the match key field within the payload. */
-  static HASH_OFFSET = 5;
+  static MATCH_KEY_OFFSET = 5;
   /**
    * Byte length of the match key field for Probabilistic and HashedEmail
    * identifiers, being a SHA-256.
    */
-  static HASH_LENGTH = 32;
-  static HEADER_LENGTH = 5;
+  static MATCH_KEY_LENGTH = 32;
+  /**
+   * Deprecated alias for {@link FodId.MATCH_KEY_OFFSET}. The stable,
+   * comparable part of a 51Did is now called the match key, mirroring the
+   * Model Terms for Marketing vocabulary. This alias will be removed in a
+   * future release.
+   * @deprecated Renamed to MATCH_KEY_OFFSET. This alias will be removed in
+   * a future release.
+   */
+  static HASH_OFFSET = FodId.MATCH_KEY_OFFSET;
+  /**
+   * Deprecated alias for {@link FodId.MATCH_KEY_LENGTH}. The stable,
+   * comparable part of a 51Did is now called the match key, mirroring the
+   * Model Terms for Marketing vocabulary. This alias will be removed in a
+   * future release.
+   * @deprecated Renamed to MATCH_KEY_LENGTH. This alias will be removed in
+   * a future release.
+   */
+  static HASH_LENGTH = FodId.MATCH_KEY_LENGTH;
+  static HEADER_LENGTH = FodId.MATCH_KEY_OFFSET;
   /** Byte length of the GUID match key carried by Random identifiers. */
   static GUID_LENGTH = 16;
   static RANDOM_PAYLOAD_LENGTH = 21;
-  static PAYLOAD_LENGTH = 37;
+  static PAYLOAD_LENGTH = FodId.MATCH_KEY_OFFSET + FodId.MATCH_KEY_LENGTH;
 
   /**
    * Why a read succeeded or failed, being the OWID library's statuses plus
@@ -471,7 +489,7 @@ function unpack (payload) {
     // is the match key.
     matchKeyLength = length - FodId.HEADER_LENGTH;
   } else {
-    matchKeyLength = FodId.HASH_LENGTH;
+    matchKeyLength = FodId.MATCH_KEY_LENGTH;
   }
   const required = FodId.HEADER_LENGTH + matchKeyLength;
   if (length < required) {
@@ -488,7 +506,7 @@ function unpack (payload) {
     licenseId,
     // slice() copies, so the stored match key is this identifier's own.
     matchKey: payload.slice(
-      FodId.HASH_OFFSET, FodId.HASH_OFFSET + matchKeyLength),
+      FodId.MATCH_KEY_OFFSET, FodId.MATCH_KEY_OFFSET + matchKeyLength),
     length,
     required
   };

package/idType.js

@@ -49,8 +49,8 @@ const IdType = Object.freeze({
 
   /**
    * The human-readable name of an IdType value.
-   * @param {number} type an IdType value
-   * @returns {string}
+   * @param {number} type an IdType value, being 0 to 3 as fromFlags returns
+   * @returns {string} the name of that type, for example "Probabilistic"
    */
   name (type) {
     return NAMES[type];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fiftyone.pipeline.did",
-  "version": "4.5.35",
+  "version": "4.5.36",
   "description": "Strongly typed reader for the 51Did (51Degrees Identifier) value returned by the 51Degrees Cloud service. Parses the OWID envelope and exposes the Flags, License Id and match key plus the identifier type. Compare match keys, never envelopes.",
   "keywords": [
     "51degrees",

package/tests/envelope.js

@@ -37,7 +37,7 @@ const CANONICAL_LICENSE_ID = 0x12345678;
 const OWID_EPOCH_MS = Date.UTC(2020, 0, 1);
 
 function canonicalMatchKey () {
-  const h = new Uint8Array(FodId.HASH_LENGTH);
+  const h = new Uint8Array(FodId.MATCH_KEY_LENGTH);
   for (let i = 0; i < h.length; i++) { h[i] = 0x20 + i; }
   return h;
 }
@@ -54,7 +54,7 @@ function canonicalPayload () {
   const p = new Uint8Array(FodId.PAYLOAD_LENGTH);
   p[FodId.FLAGS_OFFSET] = CANONICAL_FLAGS;
   writeLicenseId(p);
-  p.set(canonicalMatchKey(), FodId.HASH_OFFSET);
+  p.set(canonicalMatchKey(), FodId.MATCH_KEY_OFFSET);
   return p;
 }
 
@@ -63,7 +63,7 @@ function canonicalRandomPayload () {
   p[FodId.FLAGS_OFFSET] = (1 << 6) | 0b001; // Random tag + usage bits
   writeLicenseId(p);
   for (let i = 0; i < FodId.GUID_LENGTH; i++) {
-    p[FodId.HASH_OFFSET + i] = 0x40 + i;
+    p[FodId.MATCH_KEY_OFFSET + i] = 0x40 + i;
   }
   return p;
 }

package/tests/fodId.test.js

@@ -43,10 +43,11 @@ describe('FodId', () => {
   // ----- Current .NET coverage -----
 
   test('constants are internally consistent', () => {
-    expect(FodId.HASH_OFFSET + FodId.HASH_LENGTH).toBe(FodId.PAYLOAD_LENGTH);
+    expect(FodId.MATCH_KEY_OFFSET + FodId.MATCH_KEY_LENGTH)
+      .toBe(FodId.PAYLOAD_LENGTH);
     expect(FodId.LICENSE_ID_OFFSET + FodId.LICENSE_ID_LENGTH)
-      .toBe(FodId.HASH_OFFSET);
-    expect(FodId.HASH_OFFSET + FodId.GUID_LENGTH)
+      .toBe(FodId.MATCH_KEY_OFFSET);
+    expect(FodId.MATCH_KEY_OFFSET + FodId.GUID_LENGTH)
       .toBe(FodId.RANDOM_PAYLOAD_LENGTH);
   });
 
@@ -128,9 +129,9 @@ describe('FodId', () => {
     const fod = FodId.fromBase64(envelopeBase64(canonicalPayload()));
     const k = fod.matchKey;
     k[0] = 0x00;
-    k[FodId.HASH_LENGTH - 1] = 0x00;
+    k[FodId.MATCH_KEY_LENGTH - 1] = 0x00;
     expect(fod.matchKey).toEqual(canonicalMatchKey());
-    expect(fod.payload[FodId.HASH_OFFSET]).toBe(0x20);
+    expect(fod.payload[FodId.MATCH_KEY_OFFSET]).toBe(0x20);
   });
 
   test('the deprecated hash getter returns the match key', () => {
@@ -175,7 +176,7 @@ describe('FodId', () => {
     expect(fod.flags).toBe(CANONICAL_FLAGS);
     expect(fod.licenseId).toBe(CANONICAL_LICENSE_ID);
     expect(fod.matchKey).toEqual(canonicalMatchKey());
-    expect(fod.matchKey.length).toBe(FodId.HASH_LENGTH);
+    expect(fod.matchKey.length).toBe(FodId.MATCH_KEY_LENGTH);
   });
 
   test('a long context section and a long creator domain both parse', () => {
@@ -286,7 +287,7 @@ describe('FodId', () => {
   });
 
   test('Reserved header-only payload parses', () => {
-    const p = new Uint8Array(FodId.HASH_OFFSET);
+    const p = new Uint8Array(FodId.MATCH_KEY_OFFSET);
     p[FodId.FLAGS_OFFSET] = 0b1100_0000;
     const fod = FodId.fromBase64(envelopeBase64(p));
     expect(fod.type).toBe(IdType.RESERVED);
@@ -304,7 +305,7 @@ describe('FodId', () => {
     const fb = FodId.fromBase64(b);
 
     expect(fa.matchKey).toEqual(fb.matchKey); // match key is stable
-    expect(fa.date).not.toBe(fb.date);           // envelope differs
+    expect(fa.date).not.toBe(fb.date); // envelope differs
     expect(fa.signature).not.toEqual(fb.signature);
     expect(a).not.toBe(b);
   });
@@ -325,11 +326,11 @@ describe('FodId', () => {
     const o = owid.parse(envelopeBase64(canonicalPayload())).owid;
     const fod = FodId.fromOwid(o);
     expect(Object.isFrozen(o)).toBe(true);
-    o.payload[FodId.HASH_OFFSET] = 0x00; // writes into a copy
-    expect(o.payload[FodId.HASH_OFFSET]).toBe(0x20);
+    o.payload[FodId.MATCH_KEY_OFFSET] = 0x00; // writes into a copy
+    expect(o.payload[FodId.MATCH_KEY_OFFSET]).toBe(0x20);
     expect(fod.matchKey).toEqual(canonicalMatchKey());
     expect(fod.flags).toBe(CANONICAL_FLAGS);
-    expect(fod.payload[FodId.HASH_OFFSET]).toBe(0x20);
+    expect(fod.payload[FodId.MATCH_KEY_OFFSET]).toBe(0x20);
   });
 
   test('constructor is decoupled from the source owid', () => {
@@ -338,10 +339,10 @@ describe('FodId', () => {
     const o = owid.parse(envelopeBase64(canonicalPayload())).owid;
     const fod = new FodId(o);
     expect(fod._owid).not.toBe(o);
-    fod.payload[FodId.HASH_OFFSET] = 0x00; // writes into a copy
+    fod.payload[FodId.MATCH_KEY_OFFSET] = 0x00; // writes into a copy
     expect(fod.matchKey).toEqual(canonicalMatchKey());
     expect(fod.flags).toBe(CANONICAL_FLAGS);
-    expect(fod.payload[FodId.HASH_OFFSET]).toBe(0x20);
+    expect(fod.payload[FodId.MATCH_KEY_OFFSET]).toBe(0x20);
   });
 
   test('verify with the wrong key returns false', async () => {
@@ -367,9 +368,9 @@ describe('FodId', () => {
   function alphabetPayload () {
     const p = canonicalPayload();
     // 0xFB 0xFF 0xBF encodes to "+/+/" in standard base64.
-    p[FodId.HASH_OFFSET] = 0xFB;
-    p[FodId.HASH_OFFSET + 1] = 0xFF;
-    p[FodId.HASH_OFFSET + 2] = 0xBF;
+    p[FodId.MATCH_KEY_OFFSET] = 0xFB;
+    p[FodId.MATCH_KEY_OFFSET + 1] = 0xFF;
+    p[FodId.MATCH_KEY_OFFSET + 2] = 0xBF;
     return p;
   }
 

package/types/fodId.d.ts

@@ -39,11 +39,29 @@ declare class FodId {
     static LICENSE_ID_OFFSET: number;
     static LICENSE_ID_LENGTH: number;
     /** Byte offset of the match key field within the payload. */
-    static HASH_OFFSET: number;
+    static MATCH_KEY_OFFSET: number;
     /**
      * Byte length of the match key field for Probabilistic and HashedEmail
      * identifiers, being a SHA-256.
      */
+    static MATCH_KEY_LENGTH: number;
+    /**
+     * Deprecated alias for {@link FodId.MATCH_KEY_OFFSET}. The stable,
+     * comparable part of a 51Did is now called the match key, mirroring the
+     * Model Terms for Marketing vocabulary. This alias will be removed in a
+     * future release.
+     * @deprecated Renamed to MATCH_KEY_OFFSET. This alias will be removed in
+     * a future release.
+     */
+    static HASH_OFFSET: number;
+    /**
+     * Deprecated alias for {@link FodId.MATCH_KEY_LENGTH}. The stable,
+     * comparable part of a 51Did is now called the match key, mirroring the
+     * Model Terms for Marketing vocabulary. This alias will be removed in a
+     * future release.
+     * @deprecated Renamed to MATCH_KEY_LENGTH. This alias will be removed in
+     * a future release.
+     */
     static HASH_LENGTH: number;
     static HEADER_LENGTH: number;
     /** Byte length of the GUID match key carried by Random identifiers. */

package/types/idType.d.ts

@@ -22,8 +22,8 @@ declare const IdType: Readonly<{
     fromFlags(flags: number): number;
     /**
      * The human-readable name of an IdType value.
-     * @param {number} type an IdType value
-     * @returns {string}
+     * @param {number} type an IdType value, being 0 to 3 as fromFlags returns
+     * @returns {string} the name of that type, for example "Probabilistic"
      */
     name(type: number): string;
 }>;