@mmstack/di 19.3.4 → 19.3.5

package/fesm2022/mmstack-di.mjs

@@ -5,10 +5,24 @@ import { inject, Injector, runInInjectionContext, Injectable, InjectionToken } f
  * Captures an injection context and returns a runner function.
  *
  * This runner function allows you to execute callbacks inside the captured context at a later time.
- * It's really just a slight DX improvement over calling runInInjectionContext over and over
+ * It's really just a slight DX improvement over calling `runInInjectionContext` over and over.
  *
- * @param passedInjector An optional injector. If not provided, the current context's injector is pulled natively via `inject(Injector)`.
+ * @param injector An optional injector. If not provided, the current context's injector is pulled natively via `inject(Injector)`.
  * @returns A runner function that executes any provided callback within the captured context.
+ *
+ * @example
+ * ```ts
+ * @Component({ ... })
+ * class MyComponent {
+ *   // Capture at construction so we can run injection-context code later.
+ *   private readonly run = createRunInInjectionContext();
+ *
+ *   onClick = () => {
+ *     // `inject()` works here even though we're no longer in an injection context.
+ *     const value = this.run(() => inject(SomeService).doThing());
+ *   };
+ * }
+ * ```
  */
 function createRunInInjectionContext(injector) {
     if (!injector)
@@ -112,7 +126,17 @@ function injectLazy(token, options) {
     };
 }
 
