@snap/camera-kit 0.7.0

package/lib/configuration.js

@@ -0,0 +1,36 @@
+import { copyDefinedProperties } from "./common/copyDefinedProperties";
+import { getConfigurationOverrides } from "./configurationOverrides";
+import { Injectable } from "./dependency-injection/Injectable";
+/**
+ * Defaults are provided for runtime configuration and any optional bootstrap configuration properties which require
+ * defaults.
+ */
+const defaultConfiguration = {
+    // If the applications doesn't provide performance data (e.g. via estimateLensPerformance), we'll use 0 to indicate
+    // no performance estimation occurred. This is indicative of typical performance-targeting logic, which often
+    // defaults to the lowest-tier experience in the absense of performance cluster data.
+    lensPerformance: { cluster: 0, benchmarks: [], webglRendererInfo: "unknown" },
+    logger: "noop",
+    logLevel: "info",
+    shouldUseWorker: true,
+};
+/** @internal */
+export const configurationToken = "configuration";
+/** @internal */
+export const createCameraKitConfigurationFactory = (configuration) => {
+    // always leave debug mode warning about overrides in console
+    const overrides = getConfigurationOverrides();
+    if (overrides) {
+        console.warn("Configuration overrides applied", overrides);
+    }
+    return Injectable(configurationToken, () => {
+        // We'll ensure that we handle errors on any Promises passed as config values, otherwise we either must
+        // handle them separately wherever they're used, or rejections would go unhandled.
+        const safeConfig = Object.assign(Object.assign({}, configuration), { lensPerformance: configuration.lensPerformance instanceof Promise
+                ? // Safety: defaultConfiguration.lensPerformance is defined (it's hardcoded above).
+                    configuration.lensPerformance.catch(() => defaultConfiguration.lensPerformance)
+                : configuration.lensPerformance });
+        return Object.assign(Object.assign(Object.assign({}, defaultConfiguration), copyDefinedProperties(safeConfig)), copyDefinedProperties(overrides !== null && overrides !== void 0 ? overrides : {}));
+    });
+};
+//# sourceMappingURL=configuration.js.map

package/lib/configuration.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"configuration.js","sourceRoot":"","sources":["../src/configuration.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,qBAAqB,EAAE,MAAM,gCAAgC,CAAC;AACvE,OAAO,EAAE,yBAAyB,EAAE,MAAM,0BAA0B,CAAC;AACrE,OAAO,EAAE,UAAU,EAAE,MAAM,mCAAmC,CAAC;AAU/D;;;GAGG;AACH,MAAM,oBAAoB,GAAmF;IACzG,mHAAmH;IACnH,6GAA6G;IAC7G,qFAAqF;IACrF,eAAe,EAAE,EAAE,OAAO,EAAE,CAAC,EAAE,UAAU,EAAE,EAAE,EAAE,iBAAiB,EAAE,SAAS,EAAE;IAC7E,MAAM,EAAE,MAAM;IACd,QAAQ,EAAE,MAAM;IAChB,eAAe,EAAE,IAAI;CACxB,CAAC;AAwFF,gBAAgB;AAChB,MAAM,CAAC,MAAM,kBAAkB,GAAG,eAAe,CAAC;AAElD,gBAAgB;AAChB,MAAM,CAAC,MAAM,mCAAmC,GAAG,CAAC,aAA8C,EAAE,EAAE;IAClG,6DAA6D;IAC7D,MAAM,SAAS,GAAG,yBAAyB,EAAE,CAAC;IAC9C,IAAI,SAAS,EAAE;QACX,OAAO,CAAC,IAAI,CAAC,iCAAiC,EAAE,SAAS,CAAC,CAAC;KAC9D;IACD,OAAO,UAAU,CACb,kBAAkB,EAClB,GAA2B,EAAE;QACzB,uGAAuG;QACvG,kFAAkF;QAClF,MAAM,UAAU,mCACT,aAAa,KAChB,eAAe,EACX,aAAa,CAAC,eAAe,YAAY,OAAO;gBAC5C,CAAC,CAAC,kFAAkF;oBAClF,aAAa,CAAC,eAAe,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,oBAAoB,CAAC,eAAgB,CAAC;gBAClF,CAAC,CAAC,aAAa,CAAC,eAAe,GAC1C,CAAC;QACF,qDACO,oBAAoB,GACpB,qBAAqB,CAAC,UAAU,CAAC,GACjC,qBAAqB,CAAC,SAAS,aAAT,SAAS,cAAT,SAAS,GAAI,EAAE,CAAC,EAC3C;IACN,CAAC,CACJ,CAAC;AACN,CAAC,CAAC","sourcesContent":["import { EstimatedLensPerformance } from \"./benchmark/estimateLensPerformanceCluster\";\nimport { copyDefinedProperties } from \"./common/copyDefinedProperties\";\nimport { getConfigurationOverrides } from \"./configurationOverrides\";\nimport { Injectable } from \"./dependency-injection/Injectable\";\nimport { LogLevelName } from \"./logger/logger\";\n\n/**\n * From T, pick the set of properties whose values are optional. Create a new type containing only those properties.\n */\ntype PickOptionals<T> = {\n    [K in keyof T as T[K] extends Exclude<T[K], undefined> ? never : K]: T[K];\n};\n\n/**\n * Defaults are provided for runtime configuration and any optional bootstrap configuration properties which require\n * defaults.\n */\nconst defaultConfiguration: CameraKitRuntimeConfiguration & PickOptionals<CameraKitBootstrapConfiguration> = {\n    // If the applications doesn't provide performance data (e.g. via estimateLensPerformance), we'll use 0 to indicate\n    // no performance estimation occurred. This is indicative of typical performance-targeting logic, which often\n    // defaults to the lowest-tier experience in the absense of performance cluster data.\n    lensPerformance: { cluster: 0, benchmarks: [], webglRendererInfo: \"unknown\" },\n    logger: \"noop\",\n    logLevel: \"info\",\n    shouldUseWorker: true,\n};\n\ninterface CameraKitRuntimeConfiguration {\n    lensPerformance: EstimatedLensPerformance | Promise<EstimatedLensPerformance>;\n    logger: \"noop\" | \"console\";\n    logLevel: LogLevelName;\n    shouldUseWorker: boolean;\n}\n\n/**\n * Configuration which must be provided when calling {@link bootstrapCameraKit}. These values are used to create various\n * CameraKit components.\n *\n * @category Bootstrapping and Configuration\n */\nexport interface CameraKitBootstrapConfiguration {\n    /**\n     * Long-lived token granting your application access to CameraKit APIs. This is found in the SnapKit Dev Portal,\n     * where it's called the API Token.\n     */\n    apiToken: string;\n\n    /**\n     * Determine where to print CameraKit log messages. By default no logs will be printed.\n     *\n     * CameraKit emits log messages to help diagnose and root cause issues that may occur during the development of a\n     * host application. The printing of these can be controlled via the following\n     * options:\n     *  - `noop`: log messages are ignored.\n     *  - `console`: log messages are printed to console.\n     */\n    logger?: \"noop\" | \"console\";\n\n    /**\n     * Log only if a logged entry level is greater than or equal to this level. Here is the order of levels:\n     * error > warn > log = info > debug. Default value is \"info\".\n     */\n    logLevel?: LogLevelName;\n\n    /**\n     * Some lenses may decide to modify their behavior based on the performance of the current environment. If you are\n     * using such lenses, providing an estimation of lens performance may lead to better user experience (especially on\n     * low-performance devices).\n     *\n     * Running the {@link estimateLensPerformance} function will run benchmarks and estimate an appropriate lens\n     * performance cluster (i.e. a performance rating) based on the current environment.\n     *\n     * Lower cluster = worse expected performance capability.\n     *\n     * @example\n     * ```ts\n     * import { bootstrapCameraKit, estimateLensPerformance } from '@snap/camera-kit`\n     *\n     * const cameraKit = await bootstrapCameraKit({\n     *   apiToken: '...',\n     *   lensPerformance: estimateLensPerformance(),\n     * })\n     * ```\n     */\n    lensPerformance?: EstimatedLensPerformance | Promise<EstimatedLensPerformance>;\n\n    /**\n     * In recommended production deployments, the WebAssembly assets required by CameraKit will be downloaded from an\n     * optimized CDN. But sometimes (e.g. during development or within a CI pipeline), it may be necessary to download\n     * these assets from somewhere else.\n     *\n     * This configuration option allows the application to specify URLs to be used for both the WebAssembly and JS glue\n     * file that are used to run and interact with CameraKit's rendering engine.\n     */\n    lensCoreOverrideUrls?: { wasm: string; js: string };\n\n    /**\n     * In recommended production deployments, the WebAssembly assets required by CameraKit will be downloaded from an\n     * optimized CDN. But sometimes during development or within a CI pipeline, it may be necessary to download these\n     * assets from somewhere else. With a provided `wasmEndpointOverride`, asset URLs will be automatically generated\n     * based on this root endpoint.\n     */\n    wasmEndpointOverride?: string;\n}\n\n/**\n * This type represents the result of merging user-supplied config with default config -- as such, it has no nullable\n * fields, making it a more convenient type for other components to use.\n *\n * @internal\n */\nexport type CameraKitConfiguration = CameraKitRuntimeConfiguration & CameraKitBootstrapConfiguration;\n\n/** @internal */\nexport const configurationToken = \"configuration\";\n\n/** @internal */\nexport const createCameraKitConfigurationFactory = (configuration: CameraKitBootstrapConfiguration) => {\n    // always leave debug mode warning about overrides in console\n    const overrides = getConfigurationOverrides();\n    if (overrides) {\n        console.warn(\"Configuration overrides applied\", overrides);\n    }\n    return Injectable(\n        configurationToken,\n        (): CameraKitConfiguration => {\n            // We'll ensure that we handle errors on any Promises passed as config values, otherwise we either must\n            // handle them separately wherever they're used, or rejections would go unhandled.\n            const safeConfig: CameraKitBootstrapConfiguration = {\n                ...configuration,\n                lensPerformance:\n                    configuration.lensPerformance instanceof Promise\n                        ? // Safety: defaultConfiguration.lensPerformance is defined (it's hardcoded above).\n                          configuration.lensPerformance.catch(() => defaultConfiguration.lensPerformance!)\n                        : configuration.lensPerformance,\n            };\n            return {\n                ...defaultConfiguration,\n                ...copyDefinedProperties(safeConfig),\n                ...copyDefinedProperties(overrides ?? {}),\n            };\n        }\n    );\n};\n"]}

