@amazon/vinyl-di 1.0.0

package/dist/index.cjs

@@ -0,0 +1,129 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  CyclicDependencyError: () => CyclicDependencyError,
+  ExternalDependency: () => ExternalDependency,
+  createContainer: () => createContainer,
+  externalDependencies: () => externalDependencies,
+  validateFactories: () => validateFactories
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/di/validation.ts
+function validateFactories(dependencyMap) {
+  return dependencyMap;
+}
+
+// src/di/di.ts
+var import_vinyl_util2 = require("@amazon/vinyl-util");
+var import_vinyl_util3 = require("@amazon/vinyl-util");
+
+// src/di/CyclicDependencyError.ts
+var import_vinyl_util = require("@amazon/vinyl-util");
+var CyclicDependencyError = class _CyclicDependencyError extends import_vinyl_util.IllegalArgumentError {
+  get [Symbol.toStringTag]() {
+    return "CyclicDependencyError";
+  }
+  constructor(message) {
+    super(message);
+    Object.setPrototypeOf(this, _CyclicDependencyError.prototype);
+  }
+};
+
+// src/di/di.ts
+var ExternalDependency = /* @__PURE__ */ Symbol("externalDependency");
+function externalDependencies(deps) {
+  const out = {};
+  for (const key of Object.keys(deps)) {
+    const provider = () => deps[key];
+    provider[ExternalDependency] = true;
+    out[key] = provider;
+  }
+  return out;
+}
+function createContainer(factories) {
+  let disposed = false;
+  const disposables = [];
+  const o = {};
+  let creationCount = 0;
+  Object.defineProperty(o, "__enumerableGuard", {
+    get() {
+      if (creationCount !== 0) {
+        throw new import_vinyl_util2.IllegalStateError(
+          "Enumeration is not supported within factories."
+        );
+      }
+    },
+    configurable: false,
+    enumerable: true
+  });
+  for (const key in factories) {
+    if (key === "__enumerableGuard") continue;
+    let creating = false;
+    let created = false;
+    let value = null;
+    Object.defineProperty(o, key, {
+      get() {
+        if (disposed) throw new import_vinyl_util3.DisposedError();
+        if (!created) {
+          if (creating)
+            throw new CyclicDependencyError(
+              `The dependency with key '${key}' is cyclical. Check to ensure dependencies are not used in a property iterator.`
+            );
+          creationCount++;
+          creating = true;
+          const provider = factories[key];
+          const index = disposables.length;
+          const add = (disposableOrUnsub) => {
+            if (disposableOrUnsub) {
+              const disposable = (0, import_vinyl_util3.isDisposable)(disposableOrUnsub) ? disposableOrUnsub : (0, import_vinyl_util3.toDisposable)(disposableOrUnsub);
+              disposables.splice(index, 0, disposable);
+            }
+            return disposableOrUnsub;
+          };
+          value = provider(o, add);
+          if ((0, import_vinyl_util3.isPromiseLike)(value)) {
+            value = (0, import_vinyl_util3.toDisposablePromise)(value);
+          }
+          if ((0, import_vinyl_util3.isDisposable)(value) && !(ExternalDependency in provider))
+            disposables.splice(index, 0, value);
+          creating = false;
+          created = true;
+          creationCount--;
+        }
+        return value;
+      },
+      configurable: false,
+      enumerable: true
+    });
+  }
+  return {
+    dependencies: o,
+    dispose() {
+      if (disposed) throw new import_vinyl_util3.DisposedError();
+      (0, import_vinyl_util3.disposeAll)(disposables);
+      disposed = true;
+      disposables.length = 0;
+    }
+  };
+}
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/index.ts", "../src/di/validation.ts", "../src/di/di.ts", "../src/di/CyclicDependencyError.ts"],
+  "sourcesContent": ["/** Auto-generated from build scripts */\nexport * from './di/validation'\nexport * from './di/di'\nexport * from './di/CyclicDependencyError'\n", "/*\n * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.\n * SPDX-License-Identifier: Apache-2.0\n */\n\n/*\n * Provides validation utilities for type-safe dependency factories.\n */\n\nimport type { Factories, Factory } from './di'\nimport type { AddDisposable, IsNever, Merge } from '@amazon/vinyl-util'\n\n/**\n * A compile-time validation error that a dependency may not cycle back upon itself.\n */\nexport type NeverCyclicDependency<\n    T extends PropertyKey,\n    U extends PropertyKey[],\n> = [never, T, 'cyclic dependency', U]\n\n/**\n * A compile-time validation error that a provided dependency must be assignable\n * to factories for which it is an input.\n */\nexport type NeverWrongReturnType<Expected, Actual> = [\n    never,\n    'expected provided dependency is not a subtype of what is used. Expected subtype of:',\n    Expected,\n    'Actual: ',\n    Actual,\n]\n\n/**\n * A compile-time validation error that a dependency must be a supertype of the actual type\n * provided.\n */\nexport type NeverWrongDependencyType<Expected, Actual> = [\n    never,\n    'expected dependency is not a supertype of what is provided. Expected supertype of:',\n    Expected,\n    'Actual: ',\n    Actual,\n]\n\n/**\n * A factory expects a dependency that isn't defined.\n */\nexport type NeverMissingDependency<K> = [\n    never,\n    'provider is missing a dependency for key:',\n    K,\n]\n\n/**\n * A factory expects a non-void return type.\n */\nexport type NeverNoVoidReturnType = [never, 'void return type not allowed']\n\n/**\n * A factory must be a function.\n */\nexport type NeverInvalidFactoryType = [never, 'not a valid factory']\n\n/**\n * Dependencies must be an object.\n */\nexport type NeverInvalidDependenciesType = [never, 'not valid dependency type']\n\n/**\n * A compile-time validation error that dependency factories take an input of type object.\n */\nexport type NeverWrongDependenciesInput = [\n    never,\n    'expected dependency factory to have an object argument',\n]\n\n/**\n * Provides a compile-time assertion that the given dependency map provides valid factories.\n */\nexport function validateFactories<Dm extends Factories>(\n    dependencyMap: ValidFactories<Dm>\n): NoInfer<Dm> {\n    return dependencyMap as Dm\n}\n\n/**\n * Validates that the type provided is a valid dependency map.\n *\n * This will guarantee that:\n * - All dependency factories exist with the correct signature.\n * - There are no cyclic dependencies.\n * - The factory's dependencies are provided.\n *\n * @see ValidFactory\n */\nexport type ValidFactories<Dm> = {\n    readonly [K in keyof Dm]: ValidFactory<Dm, K>\n}\n\n/**\n * Validates that the dependency factory is valid.\n */\nexport type ValidFactory<Dm, K extends keyof Dm> = Dm[K] extends (\n    deps: infer Deps,\n    add: AddDisposable\n) => infer R\n    ? [R] extends [void]\n        ? [never, Dm[K]]\n        : [R] extends [ExpectedInputType<Dm, K>]\n          ? Dm[K] extends () => any\n              ? Dm[K] // No dependencies\n              : Deps extends ValidProviderDependencies<Deps, Dm>\n                ? Dm[K]\n                : (deps: ValidProviderDependencies<Deps, Dm>) => R\n          : NeverWrongReturnType<ExpectedInputType<Dm, K>, R>\n    : NeverInvalidFactoryType\n\ntype _ExpectedInputUnion<Dm, K extends keyof Dm> = Dm[keyof Dm] extends (\n    deps: infer Deps,\n    add: AddDisposable\n) => any\n    ? K extends keyof Deps\n        ? Deps[K]\n        : never\n    : never\n\nexport type ExpectedInputType<Dm, K extends keyof Dm> =\n    // If the union provides `never`, it isn't a required dependency for any other factory, allow `any`\n    IsNever<_ExpectedInputUnion<Dm, K>> extends true\n        ? any\n        : _ExpectedInputUnion<Dm, K>\n\n/**\n * A type validating dependency overrides when merged with existing dependency factories.\n */\nexport type ValidFactoryOverrides<Deps, Base, Ext> = Pick<\n    ValidFactories<Merge<Base, Ext>>,\n    keyof Ext\n> &\n    Partial<Factories<Deps>>\n\n/**\n * Validate that the dependencies of a factory are not cyclical and that the return type of the\n * dependency is a subtype of what's needed.\n */\nexport type ValidProviderDependencies<Deps, Dm> = Deps extends object\n    ? {\n          readonly [K in keyof Deps]: K extends keyof Dm\n              ? Dm[K] extends Factory<infer R>\n                  ? R extends Deps[K]\n                      ? K extends FlattenDependencies<Dm, K>\n                          ? NeverCyclicDependency<K, FlattenDependencies<Dm, K>>\n                          : Deps[K]\n                      : NeverWrongDependencyType<ReturnType<Dm[K]>, Deps[K]>\n                  : NeverMissingDependency<K>\n              : NeverMissingDependency<K>\n      }\n    : NeverInvalidDependenciesType\n\n/**\n * Flattens the dependency graph for the given dependency factory.\n * E.g. given a map:\n * ```\n * type Map = {\n *     a: () => 1,\n *     b: (deps: { a: number }) => 2,\n *     c: () => 3,\n *     d: (deps: { b: number, c: number }) => 4,\n * }\n * ```\n *\n * `FlattenDependencies<'d', Map> // 'c' | 'b' | 'a'`\n */\nexport type FlattenDependencies<\n    Dm,\n    K extends keyof Dm,\n    Current extends keyof Dm = never,\n> = Dm[K] extends () => any\n    ? never\n    : Dm[K] extends (deps: infer Expected) => any\n      ? keyof Expected extends Current\n          ? never\n          :\n                | keyof Expected\n                | FlattenDependencies<\n                      Dm,\n                      keyof Expected & keyof Dm,\n                      Current | (keyof Expected & keyof Dm)\n                  >\n      : never\n", "/*\n * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.\n * SPDX-License-Identifier: Apache-2.0\n */\n\nimport { type AnyRecord, IllegalStateError } from '@amazon/vinyl-util'\nimport {\n    type AddDisposable,\n    type Disposable,\n    disposeAll,\n    DisposedError,\n    isDisposable,\n    isPromiseLike,\n    toDisposable,\n    toDisposablePromise,\n} from '@amazon/vinyl-util'\nimport { CyclicDependencyError } from './CyclicDependencyError'\n\n/**\n * A factory function that produces a dependency.\n * Called at most once per container lifecycle.\n *\n * @param deps - A statically-typed record of other dependencies required by this factory,\n *               provided by other factories.\n * @param add  - A function used to register disposables or cleanup callbacks.\n *               Use this to add teardown logic that should run when the container is disposed.\n *\n * @returns The constructed dependency. If it:\n *   - Implements `Disposable`, it will automatically be disposed when the container is disposed.\n *     Do not manually pass it to `add`.\n *   - Is `PromiseLike`, the container will wait for the promise to resolve.\n *     If the resolved value implements `Disposable`, it will also be disposed automatically.\n *     Additionally, the promise will reject if the container is disposed before resolution.\n */\nexport type Factory<T> = (deps: any, add: AddDisposable) => T\n\n/**\n * A symbol used to mark dependency factories as externally owned.\n *\n * If a `Factory` has this symbol as a property,\n * it will be considered to be owned by a parent container and will not be\n * disposed regardless of whether it implements {@link Disposable}.\n *\n * This prevents the dependency injection container from taking ownership\n * of dependencies that should be managed elsewhere.\n *\n * @example\n * ```typescript\n * const provider = () => someExternalService\n * provider[ExternalDependency] = true\n * ```\n */\nexport const ExternalDependency = /* @__PURE__ */ Symbol('externalDependency')\n\n/**\n * Creates a Factories record which provides the values of `deps`.\n * These dependencies will be considered to be owned externally and will not\n * be disposed by containers using these factories.\n *\n * This is useful when you want to inject existing instances into a dependency\n * container without transferring ownership. The container will use these\n * dependencies but won't dispose them when the container is disposed.\n *\n * @param deps - A record of dependency instances to be wrapped as factories.\n *               Each value will be returned as-is by the corresponding factory.\n * @returns An object with dependency factories for each member of deps.\n *          Each provider is marked with the {@link ExternalDependency} symbol.\n *\n * @example\n * ```typescript\n * const logger = new Logger()\n * const config = { port: 8080 }\n *\n * const factories = validateFactories({\n *     ...externalDependencies({ logger, config }),\n *     controller: (deps: { readonly logger: Logger }) => ({\n *         start: () => deps.logger.log('starting...'),\n *         dispose: () => deps.logger.log('disposed')\n *     })\n * })\n * const container = createContainer(factories)\n *\n * // logger and config won't be disposed when container is disposed\n * // controller will be disposed\n * container.dispose()\n * ```\n */\nexport function externalDependencies<T extends AnyRecord>(\n    deps: T\n): Factories<T> {\n    const out = {} as any\n    for (const key of Object.keys(deps)) {\n        const provider = () => deps[key as keyof T]\n        provider[ExternalDependency] = true\n        out[key] = provider\n    }\n    return out\n}\n\n/**\n * A map from dependency keys to factory functions.\n *\n * For each property `K` in `T`, if `T[K]` is a `Dependency`, the value must be\n * a `Factory` that produces `T[K]`. If `T[K]` is not a `Dependency`, the\n * property type resolves to `never`, causing a compile-time error.\n *\n * This ensures factories are defined only for valid dependencies and that\n * each factory is correctly typed.\n *\n * @typeParam T - A record whose values are expected to be `Dependency` types.\n */\nexport type Factories<T = any> = {\n    readonly [K in keyof T]: Factory<T[K]>\n}\n\n/**\n * Given a dependency map of keys to dependency factories, provides the mapped dependency\n * instances.\n */\nexport type Dependencies<T extends Factories> = {\n    readonly [K in keyof T]: ReturnType<T[K]>\n}\n\n/**\n * A dependencies container provides final dependencies and a handle for disposal.\n */\nexport interface Container<T> extends Disposable {\n    readonly dependencies: T\n}\n\n/**\n * Creates a {@link Container} from a dependency factory map.\n *\n * The dependencies will be a map of getters where the key matches the key within\n * `factories` and the value is a lazily constructed dependency obtained from\n * the respective provider.\n *\n * @param factories An object of key value pairs where the values are dependency\n * providers.\n */\nexport function createContainer<Dm extends Factories>(\n    factories: Dm\n): Container<Dependencies<Dm>> {\n    let disposed = false\n    const disposables: Disposable[] = []\n    const o = {}\n    let creationCount = 0\n    Object.defineProperty(o, '__enumerableGuard', {\n        get() {\n            if (creationCount !== 0) {\n                throw new IllegalStateError(\n                    'Enumeration is not supported within factories.'\n                )\n            }\n        },\n        configurable: false,\n        enumerable: true,\n    })\n    for (const key in factories) {\n        if (key === '__enumerableGuard') continue\n        let creating = false\n        let created = false\n        let value: any = null\n        Object.defineProperty(o, key, {\n            get(): any {\n                if (disposed) throw new DisposedError()\n                if (!created) {\n                    if (creating)\n                        throw new CyclicDependencyError(\n                            `The dependency with key '${key}' is cyclical. Check to ensure dependencies are not used in a property iterator.`\n                        )\n                    creationCount++\n                    creating = true\n                    const provider = factories[key]\n                    const index = disposables.length\n                    const add: AddDisposable = (disposableOrUnsub) => {\n                        if (disposableOrUnsub) {\n                            const disposable = isDisposable(disposableOrUnsub)\n                                ? disposableOrUnsub\n                                : toDisposable(disposableOrUnsub)\n                            disposables.splice(index, 0, disposable)\n                        }\n                        return disposableOrUnsub\n                    }\n                    value = provider(o, add)\n\n                    if (isPromiseLike(value)) {\n                        value = toDisposablePromise(value)\n                    }\n                    // Insert the disposable into the disposables list at the end of the list\n                    // as it was before construction. This ensures reentrancy due to\n                    // dependencies referenced during construction will be added after the\n                    // independent.\n                    if (\n                        isDisposable(value) &&\n                        !(ExternalDependency in provider)\n                    )\n                        disposables.splice(index, 0, value)\n                    creating = false\n                    created = true\n                    creationCount--\n                }\n                return value\n            },\n            configurable: false,\n            enumerable: true,\n        })\n    }\n    return {\n        dependencies: o as Dependencies<Dm>,\n        dispose() {\n            if (disposed) throw new DisposedError()\n            disposeAll(disposables)\n            disposed = true\n            disposables.length = 0\n        },\n    }\n}\n", "/*\n * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.\n * SPDX-License-Identifier: Apache-2.0\n */\n\nimport { IllegalArgumentError } from '@amazon/vinyl-util'\n\n/**\n * Thrown at runtime if a dependency is determined to depend upon itself.\n *\n * When using TypeScript this should result in a {@link NeverCyclicDependency} compile-time\n * validation error when using {@link validateFactories} unless there was an unsafe cast.\n */\nexport class CyclicDependencyError extends IllegalArgumentError {\n    get [Symbol.toStringTag](): string {\n        return 'CyclicDependencyError'\n    }\n\n    constructor(message: string) {\n        super(message)\n        Object.setPrototypeOf(this, CyclicDependencyError.prototype)\n    }\n}\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;AC+EO,SAAS,kBACZ,eACW;AACX,SAAO;AACX;;;AC9EA,IAAAA,qBAAkD;AAClD,IAAAA,qBASO;;;ACVP,wBAAqC;AAQ9B,IAAM,wBAAN,MAAM,+BAA8B,uCAAqB;AAAA,EAC5D,KAAK,OAAO,WAAW,IAAY;AAC/B,WAAO;AAAA,EACX;AAAA,EAEA,YAAY,SAAiB;AACzB,UAAM,OAAO;AACb,WAAO,eAAe,MAAM,uBAAsB,SAAS;AAAA,EAC/D;AACJ;;;AD8BO,IAAM,qBAAqC,uBAAO,oBAAoB;AAmCtE,SAAS,qBACZ,MACY;AACZ,QAAM,MAAM,CAAC;AACb,aAAW,OAAO,OAAO,KAAK,IAAI,GAAG;AACjC,UAAM,WAAW,MAAM,KAAK,GAAc;AAC1C,aAAS,kBAAkB,IAAI;AAC/B,QAAI,GAAG,IAAI;AAAA,EACf;AACA,SAAO;AACX;AA2CO,SAAS,gBACZ,WAC2B;AAC3B,MAAI,WAAW;AACf,QAAM,cAA4B,CAAC;AACnC,QAAM,IAAI,CAAC;AACX,MAAI,gBAAgB;AACpB,SAAO,eAAe,GAAG,qBAAqB;AAAA,IAC1C,MAAM;AACF,UAAI,kBAAkB,GAAG;AACrB,cAAM,IAAI;AAAA,UACN;AAAA,QACJ;AAAA,MACJ;AAAA,IACJ;AAAA,IACA,cAAc;AAAA,IACd,YAAY;AAAA,EAChB,CAAC;AACD,aAAW,OAAO,WAAW;AACzB,QAAI,QAAQ,oBAAqB;AACjC,QAAI,WAAW;AACf,QAAI,UAAU;AACd,QAAI,QAAa;AACjB,WAAO,eAAe,GAAG,KAAK;AAAA,MAC1B,MAAW;AACP,YAAI,SAAU,OAAM,IAAI,iCAAc;AACtC,YAAI,CAAC,SAAS;AACV,cAAI;AACA,kBAAM,IAAI;AAAA,cACN,4BAA4B,GAAG;AAAA,YACnC;AACJ;AACA,qBAAW;AACX,gBAAM,WAAW,UAAU,GAAG;AAC9B,gBAAM,QAAQ,YAAY;AAC1B,gBAAM,MAAqB,CAAC,sBAAsB;AAC9C,gBAAI,mBAAmB;AACnB,oBAAM,iBAAa,iCAAa,iBAAiB,IAC3C,wBACA,iCAAa,iBAAiB;AACpC,0BAAY,OAAO,OAAO,GAAG,UAAU;AAAA,YAC3C;AACA,mBAAO;AAAA,UACX;AACA,kBAAQ,SAAS,GAAG,GAAG;AAEvB,kBAAI,kCAAc,KAAK,GAAG;AACtB,wBAAQ,wCAAoB,KAAK;AAAA,UACrC;AAKA,kBACI,iCAAa,KAAK,KAClB,EAAE,sBAAsB;AAExB,wBAAY,OAAO,OAAO,GAAG,KAAK;AACtC,qBAAW;AACX,oBAAU;AACV;AAAA,QACJ;AACA,eAAO;AAAA,MACX;AAAA,MACA,cAAc;AAAA,MACd,YAAY;AAAA,IAChB,CAAC;AAAA,EACL;AACA,SAAO;AAAA,IACH,cAAc;AAAA,IACd,UAAU;AACN,UAAI,SAAU,OAAM,IAAI,iCAAc;AACtC,yCAAW,WAAW;AACtB,iBAAW;AACX,kBAAY,SAAS;AAAA,IACzB;AAAA,EACJ;AACJ;",
+  "names": ["import_vinyl_util"]
+}

