@launchdarkly/js-sdk-common 2.17.0 → 2.18.0

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 All notable changes to `@launchdarkly/js-sdk-common` will be documented in this file. This project adheres to [Semantic Versioning](http://semver.org).
 
+## [2.18.0](https://github.com/launchdarkly/js-core/compare/js-sdk-common-v2.17.0...js-sdk-common-v2.18.0) (2025-05-21)
+
+
+### Features
+
+* Add support for per-context summary events. ([#859](https://github.com/launchdarkly/js-core/issues/859)) ([c9fa5c4](https://github.com/launchdarkly/js-core/commit/c9fa5c45f3ac2cbaad2f2e6312d5231c3f671d98))
+
 ## [2.17.0](https://github.com/launchdarkly/js-core/compare/js-sdk-common-v2.16.0...js-sdk-common-v2.17.0) (2025-04-29)
 
 

package/dist/cjs/AttributeReference.d.ts

@@ -31,5 +31,6 @@ export default class AttributeReference {
     get depth(): number;
     get isKind(): boolean;
     compare(other: AttributeReference): boolean;
+    get components(): string[];
 }
 //# sourceMappingURL=AttributeReference.d.ts.map

package/dist/cjs/AttributeReference.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AttributeReference.d.ts","sourceRoot":"","sources":["../src/AttributeReference.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AAiChE,MAAM,CAAC,OAAO,OAAO,kBAAkB;IACrC,SAAgB,OAAO,UAAC;IAExB;;;OAGG;IACH,SAAgB,aAAa,SAAC;IAE9B;;OAEG;IACH,gBAAuB,gBAAgB,qBAA8B;IAErE,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAW;IAEvC;;;;;;;;;;;;;OAaG;gBACgB,YAAY,EAAE,MAAM,EAAE,OAAO,GAAE,OAAe;IAkC1D,GAAG,CAAC,MAAM,EAAE,eAAe;IA+B3B,YAAY,CAAC,KAAK,EAAE,MAAM;IAIjC,IAAW,KAAK,WAEf;IAED,IAAW,MAAM,IAAI,OAAO,CAE3B;IAEM,OAAO,CAAC,KAAK,EAAE,kBAAkB;CAMzC"}
+{"version":3,"file":"AttributeReference.d.ts","sourceRoot":"","sources":["../src/AttributeReference.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AAiChE,MAAM,CAAC,OAAO,OAAO,kBAAkB;IACrC,SAAgB,OAAO,UAAC;IAExB;;;OAGG;IACH,SAAgB,aAAa,SAAC;IAE9B;;OAEG;IACH,gBAAuB,gBAAgB,qBAA8B;IAErE,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAW;IAEvC;;;;;;;;;;;;;OAaG;gBACgB,YAAY,EAAE,MAAM,EAAE,OAAO,GAAE,OAAe;IAkC1D,GAAG,CAAC,MAAM,EAAE,eAAe;IA+B3B,YAAY,CAAC,KAAK,EAAE,MAAM;IAIjC,IAAW,KAAK,WAEf;IAED,IAAW,MAAM,IAAI,OAAO,CAE3B;IAEM,OAAO,CAAC,KAAK,EAAE,kBAAkB;IAOxC,IAAW,UAAU,aAEpB;CACF"}

package/dist/cjs/Context.d.ts

@@ -12,6 +12,7 @@ export default class Context {
     private _wasLegacy;
     private _contexts;
     private _privateAttributeReferences?;
+    private _cachedCanonicalJson?;
     readonly kind: string;
     /**
      * Is this a valid context. If a valid context cannot be created, then this flag will be true.
@@ -91,5 +92,13 @@ export default class Context {
      */
     getContexts(): [string, LDContextCommon][];
     get legacy(): boolean;
+    /**
+     * Get the serialized canonical JSON for this context. This is not filtered for use in events.
+     *
+     * This method will cache the result.
+     *
+     * @returns The serialized canonical JSON or undefined if it cannot be serialized.
+     */
+    canonicalUnfilteredJson(): string | undefined;
 }
 //# sourceMappingURL=Context.d.ts.map

package/dist/cjs/Context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Context.d.ts","sourceRoot":"","sources":["../src/Context.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,SAAS,EACT,eAAe,EAIhB,MAAM,OAAO,CAAC;AACf,OAAO,kBAAkB,MAAM,sBAAsB,CAAC;AAiJtD;;;;GAIG;AACH,MAAM,CAAC,OAAO,OAAO,OAAO;IAC1B,OAAO,CAAC,QAAQ,CAAC,CAAkB;IAEnC,OAAO,CAAC,QAAQ,CAAkB;IAElC,OAAO,CAAC,OAAO,CAAkB;IAEjC,OAAO,CAAC,UAAU,CAAkB;IAEpC,OAAO,CAAC,SAAS,CAAuC;IAExD,OAAO,CAAC,2BAA2B,CAAC,CAAuC;IAE3E,SAAgB,IAAI,EAAE,MAAM,CAAC;IAE7B;;;OAGG;IACH,SAAgB,KAAK,EAAE,OAAO,CAAC;IAE/B,SAAgB,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjC,MAAM,CAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAgB;IAEhD;;;;;;OAMG;IACH,OAAO;IAMP,OAAO,CAAC,MAAM,CAAC,gBAAgB;IAI/B,OAAO,CAAC,MAAM,CAAC,oBAAoB;IAcnC,OAAO,CAAC,eAAe;IAUvB,OAAO,CAAC,MAAM,CAAC,qBAAqB;IAwDpC,OAAO,CAAC,MAAM,CAAC,sBAAsB;IAyBrC,OAAO,CAAC,MAAM,CAAC,eAAe;IAgB9B;;;;;OAKG;WACW,aAAa,CAAC,OAAO,EAAE,SAAS,GAAG,OAAO;IAiBxD;;;;OAIG;WACW,WAAW,CAAC,OAAO,EAAE,OAAO,GAAG,SAAS,GAAG,SAAS;IAoBlE;;;;;OAKG;IACI,YAAY,CAAC,SAAS,EAAE,kBAAkB,EAAE,IAAI,GAAE,MAAqB,GAAG,GAAG,GAAG,SAAS;IAOhG;;;;OAIG;IACI,GAAG,CAAC,IAAI,GAAE,MAAqB,GAAG,MAAM,GAAG,SAAS;IAI3D;;OAEG;IACH,IAAW,WAAW,IAAI,OAAO,CAEhC;IAED;;OAEG;IACH,IAAW,YAAY,IAAI,MAAM,CAWhC;IAED;;OAEG;IACH,IAAW,KAAK,IAAI,MAAM,EAAE,CAK3B;IAED;;OAEG;IACH,IAAW,YAAY,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAWhD;IAED;;;;OAIG;IACI,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,kBAAkB,EAAE;IAI5D;;;;;;OAMG;IACI,WAAW,IAAI,CAAC,MAAM,EAAE,eAAe,CAAC,EAAE;IAOjD,IAAW,MAAM,IAAI,OAAO,CAE3B;CACF"}
+{"version":3,"file":"Context.d.ts","sourceRoot":"","sources":["../src/Context.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,SAAS,EACT,eAAe,EAIhB,MAAM,OAAO,CAAC;AACf,OAAO,kBAAkB,MAAM,sBAAsB,CAAC;AAkJtD;;;;GAIG;AACH,MAAM,CAAC,OAAO,OAAO,OAAO;IAC1B,OAAO,CAAC,QAAQ,CAAC,CAAkB;IAEnC,OAAO,CAAC,QAAQ,CAAkB;IAElC,OAAO,CAAC,OAAO,CAAkB;IAEjC,OAAO,CAAC,UAAU,CAAkB;IAEpC,OAAO,CAAC,SAAS,CAAuC;IAExD,OAAO,CAAC,2BAA2B,CAAC,CAAuC;IAE3E,OAAO,CAAC,oBAAoB,CAAC,CAAS;IAEtC,SAAgB,IAAI,EAAE,MAAM,CAAC;IAE7B;;;OAGG;IACH,SAAgB,KAAK,EAAE,OAAO,CAAC;IAE/B,SAAgB,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjC,MAAM,CAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAgB;IAEhD;;;;;;OAMG;IACH,OAAO;IAMP,OAAO,CAAC,MAAM,CAAC,gBAAgB;IAI/B,OAAO,CAAC,MAAM,CAAC,oBAAoB;IAcnC,OAAO,CAAC,eAAe;IAUvB,OAAO,CAAC,MAAM,CAAC,qBAAqB;IAwDpC,OAAO,CAAC,MAAM,CAAC,sBAAsB;IAyBrC,OAAO,CAAC,MAAM,CAAC,eAAe;IAgB9B;;;;;OAKG;WACW,aAAa,CAAC,OAAO,EAAE,SAAS,GAAG,OAAO;IAiBxD;;;;OAIG;WACW,WAAW,CAAC,OAAO,EAAE,OAAO,GAAG,SAAS,GAAG,SAAS;IAoBlE;;;;;OAKG;IACI,YAAY,CAAC,SAAS,EAAE,kBAAkB,EAAE,IAAI,GAAE,MAAqB,GAAG,GAAG,GAAG,SAAS;IAOhG;;;;OAIG;IACI,GAAG,CAAC,IAAI,GAAE,MAAqB,GAAG,MAAM,GAAG,SAAS;IAI3D;;OAEG;IACH,IAAW,WAAW,IAAI,OAAO,CAEhC;IAED;;OAEG;IACH,IAAW,YAAY,IAAI,MAAM,CAWhC;IAED;;OAEG;IACH,IAAW,KAAK,IAAI,MAAM,EAAE,CAK3B;IAED;;OAEG;IACH,IAAW,YAAY,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAWhD;IAED;;;;OAIG;IACI,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,kBAAkB,EAAE;IAI5D;;;;;;OAMG;IACI,WAAW,IAAI,CAAC,MAAM,EAAE,eAAe,CAAC,EAAE;IAOjD,IAAW,MAAM,IAAI,OAAO,CAE3B;IAED;;;;;;OAMG;IACI,uBAAuB,IAAI,MAAM,GAAG,SAAS;CAcrD"}

package/dist/cjs/api/subsystem/DataSystem/DataSource.d.ts

@@ -13,7 +13,7 @@ export interface DataSource {
      */
     start(dataCallback: (basis: boolean, data: any) => void, statusCallback: (status: DataSourceState, err?: any) => void): void;
     /**
-     * May be called any number of times, if already stopped, has no effect.
+     * May be called any number of times, if already stopped, has no effect. Datasource will not make any additional callbacks after stop returns.
      */
     stop(): void;
 }

package/dist/cjs/index.cjs

@@ -117,6 +117,9 @@ class AttributeReference {
         return (this.depth === other.depth &&
             this._components.every((value, index) => value === other.getComponent(index)));
     }
+    get components() {
+        return [...this._components];
+    }
 }
 /**
  * For use as invalid references when deserializing Flag/Segment data.
@@ -316,6 +319,41 @@ function isLegacyUser(context) {
     return !('kind' in context) || context.kind === null || context.kind === undefined;
 }
 
+/**
+ * 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 object The object to serialize.
+ */
+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(',')}}`;
+}
+
 // The general strategy for the context is to transform the passed in context
 // as little as possible. We do convert the legacy users to a single kind
 // context, but we do not translate all passed contexts into a rigid structure.
@@ -690,6 +728,28 @@ class Context {
     get legacy() {
         return this._wasLegacy;
     }
+    /**
+     * Get the serialized canonical JSON for this context. This is not filtered for use in events.
+     *
+     * This method will cache the result.
+     *
+     * @returns The serialized canonical JSON or undefined if it cannot be serialized.
+     */
+    canonicalUnfilteredJson() {
+        if (!this.valid) {
+            return undefined;
+        }
+        if (this._cachedCanonicalJson) {
+            return this._cachedCanonicalJson;
+        }
+        try {
+            this._cachedCanonicalJson = canonicalize(Context.toLDContext(this));
+        }
+        catch {
+            // Indicated by undefined being returned.
+        }
+        return this._cachedCanonicalJson;
+    }
 }
 Context.UserKind = DEFAULT_KIND;
 
@@ -2353,7 +2413,9 @@ function counterKey(event) {
  * @internal
  */
 class EventSummarizer {
-    constructor() {
+    constructor(_singleContext = false, _contextFilter) {
+        this._singleContext = _singleContext;
+        this._contextFilter = _contextFilter;
         this._startDate = 0;
         this._endDate = 0;
         this._counters = {};
@@ -2361,6 +2423,9 @@ class EventSummarizer {
     }
     summarizeEvent(event) {
         if (isFeature(event) && !event.excludeFromSummaries) {
+            if (!this._context) {
+                this._context = event.context;
+            }
             const countKey = counterKey(event);
             const counter = this._counters[countKey];
             let kinds = this._contextKinds[event.key];
@@ -2410,14 +2475,19 @@ class EventSummarizer {
             flagSummary.counters.push(counterOut);
             return acc;
         }, {});
-        return {
+        const event = {
             startDate: this._startDate,
             endDate: this._endDate,
             features,
             kind: 'summary',
+            context: this._context !== undefined && this._singleContext
+                ? this._contextFilter?.filter(this._context)
+                : undefined,
         };
+        this._clearSummary();
+        return event;
     }
-    clearSummary() {
+    _clearSummary() {
         this._startDate = 0;
         this._endDate = 0;
         this._counters = {};
@@ -2432,6 +2502,38 @@ class LDInvalidSDKKeyError extends Error {
     }
 }
 
+class MultiEventSummarizer {
+    constructor(_contextFilter, _logger) {
+        this._contextFilter = _contextFilter;
+        this._logger = _logger;
+        this._summarizers = {};
+    }
+    summarizeEvent(event) {
+        if (isFeature(event)) {
+            const key = event.context.canonicalUnfilteredJson();
+            if (!key) {
+                if (event.context.valid) {
+                    // The context appeared valid, but it could not be hashed.
+                    // This is likely because of a cycle in the data.
+                    this._logger?.error('Unable to serialize context, likely the context contains a cycle.');
+                }
+                return;
+            }
+            let summarizer = this._summarizers[key];
+            if (!summarizer) {
+                this._summarizers[key] = new EventSummarizer(true, this._contextFilter);
+                summarizer = this._summarizers[key];
+            }
+            summarizer.summarizeEvent(event);
+        }
+    }
+    getSummaries() {
+        const summarizersToFlush = this._summarizers;
+        this._summarizers = {};
+        return Object.values(summarizersToFlush).map((summarizer) => summarizer.getSummary());
+    }
+}
+
 /**
  * The contents of this file are for event sampling. They are not used for
  * any purpose requiring cryptographic security.
@@ -2452,12 +2554,14 @@ function shouldSample(ratio) {
     return Math.floor(Math.random() * truncated) === 0;
 }
 
+function isMultiEventSummarizer(summarizer) {
+    return summarizer.getSummaries !== undefined;
+}
 class EventProcessor {
-    constructor(_config, clientContext, baseHeaders, _contextDeduplicator, _diagnosticsManager, start = true) {
+    constructor(_config, clientContext, baseHeaders, _contextDeduplicator, _diagnosticsManager, start = true, summariesPerContext = false) {
         this._config = _config;
         this._contextDeduplicator = _contextDeduplicator;
         this._diagnosticsManager = _diagnosticsManager;
-        this._summarizer = new EventSummarizer();
         this._queue = [];
         this._lastKnownPastTime = 0;
         this._droppedEvents = 0;
@@ -2470,6 +2574,12 @@ class EventProcessor {
         this._logger = clientContext.basicConfiguration.logger;
         this._eventSender = new EventSender(clientContext, baseHeaders);
         this._contextFilter = new ContextFilter(_config.allAttributesPrivate, _config.privateAttributes.map((ref) => new AttributeReference(ref)));
+        if (summariesPerContext) {
+            this._summarizer = new MultiEventSummarizer(this._contextFilter, this._logger);
+        }
+        else {
+            this._summarizer = new EventSummarizer();
+        }
         if (start) {
             this.start();
         }
@@ -2521,10 +2631,19 @@ class EventProcessor {
         }
         const eventsToFlush = this._queue;
         this._queue = [];
-        const summary = this._summarizer.getSummary();
-        this._summarizer.clearSummary();
-        if (Object.keys(summary.features).length) {
-            eventsToFlush.push(summary);
+        if (isMultiEventSummarizer(this._summarizer)) {
+            const summaries = this._summarizer.getSummaries();
+            summaries.forEach((summary) => {
+                if (Object.keys(summary.features).length) {
+                    eventsToFlush.push(summary);
+                }
+            });
+        }
+        else {
+            const summary = this._summarizer.getSummary();
+            if (Object.keys(summary.features).length) {
+                eventsToFlush.push(summary);
+            }
         }
         if (!eventsToFlush.length) {
             return;
@@ -3115,6 +3234,7 @@ var index = /*#__PURE__*/Object.freeze({
     NullEventProcessor: NullEventProcessor,
     PayloadProcessor: PayloadProcessor,
     PayloadStreamReader: PayloadStreamReader,
+    canonicalize: canonicalize,
     initMetadataFromHeaders: initMetadataFromHeaders,
     isLegacyUser: isLegacyUser,
     isMultiKind: isMultiKind,