@resolid/di 0.5.0 → 0.6.0

package/README.md

@@ -8,17 +8,19 @@
 ## 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
+Supports singleton & transient scopes, lazy resolution, optional dependencies, 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.
+- Lazy resolution for dependencies.
+- Optional dependency resolution.
 - Detects circular dependencies.
 - Handles disposable instances with dispose() support.
-- Fully async-compatible.
+- Fully async-compatible with inject() and injectAsync() functions.
+- Context-aware injection with InjectionContext.
 
 ### Installation
 
@@ -34,123 +36,233 @@ bun add @resolid/di
 
 ### Basic Usage
 
-```js
-import { createContainer } from "@resolid/di";
+```typescript
+import { Container, inject } from "@resolid/di";
 
-const VALUE = "VALUE";
-const FUNCTION = "FUNCTION";
-const FACTORY = "FACTORY";
+class LogService {
+  log(message: string): void {
+    console.log(`[LOG]: ${message}`);
+  }
+}
 
-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" },
-  },
-]);
+class UserService {
+  private logger: LogService;
+
+  constructor(logger: LogService) {
+    this.logger = logger;
+  }
+
+  createUser(name: string): void {
+    this.logger.log(`Creating user: ${name}`);
+  }
+}
+
+const container = new Container();
+
+container.add({
+  token: LogService,
+  factory: () => new LogService(),
+});
+
+container.add({
+  token: UserService,
+  factory: () => new UserService(inject(LogService)),
+});
+
+const userService = container.get(USER_SERVICE);
+
+userService.createUser("John Doe"); // Output: [LOG]: Creating user: John Doe
+```
 
-const valueResult = await container.resolve(VALUE);
-console.log(valueResult); // Output: "Hello World"
+### Scopes
 
-const callable = await container.resolve(FUNCTION);
-const callableResult = callable();
-console.log(callableResult); // Output: "Hello World from callable"
+The container supports two scopes:
 
-const factoryResult = await container.resolve(FACTORY);
-console.log(factoryResult); // Output: "Hello World from factory with config"
+- **singleton** (default): Only one instance is created and shared for all resolutions.
+- **transient**: A new instance is created on each resolution.
+
+```typescript
+container.add({
+  token: LogService,
+  factory: () => new LogService(),
+  scope: "singleton", // Default scope
+});
+
+container.add({
+  token: Symbol("REQUEST_ID"),
+  factory: () => Math.random(),
+  scope: "transient", // New instance each time
+});
 ```
 
-### Lazy Resolve
+### Asynchronous Dependencies
+
+```typescript
+import { Container, injectAsync } from "@resolid/di";
+
+class AsyncDatabaseService {
+  async connect(): Promise<void> {
+    await new Promise(resolve => setTimeout(resolve, 100));
+    console.log("Database connected");
+  }
+}
 
