@mmstack/di 19.3.0 → 19.3.2

package/README.md

@@ -17,6 +17,7 @@ This library provides the following utilities:
 
 - `injectable` - Creates a typed InjectionToken with inject and provide helper functions for type-safe dependency injection.
 - `rootInjectable` - Creates a lazily-initialized root-level injectable that maintains a singleton instance.
+- `createScope` - Creates a dependency injection scope that caches singletons based on the factory function.
 
 ---
 
@@ -381,6 +382,49 @@ export class NavbarComponent {
 
 ---
 
+## createScope
+
+Creates a dependency injection scope using a dynamic `InjectionToken` representing a caching registry. Factories executed within the scope run in the Angular injection context and their results are cached, effectively creating scoped singletons, that are destroyed when the scoped provider is. It returns a tuple of `[injectable, provider]`.
+
+### Basic Usage
+
+```typescript
+import { Component, inject } from '@angular/core';
+import { createScope } from '@mmstack/di';
+
+// Create the scope
+const [injectableFeatureItem, provideFeatureScope] = createScope('FeatureScope');
+
+// Provide the scope at a specific component level boundary
+@Component({
+  selector: 'app-feature',
+  providers: [provideFeatureScope()],
+  template: `<app-child></app-child>`,
+})
+export class FeatureComponent {}
+
+// Use the scope to register an item factory
+// The factory will run in the injection context so you can use inject()
+const useFeatureItem = injectableFeatureItem(() => {
+  const someDep = inject(SomeDependency);
+  return {
+    id: Math.random(),
+    doWork: () => someDep.work(),
+  };
+});
+
+@Component({
+  selector: 'app-child',
+  template: `<div>Child Item ID: {{ item.id }}</div>`,
+})
+export class ChildComponent {
+  // Always returns the exact same instance for this specific scope provider boundary
+  item = useFeatureItem();
+}
+```
+
+---
+
 ## License
 
 MIT © [Miha Mulec](https://github.com/mihajm)

package/fesm2022/mmstack-di.mjs

@@ -1,5 +1,76 @@
 import * as i0 from '@angular/core';
-import { InjectionToken, inject, Injector, runInInjectionContext, Injectable } from '@angular/core';
+import { inject, Injector, runInInjectionContext, Injectable, InjectionToken } from '@angular/core';
+
+class ScopeRegistry {
+    injector = inject(Injector);
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
+    registry = new Map();
+    getOrCreate(factory) {
+        if (this.registry.has(factory))
+            return this.registry.get(factory);
+        const val = runInInjectionContext(this.injector, factory);
+        this.registry.set(factory, val);
+        return val;
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "19.2.19", ngImport: i0, type: ScopeRegistry, deps: [], target: i0.ɵɵFactoryTarget.Injectable });
+    static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "19.2.19", ngImport: i0, type: 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 = () => ({
+        provide: token,
+        useClass: ScopeRegistry,
+    });
+    const registerFn = (factory) => {
+        return () => {
+            const registry = inject(token, { optional: true });
+            if (!registry)
+                throw new Error(`[mmstack/di]: Scope ${name ?? 'unknown'} not found. Please make sure you provide it`);
+            return registry.getOrCreate(factory);
+        };
+    };
+    return [registerFn, provideFn];
+}
 
 function injectable(token, opt) {
     const injectionToken = new InjectionToken(token);
@@ -35,59 +106,22 @@ function injectable(token, opt) {
     return [injectFn, provideFn];
 }
 
-function generateID() {
-    if (globalThis.crypto?.randomUUID) {
-        return globalThis.crypto.randomUUID();
-    }
-    return Math.random().toString(36).substring(2);
-}
-class RootInjectables {
-    injector = inject(Injector);
-    registry = {};
-    register(register) {
-        let key = generateID();
-        while (this.registry[key]) {
-            key = generateID();
-        }
-        const injector = this.injector;
-        const value = runInInjectionContext(this.injector, () => register(injector));
-        this.registry[key] = value;
-        return key;
-    }
-    get(key) {
-        return this.registry[key];
-    }
-    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "19.2.19", ngImport: i0, type: RootInjectables, deps: [], target: i0.ɵɵFactoryTarget.Injectable });
-    static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "19.2.19", ngImport: i0, type: RootInjectables, providedIn: 'root' });
-}
-i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "19.2.19", ngImport: i0, type: RootInjectables, decorators: [{
-            type: Injectable,
-            args: [{
-                    providedIn: 'root',
-                }]
-        }] });
 /**
- * Creates a lazily-initialized root-level injectable that maintains a singleton instance.
- * The factory function runs in the root injection context on first access.
- * This should only be used for pure singletons, if you need scoped instances use regular @Injectable services.
- *
- * @param register - Factory function that creates the injectable instance using the root injector
- * @returns An inject function that returns the singleton instance
+ * Creates a tree-shakable root singleton without a class.
+ * @example const injectUser = rootInjectable(() => ({ name: signal('John') }));
  */