package/lib/configurationOverrides.d.ts

@@ -0,0 +1,12 @@
+import { CameraKitBootstrapConfiguration } from "./configuration";
+/**
+ * Configuration overrides that are stored in session storage.
+ */
+declare type StoredOverrides = Pick<CameraKitBootstrapConfiguration, "wasmEndpointOverride" | "logger" | "logLevel">;
+/**
+ * Checks whether there are configuration overrides stored, and if yes, returns them.
+ *
+ * @internal
+ */
+export declare function getConfigurationOverrides(): StoredOverrides | undefined;
+export {};

package/lib/configurationOverrides.js

@@ -0,0 +1,41 @@
+/**
+ * Prefix of override key on window object.
+ */
+const windowFieldPrefix = "__snap_camkit_override__";
+const configPropertiesToOverride = ["wasmEndpointOverride", "logger", "logLevel"];
+configPropertiesToOverride.forEach((fieldToOverride) => {
+    defineWindowField(fieldToOverride);
+});
+function defineWindowField(propertyToOverride) {
+    if (typeof window === "undefined")
+        return;
+    Object.defineProperty(window, `${windowFieldPrefix}${propertyToOverride}`, {
+        get() {
+            var _a;
+            return (_a = getConfigurationOverrides()) === null || _a === void 0 ? void 0 : _a[propertyToOverride];
+        },
+        set(value) {
+            var _a;
+            const storedOverrdies = (_a = getConfigurationOverrides()) !== null && _a !== void 0 ? _a : {};
+            storedOverrdies[propertyToOverride] = value;
+            if (Object.values(storedOverrdies).every((value) => typeof value === "undefined")) {
+                sessionStorage.removeItem(windowFieldPrefix);
+            }
+            else {
+                sessionStorage.setItem(windowFieldPrefix, JSON.stringify(storedOverrdies));
+            }
+        },
+        enumerable: false,
+        configurable: true,
+    });
+}
+/**
+ * Checks whether there are configuration overrides stored, and if yes, returns them.
+ *
+ * @internal
+ */
+export function getConfigurationOverrides() {
+    const overridesString = sessionStorage.getItem(windowFieldPrefix);
+    return overridesString && JSON.parse(overridesString);
+}
+//# sourceMappingURL=configurationOverrides.js.map

