injectdi 0.0.1

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026 Hossam Hamdy
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,24 @@
+# Inject DI
+
+High-performant, decorator-free dependency IoC container for Node.js.
+
+> **Status: pre-alpha (`0.0.x`).** The public API is being designed in the open. Implementation is incomplete and breaking changes will land on every release until `0.1.0`. Do not use in production yet.
+
+## Install
+
+```sh
+npm install injectdi
+
+pnpm install injectdi
+
+yarn install injectdi
+```
+
+## Requirements
+
+- Node.js `>=22.12.0`
+- ESM only — no CommonJS build is shipped. Consumers on Node `>=22.12.0` can still `require()` it via Node's built-in `require(esm)` interop.
+
+## License
+
+[ISC](./LICENSE) © Hossam Hamdy

package/dist/binding.d.ts

@@ -0,0 +1,9 @@
+import type { Lifetime } from "./lifetime.ts";
+export declare const EMPTY: unique symbol;
+export declare const CIRCULAR: unique symbol;
+export interface Binding<T = unknown> {
+    factory: (() => T) | undefined;
+    value: T | typeof EMPTY | typeof CIRCULAR;
+    lifetime: Lifetime;
+}
+export declare function createBinding<T>(factory: (() => T) | undefined, value: T | typeof EMPTY, lifetime: Lifetime): Binding<T>;

package/dist/binding.js

@@ -0,0 +1,5 @@
+export const EMPTY = Symbol("EMPTY");
+export const CIRCULAR = Symbol("CIRCULAR");
+export function createBinding(factory, value, lifetime) {
+    return { factory, value, lifetime };
+}

package/dist/errors.d.ts

@@ -0,0 +1,22 @@
+import type { Token } from "./token.ts";
+/** Throws an error when a token is not found. */
+export declare class ProviderNotFoundError extends Error {
+    readonly name = "ProviderNotFoundError";
+    readonly scopeName?: string;
+    constructor(token: Token, scopeName?: string);
+}
+/** circular dependency runtime error. */
+export declare class CircularDependencyError extends Error {
+    readonly name = "CircularDependencyError";
+    constructor(token: Token);
+}
+/** inject() called outside of a factory or runInInjectionContext. */
+export declare class InjectionContextError extends Error {
+    readonly name = "InjectionContextError";
+    constructor(token?: Token);
+}
+/** Container or scope has already been destroyed. */
+export declare class ScopeDestroyedError extends Error {
+    readonly name = "ScopeDestroyedError";
+    constructor(name?: string);
+}

package/dist/errors.js

