@fluixi/di 0.0.0-stage → 1.0.0-alpha.99

package/dist/injector.cjs

@@ -0,0 +1,259 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __typeError = (msg) => {
+  throw TypeError(msg);
+};
+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);
+var __accessCheck = (obj, member, msg) => member.has(obj) || __typeError("Cannot " + msg);
+var __privateGet = (obj, member, getter) => (__accessCheck(obj, member, "read from private field"), getter ? getter.call(obj) : member.get(obj));
+var __privateAdd = (obj, member, value) => member.has(obj) ? __typeError("Cannot add the same private member more than once") : member instanceof WeakSet ? member.add(obj) : member.set(obj, value);
+var __privateSet = (obj, member, value, setter) => (__accessCheck(obj, member, "write to private field"), setter ? setter.call(obj, value) : member.set(obj, value), value);
+var __privateMethod = (obj, member, method) => (__accessCheck(obj, member, "access private method"), method);
+
+// src/injector.ts
+var injector_exports = {};
+__export(injector_exports, {
+  Injector: () => Injector
+});
+module.exports = __toCommonJS(injector_exports);
+var import_signal2 = require("@fluixi/reactive/signal");
+
+// src/errors.ts
+var InjectionError = class extends Error {
+  /**
+   * @param message - What went wrong, with the path rendered into it.
+   * @param path - The tokens being resolved, outermost first; the last one is the one that failed.
+   */
+  constructor(message, path) {
+    super(message);
+    this.path = path;
+    this.name = "InjectionError";
+  }
+};
+
+// src/hierarchy.ts
+var import_dom = require("@fluixi/dom");
+var import_signal = require("@fluixi/reactive/signal");
+
+// src/state.ts
+function freshState() {
+  return {
+    platformProviders: [],
+    rootProviders: [],
+    platform: null,
+    clientRoot: null,
+    requestRoots: /* @__PURE__ */ new WeakMap(),
+    ownerInjectors: /* @__PURE__ */ new WeakMap(),
+    moduleScopes: /* @__PURE__ */ new WeakMap(),
+    overrides: /* @__PURE__ */ new Map(),
+    explicit: null,
+    path: []
+  };
+}
+var state = globalThis[/* @__PURE__ */ Symbol.for("fluixi.di")] ??= freshState();
+
+// src/hierarchy.ts
+function platformInjector() {
+  return state.platform ??= new Injector(null, "platform").register(state.platformProviders);
+}
+
+// src/token.ts
+function injectionToken(name, options) {
+  return { id: Symbol(name), name, factory: options?.factory, scope: options?.scope ?? "root" };
+}
+
+// src/tokens.ts
+var DestroyRef = injectionToken("DestroyRef");
+var INJECTOR = injectionToken("Injector");
+
+// src/injector.ts
+var _records, _created, _hooks, _destroyed, _Injector_instances, home_fn, fromProvider_fn, build_fn, make_fn;
+var Injector = class {
+  /**
+   * @param parent - Where a token this injector does not hold is looked for next; `null` for the
+   *   top of a chain.
+   * @param kind - Where the injector sits in the hierarchy; see {@link InjectorKind}.
+   */
+  constructor(parent = null, kind = "standalone") {
+    this.parent = parent;
+    this.kind = kind;
+    __privateAdd(this, _Injector_instances);
+    __privateAdd(this, _records, /* @__PURE__ */ new Map());
+    __privateAdd(this, _created, []);
+    __privateAdd(this, _hooks, []);
+    __privateAdd(this, _destroyed, false);
+    const self = this;
+    this.destroyRef = {
+      onDestroy(fn) {
+        __privateGet(self, _hooks).push(fn);
+        return () => {
+          const i = __privateGet(self, _hooks).indexOf(fn);
+          if (i >= 0) __privateGet(self, _hooks).splice(i, 1);
+        };
+      },
+      get destroyed() {
+        return __privateGet(self, _destroyed);
+      }
+    };
+  }
+  /** Whether {@link Injector.dispose} has run. A disposed injector refuses every `get`. */
+  get destroyed() {
+    return __privateGet(this, _destroyed);
+  }
+  /**
+   * Add providers to this injector. A provider for a token already held replaces it, except
+   * `multi` providers, which extend the token's list. A provider whose token has a test override
+   * is replaced by the override.
+   *
+   * @param providers - The providers to add, in order.
+   * @returns This injector, for chaining.
+   */
+  register(providers) {
+    for (const given of providers) {
+      const p = state.overrides.get(given.provide.id) ?? given;
+      if (p.multi) {
+        const rec = __privateGet(this, _records).get(p.provide.id);
+        if (rec?.multi) {
+          rec.providers.push(p);
+          rec.built = false;
+        } else __privateGet(this, _records).set(p.provide.id, { multi: true, providers: [p], built: false, building: false, value: [] });
+      } else {
+        __privateGet(this, _records).set(p.provide.id, { multi: false, provider: p, built: false, building: false, value: void 0 });
+      }
+    }
+    return this;
+  }
+  get(token, options = {}) {
+    var _a, _b, _c;
+    if (__privateGet(this, _destroyed)) throw new InjectionError(`[fluixi/di] "${token.name}" requested from a disposed injector.`, [...state.path, token.name]);
+    if (token.id === INJECTOR.id) return this;
+    if (token.id === DestroyRef.id) return this.destroyRef;
+    let inj = options.skipSelf ? this.parent : this;
+    while (inj) {
+      const rec = __privateGet(inj, _records).get(token.id);
+      if (rec) return __privateMethod(_a = inj, _Injector_instances, build_fn).call(_a, token, rec);
+      if (options.self || options.host && inj.kind === "owner") break;
+      inj = inj.parent;
+    }
+    const override = state.overrides.get(token.id);
+    if (override && !options.self) return __privateMethod(_b = __privateMethod(this, _Injector_instances, home_fn).call(this, token.scope), _Injector_instances, fromProvider_fn).call(_b, token, override);
+    if (token.factory && !options.self && !options.host) {
+      return __privateMethod(_c = __privateMethod(this, _Injector_instances, home_fn).call(this, token.scope), _Injector_instances, fromProvider_fn).call(_c, token, { provide: token, useFactory: token.factory });
+    }
+    if (options.optional) return null;
+    const path = [...state.path, token.name];
+    throw new InjectionError(
+      `[fluixi/di] No provider for "${token.name}" (${path.join(" → ")}). Provide it in an app module, with provide() or provideRoot(), or give the token a { factory }.`,
+      path
+    );
+  }
+  /**
+   * Release this injector: run the hooks registered on its `DestroyRef`, latest first, then the
+   * `onDestroy()` method of every service it built, latest built first, then forget its
+   * providers. A hook or `onDestroy()` that throws is logged and the rest still run. Running it
+   * again does nothing.
+   *
+   * Component injectors are disposed when the component unmounts, request roots when the request
+   * ends; call it yourself only for injectors you created.
+   */
+  dispose() {
+    if (__privateGet(this, _destroyed)) return;
+    __privateSet(this, _destroyed, true);
+    const fail = (error) => console.error("[fluixi/di] a destroy hook threw:", error);
+    for (const hook of __privateGet(this, _hooks).splice(0).reverse()) {
+      try {
+        hook();
+      } catch (error) {
+        fail(error);
+      }
+    }
+    for (const value of __privateGet(this, _created).splice(0).reverse()) {
+      const service = value;
+      if (service && typeof service.onDestroy === "function") {
+        try {
+          service.onDestroy();
+        } catch (error) {
+          fail(error);
+        }
+      }
+    }
+    __privateGet(this, _records).clear();
+  }
+};
+_records = new WeakMap();
+_created = new WeakMap();
+_hooks = new WeakMap();
+_destroyed = new WeakMap();
+_Injector_instances = new WeakSet();
+/** The injector a self-providing token builds in: the nearest root, or the platform. */
+home_fn = function(scope) {
+  let inj = this;
+  if (scope === "platform") {
+    while (inj.parent) inj = inj.parent;
+    return inj.kind === "platform" ? inj : platformInjector();
+  }
+  let probe = this;
+  while (probe) {
+    if (probe.kind === "root") return probe;
+    probe = probe.parent;
+  }
+  while (inj.parent && inj.parent.kind !== "platform") inj = inj.parent;
+  return inj;
+};
+fromProvider_fn = function(token, provider) {
+  let rec = __privateGet(this, _records).get(token.id);
+  if (!rec) {
+    rec = { multi: false, provider, built: false, building: false, value: void 0 };
+    __privateGet(this, _records).set(token.id, rec);
+  }
+  return __privateMethod(this, _Injector_instances, build_fn).call(this, token, rec);
+};
+build_fn = function(token, rec) {
+  if (rec.built) return rec.value;
+  if (rec.building) {
+    const path = [...state.path, token.name];
+    throw new InjectionError(`[fluixi/di] Circular dependency: ${path.join(" → ")}.`, path);
+  }
+  rec.building = true;
+  state.path.push(token.name);
+  const previous = state.explicit;
+  state.explicit = this;
+  try {
+    if (rec.multi) {
+      rec.value = rec.providers.map((p) => __privateMethod(this, _Injector_instances, make_fn).call(this, token, p));
+    } else {
+      const module2 = state.moduleScopes.get(rec.provider);
+      rec.value = module2 ? (0, import_signal2.withReactiveScope)(module2, () => __privateMethod(this, _Injector_instances, make_fn).call(this, token, rec.provider)) : __privateMethod(this, _Injector_instances, make_fn).call(this, token, rec.provider);
+    }
+    rec.built = true;
+    return rec.value;
+  } finally {
+    state.explicit = previous;
+    state.path.pop();
+    rec.building = false;
+  }
+};
+make_fn = function(token, p) {
+  if ("useValue" in p) return p.useValue;
+  if ("useExisting" in p) return this.get(p.useExisting);
+  const deps = (p.deps ?? []).map((d) => "token" in d ? this.get(d.token, d) : this.get(d));
+  const scope = (0, import_signal2.openReactiveScope)({ kind: "service", name: token.name, detail: "useClass" in p ? "useClass" : "useFactory" });
+  const value = (0, import_signal2.withReactiveScope)(scope, () => "useClass" in p ? new p.useClass(...deps) : p.useFactory(...deps));
+  __privateGet(this, _created).push(value);
+  return value;
+};

