@resolid/di 0.2.1 → 0.3.0

package/README.md

@@ -1,6 +1,7 @@
 # Resolid: DI Container Package
 
-![GitHub License](https://badgen.net/github/license/resolid/framework) ![NPM Version](https://badgen.net/npm/v/@resolid/di)
+![GitHub License](https://img.shields.io/github/license/resolid/framework)
+![NPM Version](https://img.shields.io/npm/v/%40resolid/di)
 
 <b>[Documentation](https://www.resolid.tech/docs/di)</b> | [Framework Bundle](https://github.com/resolid/framework)
 
@@ -31,87 +32,125 @@ yarn add @resolid/di
 bun add @resolid/di
 ```
 
-### Usage
-
-#### Creating a container
+### Basic Usage
 
 ```js
 import { createContainer } from "@resolid/di";
 
-const container = createContainer();
-```
-
-#### Binding dependencies
-
-You can bind values, functions, or factories:
-
-1. Bind a value
+const VALUE = Symbol("VALUE");
+const FUNCTION = Symbol("FUNCTION");
+const FACTORY = Symbol("FACTORY");
+
+const container = createContainer([
+  { name: VALUE, value: "Hello World" },
+  {
+    name: FUNCTION,
+    callable: () => {
+      return "Hello World from callable";
+    },
+  },
+  {
+    name: FACTORY,
+    factory: async ({ resolver, config }) => {
+      const value = await resolver.resolve(VALUE);
+
+      return value + " " + config.message || "from factory!";
+    },
+    /**
+     * Scope of a binding.
+     * singleton (default): Only one instance is created and shared for all resolves.
+     * transient: A new instance is created on each resolve.
+     */
+    scope: "singleton",
+    /**
+     * Optional configuration object passed to a factory.
+     * Type is inferred from the factory definition.
+     * Used to provide parameters for instance creation.
+     */
+    config: { message: " from factory with config" },
+  },
+]);
 
-```js
-const TOKEN = Symbol("token");
+const valueResult = await container.resolve(VALUE);
+console.log(valueResult); // Output: "Hello World"
 
-container.bind(TOKEN).toValue({ message: "Hello World" });
+const callable = await container.resolve(FUNCTION);
+const callableResult = callable();
+console.log(callableResult); // Output: "Hello World from callable"
 
-const result = await container.resolve(TOKEN); // result = "Hello World"
+const factoryResult = await container.resolve(FACTORY);
+console.log(factoryResult); // Output: "Hello World from factory with config"
 ```
 
-2. Bind a function
+### Lazy Resolve
 
-```js
-const FUNC_TOKEN = Symbol("func");
+You can create bindings that are resolved lazily, useful for circular dependencies or heavy computations:
 
-container.bind(FUNC_TOKEN).toFunction(() => console.log("Hello from function"));
+```js
+const LAZY_A = Symbol("LAZY_A");
+const LAZY_B = Symbol("LAZY_B");
+
+const container = createContainer([
+  {
+    name: LAZY_A,
+    factory: ({ resolver }) => {
+      const b = resolver.lazyResolve(LAZY_B);
+      return `A depends on ${b.value}`;
+    },
+  },
+  {
+    name: LAZY_B,
+    factory: ({ resolver }) => {
+      const a = resolver.lazyResolve(LAZY_A);
+      return `B depends on ${a.value}`;
+    },
+  },
+]);
 
-const fn = await container.resolve(FUNC_TOKEN);
-const result = fn(); // result = "Hello from function"
+// Accessing value after construction is safe
+await container.resolve(LAZY_A);
+await container.resolve(LAZY_B);
 ```
 
-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.
+> Note: Access `lazyResolve.value` **only after all bindings are constructed**, otherwise it will throw an error.
 
-- config is optional
+### Circular Dependency Detection
 
 ```js
-const TOKEN = Symbol("token");
+const A = Symbol("A");
+const B = Symbol("B");
 
-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}`;
+const container = createContainer([
+  {
+    name: A,
+    factory: ({ resolver }) => resolver.resolve(B),
   },
-  { scope: "singleton", config: { message: "World." } },
-);
+  {
+    name: B,
+    factory: ({ resolver }) => resolver.resolve(A),
+  },
+]);
 
-const result = await container.resolve(FACTORY_TOKEN); // result = "Factory resolved: Hello world."
+await container.resolve(A);
+// Throws Error: Circular dependency detected: A -> B -> A
 ```
 
-4. Circular dependencies
+### Dispose
 
 ```js
-const LAZY_DEP = Symbol("lazyDep");
-const CONSUMER = Symbol("consumer");
-
-container.bind(LAZY_DEP).toValue({ data: "lazy data" });
+class Resource {
+  async dispose() {
+    console.log("Resource disposed");
+  }
+}
 
-container.bind(CONSUMER).toFactory(({ resolver }) => {
-  const lazy = resolver.lazyResolve(LAZY_DEP);
+const RESOURCE = Symbol("RESOURCE");
 
-  return {
-    getLazyData: () => lazy.value.data,
-  };
-});
+const container = createContainer([{ name: RESOURCE, value: new Resource() }]);
 
-const consumer = await container.resolve(CONSUMER);
-// consumer.getLazyData()).toBe("lazy data");
+// Dispose all singleton instances
+await container.dispose();
+// Output: "Resource disposed"
 ```
 
 ## License

package/dist/index.d.ts

@@ -1,40 +1,43 @@
-//#region src/types/index.d.ts
-type Scope = "singleton" | "transient";
-type BindingConfig = Record<string, unknown>;
-//#endregion
 //#region src/container/index.d.ts
-type Resolve = (name: symbol) => unknown;
+type Resolve = <T>(name: symbol) => Promise<T>;
 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?: {
+type Scope = "singleton" | "transient";
+type BindingDefinition<Config extends Record<string, unknown> = Record<string, unknown>> = {
+  name: symbol;
+  value: unknown;
+  callable?: never;
+  factory?: never;
+  scope?: never;
+  config?: never;
+} | {
+  name: symbol;
+  callable: (...args: unknown[]) => unknown;
+  value?: never;
+  factory?: never;
+  scope?: never;
+  config?: never;
+} | {
+  name: symbol;
+  factory: (options: {
+    resolver: {
+      resolve: Resolve;
+      lazyResolve: LazyResolve;
+    };
+    config?: Config;
+  }) => unknown | Promise<unknown>;
   scope?: Scope;
-  config?: BindingConfig;
-}) => void;
+  config?: Config;
+  value?: never;
+  callable?: never;
+};
 type Disposable = {
   dispose: () => Promise<void> | void;
 };
 type Container = {
-  bind: (name: symbol) => {
-    toValue: ToValue;
-    toFunction: ToFunction;
-    toFactory: ToFactory;
-  };
-  resolve: <T>(name: symbol) => Promise<T>;
-  lazyResolve: LazyResolve;
+  resolve: Resolve;
 } & Disposable;
-declare const createContainer: () => Container;
+declare const createContainer: (definitions: readonly BindingDefinition[]) => Container;
 //#endregion
-export { BindingConfig, Container, Scope, createContainer };
+export { BindingDefinition, Container, Scope, createContainer };

package/dist/index.js

@@ -1 +1 @@
-const e=()=>{let e=new t;return{bind:t=>e.bind(t),resolve:t=>e.resolve(t),lazyResolve:t=>e.lazyResolve(t),dispose:()=>e.dispose()}};var t=class e{#bindings;#singletons;#constructing;#lazyResolveQueue=[];constructor(e,t,n){this.#bindings=e?.getBindings()??new Map,this.#singletons=e?.getSingletons()??new Map,this.#constructing=t?[...n??e?.getConstructing()??[],t]:[]}getBindings(){return this.#bindings}getSingletons(){return this.#singletons}getConstructing(){return this.#constructing}bind(e){return{toValue:t=>{this.#bindings.set(e,{factory:()=>t,scope:`singleton`})},toFunction:t=>{this.#bindings.set(e,{factory:()=>t,scope:`singleton`})},toFactory:(t,n)=>{this.#bindings.set(e,{factory:(e,r)=>t({resolver:{resolve:e,lazyResolve:r},config:n?.config}),scope:n?.scope??`singleton`,config:n?.config})}}}async#resolveBinding(t,n){let r=this.#bindings.get(t);if(!r)throw Error(`No binding found for name: ${t.toString()}`);let i=r.scope===`singleton`;if(i&&this.#singletons.has(t))return this.#singletons.get(t);let a=new e(this,t,n),o=await r.factory(e=>a.resolve(e),e=>a.lazyResolve(e));return i&&this.#singletons.set(t,o),await a.dequeueLazyResolves(),o}async dequeueLazyResolves(){for(let e of this.#lazyResolveQueue)try{e.resolve(await this.#resolveBinding(e.name,[]))}catch(t){throw Error(`Failed to resolve lazy resolver for name ${e.name.toString()}: ${t instanceof Error?t.message:String(t)}`)}}async resolve(e){if(this.#constructing.includes(e))throw Error(`Circular dependency detected: ${[...this.#constructing,e].map(String).join(` -> `)}`);return this.#resolveBinding(e)}lazyResolve(e){let t;return new Promise(t=>{this.#lazyResolveQueue.push({name:e,resolve:e=>{t(e)}})}).then(e=>{t=e}),{get value(){if(!t)throw Error(`Lazy binding is not yet resolved. Do not use lazy-resolved bindings before the binding construction ends.`);return t}}}async dispose(){let e=[];for(let[t,n]of this.#singletons)if(typeof n.dispose==`function`)try{await n.dispose()}catch(n){e.push({name:t,error:n})}if(e.length>0){let t=e.map(({name:e,error:t})=>`${e.toString()}: ${t instanceof Error?t.message:String(t)}`).join(`; `);throw Error(`Failed to dispose ${e.length} binding(s): ${t}`)}}};export{e as createContainer};
+const e=e=>{let n=new t;return n.register(e),{resolve:e=>n.resolve(e),dispose:()=>n.dispose()}};var t=class e{#bindings;#singletons;#constructing;#lazyResolveQueue=[];constructor(e,t,n){this.#bindings=e?.getBindings()??new Map,this.#singletons=e?.getSingletons()??new Map,this.#constructing=t?[...n??e?.getConstructing()??[],t]:[]}getBindings(){return this.#bindings}getSingletons(){return this.#singletons}getConstructing(){return this.#constructing}register(e){for(let t of e)t.callable?this.#bindings.set(t.name,{factory:()=>t.callable,scope:`singleton`}):t.factory?this.#bindings.set(t.name,{factory:(e,n)=>t.factory({resolver:{resolve:e,lazyResolve:n},config:t.config}),scope:t.scope??`singleton`,config:t.config}):this.#bindings.set(t.name,{factory:()=>t.value,scope:`singleton`})}async#resolveBinding(t,n){let r=this.#bindings.get(t);if(!r)throw Error(`No binding found for ${t.description??t.toString()}.`);let i=r.scope===`singleton`;if(i&&this.#singletons.has(t))return this.#singletons.get(t);let a=new e(this,t,n),o=await r.factory(e=>a.resolve(e),e=>a.lazyResolve(e));return i&&this.#singletons.set(t,o),await a.dequeueLazyResolves(),o}async dequeueLazyResolves(){for(let e of this.#lazyResolveQueue)try{e.resolve(await this.#resolveBinding(e.name,[]))}catch(t){throw Error(`Failed to resolve lazy binding ${e.name.description??e.name.toString()}: ${t instanceof Error?t.message:String(t)}`)}}async resolve(e){if(this.#constructing.includes(e))throw Error(`Circular dependency detected: ${[...this.#constructing,e].map(e=>e.description??e.toString()).join(` -> `)}`);return this.#resolveBinding(e)}lazyResolve(e){let t;return new Promise(t=>{this.#lazyResolveQueue.push({name:e,resolve:e=>{t(e)}})}).then(e=>{t=e}),{get value(){if(!t)throw Error(`Lazy binding is not yet resolved. Avoid accessing it before container construction finishes.`);return t}}}async dispose(){let e=[];for(let[t,n]of this.#singletons)if(typeof n.dispose==`function`)try{await n.dispose()}catch(n){e.push({name:t,error:n})}if(this.#singletons.clear(),e.length>0){let t=e.map(({name:e,error:t})=>`${e.description??e.toString()}: ${t instanceof Error?t.message:String(t)}`).join(`; `);throw Error(`Failed to dispose ${e.length} binding(s):\n${t}`)}}};export{e as createContainer};

package/package.json

@@ -4,7 +4,7 @@
   "license": "MIT",
   "private": false,
   "sideEffects": false,
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "The Resolid DI Container package.",
   "author": {
     "name": "Huijie Wei",