@stone-js/service-container 0.1.0 → 0.1.2

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 Stone.js
+Copyright © 2025 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

@@ -1,17 +1,23 @@
-# Stone.js: Service Container
+# Stone.js - Service Container
 
-[![npm](https://img.shields.io/npm/l/@stone-js/service-container)](https://opensource.org/licenses/Apache-2.0)
+[![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)
-[![Publish Package to npmjs](https://github.com/stonemjs/service-container/actions/workflows/release.yml/badge.svg)](https://github.com/stonemjs/service-container/actions/workflows/release.yml)
+[![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)
 [![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-yellow.svg)](https://conventionalcommits.org)
 
-IoC Service Container with proposal decorator, 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.
+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.
 
 ---
 
-## Synopsis
+## Overview
 
 The **Service Container** is an advanced JavaScript/TypeScript library that helps you manage dependencies effectively in your applications. It utilizes the Inversion of Control (IoC) pattern to simplify dependency injection, allowing you to create highly decoupled and maintainable codebases.
 
@@ -41,9 +47,8 @@ PNPM:
 pnpm add @stone-js/service-container
 ```
 
-> [!NOTE]
-> This package is Pure ESM. If you are unfamiliar with what that means or how to handle it in your project, 
-> please refer to [`this guide on Pure ESM packages`](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c).
+> [!IMPORTANT]
+> This package is **pure ESM**. Ensure your `package.json` includes `"type": "module"` or configure your bundler appropriately.
 
 Make sure your project setup is compatible with ESM. This might involve updating your `package.json` or using certain bundler configurations.
 
@@ -90,16 +95,14 @@ class A {
 Now, create a class `B` that depends on `Logger` and `A` to log the message:
 
 ```typescript
-import { Binding } from '@stone-js/service-container';
-
 // Your class B
 class B {
   private readonly a: A;
   private readonly logger: Logger;
 
-  constructor({ a, logger }: Binding<A | Logger>) { // Dependency injection by destructuring
-    this.a = a as A;
-    this.logger = logger as Logger;
+  constructor({ a, logger }: { a: A, logger: Logger }) { // Dependency injection by destructuring
+    this.a = a
+    this.logger = logger
   }
 
   logMessage() {
@@ -331,13 +334,19 @@ With this library, managing dependencies in your application becomes much simple
 
 The Stone Service Container simplifies dependency management in your applications, making them more modular, testable, and maintainable. It provides tools for binding instances, singletons, and factories, as well as auto and conditional binding. By leveraging Inversion of Control and dependency injection, the service container ensures efficient, flexible, and scalable management of dependencies, fitting projects of any size.
 
+## Learn More
+
+This package is part of the Stone.js ecosystem, a modern JavaScript framework built around the Continuum Architecture.
+
+Explore the full documentation: [https://stonejs.dev](https://stonejs.dev)
+
 ## API documentation
 
-- [API](https://github.com/stonemjs/service-container/blob/main/docs/modules.md)
+- [API](https://github.com/stone-foundation/stone-js-service-container/blob/main/docs/modules.md)
 
 ## Contributing
 
-See [Contributing Guide](https://github.com/stonemjs/service-container/blob/main/CONTRIBUTING.md).
+See [Contributing Guide](https://github.com/stone-foundation/stone-js-service-container/blob/main/CONTRIBUTING.md).
 
 ## Credits
 - [Laravel Service Container](https://github.com/illuminate/container)

package/dist/index.d.ts

@@ -24,13 +24,13 @@ declare abstract class Proxiable {
  *
  * @example
  * ```typescript
- * const myResolver: Resolver<number> = (container: Container) => {
+ * const myResolver: Resolver<number> = (container: IContainer) => {
  *   // Use the container to resolve dependencies and return a number.
  *   return 42;
  * };
  * ```
  */
-type Resolver<V> = (container: Container) => V;
+type Resolver<V> = (container: IContainer) => V;
 /**
  * A union type representing the possible keys that can be used to bind values in the container.
  *
@@ -59,6 +59,106 @@ type BindingKey = number | boolean | string | Function | object | symbol;
  * 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.
@@ -70,7 +170,7 @@ type BindingValue = number | boolean | string | Function | object | symbol;
  * @template V - The type of value that this binding holds.
  * @author Mr. Stone <evensstone@gmail.com>
  */
-declare abstract class Binding<V extends BindingValue> {
+declare abstract class Binding<V extends BindingValue> implements IBinding<V> {
     /**
      * The value held by the binding.
      *
@@ -97,7 +197,7 @@ declare abstract class Binding<V extends BindingValue> {
      * @param container - The container to resolve dependencies from.
      * @returns The resolved value of the binding.
      */
-    abstract resolve(container: Container): V | undefined;
+    abstract resolve(container: IContainer): V | undefined;
 }
 
 /**
@@ -109,7 +209,7 @@ declare abstract class Binding<V extends BindingValue> {
  *
  * @author Mr. Stone <evensstone@gmail.com>
  */
-declare class Container extends Proxiable {
+declare class Container extends Proxiable implements IContainer {
     private readonly aliases;
     private readonly resolvingKeys;
     private readonly bindings;
@@ -272,5 +372,157 @@ declare class Container extends Proxiable {
     autoBinding<V extends BindingValue>(name: BindingKey, item?: V, singleton?: boolean, alias?: string | string[]): this;
 }
 
-export { Container, Proxiable };
-export type { BindingKey, BindingValue, Resolver };
+/**
+ * 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 };

package/dist/index.js

@@ -539,7 +539,7 @@ class Container extends Proxiable {
         if (!this.bound(key)) {
             if (typeof value === 'function') {
                 const callable = value;
-                const resolver = Object.prototype.hasOwnProperty.call(callable, 'prototype')
+                const resolver = Object.hasOwn(callable, 'prototype')
                     ? (container) => new callable.prototype.constructor(container)
                     : (container) => callable(container);
                 singleton ? this.singleton(key, resolver) : this.binding(key, resolver);

package/package.json

@@ -1,16 +1,16 @@
 {
   "name": "@stone-js/service-container",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "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/stonemjs/service-container.git"
+    "url": "git+ssh://git@github.com/stone-foundation/stone-js-service-container.git"
   },
-  "homepage": "https://github.com/stonemjs/service-container#readme",
+  "homepage": "https://stonejs.dev",
   "bugs": {
-    "url": "https://github.com/stonemjs/service-container/issues"
+    "url": "https://github.com/stone-foundation/stone-js-service-container/issues"
   },
   "keywords": [
     "DI",
@@ -36,7 +36,7 @@
     }
   },
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=18.17.0"
   },
   "scripts": {
     "lint": "ts-standard src",
@@ -55,24 +55,24 @@
   "devDependencies": {
     "@commitlint/cli": "^19.8.1",
     "@commitlint/config-conventional": "^19.8.1",
-    "@rollup/plugin-commonjs": "^28.0.3",
+    "@rollup/plugin-commonjs": "^28.0.6",
     "@rollup/plugin-multi-entry": "^6.0.1",
     "@rollup/plugin-node-resolve": "^16.0.1",
-    "@rollup/plugin-typescript": "^12.1.1",
-    "@types/node": "^22.15.17",
-    "@vitest/coverage-v8": "^3.1.3",
+    "@rollup/plugin-typescript": "^12.1.4",
+    "@types/node": "^24.0.7",
+    "@vitest/coverage-v8": "^3.2.4",
     "husky": "^9.1.7",
     "rimraf": "^6.0.1",
-    "rollup": "^4.40.2",
+    "rollup": "^4.44.1",
     "rollup-plugin-delete": "^3.0.1",
     "rollup-plugin-dts": "^6.2.1",
-    "rollup-plugin-node-externals": "^8.0.0",
+    "rollup-plugin-node-externals": "^8.0.1",
     "ts-standard": "^12.0.2",
     "tslib": "^2.8.1",
-    "typedoc": "^0.28.4",
-    "typedoc-plugin-markdown": "^4.6.3",
+    "typedoc": "^0.28.6",
+    "typedoc-plugin-markdown": "^4.7.0",
     "typescript": "^5.6.3",
-    "vitest": "^3.1.3"
+    "vitest": "^3.2.4"
   },
   "ts-standard": {
     "globals": [