syrinject 0.1.0 → 0.1.2

package/README.md

@@ -1,5 +1,208 @@
 <p align="center">
-	<img src="https://cdn.jsdelivr.net/npm/syrinject@latest/assets/logo-without-background.png" alt="Syrinject Logo" width="500" />
+	<img src="https://cdn.jsdelivr.net/npm/syrinject@latest/assets/Syringect-Black.png" alt="Syrinject Logo" width="500" />
 </p>
 
-<hr>
+<p align="center">
+	<strong>A tiny, modern dependency injection container for TypeScript.</strong>
+</p>
+
+<hr>
+
+## Overview
+
+Syrinject is a lightweight Dependency Injection (DI) container built for TypeScript. It focuses on clarity and explicitness while remaining flexible enough for small apps and larger codebases. You can register providers and resolve dependencies by token.
+
+## Features
+
+- ✅ Simple DI container API.
+- ✅ Typed tokens for safe resolution.
+- ✅ Class, value, and factory providers.
+- ✅ Singleton or transient lifetimes.
+- ✅ Optional logging decorator for class usage.
+- ✅ Clear error messages for invalid providers, missing dependencies, and circular graphs.
+
+## Installation
+
+```bash
+npm install syrinject
+```
+
+## Quick Start
+
+```ts
+import { Container } from "syrinject";
+
+// Tokens can be string, symbol, or class constructors
+const LoggerToken = "Logger";
+
+interface Logger {
+	log(message: string): void;
+}
+
+class ConsoleLogger implements Logger {
+	log(message: string) {
+		console.log(message);
+	}
+}
+
+const container = new Container();
+
+// Register a token with a class provider
+container.register(LoggerToken, {
+	useClass: ConsoleLogger,
+	singleton: true,
+});
+
+const logger = container.resolve<Logger>(LoggerToken);
+logger.log("Hello from Syrinject!");
+```
+
+## Core Concepts
+
+### Tokens
+
+Tokens are identifiers for dependencies. Use a `string`, `symbol`, or a class constructor.
+
+```ts
+export interface HttpClient {
+	get(url: string): Promise<string>;
+}
+
+export const HttpClientToken = "HttpClient";
+```
+
+### Providers
+
+Providers define how a dependency is created.
+
+#### Class Provider
+
+```ts
+container.register(HttpClientToken, {
+	useClass: FetchHttpClient,
+	singleton: false,
+	deps: [LoggerToken],
+});
+```
+
+#### Value Provider
+
+```ts
+container.register(HttpClientToken, {
+	useValue: { get: async (url) => fetch(url).then((r) => r.text()) },
+});
+```
+
+#### Factory Provider
+
+```ts
+container.register(HttpClientToken, {
+	useFactory: (c) => new FetchHttpClient(c.resolve(LoggerToken)),
+	singleton: true,
+});
+```
+
+### Lifetimes
+
+- `singleton: true` creates and caches a single instance.
+- `singleton: false` creates a new instance on each resolve (default).
+
+### Decorator: Logger
+
+Syrinject includes a `Logger` decorator that logs instantiation and public method calls.
+To show dependencies and singleton status in logs, set static `deps` (or `dependencies`) and `singleton` on the class.
+
+```ts
+import { Container, Logger } from "syrinject";
+
+const LoggerToken = "Logger";
+
+interface LoggerService {
+	log(message: string): void;
+}
+
+class ConsoleLogger implements LoggerService {
+	log(message: string) {
+		console.log(message);
+	}
+}
+
+@Logger()
+class UserService {
+	static deps = [LoggerToken];
+	static singleton = true;
+
+	constructor(private readonly logger: LoggerService) {}
+
+	createUser(name: string) {
+		this.logger.log(`Creating user: ${name}`);
+	}
+}
+
+const container = new Container();
+container.register(LoggerToken, { useClass: ConsoleLogger, singleton: true });
+container.register(UserService, { useClass: UserService, deps: UserService.deps, singleton: true });
+
+const service = container.resolve(UserService);
+service.createUser("Ada");
+```
+
+## Container API
+
+### `register(token, provider)`
+
+Registers a provider for a token.
+
+### `resolve(token)`
+
+Resolves an instance for the given token.
+
+### `unregister(token)`
+
+Removes a token from the container.
+
+### `clear()`
+
+Clears all registrations.
+
+### `has(token)`
+
+Checks if a token is registered.
+
+### `registerClass(...)`
+
+Registers a class provider. You can pass a token + class, or only a class.
+When only a class is provided, the token will be the class name (string).
+
+### `registerValue(token, value)`
+
+Registers a value provider.
+
+### `registerFactory(token, factory, options?)`
+
+Registers a factory provider.
+
+## Errors
+
+Syrinject throws descriptive errors to simplify debugging:
+
+- `DependencyNotFoundError` when a token is not registered.
+- `InvalidProviderError` when a provider is malformed.
+- `CircularDependencyError` when a dependency graph loops.
+
+## TypeScript Configuration
+
+If you use the `Logger` decorator, enable decorators in `tsconfig.json`:
+
+```json
+{
+	"compilerOptions": {
+		"experimentalDecorators": true,
+		"emitDecoratorMetadata": false
+	}
+}
+```
+
+## License
+
+MIT