-function rootInjectable(register) {
-    let key = null;
-    return () => {
-        const registry = inject(RootInjectables);
-        if (!key) {
-            key = registry.register(register);
-        }
-        return registry.get(key);
-    };
+function rootInjectable(factory, // Keeping the injector just in case
+name) {
+    const token = new InjectionToken(name ?? '@mmstack/di/root-injectable', {
+        providedIn: 'root',
+        factory: () => factory(inject(Injector)),
+    });
+    return () => inject(token);
 }
 
 /**
  * Generated bundle index. Do not edit.
  */
 
-export { injectable, rootInjectable };
+export { createScope, injectable, rootInjectable };
 //# sourceMappingURL=mmstack-di.mjs.map

package/fesm2022/mmstack-di.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"mmstack-di.mjs","sources":["../../../../packages/di/src/lib/injectable.ts","../../../../packages/di/src/lib/root-injectable.ts","../../../../packages/di/src/mmstack-di.ts"],"sourcesContent":["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 {\n  inject,\n  Injectable,\n  Injector,\n  runInInjectionContext,\n} from '@angular/core';\n\nfunction generateID() {\n  if (globalThis.crypto?.randomUUID) {\n    return globalThis.crypto.randomUUID();\n  }\n  return Math.random().toString(36).substring(2);\n}\n\n@Injectable({\n  providedIn: 'root',\n})\nexport class RootInjectables {\n  private readonly injector = inject(Injector);\n  private readonly registry: Record<string, any> = {};\n\n  register<T>(register: (injector: Injector) => T): string {\n    let key = generateID();\n\n    while (this.registry[key]) {\n      key = generateID();\n    }\n\n    const injector = this.injector;\n\n    const value = runInInjectionContext(this.injector, () =>\n      register(injector),\n    );\n    this.registry[key] = value;\n\n    return key;\n  }\n\n  get<T>(key: string): T {\n    return this.registry[key];\n  }\n}\n\n/**\n * Creates a lazily-initialized root-level injectable that maintains a singleton instance.\n * The factory function runs in the root injection context on first access.\n * This should only be used for pure singletons, if you need scoped instances use regular @Injectable services.\n *\n * @param register - Factory function that creates the injectable instance using the root injector\n * @returns An inject function that returns the singleton instance\n */\nexport function rootInjectable<T>(\n  register: (injector: Injector) => T,\n): () => T {\n  let key: string | null = null;\n  return () => {\n    const registry = inject(RootInjectables);\n    if (!key) {\n      key = registry.register(register);\n    }\n    return registry.get<T>(key);\n  };\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/index.d.ts

@@ -1,2 +1,3 @@
+export { createScope } from './lib/create-scope';
 export * from './lib/injectable';
 export { rootInjectable } from './lib/root-injectable';

package/lib/create-scope.d.ts

@@ -0,0 +1,47 @@
+import { type Provider } from '@angular/core';
+import * as i0 from "@angular/core";
+export declare class ScopeRegistry {
+    private readonly injector;
+    private readonly registry;
+    getOrCreate<T>(factory: () => T): T;
+    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/lib/root-injectable.d.ts

@@ -1,19 +1,7 @@
 import { Injector } from '@angular/core';
-import * as i0 from "@angular/core";
-export declare class RootInjectables {
-    private readonly injector;
-    private readonly registry;
-    register<T>(register: (injector: Injector) => T): string;
-    get<T>(key: string): T;
-    static ɵfac: i0.ɵɵFactoryDeclaration<RootInjectables, never>;
-    static ɵprov: i0.ɵɵInjectableDeclaration<RootInjectables>;
-}
 /**
- * Creates a lazily-initialized root-level injectable that maintains a singleton instance.
- * The factory function runs in the root injection context on first access.
- * This should only be used for pure singletons, if you need scoped instances use regular @Injectable services.
- *
- * @param register - Factory function that creates the injectable instance using the root injector
- * @returns An inject function that returns the singleton instance
+ * Creates a tree-shakable root singleton without a class.
+ * @example const injectUser = rootInjectable(() => ({ name: signal('John') }));
  */
-export declare function rootInjectable<T>(register: (injector: Injector) => T): () => T;
+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.0",
+  "version": "19.3.2",
   "keywords": [
     "angular",
     "dependency injection",