package/dist/index.js

@@ -0,0 +1,113 @@
+// src/di/validation.ts
+function validateFactories(dependencyMap) {
+  return dependencyMap;
+}
+
+// src/di/di.ts
+import { IllegalStateError } from "@amazon/vinyl-util";
+import {
+  disposeAll,
+  DisposedError,
+  isDisposable,
+  isPromiseLike,
+  toDisposable,
+  toDisposablePromise
+} from "@amazon/vinyl-util";
+
+// src/di/CyclicDependencyError.ts
+import { IllegalArgumentError } from "@amazon/vinyl-util";
+var CyclicDependencyError = class _CyclicDependencyError extends IllegalArgumentError {
+  get [Symbol.toStringTag]() {
+    return "CyclicDependencyError";
+  }
+  constructor(message) {
+    super(message);
+    Object.setPrototypeOf(this, _CyclicDependencyError.prototype);
+  }
+};
+
+// src/di/di.ts
+var ExternalDependency = /* @__PURE__ */ Symbol("externalDependency");
+function externalDependencies(deps) {
+  const out = {};
+  for (const key of Object.keys(deps)) {
+    const provider = () => deps[key];
+    provider[ExternalDependency] = true;
+    out[key] = provider;
+  }
+  return out;
+}
+function createContainer(factories) {
+  let disposed = false;
+  const disposables = [];
+  const o = {};
+  let creationCount = 0;
+  Object.defineProperty(o, "__enumerableGuard", {
+    get() {
+      if (creationCount !== 0) {
+        throw new IllegalStateError(
+          "Enumeration is not supported within factories."
+        );
+      }
+    },
+    configurable: false,
+    enumerable: true
+  });
+  for (const key in factories) {
+    if (key === "__enumerableGuard") continue;
+    let creating = false;
+    let created = false;
+    let value = null;
+    Object.defineProperty(o, key, {
+      get() {
+        if (disposed) throw new DisposedError();
+        if (!created) {
+          if (creating)
+            throw new CyclicDependencyError(
+              `The dependency with key '${key}' is cyclical. Check to ensure dependencies are not used in a property iterator.`
+            );
+          creationCount++;
+          creating = true;
+          const provider = factories[key];
+          const index = disposables.length;
+          const add = (disposableOrUnsub) => {
+            if (disposableOrUnsub) {
+              const disposable = isDisposable(disposableOrUnsub) ? disposableOrUnsub : toDisposable(disposableOrUnsub);
+              disposables.splice(index, 0, disposable);
+            }
+            return disposableOrUnsub;
+          };
+          value = provider(o, add);
+          if (isPromiseLike(value)) {
+            value = toDisposablePromise(value);
+          }
+          if (isDisposable(value) && !(ExternalDependency in provider))
+            disposables.splice(index, 0, value);
+          creating = false;
+          created = true;
+          creationCount--;
+        }
+        return value;
+      },
+      configurable: false,
+      enumerable: true
+    });
+  }
+  return {
+    dependencies: o,
+    dispose() {
+      if (disposed) throw new DisposedError();
+      disposeAll(disposables);
+      disposed = true;
+      disposables.length = 0;
+    }
+  };
+}
+export {
+  CyclicDependencyError,
+  ExternalDependency,
+  createContainer,
+  externalDependencies,
+  validateFactories
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/di/validation.ts", "../src/di/di.ts", "../src/di/CyclicDependencyError.ts"],
+  "sourcesContent": ["/*\n * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.\n * SPDX-License-Identifier: Apache-2.0\n */\n\n/*\n * Provides validation utilities for type-safe dependency factories.\n */\n\nimport type { Factories, Factory } from './di'\nimport type { AddDisposable, IsNever, Merge } from '@amazon/vinyl-util'\n\n/**\n * A compile-time validation error that a dependency may not cycle back upon itself.\n */\nexport type NeverCyclicDependency<\n    T extends PropertyKey,\n    U extends PropertyKey[],\n> = [never, T, 'cyclic dependency', U]\n\n/**\n * A compile-time validation error that a provided dependency must be assignable\n * to factories for which it is an input.\n */\nexport type NeverWrongReturnType<Expected, Actual> = [\n    never,\n    'expected provided dependency is not a subtype of what is used. Expected subtype of:',\n    Expected,\n    'Actual: ',\n    Actual,\n]\n\n/**\n * A compile-time validation error that a dependency must be a supertype of the actual type\n * provided.\n */\nexport type NeverWrongDependencyType<Expected, Actual> = [\n    never,\n    'expected dependency is not a supertype of what is provided. Expected supertype of:',\n    Expected,\n    'Actual: ',\n    Actual,\n]\n\n/**\n * A factory expects a dependency that isn't defined.\n */\nexport type NeverMissingDependency<K> = [\n    never,\n    'provider is missing a dependency for key:',\n    K,\n]\n\n/**\n * A factory expects a non-void return type.\n */\nexport type NeverNoVoidReturnType = [never, 'void return type not allowed']\n\n/**\n * A factory must be a function.\n */\nexport type NeverInvalidFactoryType = [never, 'not a valid factory']\n\n/**\n * Dependencies must be an object.\n */\nexport type NeverInvalidDependenciesType = [never, 'not valid dependency type']\n\n/**\n * A compile-time validation error that dependency factories take an input of type object.\n */\nexport type NeverWrongDependenciesInput = [\n    never,\n    'expected dependency factory to have an object argument',\n]\n\n/**\n * Provides a compile-time assertion that the given dependency map provides valid factories.\n */\nexport function validateFactories<Dm extends Factories>(\n    dependencyMap: ValidFactories<Dm>\n): NoInfer<Dm> {\n    return dependencyMap as Dm\n}\n\n/**\n * Validates that the type provided is a valid dependency map.\n *\n * This will guarantee that:\n * - All dependency factories exist with the correct signature.\n * - There are no cyclic dependencies.\n * - The factory's dependencies are provided.\n *\n * @see ValidFactory\n */\nexport type ValidFactories<Dm> = {\n    readonly [K in keyof Dm]: ValidFactory<Dm, K>\n}\n\n/**\n * Validates that the dependency factory is valid.\n */\nexport type ValidFactory<Dm, K extends keyof Dm> = Dm[K] extends (\n    deps: infer Deps,\n    add: AddDisposable\n) => infer R\n    ? [R] extends [void]\n        ? [never, Dm[K]]\n        : [R] extends [ExpectedInputType<Dm, K>]\n          ? Dm[K] extends () => any\n              ? Dm[K] // No dependencies\n              : Deps extends ValidProviderDependencies<Deps, Dm>\n                ? Dm[K]\n                : (deps: ValidProviderDependencies<Deps, Dm>) => R\n          : NeverWrongReturnType<ExpectedInputType<Dm, K>, R>\n    : NeverInvalidFactoryType\n\ntype _ExpectedInputUnion<Dm, K extends keyof Dm> = Dm[keyof Dm] extends (\n    deps: infer Deps,\n    add: AddDisposable\n) => any\n    ? K extends keyof Deps\n        ? Deps[K]\n        : never\n    : never\n\nexport type ExpectedInputType<Dm, K extends keyof Dm> =\n    // If the union provides `never`, it isn't a required dependency for any other factory, allow `any`\n    IsNever<_ExpectedInputUnion<Dm, K>> extends true\n        ? any\n        : _ExpectedInputUnion<Dm, K>\n\n/**\n * A type validating dependency overrides when merged with existing dependency factories.\n */\nexport type ValidFactoryOverrides<Deps, Base, Ext> = Pick<\n    ValidFactories<Merge<Base, Ext>>,\n    keyof Ext\n> &\n    Partial<Factories<Deps>>\n\n/**\n * Validate that the dependencies of a factory are not cyclical and that the return type of the\n * dependency is a subtype of what's needed.\n */\nexport type ValidProviderDependencies<Deps, Dm> = Deps extends object\n    ? {\n          readonly [K in keyof Deps]: K extends keyof Dm\n              ? Dm[K] extends Factory<infer R>\n                  ? R extends Deps[K]\n                      ? K extends FlattenDependencies<Dm, K>\n                          ? NeverCyclicDependency<K, FlattenDependencies<Dm, K>>\n                          : Deps[K]\n                      : NeverWrongDependencyType<ReturnType<Dm[K]>, Deps[K]>\n                  : NeverMissingDependency<K>\n              : NeverMissingDependency<K>\n      }\n    : NeverInvalidDependenciesType\n\n/**\n * Flattens the dependency graph for the given dependency factory.\n * E.g. given a map:\n * ```\n * type Map = {\n *     a: () => 1,\n *     b: (deps: { a: number }) => 2,\n *     c: () => 3,\n *     d: (deps: { b: number, c: number }) => 4,\n * }\n * ```\n *\n * `FlattenDependencies<'d', Map> // 'c' | 'b' | 'a'`\n */\nexport type FlattenDependencies<\n    Dm,\n    K extends keyof Dm,\n    Current extends keyof Dm = never,\n> = Dm[K] extends () => any\n    ? never\n    : Dm[K] extends (deps: infer Expected) => any\n      ? keyof Expected extends Current\n          ? never\n          :\n                | keyof Expected\n                | FlattenDependencies<\n                      Dm,\n                      keyof Expected & keyof Dm,\n                      Current | (keyof Expected & keyof Dm)\n                  >\n      : never\n", "/*\n * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.\n * SPDX-License-Identifier: Apache-2.0\n */\n\nimport { type AnyRecord, IllegalStateError } from '@amazon/vinyl-util'\nimport {\n    type AddDisposable,\n    type Disposable,\n    disposeAll,\n    DisposedError,\n    isDisposable,\n    isPromiseLike,\n    toDisposable,\n    toDisposablePromise,\n} from '@amazon/vinyl-util'\nimport { CyclicDependencyError } from './CyclicDependencyError'\n\n/**\n * A factory function that produces a dependency.\n * Called at most once per container lifecycle.\n *\n * @param deps - A statically-typed record of other dependencies required by this factory,\n *               provided by other factories.\n * @param add  - A function used to register disposables or cleanup callbacks.\n *               Use this to add teardown logic that should run when the container is disposed.\n *\n * @returns The constructed dependency. If it:\n *   - Implements `Disposable`, it will automatically be disposed when the container is disposed.\n *     Do not manually pass it to `add`.\n *   - Is `PromiseLike`, the container will wait for the promise to resolve.\n *     If the resolved value implements `Disposable`, it will also be disposed automatically.\n *     Additionally, the promise will reject if the container is disposed before resolution.\n */\nexport type Factory<T> = (deps: any, add: AddDisposable) => T\n\n/**\n * A symbol used to mark dependency factories as externally owned.\n *\n * If a `Factory` has this symbol as a property,\n * it will be considered to be owned by a parent container and will not be\n * disposed regardless of whether it implements {@link Disposable}.\n *\n * This prevents the dependency injection container from taking ownership\n * of dependencies that should be managed elsewhere.\n *\n * @example\n * ```typescript\n * const provider = () => someExternalService\n * provider[ExternalDependency] = true\n * ```\n */\nexport const ExternalDependency = /* @__PURE__ */ Symbol('externalDependency')\n\n/**\n * Creates a Factories record which provides the values of `deps`.\n * These dependencies will be considered to be owned externally and will not\n * be disposed by containers using these factories.\n *\n * This is useful when you want to inject existing instances into a dependency\n * container without transferring ownership. The container will use these\n * dependencies but won't dispose them when the container is disposed.\n *\n * @param deps - A record of dependency instances to be wrapped as factories.\n *               Each value will be returned as-is by the corresponding factory.\n * @returns An object with dependency factories for each member of deps.\n *          Each provider is marked with the {@link ExternalDependency} symbol.\n *\n * @example\n * ```typescript\n * const logger = new Logger()\n * const config = { port: 8080 }\n *\n * const factories = validateFactories({\n *     ...externalDependencies({ logger, config }),\n *     controller: (deps: { readonly logger: Logger }) => ({\n *         start: () => deps.logger.log('starting...'),\n *         dispose: () => deps.logger.log('disposed')\n *     })\n * })\n * const container = createContainer(factories)\n *\n * // logger and config won't be disposed when container is disposed\n * // controller will be disposed\n * container.dispose()\n * ```\n */\nexport function externalDependencies<T extends AnyRecord>(\n    deps: T\n): Factories<T> {\n    const out = {} as any\n    for (const key of Object.keys(deps)) {\n        const provider = () => deps[key as keyof T]\n        provider[ExternalDependency] = true\n        out[key] = provider\n    }\n    return out\n}\n\n/**\n * A map from dependency keys to factory functions.\n *\n * For each property `K` in `T`, if `T[K]` is a `Dependency`, the value must be\n * a `Factory` that produces `T[K]`. If `T[K]` is not a `Dependency`, the\n * property type resolves to `never`, causing a compile-time error.\n *\n * This ensures factories are defined only for valid dependencies and that\n * each factory is correctly typed.\n *\n * @typeParam T - A record whose values are expected to be `Dependency` types.\n */\nexport type Factories<T = any> = {\n    readonly [K in keyof T]: Factory<T[K]>\n}\n\n/**\n * Given a dependency map of keys to dependency factories, provides the mapped dependency\n * instances.\n */\nexport type Dependencies<T extends Factories> = {\n    readonly [K in keyof T]: ReturnType<T[K]>\n}\n\n/**\n * A dependencies container provides final dependencies and a handle for disposal.\n */\nexport interface Container<T> extends Disposable {\n    readonly dependencies: T\n}\n\n/**\n * Creates a {@link Container} from a dependency factory map.\n *\n * The dependencies will be a map of getters where the key matches the key within\n * `factories` and the value is a lazily constructed dependency obtained from\n * the respective provider.\n *\n * @param factories An object of key value pairs where the values are dependency\n * providers.\n */\nexport function createContainer<Dm extends Factories>(\n    factories: Dm\n): Container<Dependencies<Dm>> {\n    let disposed = false\n    const disposables: Disposable[] = []\n    const o = {}\n    let creationCount = 0\n    Object.defineProperty(o, '__enumerableGuard', {\n        get() {\n            if (creationCount !== 0) {\n                throw new IllegalStateError(\n                    'Enumeration is not supported within factories.'\n                )\n            }\n        },\n        configurable: false,\n        enumerable: true,\n    })\n    for (const key in factories) {\n        if (key === '__enumerableGuard') continue\n        let creating = false\n        let created = false\n        let value: any = null\n        Object.defineProperty(o, key, {\n            get(): any {\n                if (disposed) throw new DisposedError()\n                if (!created) {\n                    if (creating)\n                        throw new CyclicDependencyError(\n                            `The dependency with key '${key}' is cyclical. Check to ensure dependencies are not used in a property iterator.`\n                        )\n                    creationCount++\n                    creating = true\n                    const provider = factories[key]\n                    const index = disposables.length\n                    const add: AddDisposable = (disposableOrUnsub) => {\n                        if (disposableOrUnsub) {\n                            const disposable = isDisposable(disposableOrUnsub)\n                                ? disposableOrUnsub\n                                : toDisposable(disposableOrUnsub)\n                            disposables.splice(index, 0, disposable)\n                        }\n                        return disposableOrUnsub\n                    }\n                    value = provider(o, add)\n\n                    if (isPromiseLike(value)) {\n                        value = toDisposablePromise(value)\n                    }\n                    // Insert the disposable into the disposables list at the end of the list\n                    // as it was before construction. This ensures reentrancy due to\n                    // dependencies referenced during construction will be added after the\n                    // independent.\n                    if (\n                        isDisposable(value) &&\n                        !(ExternalDependency in provider)\n                    )\n                        disposables.splice(index, 0, value)\n                    creating = false\n                    created = true\n                    creationCount--\n                }\n                return value\n            },\n            configurable: false,\n            enumerable: true,\n        })\n    }\n    return {\n        dependencies: o as Dependencies<Dm>,\n        dispose() {\n            if (disposed) throw new DisposedError()\n            disposeAll(disposables)\n            disposed = true\n            disposables.length = 0\n        },\n    }\n}\n", "/*\n * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.\n * SPDX-License-Identifier: Apache-2.0\n */\n\nimport { IllegalArgumentError } from '@amazon/vinyl-util'\n\n/**\n * Thrown at runtime if a dependency is determined to depend upon itself.\n *\n * When using TypeScript this should result in a {@link NeverCyclicDependency} compile-time\n * validation error when using {@link validateFactories} unless there was an unsafe cast.\n */\nexport class CyclicDependencyError extends IllegalArgumentError {\n    get [Symbol.toStringTag](): string {\n        return 'CyclicDependencyError'\n    }\n\n    constructor(message: string) {\n        super(message)\n        Object.setPrototypeOf(this, CyclicDependencyError.prototype)\n    }\n}\n"],
+  "mappings": ";AA+EO,SAAS,kBACZ,eACW;AACX,SAAO;AACX;;;AC9EA,SAAyB,yBAAyB;AAClD;AAAA,EAGI;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OACG;;;ACVP,SAAS,4BAA4B;AAQ9B,IAAM,wBAAN,MAAM,+BAA8B,qBAAqB;AAAA,EAC5D,KAAK,OAAO,WAAW,IAAY;AAC/B,WAAO;AAAA,EACX;AAAA,EAEA,YAAY,SAAiB;AACzB,UAAM,OAAO;AACb,WAAO,eAAe,MAAM,uBAAsB,SAAS;AAAA,EAC/D;AACJ;;;AD8BO,IAAM,qBAAqC,uBAAO,oBAAoB;AAmCtE,SAAS,qBACZ,MACY;AACZ,QAAM,MAAM,CAAC;AACb,aAAW,OAAO,OAAO,KAAK,IAAI,GAAG;AACjC,UAAM,WAAW,MAAM,KAAK,GAAc;AAC1C,aAAS,kBAAkB,IAAI;AAC/B,QAAI,GAAG,IAAI;AAAA,EACf;AACA,SAAO;AACX;AA2CO,SAAS,gBACZ,WAC2B;AAC3B,MAAI,WAAW;AACf,QAAM,cAA4B,CAAC;AACnC,QAAM,IAAI,CAAC;AACX,MAAI,gBAAgB;AACpB,SAAO,eAAe,GAAG,qBAAqB;AAAA,IAC1C,MAAM;AACF,UAAI,kBAAkB,GAAG;AACrB,cAAM,IAAI;AAAA,UACN;AAAA,QACJ;AAAA,MACJ;AAAA,IACJ;AAAA,IACA,cAAc;AAAA,IACd,YAAY;AAAA,EAChB,CAAC;AACD,aAAW,OAAO,WAAW;AACzB,QAAI,QAAQ,oBAAqB;AACjC,QAAI,WAAW;AACf,QAAI,UAAU;AACd,QAAI,QAAa;AACjB,WAAO,eAAe,GAAG,KAAK;AAAA,MAC1B,MAAW;AACP,YAAI,SAAU,OAAM,IAAI,cAAc;AACtC,YAAI,CAAC,SAAS;AACV,cAAI;AACA,kBAAM,IAAI;AAAA,cACN,4BAA4B,GAAG;AAAA,YACnC;AACJ;AACA,qBAAW;AACX,gBAAM,WAAW,UAAU,GAAG;AAC9B,gBAAM,QAAQ,YAAY;AAC1B,gBAAM,MAAqB,CAAC,sBAAsB;AAC9C,gBAAI,mBAAmB;AACnB,oBAAM,aAAa,aAAa,iBAAiB,IAC3C,oBACA,aAAa,iBAAiB;AACpC,0BAAY,OAAO,OAAO,GAAG,UAAU;AAAA,YAC3C;AACA,mBAAO;AAAA,UACX;AACA,kBAAQ,SAAS,GAAG,GAAG;AAEvB,cAAI,cAAc,KAAK,GAAG;AACtB,oBAAQ,oBAAoB,KAAK;AAAA,UACrC;AAKA,cACI,aAAa,KAAK,KAClB,EAAE,sBAAsB;AAExB,wBAAY,OAAO,OAAO,GAAG,KAAK;AACtC,qBAAW;AACX,oBAAU;AACV;AAAA,QACJ;AACA,eAAO;AAAA,MACX;AAAA,MACA,cAAc;AAAA,MACd,YAAY;AAAA,IAChB,CAAC;AAAA,EACL;AACA,SAAO;AAAA,IACH,cAAc;AAAA,IACd,UAAU;AACN,UAAI,SAAU,OAAM,IAAI,cAAc;AACtC,iBAAW,WAAW;AACtB,iBAAW;AACX,kBAAY,SAAS;AAAA,IACzB;AAAA,EACJ;AACJ;",
+  "names": []
+}