package/dist/container.test.js

@@ -0,0 +1,102 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_test_1 = __importDefault(require("node:test"));
+const strict_1 = __importDefault(require("node:assert/strict"));
+const node_path_1 = __importDefault(require("node:path"));
+const { Container, CircularDependencyError, DependencyNotFoundError, InvalidProviderError } = require(node_path_1.default.resolve(__dirname, '..', '..', 'dist'));
+(0, node_test_1.default)('resolve class with deps from options', () => {
+    class Engine {
+        constructor() {
+            this.kind = 'v8';
+        }
+    }
+    class Car {
+        constructor(engine) {
+            this.engine = engine;
+        }
+    }
+    const container = new Container();
+    container.register(Engine, Engine);
+    container.register(Car, Car, { deps: [Engine] });
+    const car = container.resolve(Car);
+    strict_1.default.equal(car.engine.kind, 'v8');
+});
+(0, node_test_1.default)('registerClass infers token by class name', () => {
+    class Service {
+        constructor() {
+            this.value = 42;
+        }
+    }
+    const container = new Container();
+    container.registerClass(Service);
+    const resolved = container.resolve('Service');
+    strict_1.default.ok(resolved instanceof Service);
+    strict_1.default.equal(resolved.value, 42);
+});
+(0, node_test_1.default)('singleton class provider returns same instance', () => {
+    class Counter {
+        constructor() {
+            this.count = 0;
+        }
+    }
+    const container = new Container();
+    container.register(Counter, Counter, { singleton: true });
+    const a = container.resolve(Counter);
+    const b = container.resolve(Counter);
+    strict_1.default.equal(a, b);
+});
+(0, node_test_1.default)('value provider returns same value', () => {
+    const container = new Container();
+    container.registerValue('config', { port: 3000 });
+    const config = container.resolve('config');
+    strict_1.default.deepEqual(config, { port: 3000 });
+});
+(0, node_test_1.default)('factory provider builds instance', () => {
+    const container = new Container();
+    container.registerFactory('random', () => ({ value: Math.random() }));
+    const a = container.resolve('random');
+    const b = container.resolve('random');
+    strict_1.default.notEqual(a, b);
+    strict_1.default.equal(typeof a.value, 'number');
+});
+(0, node_test_1.default)('factory provider respects singleton', () => {
+    const container = new Container();
+    container.registerFactory('singleton', () => ({ value: Math.random() }), { singleton: true });
+    const a = container.resolve('singleton');
+    const b = container.resolve('singleton');
+    strict_1.default.equal(a, b);
+});
+(0, node_test_1.default)('throws DependencyNotFoundError for missing token', () => {
+    const container = new Container();
+    strict_1.default.throws(() => container.resolve('missing'), (err) => err instanceof DependencyNotFoundError);
+});
+(0, node_test_1.default)('throws CircularDependencyError when cycle exists', () => {
+    class A {
+    }
+    class B {
+    }
+    const container = new Container();
+    container.register(A, A, { deps: [B] });
+    container.register(B, B, { deps: [A] });
+    strict_1.default.throws(() => container.resolve(A), (err) => err instanceof CircularDependencyError);
+});
+(0, node_test_1.default)('throws InvalidProviderError for invalid provider', () => {
+    const container = new Container();
+    container.register('invalid', {});
+    strict_1.default.throws(() => container.resolve('invalid'), (err) => err instanceof InvalidProviderError);
+});
+(0, node_test_1.default)('has, unregister, clear work as expected', () => {
+    const container = new Container();
+    container.registerValue('token', 123);
+    strict_1.default.equal(container.has('token'), true);
+    container.unregister('token');
+    strict_1.default.equal(container.has('token'), false);
+    container.registerValue('a', 1);
+    container.registerValue('b', 2);
+    container.clear();
+    strict_1.default.equal(container.has('a'), false);
+    strict_1.default.equal(container.has('b'), false);
+});

