di-craft 0.0.9 → 0.0.10

package/README.md

@@ -1,18 +1,186 @@
 # di-craft
 
-A tiny TypeScript dependency injection container.
+A tiny, type-safe dependency injection container for TypeScript.
+
+```ts
+import {
+  createContainer,
+  createToken,
+  provideFactory,
+  provideValue,
+  type Provider,
+} from "di-craft";
+
+const CONFIG = createToken<Config>("config");
+const LOGGER = createToken<Logger>("logger");
+const USERS = createToken<UserService>("users");
+
+const providers: Provider[] = [
+  provideValue(CONFIG, loadConfig()),
+  provideFactory(LOGGER, {
+    deps: { config: CONFIG },
+    useFactory: ({ config }) => new Logger(config.level),
+  }),
+  provideFactory(USERS, {
+    deps: { logger: LOGGER },
+    useFactory: ({ logger }) => new UserService(logger),
+  }),
+];
+
+const container = createContainer(providers);
+
+const users = container.get(USERS); // UserService, fully typed
+```
+
+## Philosophy
+
+`di-craft` is a small DI container with no magic.
+
+- No decorators
+- No `reflect-metadata`
+- No framework dependencies
+
+Just **tokens**, **providers**, a **container**, **scopes**, and **cycle detection**.
 
 ## Features
 
 - Zero runtime dependencies
 - No decorators
-- No reflect-metadata
+- No `reflect-metadata`
+- Framework agnostic
 - Type-safe tokens
 - Explicit factories
 - Singleton and transient scopes
+- Circular dependency detection
+- Tree-shakable, tiny bundle size
+- Ships both ESM and CommonJS builds
 
 ## Install
 
 ```bash
 bun add di-craft
+npm install di-craft
+pnpm add di-craft
+yarn add di-craft
+```
+
+Requires Node.js `>= 20`.
+
+## Core concepts
+
+### Tokens
+
+A token is a unique, type-carrying key. Identity is based on an internal `symbol`, **not** on the name — two tokens with the same name are still different.
+
+```ts
+const PORT = createToken<number>("port");
+
+PORT.name; // "port" — used only for error messages
+```
+
+The type argument flows everywhere: providers must produce a matching value, and `container.get(PORT)` returns `number`.
+
+### Providers
+
+A provider tells the container how to produce the value for a token.
+
+`provideValue` — register an existing value:
+
+```ts
+provideValue(PORT, 3000);
+```
+
+`provideFactory` — build the value lazily, with optional dependencies and scope:
+
+```ts
+provideFactory(HTTP, {
+  deps: { config: CONFIG },         // optional, keyed map of tokens
+  scope: "singleton",                // optional, defaults to "singleton"
+  useFactory: ({ config }) => new HttpClient(config.apiUrl),
+});
+```
+
+The keys in `deps` become the keys of the object passed to `useFactory`, each resolved to its token's type.
+
+### Container
+
+```ts
+const container = createContainer(providers); // providers are optional
+
+container.register(provideValue(PORT, 3000)); // register more at any time
+container.has(PORT);                           // true
+container.get(PORT);                           // 3000
+```
+
+Registering the same token twice throws `DuplicateProviderError`.
+
+### Scopes
+
+| Scope                  | Behavior                                                         |
+| ---------------------- | ---------------------------------------------------------------- |
+| `singleton` (default)  | The factory runs once; the same instance is returned every time. |
+| `transient`            | The factory runs on every `get`, producing a fresh instance.     |
+
+```ts
+provideFactory(ID, {
+  scope: "transient",
+  useFactory: () => crypto.randomUUID(),
+});
+
+container.get(ID) !== container.get(ID); // true
+```
+
+A transient provider that depends on a singleton still reuses the shared singleton instance.
+
+### Cycle detection
+
+If providers form a dependency cycle, resolution throws `CircularDependencyError` with the full path instead of overflowing the stack.
+
+```ts
+// A -> B -> A
+container.get(A); // throws: Circular dependency detected: A -> B -> A
+```
+
+## Error handling
+
+All errors extend the shared `DiError` base class, so you can catch any container error with a single check:
+
+```ts
+import { DiError, MissingProviderError } from "di-craft";
+
+try {
+  container.get(SOME_TOKEN);
+} catch (error) {
+  if (error instanceof MissingProviderError) {
+    // a specific failure
+  }
+
+  if (error instanceof DiError) {
+    // any di-craft error
+  }
+}
 ```
