@stone-js/service-container 0.1.3 → 0.8.1

package/README.md

@@ -1,16 +1,16 @@
 # Stone.js - Service Container
 
-[![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)
+[![npm license](https://img.shields.io/npm/l/@stone-js/service-container)](https://opensource.org/licenses/MIT)
+[![npm version](https://img.shields.io/npm/v/@stone-js/service-container)](https://www.npmjs.com/package/@stone-js/service-container)
+[![npm downloads](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/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)
-[![Coverage](https://sonarcloud.io/api/project_badges/measure?project=stone-foundation_stone-js-service-container&metric=coverage)](https://sonarcloud.io/summary/new_code?id=stone-foundation_stone-js-service-container)
-[![Security Policy](https://img.shields.io/badge/Security-Policy-blue.svg)](./SECURITY.md)
-[![CodeQL](https://github.com/stone-foundation/stone-js-service-container/actions/workflows/github-code-scanning/codeql/badge.svg)](https://github.com/stone-foundation/stone-js-service-container/security/code-scanning)
-[![Dependabot Status](https://img.shields.io/badge/Dependabot-enabled-brightgreen.svg)](https://github.com/stone-foundation/stone-js-service-container/network/updates)
+[![CI](https://github.com/stone-foundation/stone-js-framework/actions/workflows/ci.yml/badge.svg)](https://github.com/stone-foundation/stone-js-framework/actions/workflows/ci.yml)
+[![Release](https://github.com/stone-foundation/stone-js-framework/actions/workflows/release.yml/badge.svg)](https://github.com/stone-foundation/stone-js-framework/actions/workflows/release.yml)
+[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=stone-foundation_stone-js-framework&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=stone-foundation_stone-js-framework)
+[![Coverage](https://sonarcloud.io/api/project_badges/measure?project=stone-foundation_stone-js-framework&metric=coverage)](https://sonarcloud.io/summary/new_code?id=stone-foundation_stone-js-framework)
+[![Security Policy](https://img.shields.io/badge/Security-Policy-blue.svg)](https://github.com/stone-foundation/stone-js-framework/blob/main/SECURITY.md)
+[![CodeQL](https://github.com/stone-foundation/stone-js-framework/actions/workflows/github-code-scanning/codeql/badge.svg)](https://github.com/stone-foundation/stone-js-framework/security/code-scanning)
+[![Dependabot Status](https://img.shields.io/badge/Dependabot-enabled-brightgreen.svg)](https://github.com/stone-foundation/stone-js-framework/network/updates)
 [![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-yellow.svg)](https://conventionalcommits.org)
 
 IoC Service Container with proxy resolver and destructuring injection provides a very simple, centralized container that stores and resolves libraries, objects, and values to better organize code, manage dependencies, and enhance testability.

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;
+}