@mmstack/di 19.3.1 → 19.3.2

package/fesm2022/mmstack-di.mjs

@@ -18,6 +18,43 @@ class ScopeRegistry {
 i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "19.2.19", ngImport: i0, type: ScopeRegistry, decorators: [{
             type: Injectable
         }] });
+/**
+ * Creates a specialized dependency injection scope.
+ *
+ * This utility allows you to create a localized dependency injection scope where you can
+ * register and provide shared state, services, or primitives that are bound to a specific
+ * component tree instead of the global root injector.
+ *
+ * @param name Optional name for the scope, primarily used for debugging and error messages.
+ * @returns A tuple containing `[registerFn, provideFn]`:
+ * - `registerFn`: A function to register a factory within the scope. Returns an injection function to retrieve the value.
+ * - `provideFn`: An Angular provider function that must be added to the `providers` array where the scope begins.
+ *
+ * @example
+ * ```ts
+ * const [registerInUserScope, provideUserScope] = createScope('UserScope');
+ *
+ * // Define a state/service bound to this scope
+ * const injectUserState = registerInUserScope(() => signal({ name: 'John Doe' }));
+ * const injectLogger = registerInUserScope(() => {
+ *  const globalLogger = inject(GlobalLogger);
+ *  const user = injectUserState();
+ *  return {
+ *    log: (msg: string) => globalLogger.log(`[USER MODULE (${user().name})]: ${msg}`),
+ *  }
+ * })
+ * @Component({
+ *   providers: [provideUserScope()] // provides a new instance of every dependency registered to the scope
+ * })
+ * class ParentComponent {}
+ *
+ * @Component({})
+ * class ChildComponent {
+ *   readonly userState = injectUserState();
+ *   readonly logger = injectLogger();
+ * }
+ * ```
+ */
 function createScope(name) {
     const token = new InjectionToken(name ?? '@mmstack/di/scope');
     const provideFn = () => ({

package/fesm2022/mmstack-di.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"mmstack-di.mjs","sources":["../../../../packages/di/src/lib/create-scope.ts","../../../../packages/di/src/lib/injectable.ts","../../../../packages/di/src/lib/root-injectable.ts","../../../../packages/di/src/mmstack-di.ts"],"sourcesContent":["import {\n  inject,\n  Injectable,\n  InjectionToken,\n  Injector,\n  runInInjectionContext,\n  type Provider,\n} from '@angular/core';\n\n@Injectable()\nexport class 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\n  getOrCreate<T>(factory: () => T): T {\n    if (this.registry.has(factory)) return this.registry.get(factory);\n\n    const val = runInInjectionContext(this.injector, factory);\n    this.registry.set(factory, val);\n    return val;\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) => {\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);\n    };\n  };\n\n  return [registerFn, provideFn] as const;\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 tree-shakable root singleton without a class.\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-scope.ts","../../../../packages/di/src/lib/injectable.ts","../../../../packages/di/src/lib/root-injectable.ts","../../../../packages/di/src/mmstack-di.ts"],"sourcesContent":["import {\n  inject,\n  Injectable,\n  InjectionToken,\n  Injector,\n  runInInjectionContext,\n  type Provider,\n} from '@angular/core';\n\n@Injectable()\nexport class 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\n  getOrCreate<T>(factory: () => T): T {\n    if (this.registry.has(factory)) return this.registry.get(factory);\n\n    const val = runInInjectionContext(this.injector, factory);\n    this.registry.set(factory, val);\n    return val;\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) => {\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);\n    };\n  };\n\n  return [registerFn, provideFn] as const;\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 tree-shakable root singleton without a class.\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":";;;MAUa,aAAa,CAAA;AACP,IAAA,QAAQ,GAAG,MAAM,CAAC,QAAQ,CAAC;;AAE3B,IAAA,QAAQ,GAAG,IAAI,GAAG,EAAiB;AAEpD,IAAA,WAAW,CAAI,OAAgB,EAAA;AAC7B,QAAA,IAAI,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC;YAAE,OAAO,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC;QAEjE,MAAM,GAAG,GAAG,qBAAqB,CAAC,IAAI,CAAC,QAAQ,EAAE,OAAO,CAAC;QACzD,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,OAAO,EAAE,GAAG,CAAC;AAC/B,QAAA,OAAO,GAAG;IACZ;wGAXW,aAAa,EAAA,IAAA,EAAA,EAAA,EAAA,MAAA,EAAA,EAAA,CAAA,eAAA,CAAA,UAAA,EAAA,CAAA;4GAAb,aAAa,EAAA,CAAA;;4FAAb,aAAa,EAAA,UAAA,EAAA,CAAA;kBADzB;;AAeD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAoCG;AACG,SAAU,WAAW,CAAC,IAAa,EAAA;IACvC,MAAM,KAAK,GAAG,IAAI,cAAc,CAAgB,IAAI,IAAI,mBAAmB,CAAC;AAE5E,IAAA,MAAM,SAAS,GAAG,OAAiB;AACjC,QAAA,OAAO,EAAE,KAAK;AACd,QAAA,QAAQ,EAAE,aAAa;AACxB,KAAA,CAAC;AAEF,IAAA,MAAM,UAAU,GAAG,CAAI,OAAgB,KAAI;AACzC,QAAA,OAAO,MAAK;AACV,YAAA,MAAM,QAAQ,GAAG,MAAM,CAAC,KAAK,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;AAClD,YAAA,IAAI,CAAC,QAAQ;gBACX,MAAM,IAAI,KAAK,CACb,CAAA,oBAAA,EAAuB,IAAI,IAAI,SAAS,CAAA,2CAAA,CAA6C,CACtF;AAEH,YAAA,OAAO,QAAQ,CAAC,WAAW,CAAC,OAAO,CAAC;AACtC,QAAA,CAAC;AACH,IAAA,CAAC;AAED,IAAA,OAAO,CAAC,UAAU,EAAE,SAAS,CAAU;AACzC;;ACqBM,SAAU,UAAU,CACxB,KAAa,EACb,GAA0B,EAAA;AAE1B,IAAA,MAAM,cAAc,GAAG,IAAI,cAAc,CAAI,KAAK,CAAC;IAEnD,MAAM,OAAO,GAAG,GAMH;AAEb,IAAA,IAAI,QAAQ,GAAyB,OAAO,EAAE,QAAQ;AAEtD,IAAA,MAAM,YAAY,GAChB,OAAO,EAAE,YAAY,KAAK,MAAM,OAAO,EAAE,QAAQ,IAAI,IAAI,CAAC;IAE5D,MAAM,UAAU,GAAG,MAAK;QACtB,IAAI,QAAQ,KAAK,SAAS;YAAE,QAAQ,GAAG,YAAY,EAAE;AACrD,QAAA,OAAO,QAAQ;AACjB,IAAA,CAAC;AAED,IAAA,MAAM,QAAQ,GAAG,CAAC,IAAsC,KAAI;AAC1D,QAAA,MAAM,QAAQ,GACZ,MAAM,CAAC,cAAc,EAAE;AACrB,YAAA,GAAG,IAAI;AACP,YAAA,QAAQ,EAAE,IAAI;SACf,CAAC,IAAI,UAAU,EAAE;AAEpB,QAAA,IAAI,QAAQ,KAAK,IAAI,IAAI,OAAO,EAAE,YAAY;AAC5C,YAAA,MAAM,IAAI,KAAK,CAAC,OAAO,CAAC,YAAY,CAAC;AAEvC,QAAA,OAAO,QAAa;AACtB,IAAA,CAAC;AAED,IAAA,MAAM,SAAS,GAAG,CAChB,SAAsC,EACtC,IAAY,KACA;QACZ,IAAI,IAAI,KAAK,SAAS;YACpB,OAAO;AACL,gBAAA,OAAO,EAAE,cAAc;AACvB,gBAAA,UAAU,EAAE,SAAkC;gBAC9C,IAAI;aACL;QAEH,OAAO;AACL,YAAA,OAAO,EAAE,cAAc;AACvB,YAAA,QAAQ,EAAE,SAAS;SACpB;AACH,IAAA,CAAC;AAED,IAAA,OAAO,CAAC,QAAQ,EAAE,SAAS,CAAC;AAC9B;;AC5JA;;;AAGG;AACG,SAAU,cAAc,CAC5B,OAAkC;AAClC,IAAa,EAAA;IAEb,MAAM,KAAK,GAAG,IAAI,cAAc,CAAI,IAAI,IAAI,6BAA6B,EAAE;AACzE,QAAA,UAAU,EAAE,MAAM;QAClB,OAAO,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;AACzC,KAAA,CAAC;AAEF,IAAA,OAAO,MAAM,MAAM,CAAC,KAAK,CAAC;AAC5B;;AChBA;;AAEG;;;;"}

package/lib/create-scope.d.ts

@@ -7,4 +7,41 @@ export declare class ScopeRegistry {
     static ɵfac: i0.ɵɵFactoryDeclaration<ScopeRegistry, never>;
     static ɵprov: i0.ɵɵInjectableDeclaration<ScopeRegistry>;
 }
+/**
+ * Creates a specialized dependency injection scope.
+ *
+ * This utility allows you to create a localized dependency injection scope where you can
+ * register and provide shared state, services, or primitives that are bound to a specific
+ * component tree instead of the global root injector.
+ *
+ * @param name Optional name for the scope, primarily used for debugging and error messages.
+ * @returns A tuple containing `[registerFn, provideFn]`:
+ * - `registerFn`: A function to register a factory within the scope. Returns an injection function to retrieve the value.
+ * - `provideFn`: An Angular provider function that must be added to the `providers` array where the scope begins.
+ *
+ * @example
+ * ```ts
+ * const [registerInUserScope, provideUserScope] = createScope('UserScope');
+ *
+ * // Define a state/service bound to this scope
+ * const injectUserState = registerInUserScope(() => signal({ name: 'John Doe' }));
+ * const injectLogger = registerInUserScope(() => {
+ *  const globalLogger = inject(GlobalLogger);
+ *  const user = injectUserState();
+ *  return {
+ *    log: (msg: string) => globalLogger.log(`[USER MODULE (${user().name})]: ${msg}`),
+ *  }
+ * })
+ * @Component({
+ *   providers: [provideUserScope()] // provides a new instance of every dependency registered to the scope
+ * })
+ * class ParentComponent {}
+ *
+ * @Component({})
+ * class ChildComponent {
+ *   readonly userState = injectUserState();
+ *   readonly logger = injectLogger();
+ * }
+ * ```
+ */
 export declare function createScope(name?: string): readonly [<T>(factory: () => T) => () => T, () => Provider];

package/package.json

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