package/dist/types/current/di/CyclicDependencyError.d.ts

@@ -0,0 +1,12 @@
+import { IllegalArgumentError } from '@amazon/vinyl-util';
+/**
+ * Thrown at runtime if a dependency is determined to depend upon itself.
+ *
+ * When using TypeScript this should result in a {@link NeverCyclicDependency} compile-time
+ * validation error when using {@link validateFactories} unless there was an unsafe cast.
+ */
+export declare class CyclicDependencyError extends IllegalArgumentError {
+    get [Symbol.toStringTag](): string;
+    constructor(message: string);
+}
+//# sourceMappingURL=CyclicDependencyError.d.ts.map

package/dist/types/current/di/CyclicDependencyError.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CyclicDependencyError.d.ts","sourceRoot":"","sources":["../../../../src/di/CyclicDependencyError.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAA;AAEzD;;;;;GAKG;AACH,qBAAa,qBAAsB,SAAQ,oBAAoB;IAC3D,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC,IAAI,MAAM,CAEjC;gBAEW,OAAO,EAAE,MAAM;CAI9B"}

package/dist/types/current/di/CyclicDependencyError.js

@@ -0,0 +1,20 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { IllegalArgumentError } from '@amazon/vinyl-util';
+/**
+ * Thrown at runtime if a dependency is determined to depend upon itself.
+ *
+ * When using TypeScript this should result in a {@link NeverCyclicDependency} compile-time
+ * validation error when using {@link validateFactories} unless there was an unsafe cast.
+ */
+export class CyclicDependencyError extends IllegalArgumentError {
+    get [Symbol.toStringTag]() {
+        return 'CyclicDependencyError';
+    }
+    constructor(message) {
+        super(message);
+        Object.setPrototypeOf(this, CyclicDependencyError.prototype);
+    }
+}

