navi-di 1.0.0 → 1.1.1

package/dist/container/container.d.ts

@@ -1,14 +1,104 @@
 import type { ContainerIdentifier, Metadata, ServiceIdentifier } from '../types';
+/**
+ * Resolves services and stores container-local bindings.
+ *
+ * Containers let you resolve registered services, override values for the
+ * current context, and isolate container-scoped services by container.
+ */
 export declare class Container {
+    /**
+     * The identifier of this container.
+     *
+     * The default container uses `'default'`, and named containers use the
+     * identifier they were created with.
+     */
     readonly id: ContainerIdentifier;
     private metadataMap;
+    private bindingMap;
     private resolving;
     private resolvingPath;
     constructor(id: ContainerIdentifier);
+    /**
+     * Returns the default container or a named container.
+     *
+     * Calling this method with the same identifier always returns the same
+     * container instance.
+     *
+     * @param id The container identifier. Omit this to use the default container.
+     * @returns The matching container instance.
+     */
     static of(id?: ContainerIdentifier): Container;
-    set<T>(metadata: Metadata<T>): void;
+    /**
+     * Registers service metadata in this container.
+     *
+     * This is a low-level API for manual registration when you are not using
+     * `@Service()`. Registering a `singleton` on a named container stores it in
+     * the default container so it can be shared across containers.
+     *
+     * @param metadata The service metadata to register.
+     * @returns The current container.
+     */
+    register<T>(metadata: Metadata<T>): this;
+    /**
+     * Returns whether this container has a local registration for an identifier.
+     *
+     * This only checks registrations stored on the current container and does
+     * not indicate whether the identifier can be resolved through fallback.
+     *
+     * @param id The service identifier to check.
+     * @returns `true` when the current container has a local registration.
+     */
     has(id: ServiceIdentifier): boolean;
-    reset(strategy?: 'value' | 'service'): void;
+    /**
+     * 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<T>(id: ServiceIdentifier<T>, value: T): this;
+    /**
+     * Removes a local binding or registration from this container.
+     *
+     * @param id The service identifier to remove.
+     * @returns The current container.
+     */
+    remove(id: ServiceIdentifier): this;
+    /**
+     * Resets services stored in this container.
+     *
+     * Use `'value'` to clear cached instances while keeping registrations, or
+     * `'service'` to remove local registrations and bindings entirely.
+     *
+     * @param strategy The reset strategy to apply.
+     * @returns The current container.
+     */
+    reset(strategy?: 'value' | 'service'): this;
+    /**
+     * Resolves a service from this container.
+     *
+     * If the current container does not have a local registration, named
+     * containers can continue resolution through the default container according
+     * to the service scope. Services are instantiated with `new Class()` and do
+     * not support constructor arguments.
+     *
+     * @param id The service identifier to resolve.
+     * @returns The resolved service instance or bound value.
+     * @throws {ServiceNotFoundError} If no service is registered for the identifier.
+     * @throws {CircularDependencyError} If the dependency graph contains a cycle.
+     */
     get<T>(id: ServiceIdentifier<T>): T;
     private isDefault;
+    /**
+     * Resets a container by its identifier.
+     *
+     * @param containerId The container to reset.
+     * @param options Reset options.
+     */
+    static reset(containerId: ContainerIdentifier, options?: {
+        strategy?: 'value' | 'service';
+    }): void;
 }

package/dist/container/container.js

@@ -1,14 +1,36 @@
 import { CircularDependencyError, ServiceNotFoundError } from '../errors';
 import { EMPTY_VALUE } from '../types';
 import { ContainerRegistry } from './registry';