package/dist/injector.d.ts

@@ -0,0 +1,73 @@
+import type { InjectOptions, Provider } from './provider.js';
+import type { Token } from './token.js';
+import { DestroyRef } from './tokens.js';
+/**
+ * Where an injector sits in the hierarchy.
+ *
+ * - `'platform'`: one per process, the top of every chain.
+ * - `'root'`: one per request on the server, one per app in the browser, below the platform.
+ * - `'owner'`: created by `provide()` for a component, below its nearest ancestor's injector or
+ *   the root; the boundary `{ host: true }` stops at.
+ * - `'standalone'`: created by `createInjector()` or for a test.
+ */
+export type InjectorKind = 'platform' | 'root' | 'owner' | 'standalone';
+/**
+ * Holds providers and resolves tokens: from itself, then up its parents, then from the token's
+ * own factory. Each value is built once per injector, on first request, and released when the
+ * injector is disposed.
+ *
+ * Code rarely creates injectors: `provide()`, `provideRoot()` and `providePlatform()` place
+ * providers in the hierarchy, and `inject()` resolves from the current context. An `Injector` is
+ * handled directly to resolve outside a context (`get`), to scope work to it
+ * (`runInInjectionContext`), or in tests.
+ */
+export declare class Injector {
+    #private;
+    readonly parent: Injector | null;
+    readonly kind: InjectorKind;
+    /** The lifecycle of this injector, also answered by `inject(DestroyRef)` in its context. */
+    readonly destroyRef: DestroyRef;
+    /**
+     * @param parent - Where a token this injector does not hold is looked for next; `null` for the
+     *   top of a chain.
+     * @param kind - Where the injector sits in the hierarchy; see {@link InjectorKind}.
+     */
+    constructor(parent?: Injector | null, kind?: InjectorKind);
+    /** Whether {@link Injector.dispose} has run. A disposed injector refuses every `get`. */
+    get destroyed(): boolean;
+    /**
+     * Add providers to this injector. A provider for a token already held replaces it, except
+     * `multi` providers, which extend the token's list. A provider whose token has a test override
+     * is replaced by the override.
+     *
+     * @param providers - The providers to add, in order.
+     * @returns This injector, for chaining.
+     */
+    register(providers: ReadonlyArray<Provider>): this;
+    /**
+     * Resolve `token`: from this injector, then up its parents, then from the token's own factory
+     * (built in its scope). The value is built on first request and reused after. `INJECTOR` and
+     * `DestroyRef` resolve to this injector and its lifecycle.
+     *
+     * @param token - What to resolve.
+     * @param options - Where to look and what to do when nothing is found; see {@link InjectOptions}.
+     * @returns The value, or `null` when `optional` is set and nothing provides the token.
+     * @throws {@link InjectionError} When nothing provides the token, on a dependency cycle, or when
+     *   this injector is disposed.
+     */
+    get<T>(token: Token<T>, options: InjectOptions & {
+        optional: true;
+    }): T | null;
+    get<T>(token: Token<T>, options?: InjectOptions): T;
+    /**
+     * Release this injector: run the hooks registered on its `DestroyRef`, latest first, then the
+     * `onDestroy()` method of every service it built, latest built first, then forget its
+     * providers. A hook or `onDestroy()` that throws is logged and the rest still run. Running it
+     * again does nothing.
+     *
+     * Component injectors are disposed when the component unmounts, request roots when the request
+     * ends; call it yourself only for injectors you created.
+     */
+    dispose(): void;
+}
+//# sourceMappingURL=injector.d.ts.map