package/dist/types/current/di/di.d.ts

@@ -0,0 +1,110 @@
+import { type AnyRecord } from '@amazon/vinyl-util';
+import { type AddDisposable, type Disposable } from '@amazon/vinyl-util';
+/**
+ * A factory function that produces a dependency.
+ * Called at most once per container lifecycle.
+ *
+ * @param deps - A statically-typed record of other dependencies required by this factory,
+ *               provided by other factories.
+ * @param add  - A function used to register disposables or cleanup callbacks.
+ *               Use this to add teardown logic that should run when the container is disposed.
+ *
+ * @returns The constructed dependency. If it:
+ *   - Implements `Disposable`, it will automatically be disposed when the container is disposed.
+ *     Do not manually pass it to `add`.
+ *   - Is `PromiseLike`, the container will wait for the promise to resolve.
+ *     If the resolved value implements `Disposable`, it will also be disposed automatically.
+ *     Additionally, the promise will reject if the container is disposed before resolution.
+ */
+export type Factory<T> = (deps: any, add: AddDisposable) => T;
+/**
+ * A symbol used to mark dependency factories as externally owned.
+ *
+ * If a `Factory` has this symbol as a property,
+ * it will be considered to be owned by a parent container and will not be
+ * disposed regardless of whether it implements {@link Disposable}.
+ *
+ * This prevents the dependency injection container from taking ownership
+ * of dependencies that should be managed elsewhere.
+ *
+ * @example
+ * ```typescript
+ * const provider = () => someExternalService
+ * provider[ExternalDependency] = true
+ * ```
+ */
+export declare const ExternalDependency: unique symbol;
+/**
+ * Creates a Factories record which provides the values of `deps`.
+ * These dependencies will be considered to be owned externally and will not
+ * be disposed by containers using these factories.
+ *
+ * This is useful when you want to inject existing instances into a dependency
+ * container without transferring ownership. The container will use these
+ * dependencies but won't dispose them when the container is disposed.
+ *
+ * @param deps - A record of dependency instances to be wrapped as factories.
+ *               Each value will be returned as-is by the corresponding factory.
+ * @returns An object with dependency factories for each member of deps.
+ *          Each provider is marked with the {@link ExternalDependency} symbol.
+ *
+ * @example
+ * ```typescript
+ * const logger = new Logger()
+ * const config = { port: 8080 }
+ *
+ * const factories = validateFactories({
+ *     ...externalDependencies({ logger, config }),
+ *     controller: (deps: { readonly logger: Logger }) => ({
+ *         start: () => deps.logger.log('starting...'),
+ *         dispose: () => deps.logger.log('disposed')
+ *     })
+ * })
+ * const container = createContainer(factories)
+ *
+ * // logger and config won't be disposed when container is disposed
+ * // controller will be disposed
+ * container.dispose()
+ * ```
+ */
+export declare function externalDependencies<T extends AnyRecord>(deps: T): Factories<T>;
+/**
+ * A map from dependency keys to factory functions.
+ *
+ * For each property `K` in `T`, if `T[K]` is a `Dependency`, the value must be
+ * a `Factory` that produces `T[K]`. If `T[K]` is not a `Dependency`, the
+ * property type resolves to `never`, causing a compile-time error.
+ *
+ * This ensures factories are defined only for valid dependencies and that
+ * each factory is correctly typed.
+ *
+ * @typeParam T - A record whose values are expected to be `Dependency` types.
+ */
+export type Factories<T = any> = {
+    readonly [K in keyof T]: Factory<T[K]>;
+};
+/**
+ * Given a dependency map of keys to dependency factories, provides the mapped dependency
+ * instances.
+ */
+export type Dependencies<T extends Factories> = {
+    readonly [K in keyof T]: ReturnType<T[K]>;
+};
+/**
+ * A dependencies container provides final dependencies and a handle for disposal.
+ */
+export interface Container<T> extends Disposable {
+    readonly dependencies: T;
+}
+/**
+ * Creates a {@link Container} from a dependency factory map.
+ *
+ * The dependencies will be a map of getters where the key matches the key within
+ * `factories` and the value is a lazily constructed dependency obtained from
+ * the respective provider.
+ *
+ * @param factories An object of key value pairs where the values are dependency
+ * providers.
+ */
+export declare function createContainer<Dm extends Factories>(factories: Dm): Container<Dependencies<Dm>>;
+//# sourceMappingURL=di.d.ts.map