@@ -0,0 +1,32 @@
+import { tokenName } from "./token.js";
+/** Throws an error when a token is not found. */
+export class ProviderNotFoundError extends Error {
+    name = "ProviderNotFoundError";
+    scopeName;
+    constructor(token, scopeName) {
+        super(`Provider not found for: ${tokenName(token)}.`);
+        this.scopeName = scopeName;
+    }
+}
+/** circular dependency runtime error. */
+export class CircularDependencyError extends Error {
+    name = "CircularDependencyError";
+    constructor(token) {
+        super(`Circular dependency detected for: ${tokenName(token)}.`);
+    }
+}
+/** inject() called outside of a factory or runInInjectionContext. */
+export class InjectionContextError extends Error {
+    name = "InjectionContextError";
+    constructor(token) {
+        super(`inject(${token ? `${tokenName(token)}` : ""}) called outside of an injection context. ` +
+            "can only be used within an injection context such as a constructor, a factory function, a field initializer, or a function used with `runInInjectionContext`");
+    }
+}
+/** Container or scope has already been destroyed. */
+export class ScopeDestroyedError extends Error {
+    name = "ScopeDestroyedError";
+    constructor(name = "Scope") {
+        super(`${name} has already been destroyed.`);
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { CircularDependencyError, InjectionContextError, ProviderNotFoundError, ScopeDestroyedError, } from "./errors.ts";
+export { inject, runInInjectionContext } from "./injection-context.ts";
+export { Lifetime } from "./lifetime.ts";
+export type { ClassProvider, ExistingProvider, FactoryProvider, Provider, ValueProvider, } from "./provider.ts";
+export type { ResolveOptions, Resolver } from "./resolver.ts";
+export { Scope } from "./scope.ts";
+export type { AbstractClass, Class, Token } from "./token.ts";
+export { InjectionToken } from "./token.ts";

package/dist/index.js

@@ -0,0 +1,8 @@
+//  Errors
+export { CircularDependencyError, InjectionContextError, ProviderNotFoundError, ScopeDestroyedError, } from "./errors.js";
+// Injection context
+export { inject, runInInjectionContext } from "./injection-context.js";
+export { Lifetime } from "./lifetime.js";
+// Scope
+export { Scope } from "./scope.js";
+export { InjectionToken } from "./token.js";

package/dist/injection-context.d.ts

@@ -0,0 +1,24 @@
+import type { Resolver } from "./resolver.ts";
+import type { Token } from "./token.ts";
+/** @internal */
+export declare function getInjectionContext(): Resolver | undefined;
+/** @internal — Returns the previous context so it can be restored. */
+export declare function setInjectionContext(resolver: Resolver | undefined): Resolver | undefined;
+/**
+ * Retrieve a dependency from the currently active injection context.
+ *
+ * Must be called **synchronously** during container-managed construction:
+ * inside a factory, inside a class field initializer triggered by a
+ * `useClass` provider, or inside `runInInjectionContext()`.
+ */
+export declare function inject<T>(token: Token<T>): T;
+export declare function inject<T>(token: Token<T>, options: {
+    optional: true;
+}): T | null;
+/**
+ * Run a function with a specific resolver as the active injection context.
+ *
+ * Within `fn`, calls to `inject()` will resolve against `resolver`.
+ * The previous context (if any) is restored when `fn` returns.
+ */
+export declare function runInInjectionContext<R>(resolver: Resolver, fn: () => R): R;

package/dist/injection-context.js

@@ -0,0 +1,34 @@
+import { InjectionContextError } from "./errors.js";
+let _currentContext;
+/** @internal */
+export function getInjectionContext() {
+    return _currentContext;
+}
+/** @internal — Returns the previous context so it can be restored. */
+export function setInjectionContext(resolver) {
+    const prev = _currentContext;
+    _currentContext = resolver;
+    return prev;
+}
+export function inject(token, options) {
+    const resolver = getInjectionContext();
+    if (!resolver) {
+        throw new InjectionContextError(token);
+    }
+    return resolver.resolve(token, options);
+}
+/**
+ * Run a function with a specific resolver as the active injection context.
+ *
+ * Within `fn`, calls to `inject()` will resolve against `resolver`.
+ * The previous context (if any) is restored when `fn` returns.
+ */
+export function runInInjectionContext(resolver, fn) {
+    const prev = setInjectionContext(resolver);
+    try {
+        return fn();
+    }
+    finally {
+        setInjectionContext(prev);
+    }
+}

package/dist/lifetime.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Defines how long an instance lives and how it is shared.
+ */
+export declare const Lifetime: Readonly<{
+    /** One instance for the entire container. */
+    Singleton: "singleton";
+    /** New instance per injection point. */
+    Transient: "transient";
+}>;
+export type Lifetime = (typeof Lifetime)[keyof typeof Lifetime];

package/dist/lifetime.js

@@ -0,0 +1,9 @@
+/**
+ * Defines how long an instance lives and how it is shared.
+ */
+export const Lifetime = Object.freeze({
+    /** One instance for the entire container. */
+    Singleton: "singleton",
+    /** New instance per injection point. */
+    Transient: "transient",
+});

package/dist/provider.d.ts

@@ -0,0 +1,39 @@
+import type { Lifetime } from "./lifetime.ts";
+import type { Class, Token } from "./token.ts";
+/**
+ * Provide a pre-existing value. No factory, no lifetime — the value is
+ * always immediately available and lives as long as its container.
+ */
+export interface ValueProvider<T = unknown> {
+    provide: Token<T>;
+    useValue: T;
+}
+/**
+ * Provide via a factory function. `inject()` works inside the factory.
+ */
+export interface FactoryProvider<T = unknown> {
+    provide: Token<T>;
+    useFactory: () => T;
+    lifetime?: Lifetime;
+}
+/**
+ * Provide by constructing a class. `inject()` works in field initializers.
+ */
+export interface ClassProvider<T = unknown> {
+    provide: Token<T>;
+    useClass: Class<T>;
+    lifetime?: Lifetime;
+}
+/**
+ * Alias: resolve one token as another.
+ * Inherits the lifetime of the target token's registration.
+ */
+export interface ExistingProvider<T = unknown> {
+    provide: Token<T>;
+    useExisting: Token<T>;
+}
+export type Provider<T = unknown> = ValueProvider<T> | FactoryProvider<T> | ClassProvider<T> | ExistingProvider<T>;
+export declare function isValueProvider<T>(p: Provider<T>): p is ValueProvider<T>;
+export declare function isFactoryProvider<T>(p: Provider<T>): p is FactoryProvider<T>;
+export declare function isClassProvider<T>(p: Provider<T>): p is ClassProvider<T>;
+export declare function isExistingProvider<T>(p: Provider<T>): p is ExistingProvider<T>;

package/dist/provider.js

@@ -0,0 +1,12 @@
+export function isValueProvider(p) {
+    return "useValue" in p;
+}
+export function isFactoryProvider(p) {
+    return "useFactory" in p;
+}
+export function isClassProvider(p) {
+    return "useClass" in p;
+}
+export function isExistingProvider(p) {
+    return "useExisting" in p;
+}

package/dist/resolver.d.ts

@@ -0,0 +1,11 @@
+import type { Token } from "./token.ts";
+export interface ResolveOptions {
+    optional?: boolean;
+}
+export interface Resolver {
+    resolve<T>(token: Token<T>): T;
+    resolve<T>(token: Token<T>, options: {
+        optional: true;
+    }): T | null;
+    resolve<T>(token: Token<T>, options?: ResolveOptions): T | null;
+}

package/dist/resolver.js

@@ -0,0 +1 @@
+export {};

package/dist/scope.d.ts

@@ -0,0 +1,15 @@
+import { type Provider } from "./provider.ts";
+import type { Resolver } from "./resolver.ts";
+import type { Token } from "./token.ts";
+export declare class Scope implements Resolver, AsyncDisposable {
+    #private;
+    constructor(providers: Provider[]);
+    get disposed(): boolean;
+    resolve<T>(token: Token<T>): T;
+    resolve<T>(token: Token<T>, options: {
+        optional: true;
+    }): T | null;
+    has<T>(token: Token<T>): boolean;
+    dispose(): Promise<void>;
+    [Symbol.asyncDispose](): Promise<void>;
+}

package/dist/scope.js

@@ -0,0 +1,44 @@
+import { createBinding, EMPTY } from "./binding.js";
+import { inject } from "./injection-context.js";
+import { Lifetime } from "./lifetime.js";
+import { isClassProvider, isExistingProvider, isFactoryProvider, isValueProvider, } from "./provider.js";
+export class Scope {
+    #disposed;
+    #bindings;
+    constructor(providers) {
+        this.#disposed = false;
+        this.#bindings = new Map();
+        for (const provider of providers) {
+            this.#bindings.set(provider.provide, providerToBinding(provider));
+        }
+    }
+    get disposed() {
+        return this.#disposed;
+    }
+    resolve(_token, _options) {
+        throw new Error("Scope.resolve is not implemented in this preview build");
+    }
+    has(token) {
+        return this.#bindings.has(token);
+    }
+    async dispose() {
+        this.#disposed = true;
+    }
+    [Symbol.asyncDispose]() {
+        return this.dispose();
+    }
+}
+function providerToBinding(provider) {
+    switch (true) {
+        case isValueProvider(provider):
+            return createBinding(undefined, provider.useValue, Lifetime.Singleton);
+        case isExistingProvider(provider):
+            return createBinding(() => inject(provider.useExisting), EMPTY, Lifetime.Transient);
+        case isFactoryProvider(provider):
+            return createBinding(provider.useFactory, EMPTY, provider.lifetime ?? Lifetime.Singleton);
+        case isClassProvider(provider):
+            return createBinding(() => new provider.useClass(), EMPTY, provider.lifetime ?? Lifetime.Singleton);
+        default:
+            throw new Error("Invalid provider type", { cause: provider });
+    }
+}

package/dist/token.d.ts

@@ -0,0 +1,26 @@
+/**
+ * A token that can be used as a DI key for non-class dependencies
+ * (strings, numbers, interfaces, configuration objects, etc.).
+ *
+ * Each `InjectionToken` instance is unique by identity — two tokens
+ * with the same description are still different tokens.
+ *
+ * @example
+ * ```ts
+ * const API_URL = new InjectionToken<string>('API_URL');
+ * ```
+ */
+export declare class InjectionToken<T> {
+    readonly __type: T;
+    readonly description: string;
+    constructor(description: string);
+    toString(): string;
+}
+/** A concrete class constructor. */
+export type Class<T = unknown> = new (...args: unknown[]) => T;
+/** A class or abstract class reference. */
+export type AbstractClass<T = unknown> = abstract new (...args: unknown[]) => T;
+/** Anything that can be used as a DI key. */
+export type Token<T = unknown> = InjectionToken<T> | AbstractClass<T>;
+/** Returns a human-readable name for a token. */
+export declare function tokenName(token: Token): string;

package/dist/token.js

@@ -0,0 +1,27 @@
+/**
+ * A token that can be used as a DI key for non-class dependencies
+ * (strings, numbers, interfaces, configuration objects, etc.).
+ *
+ * Each `InjectionToken` instance is unique by identity — two tokens
+ * with the same description are still different tokens.
+ *
+ * @example
+ * ```ts
+ * const API_URL = new InjectionToken<string>('API_URL');
+ * ```
+ */
+export class InjectionToken {
+    description;
+    constructor(description) {
+        this.description = description;
+    }
+    toString() {
+        return `InjectionToken(${this.description})`;
+    }
+}
+/** Returns a human-readable name for a token. */
+export function tokenName(token) {
+    if (token instanceof InjectionToken)
+        return token.toString();
+    return token.name || String(token);
+}

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "injectdi",
+  "version": "0.0.1",
+  "type": "module",
+  "description": "High-performant, decorator-free dependency IoC container for Node.js.",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "keywords": [
+    "di",
+    "dependency-injection",
+    "ioc",
+    "ioc-container",
+    "inversion-of-control",
+    "container",
+    "decorator-free",
+    "scope",
+    "binding",
+    "token",
+    "typescript",
+    "esm",
+    "node"
+  ],
+  "license": "ISC",
+  "author": "Hossam Hamdy <hossamhamdy117@gmail.com> (https://github.com/hossam7amdy)",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hossam7amdy/injectdi.git"
+  },
+  "homepage": "https://github.com/hossam7amdy/injectdi#readme",
+  "bugs": {
+    "url": "https://github.com/hossam7amdy/injectdi/issues"
+  },
+  "scripts": {
+    "preinstall": "npx only-allow pnpm",
+    "clean": "rm -rf dist",
+    "build": "tsc -p tsconfig.build.json",
+    "prepublishOnly": "pnpm run clean && pnpm run check && pnpm run test && pnpm run build",
+    "test": "node --test 'src/__tests__/**/*.test.ts'",
+    "check": "biome check .",
+    "check:fix": "biome check . --write"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.15",
+    "@types/node": "^22.19.19",
+    "typescript": "^6.0.3"
+  },
+  "packageManager": "pnpm@11.1.2"
+}