package/lib/configurationOverrides.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"configurationOverrides.js","sourceRoot":"","sources":["../src/configurationOverrides.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,MAAM,iBAAiB,GAAG,0BAA0B,CAAC;AAOrD,MAAM,0BAA0B,GAAiC,CAAC,sBAAsB,EAAE,QAAQ,EAAE,UAAU,CAAC,CAAC;AAEhH,0BAA0B,CAAC,OAAO,CAAC,CAAC,eAAe,EAAE,EAAE;IACnD,iBAAiB,CAAC,eAAe,CAAC,CAAC;AACvC,CAAC,CAAC,CAAC;AAEH,SAAS,iBAAiB,CAAC,kBAAyC;IAChE,IAAI,OAAO,MAAM,KAAK,WAAW;QAAE,OAAO;IAE1C,MAAM,CAAC,cAAc,CAAC,MAAM,EAAE,GAAG,iBAAiB,GAAG,kBAAkB,EAAE,EAAE;QACvE,GAAG;;YACC,OAAO,MAAA,yBAAyB,EAAE,0CAAG,kBAAkB,CAAC,CAAC;QAC7D,CAAC;QACD,GAAG,CAAC,KAAU;;YACV,MAAM,eAAe,GAAG,MAAA,yBAAyB,EAAE,mCAAI,EAAE,CAAC;YAC1D,eAAe,CAAC,kBAAkB,CAAC,GAAG,KAAK,CAAC;YAC5C,IAAI,MAAM,CAAC,MAAM,CAAC,eAAe,CAAC,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,OAAO,KAAK,KAAK,WAAW,CAAC,EAAE;gBAC/E,cAAc,CAAC,UAAU,CAAC,iBAAiB,CAAC,CAAC;aAChD;iBAAM;gBACH,cAAc,CAAC,OAAO,CAAC,iBAAiB,EAAE,IAAI,CAAC,SAAS,CAAC,eAAe,CAAC,CAAC,CAAC;aAC9E;QACL,CAAC;QACD,UAAU,EAAE,KAAK;QACjB,YAAY,EAAE,IAAI;KACrB,CAAC,CAAC;AACP,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,yBAAyB;IACrC,MAAM,eAAe,GAAG,cAAc,CAAC,OAAO,CAAC,iBAAiB,CAAC,CAAC;IAClE,OAAO,eAAe,IAAI,IAAI,CAAC,KAAK,CAAC,eAAe,CAAC,CAAC;AAC1D,CAAC","sourcesContent":["import { CameraKitBootstrapConfiguration } from \"./configuration\";\n\n/**\n * Prefix of override key on window object.\n */\nconst windowFieldPrefix = \"__snap_camkit_override__\";\n\n/**\n * Configuration overrides that are stored in session storage.\n */\ntype StoredOverrides = Pick<CameraKitBootstrapConfiguration, \"wasmEndpointOverride\" | \"logger\" | \"logLevel\">;\n\nconst configPropertiesToOverride: Array<keyof StoredOverrides> = [\"wasmEndpointOverride\", \"logger\", \"logLevel\"];\n\nconfigPropertiesToOverride.forEach((fieldToOverride) => {\n    defineWindowField(fieldToOverride);\n});\n\nfunction defineWindowField(propertyToOverride: keyof StoredOverrides) {\n    if (typeof window === \"undefined\") return;\n\n    Object.defineProperty(window, `${windowFieldPrefix}${propertyToOverride}`, {\n        get() {\n            return getConfigurationOverrides()?.[propertyToOverride];\n        },\n        set(value: any) {\n            const storedOverrdies = getConfigurationOverrides() ?? {};\n            storedOverrdies[propertyToOverride] = value;\n            if (Object.values(storedOverrdies).every((value) => typeof value === \"undefined\")) {\n                sessionStorage.removeItem(windowFieldPrefix);\n            } else {\n                sessionStorage.setItem(windowFieldPrefix, JSON.stringify(storedOverrdies));\n            }\n        },\n        enumerable: false,\n        configurable: true,\n    });\n}\n\n/**\n * Checks whether there are configuration overrides stored, and if yes, returns them.\n *\n * @internal\n */\nexport function getConfigurationOverrides(): StoredOverrides | undefined {\n    const overridesString = sessionStorage.getItem(windowFieldPrefix);\n    return overridesString && JSON.parse(overridesString);\n}\n"]}

package/lib/dependency-injection/Container.d.ts

