navi-di 1.1.1 → 1.1.2

package/README.md

@@ -55,6 +55,9 @@ Runtime exports:
 - `Inject`
 - `Token`
 
+`Container` exposes the runtime API for resolution and low-level registration,
+including `of()`, `get()`, `set()`, `has()`, `remove()`, and `reset()`.
+
 Type-only exports:
 
 - `Constructable` / `AbstractConstructable`
@@ -209,6 +212,9 @@ handler.logger.log('hello from token injection');
 
 Returns the default container or a named container.
 
+Calling `Container.of(id)` with the same identifier reuses the same container
+instance until that instance is disposed.
+
 ### `container.get(id)`
 
 Resolves a service by class or service identifier.
@@ -218,6 +224,15 @@ Throws:
 - `ServiceNotFoundError` when no registration exists;
 - `CircularDependencyError` when the current resolution path loops back to an in-progress dependency.
 
+### `container.tryGet(id)`
+
+Resolves a service by class or service identifier and returns `undefined` when
+no registration exists.
+
+Unlike `get()`, this only returns `undefined` when the requested identifier is
+not registered anywhere in the current resolution path. Other failures, such as
+circular dependencies or missing nested dependencies, still throw.
+
 ### `container.has(id)`
 
 Checks whether the current container has a local registration.
@@ -235,12 +250,80 @@ Supported strategies:
 
 This is especially useful in tests.
 
-### `container.set(metadata)`
+### `await container.dispose()`
+
+Disposes the current container instance explicitly.
+
+- clears local registrations, bindings, and cached service instances;
+- awaits any bound value or cached service instance that exposes a `dispose()` method;
+- makes the disposed container instance unusable for future operations.
+
+After disposal, calling `Container.of(id)` again creates a fresh container for
+that identifier. The same applies to the default container: after disposal, the
+next `Container.of()` or named-container fallback access recreates a fresh
+default container with no previous registrations or cached instances.
+
+### `container.set(id, valueOrProvider)`
+
+Registers or replaces a bound value or provider for a service identifier.
+
+Use `set()` when you want manual registration without decorating a class.
+This is the supported low-level API for values, classes, and factories.
+
+Supported forms today:
+
+- `container.set(id, value)`
+- `container.set(id, { useValue: value })`
+- `container.set(id, { useClass: Class, scope?, injections? })`
+- `container.set(id, { useFactory: (container) => value, scope? })`
+
+This is the low-level API for manual value, class, and factory registration.
+For decorator-driven classes, prefer `@Service()`.
+
+Value example:
+
+```ts
+const REQUEST_ID = 'request-id';
+
+Container.of().set(REQUEST_ID, { useValue: crypto.randomUUID() });
+
+const requestId = Container.of().get<string>(REQUEST_ID);
+```
 
-Registers or replaces service metadata for a service identifier.
+Class example:
+
+```ts
+interface Logger {
+  log(message: string): void;
+}
+
+class ConsoleLogger implements Logger {
+  public log(message: string) {
+    console.log(message);
+  }
+}
+
+Container.of().set<Logger>('logger', { useClass: ConsoleLogger, scope: 'singleton' });
+```
+
+Factory example:
+
+```ts
+class Connection {
+  constructor(public readonly requestId: string) {}
+}
+
+Container.of().set('request-id', { useValue: 'request-1' });
+Container.of().set(Connection, {
+  useFactory: (container) => new Connection(container.get('request-id')),
+  scope: 'container',
+});
+```
 
-This is a low-level API that powers manual registration scenarios and internal tests.
-For application-facing code, prefer `@Service()` unless you specifically need to construct metadata yourself.
+For named containers, values bound in the default container are available through
+fallback. Provider objects are detected structurally, so plain object values that
+contain `useValue`, `useClass`, or `useFactory` should be wrapped with
+`{ useValue: value }` if you want them treated as values.
 
 ## Internal architecture
 

package/dist/container/container.d.ts