package/dist/types/current/di/di.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"di.d.ts","sourceRoot":"","sources":["../../../../src/di/di.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,KAAK,SAAS,EAAqB,MAAM,oBAAoB,CAAA;AACtE,OAAO,EACH,KAAK,aAAa,EAClB,KAAK,UAAU,EAOlB,MAAM,oBAAoB,CAAA;AAG3B;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,GAAG,EAAE,GAAG,EAAE,aAAa,KAAK,CAAC,CAAA;AAE7D;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,kBAAkB,eAA+B,CAAA;AAE9D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,SAAS,SAAS,EACpD,IAAI,EAAE,CAAC,GACR,SAAS,CAAC,CAAC,CAAC,CAQd;AAED;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,SAAS,CAAC,CAAC,GAAG,GAAG,IAAI;IAC7B,QAAQ,EAAE,CAAC,IAAI,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CACzC,CAAA;AAED;;;GAGG;AACH,MAAM,MAAM,YAAY,CAAC,CAAC,SAAS,SAAS,IAAI;IAC5C,QAAQ,EAAE,CAAC,IAAI,MAAM,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CAC5C,CAAA;AAED;;GAEG;AACH,MAAM,WAAW,SAAS,CAAC,CAAC,CAAE,SAAQ,UAAU;IAC5C,QAAQ,CAAC,YAAY,EAAE,CAAC,CAAA;CAC3B;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,EAAE,SAAS,SAAS,EAChD,SAAS,EAAE,EAAE,GACd,SAAS,CAAC,YAAY,CAAC,EAAE,CAAC,CAAC,CA2E7B"}