@@ -0,0 +1,177 @@
+import { Memoized } from "../common/memoize";
+import { PartialContainer } from "./PartialContainer";
+import { AddService, InjectableFunction, ValidTokens } from "./types";
+declare type UnsafePartialContainer<Services> = Container<Partial<Services>>;
+declare type MaybeMemoizedFactories<Services> = {
+    [K in keyof Services]: ((c: UnsafePartialContainer<Services>) => Services[K]) | Memoized<(c: UnsafePartialContainer<Services>) => Services[K]>;
+};
+export declare type Factories<Services> = {
+    [K in keyof Services]: Memoized<(c: UnsafePartialContainer<Services>) => Services[K]>;
+};
+export declare const CONTAINER = "$container";
+export declare type ContainerToken = typeof CONTAINER;
+/**
+ * A Container of values, indexed each by a unique token, which can be used throughout CameraKit. This is how CameraKit
+ * implements simple dependency injection.
+ *
+ * Dependency injection is a way to decouple the *use* of a dependency from the *creation* of that dependency. This
+ * improves modularity and re-usability, since components only care about the *interfaces* of dependencies (since that
+ * determines their use) and not about their concrete creation. New implementations of a particular dependency may be
+ * provided without the need to change any of the consumers of that dependency.
+ *
+ * There are a few commonly-used terms used when talking about dependency injection:
+ *
+ *   - Container (or Injector): Maintains a registry of all available Services and understands how to create them.
+ *   - Service: Anything that can be provided by the Container is called a Service – this can be a value of any type.
+ *   - Token: Each Service is associated with a unique name, or Token. In order to obtain a Service from the Container,
+ *     the consumer must provide the Token corresponding to that Service.
+ *   - InjectableFunction: Services are created by InjectableFunctions. When adding a Service to a Container, the
+ *     Service provider gives the Container a InjectableFunction which, when called will return the Service. These
+ *     InjectableFunctions may themselves use other Services, which will be passed to them as arguments.
+ *
+ * Services are, by default, singletons – that is, each call to `get()` a particular Service will return a reference
+ * to the same value. In other words, InjectableFunctions are only invoked once. If multiple instances of a Service are
+ * desired, a new Container can be created using the `copy([Token])` method – passing a Token to this method forces the
+ * new Container to recreate the corresponding Service (the InjectableFunction will be invoked again). We say that the
+ * Service is then "scoped" to the new Container.
+ *
+ *
+ * One common downside of many dependency injection implementations is that the dependency graph formed by the various
+ * Services can only be validated at runtime. That is, if a dependency is missing or a circular dependency is found, the
+ * developer must wait until runtime to discover the error. These errors can often be confusing and hard to debug.
+ *
+ * This implementation eliminates this issue by moving these sorts of errors to compile time. If an unknown dependency
+ * is used in a InjectableFunction, for example, the code simply won't compile.
+ *
+ * To achieve this, we do lose the ability to implicitly define the dependency graph, as is common with many dependency
+ * injection frameworks that employ decorators to define Services and their dependencies. Instead, the dependency graph
+ * must be constructed explicitly, step-by-step, via successive calls to the `provide()` method. This is a suitable
+ * trade-off for CameraKit, as there are a relatively small number of Services.
+ *
+ * Here's a simple example of Container usage:
+ * ```ts
+ * const fooFactory = Injectable('Foo', () => new Foo())
+ * const barFactory = Injectable('Bar', ['Foo'] as const, (foo: Foo) => new Bar(foo))
+ * const container = Container.empy()
+ *   .provide(fooFactory)
+ *   .provide(barFactory)
+ *
+ * const bar: Bar = container.get('Bar')
+ * ```
+ */
+/** @internal */
+export declare class Container<Services = {}> {
+    private readonly factories;
+    constructor(factories: MaybeMemoizedFactories<Services>);
+    /**
+     * Create a new [Container] by providing a [PartialContainer] that has no dependencies.
+     */
+    static provides<Services>(container: PartialContainer<Services, {}> | Container<Services>): Container<Services>;
+    /**
+     * Create a new [Container] by providing a Service that has no dependencies.
+     */
+    static provides<Token extends string, Service>(fn: InjectableFunction<{}, [], Token, Service>): Container<AddService<{}, Token, Service>>;
+    /**
+     * Create a copy of this Container, optionally providing a list of Services which will be scoped to the copy.
+     *
+     * This can be useful, for example, if different parts of an application wish to use the same Service interface, but
+     * do not want to share a reference to same Service instance.
+     *
+     * Say we have a Service which manages a list of Users. Our application wishes to display two lists of Users, which
+     * may be edited independently. In this case it may be desirable to create a Container for each list component, with
+     * the UserList Service scoped to those Containers – that way, each list component gets a unique copy of the
+     * UserList Service that can be edited independently of the other.
+     *
+     * @param scopedServices A list of Tokens identifying Services which will be scoped to the new Container – that is,
+     * if those Services had already been created by the source Container, they will be re-created by their Factory
+     * functions when provided by the new Container.
+     * @returns A new copy of this Container, sharing all of this Container's Services. Services corresponding to any
+     * Tokens passed to this method will be re-created by the new Container (i.e. they become "scoped" to the new
+     * Container).
+     */
+    copy<Tokens extends readonly (keyof Services)[]>(scopedServices?: Tokens): Container<Services>;
+    /**
+     * Gets a reference to this Container.
+     *
+     * @param token The CONTAINER token.
+     * @returns This Container.
+     */
+    get(token: ContainerToken): this;
+    /**
+     * Get a specific Service provided by this Container.
+     *
+     * @param token A unique string corresponding to a Service
+     * @returns A Service corresponding to the given Token.
+     */
+    get<Token extends keyof Services>(token: Token): Services[Token];
+    /**
+     * Run the services in this [PartialContainer]. "Run" simply means that [Container::get] will be called for each
+     * Service, which invokes that Service's factory function, creating the Service.
+     *
+     * This may be useful e.g. if services need to initialize themselves, since generally a Service factory is only
+     * invoked when the Service is needed.
+     *
+     * Note this method cannot be used to add services to a Container. – that is, calling this method does not provide
+     * the services in a new Container.
+     *
+     * @param container Optionally provide a [PartialContainer], which will be used as a filter – the only services
+     * from *this* container that will run are those with a token that is also present in this PartialContainer.
+     * @returns No mutation is done to the Container, it is returned as-is (convenient for chaining).
+     */
+    run<AdditionalServices, Dependencies, FulfilledDependencies extends Dependencies>(this: Container<FulfilledDependencies>, container: PartialContainer<AdditionalServices, Dependencies>): this;
+    /**
+     * Run the given Service. "Run" simply means that [Container::get] will be called for this Service, which invokes
+     * the Service's factory function, creating the Service.
+     *
+     * This may be useful e.g. if services need to initialize themselves, since generally a Service factory is only
+     * invoked when the Service is needed.
+     *
+     * Note this method cannot be used to add services to a Container. – that is, calling this method does not provide
+     * the services in a new Container.
+     *
+     * @param fn Optionally provide an [InjectableFunction], which will be used as a filter – the only services
+     * from *this* container that will run are those with a token that is also present in this PartialContainer.
+     * @returns No mutation is done to the Container, it is returned as-is (convenient for chaining).
+     */
+    run<Token extends string, Tokens extends readonly ValidTokens<Services>[], Service>(fn: InjectableFunction<Services, Tokens, Token, Service>): this;
+    /**
+     * Create a new Container from this Container with additional services from a given [PartialContainer].
+     *
+     * Services in the provided PartialContainer take precedence if there are service token conflicts.
+     *
+     * Services from the provided PartialContainer become scoped to the new Container – that is, if PartialContainer A
+     * is provided to Container X and Container Y, each resultant Container will contain its own copy of the services
+     * from PartialContainer A.
+     *
+     * @param container A [PartialContainer] providing additional services.
+     */
+    provides<AdditionalServices, Dependencies, FulfilledDependencies extends Dependencies>(this: Container<FulfilledDependencies>, container: PartialContainer<AdditionalServices, Dependencies>): Container<Services & AdditionalServices>;
+    /**
+     * Creates a new Container from this Container with additional services from another Container.
+     *
+     * Services in the provided PartialContainer take precedence if there are service token conflicts.
+     *
+     * Services from the provided Container become scoped to both Containers (the one from which they were provided
+     * and the new Container returned by this method) - that is, if Container A is provided to Container B,
+     * they will share the same instances of any Services provided by Container A.
+     * If Container B should re-create new instances of the Services from Container A,
+     * Container A must first be copied before providing it here.
+     *
+     * @param container A [Container] providing additional services.
+     */
+    provides<AdditionalServices>(container: Container<AdditionalServices>): Container<Services & AdditionalServices>;
+    /**
+     * Create a new Container which provides a Service created by the given [InjectableFunction].
+     *
+     * The InjectableFunction contains metadata specifying the Token by which the created Service will be known, as well
+     * as an ordered list of Tokens to be resolved and provided to the InjectableFunction as arguments.
+     *
+     * If any of these required dependencies are missing from the Container (or if there is a mismatch between the types
+     * of those dependencies and the arguments of the InjectableFunction), a compiler error will be raised.
+     *
+     * @param fn A factory function, taking dependencies as arguments, which returns the Service.
+     */
+    provides<Token extends string, Tokens extends readonly ValidTokens<Services>[], Service>(fn: InjectableFunction<Services, Tokens, Token, Service>): Container<AddService<Services, Token, Service>>;
+    private providesService;
+}
+export {};

package/lib/dependency-injection/Container.js

