@stone-js/service-container 0.1.2 → 0.8.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright © 2025 Stone Foundation
+Copyright © 2026 Stone Foundation
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -3,7 +3,7 @@
 [![npm](https://img.shields.io/npm/l/@stone-js/service-container)](https://opensource.org/licenses/MIT)
 [![npm](https://img.shields.io/npm/v/@stone-js/service-container)](https://www.npmjs.com/package/@stone-js/service-container)
 [![npm](https://img.shields.io/npm/dm/@stone-js/service-container)](https://www.npmjs.com/package/@stone-js/service-container)
-![Maintenance](https://img.shields.io/maintenance/yes/2025)
+![Maintenance](https://img.shields.io/maintenance/yes/2026)
 [![Build Status](https://github.com/stone-foundation/stone-js-service-container/actions/workflows/main.yml/badge.svg)](https://github.com/stone-foundation/stone-js-service-container/actions/workflows/main.yml)
 [![Publish Package to npmjs](https://github.com/stone-foundation/stone-js-service-container/actions/workflows/release.yml/badge.svg)](https://github.com/stone-foundation/stone-js-service-container/actions/workflows/release.yml)
 [![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=stone-foundation_stone-js-service-container&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=stone-foundation_stone-js-service-container)

package/dist/Container.d.ts

@@ -0,0 +1,181 @@
+import { Proxiable } from './Proxiable';
+import { Binding } from './models/Binding';
+import { BindingKey, BindingValue, Resolver, IContainer } from './declarations';
+/**
+ * Class representing a Container.
+ *
+ * The Container class acts as a dependency injection container, managing bindings and resolving instances.
+ * It supports different types of bindings, such as singletons, factories, and instances, and allows the use of aliases for bindings.
+ * This makes it easier to manage and resolve complex dependency trees in an application.
+ *
+ * @author Mr. Stone <evensstone@gmail.com>
+ */
+export declare class Container extends Proxiable implements IContainer {
+    private readonly aliases;
+    private readonly resolvingKeys;
+    private readonly bindings;
+    /**
+     * Create a Container.
+     *
+     * @returns A new Container instance.
+     */
+    static create(): Container;
+    /**
+     * Create a ProxyHandler for the container.
+     *
+     * @returns A new ProxyHandler instance.
+     */
+    /**
+     * Well-known property names that must never trigger service resolution. Accessing them
+     * (via `await container`, `JSON.stringify`, `console.log`, React element checks, spread,
+     * etc.) returns `undefined` so the container is safe to inspect and pass around, while
+     * genuine unknown-service access still fails fast through `make()`.
+     */
+    private static readonly SYSTEM_PROPS;
+    private static Proxyhandler;
+    /**
+     * Create a container.
+     *
+     * Initializes the container with empty alias and binding maps.
+     */
+    protected constructor();
+    /**
+     * Retrieve the value of the bindings property.
+     *
+     * @returns A map of all bindings registered in the container.
+     */
+    getBindings(): Map<BindingKey, Binding<BindingValue>>;
+    /**
+     * Retrieve the value of the aliases property.
+     *
+     * @returns A map of all aliases registered in the container.
+     */
+    getAliases(): Map<string, BindingKey>;
+    /**
+     * Set a binding as alias.
+     *
+     * Adds one or more aliases for a given binding key.
+     *
+     * @param key - The binding value.
+     * @param aliases - One or more strings representing the aliases.
+     * @returns The container instance.
+     */
+    alias(key: BindingKey, aliases: string | string[]): this;
+    /**
+     * Check if an alias exists in the container.
+     *
+     * @param alias - The alias to check.
+     * @returns True if the alias exists, false otherwise.
+     */
+    isAlias(alias: BindingKey): boolean;
+    /**
+     * Get a binding key by its alias.
+     *
+     * @param alias - The alias name.
+     * @returns The binding key associated with the alias, or undefined if not found.
+     */
+    getAliasKey(alias: BindingKey): BindingKey | undefined;
+    /**
+     * Bind a single instance or value into the container under the provided key.
+     *
+     * @param key - The key to associate with the value.
+     * @param value - The value to be bound.
+     * @returns The container instance.
+     */
+    instance(key: BindingKey, value: BindingValue): this;
+    /**
+     * Bind a single instance or value into the container under the provided key if not already bound.
+     *
+     * @param key - The key to associate with the value.
+     * @param value - The value to be bound.
+     * @returns The container instance.
+     */
+    instanceIf(key: BindingKey, value: BindingValue): this;
+    /**
+     * Bind a resolver function into the container under the provided key as a singleton.
+     *
+     * The resolver function will be called once, and the resulting value will be cached for future use.
+     *
+     * @param key - The key to associate with the singleton value.
+     * @param resolver - The resolver function to provide the value.
+     * @returns The container instance.
+     */
+    singleton<V extends BindingValue>(key: BindingKey, resolver: Resolver<V>): this;
+    /**
+     * Bind a resolver function into the container under the provided key as a singleton if not already bound.
+     *
+     * @param key - The key to associate with the singleton value.
+     * @param resolver - The resolver function to provide the value.
+     * @returns The container instance.
+     */
+    singletonIf<V extends BindingValue>(key: BindingKey, resolver: Resolver<V>): this;
+    /**
+     * Bind a resolver function into the container under the provided key, returning a new instance each time.
+     *
+     * @param key - The key to associate with the value.
+     * @param resolver - The resolver function to provide the value.
+     * @returns The container instance.
+     */
+    binding<V extends BindingValue>(key: BindingKey, resolver: Resolver<V>): this;
+    /**
+     * Bind a resolver function into the container under the provided key, returning a new instance each time if not already bound.
+     *
+     * @param key - The key to associate with the value.
+     * @param resolver - The resolver function to provide the value.
+     * @returns The container instance.
+     */
+    bindingIf<V extends BindingValue>(key: BindingKey, resolver: Resolver<V>): this;
+    /**
+     * Resolve a registered value from the container by its key.
+     *
+     * @param key - The key to resolve.
+     * @returns The resolved value.
+     * @throws ContainerError if the key cannot be resolved.
+     */
+    make<V extends BindingValue>(key: BindingKey): V;
+    /**
+     * Resolve a value from the container by its key, binding it if necessary.
+     *
+     * @param key - The key to resolve.
+     * @param singleton - Whether to bind as a singleton if not already bound.
+     * @returns The resolved value.
+     */
+    resolve<V extends BindingValue>(key: BindingKey, singleton?: boolean): V;
+    /**
+     * Resolve a value from the container by its key and return it in a factory function.
+     *
+     * @param key - The key to resolve.
+     * @returns A factory function that returns the resolved value.
+     */
+    factory<V extends BindingValue>(key: BindingKey): () => V;
+    /**
+     * Check if a value is already bound in the container by its key.
+     *
+     * @param key - The key to check.
+     * @returns True if the key is bound, false otherwise.
+     */
+    bound(key: BindingKey): boolean;
+    /**
+     * Check if a value is already bound in the container by its key.
+     *
+     * @param key - The key to check.
+     * @returns True if the key is bound, false otherwise.
+     */
+    has(key: BindingKey): boolean;
+    /**
+     * Reset the container so that all bindings are removed.
+     *
+     * @returns The container instance.
+     */
+    clear(): this;
+    /**
+     * AutoBind value to the service container.
+     *
+     * @param name - A key to make the binding. Can be anything.
+     * @param item - The item to bind.
+     * @param singleton - Bind as singleton when true.
+     * @param alias - Key binding aliases.
+     * @returns The container instance.
+     */
+    autoBinding<V extends BindingValue>(name: BindingKey, item?: V, singleton?: boolean, alias?: string | string[]): this;
+}

package/dist/Proxiable.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Class representing a Proxiable.
+ *
+ * This class allows instances to be wrapped in a Proxy, enabling custom behaviors for property access, assignment, etc.
+ *
+ * @author Mr. Stone <evensstone@gmail.com>
+ */
+export declare abstract class Proxiable {
+    /**
+     * Creates a Proxiable instance wrapped in a Proxy.
+     *
+     * @param handler - A trap object for the proxy, which defines custom behavior for fundamental operations (e.g., property lookup, assignment, etc.).
+     * @returns A new proxy object for this instance.
+     */
+    constructor(handler: ProxyHandler<Proxiable>);
+}

package/dist/declarations.d.ts

@@ -0,0 +1,144 @@
+/**
+ * A resolver function that takes a container and returns a value of type V.
+ *
+ * @template V - The type of value that the resolver returns.
+ * @param container - The container used to resolve dependencies.
+ * @returns The resolved value of type V.
+ *
+ * @example
+ * ```typescript
+ * const myResolver: Resolver<number> = (container: IContainer) => {
+ *   // Use the container to resolve dependencies and return a number.
+ *   return 42;
+ * };
+ * ```
+ */
+export type Resolver<V> = (container: IContainer) => V;
+/**
+ * A union type representing the possible keys that can be used to bind values in the container.
+ *
+ * Binding keys can be of various types, such as numbers, booleans, strings, functions, objects, or symbols.
+ * These types are used because they provide a broad range of ways to uniquely identify a binding.
+ *
+ * - `number`, `boolean`, `string`: These are basic types that are easy to use and uniquely identify a binding.
+ * - `Function`: Useful for identifying bindings by constructor or other functions.
+ * - `object`: Allows more complex key types, like instances of classes.
+ * - `symbol`: Guarantees a unique identifier, which can prevent conflicts.
+ *
+ * @example
+ * ```typescript
+ * const key1: BindingKey = 42; // Using a number as a key
+ * const key2: BindingKey = 'serviceName'; // Using a string as a key
+ * const key3: BindingKey = Symbol('uniqueKey'); // Using a symbol for uniqueness
+ * const key4: BindingKey = MyServiceClass; // Using a function (constructor) as a key
+ * const key5: BindingKey = { custom: 'objectKey' }; // Using an object as a key
+ * ```
+ */
+export type BindingKey = number | boolean | string | Function | object | symbol;
+/**
+ * A union type representing the possible values that can be bound in the container.
+ *
+ * Binding values can be of various types, including numbers, booleans, strings, functions, objects, or symbols.
+ * Unlike `BindingKey`, `BindingValue` represents the actual data or instance being bound, while `BindingKey` represents the identifier used to access that data.
+ */
+export type BindingValue = number | boolean | string | Function | object | symbol;
+/**
+ * Interface representing a Binding.
+ *
+ * This interface defines the contract for all types of bindings in the service container.
+ * Bindings are used to manage dependencies and control how objects are instantiated within the container.
+ *
+ * @template V - The type of value that this binding holds.
+ * @author Mr. Stone <evensstone@gmail.com>
+ */
+export interface IBinding<V extends BindingValue> {
+    /**
+     * Resolve and return the value of the binding.
+     *
+     * @param container - The container to resolve dependencies from.
+     * @returns The resolved value of the binding.
+     */
+    resolve: (container: IContainer) => V | undefined;
+}
+/**
+ * Interface representing a Container.
+ *
+ * This interface defines the public contract for dependency injection containers,
+ * allowing for better testability and preventing circular dependencies.
+ *
+ * @author Mr. Stone <evensstone@gmail.com>
+ */
+export interface IContainer {
+    /**
+     * Retrieve the value of the bindings property.
+     */
+    getBindings: () => Map<BindingKey, IBinding<BindingValue>>;
+    /**
+     * Retrieve the value of the aliases property.
+     */
+    getAliases: () => Map<string, BindingKey>;
+    /**
+     * Set a binding as alias.
+     */
+    alias: (key: BindingKey, aliases: string | string[]) => this;
+    /**
+     * Check if an alias exists in the container.
+     */
+    isAlias: (alias: BindingKey) => boolean;
+    /**
+     * Get a binding key by its alias.
+     */
+    getAliasKey: (alias: BindingKey) => BindingKey | undefined;
+    /**
+     * Bind a single instance or value into the container under the provided key.
+     */
+    instance: (key: BindingKey, value: BindingValue) => this;
+    /**
+     * Bind a single instance or value into the container under the provided key if not already bound.
+     */
+    instanceIf: (key: BindingKey, value: BindingValue) => this;
+    /**
+     * Bind a resolver function into the container under the provided key as a singleton.
+     */
+    singleton: <V extends BindingValue>(key: BindingKey, resolver: Resolver<V>) => this;
+    /**
+     * Bind a resolver function into the container under the provided key as a singleton if not already bound.
+     */
+    singletonIf: <V extends BindingValue>(key: BindingKey, resolver: Resolver<V>) => this;
+    /**
+     * Bind a resolver function into the container under the provided key, returning a new instance each time.
+     */
+    binding: <V extends BindingValue>(key: BindingKey, resolver: Resolver<V>) => this;
+    /**
+     * Bind a resolver function into the container under the provided key, returning a new instance each time if not already bound.
+     */
+    bindingIf: <V extends BindingValue>(key: BindingKey, resolver: Resolver<V>) => this;
+    /**
+     * Resolve a registered value from the container by its key.
+     */
+    make: <V extends BindingValue>(key: BindingKey) => V;
+    /**
+     * Resolve a value from the container by its key, binding it if necessary.
+     */
+    resolve: <V extends BindingValue>(key: BindingKey, singleton?: boolean) => V;
+    /**
+     * Resolve a value from the container by its key and return it in a factory function.
+     */
+    factory: <V extends BindingValue>(key: BindingKey) => () => V;
+    /**
+     * Check if a value is already bound in the container by its key.
+     */
+    bound: (key: BindingKey) => boolean;
+    /**
+     * Check if a value is already bound in the container by its key.
+     */
+    has: (key: BindingKey) => boolean;
+    /**
+     * Reset the container so that all bindings are removed.
+     */
+    clear: () => this;
+    /**
+     * AutoBind value to the service container.
+     */
+    autoBinding: <V extends BindingValue>(name: BindingKey, item?: V, singleton?: boolean, alias?: string | string[]) => this;
+}

package/dist/errors/ContainerError.d.ts

@@ -0,0 +1,62 @@
+import { BindingKey } from '../declarations';
+/**
+ * Class representing a ContainerError.
+ *
+ * @author Mr. Stone <evensstone@gmail.com>
+ */
+export declare class ContainerError extends Error {
+    /**
+     * Error type indicating an alias conflict.
+     */
+    static readonly ALIAS_TYPE = "alias";
+    /**
+     * Error type indicating that the resolver is not a function.
+     */
+    static readonly RESOLVER_TYPE = "resolver";
+    /**
+     * Error type indicating a resolution failure.
+     */
+    static readonly RESOLUTION_TYPE = "resolution";
+    /**
+     * Error type indicating an attempt to alias an unbound value.
+     */
+    static readonly ALIAS_UNBOUND_TYPE = "alias_unbound";
+    /**
+     * Error type indicating that a value is not a service.
+     */
+    static readonly NOT_A_SERVICE_TYPE = "not_a_service";
+    /**
+     * Error type indicating an error thrown by the resolver function.
+     */
+    static readonly CANNOT_RESOLVE_TYPE = "cannot_resolve";
+    /**
+     * Error type indicating a circular dependency.
+     */
+    static readonly CIRCULAR_DEPENDENCY_TYPE = "circular_dependency";
+    /**
+     * The type of the error.
+     */
+    private readonly type;
+    /**
+     * Create a ContainerError.
+     *
+     * @param type - The type of the error.
+     * @param message - The error message or key related to the error.
+     */
+    constructor(type: string, message: BindingKey);
+    /**
+     * Retrieve the error message based on the type and provided message.
+     *
+     * @param type - The type of the error.
+     * @param message - The error message or key related to the error.
+     * @returns The formatted error message.
+     */
+    private getMessage;
+    /**
+     * Retrieve the resolution message based on the key.
+     *
+     * @param key - The key for which the resolution failed.
+     * @returns The formatted resolution error message.
+     */
+    private getResolutionMessage;
+}

package/dist/index.d.ts

@@ -1,528 +1,9 @@
-/**
- * Class representing a Proxiable.
- *
- * This class allows instances to be wrapped in a Proxy, enabling custom behaviors for property access, assignment, etc.
- *
- * @author Mr. Stone <evensstone@gmail.com>
- */
-declare abstract class Proxiable {
-    /**
-     * Creates a Proxiable instance wrapped in a Proxy.
-     *
-     * @param handler - A trap object for the proxy, which defines custom behavior for fundamental operations (e.g., property lookup, assignment, etc.).
-     * @returns A new proxy object for this instance.
-     */
-    constructor(handler: ProxyHandler<Proxiable>);
-}
-
-/**
- * A resolver function that takes a container and returns a value of type V.
- *
- * @template V - The type of value that the resolver returns.
- * @param container - The container used to resolve dependencies.
- * @returns The resolved value of type V.
- *
- * @example
- * ```typescript
- * const myResolver: Resolver<number> = (container: IContainer) => {
- *   // Use the container to resolve dependencies and return a number.
- *   return 42;
- * };
- * ```
- */
-type Resolver<V> = (container: IContainer) => V;
-/**
- * A union type representing the possible keys that can be used to bind values in the container.
- *
- * Binding keys can be of various types, such as numbers, booleans, strings, functions, objects, or symbols.
- * These types are used because they provide a broad range of ways to uniquely identify a binding.
- *
- * - `number`, `boolean`, `string`: These are basic types that are easy to use and uniquely identify a binding.
- * - `Function`: Useful for identifying bindings by constructor or other functions.
- * - `object`: Allows more complex key types, like instances of classes.
- * - `symbol`: Guarantees a unique identifier, which can prevent conflicts.
- *
- * @example
- * ```typescript
- * const key1: BindingKey = 42; // Using a number as a key
- * const key2: BindingKey = 'serviceName'; // Using a string as a key
- * const key3: BindingKey = Symbol('uniqueKey'); // Using a symbol for uniqueness
- * const key4: BindingKey = MyServiceClass; // Using a function (constructor) as a key
- * const key5: BindingKey = { custom: 'objectKey' }; // Using an object as a key
- * ```
- */
-type BindingKey = number | boolean | string | Function | object | symbol;
-/**
- * A union type representing the possible values that can be bound in the container.
- *
- * Binding values can be of various types, including numbers, booleans, strings, functions, objects, or symbols.
- * Unlike `BindingKey`, `BindingValue` represents the actual data or instance being bound, while `BindingKey` represents the identifier used to access that data.
- */
-type BindingValue = number | boolean | string | Function | object | symbol;
-/**
- * Interface representing a Binding.
- *
- * This interface defines the contract for all types of bindings in the service container.
- * Bindings are used to manage dependencies and control how objects are instantiated within the container.
- *
- * @template V - The type of value that this binding holds.
- * @author Mr. Stone <evensstone@gmail.com>
- */
-interface IBinding<V extends BindingValue> {
-    /**
-     * Resolve and return the value of the binding.
-     *
-     * @param container - The container to resolve dependencies from.
-     * @returns The resolved value of the binding.
-     */
-    resolve: (container: IContainer) => V | undefined;
-}
-/**
- * Interface representing a Container.
- *
- * This interface defines the public contract for dependency injection containers,
- * allowing for better testability and preventing circular dependencies.
- *
- * @author Mr. Stone <evensstone@gmail.com>
- */
-interface IContainer {
-    /**
-     * Retrieve the value of the bindings property.
-     */
-    getBindings: () => Map<BindingKey, IBinding<BindingValue>>;
-    /**
-     * Retrieve the value of the aliases property.
-     */
-    getAliases: () => Map<string, BindingKey>;
-    /**
-     * Set a binding as alias.
-     */
-    alias: (key: BindingKey, aliases: string | string[]) => this;
-    /**
-     * Check if an alias exists in the container.
-     */
-    isAlias: (alias: BindingKey) => boolean;
-    /**
-     * Get a binding key by its alias.
-     */
-    getAliasKey: (alias: BindingKey) => BindingKey | undefined;
-    /**
-     * Bind a single instance or value into the container under the provided key.
-     */
-    instance: (key: BindingKey, value: BindingValue) => this;
-    /**
-     * Bind a single instance or value into the container under the provided key if not already bound.
-     */
-    instanceIf: (key: BindingKey, value: BindingValue) => this;
-    /**
-     * Bind a resolver function into the container under the provided key as a singleton.
-     */
-    singleton: <V extends BindingValue>(key: BindingKey, resolver: Resolver<V>) => this;
-    /**
-     * Bind a resolver function into the container under the provided key as a singleton if not already bound.
-     */
-    singletonIf: <V extends BindingValue>(key: BindingKey, resolver: Resolver<V>) => this;
-    /**
-     * Bind a resolver function into the container under the provided key, returning a new instance each time.
-     */
-    binding: <V extends BindingValue>(key: BindingKey, resolver: Resolver<V>) => this;
-    /**
-     * Bind a resolver function into the container under the provided key, returning a new instance each time if not already bound.
-     */
-    bindingIf: <V extends BindingValue>(key: BindingKey, resolver: Resolver<V>) => this;
-    /**
-     * Resolve a registered value from the container by its key.
-     */
-    make: <V extends BindingValue>(key: BindingKey) => V;
-    /**
-     * Resolve a value from the container by its key, binding it if necessary.
-     */
-    resolve: <V extends BindingValue>(key: BindingKey, singleton?: boolean) => V;
-    /**
-     * Resolve a value from the container by its key and return it in a factory function.
-     */
-    factory: <V extends BindingValue>(key: BindingKey) => () => V;
-    /**
-     * Check if a value is already bound in the container by its key.
-     */
-    bound: (key: BindingKey) => boolean;
-    /**
-     * Check if a value is already bound in the container by its key.
-     */
-    has: (key: BindingKey) => boolean;
-    /**
-     * Reset the container so that all bindings are removed.
-     */
-    clear: () => this;
-    /**
-     * AutoBind value to the service container.
-     */
-    autoBinding: <V extends BindingValue>(name: BindingKey, item?: V, singleton?: boolean, alias?: string | string[]) => this;
-}
-
-/**
- * Abstract class representing a Binding.
- *
- * This abstract class serves as the base class for all types of bindings in the service container. It holds a value and provides an abstract method
- * to resolve and return that value, allowing different subclasses to implement their own resolution logic. Bindings are used to manage dependencies
- * and control how objects are instantiated within the container.
- *
- * @template V - The type of value that this binding holds.
- * @author Mr. Stone <evensstone@gmail.com>
- */
-declare abstract class Binding<V extends BindingValue> implements IBinding<V> {
-    /**
-     * The value held by the binding.
-     *
-     * This value is resolved at runtime, either directly or through a resolver function.
-     */
-    protected value?: V;
-    /**
-     * Create a new instance of Binding.
-     *
-     * @param value - The value to be held by the binding.
-     */
-    constructor(value?: V);
-    /**
-     * Check if the value has been resolved.
-     *
-     * @returns A boolean indicating whether the value has been resolved.
-     */
-    protected isResolved(): boolean;
-    /**
-     * Resolve and return the value of the binding.
-     *
-     * This abstract method must be implemented by subclasses to provide specific resolution logic.
-     *
-     * @param container - The container to resolve dependencies from.
-     * @returns The resolved value of the binding.
-     */
-    abstract resolve(container: IContainer): V | undefined;
-}
-
-/**
- * Class representing a Container.
- *
- * The Container class acts as a dependency injection container, managing bindings and resolving instances.
- * It supports different types of bindings, such as singletons, factories, and instances, and allows the use of aliases for bindings.
- * This makes it easier to manage and resolve complex dependency trees in an application.
- *
- * @author Mr. Stone <evensstone@gmail.com>
- */
-declare class Container extends Proxiable implements IContainer {
-    private readonly aliases;
-    private readonly resolvingKeys;
-    private readonly bindings;
-    /**
-     * Create a Container.
-     *
-     * @returns A new Container instance.
-     */
-    static create(): Container;
-    /**
-     * Create a ProxyHandler for the container.
-     *
-     * @returns A new ProxyHandler instance.
-     */
-    private static Proxyhandler;
-    /**
-     * Create a container.
-     *
-     * Initializes the container with empty alias and binding maps.
-     */
-    protected constructor();
-    /**
-     * Retrieve the value of the bindings property.
-     *
-     * @returns A map of all bindings registered in the container.
-     */
-    getBindings(): Map<BindingKey, Binding<BindingValue>>;
-    /**
-     * Retrieve the value of the aliases property.
-     *
-     * @returns A map of all aliases registered in the container.
-     */
-    getAliases(): Map<string, BindingKey>;
-    /**
-     * Set a binding as alias.
-     *
-     * Adds one or more aliases for a given binding key.
-     *
-     * @param key - The binding value.
-     * @param aliases - One or more strings representing the aliases.
-     * @returns The container instance.
-     */
-    alias(key: BindingKey, aliases: string | string[]): this;
-    /**
-     * Check if an alias exists in the container.
-     *
-     * @param alias - The alias to check.
-     * @returns True if the alias exists, false otherwise.
-     */
-    isAlias(alias: BindingKey): boolean;
-    /**
-     * Get a binding key by its alias.
-     *
-     * @param alias - The alias name.
-     * @returns The binding key associated with the alias, or undefined if not found.
-     */
-    getAliasKey(alias: BindingKey): BindingKey | undefined;
-    /**
-     * Bind a single instance or value into the container under the provided key.
-     *
-     * @param key - The key to associate with the value.
-     * @param value - The value to be bound.
-     * @returns The container instance.
-     */
-    instance(key: BindingKey, value: BindingValue): this;
-    /**
-     * Bind a single instance or value into the container under the provided key if not already bound.
-     *
-     * @param key - The key to associate with the value.
-     * @param value - The value to be bound.
-     * @returns The container instance.
-     */
-    instanceIf(key: BindingKey, value: BindingValue): this;
-    /**
-     * Bind a resolver function into the container under the provided key as a singleton.
-     *
-     * The resolver function will be called once, and the resulting value will be cached for future use.
-     *
-     * @param key - The key to associate with the singleton value.
-     * @param resolver - The resolver function to provide the value.
-     * @returns The container instance.
-     */
-    singleton<V extends BindingValue>(key: BindingKey, resolver: Resolver<V>): this;
-    /**
-     * Bind a resolver function into the container under the provided key as a singleton if not already bound.
-     *
-     * @param key - The key to associate with the singleton value.
-     * @param resolver - The resolver function to provide the value.
-     * @returns The container instance.
-     */
-    singletonIf<V extends BindingValue>(key: BindingKey, resolver: Resolver<V>): this;
-    /**
-     * Bind a resolver function into the container under the provided key, returning a new instance each time.
-     *
-     * @param key - The key to associate with the value.
-     * @param resolver - The resolver function to provide the value.
-     * @returns The container instance.
-     */
-    binding<V extends BindingValue>(key: BindingKey, resolver: Resolver<V>): this;
-    /**
-     * Bind a resolver function into the container under the provided key, returning a new instance each time if not already bound.
-     *
-     * @param key - The key to associate with the value.
-     * @param resolver - The resolver function to provide the value.
-     * @returns The container instance.
-     */
-    bindingIf<V extends BindingValue>(key: BindingKey, resolver: Resolver<V>): this;
-    /**
-     * Resolve a registered value from the container by its key.
-     *
-     * @param key - The key to resolve.
-     * @returns The resolved value.
-     * @throws ContainerError if the key cannot be resolved.
-     */
-    make<V extends BindingValue>(key: BindingKey): V;
-    /**
-     * Resolve a value from the container by its key, binding it if necessary.
-     *
-     * @param key - The key to resolve.
-     * @param singleton - Whether to bind as a singleton if not already bound.
-     * @returns The resolved value.
-     */
-    resolve<V extends BindingValue>(key: BindingKey, singleton?: boolean): V;
-    /**
-     * Resolve a value from the container by its key and return it in a factory function.
-     *
-     * @param key - The key to resolve.
-     * @returns A factory function that returns the resolved value.
-     */
-    factory<V extends BindingValue>(key: BindingKey): () => V;
-    /**
-     * Check if a value is already bound in the container by its key.
-     *
-     * @param key - The key to check.
-     * @returns True if the key is bound, false otherwise.
-     */
-    bound(key: BindingKey): boolean;
-    /**
-     * Check if a value is already bound in the container by its key.
-     *
-     * @param key - The key to check.
-     * @returns True if the key is bound, false otherwise.
-     */
-    has(key: BindingKey): boolean;
-    /**
-     * Reset the container so that all bindings are removed.
-     *
-     * @returns The container instance.
-     */
-    clear(): this;
-    /**
-     * AutoBind value to the service container.
-     *
-     * @param name - A key to make the binding. Can be anything.
-     * @param item - The item to bind.
-     * @param singleton - Bind as singleton when true.
-     * @param alias - Key binding aliases.
-     * @returns The container instance.
-     */
-    autoBinding<V extends BindingValue>(name: BindingKey, item?: V, singleton?: boolean, alias?: string | string[]): this;
-}
-
-/**
- * Class representing a ContainerError.
- *
- * @author Mr. Stone <evensstone@gmail.com>
- */
-declare class ContainerError extends Error {
-    /**
-     * Error type indicating an alias conflict.
-     */
-    static readonly ALIAS_TYPE = "alias";
-    /**
-     * Error type indicating that the resolver is not a function.
-     */
-    static readonly RESOLVER_TYPE = "resolver";
-    /**
-     * Error type indicating a resolution failure.
-     */
-    static readonly RESOLUTION_TYPE = "resolution";
-    /**
-     * Error type indicating an attempt to alias an unbound value.
-     */
-    static readonly ALIAS_UNBOUND_TYPE = "alias_unbound";
-    /**
-     * Error type indicating that a value is not a service.
-     */
-    static readonly NOT_A_SERVICE_TYPE = "not_a_service";
-    /**
-     * Error type indicating an error thrown by the resolver function.
-     */
-    static readonly CANNOT_RESOLVE_TYPE = "cannot_resolve";
-    /**
-     * Error type indicating a circular dependency.
-     */
-    static readonly CIRCULAR_DEPENDENCY_TYPE = "circular_dependency";
-    /**
-     * The type of the error.
-     */
-    private readonly type;
-    /**
-     * Create a ContainerError.
-     *
-     * @param type - The type of the error.
-     * @param message - The error message or key related to the error.
-     */
-    constructor(type: string, message: BindingKey);
-    /**
-     * Retrieve the error message based on the type and provided message.
-     *
-     * @param type - The type of the error.
-     * @param message - The error message or key related to the error.
-     * @returns The formatted error message.
-     */
-    private getMessage;
-    /**
-     * Retrieve the resolution message based on the key.
-     *
-     * @param key - The key for which the resolution failed.
-     * @returns The formatted resolution error message.
-     */
-    private getResolutionMessage;
-}
-
-/**
- * Class representing a ResolverBinding.
- *
- * This class extends the Binding class, using a resolver function to lazily resolve the value when needed.
- *
- * @template V - The type of value that this binding holds.
- * @author Mr. Stone <evensstone@gmail.com>
- */
-declare abstract class ResolverBinding<V extends BindingValue> extends Binding<V> {
-    /**
-     * The resolver function used to provide the binding value.
-     *
-     * This function will be called when the value is needed, allowing for lazy instantiation
-     * and dependency resolution. It should return an instance of type `V`.
-     */
-    protected readonly resolver: Resolver<V>;
-    /**
-     * Create a new instance of ResolverBinding.
-     *
-     * @param resolver - The resolver function to provide the binding value.
-     * @throws ContainerError if the resolver is not a function.
-     */
-    constructor(resolver: Resolver<V>);
-}
-
-/**
- * Class representing a Factory.
- *
- * The Factory class extends the ResolverBinding class, providing a mechanism to resolve a new instance each time the binding is resolved.
- * This ensures that a fresh instance is created with each call to the `resolve` method.
- *
- * @template V - The type of value that this binding holds.
- * @author Mr. Stone <evensstone@gmail.com>
- */
-declare class Factory<V extends BindingValue> extends ResolverBinding<V> {
-    /**
-     * Resolve and return the value of the binding.
-     *
-     * Each time this method is called, a new value is resolved using the resolver function.
-     * This is intended for cases where a fresh instance is required for each resolution, such as factories or transient dependencies.
-     *
-     * @param container - The container to resolve dependencies from.
-     * @returns The resolved value of the binding.
-     * @throws ContainerError if the value cannot be resolved.
-     */
-    resolve(container: IContainer): V;
-}
-
-/**
- * Class representing an Instance.
- *
- * This class extends the Binding class and directly holds an instance value.
- * It provides a straightforward resolution mechanism that simply returns the stored value.
- *
- * @template V - The type of value that this binding holds.
- * @author Mr. Stone <evensstone@gmail.com>
- */
-declare class Instance<V extends BindingValue> extends Binding<V> {
-    /**
-     * Resolve and return the value of the binding.
-     *
-     * @param _container - Container to resolve dependencies (not used in this implementation).
-     * @returns The resolved value of the binding.
-     */
-    resolve(_container: IContainer): V | undefined;
-}
-
-/**
- * Class representing a Singleton.
- *
- * The Singleton class extends the ResolverBinding class, ensuring that the value is only resolved once.
- * Subsequent calls to the `resolve` method will return the previously resolved value, making it behave as a singleton.
- *
- * @template V - The type of value that this binding holds.
- * @author Mr. Stone <evensstone@gmail.com>
- */
-declare class Singleton<V extends BindingValue> extends ResolverBinding<V> {
-    /**
-     * Resolve and return the value of the binding.
-     *
-     * If the value has already been resolved, return the cached value. Otherwise, use the resolver function
-     * to resolve the value, store it, and return it.
-     *
-     * @param container - The container to resolve dependencies from.
-     * @returns The resolved value of the binding.
-     * @throws ContainerError if the value cannot be resolved.
-     */
-    resolve(container: IContainer): V | undefined;
-}
-
-export { Binding, Container, ContainerError, Factory, Instance, Proxiable, ResolverBinding, Singleton };
-export type { BindingKey, BindingValue, IBinding, IContainer, Resolver };
+export * from './Container';
+export * from './Proxiable';
+export * from './declarations';
+export * from './errors/ContainerError';
+export * from './models/Binding';
+export * from './models/Factory';
+export * from './models/Instance';
+export * from './models/ResolverBinding';
+export * from './models/Singleton';

package/dist/index.js

@@ -35,6 +35,14 @@ class Binding {
      * This value is resolved at runtime, either directly or through a resolver function.
      */
     value;
+    /**
+     * Whether the value has been resolved at least once.
+     *
+     * Tracked explicitly (not inferred from `value !== undefined`) so a binding whose resolved
+     * value is legitimately `undefined` is still considered resolved — preserving the singleton
+     * guarantee and avoiding repeated resolver side effects.
+     */
+    resolved;
     /**
      * Create a new instance of Binding.
      *
@@ -42,6 +50,7 @@ class Binding {
      */
     constructor(value) {
         this.value = value;
+        this.resolved = value !== undefined;
     }
     /**
      * Check if the value has been resolved.
@@ -49,7 +58,7 @@ class Binding {
      * @returns A boolean indicating whether the value has been resolved.
      */
     isResolved() {
-        return this.value !== undefined;
+        return this.resolved;
     }
 }
 
@@ -116,7 +125,7 @@ class ContainerError extends Error {
             [ContainerError.ALIAS_TYPE]: `${String(message)} is aliased to itself`,
             [ContainerError.CANNOT_RESOLVE_TYPE]: `Failed to resolve binding: ${String(message)}`,
             [ContainerError.ALIAS_UNBOUND_TYPE]: `Cannot alias an unbound value : ${String(message)}`,
-            [ContainerError.CIRCULAR_DEPENDENCY_TYPE]: `Circular dependency detected for key: ${String(message)}`,
+            [ContainerError.CIRCULAR_DEPENDENCY_TYPE]: `Circular dependency detected: ${String(message)}`,
             [ContainerError.RESOLVER_TYPE]: `Invalid resolver: Expected a function but received ${typeof message}`,
             [ContainerError.NOT_A_SERVICE_TYPE]: `This (${String(message)}) is not a service. Must contain $$metadata$$ static property or must use @Service decorator.`
         };
@@ -262,6 +271,7 @@ class Singleton extends ResolverBinding {
         if (!this.isResolved()) {
             try {
                 this.value = this.resolver(container);
+                this.resolved = true;
             }
             catch (error) {
                 throw new ContainerError(ContainerError.CANNOT_RESOLVE_TYPE, error.message);
@@ -297,15 +307,30 @@ class Container extends Proxiable {
      *
      * @returns A new ProxyHandler instance.
      */
+    /**
+     * Well-known property names that must never trigger service resolution. Accessing them
+     * (via `await container`, `JSON.stringify`, `console.log`, React element checks, spread,
+     * etc.) returns `undefined` so the container is safe to inspect and pass around, while
+     * genuine unknown-service access still fails fast through `make()`.
+     */
+    static SYSTEM_PROPS = new Set([
+        'then', 'catch', 'finally',
+        'toJSON', 'toString', 'valueOf', 'inspect',
+        'constructor', 'prototype', '$$typeof', 'nodeType'
+    ]);
     static Proxyhandler() {
         return {
             get: (target, prop, receiver) => {
                 if (Reflect.has(target, prop)) {
                     return Reflect.get(target, prop, receiver);
                 }
-                else {
-                    return target.make(prop);
+                // Symbols (Symbol.toPrimitive, Symbol.iterator, inspect.custom…) and well-known
+                // system props are inspection/coercion hooks, never services: return undefined.
+                if (typeof prop === 'symbol' || Container.SYSTEM_PROPS.has(prop)) {
+                    return undefined;
                 }
+                // Otherwise resolve as a bound service (make throws ContainerError if unbound).
+                return target.make(prop);
             }
         };
     }
@@ -458,7 +483,10 @@ class Container extends Proxiable {
     make(key) {
         key = this.getAliasKey(key) ?? key;
         if (this.resolvingKeys.has(key)) {
-            throw new ContainerError(ContainerError.CIRCULAR_DEPENDENCY_TYPE, key);
+            // Surface the full resolution chain (A → B → C → A) so the cycle is diagnosable
+            // at a glance, not just the offending key.
+            const chain = [...this.resolvingKeys, key].map(containerKeyName).join(' → ');
+            throw new ContainerError(ContainerError.CIRCULAR_DEPENDENCY_TYPE, chain);
         }
         this.resolvingKeys.add(key);
         try {
@@ -539,18 +567,67 @@ class Container extends Proxiable {
         if (!this.bound(key)) {
             if (typeof value === 'function') {
                 const callable = value;
-                const resolver = Object.hasOwn(callable, 'prototype')
-                    ? (container) => new callable.prototype.constructor(container)
+                // Only real ES classes are instantiated with `new`; ordinary/arrow factory
+                // functions are called. `hasOwnProperty('prototype')` was too loose (every
+                // non-arrow function has a prototype), breaking `function` factories.
+                const resolver = isClassConstructor(callable)
+                    ? (container) => new callable(container)
                     : (container) => callable(container);
                 singleton ? this.singleton(key, resolver) : this.binding(key, resolver);
             }
             else {
                 this.instance(key, value);
             }
-            this.alias(key, alias);
         }
+        // Apply aliases even when the key is already bound (aliasing was previously dropped).
+        this.alias(key, alias);
         return this;
     }
 }
+/**
+ * Detect a class constructor (as opposed to an ordinary or factory function).
+ *
+ * Uses two complementary signals so it survives down-level (ES5) bundling:
+ * 1. Native/modern classes stringify with the `class` keyword.
+ * 2. Transpiled classes lose the keyword but keep their methods on the prototype, whereas a
+ *    plain/factory function's prototype has only `constructor`.
+ *
+ * For ambiguous cases, callers should pass an explicit `isClass`/`isFactory` flag.
+ *
+ * @param value - The value to test.
+ * @returns True if the value is (very likely) a class constructor.
+ */
+function isClassConstructor(value) {
+    // Callers already narrow to `typeof value === 'function'`, so no redundant guard here.
+    // A function's source starts with `class` only for real ES classes.
+    if (Function.prototype.toString.call(value).startsWith('class')) {
+        return true;
+    }
+    // Otherwise fall back to the ES5-safe heuristic: a transpiled class carries own methods on
+    // its prototype (a bare/arrow factory does not).
+    const proto = value.prototype;
+    if (proto === undefined || proto === null) {
+        return false;
+    }
+    return Object.getOwnPropertyNames(proto).length > 1;
+}
+/**
+ * Produce a readable name for a binding key (used in circular-dependency chains).
+ *
+ * @param key - The binding key.
+ * @returns A human-readable label.
+ */
+function containerKeyName(key) {
+    if (typeof key === 'function') {
+        return key.name.length > 0 ? key.name : 'anonymous';
+    }
+    if (typeof key === 'symbol') {
+        return key.toString();
+    }
+    if (typeof key === 'object' && key !== null) {
+        return key.constructor?.name ?? 'Object';
+    }
+    return String(key);
+}
 
 export { Binding, Container, ContainerError, Factory, Instance, Proxiable, ResolverBinding, Singleton };

package/dist/models/Binding.d.ts

@@ -0,0 +1,48 @@
+import { BindingValue, IContainer, IBinding } from '../declarations';
+/**
+ * Abstract class representing a Binding.
+ *
+ * This abstract class serves as the base class for all types of bindings in the service container. It holds a value and provides an abstract method
+ * to resolve and return that value, allowing different subclasses to implement their own resolution logic. Bindings are used to manage dependencies
+ * and control how objects are instantiated within the container.
+ *
+ * @template V - The type of value that this binding holds.
+ * @author Mr. Stone <evensstone@gmail.com>
+ */
+export declare abstract class Binding<V extends BindingValue> implements IBinding<V> {
+    /**
+     * The value held by the binding.
+     *
+     * This value is resolved at runtime, either directly or through a resolver function.
+     */
+    protected value?: V;
+    /**
+     * Whether the value has been resolved at least once.
+     *
+     * Tracked explicitly (not inferred from `value !== undefined`) so a binding whose resolved
+     * value is legitimately `undefined` is still considered resolved — preserving the singleton
+     * guarantee and avoiding repeated resolver side effects.
+     */
+    protected resolved: boolean;
+    /**
+     * Create a new instance of Binding.
+     *
+     * @param value - The value to be held by the binding.
+     */
+    constructor(value?: V);
+    /**
+     * Check if the value has been resolved.
+     *
+     * @returns A boolean indicating whether the value has been resolved.
+     */
+    protected isResolved(): boolean;
+    /**
+     * Resolve and return the value of the binding.
+     *
+     * This abstract method must be implemented by subclasses to provide specific resolution logic.
+     *
+     * @param container - The container to resolve dependencies from.
+     * @returns The resolved value of the binding.
+     */
+    abstract resolve(container: IContainer): V | undefined;
+}

package/dist/models/Factory.d.ts

@@ -0,0 +1,24 @@
+import { ResolverBinding } from './ResolverBinding';
+import { BindingValue, IContainer } from '../declarations';
+/**
+ * Class representing a Factory.
+ *
+ * The Factory class extends the ResolverBinding class, providing a mechanism to resolve a new instance each time the binding is resolved.
+ * This ensures that a fresh instance is created with each call to the `resolve` method.
+ *
+ * @template V - The type of value that this binding holds.
+ * @author Mr. Stone <evensstone@gmail.com>
+ */
+export declare class Factory<V extends BindingValue> extends ResolverBinding<V> {
+    /**
+     * Resolve and return the value of the binding.
+     *
+     * Each time this method is called, a new value is resolved using the resolver function.
+     * This is intended for cases where a fresh instance is required for each resolution, such as factories or transient dependencies.
+     *
+     * @param container - The container to resolve dependencies from.
+     * @returns The resolved value of the binding.
+     * @throws ContainerError if the value cannot be resolved.
+     */
+    resolve(container: IContainer): V;
+}

package/dist/models/Instance.d.ts

@@ -0,0 +1,20 @@
+import { Binding } from './Binding';
+import { BindingValue, IContainer } from '../declarations';
+/**
+ * Class representing an Instance.
+ *
+ * This class extends the Binding class and directly holds an instance value.
+ * It provides a straightforward resolution mechanism that simply returns the stored value.
+ *
+ * @template V - The type of value that this binding holds.
+ * @author Mr. Stone <evensstone@gmail.com>
+ */
+export declare class Instance<V extends BindingValue> extends Binding<V> {
+    /**
+     * Resolve and return the value of the binding.
+     *
+     * @param _container - Container to resolve dependencies (not used in this implementation).
+     * @returns The resolved value of the binding.
+     */
+    resolve(_container: IContainer): V | undefined;
+}

package/dist/models/ResolverBinding.d.ts

@@ -0,0 +1,26 @@
+import { Binding } from './Binding';
+import { BindingValue, Resolver } from '../declarations';
+/**
+ * Class representing a ResolverBinding.
+ *
+ * This class extends the Binding class, using a resolver function to lazily resolve the value when needed.
+ *
+ * @template V - The type of value that this binding holds.
+ * @author Mr. Stone <evensstone@gmail.com>
+ */
+export declare abstract class ResolverBinding<V extends BindingValue> extends Binding<V> {
+    /**
+     * The resolver function used to provide the binding value.
+     *
+     * This function will be called when the value is needed, allowing for lazy instantiation
+     * and dependency resolution. It should return an instance of type `V`.
+     */
+    protected readonly resolver: Resolver<V>;
+    /**
+     * Create a new instance of ResolverBinding.
+     *
+     * @param resolver - The resolver function to provide the binding value.
+     * @throws ContainerError if the resolver is not a function.
+     */
+    constructor(resolver: Resolver<V>);
+}

package/dist/models/Singleton.d.ts

@@ -0,0 +1,24 @@
+import { ResolverBinding } from './ResolverBinding';
+import { BindingValue, IContainer } from '../declarations';
+/**
+ * Class representing a Singleton.
+ *
+ * The Singleton class extends the ResolverBinding class, ensuring that the value is only resolved once.
+ * Subsequent calls to the `resolve` method will return the previously resolved value, making it behave as a singleton.
+ *
+ * @template V - The type of value that this binding holds.
+ * @author Mr. Stone <evensstone@gmail.com>
+ */
+export declare class Singleton<V extends BindingValue> extends ResolverBinding<V> {
+    /**
+     * Resolve and return the value of the binding.
+     *
+     * If the value has already been resolved, return the cached value. Otherwise, use the resolver function
+     * to resolve the value, store it, and return it.
+     *
+     * @param container - The container to resolve dependencies from.
+     * @returns The resolved value of the binding.
+     * @throws ContainerError if the value cannot be resolved.
+     */
+    resolve(container: IContainer): V | undefined;
+}

package/package.json

@@ -1,16 +1,17 @@
 {
   "name": "@stone-js/service-container",
-  "version": "0.1.2",
+  "version": "0.8.0",
   "description": "Javascript/Typescript IoC Service Container with proxy resolver and destructuring injection",
   "author": "Mr. Stone <evensstone@gmail.com>",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+ssh://git@github.com/stone-foundation/stone-js-service-container.git"
+    "url": "git+https://github.com/stone-foundation/stone-js-framework.git",
+    "directory": "stone-js-service-container"
   },
   "homepage": "https://stonejs.dev",
   "bugs": {
-    "url": "https://github.com/stone-foundation/stone-js-service-container/issues"
+    "url": "https://github.com/stone-foundation/stone-js-framework/issues"
   },
   "keywords": [
     "DI",
@@ -43,7 +44,7 @@
     "lint:fix": "ts-standard --fix src tests",
     "predoc": "rimraf docs",
     "doc": "typedoc",
-    "prebuild": "rimraf dist && npm run doc",
+    "clean": "rimraf dist",
     "build": "rollup -c",
     "test": "vitest run",
     "test:cvg": "npm run test -- --coverage",
@@ -64,8 +65,6 @@
     "husky": "^9.1.7",
     "rimraf": "^6.0.1",
     "rollup": "^4.44.1",
-    "rollup-plugin-delete": "^3.0.1",
-    "rollup-plugin-dts": "^6.2.1",
     "rollup-plugin-node-externals": "^8.0.1",
     "ts-standard": "^12.0.2",
     "tslib": "^2.8.1",
@@ -82,5 +81,6 @@
       "describe",
       "beforeEach"
     ]
-  }
+  },
+  "sideEffects": false
 }