@monkin/di 0.1.12

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Andrey Monkin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,276 @@
+# @monkin/di
+
+[![Tests](https://github.com/monkin/di/actions/workflows/test.yml/badge.svg)](https://github.com/monkin/di/actions/workflows/test.yml)
+[![NPM version](https://img.shields.io/npm/v/@monkin/di.svg)](https://www.npmjs.com/package/@monkin/di)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+`@monkin/di` is a lightweight (472 bytes), type-safe dependency injection container for TypeScript. It leverages TypeScript's advanced type system to provide a fluent API for service registration and resolution with full type safety and autocompletion.
+
+## Table of Contents
+
+- [Features](#features)
+- [Installation](#installation)
+- [Usage](#usage)
+  - [1. Defining a Service](#1-defining-a-service)
+  - [2. Basic Injection](#2-basic-injection)
+  - [3. Services with Dependencies](#3-services-with-dependencies)
+  - [4. Merging Containers](#4-merging-containers)
+  - [5. Lazy](#5-lazy)
+  - [6. Duplicate Service Name Protection](#6-duplicate-service-name-protection)
+  - [7. Reserved Field Names](#7-reserved-field-names)
+  - [8. Circular Dependencies](#8-circular-dependencies)
+- [API Reference](#api-reference)
+- [Development](#development)
+- [License](#license)
+
+## Features
+
+- **Full Type Safety**: Get autocompletion and type checks for all your injected services.
+- **No Decorators**: No need for `reflect-metadata` or experimental decorators. Pure TypeScript.
+- **Fluent API**: Chainable service registration makes it easy to compose your container.
+- **Container Composition**: Merge multiple containers together to share dependencies across different parts of your application.
+- **Lazy**: Services are instantiated only on demand (when first accessed) and reused for subsequent accesses.
+- **Zero Runtime Dependencies**: Extremely lightweight (472 bytes minified / 323 bytes gzipped).
+
+## Installation
+
+```bash
+npm install @monkin/di
+```
+
+## Usage
+
+### 1. Defining a Service
+
+A service is a class that implements the `DiService` interface. It must implement a `getServiceName()` method which will be used as the key in the container. Use `as const` to ensure the name is treated as a literal type.
+
+```typescript
+import { DiService } from '@monkin/di';
+
+export class LoggerService implements DiService<"logger"> {
+    getServiceName() {
+        return "logger" as const;
+    }
+    
+    log(message: string) {
+        console.log(`[LOG]: ${message}`);
+    }
+}
+```
+
+### 2. Basic Injection
+
+Use `DiContainer` to register and resolve your services. You can register a single service or multiple services in one call. When registering multiple services, the order doesn't matter; they can even depend on each other.
+
+```typescript
+import { DiContainer } from '@monkin/di';
+import { LoggerService } from './LoggerService';
+import { ConfigService } from './ConfigService';
+
+// Single service
+const container = new DiContainer()
+    .inject(LoggerService);
+
+// Multiple services in one call (order-independent)
+const multiContainer = new DiContainer()
+    .inject(ConfigService, LoggerService);
+
+// Access the service directly on the container
+container.logger.log("Service is ready!");
+```
+
+### 3. Services with Dependencies
+
+To inject dependencies into a service, define its constructor to accept the container. You can use the `Di<...T>` type helper to specify which services are required. It supports multiple services passed as separate arguments or as a tuple.
+
+```typescript
+import { Di, DiService } from '@monkin/di';
+import { LoggerService } from './LoggerService';
+import { ConfigService } from './ConfigService';
+
+export class UserService implements DiService<"user"> {
+    getServiceName() {
+        return "user" as const;
+    }
+    
+    // Single dependency:
+    // constructor(private di: Di<LoggerService>) {}
+
+    // Multiple dependencies:
+    constructor(private di: Di<LoggerService, ConfigService>) {}
+
+    getUser(id: string) {
+        const prefix = this.di.config.get("userPrefix");
+        this.di.logger.log(`Fetching user: ${prefix}${id}`);
+        return { id, name: "User " + id };
+    }
+}
+
+const container = new DiContainer()
+    .inject(LoggerService)
+    .inject(ConfigService)
+    .inject(UserService);
+
+container.user.getUser("42");
+```
+
+When using `inject` with multiple services, they can depend on each other regardless of the order they are passed to the method.
+
+### 4. Merging Containers
+
+You can create specialized containers and merge them into a main container using `injectContainer`.
+
+```typescript
+const authContainer = new DiContainer().inject(AuthService);
+const apiContainer = new DiContainer().inject(ApiService);
+
+const appContainer = new DiContainer()
+    .injectContainer(authContainer)
+    .injectContainer(apiContainer)
+    .inject(MainApp);
+```
+
+### 5. Lazy
+
+Services registered via `inject` are lazy by default. When you register a service, `@monkin/di` creates a **Proxy** for it on the container. The actual service instance is only created when you first interact with it (e.g., call a method, access a property). Once created, the same instance is reused for all subsequent accesses.
+
+```typescript
+const container = new DiContainer()
+    .inject(ExpensiveService);
+
+// ExpensiveService is NOT instantiated yet
+const service = container.expensive; 
+// Still NOT instantiated! `service` is a Proxy.
+
+console.log("Container ready");
+
+// ExpensiveService is instantiated NOW because we access a property/method
+service.doSomething();
+```
+
+### 6. Duplicate Service Name Protection
+
+`@monkin/di` prevents registering multiple services with the same name. This protection works at both compile-time and runtime:
+
+- **Type-level Check**: If you try to `inject` a service with a name that already exists in the container, TypeScript will report an error, and the resulting type will be a string literal describing the error.
+- **Runtime Check**: The `inject` and `injectContainer` methods will throw an `Error` if a duplicate key is detected.
+
+```typescript
+const container = new DiContainer()
+    .inject(LoggerService);
+
+// TypeScript Error: Type '"Duplicate service name: logger"' ...
+// Runtime Error: Duplicated service name: logger
+container.inject(AnotherLoggerService); 
+```
+
+### 7. Reserved Field Names
+
+Since `DiContainer` uses a fluent API, certain names are reserved for its internal methods and cannot be used as service names:
+
+- `inject`
+- `injectContainer`
+
+Similar to duplicate names, attempting to use a reserved name will trigger both a **Type-level Check** and a **Runtime Check**.
+
+```typescript
+class InjectService implements DiService<"inject"> {
+    getServiceName() { return "inject" as const; }
+}
+
+const container = new DiContainer();
+
+// TypeScript Error: Type '"Reserved field name: inject"' ...
+// Runtime Error: Reserved service name: inject
+container.inject(InjectService);
+```
+
+### 8. Circular Dependencies
+
+`@monkin/di` supports circular dependencies between services because it uses **Proxies** for lazy initialization. A service can depend on another service that depends back on it, provided that they don't try to access each other's methods or properties in their constructors.
+
+```typescript
+class ServiceA implements DiService<"a"> {
+    getServiceName() { return "a" as const; }
+    constructor(private di: Di<ServiceB>) {}
+    
+    doA() {
+        console.log("A doing something...");
+        this.di.b.doB();
+    }
+}
+
+class ServiceB implements DiService<"b"> {
+    getServiceName() { return "b" as const; }
+    constructor(private di: Di<ServiceA>) {}
+    
+    doB() {
+        console.log("B doing something...");
+    }
+}
+
+const container = new DiContainer().inject(ServiceA, ServiceB);
+container.a.doA(); // Works fine!
+```
+
+> [!IMPORTANT]
+> Do not access circular dependencies in the constructor, as this will trigger a stack overflow during instantiation.
+
+## API Reference
+
+### `DiContainer`
+
+The main class for managing services.
+
+- `inject(...ServiceClasses: new (di: any) => any): DiContainer`
+  Registers one or more service classes. Returns the container instance, typed with the newly added services. Each service can depend on other services provided in the same call or already present in the container.
+- `injectContainer<DC extends DiContainer>(other: DC): this & DC`
+  Copies all services from another container into this one. Returns the container instance, typed with the merged services.
+
+### `DiService<Name>`
+
+An interface that your service classes must implement.
+
+- `getServiceName(this: null): Name`
+  Must return the unique name of the service as a string literal type.
+
+### `Di<...S>`
+
+A utility type to help define dependencies in your service constructors.
+
+- `Di<ServiceClass>`: Resolves to an object with the service name as the key and the service instance as the value.
+- `Di<Service1, Service2, ...>`: Resolves to a merged object containing all specified services.
+
+## Development
+
+### Installation
+
+```bash
+npm install
+```
+
+### Build
+
+```bash
+npm run build
+```
+
+### Test
+
+```bash
+npm test
+npm run test:watch  # Watch mode
+```
+
+### Linting & Formatting
+
+```bash
+npm run lint          # Run Biome check (lint, format, and import sorting)
+npm run format        # Format code with Biome
+npm run format:check  # Check code formatting with Biome
+```
+
+## License
+
+MIT
+

package/dist/di.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Base interface for services in the DI system.
+ * The `name` property is used as the key when the service is injected into a DiContainer.
+ */
+export interface DiService<Name extends string> {
+    /**
+     * The name of the service.
+     * This is used as the key when the service is injected into a DiContainer.
+     *
+     * The method is called without an instance context, so it can be used as a static property.
+     */
+    getServiceName(this: null): Name;
+}
+/**
+ * A type transformation that converts one or more Services (passed as separate
+ * arguments) into a merged mapped object type.
+ *
+ * Example: Di<LoggerService> -> { logger: LoggerService }
+ * Example: Di<ServiceA, ServiceB> -> { a: ServiceA } & { b: ServiceB }
+ */
+export type Di<S1, S2 = never, S3 = never, S4 = never, S5 = never, S6 = never, S7 = never, S8 = never, S9 = never, S10 = never, S11 = never, S12 = never, S13 = never, S14 = never, S15 = never, S16 = never> = ToDi<S1> & ToDi<S2> & ToDi<S3> & ToDi<S4> & ToDi<S5> & ToDi<S6> & ToDi<S7> & ToDi<S8> & ToDi<S9> & ToDi<S10> & ToDi<S11> & ToDi<S12> & ToDi<S13> & ToDi<S14> & ToDi<S15> & ToDi<S16>;
+type ToDi<S> = [S] extends [never] ? unknown : S extends DiService<infer Name> ? {
+    [Key in Name]: S;
+} : never;
+type CheckReservedField<Name, T> = Name extends keyof DiContainer ? `Reserved field name: ${Name}` : T;
+type Append<Container, Service extends DiService<string>> = Container extends object ? Service extends DiService<infer Name> ? CheckReservedField<Name, Container extends {
+    [Key in Name]: unknown;
+} ? `Duplicate service name: ${Name}` : Container & Di<Service>> : never : Container;
+/**
+ * A recursive type transformation that appends multiple services to a container.
+ */
+export type AppendAll<Container, Services extends any[]> = Container extends object ? Services extends [infer Head, ...infer Tail] ? Head extends DiService<string> ? AppendAll<Append<Container, Head>, Tail> : AppendAll<Container, Tail> : Container : Container;
+type Merge<DI1, DI2> = DI1 extends object ? DI2 extends object ? Exclude<keyof DI1, keyof DiContainer> & Exclude<keyof DI2, keyof DiContainer> extends never ? DI1 & DI2 : `Containers have duplicated keys: ${(Exclude<keyof DI1, keyof DiContainer> & Exclude<keyof DI2, keyof DiContainer>) & string}` : DI2 : DI1;
+/**
+ * DiContainer manages service instantiation and dependency resolution.
+ * It uses a fluent interface to chain service registrations, dynamically
+ * extending its own type with each injected service.
+ */
+export declare class DiContainer {
+    /**
+     * Register services.
+     * Each service can depend on all others provided in the same call.
+     */
+    inject<S extends DiService<string>[]>(...dependencies: {
+        [K in keyof S]: new (dependencies: AppendAll<this, S>) => S[K];
+    }): AppendAll<this, S>;
+    /**
+     * Copies all service properties from another container into this one.
+     * Useful for composing containers or providing shared dependencies.
+     *
+     * @template DC - The type of the other DiContainer.
+     * @param other - The source container to copy services from.
+     * @returns The current container instance, typed with the merged services.
+     * @throws {Error} If any service name from the other container already exists in this container.
+     */
+    injectContainer<DC extends DiContainer>(other: DC): Merge<this, DC>;
+}
+export {};
+//# sourceMappingURL=di.d.ts.map

package/dist/di.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"di.d.ts","sourceRoot":"","sources":["../src/di.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,WAAW,SAAS,CAAC,IAAI,SAAS,MAAM;IAC1C;;;;;OAKG;IACH,cAAc,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,CAAC;CACpC;AAED;;;;;;GAMG;AACH,MAAM,MAAM,EAAE,CACV,EAAE,EACF,EAAE,GAAG,KAAK,EACV,EAAE,GAAG,KAAK,EACV,EAAE,GAAG,KAAK,EACV,EAAE,GAAG,KAAK,EACV,EAAE,GAAG,KAAK,EACV,EAAE,GAAG,KAAK,EACV,EAAE,GAAG,KAAK,EACV,EAAE,GAAG,KAAK,EACV,GAAG,GAAG,KAAK,EACX,GAAG,GAAG,KAAK,EACX,GAAG,GAAG,KAAK,EACX,GAAG,GAAG,KAAK,EACX,GAAG,GAAG,KAAK,EACX,GAAG,GAAG,KAAK,EACX,GAAG,GAAG,KAAK,IACX,IAAI,CAAC,EAAE,CAAC,GACR,IAAI,CAAC,EAAE,CAAC,GACR,IAAI,CAAC,EAAE,CAAC,GACR,IAAI,CAAC,EAAE,CAAC,GACR,IAAI,CAAC,EAAE,CAAC,GACR,IAAI,CAAC,EAAE,CAAC,GACR,IAAI,CAAC,EAAE,CAAC,GACR,IAAI,CAAC,EAAE,CAAC,GACR,IAAI,CAAC,EAAE,CAAC,GACR,IAAI,CAAC,GAAG,CAAC,GACT,IAAI,CAAC,GAAG,CAAC,GACT,IAAI,CAAC,GAAG,CAAC,GACT,IAAI,CAAC,GAAG,CAAC,GACT,IAAI,CAAC,GAAG,CAAC,GACT,IAAI,CAAC,GAAG,CAAC,GACT,IAAI,CAAC,GAAG,CAAC,CAAC;AAEd,KAAK,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,GAC5B,OAAO,GACP,CAAC,SAAS,SAAS,CAAC,MAAM,IAAI,CAAC,GAC7B;KAAG,GAAG,IAAI,IAAI,GAAG,CAAC;CAAE,GACpB,KAAK,CAAC;AAEd,KAAK,kBAAkB,CAAC,IAAI,EAAE,CAAC,IAAI,IAAI,SAAS,MAAM,WAAW,GAC3D,wBAAwB,IAAI,EAAE,GAC9B,CAAC,CAAC;AAER,KAAK,MAAM,CACP,SAAS,EACT,OAAO,SAAS,SAAS,CAAC,MAAM,CAAC,IACjC,SAAS,SAAS,MAAM,GACtB,OAAO,SAAS,SAAS,CAAC,MAAM,IAAI,CAAC,GACjC,kBAAkB,CACd,IAAI,EACJ,SAAS,SAAS;KAAG,GAAG,IAAI,IAAI,GAAG,OAAO;CAAE,GACtC,2BAA2B,IAAI,EAAE,GACjC,SAAS,GAAG,EAAE,CAAC,OAAO,CAAC,CAChC,GACD,KAAK,GACT,SAAS,CAAC;AAEhB;;GAEG;AACH,MAAM,MAAM,SAAS,CACjB,SAAS,EACT,QAAQ,SAAS,GAAG,EAAE,IACtB,SAAS,SAAS,MAAM,GACtB,QAAQ,SAAS,CAAC,MAAM,IAAI,EAAE,GAAG,MAAM,IAAI,CAAC,GACxC,IAAI,SAAS,SAAS,CAAC,MAAM,CAAC,GAC1B,SAAS,CAAC,MAAM,CAAC,SAAS,EAAE,IAAI,CAAC,EAAE,IAAI,CAAC,GACxC,SAAS,CAAC,SAAS,EAAE,IAAI,CAAC,GAC9B,SAAS,GACb,SAAS,CAAC;AAEhB,KAAK,KAAK,CAAC,GAAG,EAAE,GAAG,IAAI,GAAG,SAAS,MAAM,GACnC,GAAG,SAAS,MAAM,GACd,OAAO,CAAC,MAAM,GAAG,EAAE,MAAM,WAAW,CAAC,GACjC,OAAO,CAAC,MAAM,GAAG,EAAE,MAAM,WAAW,CAAC,SAAS,KAAK,GACnD,GAAG,GAAG,GAAG,GACT,oCAAoC,CAAC,OAAO,CACxC,MAAM,GAAG,EACT,MAAM,WAAW,CACpB,GACG,OAAO,CAAC,MAAM,GAAG,EAAE,MAAM,WAAW,CAAC,CAAC,GACtC,MAAM,EAAE,GAChB,GAAG,GACP,GAAG,CAAC;AAEV;;;;GAIG;AACH,qBAAa,WAAW;IACpB;;;OAGG;IACH,MAAM,CAAC,CAAC,SAAS,SAAS,CAAC,MAAM,CAAC,EAAE,EAChC,GAAG,YAAY,EAAE;SACZ,CAAC,IAAI,MAAM,CAAC,GAAG,KACZ,YAAY,EAAE,SAAS,CAAC,IAAI,EAAE,CAAC,CAAC,KAC/B,CAAC,CAAC,CAAC,CAAC;KACZ,GACF,SAAS,CAAC,IAAI,EAAE,CAAC,CAAC;IA8BrB;;;;;;;;OAQG;IACH,eAAe,CAAC,EAAE,SAAS,WAAW,EAAE,KAAK,EAAE,EAAE,GAAG,KAAK,CAAC,IAAI,EAAE,EAAE,CAAC;CAStE"}

package/dist/index.js

@@ -0,0 +1 @@
+class e{inject(...e){return e.reduce((e,t)=>{let r,n=t.prototype,i=(0,n.getServiceName)();if(e[i])throw Error((/^inject(Container)?$/.test(i)?"Reserv":"Duplicat")+"ed service name: "+i);return e[i]=new Proxy(Object.create(n),{get:(n,o)=>{r||=e[i]=new t(e);let a=r[o];return"function"==typeof a?a.bind(r):a}}),e},this)}injectContainer(e){for(let t in e)if(t in this)throw Error("Containers have duplicated keys: "+t);return Object.assign(this,e)}}export{e as DiContainer};

package/dist/index.umd.cjs

@@ -0,0 +1 @@
+!function(e,t){"object"==typeof exports&&typeof module<"u"?t(exports):"function"==typeof define&&define.amd?define(["exports"],t):t((e=typeof globalThis<"u"?globalThis:e||self).Di={})}(this,function(e){"use strict";e.DiContainer=class{inject(...e){return e.reduce((e,t)=>{let i,n=t.prototype,r=(0,n.getServiceName)();if(e[r])throw Error((/^inject(Container)?$/.test(r)?"Reserv":"Duplicat")+"ed service name: "+r);return e[r]=new Proxy(Object.create(n),{get:(n,o)=>{i||=e[r]=new t(e);let s=i[o];return"function"==typeof s?s.bind(i):s}}),e},this)}injectContainer(e){for(let t in e)if(t in this)throw Error("Containers have duplicated keys: "+t);return Object.assign(this,e)}},Object.defineProperty(e,Symbol.toStringTag,{value:"Module"})});

package/package.json

@@ -0,0 +1,66 @@
+{
+    "name": "@monkin/di",
+    "version": "0.1.12",
+    "description": "Small type-safe dependency injection lib",
+    "type": "module",
+    "main": "./dist/index.js",
+    "types": "./dist/di.d.ts",
+    "exports": {
+        ".": {
+            "types": "./dist/di.d.ts",
+            "import": "./dist/index.js",
+            "require": "./dist/index.umd.cjs"
+        }
+    },
+    "files": [
+        "dist"
+    ],
+    "sideEffects": false,
+    "engines": {
+        "node": ">=18.0.0"
+    },
+    "scripts": {
+        "build": "vite build",
+        "test": "vitest run",
+        "test:watch": "vitest",
+        "lint": "biome check src",
+        "format": "biome format --write src",
+        "format:check": "biome format src",
+        "prepublishOnly": "npm run lint && npm run test && npm run build"
+    },
+    "keywords": [
+        "dependency-injection",
+        "di",
+        "typescript",
+        "type-safe",
+        "container",
+        "ioc",
+        "lightweight"
+    ],
+    "author": {
+        "name": "Andrei Monkin",
+        "email": "monkin.andrey@gmail.com",
+        "url": "https://github.com/monkin"
+    },
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/monkin/di.git"
+    },
+    "bugs": {
+        "url": "https://github.com/monkin/di/issues"
+    },
+    "homepage": "https://github.com/monkin/di#readme",
+    "license": "MIT",
+    "publishConfig": {
+        "access": "public"
+    },
+    "devDependencies": {
+        "@biomejs/biome": "^2.3.15",
+        "@types/node": "^25.0.9",
+        "terser": "^5.46.0",
+        "typescript": "^5.9.3",
+        "vite": "^7.3.1",
+        "vite-plugin-dts": "^4.5.4",
+        "vitest": "^4.0.18"
+    }
+}