@stone-js/service-container 0.0.41

package/dist/Container.d.ts

@@ -0,0 +1,178 @@
+import { Proxiable } from './Proxiable';
+import { Binding } from './models/Binding';
+import { BindingKey, BindingValue, Resolver } 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 {
+    private readonly aliases;
+    private readonly resolvingKeys;
+    private readonly bindings;
+    /**
+     * Create a container.
+     *
+     * Initializes the container with empty alias and binding maps.
+     */
+    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;
+    /**
+     * Set class name as camelCase alias.
+     *
+     * Automatically assigns a camelCase alias to a given class based on its name or metadata.
+     *
+     * @param Class - The class to alias.
+     * @returns The container instance.
+     */
+    asAlias(Class: Function): this;
+    /**
+     * 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 | undefined;
+    /**
+     * 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 | undefined;
+    /**
+     * 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 | undefined;
+    /**
+     * 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;
+    /**
+     * Register services with zero configuration.
+     *
+     * @param classes - Classes representing the services to be registered in the container.
+     * @returns The container instance.
+     */
+    register(classes: Function | Function[]): 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,45 @@
+import { Container } from './Container';
+/**
+ * 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: Container) => {
+ *   // Use the container to resolve dependencies and return a number.
+ *   return 42;
+ * };
+ * ```
+ */
+export type Resolver<V> = (container: Container) => 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;

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