@@ -0,0 +1,160 @@
+import { isMemoized, memoize } from "../common/memoize";
+import { PartialContainer } from "./PartialContainer";
+export const CONTAINER = "$container";
+/**
+ * A Container of values, indexed each by a unique token, which can be used throughout CameraKit. This is how CameraKit
+ * implements simple dependency injection.
+ *
+ * Dependency injection is a way to decouple the *use* of a dependency from the *creation* of that dependency. This
+ * improves modularity and re-usability, since components only care about the *interfaces* of dependencies (since that
+ * determines their use) and not about their concrete creation. New implementations of a particular dependency may be
+ * provided without the need to change any of the consumers of that dependency.
+ *
+ * There are a few commonly-used terms used when talking about dependency injection:
+ *
+ *   - Container (or Injector): Maintains a registry of all available Services and understands how to create them.
+ *   - Service: Anything that can be provided by the Container is called a Service – this can be a value of any type.
+ *   - Token: Each Service is associated with a unique name, or Token. In order to obtain a Service from the Container,
+ *     the consumer must provide the Token corresponding to that Service.
+ *   - InjectableFunction: Services are created by InjectableFunctions. When adding a Service to a Container, the
+ *     Service provider gives the Container a InjectableFunction which, when called will return the Service. These
+ *     InjectableFunctions may themselves use other Services, which will be passed to them as arguments.
+ *
+ * Services are, by default, singletons – that is, each call to `get()` a particular Service will return a reference
+ * to the same value. In other words, InjectableFunctions are only invoked once. If multiple instances of a Service are
+ * desired, a new Container can be created using the `copy([Token])` method – passing a Token to this method forces the
+ * new Container to recreate the corresponding Service (the InjectableFunction will be invoked again). We say that the
+ * Service is then "scoped" to the new Container.
+ *
+ *
+ * One common downside of many dependency injection implementations is that the dependency graph formed by the various
+ * Services can only be validated at runtime. That is, if a dependency is missing or a circular dependency is found, the
+ * developer must wait until runtime to discover the error. These errors can often be confusing and hard to debug.
+ *
+ * This implementation eliminates this issue by moving these sorts of errors to compile time. If an unknown dependency
+ * is used in a InjectableFunction, for example, the code simply won't compile.
+ *
+ * To achieve this, we do lose the ability to implicitly define the dependency graph, as is common with many dependency
+ * injection frameworks that employ decorators to define Services and their dependencies. Instead, the dependency graph
+ * must be constructed explicitly, step-by-step, via successive calls to the `provide()` method. This is a suitable
+ * trade-off for CameraKit, as there are a relatively small number of Services.
+ *
+ * Here's a simple example of Container usage:
+ * ```ts
+ * const fooFactory = Injectable('Foo', () => new Foo())
+ * const barFactory = Injectable('Bar', ['Foo'] as const, (foo: Foo) => new Bar(foo))
+ * const container = Container.empy()
+ *   .provide(fooFactory)
+ *   .provide(barFactory)
+ *
+ * const bar: Bar = container.get('Bar')
+ * ```
+ */
+/** @internal */
+export class Container {
+    constructor(factories) {
+        this.factories = {};
+        for (const k in factories) {
+            const fn = factories[k];
+            if (isMemoized(fn))
+                this.factories[k] = fn;
+            else
+                this.factories[k] = memoize(fn);
+        }
+    }
+    static provides(fnOrContainer) {
+        // Although the `provides` method has overloads that match both members of the union type separately, it does
+        // not match the union type itself, so the compiler forces us to branch and handle each type within the union
+        // separately. (Maybe in the future the compiler will decide to infer this, but for now this is necessary.)
+        if (fnOrContainer instanceof PartialContainer)
+            return new Container({}).provides(fnOrContainer);
+        if (fnOrContainer instanceof Container)
+            return new Container({}).provides(fnOrContainer);
+        return new Container({}).provides(fnOrContainer);
+    }
+    /**
+     * Create a copy of this Container, optionally providing a list of Services which will be scoped to the copy.
+     *
+     * This can be useful, for example, if different parts of an application wish to use the same Service interface, but
+     * do not want to share a reference to same Service instance.
+     *
+     * Say we have a Service which manages a list of Users. Our application wishes to display two lists of Users, which
+     * may be edited independently. In this case it may be desirable to create a Container for each list component, with
+     * the UserList Service scoped to those Containers – that way, each list component gets a unique copy of the
+     * UserList Service that can be edited independently of the other.
+     *
+     * @param scopedServices A list of Tokens identifying Services which will be scoped to the new Container – that is,
+     * if those Services had already been created by the source Container, they will be re-created by their Factory
+     * functions when provided by the new Container.
+     * @returns A new copy of this Container, sharing all of this Container's Services. Services corresponding to any
+     * Tokens passed to this method will be re-created by the new Container (i.e. they become "scoped" to the new
+     * Container).
+     */
+    copy(scopedServices) {
+        const factories = Object.assign({}, this.factories);
+        // We "un-memoize" scoped Service InjectableFunctions so they will create a new copy of their Service when
+        // provided by the new Container – we re-memoize them so the new Container will itself only create one Service
+        // instance.
+        (scopedServices || []).forEach((token) => {
+            factories[token] = this.factories[token].delegate;
+        });
+        return new Container(factories);
+    }
+    get(token) {
+        if (token === CONTAINER)
+            return this;
+        const factory = this.factories[token];
+        if (!factory) {
+            throw new Error(`[Container::get] Could not find Service for Token "${token}". This should've caused a ` +
+                "compile-time error. If the Token is 'undefined', check all your calls to the Injectable " +
+                "function. Make sure you define dependencies using string literals or string constants that are " +
+                "definitely initialized before the call to Injectable.");
+        }
+        return factory(this);
+    }
+    run(fnOrContainer) {
+        if (fnOrContainer instanceof PartialContainer) {
+            const runnableContainer = this.provides(fnOrContainer);
+            for (const token of fnOrContainer.getTokens()) {
+                runnableContainer.get(token);
+            }
+        }
+        else {
+            this.provides(fnOrContainer).get(fnOrContainer.token);
+        }
+        return this;
+    }
+    provides(fnOrContainer) {
+        if (fnOrContainer instanceof PartialContainer || fnOrContainer instanceof Container) {
+            const factories = fnOrContainer instanceof PartialContainer ? fnOrContainer.getFactories(this) : fnOrContainer.factories;
+            // Safety: `this.factories` and `factories` are both properly type checked, so merging them produces
+            // a Factories object with keys from both Services and AdditionalServices. The compiler is unable to
+            // infer that Factories<A> & Factories<B> == Factories<A & B>, so the cast is required.
+            return new Container(Object.assign(Object.assign({}, this.factories), factories));
+        }
+        return this.providesService(fnOrContainer);
+    }
+    providesService(fn) {
+        const token = fn.token;
+        const dependencies = fn.dependencies;
+        const factory = memoize((container) => {
+            return fn(...dependencies.map((t) => {
+                // To support overwriting an already-existing service with a new implementation, it should be
+                // possibleto do `provide(A, [A], a => createNewServiceFromOld(a))` – that is, inject a dependency
+                // with the same token as this service's token.
+                //
+                // To avoid a circular dependency (in which the factory for service A depends on itself), we always
+                // use the service defined in the *parent* container (i.e. this) when injecting a dependency with
+                // the same token as the service we're providing. If we did not do this, calling `container.get(t)`
+                // would result in an infinite loop.
+                return t === token ? this.get(t) : container.get(t);
+            }));
+        });
+        // Safety: `token` and `factory` are property type checked, so extending `this.factories` produces a
+        // MaybeMemoizedFactories object with the expected set of services – but when using the spread operation to
+        // merge two objects, the compiler widens the Token type to string. So we must re-narrow via casting.
+        const factories = Object.assign(Object.assign({}, this.factories), { [token]: factory });
+        return new Container(factories);
+    }
+}
+//# sourceMappingURL=Container.js.map

