@resolid/di 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022-present, Resolid Tech
+
+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,119 @@
+# Resolid: DI Container Package
+
+![GitHub License](https://img.shields.io/github/license/resolid/framework)
+
+<b>[Documentation](https://www.resolid.tech/docs/di)</b> | [Framework Bundle](https://github.com/resolid/framework)
+
+## TypeScript Dependency Injection Container
+
+A lightweight, fully-typed Dependency Injection (DI) container for TypeScript.
+Supports singleton & transient scopes, lazy resolution, and disposable resources. Fully functional with async factories
+and avoids circular dependency issues.
+
+### Features
+
+- Fully typed with TypeScript, no any.
+- Supports singleton and transient scopes.
+- Lazy resolution for async dependencies.
+- Detects circular dependencies.
+- Handles disposable instances with dispose() support.
+- Fully async-compatible.
+
+### Installation
+
+```shell
+pnpm add @resolid/di
+# or
+npm install @resolid/di
+# or
+yarn add @resolid/di
+# or
+bun add @resolid/di
+```
+
+### Usage
+
+#### Creating a container
+
+```js
+import { createContainer } from "@resolid/di";
+
+const container = createContainer();
+```
+
+#### Binding dependencies
+
+You can bind values, functions, or factories:
+
+1. Bind a value
+
+```js
+const TOKEN = Symbol("token");
+
+container.bind(TOKEN).toValue({ message: "Hello World" });
+
+const result = await container.resolve(TOKEN); // result = "Hello World"
+```
+
+2. Bind a function
+
+```js
+const FUNC_TOKEN = Symbol("func");
+
+container.bind(FUNC_TOKEN).toFunction(() => console.log("Hello from function"));
+
+const fn = await container.resolve(FUNC_TOKEN);
+const result = fn(); // result = "Hello from function"
+```
+
+3. Bind a factory
+
+Bind a factory, can with bellow options:
+
+- scope
+  - singleton (default): One instance per container.
+  - transient: A new instance each time resolved.
+
+- config is optional
+
+```js
+const TOKEN = Symbol("token");
+
+container.bind(TOKEN).toValue({ message: "Hello" });
+
+const FACTORY_TOKEN = Symbol("factory");
+
+container.bind(FACTORY_TOKEN).toFactory(
+  ({ resolver, config }) => {
+    const dep = resolver.resolve(TOKEN);
+    return `Factory resolved: ${dep.message} ${config.message}`;
+  },
+  { scope: "singleton", config: { message: "World." } },
+);
+
+const result = await container.resolve(FACTORY_TOKEN); // result = "Factory resolved: Hello world."
+```
+
+4. Circular dependencies
+
+```js
+const LAZY_DEP = Symbol("lazyDep");
+const CONSUMER = Symbol("consumer");
+
+container.bind(LAZY_DEP).toValue({ data: "lazy data" });
+
+container.bind(CONSUMER).toFactory(({ resolver }) => {
+  const lazy = resolver.lazyResolve(LAZY_DEP);
+
+  return {
+    getLazyData: () => lazy.value.data,
+  };
+});
+
+const consumer = await container.resolve(CONSUMER);
+// consumer.getLazyData()).toBe("lazy data");
+```
+
+## License
+
+MIT License (MIT). Please see [LICENSE](./LICENSE) for more information.

package/dist/index.d.ts

@@ -0,0 +1,42 @@
+//#region src/types/index.d.ts
+type Scope = "singleton" | "transient";
+type BindingConfig = Record<string, unknown>;
+//#endregion
+//#region src/utils/index.d.ts
+type Disposable = {
+  dispose: () => Promise<void> | void;
+};
+//#endregion
+//#region src/container/index.d.ts
+type Resolve = (name: symbol) => unknown;
+type LazyResolve = <T = unknown>(name: symbol) => Readonly<{
+  value: T;
+}>;
+type Resolver = {
+  resolve: Resolve;
+  lazyResolve: LazyResolve;
+};
+type ToValue = (value: unknown) => void;
+type ToFunction = (fn: (...args: unknown[]) => unknown) => void;
+type ToFactory = (fn: ({
+  resolver,
+  config
+}: {
+  resolver: Resolver;
+  config?: BindingConfig;
+}) => unknown | Promise<unknown>, options?: {
+  scope?: Scope;
+  config?: BindingConfig;
+}) => void;
+type Container = {
+  bind: (name: symbol) => {
+    toValue: ToValue;
+    toFunction: ToFunction;
+    toFactory: ToFactory;
+  };
+  resolve: <T>(name: symbol) => Promise<T>;
+  lazyResolve: LazyResolve;
+} & Disposable;
+declare const createContainer: () => Container;
+//#endregion
+export { BindingConfig, Container, Scope, createContainer };

package/dist/index.js

@@ -0,0 +1,130 @@
+//#region src/utils/index.ts
+const isDisposable = (obj) => !!obj && typeof obj.dispose === "function";
+const formatChain = (chain, current) => {
+	return (current ? [...chain, current] : chain).map(String).join(" -> ");
+};
+
+//#endregion
+//#region src/container/index.ts
+const createContainer = () => {
+	const result = _createContainer();
+	return {
+		bind: result.bind,
+		resolve: result.resolve,
+		lazyResolve: result.lazyResolve,
+		dispose: result.dispose
+	};
+};
+const _createContainer = (parent, item, constructing) => {
+	const bindings = parent?.bindings ?? /* @__PURE__ */ new Map();
+	const singletons = parent?.singletons ?? /* @__PURE__ */ new Map();
+	const currentConstructing = item ? [...constructing ?? parent?.constructing ?? [], item] : [];
+	const lazyResolveQueue = [];
+	const container = {};
+	const enqueueLazyResolve = (name) => {
+		return new Promise((resolve$1) => {
+			const lazy = (value) => {
+				resolve$1(value);
+			};
+			lazyResolveQueue.push({
+				name,
+				resolve: lazy
+			});
+		});
+	};
+	const dequeueLazyResolves = async () => {
+		for (const lazyResolve$1 of lazyResolveQueue) try {
+			lazyResolve$1.resolve(await resolveBinding(lazyResolve$1.name, []));
+		} catch (e) {
+			throw new Error(`Failed to resolve lazy resolver for name ${lazyResolve$1.name.toString()}: ${e instanceof Error ? e.message : String(e)}`);
+		}
+	};
+	const bind = (name) => {
+		const toValue = (value) => {
+			bindings.set(name, {
+				factory: () => value,
+				scope: "singleton"
+			});
+		};
+		const toFunction = (fn) => {
+			bindings.set(name, {
+				factory: () => fn,
+				scope: "singleton"
+			});
+		};
+		const toFactory = (fn, options) => {
+			bindings.set(name, {
+				factory: (resolve$1, lazyResolve$1) => {
+					return fn({
+						resolver: {
+							resolve: resolve$1,
+							lazyResolve: lazyResolve$1
+						},
+						config: options?.config
+					});
+				},
+				scope: options?.scope ?? "singleton",
+				config: options?.config
+			});
+		};
+		return {
+			toValue,
+			toFunction,
+			toFactory
+		};
+	};
+	const resolveBinding = async (name, constructing$1) => {
+		const binding = bindings.get(name);
+		if (!binding) throw new Error(`No binding found for name: ${name.toString()}`);
+		const isSingleton = binding.scope === "singleton";
+		if (isSingleton && singletons.has(name)) return singletons.get(name);
+		const child = _createContainer(container, name, constructing$1);
+		const result = await binding.factory(child.resolve, child.lazyResolve);
+		if (isSingleton) singletons.set(name, result);
+		await child.dequeueLazyResolves();
+		return result;
+	};
+	const resolve = async (name) => {
+		if (currentConstructing.includes(name)) throw new Error(`Circular dependency detected: ${formatChain(currentConstructing, name)}`);
+		return resolveBinding(name);
+	};
+	const lazyResolve = (name) => {
+		let value;
+		enqueueLazyResolve(name).then((resolved) => {
+			value = resolved;
+		});
+		return { get value() {
+			if (!value) throw new Error("Lazy binding is not yet resolved. Do not use lazy-resolved bindings before the binding construction ends.");
+			return value;
+		} };
+	};
+	const dispose = async () => {
+		const disposeErrors = [];
+		for (const [name, instance] of singletons) if (isDisposable(instance)) try {
+			await instance.dispose();
+		} catch (error) {
+			disposeErrors.push({
+				name,
+				error
+			});
+		}
+		if (disposeErrors.length > 0) {
+			const errorMessages = disposeErrors.map(({ name, error }) => `${name.toString()}: ${error instanceof Error ? error.message : String(error)}`).join("; ");
+			throw new Error(`Failed to dispose ${disposeErrors.length} binding(s): ${errorMessages}`);
+		}
+	};
+	Object.assign(container, {
+		bindings,
+		singletons,
+		constructing: currentConstructing,
+		dequeueLazyResolves,
+		bind,
+		resolve,
+		lazyResolve,
+		dispose
+	});
+	return container;
+};
+
+//#endregion
+export { createContainer };

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@resolid/di",
+  "type": "module",
+  "license": "MIT",
+  "private": false,
+  "sideEffects": false,
+  "version": "0.1.0",
+  "description": "The Resolid DI Container package.",
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "dependencies": {},
+  "devDependencies": {},
+  "peerDependencies": {
+    "typescript": "^5.9.3"
+  },
+  "engines": {
+    "node": "^22.13.0 || >=24"
+  },
+  "homepage": "https://www.resolid.tech",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/resolid/framework.git",
+    "directory": "packages/di"
+  },
+  "scripts": {
+    "lint": "eslint .",
+    "build": "tsdown",
+    "test": "vitest run",
+    "bench": "vitest bench",
+    "typecheck": "tsc --noEmit"
+  }
+}