package/dist/test/container.test.js

@@ -0,0 +1,102 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_test_1 = __importDefault(require("node:test"));
+const strict_1 = __importDefault(require("node:assert/strict"));
+const node_path_1 = __importDefault(require("node:path"));
+const { Container, CircularDependencyError, DependencyNotFoundError, InvalidProviderError } = require(node_path_1.default.resolve(__dirname, '..', '..', 'dist'));
+(0, node_test_1.default)('resolve class with deps from options', () => {
+    class Engine {
+        constructor() {
+            this.kind = 'v8';
+        }
+    }
+    class Car {
+        constructor(engine) {
+            this.engine = engine;
+        }
+    }
+    const container = new Container();
+    container.register(Engine, Engine);
+    container.register(Car, Car, { deps: [Engine] });
+    const car = container.resolve(Car);
+    strict_1.default.equal(car.engine.kind, 'v8');
+});
+(0, node_test_1.default)('registerClass infers token by class name', () => {
+    class Service {
+        constructor() {
+            this.value = 42;
+        }
+    }
+    const container = new Container();
+    container.registerClass(Service);
+    const resolved = container.resolve('Service');
+    strict_1.default.ok(resolved instanceof Service);
+    strict_1.default.equal(resolved.value, 42);
+});
+(0, node_test_1.default)('singleton class provider returns same instance', () => {
+    class Counter {
+        constructor() {
+            this.count = 0;
+        }
+    }
+    const container = new Container();
+    container.register(Counter, Counter, { singleton: true });
+    const a = container.resolve(Counter);
+    const b = container.resolve(Counter);
+    strict_1.default.equal(a, b);
+});
+(0, node_test_1.default)('value provider returns same value', () => {
+    const container = new Container();
+    container.registerValue('config', { port: 3000 });
+    const config = container.resolve('config');
+    strict_1.default.deepEqual(config, { port: 3000 });
+});
+(0, node_test_1.default)('factory provider builds instance', () => {
+    const container = new Container();
+    container.registerFactory('random', () => ({ value: Math.random() }));
+    const a = container.resolve('random');
+    const b = container.resolve('random');
+    strict_1.default.notEqual(a, b);
+    strict_1.default.equal(typeof a.value, 'number');
+});
+(0, node_test_1.default)('factory provider respects singleton', () => {
+    const container = new Container();
+    container.registerFactory('singleton', () => ({ value: Math.random() }), { singleton: true });
+    const a = container.resolve('singleton');
+    const b = container.resolve('singleton');
+    strict_1.default.equal(a, b);
+});
+(0, node_test_1.default)('throws DependencyNotFoundError for missing token', () => {
+    const container = new Container();
+    strict_1.default.throws(() => container.resolve('missing'), (err) => err instanceof DependencyNotFoundError);
+});
+(0, node_test_1.default)('throws CircularDependencyError when cycle exists', () => {
+    class A {
+    }
+    class B {
+    }
+    const container = new Container();
+    container.register(A, A, { deps: [B] });
+    container.register(B, B, { deps: [A] });
+    strict_1.default.throws(() => container.resolve(A), (err) => err instanceof CircularDependencyError);
+});
+(0, node_test_1.default)('throws InvalidProviderError for invalid provider', () => {
+    const container = new Container();
+    container.register('invalid', {});
+    strict_1.default.throws(() => container.resolve('invalid'), (err) => err instanceof InvalidProviderError);
+});
+(0, node_test_1.default)('has, unregister, clear work as expected', () => {
+    const container = new Container();
+    container.registerValue('token', 123);
+    strict_1.default.equal(container.has('token'), true);
+    container.unregister('token');
+    strict_1.default.equal(container.has('token'), false);
+    container.registerValue('a', 1);
+    container.registerValue('b', 2);
+    container.clear();
+    strict_1.default.equal(container.has('a'), false);
+    strict_1.default.equal(container.has('b'), false);
+});

package/dist/test/test/container.test.js

