plain-ioc 0.1.3 → 1.0.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2019 Sality
+Copyright (c) 2025 mvcbox
 
 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,2 +1,270 @@
+[![npm version](https://badge.fury.io/js/plain-ioc.svg?flush_cache=v1_0_0)](https://badge.fury.io/js/plain-ioc)
+
 # plain-ioc
-Plain inversion of control container
+
+A small, dependency-free **Inversion of Control (IoC) / Dependency Injection** container for Node.js and TypeScript.
+
+**Highlights**
+
+- **Synchronous factories only** (factories cannot return a `Promise`)
+- **Transient** and **singleton** bindings
+- Optional **circular dependency detection** (useful in development)
+- Tiny API surface
+
+---
+
+## Installation
+
+```bash
+npm install plain-ioc
+```
+
+---
+
+## Core concepts
+
+### Dependency keys
+
+A *dependency key* is used to register and later resolve a dependency.
+
+In TypeScript, the key type is:
+
+```ts
+type DependencyKey = string | symbol | object;
+```
+
+Recommended key styles:
+
+- **`symbol`** keys for interfaces or abstract concepts (prevents accidental collisions)
+- **class constructors** as keys for concrete classes
+- **`string`** keys for quick scripts or small apps
+
+> Tip: Using `Symbol('Name')` makes debugging easier.
+
+### Factories
+
+A *factory* creates the dependency instance.
+
+```ts
+interface DependencyFactory<T> {
+  (container: Container): T; // must not return a Promise
+}
+```
+
+Factories receive the `Container`, so they can resolve other dependencies.
+
+---
+
+## Usage
+
+### Create a container
+
+```ts
+import { Container } from "plain-ioc";
+
+const container = new Container();
+```
+
+### Bind and resolve (transient)
+
+`bind()` registers a factory that runs **every time** you resolve the key.
+
+```ts
+import { Container } from "plain-ioc";
+
+const c = new Container();
+
+c.bind("now", () => Date.now());
+
+const a = c.resolve<number>("now");
+const b = c.resolve<number>("now");
+// a !== b (very likely)
+```
+
+### Bind and resolve (singleton)
+
+`bindSingleton()` registers a factory that runs **once**. The created instance is cached and returned for subsequent resolves.
+
+```ts
+import { Container } from "plain-ioc";
+
+class Logger {
+  log(message: string) {
+    console.log(message);
+  }
+}
+
+const c = new Container();
+
+c.bindSingleton(Logger, () => new Logger());
+
+const l1 = c.resolve<Logger>(Logger);
+const l2 = c.resolve<Logger>(Logger);
+// l1 === l2
+```
+
+### Using symbols (recommended for interfaces)
+
+```ts
+import { Container } from "plain-ioc";
+
+interface Config {
+  baseUrl: string;
+}
+
+const TOKENS = {
+  Config: Symbol("Config"),
+} as const;
+
+const c = new Container();
+
+c.bindSingleton<Config>(TOKENS.Config, () => ({ baseUrl: "https://api.example.com" }));
+
+const cfg = c.resolve<Config>(TOKENS.Config);
+```
+
+### Wiring dependencies together
+
+```ts
+import { Container } from "plain-ioc";
+
+const TOKENS = {
+  BaseUrl: Symbol("BaseUrl"),
+} as const;
+
+class ApiClient {
+  constructor(public readonly baseUrl: string) {}
+}
+
+const c = new Container();
+
+c.bindSingleton<string>(TOKENS.BaseUrl, () => "https://api.example.com");
+c.bindSingleton(ApiClient, (c) => new ApiClient(c.resolve(TOKENS.BaseUrl)));
+
+const api = c.resolve<ApiClient>(ApiClient);
+console.log(api.baseUrl);
+```
+
+### Check if a key is bound
+
+```ts
+import { Container } from "plain-ioc";
+
+const c = new Container();
+
+c.isBound("service"); // false
+c.bind("service", () => ({ ok: true }));
+c.isBound("service"); // true
+```
+
+### Unbind
+
+`unbind()` removes the factory. If the binding was a singleton, its cached instance is removed as well.
+
+```ts
+import { Container } from "plain-ioc";
+
+const c = new Container();
+
+c.bindSingleton("app", () => ({ name: "demo" }));
+
+c.unbind("app");
+// c.resolve("app") will now throw
+```
+
+---
+
+## Circular dependency detection
+
+By default, circular dependency detection is **off**.
+
+Enable it when creating the container:
+
+```ts
+import { Container } from "plain-ioc";
+
+const c = new Container({ circularDependencyDetect: true });
+```
+
+When enabled, `resolve()` tracks a stack of keys being resolved. If the same key appears twice in the stack, a `CircularDependencyError` is thrown with a message that includes the dependency stack.
+
+> Recommendation: Keep this enabled in development/test, and turn it off in production for minimal overhead.
+
+---
+
+## API reference
+
+### `new Container(options?)`
+
+Creates a container.
+
+- `options.circularDependencyDetect?: boolean` — default `false`
+
+### `container.bind<T>(key, factory)`
+
+Registers a **transient** factory.
+
+- Throws `FactoryAlreadyBoundError` if the key is already registered.
+
+### `container.bindSingleton<T>(key, factory)`
+
+Registers a **singleton** factory.
+
+- Throws `FactoryAlreadyBoundError` if the key is already registered.
+
+### `container.resolve<T>(key): T`
+
+Resolves an instance.
+
+- Throws `FactoryNotBoundError` if the key is not registered.
+- Throws `CircularDependencyError` when circular dependency detection is enabled and a cycle is detected.
+
+### `container.unbind(key)`
+
+Removes a registered factory and clears any cached singleton instance.
+
+- Throws `FactoryNotBoundError` if the key is not registered.
+
+### `container.isBound(key): boolean`
+
+Returns `true` if a factory is registered for `key`.
+
+---
+
+## Errors
+
+All library errors extend the base class `PlainIocError`:
+
+- `PlainIocError`
+- `FactoryNotBoundError`
+- `FactoryAlreadyBoundError`
+- `CircularDependencyError`
+
+You can catch these specifically:
+
+```ts
+import { Container, FactoryNotBoundError } from "plain-ioc";
+
+const c = new Container();
+
+try {
+  c.resolve("missing");
+} catch (e) {
+  if (e instanceof FactoryNotBoundError) {
+    console.error("Not registered");
+  }
+}
+```
+
+---
+
+## Notes & limitations
+
+- Factories are **synchronous** (the type system rejects `Promise`-returning factories). If you need async initialization, create the instance elsewhere and bind it as a singleton value via a factory like `() => alreadyInitialized`.
+- There is a single container scope (no built-in child containers / scopes).
+
+---
+
+## License
+
+MIT

package/dist/Container.d.ts

@@ -1,13 +1,19 @@
-import { Dependency } from './Dependency';
-import { DependencyKey } from './DependencyKey';
-import { DependencyFacroty } from './DependencyFacroty';
+import type { Dependency } from './Dependency';
+import type { DependencyKey } from './DependencyKey';
+import type { ContainerOptions } from './ContainerOptions';
+import type { DependencyFactory } from './DependencyFactory';
 export declare class Container {
-    dependencies: Map<DependencyKey, Dependency<any>>;
-    initInstances: Map<DependencyKey, any>;
-    bind<T>(key: DependencyKey, factory: DependencyFacroty<T>): void;
+    protected readonly circularDependencyDetect: boolean;
+    protected readonly circularDependencyStack: DependencyKey[];
+    protected readonly initializedInstances: Map<DependencyKey, unknown>;
+    protected readonly dependencies: Map<DependencyKey, Dependency<unknown>>;
+    constructor(options?: ContainerOptions);
+    protected circularDependencyStackPush(key: DependencyKey): void;
+    protected circularDependencyStackPop(): void;
+    protected keyToString(key: DependencyKey): string;
+    bind<T>(key: DependencyKey, factory: DependencyFactory<T>): void;
     unbind(key: DependencyKey): void;
-    bindSingleton<T>(key: DependencyKey, factory: DependencyFacroty<T>): void;
+    bindSingleton<T>(key: DependencyKey, factory: DependencyFactory<T>): void;
     isBound(key: DependencyKey): boolean;
     resolve<T>(key: DependencyKey): T;
-    keyToString(key: DependencyKey): string;
 }

package/dist/Container.js

@@ -1,14 +1,53 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.Container = void 0;
 const errors_1 = require("./errors");
 class Container {
-    constructor() {
+    constructor(options) {
+        var _a;
+        this.circularDependencyStack = [];
+        this.initializedInstances = new Map();
         this.dependencies = new Map();
-        this.initInstances = new Map();
+        this.circularDependencyDetect = (_a = options === null || options === void 0 ? void 0 : options.circularDependencyDetect) !== null && _a !== void 0 ? _a : false;
+    }
+    circularDependencyStackPush(key) {
+        if (!this.circularDependencyDetect) {
+            return;
+        }
+        const detected = this.circularDependencyStack.findIndex(item => item === key) !== -1;
+        this.circularDependencyStack.push(key);
+        if (detected) {
+            let errorMessage = 'Circular dependency detected\n\n';
+            errorMessage += '>>>>>>> Circular Dependency Stack <<<<<<<\n';
+            errorMessage += this.circularDependencyStack.map((item, index) => {
+                return `>>> [${index}]: ${this.keyToString(item)}\n`;
+            }).join('');
+            throw new errors_1.CircularDependencyError(errorMessage);
+        }
+    }
+    circularDependencyStackPop() {
+        if (this.circularDependencyDetect) {
+            this.circularDependencyStack.pop();
+        }
+    }
+    keyToString(key) {
+        const type = typeof key;
+        try {
+            if (typeof key === 'function') {
+                return `"${key.name || '<anonymous>'}" (${type})`;
+            }
+            if (type === 'object') {
+                return `"${Object.prototype.toString.call(key)}" (${type})`;
+            }
+            return `"${String(key)}" (${type})`;
+        }
+        catch (_a) {
+            return `"<unprintable>" (${type})`;
+        }
     }
     bind(key, factory) {
         if (this.dependencies.has(key)) {
-            throw new errors_1.FactoryAlreadyBoundError(`Factory for '${this.keyToString(key)}' already bound`);
+            throw new errors_1.FactoryAlreadyBoundError(`Factory for ${this.keyToString(key)} already bound`);
         }
         this.dependencies.set(key, {
             factory
@@ -16,14 +55,14 @@ class Container {
     }
     unbind(key) {
         if (!this.dependencies.has(key)) {
-            throw new errors_1.FactoryNotBoundError(`Factory not bound with '${this.keyToString(key)}'`);
+            throw new errors_1.FactoryNotBoundError(`Factory not bound with ${this.keyToString(key)}`);
         }
         this.dependencies.delete(key);
-        this.initInstances.delete(key);
+        this.initializedInstances.delete(key);
     }
     bindSingleton(key, factory) {
         if (this.dependencies.has(key)) {
-            throw new errors_1.FactoryAlreadyBoundError(`Factory for '${this.keyToString(key)}' already bound`);
+            throw new errors_1.FactoryAlreadyBoundError(`Factory for ${this.keyToString(key)} already bound`);
         }
         this.dependencies.set(key, {
             factory,
@@ -35,24 +74,24 @@ class Container {
     }
     resolve(key) {
         if (!this.dependencies.has(key)) {
-            throw new errors_1.FactoryNotBoundError(`Factory not bound with '${this.keyToString(key)}'`);
+            throw new errors_1.FactoryNotBoundError(`Factory not bound with ${this.keyToString(key)}`);
         }
         const dependency = this.dependencies.get(key);
-        if (dependency.singleton && this.initInstances.has(key)) {
-            return this.initInstances.get(key);
+        if (dependency.singleton && this.initializedInstances.has(key)) {
+            return this.initializedInstances.get(key);
         }
-        else if (dependency.singleton) {
-            const instance = dependency.factory(this);
-            this.initInstances.set(key, instance);
-            return instance;
+        try {
+            this.circularDependencyStackPush(key);
+            if (dependency.singleton) {
+                const instance = dependency.factory(this);
+                this.initializedInstances.set(key, instance);
+                return instance;
+            }
+            return dependency.factory(this);
         }
-        return dependency.factory(this);
-    }
-    keyToString(key) {
-        if (typeof key === 'function') {
-            return key.name || '';
+        finally {
+            this.circularDependencyStackPop();
         }
-        return String(key);
     }
 }
 exports.Container = Container;

package/dist/ContainerOptions.d.ts

@@ -0,0 +1,3 @@
+export type ContainerOptions = {
+    circularDependencyDetect?: boolean;
+};

package/dist/Dependency.d.ts

@@ -1,5 +1,5 @@
-import { DependencyFacroty } from './DependencyFacroty';
+import type { DependencyFactory } from './DependencyFactory';
 export interface Dependency<T> {
-    factory: DependencyFacroty<T>;
+    factory: DependencyFactory<T>;
     singleton?: boolean;
 }

package/dist/DependencyFactory.d.ts

@@ -0,0 +1,6 @@
+import type { Container } from './Container';
+type NotPromise<T> = T extends PromiseLike<any> ? never : T;
+export interface DependencyFactory<T> {
+    (container: Container): NotPromise<T>;
+}
+export {};

package/dist/DependencyFactory.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/DependencyKey.d.ts

@@ -1 +1 @@
-export declare type DependencyKey = string | symbol | object;
+export type DependencyKey = string | symbol | object;

package/dist/errors/CircularDependencyError.d.ts

@@ -0,0 +1,3 @@
+import { PlainIocError } from './PlainIocError';
+export declare class CircularDependencyError extends PlainIocError {
+}

package/dist/errors/CircularDependencyError.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CircularDependencyError = void 0;
+const PlainIocError_1 = require("./PlainIocError");
+class CircularDependencyError extends PlainIocError_1.PlainIocError {
+}
+exports.CircularDependencyError = CircularDependencyError;

package/dist/errors/FactoryAlreadyBoundError.d.ts

@@ -1,2 +1,3 @@
-export declare class FactoryAlreadyBoundError extends Error {
+import { PlainIocError } from './PlainIocError';
+export declare class FactoryAlreadyBoundError extends PlainIocError {
 }

package/dist/errors/FactoryAlreadyBoundError.js

@@ -1,5 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-class FactoryAlreadyBoundError extends Error {
+exports.FactoryAlreadyBoundError = void 0;
+const PlainIocError_1 = require("./PlainIocError");
+class FactoryAlreadyBoundError extends PlainIocError_1.PlainIocError {
 }
 exports.FactoryAlreadyBoundError = FactoryAlreadyBoundError;

package/dist/errors/FactoryNotBoundError.d.ts

@@ -1,2 +1,3 @@
-export declare class FactoryNotBoundError extends Error {
+import { PlainIocError } from './PlainIocError';
+export declare class FactoryNotBoundError extends PlainIocError {
 }

package/dist/errors/FactoryNotBoundError.js

@@ -1,5 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-class FactoryNotBoundError extends Error {
+exports.FactoryNotBoundError = void 0;
+const PlainIocError_1 = require("./PlainIocError");
+class FactoryNotBoundError extends PlainIocError_1.PlainIocError {
 }
 exports.FactoryNotBoundError = FactoryNotBoundError;

package/dist/errors/PlainIocError.d.ts

@@ -0,0 +1,3 @@
+export declare class PlainIocError extends Error {
+    constructor(message?: string);
+}

package/dist/errors/PlainIocError.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PlainIocError = void 0;
+class PlainIocError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = new.target.name;
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, new.target);
+        }
+    }
+}
+exports.PlainIocError = PlainIocError;

package/dist/errors/index.d.ts

@@ -1,2 +1,4 @@
+export { PlainIocError } from './PlainIocError';
 export { FactoryNotBoundError } from './FactoryNotBoundError';
+export { CircularDependencyError } from './CircularDependencyError';
 export { FactoryAlreadyBoundError } from './FactoryAlreadyBoundError';

package/dist/errors/index.js

@@ -1,6 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.FactoryAlreadyBoundError = exports.CircularDependencyError = exports.FactoryNotBoundError = exports.PlainIocError = void 0;
+var PlainIocError_1 = require("./PlainIocError");
+Object.defineProperty(exports, "PlainIocError", { enumerable: true, get: function () { return PlainIocError_1.PlainIocError; } });
 var FactoryNotBoundError_1 = require("./FactoryNotBoundError");
-exports.FactoryNotBoundError = FactoryNotBoundError_1.FactoryNotBoundError;
+Object.defineProperty(exports, "FactoryNotBoundError", { enumerable: true, get: function () { return FactoryNotBoundError_1.FactoryNotBoundError; } });
+var CircularDependencyError_1 = require("./CircularDependencyError");
+Object.defineProperty(exports, "CircularDependencyError", { enumerable: true, get: function () { return CircularDependencyError_1.CircularDependencyError; } });
 var FactoryAlreadyBoundError_1 = require("./FactoryAlreadyBoundError");
-exports.FactoryAlreadyBoundError = FactoryAlreadyBoundError_1.FactoryAlreadyBoundError;
+Object.defineProperty(exports, "FactoryAlreadyBoundError", { enumerable: true, get: function () { return FactoryAlreadyBoundError_1.FactoryAlreadyBoundError; } });

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 export * from './errors';
 export { Container } from './Container';
-export { Dependency } from './Dependency';
-export { DependencyKey } from './DependencyKey';
-export { DependencyFacroty } from './DependencyFacroty';
+export type { Dependency } from './Dependency';
+export type { DependencyKey } from './DependencyKey';
+export type { DependencyFactory } from './DependencyFactory';
+export type { ContainerOptions } from './ContainerOptions';

package/dist/index.js

@@ -1,8 +1,20 @@
 "use strict";
-function __export(m) {
-    for (var p in m) if (!exports.hasOwnProperty(p)) exports[p] = m[p];
-}
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
 Object.defineProperty(exports, "__esModule", { value: true });
-__export(require("./errors"));
+exports.Container = void 0;
+__exportStar(require("./errors"), exports);
 var Container_1 = require("./Container");
-exports.Container = Container_1.Container;
+Object.defineProperty(exports, "Container", { enumerable: true, get: function () { return Container_1.Container; } });

package/package.json

@@ -1,12 +1,36 @@
 {
   "name": "plain-ioc",
-  "version": "0.1.3",
+  "version": "1.0.0",
   "description": "Plain inversion of control container",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
+  "type": "commonjs",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "require": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
   "scripts": {
-    "build": "node ./node_modules/typescript/bin/tsc",
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "build": "npm run clean && node ./node_modules/.bin/tsc",
+    "clean": "node -e \"['./dist'].forEach(item => require('fs').rmSync(item, {recursive:true,force:true}));\"",
+    "prepack": "npm run build"
+  },
+  "engines": {
+    "node": ">=6.0.0"
+  },
+  "devEngines": {
+    "runtime": {
+      "name": "node",
+      "version": ">=18.0.0",
+      "onFail": "error"
+    },
+    "packageManager": {
+      "name": "npm",
+      "version": ">=8.6.0",
+      "onFail": "error"
+    }
   },
   "repository": {
     "type": "git",
@@ -24,8 +48,13 @@
     "url": "https://github.com/mvcbox/node-plain-ioc/issues"
   },
   "homepage": "https://github.com/mvcbox/node-plain-ioc#readme",
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
   "devDependencies": {
-    "@types/node": "^12.7.2",
-    "typescript": "^3.5.3"
+    "@types/node": "^6.14.13",
+    "typescript": "^4.7.2"
   }
 }

package/dist/DependencyFacroty.d.ts

@@ -1,4 +0,0 @@
-import { Container } from './Container';
-export interface DependencyFacroty<T> {
-    (container: Container): T;
-}

package/dist/errors/FactoryNotBound.d.ts

@@ -1,2 +0,0 @@
-export declare class FactoryNotBound extends Error {
-}

package/dist/errors/FactoryNotBound.js

@@ -1,23 +0,0 @@
-"use strict";
-var __extends = (this && this.__extends) || (function () {
-    var extendStatics = function (d, b) {
-        extendStatics = Object.setPrototypeOf ||
-            ({ __proto__: [] } instanceof Array && function (d, b) { d.__proto__ = b; }) ||
-            function (d, b) { for (var p in b) if (b.hasOwnProperty(p)) d[p] = b[p]; };
-        return extendStatics(d, b);
-    };
-    return function (d, b) {
-        extendStatics(d, b);
-        function __() { this.constructor = d; }
-        d.prototype = b === null ? Object.create(b) : (__.prototype = b.prototype, new __());
-    };
-})();
-exports.__esModule = true;
-var FactoryNotBound = (function (_super) {
-    __extends(FactoryNotBound, _super);
-    function FactoryNotBound() {
-        return _super !== null && _super.apply(this, arguments) || this;
-    }
-    return FactoryNotBound;
-}(Error));
-exports.FactoryNotBound = FactoryNotBound;