+
+| Error                      | Thrown when                                              |
+| -------------------------- | -------------------------------------------------------- |
+| `MissingProviderError`     | A token is resolved but no provider is registered.       |
+| `DuplicateProviderError`   | A token is registered more than once.                    |
+| `CircularDependencyError`  | Providers form a dependency cycle.                       |
+| `InvalidDependencyError`   | A declared dependency token is missing/undefined.        |
+
+## API reference
+
+| Export                  | Description                                                |
+| ----------------------- | ---------------------------------------------------------- |
+| `createToken<T>(name)`  | Create a unique, typed token.                              |
+| `provideValue(token, value)` | Provider that returns an existing value.              |
+| `provideFactory(token, options)` | Provider that builds a value via a factory.       |
+| `createContainer(providers?)` | Create a container, optionally seeded with providers. |
+
+Exported types: `Container`, `Token`, `Provider`, `ValueProvider`, `FactoryProvider`, `Scope`.
+
+Exported errors: `DiError`, `MissingProviderError`, `DuplicateProviderError`, `CircularDependencyError`, `InvalidDependencyError`.
+
+## License
+
+[MIT](./LICENSE)

package/dist/index.cjs

@@ -1,4 +1,149 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region src/error/error.ts
+var DiError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "DiError";
+		if (Error.captureStackTrace) Error.captureStackTrace(this, this.constructor);
+	}
+};
+//#endregion
+//#region src/registry/errors.ts
+var DuplicateProviderError = class extends DiError {
+	constructor(tokenName) {
+		super(`Provider for token "${tokenName}" is already registered`);
+		this.name = "DuplicateProviderError";
+	}
+};
+//#endregion
+//#region src/registry/registry.ts
+var RegistryClass = class {
+	providers = /* @__PURE__ */ new Map();
+	register(provider) {
+		if (this.providers.has(provider.provide.id)) throw new DuplicateProviderError(provider.provide.name);
+		this.providers.set(provider.provide.id, provider);
+	}
+	get(token) {
+		return this.providers.get(token.id);
+	}
+	has(token) {
+		return this.providers.has(token.id);
+	}
+};
+const createRegistry = () => new RegistryClass();
+//#endregion
+//#region src/resolver/errors.ts
+var MissingProviderError = class extends DiError {
+	constructor(tokenName) {
+		super(`Provider for token "${tokenName}" is not registered`);
+		this.name = "MissingProviderError";
+	}
+};
+var InvalidDependencyError = class extends DiError {
+	constructor(dependencyKey) {
+		super(`Invalid dependency "${dependencyKey}"`);
+		this.name = "InvalidDependencyError";
+	}
+};
+var CircularDependencyError = class extends DiError {
+	constructor(tokenNames) {
+		super(`Circular dependency detected: ${tokenNames.join(" -> ")}`);
+		this.name = "CircularDependencyError";
+	}
+};
+//#endregion
+//#region src/provider/provider.ts
+const provideValue = (token, useValue) => ({
+	provide: token,
+	useValue
+});
+const provideFactory = (token, options) => {
+	return {
+		provide: token,
+		useFactory: options.useFactory,
+		...options.deps ? { deps: options.deps } : {},
+		...options.scope ? { scope: options.scope } : {}
+	};
+};
+const isValueProvider = (provider) => {
+	return "useValue" in provider;
+};
+const isFactoryProvider = (provider) => {
+	return "useFactory" in provider;
+};
+//#endregion
+//#region src/resolver/resolver.ts
+var ResolverClass = class {
+	registry;
+	instances = /* @__PURE__ */ new Map();
+	constructor(registry) {
+		this.registry = registry;
+	}
+	resolve(token) {
+		return this.resolveToken(token, {
+			resolving: /* @__PURE__ */ new Set(),
+			path: []
+		});
+	}
+	resolveToken(token, context) {
+		const provider = this.registry.get(token);
+		if (!provider) throw new MissingProviderError(token.name);
+		if (isValueProvider(provider)) return provider.useValue;
+		if (isFactoryProvider(provider)) {
+			const scope = provider.scope ?? "singleton";
+			if (scope === "singleton" && this.instances.has(token.id)) return this.instances.get(token.id);
+			if (context.resolving.has(token.id)) {
+				const cycleStartIndex = context.path.findIndex((pathToken) => pathToken.id === token.id);
+				throw new CircularDependencyError([...context.path.slice(cycleStartIndex), token].map((cycleToken) => cycleToken.name));
+			}
+			context.resolving.add(token.id);
+			context.path.push(token);
+			try {
+				const deps = this.resolveDeps(provider.deps, context);
+				const value = provider.useFactory(deps);
+				if (scope === "singleton") this.instances.set(token.id, value);
+				return value;
+			} finally {
+				context.path.pop();
+				context.resolving.delete(token.id);
+			}
+		}
+		throw new MissingProviderError(token.name);
+	}
+	resolveDeps(deps, context) {
+		if (!deps) return {};
+		const resolvedDeps = {};
+		for (const key of Object.keys(deps)) {
+			const token = deps[key];
+			if (token === void 0) throw new InvalidDependencyError(String(key));
+			resolvedDeps[key] = this.resolveToken(token, context);
+		}
+		return resolvedDeps;
+	}
+};
+const createResolver = (registry) => new ResolverClass(registry);
+//#endregion
+//#region src/container/container.ts
+var ContainerClass = class {
+	registry;
+	resolver;
+	constructor(providers = []) {
+		this.registry = createRegistry();
+		for (const provider of providers) this.registry.register(provider);
+		this.resolver = createResolver(this.registry);
+	}
+	register(provider) {
+		this.registry.register(provider);
+	}
+	get(token) {
+		return this.resolver.resolve(token);
+	}
+	has(token) {
+		return this.registry.has(token);
+	}
+};
+const createContainer = (providers = []) => new ContainerClass(providers);
+//#endregion
 //#region src/token/token.ts
 var TokenClass = class {
 	name;
@@ -10,4 +155,12 @@ var TokenClass = class {
 };
 const createToken = (name) => new TokenClass(name);
 //#endregion
+exports.CircularDependencyError = CircularDependencyError;
+exports.DiError = DiError;
+exports.DuplicateProviderError = DuplicateProviderError;
+exports.InvalidDependencyError = InvalidDependencyError;
+exports.MissingProviderError = MissingProviderError;
+exports.createContainer = createContainer;
 exports.createToken = createToken;
+exports.provideFactory = provideFactory;
+exports.provideValue = provideValue;

package/dist/index.d.cts

@@ -8,4 +8,62 @@ type Token<T> = {
 //#region src/token/token.d.ts
 declare const createToken: <T>(name: string) => Token<T>;
 //#endregion
-export { type Token, createToken };
+//#region src/provider/types.d.ts
+type DepsMap = Record<string, Token<unknown>>;
+type TokenValue<TToken> = TToken extends Token<infer TValue> ? TValue : never;
+type ResolveDeps<TDeps extends DepsMap> = { readonly [TKey in keyof TDeps]: TokenValue<TDeps[TKey]> };
+type Factory<T, TDeps extends DepsMap> = (deps: ResolveDeps<TDeps>) => T;
+type ValueProvider<T> = {
+  readonly provide: Token<T>;
+  readonly useValue: T;
+};
+type FactoryProvider<T, TDeps extends DepsMap = Record<never, never>> = {
+  readonly provide: Token<T>;
+  readonly deps?: TDeps;
+  readonly scope?: Scope;
+  readonly useFactory: Factory<T, TDeps>;
+};
+type AnyFactoryProvider = FactoryProvider<unknown, any>;
+type Provider = ValueProvider<unknown> | AnyFactoryProvider;
+type Scope = "singleton" | "transient";
+//#endregion
+//#region src/provider/provider.d.ts
+declare const provideValue: <T>(token: Token<T>, useValue: T) => ValueProvider<T>;
+declare const provideFactory: <T, TDeps extends DepsMap = Record<never, never>>(token: Token<T>, options: {
+  readonly deps?: TDeps;
+  readonly scope?: Scope;
+  readonly useFactory: Factory<T, TDeps>;
+}) => FactoryProvider<T, TDeps>;
+//#endregion
+//#region src/container/types.d.ts
+type Container = {
+  register(provider: Provider): void;
+  get<T>(token: Token<T>): T;
+  has(token: Token<unknown>): boolean;
+};
+//#endregion
+//#region src/container/container.d.ts
+declare const createContainer: (providers?: readonly Provider[]) => Container;
+//#endregion
+//#region src/error/error.d.ts
+declare class DiError extends Error {
+  constructor(message: string);
+}
+//#endregion
+//#region src/registry/errors.d.ts
+declare class DuplicateProviderError extends DiError {
+  constructor(tokenName: string);
+}
+//#endregion
+//#region src/resolver/errors.d.ts
+declare class MissingProviderError extends DiError {
+  constructor(tokenName: string);
+}
+declare class InvalidDependencyError extends DiError {
+  constructor(dependencyKey: string);
+}
+declare class CircularDependencyError extends DiError {
+  constructor(tokenNames: string[]);
+}
+//#endregion
+export { CircularDependencyError, type Container, DiError, DuplicateProviderError, type FactoryProvider, InvalidDependencyError, MissingProviderError, type Provider, type Scope, type Token, type ValueProvider, createContainer, createToken, provideFactory, provideValue };

package/dist/index.d.mts

@@ -8,4 +8,62 @@ type Token<T> = {
 //#region src/token/token.d.ts
 declare const createToken: <T>(name: string) => Token<T>;
 //#endregion
-export { type Token, createToken };
+//#region src/provider/types.d.ts
+type DepsMap = Record<string, Token<unknown>>;
+type TokenValue<TToken> = TToken extends Token<infer TValue> ? TValue : never;
+type ResolveDeps<TDeps extends DepsMap> = { readonly [TKey in keyof TDeps]: TokenValue<TDeps[TKey]> };
+type Factory<T, TDeps extends DepsMap> = (deps: ResolveDeps<TDeps>) => T;
+type ValueProvider<T> = {
+  readonly provide: Token<T>;
+  readonly useValue: T;
+};
+type FactoryProvider<T, TDeps extends DepsMap = Record<never, never>> = {
+  readonly provide: Token<T>;
+  readonly deps?: TDeps;
+  readonly scope?: Scope;
+  readonly useFactory: Factory<T, TDeps>;
+};
+type AnyFactoryProvider = FactoryProvider<unknown, any>;
+type Provider = ValueProvider<unknown> | AnyFactoryProvider;
+type Scope = "singleton" | "transient";
+//#endregion
+//#region src/provider/provider.d.ts
+declare const provideValue: <T>(token: Token<T>, useValue: T) => ValueProvider<T>;
+declare const provideFactory: <T, TDeps extends DepsMap = Record<never, never>>(token: Token<T>, options: {
+  readonly deps?: TDeps;
+  readonly scope?: Scope;
+  readonly useFactory: Factory<T, TDeps>;
+}) => FactoryProvider<T, TDeps>;
+//#endregion
+//#region src/container/types.d.ts
+type Container = {
+  register(provider: Provider): void;
+  get<T>(token: Token<T>): T;
+  has(token: Token<unknown>): boolean;
+};
+//#endregion
+//#region src/container/container.d.ts
+declare const createContainer: (providers?: readonly Provider[]) => Container;
+//#endregion
+//#region src/error/error.d.ts
+declare class DiError extends Error {
+  constructor(message: string);
+}
+//#endregion
+//#region src/registry/errors.d.ts
+declare class DuplicateProviderError extends DiError {
+  constructor(tokenName: string);
+}
+//#endregion
+//#region src/resolver/errors.d.ts
+declare class MissingProviderError extends DiError {
+  constructor(tokenName: string);
+}
+declare class InvalidDependencyError extends DiError {
+  constructor(dependencyKey: string);
+}
+declare class CircularDependencyError extends DiError {
+  constructor(tokenNames: string[]);
+}
+//#endregion
+export { CircularDependencyError, type Container, DiError, DuplicateProviderError, type FactoryProvider, InvalidDependencyError, MissingProviderError, type Provider, type Scope, type Token, type ValueProvider, createContainer, createToken, provideFactory, provideValue };

package/dist/index.mjs

@@ -1,3 +1,148 @@
+//#region src/error/error.ts
+var DiError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "DiError";
+		if (Error.captureStackTrace) Error.captureStackTrace(this, this.constructor);
+	}
+};
+//#endregion
+//#region src/registry/errors.ts
+var DuplicateProviderError = class extends DiError {
+	constructor(tokenName) {
+		super(`Provider for token "${tokenName}" is already registered`);
+		this.name = "DuplicateProviderError";
+	}
+};
+//#endregion
+//#region src/registry/registry.ts
+var RegistryClass = class {
+	providers = /* @__PURE__ */ new Map();
+	register(provider) {
+		if (this.providers.has(provider.provide.id)) throw new DuplicateProviderError(provider.provide.name);
+		this.providers.set(provider.provide.id, provider);
+	}
+	get(token) {
+		return this.providers.get(token.id);
+	}
+	has(token) {
+		return this.providers.has(token.id);
+	}
+};
+const createRegistry = () => new RegistryClass();
+//#endregion
+//#region src/resolver/errors.ts
+var MissingProviderError = class extends DiError {
+	constructor(tokenName) {
+		super(`Provider for token "${tokenName}" is not registered`);
+		this.name = "MissingProviderError";
+	}
+};
+var InvalidDependencyError = class extends DiError {
+	constructor(dependencyKey) {
+		super(`Invalid dependency "${dependencyKey}"`);
+		this.name = "InvalidDependencyError";
+	}
+};
+var CircularDependencyError = class extends DiError {
+	constructor(tokenNames) {
+		super(`Circular dependency detected: ${tokenNames.join(" -> ")}`);
+		this.name = "CircularDependencyError";
+	}
+};
+//#endregion
+//#region src/provider/provider.ts
+const provideValue = (token, useValue) => ({
+	provide: token,
+	useValue
+});
+const provideFactory = (token, options) => {
+	return {
+		provide: token,
+		useFactory: options.useFactory,
+		...options.deps ? { deps: options.deps } : {},
+		...options.scope ? { scope: options.scope } : {}
+	};
+};
+const isValueProvider = (provider) => {
+	return "useValue" in provider;
+};
+const isFactoryProvider = (provider) => {
+	return "useFactory" in provider;
+};
+//#endregion
+//#region src/resolver/resolver.ts
+var ResolverClass = class {
+	registry;
+	instances = /* @__PURE__ */ new Map();
+	constructor(registry) {
+		this.registry = registry;
+	}
+	resolve(token) {
+		return this.resolveToken(token, {
+			resolving: /* @__PURE__ */ new Set(),
+			path: []
+		});
+	}
+	resolveToken(token, context) {
+		const provider = this.registry.get(token);
+		if (!provider) throw new MissingProviderError(token.name);
+		if (isValueProvider(provider)) return provider.useValue;
+		if (isFactoryProvider(provider)) {
+			const scope = provider.scope ?? "singleton";
+			if (scope === "singleton" && this.instances.has(token.id)) return this.instances.get(token.id);
+			if (context.resolving.has(token.id)) {
+				const cycleStartIndex = context.path.findIndex((pathToken) => pathToken.id === token.id);
+				throw new CircularDependencyError([...context.path.slice(cycleStartIndex), token].map((cycleToken) => cycleToken.name));
+			}
+			context.resolving.add(token.id);
+			context.path.push(token);
+			try {
+				const deps = this.resolveDeps(provider.deps, context);
+				const value = provider.useFactory(deps);
+				if (scope === "singleton") this.instances.set(token.id, value);
+				return value;
+			} finally {
+				context.path.pop();
+				context.resolving.delete(token.id);
+			}
+		}
+		throw new MissingProviderError(token.name);
+	}
+	resolveDeps(deps, context) {
+		if (!deps) return {};
+		const resolvedDeps = {};
+		for (const key of Object.keys(deps)) {
+			const token = deps[key];
+			if (token === void 0) throw new InvalidDependencyError(String(key));
+			resolvedDeps[key] = this.resolveToken(token, context);
+		}
+		return resolvedDeps;
+	}
+};
+const createResolver = (registry) => new ResolverClass(registry);
+//#endregion
+//#region src/container/container.ts
+var ContainerClass = class {
+	registry;
+	resolver;
+	constructor(providers = []) {
+		this.registry = createRegistry();
+		for (const provider of providers) this.registry.register(provider);
+		this.resolver = createResolver(this.registry);
+	}
+	register(provider) {
+		this.registry.register(provider);
+	}
+	get(token) {
+		return this.resolver.resolve(token);
+	}
+	has(token) {
+		return this.registry.has(token);
+	}
+};
+const createContainer = (providers = []) => new ContainerClass(providers);
+//#endregion
 //#region src/token/token.ts
 var TokenClass = class {
 	name;
@@ -9,4 +154,4 @@ var TokenClass = class {
 };
 const createToken = (name) => new TokenClass(name);
 //#endregion
-export { createToken };
+export { CircularDependencyError, DiError, DuplicateProviderError, InvalidDependencyError, MissingProviderError, createContainer, createToken, provideFactory, provideValue };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "di-craft",
-	"version": "0.0.9",
+	"version": "0.0.10",
 	"description": "A tiny TypeScript dependency injection container",
 	"license": "MIT",
 	"author": {