@@ -0,0 +1,101 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_test_1 = __importDefault(require("node:test"));
+const strict_1 = __importDefault(require("node:assert/strict"));
+const dist_1 = require("../dist");
+(0, node_test_1.default)('resolve class with deps from options', () => {
+    class Engine {
+        constructor() {
+            this.kind = 'v8';
+        }
+    }
+    class Car {
+        constructor(engine) {
+            this.engine = engine;
+        }
+    }
+    const container = new dist_1.Container();
+    container.register(Engine, Engine);
+    container.register(Car, Car, { deps: [Engine] });
+    const car = container.resolve(Car);
+    strict_1.default.equal(car.engine.kind, 'v8');
+});
+(0, node_test_1.default)('registerClass infers token by class name', () => {
+    class Service {
+        constructor() {
+            this.value = 42;
+        }
+    }
+    const container = new dist_1.Container();
+    container.registerClass(Service);
+    const resolved = container.resolve('Service');
+    strict_1.default.ok(resolved instanceof Service);
+    strict_1.default.equal(resolved.value, 42);
+});
+(0, node_test_1.default)('singleton class provider returns same instance', () => {
+    class Counter {
+        constructor() {
+            this.count = 0;
+        }
+    }
+    const container = new dist_1.Container();
+    container.register(Counter, Counter, { singleton: true });
+    const a = container.resolve(Counter);
+    const b = container.resolve(Counter);
+    strict_1.default.equal(a, b);
+});
+(0, node_test_1.default)('value provider returns same value', () => {
+    const container = new dist_1.Container();
+    container.registerValue('config', { port: 3000 });
+    const config = container.resolve('config');
+    strict_1.default.deepEqual(config, { port: 3000 });
+});
+(0, node_test_1.default)('factory provider builds instance', () => {
+    const container = new dist_1.Container();
+    container.registerFactory('random', () => ({ value: Math.random() }));
+    const a = container.resolve('random');
+    const b = container.resolve('random');
+    strict_1.default.notEqual(a, b);
+    strict_1.default.equal(typeof a.value, 'number');
+});
+(0, node_test_1.default)('factory provider respects singleton', () => {
+    const container = new dist_1.Container();
+    container.registerFactory('singleton', () => ({ value: Math.random() }), { singleton: true });
+    const a = container.resolve('singleton');
+    const b = container.resolve('singleton');
+    strict_1.default.equal(a, b);
+});
+(0, node_test_1.default)('throws DependencyNotFoundError for missing token', () => {
+    const container = new dist_1.Container();
+    strict_1.default.throws(() => container.resolve('missing'), (err) => err instanceof dist_1.DependencyNotFoundError);
+});
+(0, node_test_1.default)('throws CircularDependencyError when cycle exists', () => {
+    class A {
+    }
+    class B {
+    }
+    const container = new dist_1.Container();
+    container.register(A, A, { deps: [B] });
+    container.register(B, B, { deps: [A] });
+    strict_1.default.throws(() => container.resolve(A), (err) => err instanceof dist_1.CircularDependencyError);
+});
+(0, node_test_1.default)('throws InvalidProviderError for invalid provider', () => {
+    const container = new dist_1.Container();
+    container.register('invalid', {});
+    strict_1.default.throws(() => container.resolve('invalid'), (err) => err instanceof dist_1.InvalidProviderError);
+});
+(0, node_test_1.default)('has, unregister, clear work as expected', () => {
+    const container = new dist_1.Container();
+    container.registerValue('token', 123);
+    strict_1.default.equal(container.has('token'), true);
+    container.unregister('token');
+    strict_1.default.equal(container.has('token'), false);
+    container.registerValue('a', 1);
+    container.registerValue('b', 2);
+    container.clear();
+    strict_1.default.equal(container.has('a'), false);
+    strict_1.default.equal(container.has('b'), false);
+});

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "syrinject",
   "description": "Simple dependency injection container",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": [
@@ -11,13 +11,15 @@
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
     "dev": "tsc -w",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "npm run build",
+    "test": "npm run build && tsc -p tsconfig.test.json && node --test \"dist/test/*.test.js\""
   },
   "keywords": [],
   "author": "andersonreges",
   "license": "ISC",
   "type": "commonjs",
   "devDependencies": {
+    "@types/node": "^25.2.0",
     "typescript": "^5.9.3"
   }
 }

package/dist/package.json

@@ -1,20 +0,0 @@
-{
-  "name": "simple-di-container",
-  "description": "Simple dependency injection container",
-  "version": "0.1.0",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
-  "files": ["dist"],
-  "scripts": {
-    "build": "tsc -p tsconfig.build.json",
-    "dev": "tsc -w",
-    "prepublishOnly": "npm run build"
-  },
-  "keywords": [],
-  "author": "andersonreges",
-  "license": "ISC",
-  "type": "commonjs",
-  "devDependencies": {
-    "typescript": "^5.9.3"
-  }
-}