launchdarkly-js-sdk-common 5.6.0-beta.1 → 5.7.0-beta.1

package/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "5.5.1"
+  ".": "5.6.0"
 }

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 All notable changes to the `launchdarkly-js-sdk-common` package will be documented in this file. Changes that affect the dependent SDKs such as `launchdarkly-js-client-sdk` should also be logged in those projects, in the next release that uses the updated version of this package. This project adheres to [Semantic Versioning](http://semver.org).
 
+## [5.6.0](https://github.com/launchdarkly/js-sdk-common/compare/5.5.1...5.6.0) (2025-04-29)
+
+
+### Features
+
+* Add support for plugins. ([#124](https://github.com/launchdarkly/js-sdk-common/issues/124)) ([e0544c1](https://github.com/launchdarkly/js-sdk-common/commit/e0544c13d94b1088aebc4f6852743e408f5f77af))
+* Add support for the afterTrack stage for hooks. ([#123](https://github.com/launchdarkly/js-sdk-common/issues/123)) ([f7bebeb](https://github.com/launchdarkly/js-sdk-common/commit/f7bebebc15fc0ac718ebe167291215992b8ee6f5))
+
 ## [5.5.1](https://github.com/launchdarkly/js-sdk-common/compare/5.5.0...5.5.1) (2025-04-25)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "launchdarkly-js-sdk-common",
-  "version": "5.6.0-beta.1",
+  "version": "5.7.0-beta.1",
   "description": "LaunchDarkly SDK for JavaScript - common code",
   "author": "LaunchDarkly <team@launchdarkly.com>",
   "license": "Apache-2.0",

package/src/EventProcessor.js

@@ -1,5 +1,5 @@
 const EventSender = require('./EventSender');
-const EventSummarizer = require('./EventSummarizer');
+const MultiEventSummarizer = require('./MultiEventSummarizer');
 const ContextFilter = require('./ContextFilter');
 const errors = require('./errors');
 const messages = require('./messages');
@@ -17,8 +17,8 @@ function EventProcessor(
   const processor = {};
   const eventSender = sender || EventSender(platform, environmentId, options);
   const mainEventsUrl = utils.appendUrlPath(options.eventsUrl, '/events/bulk/' + environmentId);
-  const summarizer = EventSummarizer();
   const contextFilter = ContextFilter(options);
+  const summarizer = MultiEventSummarizer(contextFilter, () => platform.hasherFactory('sha256'));
   const samplingInterval = options.samplingInterval;
   const eventCapacity = options.eventCapacity;
   const flushInterval = options.flushInterval;
@@ -117,17 +117,24 @@ function EventProcessor(
     }
   };
 
-  processor.flush = function() {
+  processor.flush = async function() {
     if (disabled) {
       return Promise.resolve();
     }
     const eventsToSend = queue;
-    const summary = summarizer.getSummary();
-    summarizer.clearSummary();
-    if (summary) {
-      summary.kind = 'summary';
-      eventsToSend.push(summary);
-    }
+    const summaries = await summarizer.getSummaries();
+
+    summaries.forEach(summary => {
+      if (Object.keys(summary.features).length) {
+        eventsToSend.push(summary);
+      }
+    });
+    // const summary = summarizer.getSummary();
+    // summarizer.clearSummary();
+    // if (summary) {
+    //   summary.kind = 'summary';
+    //   eventsToSend.push(summary);
+    // }
     if (diagnosticsAccumulator) {
       // For diagnostic events, we record how many events were in the queue at the last flush (since "how
       // many events happened to be in the queue at the moment we decided to send a diagnostic event" would

package/src/EventSummarizer.js

@@ -89,6 +89,7 @@ function EventSummarizer() {
           startDate,
           endDate,
           features: flagsOut,
+          kind: 'summary',
         };
   };
 

package/src/MultiEventSummarizer.js

@@ -0,0 +1,76 @@
+import { hashContext } from './context';
+import EventSummarizer from './EventSummarizer';
+/**
+ *
+ * @param {{filter: (context: any) => any}} contextFilter
+ * @param {() => {update: (value: string) => void, digest: (format: string) => Promise<string>}} hasherFactory
+ */
+function MultiEventSummarizer(contextFilter, hasherFactory) {
+  let summarizers = {};
+  let contexts = {};
+  const pendingPromises = [];
+
+  /**
+   * Summarize the given event.
+   * @param {{
+   *   kind: string,
+   *   context?: any,
+   * }} event
+   */
+  function summarizeEvent(event) {
+    // This will execute asynchronously, which means that a flush could happen before the event
+    // is summarized. When that happens, then the event will just be in the next batch of summaries.
+    const promise = (async () => {
+      if (event.kind === 'feature') {
+        const hash = await hashContext(event.context, hasherFactory());
+        if (!hash) {
+          return;
+        }
+
+        let summarizer = summarizers[hash];
+        if (!summarizer) {
+          summarizers[hash] = EventSummarizer();
+          summarizer = summarizers[hash];
+          contexts[hash] = event.context;
+        }
+
+        summarizer.summarizeEvent(event);
+      }
+    })();
+    pendingPromises.push(promise);
+    promise.finally(() => {
+      const index = pendingPromises.indexOf(promise);
+      if (index !== -1) {
+        pendingPromises.splice(index, 1);
+      }
+    });
+  }
+
+  /**
+   * Get the summaries of the events that have been summarized.
+   * @returns {any[]}
+   */
+  async function getSummaries() {
+    // Wait for any pending summarizations to complete
+    // Additional tasks queued while waiting will not be waited for.
+    await Promise.all([...pendingPromises]);
+
+    const summarizersToFlush = summarizers;
+    const contextsForSummaries = contexts;
+
+    summarizers = {};
+    contexts = {};
+    return Object.entries(summarizersToFlush).map(([hash, summarizer]) => {
+      const summary = summarizer.getSummary();
+      summary.context = contextFilter.filter(contextsForSummaries[hash]);
+      return summary;
+    });
+  }
+
+  return {
+    summarizeEvent,
+    getSummaries,
+  };
+}
+
+module.exports = MultiEventSummarizer;

package/src/__tests__/LDClient-test.js

@@ -672,7 +672,9 @@ describe('LDClient', () => {
           await client.waitForInitialization(5);
         });
 
-        expect(eventsServer.requests.length()).toEqual(1);
+        // Flushing is an async operation, so we cannot ensure that the requests are made by
+        // the time we reach this point. If we await the nextRequest(), then it will catch
+        // whatever was flushed.
         const req = await eventsServer.nextRequest();
         const data = JSON.parse(req.body);
         expect(data.length).toEqual(1);

package/src/__tests__/MultiEventSummarizer-test.js

@@ -0,0 +1,158 @@
+const MultiEventSummarizer = require('../MultiEventSummarizer');
+const ContextFilter = require('../ContextFilter');
+
+function mockHasher() {
+  let state = '';
+  return {
+    update: input => {
+      state += input;
+    },
+    digest: () => state,
+  };
+}
+
+function makeEvent(key, version, variation, value, defaultVal, context) {
+  return {
+    kind: 'feature',
+    creationDate: 1000,
+    key: key,
+    version: version,
+    context: context,
+    variation: variation,
+    value: value,
+    default: defaultVal,
+  };
+}
+
+describe('with mocked crypto and hasher', () => {
+  let summarizer;
+  let contextFilter;
+
+  beforeEach(() => {
+    contextFilter = ContextFilter(false, []);
+    summarizer = MultiEventSummarizer(contextFilter, mockHasher);
+  });
+
+  it('creates new summarizer for new context hash', async () => {
+    const context = { kind: 'user', key: 'user1' };
+    const event = { kind: 'feature', context };
+
+    summarizer.summarizeEvent(event);
+
+    const summaries = await summarizer.getSummaries();
+    expect(summaries).toHaveLength(1);
+  });
+
+  it('uses existing summarizer for same context hash', async () => {
+    const context = { kind: 'user', key: 'user1' };
+    const event1 = { kind: 'feature', context, value: 'value1' };
+    const event2 = { kind: 'feature', context, value: 'value2' };
+
+    summarizer.summarizeEvent(event1);
+    summarizer.summarizeEvent(event2);
+
+    const summaries = await summarizer.getSummaries();
+    expect(summaries).toHaveLength(1);
+  });
+
+  it('ignores non-feature events', async () => {
+    const context = { kind: 'user', key: 'user1' };
+    const event = { kind: 'identify', context };
+
+    summarizer.summarizeEvent(event);
+
+    const summaries = await summarizer.getSummaries();
+    expect(summaries).toHaveLength(0);
+  });
+
+  it('handles multiple different contexts', async () => {
+    const context1 = { kind: 'user', key: 'user1' };
+    const context2 = { kind: 'user', key: 'user2' };
+    const event1 = { kind: 'feature', context: context1 };
+    const event2 = { kind: 'feature', context: context2 };
+
+    summarizer.summarizeEvent(event1);
+    summarizer.summarizeEvent(event2);
+
+    const summaries = await summarizer.getSummaries();
+    expect(summaries).toHaveLength(2);
+  });
+
+  it('automatically clears summaries when summarized', async () => {
+    const context = { kind: 'user', key: 'user1' };
+    const event = { kind: 'feature', context };
+
+    summarizer.summarizeEvent(event);
+
+    const summariesA = await summarizer.getSummaries();
+    const summariesB = await summarizer.getSummaries();
+    expect(summariesA).toHaveLength(1);
+    expect(summariesB).toHaveLength(0);
+  });
+
+  it('increments counters for feature events across multiple contexts', async () => {
+    const context1 = { kind: 'user', key: 'user1' };
+    const context2 = { kind: 'user', key: 'user2' };
+
+    // Events for context1 (using values 100-199)
+    const event1 = makeEvent('key1', 11, 1, 100, 111, context1);
+    const event2 = makeEvent('key1', 11, 2, 150, 111, context1);
+    const event3 = makeEvent('key2', 22, 1, 199, 222, context1);
+
+    // Events for context2 (using values 200-299)
+    const event4 = makeEvent('key1', 11, 1, 200, 211, context2);
+    const event5 = makeEvent('key1', 11, 2, 250, 211, context2);
+    const event6 = makeEvent('key2', 22, 1, 299, 222, context2);
+
+    summarizer.summarizeEvent(event1);
+    summarizer.summarizeEvent(event2);
+    summarizer.summarizeEvent(event3);
+    summarizer.summarizeEvent(event4);
+    summarizer.summarizeEvent(event5);
+    summarizer.summarizeEvent(event6);
+
+    const summaries = await summarizer.getSummaries();
+    expect(summaries).toHaveLength(2);
+
+    // Sort summaries by context key to make assertions consistent
+    summaries.sort((a, b) => a.context.key.localeCompare(b.context.key));
+
+    // Verify first context's summary (user1, values 100-199)
+    const summary1 = summaries[0];
+    summary1.features.key1.counters.sort((a, b) => a.value - b.value);
+    expect(summary1.features).toEqual({
+      key1: {
+        contextKinds: ['user'],
+        default: 111,
+        counters: [
+          { value: 100, variation: 1, version: 11, count: 1 },
+          { value: 150, variation: 2, version: 11, count: 1 },
+        ],
+      },
+      key2: {
+        contextKinds: ['user'],
+        default: 222,
+        counters: [{ value: 199, variation: 1, version: 22, count: 1 }],
+      },
+    });
+
+    // Verify second context's summary (user2, values 200-299)
+    const summary2 = summaries[1];
+    summary2.features.key1.counters.sort((a, b) => a.value - b.value);
+    expect(summary2.features).toEqual({
+      key1: {
+        contextKinds: ['user'],
+        default: 211,
+        counters: [
+          { value: 200, variation: 1, version: 11, count: 1 },
+          { value: 250, variation: 2, version: 11, count: 1 },
+        ],
+      },
+      key2: {
+        contextKinds: ['user'],
+        default: 222,
+        counters: [{ value: 299, variation: 1, version: 22, count: 1 }],
+      },
+    });
+  });
+});

package/src/__tests__/canonicalize-test.js

@@ -0,0 +1,86 @@
+const fs = require('fs');
+const path = require('path');
+
+const canonicalize = require('../canonicalize');
+
+// Get the test file pairs
+const testInputDir = path.join(__dirname, 'testdata', 'input');
+const testOutputDir = path.join(__dirname, 'testdata', 'output');
+const testFiles = fs.readdirSync(testInputDir);
+
+it.each(testFiles)('should correctly canonicalize %s', filename => {
+  // Load the input and expected output files
+  const inputPath = path.join(testInputDir, filename);
+  const outputPath = path.join(testOutputDir, filename);
+
+  const inputData = JSON.parse(fs.readFileSync(inputPath, 'utf8'));
+  const expectedOutput = fs.readFileSync(outputPath, 'utf8');
+
+  // Apply the canonicalize function
+  const result = canonicalize(inputData);
+
+  // Compare results
+  expect(result).toEqual(expectedOutput);
+});
+
+it('handles basic arrays', () => {
+  const input = [];
+  const expected = '[]';
+  const result = canonicalize(input);
+  expect(result).toEqual(expected);
+});
+
+it('handles arrays of null/undefined', () => {
+  const input = [null, undefined];
+  const expected = '[null,null]';
+  const result = canonicalize(input);
+  expect(result).toEqual(expected);
+});
+
+it('handles objects with numeric keys', () => {
+  const input = {
+    1: 'one',
+    2: 'two',
+  };
+  const expected = '{"1":"one","2":"two"}';
+  const result = canonicalize(input);
+  expect(result).toEqual(expected);
+});
+
+it('handles objects with undefined values', () => {
+  const input = {
+    a: 'b',
+    c: undefined,
+  };
+  const expected = '{"a":"b"}';
+  const result = canonicalize(input);
+  expect(result).toEqual(expected);
+});
+
+it('handles an object with a symbol value', () => {
+  const input = {
+    a: 'b',
+    c: Symbol('c'),
+  };
+  const expected = '{"a":"b"}';
+  const result = canonicalize(input);
+  expect(result).toEqual(expected);
+});
+
+it('handles an object with a symbol key', () => {
+  const input = {
+    a: 'b',
+    [Symbol('c')]: 'd',
+  };
+  const expected = '{"a":"b"}';
+  const result = canonicalize(input);
+  expect(result).toEqual(expected);
+});
+
+it('should throw an error for objects with cycles', () => {
+  const a = {};
+  const b = { a };
+  a.b = b;
+
+  expect(() => canonicalize(a)).toThrow('Cycle detected');
+});

package/src/__tests__/context-test.js

@@ -1,4 +1,4 @@
-const { checkContext, getContextKeys, getContextKinds, getCanonicalKey } = require('../context');
+const { checkContext, getContextKeys, getContextKinds, getCanonicalKey, hashContext } = require('../context');
 
 describe.each([{ key: 'test' }, { kind: 'user', key: 'test' }, { kind: 'multi', user: { key: 'test' } }])(
   'given a context which contains a single kind',
@@ -147,7 +147,7 @@ describe('getContextKeys', () => {
     expect(keys).toEqual({ user: 'test-user-key' });
   });
 
-  it.only('ignores empty string and null keys from multi context', () => {
+  it('ignores empty string and null keys from multi context', () => {
     const context = {
       kind: 'multi',
       user: {
@@ -199,3 +199,332 @@ describe('getContextKeys', () => {
     expect(keys).toEqual({});
   });
 });
+
+function mockHasher() {
+  let state = '';
+  return {
+    update: input => {
+      state += input;
+    },
+    digest: () => state,
+  };
+}
+
+it('hashes two equal contexts the same', async () => {
+  const a = {
+    kind: 'multi',
+    org: {
+      key: 'testKey',
+      name: 'testName',
+      cat: 'calico',
+      dog: 'lab',
+      anonymous: true,
+      _meta: {
+        privateAttributes: ['/a/b/c', 'cat', 'custom/dog'],
+      },
+    },
+    customer: {
+      key: 'testKey',
+      name: 'testName',
+      bird: 'party parrot',
+      chicken: 'hen',
+    },
+  };
+
+  const b = {
+    kind: 'multi',
+    org: {
+      key: 'testKey',
+      name: 'testName',
+      cat: 'calico',
+      dog: 'lab',
+      anonymous: true,
+      _meta: {
+        privateAttributes: ['/a/b/c', 'cat', 'custom/dog'],
+      },
+    },
+    customer: {
+      key: 'testKey',
+      name: 'testName',
+      bird: 'party parrot',
+      chicken: 'hen',
+    },
+  };
+  expect(await hashContext(a, mockHasher())).toEqual(await hashContext(b, mockHasher()));
+});
+
+it('handles shared references without getting stuck', async () => {
+  const sharedObject = { value: 'shared' };
+  const context = {
+    kind: 'multi',
+    org: {
+      key: 'testKey',
+      shared: sharedObject,
+    },
+    user: {
+      key: 'testKey',
+      shared: sharedObject,
+    },
+  };
+
+  const hash = await hashContext(context, mockHasher());
+  expect(hash).toBeDefined();
+});
+
+it('returns undefined for contexts with cycles', async () => {
+  const cyclicObject = { value: 'cyclic' };
+  cyclicObject.self = cyclicObject;
+
+  const context = {
+    kind: 'user',
+    key: 'testKey',
+    cyclic: cyclicObject,
+  };
+
+  expect(await hashContext(context, mockHasher())).toBeUndefined();
+});
+
+it('handles nested objects correctly', async () => {
+  const context = {
+    kind: 'user',
+    key: 'testKey',
+    nested: {
+      level1: {
+        level2: {
+          value: 'deep',
+        },
+      },
+    },
+  };
+
+  const hash = await hashContext(context, mockHasher());
+  expect(hash).toBeDefined();
+});
+
+it('handles arrays correctly', async () => {
+  const context = {
+    kind: 'user',
+    key: 'testKey',
+    array: [1, 2, 3],
+    nestedArray: [
+      [1, 2],
+      [3, 4],
+    ],
+  };
+
+  const hash = await hashContext(context, mockHasher());
+  expect(hash).toBeDefined();
+});
+
+it('handles primitive values correctly', async () => {
+  const context = {
+    kind: 'user',
+    key: 'testKey',
+    string: 'test',
+    number: 42,
+    boolean: true,
+    nullValue: null,
+    undefinedValue: undefined,
+  };
+
+  const hash = await hashContext(context, mockHasher());
+  expect(hash).toBeDefined();
+});
+
+it('includes private attributes in hash calculation', async () => {
+  const baseContext = {
+    kind: 'user',
+    key: 'testKey',
+    name: 'testName',
+    nested: {
+      value: 'testValue',
+    },
+  };
+
+  const contextWithPrivate = {
+    ...baseContext,
+    _meta: {
+      privateAttributes: ['name', 'nested/value'],
+    },
+  };
+
+  const hashWithPrivate = await hashContext(contextWithPrivate, mockHasher());
+  const hashWithoutPrivate = await hashContext(baseContext, mockHasher());
+
+  // The hashes should be different because private attributes are included in the hash
+  expect(hashWithPrivate).not.toEqual(hashWithoutPrivate);
+});
+
+it('uses the keys of attributes in the hash', async () => {
+  const a = {
+    kind: 'user',
+    key: 'testKey',
+    a: 'b',
+  };
+
+  const b = {
+    kind: 'user',
+    key: 'testKey',
+    b: 'b',
+  };
+
+  const hashA = await hashContext(a, mockHasher());
+  const hashB = await hashContext(b, mockHasher());
+  expect(hashA).not.toBe(hashB);
+});
+
+it('uses the keys of nested objects inside the hash', async () => {
+  const a = {
+    kind: 'user',
+    key: 'testKey',
+    nested: {
+      level1: {
+        level2: {
+          value: 'deep',
+        },
+      },
+    },
+  };
+
+  const b = {
+    kind: 'user',
+    key: 'testKey',
+    nested: {
+      sub1: {
+        sub2: {
+          value: 'deep',
+        },
+      },
+    },
+  };
+
+  const hashA = await hashContext(a, mockHasher());
+  const hashB = await hashContext(b, mockHasher());
+  expect(hashA).not.toBe(hashB);
+});
+
+it('uses the values of nested array in calculations', async () => {
+  const a = {
+    kind: 'user',
+    key: 'testKey',
+    array: [1, 2, 3],
+    nestedArray: [
+      [1, 2],
+      [3, 4],
+    ],
+  };
+
+  const b = {
+    kind: 'user',
+    key: 'testKey',
+    array: [1, 2, 3],
+    nestedArray: [
+      [2, 1],
+      [3, 4],
+    ],
+  };
+
+  const hashA = await hashContext(a, mockHasher());
+  const hashB = await hashContext(b, mockHasher());
+  expect(hashA).not.toBe(hashB);
+});
+
+it('uses the values of nested objects inside the hash', async () => {
+  const a = {
+    kind: 'user',
+    key: 'testKey',
+    nested: {
+      level1: {
+        level2: {
+          value: 'deep',
+        },
+      },
+    },
+  };
+
+  const b = {
+    kind: 'user',
+    key: 'testKey',
+    nested: {
+      level1: {
+        level2: {
+          value: 'deeper',
+        },
+      },
+    },
+  };
+
+  const hashA = await hashContext(a, mockHasher());
+  const hashB = await hashContext(b, mockHasher());
+  expect(hashA).not.toBe(hashB);
+});
+
+it('hashes _meta in attributes', async () => {
+  const a = {
+    kind: 'user',
+    key: 'testKey',
+    nested: {
+      level1: {
+        level2: {
+          _meta: { test: 'a' },
+        },
+      },
+    },
+  };
+
+  const b = {
+    kind: 'user',
+    key: 'testKey',
+    nested: {
+      level1: {
+        level2: {
+          _meta: { test: 'b' },
+        },
+      },
+    },
+  };
+
+  const hashA = await hashContext(a, mockHasher());
+  const hashB = await hashContext(b, mockHasher());
+  expect(hashA).not.toBe(hashB);
+});
+
+it('produces the same value for the given context', async () => {
+  // This isn't so much a test as it is a detection of change.
+  // If this test failed, and you didn't expect it, then you probably need to make sure your
+  // change makes sense.
+  const complexContext = {
+    kind: 'multi',
+    org: {
+      key: 'testKey',
+      name: 'testName',
+      cat: 'calico',
+      dog: 'lab',
+      anonymous: true,
+      nestedArray: [
+        [1, 2],
+        [3, 4],
+      ],
+      _meta: {
+        privateAttributes: ['/a/b/c', 'cat', 'custom/dog'],
+      },
+    },
+    customer: {
+      key: 'testKey',
+      name: 'testName',
+      bird: 'party parrot',
+      chicken: 'hen',
+      nested: {
+        level1: {
+          level2: {
+            value: 'deep',
+            _meta: { thisShouldBeInTheHash: true },
+          },
+        },
+      },
+    },
+  };
+  expect(await hashContext(complexContext, mockHasher())).toBe(
+    '{"customer":{"bird":"party parrot","chicken":"hen","key":"testKey","name":"testName","nested":{"level1":{"level2":{"_meta":{"thisShouldBeInTheHash":true},"value":"deep"}}}},"kind":"multi","org":{"_meta":{"privateAttributes":["/a/b/c","cat","custom/dog"]},"anonymous":true,"cat":"calico","dog":"lab","key":"testKey","name":"testName","nestedArray":[[1,2],[3,4]]}}'
+  );
+});

package/src/__tests__/stubPlatform.js

@@ -45,6 +45,15 @@ export function defaults() {
     diagnosticPlatformData: { name: 'stub-platform' },
     getCurrentUrl: () => currentUrl,
     isDoNotTrack: () => doNotTrack,
+    hasherFactory: (/*algorithm*/) => {
+      let content = '';
+      return {
+        update: value => {
+          content += value;
+        },
+        digest: (/*format*/) => content,
+      };
+    },
     eventSourceFactory: (url, options) => {
       const es = new EventSource(url);
       es.options = options;

package/src/__tests__/testdata/LICENSE.txt

@@ -0,0 +1,13 @@
+ Copyright 2018 Anders Rundgren
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       https://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/src/__tests__/testdata/VENDOR.txt

@@ -0,0 +1,2 @@
+Test data originally from:
+https://github.com/cyberphone/json-canonicalization/tree/master/testdata

package/src/__tests__/testdata/input/arrays.json

@@ -0,0 +1,8 @@
+[
+  56,
+  {
+    "d": true,
+    "10": null,
+    "1": [ ]
+  }
+]

package/src/__tests__/testdata/input/french.json

@@ -0,0 +1,6 @@
+{
+  "peach": "This sorting order",
+  "péché": "is wrong according to French",
+  "pêche": "but canonicalization MUST",
+  "sin":   "ignore locale"
+}

package/src/__tests__/testdata/input/structures.json

@@ -0,0 +1,8 @@
+{
+  "1": {"f": {"f": "hi","F": 5} ,"\n": 56.0},
+  "10": { },
+  "": "empty",
+  "a": { },
+  "111": [ {"e": "yes","E": "no" } ],
+  "A": { }
+}

package/src/__tests__/testdata/input/unicode.json

@@ -0,0 +1,3 @@
+{
+  "Unnormalized Unicode":"A\u030a"
+}

package/src/__tests__/testdata/input/values.json

@@ -0,0 +1,5 @@
+{
+  "numbers": [333333333.33333329, 1E30, 4.50, 2e-3, 0.000000000000000000000000001],
+  "string": "\u20ac$\u000F\u000aA'\u0042\u0022\u005c\\\"\/",
+  "literals": [null, true, false]
+}

package/src/__tests__/testdata/input/weird.json

@@ -0,0 +1,11 @@
+{
+  "\u20ac": "Euro Sign",
+  "\r": "Carriage Return",
+  "\u000a": "Newline",
+  "1": "One",
+  "\u0080": "Control\u007f",
+  "\ud83d\ude02": "Smiley",
+  "\u00f6": "Latin Small Letter O With Diaeresis",
+  "\ufb33": "Hebrew Letter Dalet With Dagesh",
+  "</script>": "Browser Challenge"
+}

package/src/__tests__/testdata/output/arrays.json

@@ -0,0 +1 @@
+[56,{"1":[],"10":null,"d":true}]

package/src/__tests__/testdata/output/french.json

@@ -0,0 +1 @@
+{"peach":"This sorting order","péché":"is wrong according to French","pêche":"but canonicalization MUST","sin":"ignore locale"}

package/src/__tests__/testdata/output/structures.json

@@ -0,0 +1 @@
+{"":"empty","1":{"\n":56,"f":{"F":5,"f":"hi"}},"10":{},"111":[{"E":"no","e":"yes"}],"A":{},"a":{}}

package/src/__tests__/testdata/output/unicode.json

@@ -0,0 +1 @@
+{"Unnormalized Unicode":"Å"}

package/src/__tests__/testdata/output/values.json

@@ -0,0 +1 @@
+{"literals":[null,true,false],"numbers":[333333333.3333333,1e+30,4.5,0.002,1e-27],"string":"€$\u000f\nA'B\"\\\\\"/"}

package/src/__tests__/testdata/output/weird.json

@@ -0,0 +1 @@
+{"\n":"Newline","\r":"Carriage Return","1":"One","</script>":"Browser Challenge","€":"Control","ö":"Latin Small Letter O With Diaeresis","€":"Euro Sign","😂":"Smiley","דּ":"Hebrew Letter Dalet With Dagesh"}

package/src/canonicalize.js

@@ -0,0 +1,41 @@
+/**
+ * Given some object to serialize product a canonicalized JSON string.
+ * https://www.rfc-editor.org/rfc/rfc8785.html
+ *
+ * We do not support custom toJSON methods on objects. Objects should be limited to basic types.
+ *
+ * @param {any} object The object to serialize.
+ * @param {any[]?} visited The list of objects that have already been visited to avoid cycles.
+ * @returns {string} The canonicalized JSON string.
+ */
+function canonicalize(object, visited = []) {
+  // For JavaScript the default JSON serialization will produce canonicalized output for basic types.
+  if (object === null || typeof object !== 'object') {
+    return JSON.stringify(object);
+  }
+
+  if (visited.includes(object)) {
+    throw new Error('Cycle detected');
+  }
+
+  if (Array.isArray(object)) {
+    const values = object
+      .map(item => canonicalize(item, [...visited, object]))
+      .map(item => (item === undefined ? 'null' : item));
+    return `[${values.join(',')}]`;
+  }
+
+  const values = Object.keys(object)
+    .sort()
+    .map(key => {
+      const value = canonicalize(object[key], [...visited, object]);
+      if (value !== undefined) {
+        return `${JSON.stringify(key)}:${value}`;
+      }
+      return undefined;
+    })
+    .filter(item => item !== undefined);
+  return `{${values.join(',')}}`;
+}
+
+module.exports = canonicalize;

package/src/context.js

@@ -1,10 +1,11 @@
+const { commonBasicLogger } = require('./loggers');
+const canonicalize = require('./canonicalize');
+
 /**
  * Validate a context kind.
  * @param {string} kind
  * @returns true if the kind is valid.
  */
-const { commonBasicLogger } = require('./loggers');
-
 function validKind(kind) {
   return typeof kind === 'string' && kind !== 'kind' && kind.match(/^(\w|\.|-)+$/);
 }
@@ -44,7 +45,7 @@ function checkContext(context, allowLegacyKey) {
 /**
  * For a given context get a list of context kinds.
  * @param {Object} context
- * @returns A list of kinds in the context.
+ * @returns {string[]} A list of kinds in the context.
  */
 function getContextKinds(context) {
   if (context) {
@@ -126,9 +127,45 @@ function getContextKeys(context, logger = commonBasicLogger()) {
   return keys;
 }
 
+/**
+ * Hash the given context using the provided hasher.
+ * This implementation can produce different hashes for equivalent contexts.
+ *
+ * For example:
+ * A legacy user and a single-kind context of user kind that are equivalent, will hash differently.
+ * A multi-context with one kind, and the single context with that kind are equivalent, but will hash differently.
+ * Two equivalent contexts, with private attributes that are defined in different orders, will hash differently.
+ *
+ * @param {Object} context
+ * @param {{update: (value: string) => void, digest: (format: string) => Promise<string>}} hasher
+ * @returns {Promise<string | undefined>} The hash of the context, or undefined if the context is invalid.
+ */
+function hashContext(context, hasher) {
+  // In js-core we have legacy and non-legacy contexts hash the same. This implementation does not support that.
+  // Because this implementation directly uses the user-provided context and doesn't manipulate it.
+  // The js-core implementation is more conceptually correct, but it isn't a practical requirement.
+
+  // This implementation additionally doesn't produce the same hash for an equivalent multi-context with one kind, and
+  // the single context with that kind.
+  if (!checkContext(context)) {
+    return undefined;
+  }
+
+  try {
+    const canonicalized = canonicalize(context);
+
+    hasher.update(canonicalized);
+
+    return hasher.digest('hex');
+  } catch {
+    return undefined;
+  }
+}
+
 module.exports = {
   checkContext,
   getContextKeys,
   getContextKinds,
   getCanonicalKey,
+  hashContext,
 };