package/dist/injector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"injector.d.ts","sourceRoot":"","sources":["../src/injector.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAE7D,OAAO,KAAK,EAAS,KAAK,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,EAAE,UAAU,EAAY,MAAM,aAAa,CAAC;AAEnD;;;;;;;;GAQG;AACH,MAAM,MAAM,YAAY,GAAG,UAAU,GAAG,MAAM,GAAG,OAAO,GAAG,YAAY,CAAC;AAoBxE;;;;;;;;;GASG;AACH,qBAAa,QAAQ;;IAejB,QAAQ,CAAC,MAAM,EAAE,QAAQ,GAAG,IAAI;IAChC,QAAQ,CAAC,IAAI,EAAE,YAAY;IAV7B,4FAA4F;IAC5F,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;IAEhC;;;;OAIG;gBAEQ,MAAM,GAAE,QAAQ,GAAG,IAAW,EAC9B,IAAI,GAAE,YAA2B;IAiB5C,yFAAyF;IACzF,IAAI,SAAS,IAAI,OAAO,CAEvB;IAED;;;;;;;OAOG;IACH,QAAQ,CAAC,SAAS,EAAE,aAAa,CAAC,QAAQ,CAAC,GAAG,IAAI;IAgBlD;;;;;;;;;;OAUG;IACH,GAAG,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,aAAa,GAAG;QAAE,QAAQ,EAAE,IAAI,CAAA;KAAE,GAAG,CAAC,GAAG,IAAI;IAC9E,GAAG,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,CAAC;IA0FnD;;;;;;;;OAQG;IACH,OAAO,IAAI,IAAI;CAuBhB"}