-function injectable(token, opt) {
+function injectable(tokenOrFn, optOrString) {
+    const token = typeof tokenOrFn === 'string'
+        ? tokenOrFn
+        : typeof optOrString === 'string'
+            ? optOrString
+            : '@mmstack/di/injectable';
+    const opt = typeof tokenOrFn === 'function'
+        ? { lazyFallback: tokenOrFn }
+        : typeof optOrString === 'string'
+            ? undefined
+            : optOrString;
     const injectionToken = new InjectionToken(token);
     const options = opt;
     let fallback = options?.fallback;
@@ -147,8 +171,32 @@ function injectable(token, opt) {
 }
 
 /**
- * Creates a root-level singleton hooked into the global injector.
- * @example const injectUser = rootInjectable(() => ({ name: signal('John') }));
+ * Creates a root-level singleton wired into the global (`providedIn: 'root'`)
+ * injector. Returns a typed `inject()` helper — calling it anywhere in an
+ * injection context yields the same singleton instance. Useful for app-wide
+ * signal stores, configuration, or services that don't need per-component
+ * scoping.
+ *
+ * @typeParam T The type of the singleton value produced by the factory.
+ * @param factory Factory invoked once (lazily) to construct the singleton.
+ *   Receives the root `Injector` for cases where `inject()` isn't ergonomic.
+ * @param name Optional token name (used as the debug name).
+ * @returns A getter function that returns the same singleton instance on every call.
+ *
+ * @example
+ * ```ts
+ * // Define once at module scope:
+ * const injectCurrentUser = rootInjectable(
+ *   () => signal<User | null>(null),
+ *   'CurrentUser',
+ * );
+ *
+ * // Consume from anywhere in an injection context:
+ * @Component({ ... })
+ * class HeaderComponent {
+ *   readonly user = injectCurrentUser();
+ * }
+ * ```
  */
 function rootInjectable(factory, // Keeping the injector just in case
 name) {

package/fesm2022/mmstack-di.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"mmstack-di.mjs","sources":["../../../../packages/di/src/lib/create-run-in-injection-context.ts","../../../../packages/di/src/lib/create-scope.ts","../../../../packages/di/src/lib/inject-lazy.ts","../../../../packages/di/src/lib/injectable.ts","../../../../packages/di/src/lib/root-injectable.ts","../../../../packages/di/src/mmstack-di.ts"],"sourcesContent":["import { inject, Injector, runInInjectionContext } from '@angular/core';\n\n/**\n * Captures an injection context and returns a runner function.\n *\n * This runner function allows you to execute callbacks inside the captured context at a later time.\n * It's really just a slight DX improvement over calling runInInjectionContext over and over\n *\n * @param passedInjector An optional injector. If not provided, the current context's injector is pulled natively via `inject(Injector)`.\n * @returns A runner function that executes any provided callback within the captured context.\n */\n\nexport function createRunInInjectionContext(injector?: Injector) {\n  if (!injector) injector = inject(Injector);\n\n  return <T>(fn: () => T) => runInInjectionContext(injector, fn);\n}\n","import {\n  inject,\n  Injectable,\n  InjectionToken,\n  Injector,\n  runInInjectionContext,\n  type Provider,\n} from '@angular/core';\n\n@Injectable()\nclass ScopeRegistry {\n  private readonly injector = inject(Injector);\n  // eslint-disable-next-line @typescript-eslint/no-unsafe-function-type\n  private readonly registry = new Map<Function, any>();\n  // eslint-disable-next-line @typescript-eslint/no-unsafe-function-type\n  private readonly resolving = new Set<Function>();\n\n  getOrCreate<T>(\n    factory: () => T,\n    scopeName?: string,\n    factoryName?: string,\n  ): T {\n    if (this.registry.has(factory)) return this.registry.get(factory);\n    if (this.resolving.has(factory))\n      throw new Error(\n        `[mmstack/di]: Circular dependency detected in scope \"${scopeName ?? 'unknown'}\"${factoryName ? ` while resolving \"${factoryName}\"` : ''}`,\n      );\n\n    this.resolving.add(factory);\n    try {\n      const val = runInInjectionContext(this.injector, factory);\n      this.registry.set(factory, val);\n      return val;\n    } finally {\n      this.resolving.delete(factory);\n    }\n  }\n}\n\n/**\n * Creates a specialized dependency injection scope.\n *\n * This utility allows you to create a localized dependency injection scope where you can\n * register and provide shared state, services, or primitives that are bound to a specific\n * component tree instead of the global root injector.\n *\n * @param name Optional name for the scope, primarily used for debugging and error messages.\n * @returns A tuple containing `[registerFn, provideFn]`:\n * - `registerFn`: A function to register a factory within the scope. Returns an injection function to retrieve the value.\n * - `provideFn`: An Angular provider function that must be added to the `providers` array where the scope begins.\n *\n * @example\n * ```ts\n * const [registerInUserScope, provideUserScope] = createScope('UserScope');\n *\n * // Define a state/service bound to this scope\n * const injectUserState = registerInUserScope(() => signal({ name: 'John Doe' }));\n * const injectLogger = registerInUserScope(() => {\n *  const globalLogger = inject(GlobalLogger);\n *  const user = injectUserState();\n *  return {\n *    log: (msg: string) => globalLogger.log(`[USER MODULE (${user().name})]: ${msg}`),\n *  }\n * })\n * @Component({\n *   providers: [provideUserScope()] // provides a new instance of every dependency registered to the scope\n * })\n * class ParentComponent {}\n *\n * @Component({})\n * class ChildComponent {\n *   readonly userState = injectUserState();\n *   readonly logger = injectLogger();\n * }\n * ```\n */\nexport function createScope(name?: string) {\n  const token = new InjectionToken<ScopeRegistry>(name ?? '@mmstack/di/scope');\n\n  const provideFn = (): Provider => ({\n    provide: token,\n    useClass: ScopeRegistry,\n  });\n\n  const registerFn = <T>(factory: () => T, factoryName?: string) => {\n    return () => {\n      const registry = inject(token, { optional: true });\n      if (!registry)\n        throw new Error(\n          `[mmstack/di]: Scope ${name ?? 'unknown'} not found. Please make sure you provide it`,\n        );\n\n      return registry.getOrCreate(factory, name, factoryName);\n    };\n  };\n\n  return [registerFn, provideFn] as const;\n}\n","import {\n  inject,\n  Injector,\n  runInInjectionContext,\n  type HostAttributeToken,\n  type InjectOptions,\n  type ProviderToken,\n} from '@angular/core';\n\nconst UNINITIALIZED_SYMBOL = Symbol('@mmstack/di/inject-lazy/uninitialized');\n\ntype OptionalInjectOptions = Omit<InjectOptions, 'optional'> & {\n  optional: true;\n};\n\ntype NonOptionalInjectOptions = Omit<InjectOptions, 'optional'> & {\n  optional?: false;\n};\n\n/**\n * Defers the resolution and instantiation of a token until the returned getter function is called.\n * The resolved value is cached for subsequent calls.\n *\n * @param token The dependency token to inject.\n * @returns A getter function that returns the lazily resolved dependency.\n */\nexport function injectLazy<T>(token: ProviderToken<T>): () => T;\n\n/**\n * Defers the resolution and instantiation of a token until the returned getter function is called.\n * The resolved value is cached for subsequent calls.\n *\n * @param token The dependency token to inject.\n * @param options Injection options specifying optional resolution.\n * @returns A getter function that returns the lazily resolved dependency or null.\n */\nexport function injectLazy<T>(\n  token: ProviderToken<T>,\n  options: OptionalInjectOptions,\n): () => T | null;\n\n/**\n * Defers the resolution and instantiation of a token until the returned getter function is called.\n * The resolved value is cached for subsequent calls.\n *\n * @param token The dependency token to inject.\n * @param options Injection options specifying non-optional resolution.\n * @returns A getter function that returns the lazily resolved dependency.\n */\nexport function injectLazy<T>(\n  token: ProviderToken<T>,\n  options: NonOptionalInjectOptions,\n): () => T;\n\n/**\n * Defers the resolution and instantiation of a host attribute token until the returned getter function is called.\n * The resolved value is cached for subsequent calls.\n *\n * @param token The host attribute token to inject.\n * @returns A getter function that returns the lazily resolved attribute string.\n */\nexport function injectLazy(token: HostAttributeToken): () => string;\n\n/**\n * Defers the resolution and instantiation of a host attribute token until the returned getter function is called.\n * The resolved value is cached for subsequent calls.\n *\n * @param token The host attribute token to inject.\n * @param options Injection options specifying non-optional resolution.\n * @returns A getter function that returns the lazily resolved attribute string.\n */\nexport function injectLazy(\n  token: HostAttributeToken,\n  options?: {\n    optional?: false;\n  },\n): () => string;\n\n/**\n * Defers the resolution and instantiation of a host attribute token until the returned getter function is called.\n * The resolved value is cached for subsequent calls.\n *\n * @param token The host attribute token to inject.\n * @param options Injection options specifying optional resolution.\n * @returns A getter function that returns the lazily resolved attribute string or null.\n */\nexport function injectLazy(\n  token: HostAttributeToken,\n  options: {\n    optional: true;\n  },\n): () => string | null;\n\nexport function injectLazy<T>(\n  token: ProviderToken<T> | HostAttributeToken,\n  options?: Partial<OptionalInjectOptions | NonOptionalInjectOptions>,\n): () => T | string | null {\n  const injector = inject(Injector);\n  let instance: T | string | null | typeof UNINITIALIZED_SYMBOL =\n    UNINITIALIZED_SYMBOL;\n\n  return () => {\n    if (instance === UNINITIALIZED_SYMBOL)\n      instance = runInInjectionContext(injector, () => {\n        return options\n          ? inject(token as any, options as any)\n          : inject(token as any);\n      });\n\n    return instance as T | string | null;\n  };\n}\n","import {\n  inject,\n  InjectionToken,\n  type AbstractType,\n  type InjectOptions,\n  type Provider,\n  type Type,\n} from '@angular/core';\n\ntype ServiceType<T> =\n  T extends Type<infer U>\n    ? U\n    : T extends AbstractType<infer U>\n      ? U\n      : T extends InjectionToken<infer U>\n        ? U\n        : never;\n\ntype MapDeps<T extends readonly any[]> = {\n  [K in keyof T]: ServiceType<T[K]>;\n};\n\ntype ProviderFn<T> = {\n  (value: T): Provider;\n  <const TDeps extends any[]>(\n    fn: (...deps: MapDeps<TDeps>) => T,\n    deps: TDeps,\n  ): Provider;\n};\n\ntype InjectFns<T> = [\n  (opt?: Omit<InjectOptions, 'optional'>) => T,\n  ProviderFn<T>,\n];\n\ntype FallbackInjectableOptions<T> = {\n  /** Default value returned when the injectable is not provided */\n  fallback: T;\n};\n\ntype LazyFallbackInjectableOptions<T> = {\n  /** Function that returns a default value when the injectable is not provided. Useful for expensive defaults. */\n  lazyFallback: () => T;\n};\n\ntype ErrorMessageInjectableOptions = {\n  /** Error message thrown when the injectable is not provided */\n  errorMessage: string;\n};\n\ntype InjectableOptions<T> =\n  | FallbackInjectableOptions<T>\n  | LazyFallbackInjectableOptions<T>\n  | ErrorMessageInjectableOptions;\n\n/**\n * Creates a typed InjectionToken with inject and provide helper functions.\n *\n * @param token - Unique token identifier\n * @param opt - Optional configuration for fallback value or error message\n * @returns A tuple of [injectFn, provideFn] for type-safe dependency injection\n */\nexport function injectable<T>(token: string): InjectFns<T | null>;\n\n/**\n * Creates a typed InjectionToken with inject and provide helper functions.\n * Returns a fallback value when the injectable is not provided.\n *\n * @param token - Unique token identifier\n * @param opt - Configuration with fallback value\n * @returns A tuple of [injectFn, provideFn] for type-safe dependency injection\n */\nexport function injectable<T>(\n  token: string,\n  opt: FallbackInjectableOptions<T>,\n): InjectFns<T>;\n\n/**\n *\n * Creates a typed InjectionToken with inject and provide helper functions.\n * Returns a lazily evaluated fallback value when the injectable is not provided.\n *\n * @param token\n * @param opt\n */\nexport function injectable<T>(\n  token: string,\n  opt: LazyFallbackInjectableOptions<T>,\n): InjectFns<T>;\n\n/**\n * Creates a typed InjectionToken with inject and provide helper functions.\n * Throws an error with a custom message when the injectable is not provided.\n *\n * @param token - Unique token identifier\n * @param opt - Configuration with error message\n * @returns A tuple of [injectFn, provideFn] for type-safe dependency injection\n */\nexport function injectable<T>(\n  token: string,\n  opt: ErrorMessageInjectableOptions,\n): InjectFns<T>;\n\nexport function injectable<T>(\n  token: string,\n  opt?: InjectableOptions<T>,\n): InjectFns<T> {\n  const injectionToken = new InjectionToken<T>(token);\n\n  const options = opt as\n    | Partial<\n        FallbackInjectableOptions<T> &\n          LazyFallbackInjectableOptions<T> &\n          ErrorMessageInjectableOptions\n      >\n    | undefined;\n\n  let fallback: T | undefined | null = options?.fallback;\n\n  const initFallback =\n    options?.lazyFallback ?? (() => options?.fallback ?? null);\n\n  const fallbackFn = () => {\n    if (fallback === undefined) fallback = initFallback();\n    return fallback;\n  };\n\n  const injectFn = (iOpt?: Omit<InjectOptions, 'optional'>) => {\n    const injected =\n      inject(injectionToken, {\n        ...iOpt,\n        optional: true,\n      }) ?? fallbackFn();\n\n    if (injected === null && options?.errorMessage)\n      throw new Error(options.errorMessage);\n\n    return injected as T;\n  };\n\n  const provideFn = (\n    fnOrValue: T | ((...deps: any[]) => T),\n    deps?: any[],\n  ): Provider => {\n    if (deps !== undefined)\n      return {\n        provide: injectionToken,\n        useFactory: fnOrValue as (...args: any[]) => T,\n        deps,\n      };\n\n    return {\n      provide: injectionToken,\n      useValue: fnOrValue,\n    };\n  };\n\n  return [injectFn, provideFn];\n}\n","import { inject, InjectionToken, Injector } from '@angular/core';\n\n/**\n * Creates a root-level singleton hooked into the global injector.\n * @example const injectUser = rootInjectable(() => ({ name: signal('John') }));\n */\nexport function rootInjectable<T>(\n  factory: (injector: Injector) => T, // Keeping the injector just in case\n  name?: string,\n): () => T {\n  const token = new InjectionToken<T>(name ?? '@mmstack/di/root-injectable', {\n    providedIn: 'root',\n    factory: () => factory(inject(Injector)),\n  });\n\n  return () => inject(token);\n}\n","/**\n * Generated bundle index. Do not edit.\n */\n\nexport * from './index';\n"],"names":[],"mappings":"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"}
+{"version":3,"file":"mmstack-di.mjs","sources":["../../../../packages/di/src/lib/create-run-in-injection-context.ts","../../../../packages/di/src/lib/create-scope.ts","../../../../packages/di/src/lib/inject-lazy.ts","../../../../packages/di/src/lib/injectable.ts","../../../../packages/di/src/lib/root-injectable.ts","../../../../packages/di/src/mmstack-di.ts"],"sourcesContent":["import { inject, Injector, runInInjectionContext } from '@angular/core';\n\n/**\n * Captures an injection context and returns a runner function.\n *\n * This runner function allows you to execute callbacks inside the captured context at a later time.\n * It's really just a slight DX improvement over calling `runInInjectionContext` over and over.\n *\n * @param injector An optional injector. If not provided, the current context's injector is pulled natively via `inject(Injector)`.\n * @returns A runner function that executes any provided callback within the captured context.\n *\n * @example\n * ```ts\n * @Component({ ... })\n * class MyComponent {\n *   // Capture at construction so we can run injection-context code later.\n *   private readonly run = createRunInInjectionContext();\n *\n *   onClick = () => {\n *     // `inject()` works here even though we're no longer in an injection context.\n *     const value = this.run(() => inject(SomeService).doThing());\n *   };\n * }\n * ```\n */\nexport function createRunInInjectionContext(injector?: Injector) {\n  if (!injector) injector = inject(Injector);\n\n  return <T>(fn: () => T) => runInInjectionContext(injector, fn);\n}\n","import {\n  inject,\n  Injectable,\n  InjectionToken,\n  Injector,\n  runInInjectionContext,\n  type Provider,\n} from '@angular/core';\n\n@Injectable()\nclass ScopeRegistry {\n  private readonly injector = inject(Injector);\n  // eslint-disable-next-line @typescript-eslint/no-unsafe-function-type\n  private readonly registry = new Map<Function, any>();\n  // eslint-disable-next-line @typescript-eslint/no-unsafe-function-type\n  private readonly resolving = new Set<Function>();\n\n  getOrCreate<T>(\n    factory: () => T,\n    scopeName?: string,\n    factoryName?: string,\n  ): T {\n    if (this.registry.has(factory)) return this.registry.get(factory);\n    if (this.resolving.has(factory))\n      throw new Error(\n        `[mmstack/di]: Circular dependency detected in scope \"${scopeName ?? 'unknown'}\"${factoryName ? ` while resolving \"${factoryName}\"` : ''}`,\n      );\n\n    this.resolving.add(factory);\n    try {\n      const val = runInInjectionContext(this.injector, factory);\n      this.registry.set(factory, val);\n      return val;\n    } finally {\n      this.resolving.delete(factory);\n    }\n  }\n}\n\n/**\n * Creates a specialized dependency injection scope.\n *\n * This utility allows you to create a localized dependency injection scope where you can\n * register and provide shared state, services, or primitives that are bound to a specific\n * component tree instead of the global root injector.\n *\n * @param name Optional name for the scope, primarily used for debugging and error messages.\n * @returns A tuple containing `[registerFn, provideFn]`:\n * - `registerFn`: A function to register a factory within the scope. Returns an injection function to retrieve the value.\n * - `provideFn`: An Angular provider function that must be added to the `providers` array where the scope begins.\n *\n * @example\n * ```ts\n * const [registerInUserScope, provideUserScope] = createScope('UserScope');\n *\n * // Define a state/service bound to this scope\n * const injectUserState = registerInUserScope(() => signal({ name: 'John Doe' }));\n * const injectLogger = registerInUserScope(() => {\n *  const globalLogger = inject(GlobalLogger);\n *  const user = injectUserState();\n *  return {\n *    log: (msg: string) => globalLogger.log(`[USER MODULE (${user().name})]: ${msg}`),\n *  }\n * })\n * @Component({\n *   providers: [provideUserScope()] // provides a new instance of every dependency registered to the scope\n * })\n * class ParentComponent {}\n *\n * @Component({})\n * class ChildComponent {\n *   readonly userState = injectUserState();\n *   readonly logger = injectLogger();\n * }\n * ```\n */\nexport function createScope(name?: string) {\n  const token = new InjectionToken<ScopeRegistry>(name ?? '@mmstack/di/scope');\n\n  const provideFn = (): Provider => ({\n    provide: token,\n    useClass: ScopeRegistry,\n  });\n\n  const registerFn = <T>(factory: () => T, factoryName?: string) => {\n    return () => {\n      const registry = inject(token, { optional: true });\n      if (!registry)\n        throw new Error(\n          `[mmstack/di]: Scope ${name ?? 'unknown'} not found. Please make sure you provide it`,\n        );\n\n      return registry.getOrCreate(factory, name, factoryName);\n    };\n  };\n\n  return [registerFn, provideFn] as const;\n}\n","import {\n  inject,\n  Injector,\n  runInInjectionContext,\n  type HostAttributeToken,\n  type InjectOptions,\n  type ProviderToken,\n} from '@angular/core';\n\nconst UNINITIALIZED_SYMBOL = Symbol('@mmstack/di/inject-lazy/uninitialized');\n\ntype OptionalInjectOptions = Omit<InjectOptions, 'optional'> & {\n  optional: true;\n};\n\ntype NonOptionalInjectOptions = Omit<InjectOptions, 'optional'> & {\n  optional?: false;\n};\n\n/**\n * Defers the resolution and instantiation of a token until the returned getter\n * function is called. The resolved value is cached for subsequent calls — the\n * actual `inject()` call happens at most once, on first access.\n *\n * Useful for services that are expensive to construct, or for breaking\n * circular dependency chains in component fields.\n *\n * @typeParam T The type of the resolved dependency.\n * @param token The dependency token to inject.\n * @returns A getter function that returns the lazily resolved dependency.\n *\n * @example\n * ```ts\n * @Component({ ... })\n * class MyComponent {\n *   // Injection context captured at construction; HeavyService is NOT instantiated yet.\n *   private readonly getHeavy = injectLazy(HeavyService);\n *\n *   onClick = () => {\n *     // First access constructs HeavyService and caches it; subsequent calls return the same instance.\n *     this.getHeavy().doExpensiveThing();\n *   };\n * }\n * ```\n */\nexport function injectLazy<T>(token: ProviderToken<T>): () => T;\n\n/**\n * Defers the resolution and instantiation of an optional token until the\n * returned getter is called. Returns `null` (not undefined) when the token\n * isn't provided, matching Angular's `inject(token, { optional: true })`\n * semantics.\n *\n * @typeParam T The type of the resolved dependency.\n * @param token The dependency token to inject.\n * @param options Injection options specifying optional resolution.\n * @returns A getter function that returns the lazily resolved dependency or `null`.\n *\n * @example\n * ```ts\n * const getAnalytics = injectLazy(AnalyticsService, { optional: true });\n *\n * function trackEvent(name: string) {\n *   getAnalytics()?.track(name); // safely no-op if Analytics isn't provided\n * }\n * ```\n */\nexport function injectLazy<T>(\n  token: ProviderToken<T>,\n  options: OptionalInjectOptions,\n): () => T | null;\n\n/**\n * Defers the resolution and instantiation of a token until the returned getter function is called.\n * The resolved value is cached for subsequent calls.\n *\n * @param token The dependency token to inject.\n * @param options Injection options specifying non-optional resolution.\n * @returns A getter function that returns the lazily resolved dependency.\n */\nexport function injectLazy<T>(\n  token: ProviderToken<T>,\n  options: NonOptionalInjectOptions,\n): () => T;\n\n/**\n * Defers reading a host attribute until the returned getter is called.\n * Mirrors {@link HostAttributeToken} resolution but lazily.\n *\n * @param token The host attribute token to inject.\n * @returns A getter function that returns the lazily resolved attribute string.\n *\n * @example\n * ```ts\n * @Directive({ ... })\n * class MyDirective {\n *   private readonly getRole = injectLazy(new HostAttributeToken('role'));\n *   // Only reads the DOM attribute when first accessed.\n * }\n * ```\n */\nexport function injectLazy(token: HostAttributeToken): () => string;\n\n/**\n * Defers the resolution and instantiation of a host attribute token until the returned getter function is called.\n * The resolved value is cached for subsequent calls.\n *\n * @param token The host attribute token to inject.\n * @param options Injection options specifying non-optional resolution.\n * @returns A getter function that returns the lazily resolved attribute string.\n */\nexport function injectLazy(\n  token: HostAttributeToken,\n  options?: {\n    optional?: false;\n  },\n): () => string;\n\n/**\n * Defers the resolution and instantiation of a host attribute token until the returned getter function is called.\n * The resolved value is cached for subsequent calls.\n *\n * @param token The host attribute token to inject.\n * @param options Injection options specifying optional resolution.\n * @returns A getter function that returns the lazily resolved attribute string or null.\n */\nexport function injectLazy(\n  token: HostAttributeToken,\n  options: {\n    optional: true;\n  },\n): () => string | null;\n\nexport function injectLazy<T>(\n  token: ProviderToken<T> | HostAttributeToken,\n  options?: Partial<OptionalInjectOptions | NonOptionalInjectOptions>,\n): () => T | string | null {\n  const injector = inject(Injector);\n  let instance: T | string | null | typeof UNINITIALIZED_SYMBOL =\n    UNINITIALIZED_SYMBOL;\n\n  return () => {\n    if (instance === UNINITIALIZED_SYMBOL)\n      instance = runInInjectionContext(injector, () => {\n        return options\n          ? inject(token as any, options as any)\n          : inject(token as any);\n      });\n\n    return instance as T | string | null;\n  };\n}\n","import {\n  inject,\n  InjectionToken,\n  type AbstractType,\n  type InjectOptions,\n  type Provider,\n  type Type,\n} from '@angular/core';\n\ntype ServiceType<T> =\n  T extends Type<infer U>\n    ? U\n    : T extends AbstractType<infer U>\n      ? U\n      : T extends InjectionToken<infer U>\n        ? U\n        : never;\n\ntype MapDeps<T extends readonly any[]> = {\n  [K in keyof T]: ServiceType<T[K]>;\n};\n\ntype ProviderFn<T> = {\n  (value: T): Provider;\n  <const TDeps extends any[]>(\n    fn: (...deps: MapDeps<TDeps>) => T,\n    deps: TDeps,\n  ): Provider;\n};\n\ntype InjectFns<T> = [\n  (opt?: Omit<InjectOptions, 'optional'>) => T,\n  ProviderFn<T>,\n];\n\ntype FallbackInjectableOptions<T> = {\n  /** Default value returned when the injectable is not provided */\n  fallback: T;\n};\n\ntype LazyFallbackInjectableOptions<T> = {\n  /** Function that returns a default value when the injectable is not provided. Useful for expensive defaults. */\n  lazyFallback: () => T;\n};\n\ntype ErrorMessageInjectableOptions = {\n  /** Error message thrown when the injectable is not provided */\n  errorMessage: string;\n};\n\ntype InjectableOptions<T> =\n  | FallbackInjectableOptions<T>\n  | LazyFallbackInjectableOptions<T>\n  | ErrorMessageInjectableOptions;\n\n/**\n * Creates a typed `InjectionToken` plus a tuple of `[inject, provide]` helpers.\n * Without configuration, the inject helper returns `T | null` when the token\n * hasn't been provided.\n *\n * @typeParam T The type of the value the token holds.\n * @param token Unique token identifier (used as the token's debug name).\n * @returns A tuple `[injectFn, provideFn]` for type-safe dependency injection.\n *\n * @example\n * ```ts\n * const [injectTheme, provideTheme] = injectable<'dark' | 'light'>('Theme');\n *\n * // In a provider scope:\n * bootstrapApplication(App, { providers: [provideTheme('dark')] });\n *\n * // In a consumer:\n * const theme = injectTheme(); // 'dark' | 'light' | null\n * ```\n */\nexport function injectable<T>(token: string): InjectFns<T | null>;\n\n/**\n * Creates a typed `InjectionToken` with an eager fallback value. The inject\n * helper returns `T` (never `null`): when the token isn't provided, the\n * configured `fallback` is returned.\n *\n * @typeParam T The type of the value the token holds.\n * @param token Unique token identifier.\n * @param opt Configuration with `fallback` value (evaluated immediately).\n * @returns A tuple `[injectFn, provideFn]` for type-safe dependency injection.\n *\n * @example\n * ```ts\n * const [injectConfig, provideConfig] = injectable<Config>('Config', {\n *   fallback: { apiUrl: 'https://api.example.com', retries: 3 },\n * });\n *\n * const config = injectConfig(); // Always Config — never null\n * ```\n */\nexport function injectable<T>(\n  token: string,\n  opt: FallbackInjectableOptions<T>,\n): InjectFns<T>;\n\n/**\n * Creates a typed `InjectionToken` with a *lazy* fallback. The fallback\n * factory runs on first access (and only once) when the token isn't\n * provided — useful when constructing the default is expensive or has its\n * own dependencies.\n *\n * @typeParam T The type of the value the token holds.\n * @param token Unique token identifier.\n * @param opt Configuration with `lazyFallback` factory (deferred until needed).\n * @returns A tuple `[injectFn, provideFn]` for type-safe dependency injection.\n *\n * @example\n * ```ts\n * const [injectCache, provideCache] = injectable<Cache>('Cache', {\n *   lazyFallback: () => new Cache({ size: 1000 }), // only constructed if no override is provided\n * });\n * ```\n */\nexport function injectable<T>(\n  token: string,\n  opt: LazyFallbackInjectableOptions<T>,\n): InjectFns<T>;\n\n/**\n * Creates a typed `InjectionToken` that throws a custom error message when\n * the token isn't provided. Use this when \"no provider\" is genuinely a bug\n * rather than a permitted state.\n *\n * @typeParam T The type of the value the token holds.\n * @param token Unique token identifier.\n * @param opt Configuration with `errorMessage` to throw on missing provider.\n * @returns A tuple `[injectFn, provideFn]` for type-safe dependency injection.\n *\n * @example\n * ```ts\n * const [injectAuth, provideAuth] = injectable<AuthService>('Auth', {\n *   errorMessage: 'AuthService must be provided before any consumer reads it',\n * });\n *\n * const auth = injectAuth(); // throws if no provideAuth(...) is in scope\n * ```\n */\nexport function injectable<T>(\n  token: string,\n  opt: ErrorMessageInjectableOptions,\n): InjectFns<T>;\n\n/**\n * Creates a typed `InjectionToken` with a baked-in factory used as the lazy\n * fallback. The factory runs in an injection context, so it can use\n * `inject()` to compose dependencies.\n *\n * @typeParam T The type of the value the factory produces.\n * @param fn Factory function evaluated lazily on first inject if no override is provided.\n * @param name Optional token name (used as the debug name).\n * @returns A tuple `[injectFn, provideFn]` for type-safe dependency injection.\n *\n * @example\n * ```ts\n * const [injectUser, provideUser] = injectable(\n *   () => inject(HttpClient).get<User>('/api/me'),\n *   'CurrentUser',\n * );\n * ```\n */\nexport function injectable<T>(fn: () => T, name?: string): InjectFns<T>;\n\nexport function injectable<T>(\n  tokenOrFn: string | (() => T),\n  optOrString?: InjectableOptions<T> | string,\n): InjectFns<T> {\n  const token =\n    typeof tokenOrFn === 'string'\n      ? tokenOrFn\n      : typeof optOrString === 'string'\n        ? optOrString\n        : '@mmstack/di/injectable';\n\n  const opt =\n    typeof tokenOrFn === 'function'\n      ? { lazyFallback: tokenOrFn }\n      : typeof optOrString === 'string'\n        ? undefined\n        : optOrString;\n\n  const injectionToken = new InjectionToken<T>(token);\n\n  const options = opt as\n    | Partial<\n        FallbackInjectableOptions<T> &\n          LazyFallbackInjectableOptions<T> &\n          ErrorMessageInjectableOptions\n      >\n    | undefined;\n\n  let fallback: T | undefined | null = options?.fallback;\n\n  const initFallback =\n    options?.lazyFallback ?? (() => options?.fallback ?? null);\n\n  const fallbackFn = () => {\n    if (fallback === undefined) fallback = initFallback();\n    return fallback;\n  };\n\n  const injectFn = (iOpt?: Omit<InjectOptions, 'optional'>) => {\n    const injected =\n      inject(injectionToken, {\n        ...iOpt,\n        optional: true,\n      }) ?? fallbackFn();\n\n    if (injected === null && options?.errorMessage)\n      throw new Error(options.errorMessage);\n\n    return injected as T;\n  };\n\n  const provideFn = (\n    fnOrValue: T | ((...deps: any[]) => T),\n    deps?: any[],\n  ): Provider => {\n    if (deps !== undefined)\n      return {\n        provide: injectionToken,\n        useFactory: fnOrValue as (...args: any[]) => T,\n        deps,\n      };\n\n    return {\n      provide: injectionToken,\n      useValue: fnOrValue,\n    };\n  };\n\n  return [injectFn, provideFn];\n}\n","import { inject, InjectionToken, Injector } from '@angular/core';\n\n/**\n * Creates a root-level singleton wired into the global (`providedIn: 'root'`)\n * injector. Returns a typed `inject()` helper — calling it anywhere in an\n * injection context yields the same singleton instance. Useful for app-wide\n * signal stores, configuration, or services that don't need per-component\n * scoping.\n *\n * @typeParam T The type of the singleton value produced by the factory.\n * @param factory Factory invoked once (lazily) to construct the singleton.\n *   Receives the root `Injector` for cases where `inject()` isn't ergonomic.\n * @param name Optional token name (used as the debug name).\n * @returns A getter function that returns the same singleton instance on every call.\n *\n * @example\n * ```ts\n * // Define once at module scope:\n * const injectCurrentUser = rootInjectable(\n *   () => signal<User | null>(null),\n *   'CurrentUser',\n * );\n *\n * // Consume from anywhere in an injection context:\n * @Component({ ... })\n * class HeaderComponent {\n *   readonly user = injectCurrentUser();\n * }\n * ```\n */\nexport function rootInjectable<T>(\n  factory: (injector: Injector) => T, // Keeping the injector just in case\n  name?: string,\n): () => T {\n  const token = new InjectionToken<T>(name ?? '@mmstack/di/root-injectable', {\n    providedIn: 'root',\n    factory: () => factory(inject(Injector)),\n  });\n\n  return () => inject(token);\n}\n","/**\n * Generated bundle index. Do not edit.\n */\n\nexport * from './index';\n"],"names":[],"mappings":"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"}

package/lib/create-run-in-injection-context.d.ts

@@ -3,9 +3,23 @@ import { Injector } from '@angular/core';
  * Captures an injection context and returns a runner function.
  *
  * This runner function allows you to execute callbacks inside the captured context at a later time.
- * It's really just a slight DX improvement over calling runInInjectionContext over and over
+ * It's really just a slight DX improvement over calling `runInInjectionContext` over and over.
  *
- * @param passedInjector An optional injector. If not provided, the current context's injector is pulled natively via `inject(Injector)`.
+ * @param injector An optional injector. If not provided, the current context's injector is pulled natively via `inject(Injector)`.
  * @returns A runner function that executes any provided callback within the captured context.
+ *
+ * @example
+ * ```ts
+ * @Component({ ... })
+ * class MyComponent {
+ *   // Capture at construction so we can run injection-context code later.
+ *   private readonly run = createRunInInjectionContext();
+ *
+ *   onClick = () => {
+ *     // `inject()` works here even though we're no longer in an injection context.
+ *     const value = this.run(() => inject(SomeService).doThing());
+ *   };
+ * }
+ * ```
  */
 export declare function createRunInInjectionContext(injector?: Injector): <T>(fn: () => T) => T;

package/lib/inject-lazy.d.ts

@@ -6,20 +6,51 @@ type NonOptionalInjectOptions = Omit<InjectOptions, 'optional'> & {
     optional?: false;
 };
 /**
- * Defers the resolution and instantiation of a token until the returned getter function is called.
- * The resolved value is cached for subsequent calls.
+ * Defers the resolution and instantiation of a token until the returned getter
+ * function is called. The resolved value is cached for subsequent calls — the
+ * actual `inject()` call happens at most once, on first access.
+ *
+ * Useful for services that are expensive to construct, or for breaking
+ * circular dependency chains in component fields.
  *
+ * @typeParam T The type of the resolved dependency.
  * @param token The dependency token to inject.
  * @returns A getter function that returns the lazily resolved dependency.
+ *
+ * @example
+ * ```ts
+ * @Component({ ... })
+ * class MyComponent {
+ *   // Injection context captured at construction; HeavyService is NOT instantiated yet.
+ *   private readonly getHeavy = injectLazy(HeavyService);
+ *
+ *   onClick = () => {
+ *     // First access constructs HeavyService and caches it; subsequent calls return the same instance.
+ *     this.getHeavy().doExpensiveThing();
+ *   };
+ * }
+ * ```
  */
 export declare function injectLazy<T>(token: ProviderToken<T>): () => T;
 /**
- * Defers the resolution and instantiation of a token until the returned getter function is called.
- * The resolved value is cached for subsequent calls.
+ * Defers the resolution and instantiation of an optional token until the
+ * returned getter is called. Returns `null` (not undefined) when the token
+ * isn't provided, matching Angular's `inject(token, { optional: true })`
+ * semantics.
  *
+ * @typeParam T The type of the resolved dependency.
  * @param token The dependency token to inject.
  * @param options Injection options specifying optional resolution.
- * @returns A getter function that returns the lazily resolved dependency or null.
+ * @returns A getter function that returns the lazily resolved dependency or `null`.
+ *
+ * @example
+ * ```ts
+ * const getAnalytics = injectLazy(AnalyticsService, { optional: true });
+ *
+ * function trackEvent(name: string) {
+ *   getAnalytics()?.track(name); // safely no-op if Analytics isn't provided
+ * }
+ * ```
  */
 export declare function injectLazy<T>(token: ProviderToken<T>, options: OptionalInjectOptions): () => T | null;
 /**
@@ -32,11 +63,20 @@ export declare function injectLazy<T>(token: ProviderToken<T>, options: Optional
  */
 export declare function injectLazy<T>(token: ProviderToken<T>, options: NonOptionalInjectOptions): () => T;
 /**
- * Defers the resolution and instantiation of a host attribute token until the returned getter function is called.
- * The resolved value is cached for subsequent calls.
+ * Defers reading a host attribute until the returned getter is called.
+ * Mirrors {@link HostAttributeToken} resolution but lazily.
  *
  * @param token The host attribute token to inject.
  * @returns A getter function that returns the lazily resolved attribute string.
+ *
+ * @example
+ * ```ts
+ * @Directive({ ... })
+ * class MyDirective {
+ *   private readonly getRole = injectLazy(new HostAttributeToken('role'));
+ *   // Only reads the DOM attribute when first accessed.
+ * }
+ * ```
  */
 export declare function injectLazy(token: HostAttributeToken): () => string;
 /**

package/lib/injectable.d.ts

@@ -24,38 +24,102 @@ type ErrorMessageInjectableOptions = {
     errorMessage: string;
 };
 /**
- * Creates a typed InjectionToken with inject and provide helper functions.
+ * Creates a typed `InjectionToken` plus a tuple of `[inject, provide]` helpers.
+ * Without configuration, the inject helper returns `T | null` when the token
+ * hasn't been provided.
  *
- * @param token - Unique token identifier
- * @param opt - Optional configuration for fallback value or error message
- * @returns A tuple of [injectFn, provideFn] for type-safe dependency injection
+ * @typeParam T The type of the value the token holds.
+ * @param token Unique token identifier (used as the token's debug name).
+ * @returns A tuple `[injectFn, provideFn]` for type-safe dependency injection.
+ *
+ * @example
+ * ```ts
+ * const [injectTheme, provideTheme] = injectable<'dark' | 'light'>('Theme');
+ *
+ * // In a provider scope:
+ * bootstrapApplication(App, { providers: [provideTheme('dark')] });
+ *
+ * // In a consumer:
+ * const theme = injectTheme(); // 'dark' | 'light' | null
+ * ```
  */
 export declare function injectable<T>(token: string): InjectFns<T | null>;
 /**
- * Creates a typed InjectionToken with inject and provide helper functions.
- * Returns a fallback value when the injectable is not provided.
+ * Creates a typed `InjectionToken` with an eager fallback value. The inject
+ * helper returns `T` (never `null`): when the token isn't provided, the
+ * configured `fallback` is returned.
  *
- * @param token - Unique token identifier
- * @param opt - Configuration with fallback value
- * @returns A tuple of [injectFn, provideFn] for type-safe dependency injection
+ * @typeParam T The type of the value the token holds.
+ * @param token Unique token identifier.
+ * @param opt Configuration with `fallback` value (evaluated immediately).
+ * @returns A tuple `[injectFn, provideFn]` for type-safe dependency injection.
+ *
+ * @example
+ * ```ts
+ * const [injectConfig, provideConfig] = injectable<Config>('Config', {
+ *   fallback: { apiUrl: 'https://api.example.com', retries: 3 },
+ * });
+ *
+ * const config = injectConfig(); // Always Config — never null
+ * ```
  */
 export declare function injectable<T>(token: string, opt: FallbackInjectableOptions<T>): InjectFns<T>;
 /**
+ * Creates a typed `InjectionToken` with a *lazy* fallback. The fallback
+ * factory runs on first access (and only once) when the token isn't
+ * provided — useful when constructing the default is expensive or has its
+ * own dependencies.
  *
- * Creates a typed InjectionToken with inject and provide helper functions.
- * Returns a lazily evaluated fallback value when the injectable is not provided.
+ * @typeParam T The type of the value the token holds.
+ * @param token Unique token identifier.
+ * @param opt Configuration with `lazyFallback` factory (deferred until needed).
+ * @returns A tuple `[injectFn, provideFn]` for type-safe dependency injection.
  *
- * @param token
- * @param opt
+ * @example
+ * ```ts
+ * const [injectCache, provideCache] = injectable<Cache>('Cache', {
+ *   lazyFallback: () => new Cache({ size: 1000 }), // only constructed if no override is provided
+ * });
+ * ```
  */
 export declare function injectable<T>(token: string, opt: LazyFallbackInjectableOptions<T>): InjectFns<T>;
 /**
- * Creates a typed InjectionToken with inject and provide helper functions.
- * Throws an error with a custom message when the injectable is not provided.
+ * Creates a typed `InjectionToken` that throws a custom error message when
+ * the token isn't provided. Use this when "no provider" is genuinely a bug
+ * rather than a permitted state.
+ *
+ * @typeParam T The type of the value the token holds.
+ * @param token Unique token identifier.
+ * @param opt Configuration with `errorMessage` to throw on missing provider.
+ * @returns A tuple `[injectFn, provideFn]` for type-safe dependency injection.
  *
- * @param token - Unique token identifier
- * @param opt - Configuration with error message
- * @returns A tuple of [injectFn, provideFn] for type-safe dependency injection
+ * @example
+ * ```ts
+ * const [injectAuth, provideAuth] = injectable<AuthService>('Auth', {
+ *   errorMessage: 'AuthService must be provided before any consumer reads it',
+ * });
+ *
+ * const auth = injectAuth(); // throws if no provideAuth(...) is in scope
+ * ```
  */
 export declare function injectable<T>(token: string, opt: ErrorMessageInjectableOptions): InjectFns<T>;
+/**
+ * Creates a typed `InjectionToken` with a baked-in factory used as the lazy
+ * fallback. The factory runs in an injection context, so it can use
+ * `inject()` to compose dependencies.
+ *
+ * @typeParam T The type of the value the factory produces.
+ * @param fn Factory function evaluated lazily on first inject if no override is provided.
+ * @param name Optional token name (used as the debug name).
+ * @returns A tuple `[injectFn, provideFn]` for type-safe dependency injection.
+ *
+ * @example
+ * ```ts
+ * const [injectUser, provideUser] = injectable(
+ *   () => inject(HttpClient).get<User>('/api/me'),
+ *   'CurrentUser',
+ * );
+ * ```
+ */
+export declare function injectable<T>(fn: () => T, name?: string): InjectFns<T>;
 export {};

package/lib/root-injectable.d.ts

@@ -1,7 +1,31 @@
 import { Injector } from '@angular/core';
 /**
- * Creates a root-level singleton hooked into the global injector.
- * @example const injectUser = rootInjectable(() => ({ name: signal('John') }));
+ * Creates a root-level singleton wired into the global (`providedIn: 'root'`)
+ * injector. Returns a typed `inject()` helper — calling it anywhere in an
+ * injection context yields the same singleton instance. Useful for app-wide
+ * signal stores, configuration, or services that don't need per-component
+ * scoping.
+ *
+ * @typeParam T The type of the singleton value produced by the factory.
+ * @param factory Factory invoked once (lazily) to construct the singleton.
+ *   Receives the root `Injector` for cases where `inject()` isn't ergonomic.
+ * @param name Optional token name (used as the debug name).
+ * @returns A getter function that returns the same singleton instance on every call.
+ *
+ * @example
+ * ```ts
+ * // Define once at module scope:
+ * const injectCurrentUser = rootInjectable(
+ *   () => signal<User | null>(null),
+ *   'CurrentUser',
+ * );
+ *
+ * // Consume from anywhere in an injection context:
+ * @Component({ ... })
+ * class HeaderComponent {
+ *   readonly user = injectCurrentUser();
+ * }
+ * ```
  */
 export declare function rootInjectable<T>(factory: (injector: Injector) => T, // Keeping the injector just in case
 name?: string): () => T;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mmstack/di",
-  "version": "19.3.4",
+  "version": "19.3.5",
   "keywords": [
     "angular",
     "dependency injection",