-You can create bindings that are resolved lazily, useful for circular dependencies or heavy computations:
+class AsyncUserService {
+  private db : AsyncDatabaseService
 
-```js
-const LAZY_A = "LAZY_A";
-const LAZY_B = "LAZY_B";
+  constructor(db: AsyncDatabaseService) {
+    this.db = db;
+  }
 
-const container = createContainer([
-  {
-    name: LAZY_A,
-    factory: ({ resolver }) => {
-      const b = resolver.lazyResolve(LAZY_B);
-      return `A depends on ${b.value}`;
-    },
+  async getUser(id: number): Promise<string> {
+    return `User ${id}`;
+  }
+}
+
+const container = new Container();
+
+container.add({
+  token: AsyncDatabaseService,
+  factory: async () => {
+    const db = new AsyncDatabaseService();
+    await db.connect();
+    return db;
   },
-  {
-    name: LAZY_B,
-    factory: ({ resolver }) => {
-      const a = resolver.lazyResolve(LAZY_A);
-      return `B depends on ${a.value}`;
-    },
+  async: true,
+});
+
+container.add({
+  token: AsyncUserService,
+  factory: async () => {
+    const db = await injectAsync(AsyncDatabaseService);
+    return new AsyncUserService(db)
   },
-]);
+  async: true,
+});
+
+// Resolve async services
+const userService = await container.getAsync(AsyncUserService);
+const user = await userService.getUser(1);
+
+console.log(user); // Output: User 1
+```
+
+### Optional Dependencies
 
-// Accessing value after construction is safe
-await container.resolve(LAZY_A);
-await container.resolve(LAZY_B);
+```typescript
+import { Container, inject } from "@resolid/di";
+
+class AnalyticsService {
+  private logger?: LogService
+
+  constructor(logger?: LogService) {
+    this.logger = logger;
+  }
+
+  track(event: string): void {
+    if (this.logger) {
+      this.logger.log(`Analytics: ${event}`);
+    } else {
+      console.log(`Analytics (no logger): ${event}`);
+    }
+  }
+}
+
+const container = new Container();
+
+// Logger is optional
+container.add({
+  token: AnalyticsService,
+  factory: () => new AnalyticsService(inject(LOG_SERVICE, { optional: true })),
+});
+
+const analytics = container.get(AnalyticsService);
+analytics.track("page_view"); // Output: Analytics (no logger): page_view
 ```
 
-> Note: Access `lazyResolve.value` **only after all bindings are constructed**, otherwise it will throw an error.
+### Lazy Resolution
+
+```typescript
+import { Container, inject } from "@resolid/di";
+
+class ReportService {
+  private getLogger : () => LogService;
+
+  constructor(private getLogger: () => LogService) {
+    this.getLogger = getLogger;
+  }
+
+  generateReport(): void {
+    const logger = this.getLogger();
+    logger.log("Report generated");
+  }
+}
+
+const container = new Container();
+
+container.add({
+  token: LogService,
+  factory: () => new LogService(),
+});
+
+container.add({
+  token: ReportService,
+  factory: () => new ReportService(inject(LogService, { lazy: true })),
+});
+
+const reportService = container.get(ReportService);
+reportService.generateReport(); // Output: [LOG]: Report generated
+```
 
 ### Circular Dependency Detection
 
-```js
-const A = "A";
-const B = "B";
+```typescript
+class ApiService {
+  constructor(private auth: AuthService) {}
+}
 
-const container = createContainer([
-  {
-    name: A,
-    factory: ({ resolver }) => resolver.resolve(B),
-  },
-  {
-    name: B,
-    factory: ({ resolver }) => resolver.resolve(A),
-  },
-]);
+class AuthService {
+  constructor(private api: ApiService) {}
+}
+
+const container = new Container();
+
+container.add({
+  token: ApiService,
+  factory: () => new ApiService(inject(AuthService)),
+});
 
-await container.resolve(A);
-// Throws Error: Circular dependency detected: A -> B -> A
+container.add({
+  token: AuthService,
+  factory: () => new AuthService(inject(ApiService)),
+});
+
+container.get(ApiService); // Throws: Circular dependency detected ApiService -> AuthService -> ApiService
 ```
 
-### Dispose
+### Disposable Resources
+
+```typescript
+import { Container } from "@resolid/di";
 
-```js
-class Resource {
-  async dispose() {
-    console.log("Resource disposed");
+class DatabaseConnection {
+  async dispose(): Promise<void> {
+    console.log("Database connection closed");
   }
 }
 
-const RESOURCE = "RESOURCE";
+const container = new Container();
+
+container.add({
+  token: DatabaseConnection,
+  factory: async () => new DatabaseConnection(),
+  async: true,
+});
 
-const container = createContainer([{ name: RESOURCE, value: new Resource() }]);
+const db = await container.getAsync(DatabaseConnection);
 
 // Dispose all singleton instances
-await container.dispose();
-// Output: "Resource disposed"
+await container.dispose(); // Output: Database connection closed
 ```
 
 ## License

package/dist/index.d.ts

@@ -1,45 +1,119 @@
-//#region src/index.d.ts
-type Resolve = <T>(name: string) => Promise<T>;
-type LazyResolve = <T = unknown>(name: string) => Readonly<{
-  value: T;
-}>;
+//#region src/shared/index.d.ts
+type Class<T> = new (...args: any[]) => T;
+type Token<T = unknown> = symbol | Class<T>;
+interface Disposable {
+  dispose: () => Promise<void> | void;
+}
+interface Resolver {
+  get: (<T>(token: Token<T>) => T) & (<T>(token: Token<T>, options: {
+    optional: true;
+  }) => T | undefined) & (<T>(token: Token<T>, options: {
+    lazy: true;
+  }) => () => T) & (<T>(token: Token<T>, options: {
+    lazy: true;
+    optional: true;
+  }) => () => T | undefined) & (<T>(token: Token<T>, options: {
+    lazy?: false;
+    optional?: boolean;
+  }) => T | undefined) & (<T>(token: Token<T>, options?: {
+    lazy?: boolean;
+    optional?: boolean;
+  }) => T | undefined | (() => T | undefined));
+  getAsync: (<T>(token: Token<T>) => Promise<T>) & (<T>(token: Token<T>, options: {
+    optional: true;
+  }) => Promise<T | undefined>) & (<T>(token: Token<T>, options: {
+    lazy: true;
+  }) => () => Promise<T>) & (<T>(token: Token<T>, options: {
+    lazy: true;
+    optional: true;
+  }) => () => Promise<T | undefined>) & (<T>(token: Token<T>, options: {
+    lazy?: false;
+    optional?: boolean;
+  }) => Promise<T | undefined>) & (<T>(token: Token<T>, options?: {
+    lazy?: boolean;
+    optional?: boolean;
+  }) => Promise<T | undefined> | (() => Promise<T | undefined>));
+}
+//#endregion
+//#region src/container/index.d.ts
 type Scope = "singleton" | "transient";
-type Resolver = {
-  resolve: Resolve;
-  lazyResolve: LazyResolve;
-};
-type FactoryConfig = Record<string, unknown>;
-type BindingDefinition<T$1 = unknown, C extends FactoryConfig = FactoryConfig> = {
-  name: string;
-  value: T$1;
-  callable?: never;
-  factory?: never;
-  scope?: never;
-  config?: never;
-} | {
-  name: string;
-  callable: (...args: unknown[]) => T$1;
-  value?: never;
-  factory?: never;
-  scope?: never;
-  config?: never;
-} | {
-  name: string;
-  factory: (options: {
-    resolver: Resolver;
-    config?: C;
-  }) => T$1 | Promise<T$1>;
+type SyncProvider<T = unknown> = {
+  token: Token<T>;
+  factory: (resolver: Resolver) => T;
+  async?: false;
   scope?: Scope;
-  config?: C;
-  value?: never;
-  callable?: never;
 };
-type Disposable = {
-  dispose: () => Promise<void> | void;
+type AsyncProvider<T = unknown> = {
+  token: Token<T>;
+  factory: (resolver: Resolver) => Promise<T>;
+  async?: true;
+  scope?: Scope;
 };
-type Container = {
-  resolve: Resolve;
-} & Disposable;
-declare const createContainer: (definitions: readonly BindingDefinition[]) => Container;
+type Provider<T = unknown> = SyncProvider<T> | AsyncProvider<T>;
+declare class Container implements Resolver, Disposable {
+  private readonly _providers;
+  private readonly _singletons;
+  private readonly _constructing;
+  private _checkCircularDependency;
+  private _resolveProvide;
+  private _resolve;
+  private _resolveAsync;
+  add(provider: Provider): void;
+  get<T>(token: Token<T>): T;
+  get<T>(token: Token<T>, options: {
+    optional: true;
+  }): T | undefined;
+  get<T>(token: Token<T>, options: {
+    lazy: true;
+  }): () => T;
+  get<T>(token: Token<T>, options: {
+    lazy: true;
+    optional: true;
+  }): () => T | undefined;
+  get<T>(token: Token<T>, options: {
+    lazy?: false;
+    optional?: boolean;
+  }): T | undefined;
+  getAsync<T>(token: Token<T>): Promise<T>;
+  getAsync<T>(token: Token<T>, options: {
+    optional: true;
+  }): Promise<T | undefined>;
+  getAsync<T>(token: Token<T>, options: {
+    lazy: true;
+  }): () => Promise<T>;
+  getAsync<T>(token: Token<T>, options: {
+    lazy: true;
+    optional: true;
+  }): () => Promise<T | undefined>;
+  getAsync<T>(token: Token<T>, options: {
+    lazy?: false;
+    optional?: boolean;
+  }): Promise<T | undefined>;
+  dispose(): Promise<void>;
+}
+//#endregion
+//#region src/inject/index.d.ts
+declare function inject<T>(token: Token<T>): T;
+declare function inject<T>(token: Token<T>, options: {
+  optional: true;
+}): T | undefined;
+declare function inject<T>(token: Token<T>, options: {
+  lazy: true;
+}): () => T;
+declare function inject<T>(token: Token<T>, options: {
+  lazy: true;
+  optional: true;
+}): () => T | undefined;
+declare function injectAsync<T>(token: Token<T>): Promise<T>;
+declare function injectAsync<T>(token: Token<T>, options: {
+  optional: true;
+}): Promise<T | undefined>;
+declare function injectAsync<T>(token: Token<T>, options: {
+  lazy: true;
+}): () => Promise<T>;
+declare function injectAsync<T>(token: Token<T>, options: {
+  lazy: true;
+  optional: true;
+}): () => Promise<T | undefined>;
 //#endregion
-export { BindingDefinition, Container, FactoryConfig, Resolver, Scope, createContainer };
+export { Container, Provider, type Resolver, Scope, type Token, inject, injectAsync };

package/dist/index.js

@@ -1 +1 @@
-const e=process.env.NODE_ENV===`development`,t=e=>{let t=n(`__R_DI`,()=>{let t=new r;return t.register(e),t});return{resolve:e=>t.resolve(e),dispose:()=>t.dispose()}},n=(t,n)=>{if(!e)return n();let r=globalThis;if(t in r)return r[t];let i=n();return r[t]=i,i};var r=class e{_bindings;_singletons;_constructing;_lazyResolveQueue=[];constructor(e,t,n){this._bindings=e?._bindings??new Map,this._singletons=e?._singletons??new Map,this._constructing=t?[...n??e?._constructing??[],t]:[]}register(e){for(let t of e){let e=t.callable?()=>t.callable:t.factory?(e,n)=>t.factory({resolver:{resolve:e,lazyResolve:n},config:t.config}):()=>t.value;this._bindings.set(t.name,{factory:e,scope:t.scope??`singleton`,config:t.config})}}async _resolveBinding(t,n){let r=this._bindings.get(t);if(!r)throw Error(`No binding found for ${t}.`);let i=r.scope===`singleton`;if(i&&this._singletons.has(t))return this._singletons.get(t);let a=new e(this,t,n),o=r.factory(e=>a.resolve(e),e=>a.lazyResolve(e)),s=o instanceof Promise?await o:o;return i&&this._singletons.set(t,s),await a.dequeueLazyResolves(),s}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}: ${t instanceof Error?t.message:String(t)}`)}}async resolve(e){if(this._constructing.includes(e))throw Error(`Circular dependency detected: ${[...this._constructing,e].join(` -> `)}`);return this._resolveBinding(e)}lazyResolve(e){let t={resolved:!1};return this._lazyResolveQueue.push({name:e,resolve:e=>{t.value=e,t.resolved=!0}}),{get value(){if(!t.resolved)throw Error(`Lazy binding is not yet resolved. Avoid accessing it before container construction finishes.`);return t.value}}}async dispose(){let e=0,t=``;for(let[n,r]of this._singletons)if(typeof r.dispose==`function`)try{await r.dispose()}catch(r){e++,t+=`${n}: ${r instanceof Error?r.message:r}; `}if(this._singletons.clear(),e>0)throw Error(`Failed to dispose ${e} binding(s):\n${t.slice(0,-2)}`)}};export{t as createContainer};
+var e=class extends Error{constructor(){super(`inject() / injectAsync() must be called within a injection context`)}},t=class t{static contextStack=[];resolver;constructor(e){this.resolver=e}static current(){let t=this.contextStack[this.contextStack.length-1];if(t===void 0)throw new e;return t}run(e){t.contextStack.push(this);try{return e(this.resolver)}finally{t.contextStack.pop()}}async runAsync(e){t.contextStack.push(this);try{return await e(this.resolver)}finally{t.contextStack.pop()}}};function n(e){return typeof e==`symbol`?e.description??String(e):e.name}var r=class{_providers=new Map;_singletons=new Map;_constructing=[];_checkCircularDependency(e){if(this._constructing.includes(e))throw Error(`Circular dependency detected ${[...this._constructing,e].map(n).join(` -> `)}`)}_resolveProvide(e,t){let r=this._providers.get(e);if(r===void 0&&!t)throw Error(`No provider found for ${n(e)}`);return r}_resolve(e,r){this._checkCircularDependency(e);let i=this._resolveProvide(e,r);if(i===void 0)return;if(i.async)throw Error(`Provider for ${n(e)} is async, please use injectAsync()`);let a=i.scope!==`transient`;if(a&&this._singletons.has(e))return this._singletons.get(e);this._constructing.push(e);try{let n=new t(this).run(()=>i.factory(this));return a&&this._singletons.set(e,n),n}finally{this._constructing.pop()}}async _resolveAsync(e,n){this._checkCircularDependency(e);let r=this._resolveProvide(e,n);if(r===void 0)return;let i=r.scope!==`transient`;if(i&&this._singletons.has(e))return this._singletons.get(e);this._constructing.push(e);try{let n=await new t(this).runAsync(async()=>await r.factory(this));return i&&this._singletons.set(e,n),n}finally{this._constructing.pop()}}add(e){this._providers.set(e.token,e)}get(e,t){return t?.lazy??!1?()=>this.get(e,{...t,lazy:!1}):this._resolve(e,t?.optional??!1)}getAsync(e,t){return t?.lazy??!1?()=>this.getAsync(e,{...t,lazy:!1}):this._resolveAsync(e,t?.optional??!1)}async dispose(){let e=0,t=``;for(let[r,i]of this._singletons)if(typeof i.dispose==`function`)try{await i.dispose()}catch(i){e++,t+=`${n(r)}: ${i instanceof Error?i.message:i}; `}if(this._singletons.clear(),e>0)throw Error(`Failed to dispose ${e} provider(s):\n${t.slice(0,-2)}`)}};function i(n,r){try{return t.current().run(e=>e.get(n,r))}catch(t){if(t instanceof e&&r?.optional==1)return;throw t}}function a(n,r){try{return r?.lazy?t.current().run(e=>e.getAsync(n,{...r,lazy:!0})):t.current().runAsync(e=>e.getAsync(n,{...r,lazy:!1}))}catch(t){return t instanceof e&&r?.optional===!0?r?.lazy?()=>Promise.resolve(void 0):Promise.resolve(void 0):Promise.reject(t)}}export{r as Container,i as inject,a as injectAsync};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@resolid/di",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "private": false,
   "description": "The Resolid DI Container package.",
   "keywords": [
@@ -36,10 +36,10 @@
     "dist"
   ],
   "devDependencies": {
-    "@vitest/coverage-v8": "beta",
-    "tsdown": "^0.15.8",
+    "@vitest/coverage-v8": "^4.0.3",
+    "tsdown": "^0.15.10",
     "typescript": "^5.9.3",
-    "vitest": "beta"
+    "vitest": "^4.0.3"
   },
   "engines": {
     "node": "^20.19.0 || ^22.13.0 || >=24"