@@ -1,4 +1,4 @@
-import type { ContainerIdentifier, Metadata, ServiceIdentifier } from '../types';
+import type { ContainerIdentifier, Metadata, ServiceIdentifier, ServiceProvider } from '../types';
 /**
  * Resolves services and stores container-local bindings.
  *
@@ -17,12 +17,22 @@ export declare class Container {
     private bindingMap;
     private resolving;
     private resolvingPath;
+    private disposed;
     constructor(id: ContainerIdentifier);
+    private ensureNotDisposed;
+    private isDisposable;
+    private canResolveLocally;
+    private canResolve;
+    private isValueProvider;
+    private isClassProvider;
+    private isFactoryProvider;
+    private getClassProviderMetadata;
+    private getFactoryProviderMetadata;
     /**
      * Returns the default container or a named container.
      *
-     * Calling this method with the same identifier always returns the same
-     * container instance.
+     * Calling this method with the same identifier returns the same container
+     * instance until that instance is disposed.
      *
      * @param id The container identifier. Omit this to use the default container.
      * @returns The matching container instance.
@@ -50,16 +60,17 @@ export declare class Container {
      */
     has(id: ServiceIdentifier): boolean;
     /**
-     * Binds a concrete value to this container.
+     * Registers a value or provider for a service identifier.
      *
-     * Bound values are returned as-is when the same identifier is requested from
-     * this container.
+     * Use a plain value to bind an explicit instance, or a provider object to
+     * resolve by class or factory.
      *
-     * @param id The service identifier to bind.
-     * @param value The value to return for that identifier.
+     * @param id The service identifier to register.
+     * @param valueOrProvider The bound value or provider definition.
      * @returns The current container.
      */
     set<T>(id: ServiceIdentifier<T>, value: T): this;
+    set<T>(id: ServiceIdentifier<T>, provider: ServiceProvider<T>): this;
     /**
      * Removes a local binding or registration from this container.
      *
@@ -91,6 +102,24 @@ export declare class Container {
      * @throws {CircularDependencyError} If the dependency graph contains a cycle.
      */
     get<T>(id: ServiceIdentifier<T>): T;