package/lib/dependency-injection/Container.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Container.js","sourceRoot":"","sources":["../../src/dependency-injection/Container.ts"],"names":[],"mappings":"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","sourcesContent":["import { isMemoized, memoize, Memoized } from \"../common/memoize\";\nimport { PartialContainer } from \"./PartialContainer\";\nimport { AddService, InjectableFunction, ValidTokens } from \"./types\";\n\n// This is un-safe. In practice, Containers should always be created by calling `Container::provides` on some other\n// Container (except for some \"root\" Container which is instantiated with no Services) – `Container::provides\" is safely\n// type-checked, so this doesn't introduce much risk. But a more accurate solution would be for the `Factories` and\n// `MaybeMemoizedFactories` types to keep track of which specific Services must be present in the Container\n// corresponding to each Service. But this is much more complex to implement.\ntype UnsafePartialContainer<Services> = Container<Partial<Services>>;\n\ntype MaybeMemoizedFactories<Services> = {\n    [K in keyof Services]:\n        | ((c: UnsafePartialContainer<Services>) => Services[K])\n        | Memoized<(c: UnsafePartialContainer<Services>) => Services[K]>;\n};\n\nexport type Factories<Services> = {\n    [K in keyof Services]: Memoized<(c: UnsafePartialContainer<Services>) => Services[K]>;\n};\n\nexport const CONTAINER = \"$container\";\nexport type ContainerToken = typeof CONTAINER;\n\n/**\n * A Container of values, indexed each by a unique token, which can be used throughout CameraKit. This is how CameraKit\n * implements simple dependency injection.\n *\n * Dependency injection is a way to decouple the *use* of a dependency from the *creation* of that dependency. This\n * improves modularity and re-usability, since components only care about the *interfaces* of dependencies (since that\n * determines their use) and not about their concrete creation. New implementations of a particular dependency may be\n * provided without the need to change any of the consumers of that dependency.\n *\n * There are a few commonly-used terms used when talking about dependency injection:\n *\n *   - Container (or Injector): Maintains a registry of all available Services and understands how to create them.\n *   - Service: Anything that can be provided by the Container is called a Service – this can be a value of any type.\n *   - Token: Each Service is associated with a unique name, or Token. In order to obtain a Service from the Container,\n *     the consumer must provide the Token corresponding to that Service.\n *   - InjectableFunction: Services are created by InjectableFunctions. When adding a Service to a Container, the\n *     Service provider gives the Container a InjectableFunction which, when called will return the Service. These\n *     InjectableFunctions may themselves use other Services, which will be passed to them as arguments.\n *\n * Services are, by default, singletons – that is, each call to `get()` a particular Service will return a reference\n * to the same value. In other words, InjectableFunctions are only invoked once. If multiple instances of a Service are\n * desired, a new Container can be created using the `copy([Token])` method – passing a Token to this method forces the\n * new Container to recreate the corresponding Service (the InjectableFunction will be invoked again). We say that the\n * Service is then \"scoped\" to the new Container.\n *\n *\n * One common downside of many dependency injection implementations is that the dependency graph formed by the various\n * Services can only be validated at runtime. That is, if a dependency is missing or a circular dependency is found, the\n * developer must wait until runtime to discover the error. These errors can often be confusing and hard to debug.\n *\n * This implementation eliminates this issue by moving these sorts of errors to compile time. If an unknown dependency\n * is used in a InjectableFunction, for example, the code simply won't compile.\n *\n * To achieve this, we do lose the ability to implicitly define the dependency graph, as is common with many dependency\n * injection frameworks that employ decorators to define Services and their dependencies. Instead, the dependency graph\n * must be constructed explicitly, step-by-step, via successive calls to the `provide()` method. This is a suitable\n * trade-off for CameraKit, as there are a relatively small number of Services.\n *\n * Here's a simple example of Container usage:\n * ```ts\n * const fooFactory = Injectable('Foo', () => new Foo())\n * const barFactory = Injectable('Bar', ['Foo'] as const, (foo: Foo) => new Bar(foo))\n * const container = Container.empy()\n *   .provide(fooFactory)\n *   .provide(barFactory)\n *\n * const bar: Bar = container.get('Bar')\n * ```\n */\n/** @internal */\nexport class Container<Services = {}> {\n    private readonly factories: Factories<Services>;\n\n    constructor(factories: MaybeMemoizedFactories<Services>) {\n        this.factories = {} as Factories<Services>;\n        for (const k in factories) {\n            const fn = factories[k];\n            if (isMemoized(fn)) this.factories[k] = fn;\n            else this.factories[k] = memoize(fn);\n        }\n    }\n\n    /**\n     * Create a new [Container] by providing a [PartialContainer] that has no dependencies.\n     */\n    static provides<Services>(container: PartialContainer<Services, {}> | Container<Services>): Container<Services>;\n\n    /**\n     * Create a new [Container] by providing a Service that has no dependencies.\n     */\n    static provides<Token extends string, Service>(\n        fn: InjectableFunction<{}, [], Token, Service>\n    ): Container<AddService<{}, Token, Service>>;\n\n    static provides(\n        fnOrContainer: InjectableFunction<{}, [], string, any> | PartialContainer<any, {}> | Container<any>\n    ): Container<any> {\n        // Although the `provides` method has overloads that match both members of the union type separately, it does\n        // not match the union type itself, so the compiler forces us to branch and handle each type within the union\n        // separately. (Maybe in the future the compiler will decide to infer this, but for now this is necessary.)\n        if (fnOrContainer instanceof PartialContainer) return new Container({}).provides(fnOrContainer);\n        if (fnOrContainer instanceof Container) return new Container({}).provides(fnOrContainer);\n        return new Container({}).provides(fnOrContainer);\n    }\n\n    /**\n     * Create a copy of this Container, optionally providing a list of Services which will be scoped to the copy.\n     *\n     * This can be useful, for example, if different parts of an application wish to use the same Service interface, but\n     * do not want to share a reference to same Service instance.\n     *\n     * Say we have a Service which manages a list of Users. Our application wishes to display two lists of Users, which\n     * may be edited independently. In this case it may be desirable to create a Container for each list component, with\n     * the UserList Service scoped to those Containers – that way, each list component gets a unique copy of the\n     * UserList Service that can be edited independently of the other.\n     *\n     * @param scopedServices A list of Tokens identifying Services which will be scoped to the new Container – that is,\n     * if those Services had already been created by the source Container, they will be re-created by their Factory\n     * functions when provided by the new Container.\n     * @returns A new copy of this Container, sharing all of this Container's Services. Services corresponding to any\n     * Tokens passed to this method will be re-created by the new Container (i.e. they become \"scoped\" to the new\n     * Container).\n     */\n    copy<Tokens extends readonly (keyof Services)[]>(scopedServices?: Tokens): Container<Services> {\n        const factories: MaybeMemoizedFactories<Services> = { ...this.factories };\n\n        // We \"un-memoize\" scoped Service InjectableFunctions so they will create a new copy of their Service when\n        // provided by the new Container – we re-memoize them so the new Container will itself only create one Service\n        // instance.\n        (scopedServices || []).forEach((token: keyof Services) => {\n            factories[token] = this.factories[token].delegate;\n        });\n        return new Container(factories);\n    }\n\n    /**\n     * Gets a reference to this Container.\n     *\n     * @param token The CONTAINER token.\n     * @returns This Container.\n     */\n    get(token: ContainerToken): this;\n\n    /**\n     * Get a specific Service provided by this Container.\n     *\n     * @param token A unique string corresponding to a Service\n     * @returns A Service corresponding to the given Token.\n     */\n    get<Token extends keyof Services>(token: Token): Services[Token];\n\n    get(token: string): this | Services[keyof Services] {\n        if (token === CONTAINER) return this;\n        const factory = this.factories[token];\n        if (!factory) {\n            throw new Error(\n                `[Container::get] Could not find Service for Token \"${token}\". This should've caused a ` +\n                    \"compile-time error. If the Token is 'undefined', check all your calls to the Injectable \" +\n                    \"function. Make sure you define dependencies using string literals or string constants that are \" +\n                    \"definitely initialized before the call to Injectable.\"\n            );\n        }\n        return factory(this);\n    }\n\n    /**\n     * Run the services in this [PartialContainer]. \"Run\" simply means that [Container::get] will be called for each\n     * Service, which invokes that Service's factory function, creating the Service.\n     *\n     * This may be useful e.g. if services need to initialize themselves, since generally a Service factory is only\n     * invoked when the Service is needed.\n     *\n     * Note this method cannot be used to add services to a Container. – that is, calling this method does not provide\n     * the services in a new Container.\n     *\n     * @param container Optionally provide a [PartialContainer], which will be used as a filter – the only services\n     * from *this* container that will run are those with a token that is also present in this PartialContainer.\n     * @returns No mutation is done to the Container, it is returned as-is (convenient for chaining).\n     */\n    run<AdditionalServices, Dependencies, FulfilledDependencies extends Dependencies>(\n        // FullfilledDependencies is assignable to Dependencies -- by specifying Container<FulfilledDependencies> as the\n        // `this` type, we ensure this Container can provide all the Dependencies required by the PartialContainer.\n        this: Container<FulfilledDependencies>,\n        container: PartialContainer<AdditionalServices, Dependencies>\n    ): this;\n\n    /**\n     * Run the given Service. \"Run\" simply means that [Container::get] will be called for this Service, which invokes\n     * the Service's factory function, creating the Service.\n     *\n     * This may be useful e.g. if services need to initialize themselves, since generally a Service factory is only\n     * invoked when the Service is needed.\n     *\n     * Note this method cannot be used to add services to a Container. – that is, calling this method does not provide\n     * the services in a new Container.\n     *\n     * @param fn Optionally provide an [InjectableFunction], which will be used as a filter – the only services\n     * from *this* container that will run are those with a token that is also present in this PartialContainer.\n     * @returns No mutation is done to the Container, it is returned as-is (convenient for chaining).\n     */\n    run<Token extends string, Tokens extends readonly ValidTokens<Services>[], Service>(\n        fn: InjectableFunction<Services, Tokens, Token, Service>\n    ): this;\n\n    run<Token extends string, Tokens extends readonly ValidTokens<Services>[], Service, AdditionalServices>(\n        fnOrContainer:\n            | InjectableFunction<Services, Tokens, Token, Service>\n            | PartialContainer<AdditionalServices, Services>\n    ): this {\n        if (fnOrContainer instanceof PartialContainer) {\n            const runnableContainer = this.provides(fnOrContainer);\n            for (const token of fnOrContainer.getTokens()) {\n                runnableContainer.get(token);\n            }\n        } else {\n            this.provides(fnOrContainer).get(fnOrContainer.token);\n        }\n        return this;\n    }\n\n    /**\n     * Create a new Container from this Container with additional services from a given [PartialContainer].\n     *\n     * Services in the provided PartialContainer take precedence if there are service token conflicts.\n     *\n     * Services from the provided PartialContainer become scoped to the new Container – that is, if PartialContainer A\n     * is provided to Container X and Container Y, each resultant Container will contain its own copy of the services\n     * from PartialContainer A.\n     *\n     * @param container A [PartialContainer] providing additional services.\n     */\n    provides<AdditionalServices, Dependencies, FulfilledDependencies extends Dependencies>(\n        // FullfilledDependencies is assignable to Dependencies -- by specifying Container<FulfilledDependencies> as the\n        // `this` type, we ensure this Container can provide all the Dependencies required by the PartialContainer.\n        this: Container<FulfilledDependencies>,\n        container: PartialContainer<AdditionalServices, Dependencies>\n    ): Container<Services & AdditionalServices>;\n\n    /**\n     * Creates a new Container from this Container with additional services from another Container.\n     *\n     * Services in the provided PartialContainer take precedence if there are service token conflicts.\n     *\n     * Services from the provided Container become scoped to both Containers (the one from which they were provided\n     * and the new Container returned by this method) - that is, if Container A is provided to Container B,\n     * they will share the same instances of any Services provided by Container A.\n     * If Container B should re-create new instances of the Services from Container A,\n     * Container A must first be copied before providing it here.\n     *\n     * @param container A [Container] providing additional services.\n     */\n    provides<AdditionalServices>(container: Container<AdditionalServices>): Container<Services & AdditionalServices>;\n\n    /**\n     * Create a new Container which provides a Service created by the given [InjectableFunction].\n     *\n     * The InjectableFunction contains metadata specifying the Token by which the created Service will be known, as well\n     * as an ordered list of Tokens to be resolved and provided to the InjectableFunction as arguments.\n     *\n     * If any of these required dependencies are missing from the Container (or if there is a mismatch between the types\n     * of those dependencies and the arguments of the InjectableFunction), a compiler error will be raised.\n     *\n     * @param fn A factory function, taking dependencies as arguments, which returns the Service.\n     */\n    provides<Token extends string, Tokens extends readonly ValidTokens<Services>[], Service>(\n        fn: InjectableFunction<Services, Tokens, Token, Service>\n    ): Container<AddService<Services, Token, Service>>;\n\n    provides<Token extends string, Tokens extends readonly ValidTokens<Services>[], Service, AdditionalServices>(\n        fnOrContainer:\n            | InjectableFunction<Services, Tokens, Token, Service>\n            | PartialContainer<AdditionalServices, Services>\n            | Container<AdditionalServices>\n    ): Container<any> {\n        if (fnOrContainer instanceof PartialContainer || fnOrContainer instanceof Container) {\n            const factories =\n                fnOrContainer instanceof PartialContainer ? fnOrContainer.getFactories(this) : fnOrContainer.factories;\n            // Safety: `this.factories` and `factories` are both properly type checked, so merging them produces\n            // a Factories object with keys from both Services and AdditionalServices. The compiler is unable to\n            // infer that Factories<A> & Factories<B> == Factories<A & B>, so the cast is required.\n            return new Container(({\n                ...this.factories,\n                ...factories,\n            } as unknown) as MaybeMemoizedFactories<Services & AdditionalServices>);\n        }\n        return this.providesService(fnOrContainer);\n    }\n\n    private providesService<Token extends string, Tokens extends readonly ValidTokens<Services>[], Service>(\n        fn: InjectableFunction<Services, Tokens, Token, Service>\n    ): Container<AddService<Services, Token, Service>> {\n        const token = fn.token;\n        const dependencies: readonly any[] = fn.dependencies;\n\n        const factory = memoize((container: Container<Services>) => {\n            return fn(\n                ...(dependencies.map((t) => {\n                    // To support overwriting an already-existing service with a new implementation, it should be\n                    // possibleto do `provide(A, [A], a => createNewServiceFromOld(a))` – that is, inject a dependency\n                    // with the same token as this service's token.\n                    //\n                    // To avoid a circular dependency (in which the factory for service A depends on itself), we always\n                    // use the service defined in the *parent* container (i.e. this) when injecting a dependency with\n                    // the same token as the service we're providing. If we did not do this, calling `container.get(t)`\n                    // would result in an infinite loop.\n                    return t === token ? this.get(t) : container.get(t);\n                }) as any)\n            );\n        });\n\n        // Safety: `token` and `factory` are property type checked, so extending `this.factories` produces a\n        // MaybeMemoizedFactories object with the expected set of services – but when using the spread operation to\n        // merge two objects, the compiler widens the Token type to string. So we must re-narrow via casting.\n        const factories = { ...this.factories, [token]: factory };\n        return new Container((factories as unknown) as MaybeMemoizedFactories<AddService<Services, Token, Service>>);\n    }\n}\n"]}