package/dist/types/current/di/di.js

@@ -0,0 +1,148 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { IllegalStateError } from '@amazon/vinyl-util';
+import { disposeAll, DisposedError, isDisposable, isPromiseLike, toDisposable, toDisposablePromise, } from '@amazon/vinyl-util';
+import { CyclicDependencyError } from './CyclicDependencyError';
+/**
+ * A symbol used to mark dependency factories as externally owned.
+ *
+ * If a `Factory` has this symbol as a property,
+ * it will be considered to be owned by a parent container and will not be
+ * disposed regardless of whether it implements {@link Disposable}.
+ *
+ * This prevents the dependency injection container from taking ownership
+ * of dependencies that should be managed elsewhere.
+ *
+ * @example
+ * ```typescript
+ * const provider = () => someExternalService
+ * provider[ExternalDependency] = true
+ * ```
+ */
+export const ExternalDependency = Symbol('externalDependency');
+/**
+ * Creates a Factories record which provides the values of `deps`.
+ * These dependencies will be considered to be owned externally and will not
+ * be disposed by containers using these factories.
+ *
+ * This is useful when you want to inject existing instances into a dependency
+ * container without transferring ownership. The container will use these
+ * dependencies but won't dispose them when the container is disposed.
+ *
+ * @param deps - A record of dependency instances to be wrapped as factories.
+ *               Each value will be returned as-is by the corresponding factory.
+ * @returns An object with dependency factories for each member of deps.
+ *          Each provider is marked with the {@link ExternalDependency} symbol.
+ *
+ * @example
+ * ```typescript
+ * const logger = new Logger()
+ * const config = { port: 8080 }
+ *
+ * const factories = validateFactories({
+ *     ...externalDependencies({ logger, config }),
+ *     controller: (deps: { readonly logger: Logger }) => ({
+ *         start: () => deps.logger.log('starting...'),
+ *         dispose: () => deps.logger.log('disposed')
+ *     })
+ * })
+ * const container = createContainer(factories)
+ *
+ * // logger and config won't be disposed when container is disposed
+ * // controller will be disposed
+ * container.dispose()
+ * ```
+ */
+export function externalDependencies(deps) {
+    const out = {};
+    for (const key of Object.keys(deps)) {
+        const provider = () => deps[key];
+        provider[ExternalDependency] = true;
+        out[key] = provider;
+    }
+    return out;
+}
+/**
+ * Creates a {@link Container} from a dependency factory map.
+ *
+ * The dependencies will be a map of getters where the key matches the key within
+ * `factories` and the value is a lazily constructed dependency obtained from
+ * the respective provider.
+ *
+ * @param factories An object of key value pairs where the values are dependency
+ * providers.
+ */
+export function createContainer(factories) {
+    let disposed = false;
+    const disposables = [];
+    const o = {};
+    let creationCount = 0;
+    Object.defineProperty(o, '__enumerableGuard', {
+        get() {
+            if (creationCount !== 0) {
+                throw new IllegalStateError('Enumeration is not supported within factories.');
+            }
+        },
+        configurable: false,
+        enumerable: true,
+    });
+    for (const key in factories) {
+        if (key === '__enumerableGuard')
+            continue;
+        let creating = false;
+        let created = false;
+        let value = null;
+        Object.defineProperty(o, key, {
+            get() {
+                if (disposed)
+                    throw new DisposedError();
+                if (!created) {
+                    if (creating)
+                        throw new CyclicDependencyError(`The dependency with key '${key}' is cyclical. Check to ensure dependencies are not used in a property iterator.`);
+                    creationCount++;
+                    creating = true;
+                    const provider = factories[key];
+                    const index = disposables.length;
+                    const add = (disposableOrUnsub) => {
+                        if (disposableOrUnsub) {
+                            const disposable = isDisposable(disposableOrUnsub)
+                                ? disposableOrUnsub
+                                : toDisposable(disposableOrUnsub);
+                            disposables.splice(index, 0, disposable);
+                        }
+                        return disposableOrUnsub;
+                    };
+                    value = provider(o, add);
+                    if (isPromiseLike(value)) {
+                        value = toDisposablePromise(value);
+                    }
+                    // Insert the disposable into the disposables list at the end of the list
+                    // as it was before construction. This ensures reentrancy due to
+                    // dependencies referenced during construction will be added after the
+                    // independent.
+                    if (isDisposable(value) &&
+                        !(ExternalDependency in provider))
+                        disposables.splice(index, 0, value);
+                    creating = false;
+                    created = true;
+                    creationCount--;
+                }
+                return value;
+            },
+            configurable: false,
+            enumerable: true,
+        });
+    }
+    return {
+        dependencies: o,
+        dispose() {
+            if (disposed)
+                throw new DisposedError();
+            disposeAll(disposables);
+            disposed = true;
+            disposables.length = 0;
+        },
+    };
+}