@stone-js/service-container 0.1.1 → 0.1.3

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 Stone.js
+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)
@@ -47,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.
 
@@ -339,7 +338,7 @@ The Stone Service Container simplifies dependency management in your application
 
 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
+Explore the full documentation: [https://stonejs.dev](https://stonejs.dev)
 
 ## API documentation
 

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;
@@ -379,7 +479,7 @@ declare class Factory<V extends BindingValue> extends ResolverBinding<V> {
      * @returns The resolved value of the binding.
      * @throws ContainerError if the value cannot be resolved.
      */
-    resolve(container: Container): V;
+    resolve(container: IContainer): V;
 }
 
 /**
@@ -398,7 +498,7 @@ declare class Instance<V extends BindingValue> extends Binding<V> {
      * @param _container - Container to resolve dependencies (not used in this implementation).
      * @returns The resolved value of the binding.
      */
-    resolve(_container: Container): V | undefined;
+    resolve(_container: IContainer): V | undefined;
 }
 
 /**
@@ -421,8 +521,8 @@ declare class Singleton<V extends BindingValue> extends ResolverBinding<V> {
      * @returns The resolved value of the binding.
      * @throws ContainerError if the value cannot be resolved.
      */
-    resolve(container: Container): V | undefined;
+    resolve(container: IContainer): V | undefined;
 }
 
 export { Binding, Container, ContainerError, Factory, Instance, Proxiable, ResolverBinding, Singleton };
-export type { BindingKey, BindingValue, Resolver };
+export type { BindingKey, BindingValue, IBinding, IContainer, Resolver };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stone-js/service-container",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Javascript/Typescript IoC Service Container with proxy resolver and destructuring injection",
   "author": "Mr. Stone <evensstone@gmail.com>",
   "license": "MIT",
@@ -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": "^24.0.0",
-    "@vitest/coverage-v8": "^3.2.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.43.0",
+    "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.5",
-    "typedoc-plugin-markdown": "^4.6.4",
+    "typedoc": "^0.28.6",
+    "typedoc-plugin-markdown": "^4.7.0",
     "typescript": "^5.6.3",
-    "vitest": "^3.2.3"
+    "vitest": "^3.2.4"
   },
   "ts-standard": {
     "globals": [