@launchdarkly/js-sdk-common 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+All notable changes to `@launchdarkly/js-sdk-common` will be documented in this file. This project adheres to [Semantic Versioning](http://semver.org).
+
+## 0.1.0 (2023-03-15)
+
+Initial prerelease version.

package/README.md

@@ -0,0 +1,25 @@
+# LaunchDarkly SDK JavaScript Common Code
+
+[![NPM](TODO)
+![Actions Status](TODO)
+[![Documentation](https://img.shields.io/static/v1?label=GitHub+Pages&message=API+reference&color=00add8)](TODO)
+
+This project contains Typescript classes and interfaces that are applicable to client-side and server-side JavaScript SDKs.
+
+## Contributing
+
+See [Contributing](../CONTRIBUTING.md).
+
+## About LaunchDarkly
+
+- LaunchDarkly is a continuous delivery platform that provides feature flags as a service and allows developers to iterate quickly and safely. We allow you to easily flag your features and manage them from the LaunchDarkly dashboard. With LaunchDarkly, you can:
+  - Roll out a new feature to a subset of your users (like a group of users who opt-in to a beta tester group), gathering feedback and bug reports from real-world use cases.
+  - Gradually roll out a feature to an increasing percentage of users, and track the effect that the feature has on key metrics (for instance, how likely is a user to complete a purchase if they have feature A versus feature B?).
+  - Turn off a feature that you realize is causing performance problems in production, without needing to re-deploy, or even restart the application with a changed configuration file.
+  - Grant access to certain features based on user attributes, like payment plan (eg: users on the ‘gold’ plan get access to more features than users in the ‘silver’ plan). Disable parts of your application to facilitate maintenance, without taking everything offline.
+- LaunchDarkly provides feature flag SDKs for a wide variety of languages and technologies. Check out [our documentation](https://docs.launchdarkly.com/sdk) for a complete list.
+- Explore LaunchDarkly
+  - [launchdarkly.com](https://www.launchdarkly.com/ 'LaunchDarkly Main Website') for more information
+  - [docs.launchdarkly.com](https://docs.launchdarkly.com/ 'LaunchDarkly Documentation') for our documentation and SDK reference guides
+  - [apidocs.launchdarkly.com](https://apidocs.launchdarkly.com/ 'LaunchDarkly API Documentation') for our API documentation
+  - [blog.launchdarkly.com](https://blog.launchdarkly.com/ 'LaunchDarkly Blog Documentation') for the latest product updates

package/dist/AttributeReference.d.ts

@@ -0,0 +1,35 @@
+import { LDContextCommon } from './api/context/LDContextCommon';
+export default class AttributeReference {
+    readonly isValid: boolean;
+    /**
+     * When redacting attributes this name can be directly added to the list of
+     * redactions.
+     */
+    readonly redactionName: string;
+    /**
+     * For use as invalid references when deserializing Flag/Segment data.
+     */
+    static readonly invalidReference: AttributeReference;
+    private readonly components;
+    /**
+     * Take an attribute reference string, or literal string, and produce
+     * an attribute reference.
+     *
+     * Legacy user objects would have been created with names not
+     * references. So, in that case, we need to use them as a component
+     * without escaping them.
+     *
+     * e.g. A user could contain a custom attribute of `/a` which would
+     * become the literal `a` if treated as a reference. Which would cause
+     * it to no longer be redacted.
+     * @param refOrLiteral The attribute reference string or literal string.
+     * @param literal it true the value should be treated as a literal.
+     */
+    constructor(refOrLiteral: string, literal?: boolean);
+    get(target: LDContextCommon): LDContextCommon | undefined;
+    getComponent(depth: number): string;
+    get depth(): number;
+    get isKind(): boolean;
+    compare(other: AttributeReference): boolean;
+}
+//# sourceMappingURL=AttributeReference.d.ts.map

package/dist/AttributeReference.d.ts.map

@@ -0,0 +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,UAAU,CAAW;IAEtC;;;;;;;;;;;;;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"}

package/dist/AttributeReference.js

@@ -0,0 +1,126 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * Converts a literal to a ref string.
+ * @param value
+ * @returns An escaped literal which can be used as a ref.
+ */
+function toRefString(value) {
+    return `/${value.replace(/~/g, '~0').replace(/\//g, '~1')}`;
+}
+/**
+ * Produce a literal from a ref component.
+ * @param ref
+ * @returns A literal version of the ref.
+ */
+function unescape(ref) {
+    return ref.indexOf('~') ? ref.replace(/~1/g, '/').replace(/~0/g, '~') : ref;
+}
+function getComponents(reference) {
+    const referenceWithoutPrefix = reference.startsWith('/') ? reference.substring(1) : reference;
+    return referenceWithoutPrefix.split('/').map((component) => unescape(component));
+}
+function isLiteral(reference) {
+    return !reference.startsWith('/');
+}
+function validate(reference) {
+    return !reference.match(/\/\/|(^\/.*~[^0|^1])|~$/);
+}
+class AttributeReference {
+    /**
+     * Take an attribute reference string, or literal string, and produce
+     * an attribute reference.
+     *
+     * Legacy user objects would have been created with names not
+     * references. So, in that case, we need to use them as a component
+     * without escaping them.
+     *
+     * e.g. A user could contain a custom attribute of `/a` which would
+     * become the literal `a` if treated as a reference. Which would cause
+     * it to no longer be redacted.
+     * @param refOrLiteral The attribute reference string or literal string.
+     * @param literal it true the value should be treated as a literal.
+     */
+    constructor(refOrLiteral, literal = false) {
+        if (!literal) {
+            this.redactionName = refOrLiteral;
+            if (refOrLiteral === '' || refOrLiteral === '/' || !validate(refOrLiteral)) {
+                this.isValid = false;
+                this.components = [];
+                return;
+            }
+            if (isLiteral(refOrLiteral)) {
+                this.components = [refOrLiteral];
+            }
+            else if (refOrLiteral.indexOf('/', 1) < 0) {
+                this.components = [unescape(refOrLiteral.slice(1))];
+            }
+            else {
+                this.components = getComponents(refOrLiteral);
+            }
+            // The items inside of '_meta' are not intended to be addressable.
+            // Excluding it as a valid reference means that we can make it non-addressable
+            // without having to copy all the attributes out of the context object
+            // provided by the user.
+            if (this.components[0] === '_meta') {
+                this.isValid = false;
+            }
+            else {
+                this.isValid = true;
+            }
+        }
+        else {
+            const literalVal = refOrLiteral;
+            this.components = [literalVal];
+            this.isValid = literalVal !== '';
+            // Literals which start with '/' need escaped to prevent ambiguity.
+            this.redactionName = literalVal.startsWith('/') ? toRefString(literalVal) : literalVal;
+        }
+    }
+    get(target) {
+        const { components, isValid } = this;
+        if (!isValid) {
+            return undefined;
+        }
+        let current = target;
+        // This doesn't use a range based for loops, because those use generators.
+        // See `no-restricted-syntax`.
+        // It also doesn't use a collection method because this logic is more
+        // straightforward with a loop.
+        for (let index = 0; index < components.length; index += 1) {
+            const component = components[index];
+            if (current !== null &&
+                current !== undefined &&
+                // See https://eslint.org/docs/rules/no-prototype-builtins
+                Object.prototype.hasOwnProperty.call(current, component) &&
+                typeof current === 'object' &&
+                // We do not want to allow indexing into an array.
+                !Array.isArray(current)) {
+                current = current[component];
+            }
+            else {
+                return undefined;
+            }
+        }
+        return current;
+    }
+    getComponent(depth) {
+        return this.components[depth];
+    }
+    get depth() {
+        return this.components.length;
+    }
+    get isKind() {
+        return this.components.length === 1 && this.components[0] === 'kind';
+    }
+    compare(other) {
+        return (this.depth === other.depth &&
+            this.components.every((value, index) => value === other.getComponent(index)));
+    }
+}
+exports.default = AttributeReference;
+/**
+ * For use as invalid references when deserializing Flag/Segment data.
+ */
+AttributeReference.invalidReference = new AttributeReference('');
+//# sourceMappingURL=AttributeReference.js.map

package/dist/AttributeReference.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AttributeReference.js","sourceRoot":"","sources":["../src/AttributeReference.ts"],"names":[],"mappings":"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"}

package/dist/Context.d.ts

@@ -0,0 +1,90 @@
+import { LDContextCommon } from './api/context';
+import { LDContext } from './api/context/LDContext';
+import AttributeReference from './AttributeReference';
+/**
+ * Container for a context/contexts. Because contexts come from external code
+ * they must be thoroughly validated and then formed to comply with
+ * the type system.
+ */
+export default class Context {
+    private context?;
+    private isMulti;
+    private isUser;
+    private wasLegacy;
+    private contexts;
+    private privateAttributeReferences?;
+    readonly kind: string;
+    /**
+     * Is this a valid context. If a valid context cannot be created, then this flag will be true.
+     * The validity of a context should be tested before it is used.
+     */
+    readonly valid: boolean;
+    readonly message?: string;
+    static readonly userKind: string;
+    /**
+     * Contexts should be created using the static factory method {@link Context.fromLDContext}.
+     * @param kind The kind of the context.
+     *
+     * The factory methods are static functions within the class because they access private
+     * implementation details, so they cannot be free functions.
+     */
+    private constructor();
+    private static contextForError;
+    private static getValueFromContext;
+    private contextForKind;
+    private static fromMultiKindContext;
+    private static fromSingleKindContext;
+    private static fromLegacyUser;
+    /**
+     * Attempt to create a {@link Context} from an {@link LDContext}.
+     * @param context The input context to create a Context from.
+     * @returns a {@link Context}, if the context was not valid, then the returned contexts `valid`
+     * property will be false.
+     */
+    static fromLDContext(context: LDContext): Context;
+    /**
+     * Attempt to get a value for the given context kind using the given reference.
+     * @param reference The reference to the value to get.
+     * @param kind The kind of the context to get the value for.
+     * @returns a value or `undefined` if one is not found.
+     */
+    valueForKind(reference: AttributeReference, kind?: string): any | undefined;
+    /**
+     * Attempt to get a key for the specified kind.
+     * @param kind The kind to get a key for.
+     * @returns The key for the specified kind, or undefined.
+     */
+    key(kind?: string): string | undefined;
+    /**
+     * True if this is a multi-kind context.
+     */
+    get isMultiKind(): boolean;
+    /**
+     * Get the canonical key for this context.
+     */
+    get canonicalKey(): string;
+    /**
+     * Get the kinds of this context.
+     */
+    get kinds(): string[];
+    /**
+     * Get the kinds, and their keys, for this context.
+     */
+    get kindsAndKeys(): Record<string, string>;
+    /**
+     * Get the attribute references.
+     *
+     * @param kind
+     */
+    privateAttributes(kind: string): AttributeReference[];
+    /**
+     * Get the underlying context objects from this context.
+     *
+     * This method is intended to be used in event generation.
+     *
+     * The returned objects should not be modified.
+     */
+    getContexts(): [string, LDContextCommon][];
+    get legacy(): boolean;
+}
+//# sourceMappingURL=Context.d.ts.map

package/dist/Context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Context.d.ts","sourceRoot":"","sources":["../src/Context.ts"],"names":[],"mappings":"AAEA,OAAO,EAAmD,eAAe,EAAE,MAAM,eAAe,CAAC;AACjG,OAAO,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AACpD,OAAO,kBAAkB,MAAM,sBAAsB,CAAC;AA+KtD;;;;GAIG;AACH,MAAM,CAAC,OAAO,OAAO,OAAO;IAC1B,OAAO,CAAC,OAAO,CAAC,CAAkB;IAElC,OAAO,CAAC,OAAO,CAAkB;IAEjC,OAAO,CAAC,MAAM,CAAkB;IAEhC,OAAO,CAAC,SAAS,CAAkB;IAEnC,OAAO,CAAC,QAAQ,CAAuC;IAEvD,OAAO,CAAC,0BAA0B,CAAC,CAAuC;IAE1E,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,eAAe;IAI9B,OAAO,CAAC,MAAM,CAAC,mBAAmB;IAclC,OAAO,CAAC,cAAc;IAUtB,OAAO,CAAC,MAAM,CAAC,oBAAoB;IAwDnC,OAAO,CAAC,MAAM,CAAC,qBAAqB;IAyBpC,OAAO,CAAC,MAAM,CAAC,cAAc;IAgB7B;;;;;OAKG;WACW,aAAa,CAAC,OAAO,EAAE,SAAS,GAAG,OAAO;IAiBxD;;;;;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"}