+    /**
+     * Resolves a service if it exists, otherwise returns `undefined`.
+     *
+     * Unlike `get()`, this only suppresses `ServiceNotFoundError`. Other errors,
+     * such as circular dependencies or disposed-container access, still surface.
+     *
+     * @param id The service identifier to resolve.
+     * @returns The resolved value, or `undefined` when the service is missing.
+     */
+    tryGet<T>(id: ServiceIdentifier<T>): T | undefined;
+    /**
+     * Disposes this container instance and clears all local registrations.
+     *
+     * The container becomes unusable after disposal. Cached service instances and
+     * bound values that expose an async or sync `dispose()` method are awaited in
+     * the order they were discovered.
+     */
+    dispose(): Promise<void>;
     private isDefault;
     /**
      * Resets a container by its identifier.

package/dist/container/container.js

@@ -1,4 +1,4 @@
-import { CircularDependencyError, ServiceNotFoundError } from '../errors';
+import { CircularDependencyError, ContainerDisposedError, ServiceNotFoundError } from '../errors';
 import { EMPTY_VALUE } from '../types';
 import { ContainerRegistry } from './registry';
 /**
@@ -19,14 +19,67 @@ export class Container {
     bindingMap = new Map();
     resolving = new Set();
     resolvingPath = [];
+    disposed = false;
     constructor(id) {
         this.id = id;
     }
+    ensureNotDisposed() {
+        if (this.disposed) {
+            throw new ContainerDisposedError(this.id);
+        }
+    }
+    isDisposable(value) {
+        return typeof value === 'object' && value !== null && 'dispose' in value && typeof value.dispose === 'function';
+    }
+    canResolveLocally(id) {
+        return this.bindingMap.has(id) || this.metadataMap.has(id);
+    }
+    canResolve(id) {
+        if (this.canResolveLocally(id)) {
+            return true;
+        }
+        if (this.isDefault()) {
+            return false;
+        }
+        return ContainerRegistry.defaultContainer.canResolveLocally(id);
+    }
+    isValueProvider(provider) {
+        return typeof provider === 'object' && provider !== null && 'useValue' in provider;
+    }
+    isClassProvider(provider) {
+        return typeof provider === 'object' && provider !== null && 'useClass' in provider;
+    }
+    isFactoryProvider(provider) {
+        return typeof provider === 'object' && provider !== null && 'useFactory' in provider;
+    }
+    getClassProviderMetadata(id, provider) {
+        const existingMetadata = this.metadataMap.get(provider.useClass) ?? ContainerRegistry.defaultContainer.metadataMap.get(provider.useClass);
+        const inheritedInjections = existingMetadata?.Class === provider.useClass ? [...existingMetadata.injections] : [];
+        const inheritedScope = existingMetadata?.Class === provider.useClass ? existingMetadata.scope : 'container';
+        return {
+            id,
+            Class: provider.useClass,
+            name: provider.useClass.name || String(id),
+            injections: provider.injections ?? inheritedInjections,
+            scope: provider.scope ?? inheritedScope,
+            value: EMPTY_VALUE,
+        };
+    }
+    getFactoryProviderMetadata(id, provider) {
+        return {
+            id,
+            name: typeof id === 'function' ? id.name : String(id),
+            injections: [],
+            scope: provider.scope ?? 'container',
+            value: EMPTY_VALUE,
+            factory: provider.useFactory,
+        };
+    }
     /**
      * Returns the default container or a named container.
      *
-     * Calling this method with the same identifier always returns the same
-     * container instance.
+     * Calling this method with the same identifier returns the same container
+     * instance until that instance is disposed.
      *
      * @param id The container identifier. Omit this to use the default container.
      * @returns The matching container instance.
@@ -53,6 +106,7 @@ export class Container {
      * @returns The current container.
      */
     register(metadata) {
+        this.ensureNotDisposed();
         if (metadata.scope === 'singleton' && !this.isDefault()) {
             ContainerRegistry.defaultContainer.register(metadata);
             this.metadataMap.delete(metadata.id);
@@ -80,20 +134,26 @@ export class Container {
      * @returns `true` when the current container has a local registration.
      */
     has(id) {
-        return this.metadataMap.has(id);
+        this.ensureNotDisposed();
+        return this.bindingMap.has(id) || this.metadataMap.has(id);
     }
-    /**
-     * Binds a concrete value to this container.
-     *
-     * Bound values are returned as-is when the same identifier is requested from
-     * this container.
-     *
-     * @param id The service identifier to bind.
-     * @param value The value to return for that identifier.
-     * @returns The current container.
-     */
-    set(id, value) {
-        this.bindingMap.set(id, value);
+    set(id, valueOrProvider) {
+        this.ensureNotDisposed();
+        if (this.isValueProvider(valueOrProvider)) {
+            this.bindingMap.set(id, valueOrProvider.useValue);
+            this.metadataMap.delete(id);
+            return this;
+        }
+        if (this.isClassProvider(valueOrProvider)) {
+            this.bindingMap.delete(id);
+            return this.register(this.getClassProviderMetadata(id, valueOrProvider));
+        }
+        if (this.isFactoryProvider(valueOrProvider)) {
+            this.bindingMap.delete(id);
+            return this.register(this.getFactoryProviderMetadata(id, valueOrProvider));
+        }
+        this.bindingMap.set(id, valueOrProvider);
+        this.metadataMap.delete(id);
         return this;
     }
     /**
@@ -103,6 +163,7 @@ export class Container {
      * @returns The current container.
      */
     remove(id) {
+        this.ensureNotDisposed();
         this.bindingMap.delete(id);
         this.metadataMap.delete(id);
         return this;
@@ -117,6 +178,7 @@ export class Container {
      * @returns The current container.
      */
     reset(strategy = 'value') {
+        this.ensureNotDisposed();
         if (strategy === 'value') {
             this.metadataMap.forEach((metadata) => {
                 metadata.value = EMPTY_VALUE;
@@ -143,11 +205,15 @@ export class Container {
      * @throws {CircularDependencyError} If the dependency graph contains a cycle.
      */
     get(id) {
+        this.ensureNotDisposed();
         if (this.bindingMap.has(id)) {
             return this.bindingMap.get(id);
         }
         let metadata = this.metadataMap.get(id);
         if (!metadata && !this.isDefault()) {
+            if (ContainerRegistry.defaultContainer.bindingMap.has(id)) {
+                return ContainerRegistry.defaultContainer.bindingMap.get(id);
+            }
             const defaultMetadata = ContainerRegistry.defaultContainer.metadataMap.get(id);
             if (!defaultMetadata) {
                 throw new ServiceNotFoundError(id);
@@ -179,7 +245,7 @@ export class Container {
         this.resolving.add(id);
         this.resolvingPath.push(id);
         try {
-            const instance = new metadata.Class();
+            const instance = metadata.factory ? metadata.factory(this) : new metadata.Class();
             for (const injection of metadata.injections) {
                 Object.defineProperty(instance, injection.name, {
                     value: this.get(injection.id),
@@ -197,6 +263,54 @@ export class Container {
             this.resolvingPath.pop();
         }
     }
+    /**
+     * Resolves a service if it exists, otherwise returns `undefined`.
+     *
+     * Unlike `get()`, this only suppresses `ServiceNotFoundError`. Other errors,
+     * such as circular dependencies or disposed-container access, still surface.
+     *
+     * @param id The service identifier to resolve.
+     * @returns The resolved value, or `undefined` when the service is missing.
+     */
+    tryGet(id) {
+        this.ensureNotDisposed();
+        if (!this.canResolve(id)) {
+            return undefined;
+        }
+        return this.get(id);
+    }
+    /**
+     * Disposes this container instance and clears all local registrations.
+     *
+     * The container becomes unusable after disposal. Cached service instances and
+     * bound values that expose an async or sync `dispose()` method are awaited in
+     * the order they were discovered.
+     */
+    async dispose() {
+        if (this.disposed) {
+            return;
+        }
+        const ownedValues = new Set();
+        this.bindingMap.forEach((value) => {
+            ownedValues.add(value);
+        });
+        this.metadataMap.forEach((metadata) => {
+            if (metadata.value !== EMPTY_VALUE) {
+                ownedValues.add(metadata.value);
+            }
+        });
+        this.disposed = true;
+        ContainerRegistry.disposeContainer(this);
+        this.bindingMap.clear();
+        this.metadataMap.clear();
+        this.resolving.clear();
+        this.resolvingPath = [];
+        for (const value of ownedValues) {
+            if (this.isDisposable(value)) {
+                await value.dispose();
+            }
+        }
+    }
     isDefault() {
         return this === ContainerRegistry.defaultContainer;
     }

package/dist/container/registry.d.ts

@@ -48,4 +48,5 @@ export declare class ContainerRegistry {
      * @throws {DefaultContainerIdError} If the reserved `default` id is used.
      */
     static removeContainer(id: ContainerIdentifier): void;
+    static disposeContainer(container: Container): void;
 }

package/dist/container/registry.js

@@ -74,4 +74,15 @@ export class ContainerRegistry {
         }
         this.containerMap.delete(id);
     }
+    static disposeContainer(container) {
+        if (container.id === 'default') {
+            if (this.defaultContainerInstance === container) {
+                this.defaultContainerInstance = undefined;
+            }
+            return;
+        }
+        if (this.containerMap.get(container.id) === container) {
+            this.containerMap.delete(container.id);
+        }
+    }
 }

package/dist/errors/container-disposed-error.d.ts

@@ -0,0 +1,11 @@
+import type { ContainerIdentifier } from '../types';
+/**
+ * Thrown when an operation is attempted on a disposed container instance.
+ */
+export declare class ContainerDisposedError extends Error {
+    name: string;
+    /**
+     * @param id The identifier of the disposed container.
+     */
+    constructor(id: ContainerIdentifier);
+}

package/dist/errors/container-disposed-error.js

@@ -0,0 +1,12 @@
+/**
+ * Thrown when an operation is attempted on a disposed container instance.
+ */
+export class ContainerDisposedError extends Error {
+    name = 'ContainerDisposedError';
+    /**
+     * @param id The identifier of the disposed container.
+     */
+    constructor(id) {
+        super(`Container has been disposed: ${String(id)}`);
+    }
+}

package/dist/errors/index.d.ts

@@ -1,4 +1,5 @@
 export { CircularDependencyError } from './circular-dependency-error';
 export { ContainerDuplicatedError } from './container-duplicated-error';
+export { ContainerDisposedError } from './container-disposed-error';
 export { DefaultContainerIdError } from './default-container-id-error';
 export { ServiceNotFoundError } from './service-not-found-error';

package/dist/errors/index.js

@@ -1,4 +1,5 @@
 export { CircularDependencyError } from './circular-dependency-error';
 export { ContainerDuplicatedError } from './container-duplicated-error';
+export { ContainerDisposedError } from './container-disposed-error';
 export { DefaultContainerIdError } from './default-container-id-error';
 export { ServiceNotFoundError } from './service-not-found-error';

package/dist/index.d.ts

@@ -3,3 +3,4 @@ export { Service, Inject } from './decorators';
 export { Token } from './tokens';
 export type { AbstractConstructable, Constructable } from './types/constructable.ts';
 export type { ServiceIdentifier } from './types/service.ts';
+export type { ClassProvider, FactoryProvider, ServiceFactory, ServiceProvider, ValueProvider, } from './types/container.ts';

package/dist/types/container.d.ts

@@ -1,6 +1,7 @@
 import type { Constructable } from './constructable';
 import type { InjectionMetadata } from './injection';
 import type { ServiceIdentifier, ServiceScope } from './service';
+import type { Container } from '../container';
 /**
  * A container identifier used to select the default container or a named container.
  */
@@ -9,6 +10,53 @@ export type ContainerIdentifier = string | symbol;
  * Sentinel value used internally to mark services that have not been instantiated yet.
  */
 export declare const EMPTY_VALUE: unique symbol;
+/**
+ * A factory function that creates a service using the current container.
+ */
+export type ServiceFactory<T> = (container: Container) => T;
+/**
+ * A provider that always resolves to the same explicit value.
+ */
+export interface ValueProvider<T> {
+    /**
+     * The value returned for the registered identifier.
+     */
+    useValue: T;
+}
+/**
+ * A provider that resolves by instantiating a class.
+ */
+export interface ClassProvider<T> {
+    /**
+     * The class instantiated when the service is resolved.
+     */
+    useClass: Constructable<T>;
+    /**
+     * Optional property injection definitions for the registered class.
+     */
+    injections?: InjectionMetadata[];
+    /**
+     * The lifetime used when the service is resolved.
+     */
+    scope?: ServiceScope;
+}
+/**
+ * A provider that resolves by calling a factory function.
+ */
+export interface FactoryProvider<T> {
+    /**
+     * The factory used to create the resolved value.
+     */
+    useFactory: ServiceFactory<T>;
+    /**
+     * The lifetime used when the service is resolved.
+     */
+    scope?: ServiceScope;
+}
+/**
+ * A provider object accepted by low-level container registration APIs.
+ */
+export type ServiceProvider<T> = ValueProvider<T> | ClassProvider<T> | FactoryProvider<T>;
 /**
  * Service registration metadata stored by a container.
  *
@@ -22,7 +70,7 @@ export interface Metadata<T = unknown> {
     /**
      * The class instantiated for this service.
      */
-    Class: Constructable<T>;
+    Class?: Constructable<T>;
     /**
      * The original class or member name, when available.
      */
@@ -39,4 +87,8 @@ export interface Metadata<T = unknown> {
      * The cached service instance, or `EMPTY_VALUE` when no instance is cached.
      */
     value: T | typeof EMPTY_VALUE;
+    /**
+     * An optional factory used to create the resolved value.
+     */
+    factory?: ServiceFactory<T>;
 }

package/dist/types/index.d.ts

@@ -1,4 +1,4 @@
 export type { AbstractConstructable, Constructable } from './constructable';
 export type { ServiceIdentifier, ServiceOption } from './service';
-export { type ContainerIdentifier, type Metadata, EMPTY_VALUE } from './container';
+export { type ClassProvider, type ContainerIdentifier, EMPTY_VALUE, type FactoryProvider, type Metadata, type ServiceFactory, type ServiceProvider, type ValueProvider, } from './container';
 export { type InjectionMetadata, INJECTION_KEY } from './injection';

package/dist/types/index.js

@@ -1,2 +1,2 @@
-export { EMPTY_VALUE } from './container';
+export { EMPTY_VALUE, } from './container';
 export { INJECTION_KEY } from './injection';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "navi-di",
-  "version": "1.1.1",
+  "version": "1.1.2",
   "description": "Dependency injection for standard ECMAScript decorators.",
   "author": "naviary-sanctuary",
   "keywords": [