package/lib/dependency-injection/Injectable.d.ts

@@ -0,0 +1,39 @@
+import { InjectableFunction, ServicesFromTokenizedParams } from "./types";
+/**
+ * Create an Injectable function with no dependencies (i.e. arguments).
+ *
+ * Ex:
+ * ```ts
+ * const createMyService = Factory(
+ *   'MyService',
+ *   () => { ... },
+ * )
+ * ```
+ *
+ * @param token A unique string Token which will correspond to the created Service.
+ * @param fn A function with no arguments which returns the Service.
+ */
+export declare function Injectable<Token extends string, Service>(token: Token, fn: () => Service): InjectableFunction<any, [], Token, Service>;
+/**
+ * Create an Injectable function with dependencies (i.e. arguments).
+ *
+ * **Note:** the list of dependencies must be readonly – that is, a literal tuple marked `as const`. This tuple must
+ * contain only string literals or string consts.
+ *
+ * Ex:
+ * ```ts
+ * const DependencyB = 'DependencyB'
+ * const createMyService = Factory(
+ *   'MyService',
+ *   ['DependencyA', DependencyB] as const,
+ *   (a: A, b: B) => { ... },
+ * )
+ * ```
+ *
+ * @param token A unique string Token which will correspond to the created Service.
+ * @param dependencies A *readonly* list of Tokens corresponding to dependencies (i.e. arguments to the Factory), which
+ * will be resolved by the Container to which this Factory is provided.
+ * @param fn A function with arguments matching in type and length to the given list of dependencies. When called, it
+ * must return the Service.
+ */
+export declare function Injectable<Token extends string, Tokens extends readonly string[], Params extends readonly any[], Service>(token: Token, dependencies: Tokens, fn: (...args: Tokens["length"] extends Params["length"] ? Params : void[]) => Service): Tokens["length"] extends Params["length"] ? InjectableFunction<ServicesFromTokenizedParams<Tokens, Params>, Tokens, Token, Service> : never;