package/dist/injector.js

@@ -0,0 +1,213 @@
+/**
+ * An injector: the providers it holds, how it resolves a token (up its parents, then the token's
+ * own factory), how it builds a service, and how it releases what it built.
+ *
+ * @module
+ */
+import { openReactiveScope, withReactiveScope } from '@fluixi/reactive/signal';
+import { InjectionError } from './errors.js';
+import { platformInjector } from './hierarchy.js';
+import { state } from './state.js';
+import { DestroyRef, INJECTOR } from './tokens.js';
+/**
+ * Holds providers and resolves tokens: from itself, then up its parents, then from the token's
+ * own factory. Each value is built once per injector, on first request, and released when the
+ * injector is disposed.
+ *
+ * Code rarely creates injectors: `provide()`, `provideRoot()` and `providePlatform()` place
+ * providers in the hierarchy, and `inject()` resolves from the current context. An `Injector` is
+ * handled directly to resolve outside a context (`get`), to scope work to it
+ * (`runInInjectionContext`), or in tests.
+ */
+export class Injector {
+    parent;
+    kind;
+    #records = new Map();
+    #created = [];
+    #hooks = [];
+    #destroyed = false;
+    /** The lifecycle of this injector, also answered by `inject(DestroyRef)` in its context. */
+    destroyRef;
+    /**
+     * @param parent - Where a token this injector does not hold is looked for next; `null` for the
+     *   top of a chain.
+     * @param kind - Where the injector sits in the hierarchy; see {@link InjectorKind}.
+     */
+    constructor(parent = null, kind = 'standalone') {
+        this.parent = parent;
+        this.kind = kind;
+        const self = this;
+        this.destroyRef = {
+            onDestroy(fn) {
+                self.#hooks.push(fn);
+                return () => {
+                    const i = self.#hooks.indexOf(fn);
+                    if (i >= 0)
+                        self.#hooks.splice(i, 1);
+                };
+            },
+            get destroyed() {
+                return self.#destroyed;
+            },
+        };
+    }
+    /** Whether {@link Injector.dispose} has run. A disposed injector refuses every `get`. */
+    get destroyed() {
+        return this.#destroyed;
+    }
+    /**
+     * Add providers to this injector. A provider for a token already held replaces it, except
+     * `multi` providers, which extend the token's list. A provider whose token has a test override
+     * is replaced by the override.
+     *
+     * @param providers - The providers to add, in order.
+     * @returns This injector, for chaining.
+     */
+    register(providers) {
+        for (const given of providers) {
+            const p = state.overrides.get(given.provide.id) ?? given;
+            if (p.multi) {
+                const rec = this.#records.get(p.provide.id);
+                if (rec?.multi) {
+                    rec.providers.push(p);
+                    rec.built = false;
+                }
+                else
+                    this.#records.set(p.provide.id, { multi: true, providers: [p], built: false, building: false, value: [] });
+            }
+            else {
+                this.#records.set(p.provide.id, { multi: false, provider: p, built: false, building: false, value: undefined });
+            }
+        }
+        return this;
+    }
+    get(token, options = {}) {
+        if (this.#destroyed)
+            throw new InjectionError(`[fluixi/di] "${token.name}" requested from a disposed injector.`, [...state.path, token.name]);
+        if (token.id === INJECTOR.id)
+            return this;
+        if (token.id === DestroyRef.id)
+            return this.destroyRef;
+        let inj = options.skipSelf ? this.parent : this;
+        while (inj) {
+            const rec = inj.#records.get(token.id);
+            if (rec)
+                return inj.#build(token, rec);
+            if (options.self || (options.host && inj.kind === 'owner'))
+                break;
+            inj = inj.parent;
+        }
+        const override = state.overrides.get(token.id);
+        if (override && !options.self)
+            return this.#home(token.scope).#fromProvider(token, override);
+        if (token.factory && !options.self && !options.host) {
+            return this.#home(token.scope).#fromProvider(token, { provide: token, useFactory: token.factory });
+        }
+        if (options.optional)
+            return null;
+        const path = [...state.path, token.name];
+        throw new InjectionError(`[fluixi/di] No provider for "${token.name}" (${path.join(' → ')}). Provide it in an app module, ` +
+            `with provide() or provideRoot(), or give the token a { factory }.`, path);
+    }
+    /** The injector a self-providing token builds in: the nearest root, or the platform. */
+    #home(scope) {
+        let inj = this;
+        if (scope === 'platform') {
+            while (inj.parent)
+                inj = inj.parent;
+            return inj.kind === 'platform' ? inj : platformInjector();
+        }
+        let probe = this;
+        while (probe) {
+            if (probe.kind === 'root')
+                return probe;
+            probe = probe.parent;
+        }
+        while (inj.parent && inj.parent.kind !== 'platform')
+            inj = inj.parent;
+        return inj;
+    }
+    #fromProvider(token, provider) {
+        let rec = this.#records.get(token.id);
+        if (!rec) {
+            rec = { multi: false, provider, built: false, building: false, value: undefined };
+            this.#records.set(token.id, rec);
+        }
+        return this.#build(token, rec);
+    }
+    #build(token, rec) {
+        if (rec.built)
+            return rec.value;
+        if (rec.building) {
+            const path = [...state.path, token.name];
+            throw new InjectionError(`[fluixi/di] Circular dependency: ${path.join(' → ')}.`, path);
+        }
+        rec.building = true;
+        state.path.push(token.name);
+        const previous = state.explicit;
+        // What the service injects resolves from where it is provided, as in Angular.
+        state.explicit = this;
+        try {
+            if (rec.multi) {
+                rec.value = rec.providers.map((p) => this.#make(token, p));
+            }
+            else {
+                const module = state.moduleScopes.get(rec.provider);
+                rec.value = module ? withReactiveScope(module, () => this.#make(token, rec.provider)) : this.#make(token, rec.provider);
+            }
+            rec.built = true;
+            return rec.value;
+        }
+        finally {
+            state.explicit = previous;
+            state.path.pop();
+            rec.building = false;
+        }
+    }
+    #make(token, p) {
+        if ('useValue' in p)
+            return p.useValue;
+        if ('useExisting' in p)
+            return this.get(p.useExisting);
+        const deps = (p.deps ?? []).map((d) => ('token' in d ? this.get(d.token, d) : this.get(d)));
+        const scope = openReactiveScope({ kind: 'service', name: token.name, detail: 'useClass' in p ? 'useClass' : 'useFactory' });
+        const value = withReactiveScope(scope, () => ('useClass' in p ? new p.useClass(...deps) : p.useFactory(...deps)));
+        this.#created.push(value);
+        return value;
+    }
+    /**
+     * Release this injector: run the hooks registered on its `DestroyRef`, latest first, then the
+     * `onDestroy()` method of every service it built, latest built first, then forget its
+     * providers. A hook or `onDestroy()` that throws is logged and the rest still run. Running it
+     * again does nothing.
+     *
+     * Component injectors are disposed when the component unmounts, request roots when the request
+     * ends; call it yourself only for injectors you created.
+     */
+    dispose() {
+        if (this.#destroyed)
+            return;
+        this.#destroyed = true;
+        const fail = (error) => console.error('[fluixi/di] a destroy hook threw:', error);
+        for (const hook of this.#hooks.splice(0).reverse()) {
+            try {
+                hook();
+            }
+            catch (error) {
+                fail(error);
+            }
+        }
+        for (const value of this.#created.splice(0).reverse()) {
+            const service = value;
+            if (service && typeof service.onDestroy === 'function') {
+                try {
+                    service.onDestroy();
+                }
+                catch (error) {
+                    fail(error);
+                }
+            }
+        }
+        this.#records.clear();
+    }
+}