+/**
+ * Resolves services and stores container-local bindings.
+ *
+ * Containers let you resolve registered services, override values for the
+ * current context, and isolate container-scoped services by container.
+ */
 export class Container {
+    /**
+     * The identifier of this container.
+     *
+     * The default container uses `'default'`, and named containers use the
+     * identifier they were created with.
+     */
     id;
     metadataMap = new Map();
+    bindingMap = new Map();
     resolving = new Set();
     resolvingPath = [];
     constructor(id) {
         this.id = id;
     }
+    /**
+     * Returns the default container or a named container.
+     *
+     * Calling this method with the same identifier always returns the same
+     * container instance.
+     *
+     * @param id The container identifier. Omit this to use the default container.
+     * @returns The matching container instance.
+     */
     static of(id = 'default') {
         if (id === 'default') {
             return ContainerRegistry.defaultContainer;
@@ -20,11 +42,21 @@ export class Container {
         ContainerRegistry.registerContainer(container);
         return container;
     }
-    set(metadata) {
+    /**
+     * Registers service metadata in this container.
+     *
+     * This is a low-level API for manual registration when you are not using
+     * `@Service()`. Registering a `singleton` on a named container stores it in
+     * the default container so it can be shared across containers.
+     *
+     * @param metadata The service metadata to register.
+     * @returns The current container.
+     */
+    register(metadata) {
         if (metadata.scope === 'singleton' && !this.isDefault()) {
-            ContainerRegistry.defaultContainer.set(metadata);
+            ContainerRegistry.defaultContainer.register(metadata);
             this.metadataMap.delete(metadata.id);
-            return;
+            return this;
         }
         const newMetadata = {
             ...metadata,
@@ -36,21 +68,84 @@ export class Container {
         else {
             this.metadataMap.set(newMetadata.id, newMetadata);
         }
+        return this;
     }
+    /**
+     * Returns whether this container has a local registration for an identifier.
+     *
+     * This only checks registrations stored on the current container and does
+     * not indicate whether the identifier can be resolved through fallback.
+     *
+     * @param id The service identifier to check.
+     * @returns `true` when the current container has a local registration.
+     */
     has(id) {
         return 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);
+        return this;
+    }
+    /**
+     * Removes a local binding or registration from this container.
+     *
+     * @param id The service identifier to remove.
+     * @returns The current container.
+     */
+    remove(id) {
+        this.bindingMap.delete(id);
+        this.metadataMap.delete(id);
+        return this;
+    }
+    /**
+     * Resets services stored in this container.
+     *
+     * Use `'value'` to clear cached instances while keeping registrations, or
+     * `'service'` to remove local registrations and bindings entirely.
+     *
+     * @param strategy The reset strategy to apply.
+     * @returns The current container.
+     */
     reset(strategy = 'value') {
         if (strategy === 'value') {
             this.metadataMap.forEach((metadata) => {
                 metadata.value = EMPTY_VALUE;
             });
+            return this;
         }
         else {
+            this.bindingMap.clear();
             this.metadataMap.clear();
+            return this;
         }
     }
+    /**
+     * Resolves a service from this container.
+     *
+     * If the current container does not have a local registration, named
+     * containers can continue resolution through the default container according
+     * to the service scope. Services are instantiated with `new Class()` and do
+     * not support constructor arguments.
+     *
+     * @param id The service identifier to resolve.
+     * @returns The resolved service instance or bound value.
+     * @throws {ServiceNotFoundError} If no service is registered for the identifier.
+     * @throws {CircularDependencyError} If the dependency graph contains a cycle.
+     */
     get(id) {
+        if (this.bindingMap.has(id)) {
+            return this.bindingMap.get(id);
+        }
         let metadata = this.metadataMap.get(id);
         if (!metadata && !this.isDefault()) {
             const defaultMetadata = ContainerRegistry.defaultContainer.metadataMap.get(id);
@@ -105,4 +200,14 @@ export class Container {
     isDefault() {
         return this === ContainerRegistry.defaultContainer;
     }
+    /**
+     * Resets a container by its identifier.
+     *
+     * @param containerId The container to reset.
+     * @param options Reset options.
+     */
+    static reset(containerId, options) {
+        const container = ContainerRegistry.getContainer(containerId);
+        container?.reset(options?.strategy);
+    }
 }

package/dist/container/registry.d.ts

@@ -1,11 +1,51 @@
 import type { ContainerIdentifier } from '../types';
 import { Container } from './container';
+/**
+ * Stores the default container and all named containers.
+ *
+ * This registry is the shared source of truth behind `Container.of()` and
+ * decorator-based service registration.
+ *
+ * @internal
+ */
 export declare class ContainerRegistry {
     private static defaultContainerInstance?;
     private static readonly containerMap;
+    /**
+     * Returns the canonical default container instance.
+     *
+     * The default container is created lazily the first time it is requested.
+     */
     static get defaultContainer(): Container;
+    /**
+     * Registers a named container in the shared registry.
+     *
+     * @param container The container to register.
+     * @throws {DefaultContainerIdError} If the container uses the reserved `default` id.
+     * @throws {ContainerDuplicatedError} If another container already uses the same id.
+     */
     static registerContainer(container: Container): void;
+    /**
+     * Returns the default container or a named container by identifier.
+     *
+     * @param id The container identifier to resolve.
+     * @returns The default container for `'default'`, or the matching named container if one exists.
+     */
     static getContainer(id: ContainerIdentifier): Container | undefined;
+    /**
+     * Returns whether a container exists for the given identifier.
+     *
+     * The reserved `default` identifier is always treated as present.
+     *
+     * @param id The container identifier to check.
+     * @returns `true` when the container exists in the registry.
+     */
     static hasContainer(id: ContainerIdentifier): boolean;
+    /**
+     * Removes a named container from the registry.
+     *
+     * @param id The named container identifier to remove.
+     * @throws {DefaultContainerIdError} If the reserved `default` id is used.
+     */
     static removeContainer(id: ContainerIdentifier): void;
 }

package/dist/container/registry.js

@@ -1,12 +1,32 @@
 import { ContainerDuplicatedError, DefaultContainerIdError } from '../errors';
 import { Container } from './container';
+/**
+ * Stores the default container and all named containers.
+ *
+ * This registry is the shared source of truth behind `Container.of()` and
+ * decorator-based service registration.
+ *
+ * @internal
+ */
 export class ContainerRegistry {
     static defaultContainerInstance;
     static containerMap = new Map();
+    /**
+     * Returns the canonical default container instance.
+     *
+     * The default container is created lazily the first time it is requested.
+     */
     static get defaultContainer() {
         this.defaultContainerInstance ??= new Container('default');
         return this.defaultContainerInstance;
     }
+    /**
+     * Registers a named container in the shared registry.
+     *
+     * @param container The container to register.
+     * @throws {DefaultContainerIdError} If the container uses the reserved `default` id.
+     * @throws {ContainerDuplicatedError} If another container already uses the same id.
+     */
     static registerContainer(container) {
         if (container.id === 'default') {
             throw new DefaultContainerIdError();
@@ -16,18 +36,38 @@ export class ContainerRegistry {
         }
         this.containerMap.set(container.id, container);
     }
+    /**
+     * Returns the default container or a named container by identifier.
+     *
+     * @param id The container identifier to resolve.
+     * @returns The default container for `'default'`, or the matching named container if one exists.
+     */
     static getContainer(id) {
         if (id === 'default') {
             return this.defaultContainer;
         }
         return this.containerMap.get(id);
     }
+    /**
+     * Returns whether a container exists for the given identifier.
+     *
+     * The reserved `default` identifier is always treated as present.
+     *
+     * @param id The container identifier to check.
+     * @returns `true` when the container exists in the registry.
+     */
     static hasContainer(id) {
         if (id === 'default') {
             return true;
         }
         return this.containerMap.has(id);
     }
+    /**
+     * Removes a named container from the registry.
+     *
+     * @param id The named container identifier to remove.
+     * @throws {DefaultContainerIdError} If the reserved `default` id is used.
+     */
     static removeContainer(id) {
         if (id === 'default') {
             throw new DefaultContainerIdError();

package/dist/decorators/inject.d.ts

@@ -1,2 +1,13 @@
 import { type ServiceIdentifier } from '../types';
+/**
+ * Injects a dependency into a class field when the service is resolved.
+ *
+ * Use this field decorator on service properties that should be resolved from
+ * the container that creates the service instance.
+ *
+ * The dependency is assigned after the instance is created, so it is not
+ * available in constructors or field initializers.
+ *
+ * @param dependency The service identifier to inject into the decorated field.
+ */
 export declare function Inject<T>(dependency: ServiceIdentifier<T>): (_: undefined, context: ClassFieldDecoratorContext) => void;

package/dist/decorators/inject.js

@@ -1,4 +1,15 @@
 import { INJECTION_KEY } from '../types';
+/**
+ * Injects a dependency into a class field when the service is resolved.
+ *
+ * Use this field decorator on service properties that should be resolved from
+ * the container that creates the service instance.
+ *
+ * The dependency is assigned after the instance is created, so it is not
+ * available in constructors or field initializers.
+ *
+ * @param dependency The service identifier to inject into the decorated field.
+ */
 export function Inject(dependency) {
     return function (_, context) {
         const injections = (context.metadata[INJECTION_KEY] ??= []);

package/dist/decorators/service.d.ts

@@ -1,4 +1,15 @@
 import type { ServiceIdentifier, ServiceOption } from '../types';
+/**
+ * Registers a class as a service that can be resolved from a container.
+ *
+ * By default, the decorated class is registered in the default container,
+ * uses its own class as the service identifier, and uses the `container`
+ * scope.
+ *
+ * Use this decorator with a custom identifier or `scope` option when you need
+ * to change how the service is registered or reused. When you provide a
+ * custom identifier, resolve the service by that identifier.
+ */
 export declare function Service(): Function;
 export declare function Service(id: ServiceIdentifier): Function;
 export declare function Service(options?: ServiceOption): Function;

package/dist/decorators/service.js

@@ -13,7 +13,7 @@ export function Service(idOrOptions) {
     return function (target, context) {
         const options = normalizeArguments(idOrOptions);
         const injections = (context.metadata[INJECTION_KEY] ?? []);
-        ContainerRegistry.defaultContainer.set({
+        ContainerRegistry.defaultContainer.register({
             id: options?.id ?? target,
             Class: target,
             name: context.name,

package/dist/errors/circular-dependency-error.d.ts

@@ -1,5 +1,13 @@
 import type { ServiceIdentifier } from '../types';
+/**
+ * Thrown when service resolution detects a circular dependency path.
+ *
+ * @internal
+ */
 export declare class CircularDependencyError extends Error {
     name: string;
+    /**
+     * @param path The dependency chain that produced the circular reference.
+     */
     constructor(path: ServiceIdentifier[]);
 }

package/dist/errors/circular-dependency-error.js

@@ -1,5 +1,13 @@
+/**
+ * Thrown when service resolution detects a circular dependency path.
+ *
+ * @internal
+ */
 export class CircularDependencyError extends Error {
     name = 'CircularDependencyError';
+    /**
+     * @param path The dependency chain that produced the circular reference.
+     */
     constructor(path) {
         super(`Circular dependency detected: ${path.map(String).join(' -> ')}`);
     }

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

@@ -1,5 +1,13 @@
 import type { ContainerIdentifier } from '../types';
+/**
+ * Thrown when a named container is registered with an identifier that already exists.
+ *
+ * @internal
+ */
 export declare class ContainerDuplicatedError extends Error {
     name: string;
+    /**
+     * @param id The duplicated container identifier.
+     */
     constructor(id: ContainerIdentifier);
 }

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

@@ -1,5 +1,13 @@
+/**
+ * Thrown when a named container is registered with an identifier that already exists.
+ *
+ * @internal
+ */
 export class ContainerDuplicatedError extends Error {
     name = 'ContainerDuplicatedError';
+    /**
+     * @param id The duplicated container identifier.
+     */
     constructor(id) {
         super(`Cannot register container with same ID(${String(id)})`);
     }

package/dist/errors/default-container-id-error.d.ts

@@ -1,3 +1,8 @@
+/**
+ * Thrown when code attempts to use the reserved `default` identifier for a named container operation.
+ *
+ * @internal
+ */
 export declare class DefaultContainerIdError extends Error {
     name: string;
     constructor();

package/dist/errors/default-container-id-error.js

@@ -1,6 +1,11 @@
+/**
+ * Thrown when code attempts to use the reserved `default` identifier for a named container operation.
+ *
+ * @internal
+ */
 export class DefaultContainerIdError extends Error {
     name = 'DefaultContainerIdError';
     constructor() {
-        super(`You cannot register a container with the "default" for ID`);
+        super('The `default` identifier is reserved for the default container.');
     }
 }

package/dist/errors/service-not-found-error.d.ts

@@ -1,5 +1,13 @@
 import type { ServiceIdentifier } from '../types';
+/**
+ * Thrown when a service cannot be resolved for the requested identifier.
+ *
+ * @internal
+ */
 export declare class ServiceNotFoundError extends Error {
     name: string;
+    /**
+     * @param id The service identifier that could not be resolved.
+     */
     constructor(id: ServiceIdentifier);
 }

package/dist/errors/service-not-found-error.js

@@ -1,5 +1,13 @@
+/**
+ * Thrown when a service cannot be resolved for the requested identifier.
+ *
+ * @internal
+ */
 export class ServiceNotFoundError extends Error {
     name = 'ServiceNotFoundError';
+    /**
+     * @param id The service identifier that could not be resolved.
+     */
     constructor(id) {
         super(`Service not found: ${String(id)}`);
     }

package/dist/tokens/token.d.ts

@@ -1,5 +1,27 @@
+/**
+ * Represents a typed service identifier.
+ *
+ * Tokens are useful when a dependency should be resolved by an explicit key
+ * instead of by its class constructor.
+ */
 export declare class Token<T> {
+    /**
+     * A human-readable name for this token.
+     *
+     * This value is useful for debugging and display, but token resolution is
+     * based on the token instance itself.
+     */
     name?: string;
+    /**
+     * Creates a token with an optional display name.
+     *
+     * @param name A human-readable name used for debugging and display.
+     */
     constructor(name?: string);
+    /**
+     * Returns a readable string representation of this token.
+     *
+     * @returns A display string for this token.
+     */
     toString(): string;
 }

package/dist/tokens/token.js

@@ -1,9 +1,31 @@
+/**
+ * Represents a typed service identifier.
+ *
+ * Tokens are useful when a dependency should be resolved by an explicit key
+ * instead of by its class constructor.
+ */
 // oxlint-disable-next-line no-unused-vars
 export class Token {
+    /**
+     * A human-readable name for this token.
+     *
+     * This value is useful for debugging and display, but token resolution is
+     * based on the token instance itself.
+     */
     name;
+    /**
+     * Creates a token with an optional display name.
+     *
+     * @param name A human-readable name used for debugging and display.
+     */
     constructor(name) {
         this.name = name;
     }
+    /**
+     * Returns a readable string representation of this token.
+     *
+     * @returns A display string for this token.
+     */
     toString() {
         return this.name ? `Token(${this.name})` : `Token()`;
     }

package/dist/types/constructable.d.ts

@@ -1,2 +1,8 @@
+/**
+ * A class constructor that can be instantiated with `new`.
+ */
 export type Constructable<T = object, Args extends unknown[] = never[]> = new (...args: Args) => T;
+/**
+ * An abstract class constructor used for typing class-based service identifiers.
+ */
 export type AbstractConstructable<T = object, Args extends unknown[] = never[]> = abstract new (...args: Args) => T;

package/dist/types/container.d.ts

@@ -1,13 +1,42 @@
 import type { Constructable } from './constructable';
 import type { InjectionMetadata } from './injection';
 import type { ServiceIdentifier, ServiceScope } from './service';
+/**
+ * A container identifier used to select the default container or a named container.
+ */
 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;
+/**
+ * Service registration metadata stored by a container.
+ *
+ * This is primarily used by low-level registration APIs and internal container logic.
+ */
 export interface Metadata<T = unknown> {
+    /**
+     * The identifier used to resolve the service.
+     */
     id: ServiceIdentifier;
+    /**
+     * The class instantiated for this service.
+     */
     Class: Constructable<T>;
+    /**
+     * The original class or member name, when available.
+     */
     name?: string | symbol;
+    /**
+     * Property injection definitions collected for the service.
+     */
     injections: InjectionMetadata[];
+    /**
+     * The lifetime used when resolving the service.
+     */
     scope: ServiceScope;
+    /**
+     * The cached service instance, or `EMPTY_VALUE` when no instance is cached.
+     */
     value: T | typeof EMPTY_VALUE;
 }

package/dist/types/container.js

@@ -1 +1,4 @@
+/**
+ * Sentinel value used internally to mark services that have not been instantiated yet.
+ */
 export const EMPTY_VALUE = Symbol.for('EMPTY_VALUE');

package/dist/types/injection.d.ts

@@ -1,6 +1,18 @@
 import type { ServiceIdentifier } from './service';
+/**
+ * Property injection metadata collected for a service.
+ */
 export interface InjectionMetadata {
+    /**
+     * The identifier of the dependency to inject.
+     */
     id: ServiceIdentifier;
+    /**
+     * The class field that receives the resolved dependency.
+     */
     name: string | symbol;
 }
+/**
+ * Metadata key used internally to store property injection definitions.
+ */
 export declare const INJECTION_KEY: unique symbol;

package/dist/types/injection.js

@@ -1 +1,4 @@
+/**
+ * Metadata key used internally to store property injection definitions.
+ */
 export const INJECTION_KEY = Symbol.for('navi-di:injections');

package/dist/types/service.d.ts

@@ -1,8 +1,23 @@
 import type { Token } from '../tokens';
 import type { AbstractConstructable, Constructable } from './constructable';
+/**
+ * An identifier that can be used to register or resolve a service.
+ */
 export type ServiceIdentifier<T = unknown, Args extends unknown[] = never[]> = Constructable<T, Args> | AbstractConstructable<T, Args> | CallableFunction | string | Token<T>;
+/**
+ * The lifetime used when a service is resolved from a container.
+ */
 export type ServiceScope = 'singleton' | 'container' | 'transient';
+/**
+ * Options for registering a service with `@Service()`.
+ */
 export interface ServiceOption {
+    /**
+     * A custom identifier used to resolve the service.
+     */
     id?: ServiceIdentifier;
+    /**
+     * The lifetime used when the service is resolved.
+     */
     scope?: ServiceScope;
 }

package/package.json

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