package/lib/dependency-injection/Injectable.js

@@ -0,0 +1,18 @@
+export function Injectable(token, dependenciesOrFn, maybeFn) {
+    const dependencies = Array.isArray(dependenciesOrFn) ? dependenciesOrFn : [];
+    const fn = typeof dependenciesOrFn === "function" ? dependenciesOrFn : maybeFn;
+    if (!fn) {
+        throw new TypeError("[Factory] Received invalid arguments. The factory function must be either the second " +
+            "or third argument.");
+    }
+    if (fn.length !== dependencies.length) {
+        throw new TypeError("[Factory] Function arity does not match the number of dependencies. Function has arity " +
+            `${fn.length}, but ${dependencies.length} dependencies were specified.` +
+            `\nDependencies: ${JSON.stringify(dependencies)}`);
+    }
+    const factory = (...args) => fn(...args);
+    factory.token = token;
+    factory.dependencies = dependencies;
+    return factory;
+}
+//# sourceMappingURL=Injectable.js.map

package/lib/dependency-injection/Injectable.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Injectable.js","sourceRoot":"","sources":["../../src/dependency-injection/Injectable.ts"],"names":[],"mappings":"AA2DA,MAAM,UAAU,UAAU,CACtB,KAAa,EACb,gBAAkD,EAClD,OAAiC;IAEjC,MAAM,YAAY,GAAa,KAAK,CAAC,OAAO,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,gBAAgB,CAAC,CAAC,CAAC,EAAE,CAAC;IACvF,MAAM,EAAE,GAAG,OAAO,gBAAgB,KAAK,UAAU,CAAC,CAAC,CAAC,gBAAgB,CAAC,CAAC,CAAC,OAAO,CAAC;IAE/E,IAAI,CAAC,EAAE,EAAE;QACL,MAAM,IAAI,SAAS,CACf,uFAAuF;YACnF,oBAAoB,CAC3B,CAAC;KACL;IAED,IAAI,EAAE,CAAC,MAAM,KAAK,YAAY,CAAC,MAAM,EAAE;QACnC,MAAM,IAAI,SAAS,CACf,yFAAyF;YACrF,GAAG,EAAE,CAAC,MAAM,SAAS,YAAY,CAAC,MAAM,+BAA+B;YACvE,mBAAmB,IAAI,CAAC,SAAS,CAAC,YAAY,CAAC,EAAE,CACxD,CAAC;KACL;IAED,MAAM,OAAO,GAAG,CAAC,GAAG,IAAW,EAAE,EAAE,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC;IAChD,OAAO,CAAC,KAAK,GAAG,KAAK,CAAC;IACtB,OAAO,CAAC,YAAY,GAAG,YAAY,CAAC;IACpC,OAAO,OAAO,CAAC;AACnB,CAAC","sourcesContent":["import { InjectableFunction, ServicesFromTokenizedParams } from \"./types\";\n\n/**\n * Create an Injectable function with no dependencies (i.e. arguments).\n *\n * Ex:\n * ```ts\n * const createMyService = Factory(\n *   'MyService',\n *   () => { ... },\n * )\n * ```\n *\n * @param token A unique string Token which will correspond to the created Service.\n * @param fn A function with no arguments which returns the Service.\n */\nexport function Injectable<Token extends string, Service>(\n    token: Token,\n    fn: () => Service\n): InjectableFunction<any, [], Token, Service>;\n\n/**\n * Create an Injectable function with dependencies (i.e. arguments).\n *\n * **Note:** the list of dependencies must be readonly – that is, a literal tuple marked `as const`. This tuple must\n * contain only string literals or string consts.\n *\n * Ex:\n * ```ts\n * const DependencyB = 'DependencyB'\n * const createMyService = Factory(\n *   'MyService',\n *   ['DependencyA', DependencyB] as const,\n *   (a: A, b: B) => { ... },\n * )\n * ```\n *\n * @param token A unique string Token which will correspond to the created Service.\n * @param dependencies A *readonly* list of Tokens corresponding to dependencies (i.e. arguments to the Factory), which\n * will be resolved by the Container to which this Factory is provided.\n * @param fn A function with arguments matching in type and length to the given list of dependencies. When called, it\n * must return the Service.\n */\nexport function Injectable<\n    Token extends string,\n    Tokens extends readonly string[],\n    Params extends readonly any[],\n    Service\n>(\n    token: Token,\n    dependencies: Tokens,\n    // The function arity (number of arguments) must match the number of dependencies specified – if they don't, we'll\n    // force a compiler error by saying the arguments should be `void[]`. We'll also throw at runtime, so the return\n    // type will be `never`.\n    fn: (...args: Tokens[\"length\"] extends Params[\"length\"] ? Params : void[]) => Service\n): Tokens[\"length\"] extends Params[\"length\"]\n    ? InjectableFunction<ServicesFromTokenizedParams<Tokens, Params>, Tokens, Token, Service>\n    : never;\n\nexport function Injectable(\n    token: string,\n    dependenciesOrFn?: readonly string[] | (() => any),\n    maybeFn?: (...args: any[]) => any\n): InjectableFunction<any, readonly string[], string, any> {\n    const dependencies: string[] = Array.isArray(dependenciesOrFn) ? dependenciesOrFn : [];\n    const fn = typeof dependenciesOrFn === \"function\" ? dependenciesOrFn : maybeFn;\n\n    if (!fn) {\n        throw new TypeError(\n            \"[Factory] Received invalid arguments. The factory function must be either the second \" +\n                \"or third argument.\"\n        );\n    }\n\n    if (fn.length !== dependencies.length) {\n        throw new TypeError(\n            \"[Factory] Function arity does not match the number of dependencies. Function has arity \" +\n                `${fn.length}, but ${dependencies.length} dependencies were specified.` +\n                `\\nDependencies: ${JSON.stringify(dependencies)}`\n        );\n    }\n\n    const factory = (...args: any[]) => fn(...args);\n    factory.token = token;\n    factory.dependencies = dependencies;\n    return factory;\n}\n"]}