getbox 1.0.0 → 1.2.0

package/CONTEXT.md

@@ -0,0 +1,123 @@
+# getbox/context
+
+`getbox/context` provides an alternative pattern where the box is available implicitly via `AsyncLocalStorage`. Classes can resolve dependencies directly in their constructors without needing `static init` methods or passing the box around.
+
+## Setup
+
+Wrap your application entry point with `withBox` to create a scoped box.
+
+```ts
+import { withBox } from "getbox/context";
+
+withBox(() => {
+  // All code in this scope can resolve dependencies
+  const app = resolve(App);
+  app.start();
+});
+```
+
+You can also pass an existing box to the scope.
+
+```ts
+import { Box } from "getbox";
+import { withBox } from "getbox/context";
+
+const box = new Box();
+Box.mock(box, LoggerFactory, new TestLogger());
+
+withBox(box, () => {
+  const app = resolve(App);
+  app.start();
+});
+```
+
+## Resolving dependencies
+
+With the context pattern, classes can use `resolve` directly as field initializers. No `static init` method is needed.
+
+```ts
+import { resolve } from "getbox/context";
+
+class UserService {
+  public db = resolve(Database);
+  public logger = resolve(LoggerFactory);
+
+  createUser(name: string) {
+    this.logger.log(`Creating user: ${name}`);
+    return this.db.query("INSERT INTO users ...");
+  }
+}
+```
+
+Compare this with the base pattern which requires `static init`:
+
+```ts
+import { Box } from "getbox";
+
+class UserService {
+  constructor(private db: Database, private logger: Logger) {}
+
+  static init(box: Box) {
+    return box.for(UserService).get(Database, LoggerFactory);
+  }
+}
+```
+
+## Resolving multiple dependencies
+
+Use `resolveAll` to resolve multiple constructors at once. Accepts an object or array of constructors.
+
+```ts
+withBox(() => {
+  // Object form
+  const { db, logger } = resolveAll({ db: Database, logger: LoggerFactory });
+
+  // Array form
+  const [db2, logger2] = resolveAll([Database, LoggerFactory]);
+
+  console.log(db === db2); // true (cached)
+  console.log(logger === logger2); // true (cached)
+});
+```
+
+## Resolving constructor parameters
+
+Use `construct` to create a class instance with resolved constructor parameters.
+
+```ts
+class UserService {
+  constructor(private db: Database, private logger: Logger) {}
+}
+
+withBox(() => {
+  const service = construct(UserService).get(Database, LoggerFactory);
+  service.createUser("Alice");
+});
+```
+
+## Accessing the box
+
+Use `useBox()` to get the current box from the scope. This is useful when you need full access to the box API.
+
+```ts
+withBox(() => {
+  const box = useBox();
+  const db = box.new(Database);
+});
+```
+
+## Nested and concurrent scopes
+
+Each `withBox` call creates an independent scope. Nested scopes do not share the parent box, and concurrent async scopes are isolated from each other.
+
+```ts
+withBox(() => {
+  const db = resolve(Database);
+
+  // Inner scope gets a fresh box
+  withBox(() => {
+    const db2 = resolve(Database);
+    console.log(db === db2); // false (different scope)
+  });
+});
+```

package/README.md

@@ -2,9 +2,11 @@
 
 ### Lightweight dependency injection for TypeScript.
 
-`getbox` provides a simple way of managing dependencies in TypeScript applications. It uses classes and factory functions to define dependencies and automatically handles instance caching.
+`getbox` provides a simple way of managing dependencies in TypeScript applications. Dependencies are defined as constructors that act as interfaces for the values they resolve.
 
-The main advantage of `getbox` is removing the need to manually pass references around when instantiating classes that depend on one another.
+Callers know the type of the value they need, but not how it will be derived. The box resolves constructors lazily and caches instances automatically.
+
+For an alternative pattern using AsyncLocalStorage where classes can resolve dependencies directly in their constructors, see [getbox/context](./CONTEXT.md).
 
 ## Installation
 
@@ -22,8 +24,6 @@ Classes are instantiated once and cached. Subsequent calls return the cached ins
 
 ```ts
 // printer.ts
-import { Box } from "getbox";
-
 export class Printer {
   print(text: string): string {
     return text.toUpperCase();
@@ -77,29 +77,21 @@ console.log(office.printer === printer); // true
 Use `box.new()` to create a new instance each time without caching. This is useful for instances that should not be shared.
 
 ```ts
-// printer.ts
+// main.ts
 import { Box } from "getbox";
 
-export class Printer {
-  id = Math.random();
-
-  print(text: string): string {
-    return text.toUpperCase();
+class Database {
+  connect() {
+    /* ... */
   }
 }
-```
-
-```ts
-// main.ts
-import { Box } from "getbox";
-import { Printer } from "./printer";
 
 const box = new Box();
 
-const printer1 = box.new(Printer);
-const printer2 = box.new(Printer);
+const db1 = box.new(Database);
+const db2 = box.new(Database);
 
-console.log(printer1 === printer2); // false
+console.log(db1 === db2); // false
 ```
 
 ## Factory functions
@@ -146,7 +138,7 @@ export class UserService {
 
 ## Constants
 
-Use the `constant` helper to register constant values without needing a factory or class.
+Use the `constant` helper to register constant values without needing a factory or class. Constant values are never cached since they are already fixed.
 
 ```ts
 import { Box, constant } from "getbox";
@@ -154,7 +146,7 @@ import { Box, constant } from "getbox";
 const ApiUrl = constant("https://api.example.com");
 const Port = constant(3000);
 const Config = constant({
-  apiUrl: "https://api.example.com",
+  baseUrl: "https://example.com",
   timeout: 5000,
 });
 
@@ -169,39 +161,71 @@ console.log(port); // 3000
 console.log(config.timeout); // 5000
 ```
 
-## Constructing classes with dependencies
+Since constructors act as interfaces, a `constant` can later be replaced with a `factory` without changing any callers.
+
+```ts
+const ApiUrl = factory((box: Box) => {
+  const config = box.get(Config);
+  return `${config.baseUrl}/api`;
+});
+
+const apiUrl = box.get(ApiUrl); // "https://example.com/api"
+```
+
+## Transient factories
 
-Use `box.for()` for a convenient way to create instances of classes that take other constructors as dependencies. The instance created with `box.for()` is not cached, but dependencies resolved with `.get()` are cached.
+Use the `transient` helper to create a factory whose result is never cached. The factory is called on every resolution, even when retrieved via `box.get()`.
 
 ```ts
-// database.ts
-export class Database {
-  connect() { /* ... */ }
-}
+import { Box, transient } from "getbox";
 
-// logger.ts
-import { Box, factory } from "getbox";
+const RequestId = transient(() => crypto.randomUUID());
 
-export interface Logger {
-  log(message: string): void;
-}
+const box = new Box();
 
-export const LoggerFactory = factory((box: Box): Logger => {
-  return console;
-});
+const id1 = box.get(RequestId);
+const id2 = box.get(RequestId);
+
+console.log(id1 === id2); // false
 ```
 
+## Resolving multiple constructors
+
+Use `box.all.get()` to resolve multiple constructors at once. Pass an object to get an object of instances, or an array to get an array of instances.
+
 ```ts
-// service.ts
 import { Box } from "getbox";
-import { Database } from "./database";
-import { Logger, LoggerFactory } from "./logger";
 
-export class UserService {
-  constructor(
-    private db: Database,
-    private logger: Logger
-  ) {}
+const box = new Box();
+
+// Object form
+const { db, logger } = box.all.get({ db: Database, logger: LoggerFactory });
+
+// Array form
+const [db2, logger2] = box.all.get([Database, LoggerFactory]);
+
+console.log(db === db2); // true (cached)
+console.log(logger === logger2); // true (cached)
+```
+
+Use `box.all.new()` to resolve multiple constructors as transient instances.
+
+```ts
+const { db } = box.all.new({ db: Database });
+const [db2] = box.all.new([Database]);
+
+console.log(db === db2); // false (transient)
+```
+
+## Class constructors
+
+Use `box.for()` inside a class's `static init` method to resolve constructor dependencies automatically. The instance returned by the builder is cached or transient depending on whether the class is retrieved via `box.get()` or `box.new()`.
+
+```ts
+import { Box, factory } from "getbox";
+
+class UserService {
+  constructor(private db: Database, private logger: Logger) {}
 
   static init(box: Box) {
     // Create new instance with cached dependencies
@@ -210,18 +234,10 @@ export class UserService {
 
   createUser(name: string) {
     this.logger.log(`Creating user: ${name}`);
-    // Use db to save user
   }
 }
-```
-
-```ts
-// main.ts
-import { Box } from "getbox";
-import { UserService } from "./service";
 
 const box = new Box();
-
 const service = box.get(UserService);
 service.createUser("Alice");
 ```
@@ -245,7 +261,8 @@ class MockLogger implements Logger {
 }
 
 const box = new Box();
-Box.mock(box, LoggerFactory, new MockLogger());
+const mockLogger = new MockLogger();
+Box.mock(box, LoggerFactory, mockLogger);
 
 const service = box.get(UserService);
 service.createUser("Alice");
@@ -253,6 +270,23 @@ service.createUser("Alice");
 console.log(mockLogger.messages); // ["Creating user: Alice"]
 ```
 
+## Clearing the cache
+
+Use `Box.clear` to remove cached instances. Pass a specific constructor to clear a single entry, or omit it to clear all cached instances.
+
+```ts
+const box = new Box();
+
+const db = box.get(Database);
+
+// Clear a specific constructor
+Box.clear(box, Database);
+console.log(box.get(Database) === db); // false (new instance)
+
+// Clear all cached instances
+Box.clear(box);
+```
+
 ## Circular dependencies
 
 `getbox` does not prevent circular dependencies. You should structure your code to avoid circular imports between modules.

package/dist/context.cjs

@@ -0,0 +1,42 @@
+const require_index = require('./index.cjs');
+let node_async_hooks = require("node:async_hooks");
+
+//#region src/context.ts
+const storage = new node_async_hooks.AsyncLocalStorage();
+function withBox(boxOrFn, fn) {
+	if (typeof boxOrFn === "function") return storage.run(new require_index.Box(), boxOrFn);
+	return storage.run(boxOrFn, fn);
+}
+/**
+* Returns the current {@link Box} from the active {@link withBox} scope.
+* Throws if called outside a scope.
+*/
+function useBox() {
+	const box = storage.getStore();
+	if (!box) throw new Error("useBox() must be called within a withBox() scope");
+	return box;
+}
+/**
+* Resolves a cached instance from the current {@link withBox} scope.
+* Shorthand for `useBox().get(constructor)`.
+*/
+function resolve(constructor) {
+	return useBox().get(constructor);
+}
+function resolveAll(constructors) {
+	return useBox().all.get(constructors);
+}
+/**
+* Returns a builder for creating a class instance with resolved constructor
+* parameters from the current {@link withBox} scope. Shorthand for `useBox().for(constructor)`.
+*/
+function construct(constructor) {
+	return useBox().for(constructor);
+}
+
+//#endregion
+exports.construct = construct;
+exports.resolve = resolve;
+exports.resolveAll = resolveAll;
+exports.useBox = useBox;
+exports.withBox = withBox;

package/dist/context.d.cts

@@ -0,0 +1,33 @@
+import { Box, Construct, Constructor, ConstructorInstanceType } from "./index.cjs";
+
+//#region src/context.d.ts
+
+/**
+ * Runs a function within a scoped {@link Box} context using AsyncLocalStorage.
+ * Creates a fresh Box if none is provided.
+ */
+declare function withBox<T>(fn: () => T): T;
+declare function withBox<T>(box: Box, fn: () => T): T;
+/**
+ * Returns the current {@link Box} from the active {@link withBox} scope.
+ * Throws if called outside a scope.
+ */
+declare function useBox(): Box;
+/**
+ * Resolves a cached instance from the current {@link withBox} scope.
+ * Shorthand for `useBox().get(constructor)`.
+ */
+declare function resolve<T>(constructor: Constructor<T>): T;
+/**
+ * Resolves multiple cached instances from the current {@link withBox} scope.
+ * Shorthand for `useBox().all.get(constructors)`.
+ */
+declare function resolveAll<const T extends Constructor<any>[]>(constructors: T): { [K in keyof T]: ConstructorInstanceType<T[K]> };
+declare function resolveAll<T extends Record<string, Constructor<any>>>(constructors: T): { [K in keyof T]: ConstructorInstanceType<T[K]> };
+/**
+ * Returns a builder for creating a class instance with resolved constructor
+ * parameters from the current {@link withBox} scope. Shorthand for `useBox().for(constructor)`.
+ */
+declare function construct<T extends new (...args: any) => any>(constructor: T): Construct<T>;
+//#endregion
+export { construct, resolve, resolveAll, useBox, withBox };

package/dist/context.d.mts

@@ -0,0 +1,33 @@
+import { Box, Construct, Constructor, ConstructorInstanceType } from "./index.mjs";
+
+//#region src/context.d.ts
+
+/**
+ * Runs a function within a scoped {@link Box} context using AsyncLocalStorage.
+ * Creates a fresh Box if none is provided.
+ */
+declare function withBox<T>(fn: () => T): T;
+declare function withBox<T>(box: Box, fn: () => T): T;
+/**
+ * Returns the current {@link Box} from the active {@link withBox} scope.
+ * Throws if called outside a scope.
+ */
+declare function useBox(): Box;
+/**
+ * Resolves a cached instance from the current {@link withBox} scope.
+ * Shorthand for `useBox().get(constructor)`.
+ */
+declare function resolve<T>(constructor: Constructor<T>): T;
+/**
+ * Resolves multiple cached instances from the current {@link withBox} scope.
+ * Shorthand for `useBox().all.get(constructors)`.
+ */
+declare function resolveAll<const T extends Constructor<any>[]>(constructors: T): { [K in keyof T]: ConstructorInstanceType<T[K]> };
+declare function resolveAll<T extends Record<string, Constructor<any>>>(constructors: T): { [K in keyof T]: ConstructorInstanceType<T[K]> };
+/**
+ * Returns a builder for creating a class instance with resolved constructor
+ * parameters from the current {@link withBox} scope. Shorthand for `useBox().for(constructor)`.
+ */
+declare function construct<T extends new (...args: any) => any>(constructor: T): Construct<T>;
+//#endregion
+export { construct, resolve, resolveAll, useBox, withBox };

package/dist/context.mjs

@@ -0,0 +1,38 @@
+import { Box } from "./index.mjs";
+import { AsyncLocalStorage } from "node:async_hooks";
+
+//#region src/context.ts
+const storage = new AsyncLocalStorage();
+function withBox(boxOrFn, fn) {
+	if (typeof boxOrFn === "function") return storage.run(new Box(), boxOrFn);
+	return storage.run(boxOrFn, fn);
+}
+/**
+* Returns the current {@link Box} from the active {@link withBox} scope.
+* Throws if called outside a scope.
+*/
+function useBox() {
+	const box = storage.getStore();
+	if (!box) throw new Error("useBox() must be called within a withBox() scope");
+	return box;
+}
+/**
+* Resolves a cached instance from the current {@link withBox} scope.
+* Shorthand for `useBox().get(constructor)`.
+*/
+function resolve(constructor) {
+	return useBox().get(constructor);
+}
+function resolveAll(constructors) {
+	return useBox().all.get(constructors);
+}
+/**
+* Returns a builder for creating a class instance with resolved constructor
+* parameters from the current {@link withBox} scope. Shorthand for `useBox().for(constructor)`.
+*/
+function construct(constructor) {
+	return useBox().for(constructor);
+}
+
+//#endregion
+export { construct, resolve, resolveAll, useBox, withBox };

package/dist/index.cjs

@@ -1,38 +1,197 @@
 
 //#region src/index.ts
+/**
+* Creates a {@link Constructor} from a factory function.
+* The factory receives the box as an argument, allowing it to resolve other dependencies.
+*
+* @example
+* ```ts
+* const LoggerFactory = factory((box: Box): Logger => {
+*   return new ConsoleLogger();
+* });
+*
+* const logger = box.get(LoggerFactory);
+* ```
+*/
 function factory(init) {
 	return { init };
 }
+const noCacheSymbol = Symbol("Box constant");
+/**
+* Creates a {@link Constructor} from a factory function whose result is never cached.
+* The factory is called on every resolution, always returning a fresh value
+* even when retrieved via {@link Box.get}.
+*
+* @example
+* ```ts
+* const RequestId = transient(() => crypto.randomUUID());
+* const id1 = box.get(RequestId);
+* const id2 = box.get(RequestId);
+* console.log(id1 === id2); // false
+* ```
+*/
+function transient(init) {
+	return {
+		init,
+		[noCacheSymbol]: true
+	};
+}
+/**
+* Creates a {@link Constructor} that always resolves to the given constant value.
+* Constant values are never cached since they are already fixed.
+*
+* @example
+* ```ts
+* const ApiUrl = constant("https://api.example.com");
+* const port = box.get(ApiUrl); // "https://api.example.com"
+* ```
+*/
 function constant(value) {
-	return { init: () => value };
+	return {
+		init: () => value,
+		[noCacheSymbol]: true
+	};
 }
+/**
+* Dependency injection container that resolves and caches instances from
+* a {@link Constructor}.
+*
+* A constructor is an object with an `init(box: Box)` method,
+* a class with a `static init(box: Box)` method, or a class with a
+* no-argument constructor. The {@link factory} and {@link constant} helpers
+* create constructors from functions and values respectively.
+*
+* @example
+* ```ts
+* class Database {
+*   connect() {}
+* }
+*
+* class UserService {
+*   constructor(private db: Database) {}
+*   static init(box: Box) {
+*     return new UserService(box.get(Database));
+*   }
+* }
+*
+* const box = new Box();
+* const service = box.get(UserService);
+* const db = box.get(Database);
+*
+* console.log(service.db === db); // true (cached)
+* console.log(box.new(Database) === db); // false (transient)
+* ```
+*/
 var Box = class {
 	cache = /* @__PURE__ */ new Map();
+	/**
+	* Creates a new (transient) instance without caching. Useful for instances
+	* that should not be shared.
+	*/
 	new(constructor) {
 		return "init" in constructor ? constructor.init(this) : new constructor();
 	}
+	/**
+	* Resolves an instance from the cache, or creates and caches a new one.
+	* Subsequent calls with the same constructor return the cached instance.
+	*/
 	get(constructor) {
 		if (this.cache.has(constructor)) return this.cache.get(constructor);
 		const value = this.new(constructor);
-		this.cache.set(constructor, value);
+		if (!(noCacheSymbol in constructor && constructor[noCacheSymbol])) this.cache.set(constructor, value);
 		return value;
 	}
+	/** Resolves multiple constructors at once. */
+	all = new BoxAll(this);
+	/**
+	* Returns a {@link Construct} builder for creating class instances by
+	* resolving constructors for each constructor parameter.
+	*
+	* Intended to be used inside a class's `static init` method. The instance
+	* returned by the builder is never cached itself, but can be cached when
+	* the class is retrieved via {@link Box.get} or kept transient via {@link Box.new}.
+	*/
 	for(constructor) {
 		return new Construct(this, constructor);
 	}
+	/**
+	* Registers a mock value in the box's cache for a given constructor.
+	* Useful for replacing dependencies in tests.
+	*/
 	static mock(box, constructor, value) {
 		box.cache.set(constructor, value);
 	}
+	/**
+	* Removes the instance from the box's cache for a given constructor.
+	* Removes all instances if no constructor is provided.
+	*/
+	static clear(box, constructor) {
+		if (!constructor) return box.cache.clear();
+		box.cache.delete(constructor);
+	}
+};
+/** Resolves multiple constructors at once from a {@link Box}. */
+var BoxAll = class {
+	constructor(box) {
+		this.box = box;
+	}
+	get(constructors) {
+		if (Array.isArray(constructors)) return constructors.map((c) => this.box.get(c));
+		const result = {};
+		for (const [key, constructor] of Object.entries(constructors)) result[key] = this.box.get(constructor);
+		return result;
+	}
+	new(constructors) {
+		if (Array.isArray(constructors)) return constructors.map((c) => this.box.new(c));
+		const result = {};
+		for (const [key, constructor] of Object.entries(constructors)) result[key] = this.box.new(constructor);
+		return result;
+	}
 };
+/** Builder for creating class instances with constructor dependencies resolved from a {@link Box}. */
 var Construct = class {
 	constructor(box, construct) {
 		this.box = box;
 		this.construct = construct;
 	}
+	/**
+	* Resolves each dependency as a new transient instance via {@link Box.new},
+	* meaning dependencies are not cached or shared.
+	*
+	* The returned instance is cached or transient depending on whether the
+	* class is retrieved via {@link Box.get} or {@link Box.new}.
+	*
+	* @example
+	* ```ts
+	* class UserService {
+	*   constructor(private db: Database, private logger: Logger) {}
+	*   static init(box: Box) {
+	*     return box.for(UserService).new(Database, LoggerFactory);
+	*   }
+	* }
+	* ```
+	*/
 	new(...args) {
 		const instances = args.map((arg) => this.box.new(arg));
 		return new this.construct(...instances);
 	}
+	/**
+	* Resolves each dependency as a cached instance via {@link Box.get},
+	* meaning dependencies are shared across the box.
+	*
+	* The returned instance is cached or transient depending on whether the
+	* class is retrieved via {@link Box.get} or {@link Box.new}.
+	*
+	* @example
+	* ```ts
+	* class UserService {
+	*   constructor(private db: Database, private logger: Logger) {}
+	*   static init(box: Box) {
+	*     return box.for(UserService).get(Database, LoggerFactory);
+	*   }
+	* }
+	* ```
+	*/
 	get(...args) {
 		const instances = args.map((arg) => this.box.get(arg));
 		return new this.construct(...instances);
@@ -41,5 +200,7 @@ var Construct = class {
 
 //#endregion
 exports.Box = Box;
+exports.Construct = Construct;
 exports.constant = constant;
-exports.factory = factory;
+exports.factory = factory;
+exports.transient = transient;

package/dist/index.d.cts

@@ -1,29 +1,183 @@
 //#region src/index.d.ts
+/**
+ * A type that can be resolved by a {@link Box}. Either an object with an
+ * `init(box: Box)` method, a class with a `static init(box: Box)` method
+ * that returns an instance, or a class with a no-argument constructor.
+ */
 type Constructor<T> = {
   init(box: Box): T;
 } | {
   new (): T;
 };
+/** Extracts the instance type from a {@link Constructor}. */
 type ConstructorInstanceType<T> = T extends Constructor<infer U> ? U : never;
+/**
+ * Creates a {@link Constructor} from a factory function.
+ * The factory receives the box as an argument, allowing it to resolve other dependencies.
+ *
+ * @example
+ * ```ts
+ * const LoggerFactory = factory((box: Box): Logger => {
+ *   return new ConsoleLogger();
+ * });
+ *
+ * const logger = box.get(LoggerFactory);
+ * ```
+ */
 declare function factory<T>(init: (box: Box) => T): Constructor<T>;
+/**
+ * Creates a {@link Constructor} from a factory function whose result is never cached.
+ * The factory is called on every resolution, always returning a fresh value
+ * even when retrieved via {@link Box.get}.
+ *
+ * @example
+ * ```ts
+ * const RequestId = transient(() => crypto.randomUUID());
+ * const id1 = box.get(RequestId);
+ * const id2 = box.get(RequestId);
+ * console.log(id1 === id2); // false
+ * ```
+ */
+declare function transient<T>(init: (box: Box) => T): Constructor<T>;
+/**
+ * Creates a {@link Constructor} that always resolves to the given constant value.
+ * Constant values are never cached since they are already fixed.
+ *
+ * @example
+ * ```ts
+ * const ApiUrl = constant("https://api.example.com");
+ * const port = box.get(ApiUrl); // "https://api.example.com"
+ * ```
+ */
 declare function constant<const T>(value: T): Constructor<T>;
+/**
+ * Dependency injection container that resolves and caches instances from
+ * a {@link Constructor}.
+ *
+ * A constructor is an object with an `init(box: Box)` method,
+ * a class with a `static init(box: Box)` method, or a class with a
+ * no-argument constructor. The {@link factory} and {@link constant} helpers
+ * create constructors from functions and values respectively.
+ *
+ * @example
+ * ```ts
+ * class Database {
+ *   connect() {}
+ * }
+ *
+ * class UserService {
+ *   constructor(private db: Database) {}
+ *   static init(box: Box) {
+ *     return new UserService(box.get(Database));
+ *   }
+ * }
+ *
+ * const box = new Box();
+ * const service = box.get(UserService);
+ * const db = box.get(Database);
+ *
+ * console.log(service.db === db); // true (cached)
+ * console.log(box.new(Database) === db); // false (transient)
+ * ```
+ */
 declare class Box {
   private cache;
+  /**
+   * Creates a new (transient) instance without caching. Useful for instances
+   * that should not be shared.
+   */
   new<T>(constructor: Constructor<T>): T;
+  /**
+   * Resolves an instance from the cache, or creates and caches a new one.
+   * Subsequent calls with the same constructor return the cached instance.
+   */
   get<T>(constructor: Constructor<T>): T;
+  /** Resolves multiple constructors at once. */
+  readonly all: BoxAll;
+  /**
+   * Returns a {@link Construct} builder for creating class instances by
+   * resolving constructors for each constructor parameter.
+   *
+   * Intended to be used inside a class's `static init` method. The instance
+   * returned by the builder is never cached itself, but can be cached when
+   * the class is retrieved via {@link Box.get} or kept transient via {@link Box.new}.
+   */
   for<T extends ClassConstructor<any>>(constructor: T): Construct<T>;
+  /**
+   * Registers a mock value in the box's cache for a given constructor.
+   * Useful for replacing dependencies in tests.
+   */
   static mock<T, V extends T = T>(box: Box, constructor: Constructor<T>, value: V): void;
+  /**
+   * Removes the instance from the box's cache for a given constructor.
+   * Removes all instances if no constructor is provided.
+   */
+  static clear<T>(box: Box, constructor?: Constructor<T>): void;
 }
+/** Resolves multiple constructors at once from a {@link Box}. */
+declare class BoxAll {
+  private box;
+  constructor(box: Box);
+  /**
+   * Resolves each constructor as a cached instance via {@link Box.get}.
+   * Accepts an array or object of constructors and returns instances in the same shape.
+   */
+  get<const T extends Constructor<any>[]>(constructors: T): { [K in keyof T]: ConstructorInstanceType<T[K]> };
+  get<T extends Record<string, Constructor<any>>>(constructors: T): { [K in keyof T]: ConstructorInstanceType<T[K]> };
+  /**
+   * Resolves each constructor as a new transient instance via {@link Box.new}.
+   * Accepts an array or object of constructors and returns instances in the same shape.
+   */
+  new<const T extends Constructor<any>[]>(constructors: T): { [K in keyof T]: ConstructorInstanceType<T[K]> };
+  new<T extends Record<string, Constructor<any>>>(constructors: T): { [K in keyof T]: ConstructorInstanceType<T[K]> };
+}
+/** Builder for creating class instances with constructor dependencies resolved from a {@link Box}. */
 declare class Construct<T extends ClassConstructor<any>> {
   private box;
   private construct;
   constructor(box: Box, construct: T);
+  /**
+   * Resolves each dependency as a new transient instance via {@link Box.new},
+   * meaning dependencies are not cached or shared.
+   *
+   * The returned instance is cached or transient depending on whether the
+   * class is retrieved via {@link Box.get} or {@link Box.new}.
+   *
+   * @example
+   * ```ts
+   * class UserService {
+   *   constructor(private db: Database, private logger: Logger) {}
+   *   static init(box: Box) {
+   *     return box.for(UserService).new(Database, LoggerFactory);
+   *   }
+   * }
+   * ```
+   */
   new(...args: ClassConstructorArgs<T>): InstanceType<T>;
+  /**
+   * Resolves each dependency as a cached instance via {@link Box.get},
+   * meaning dependencies are shared across the box.
+   *
+   * The returned instance is cached or transient depending on whether the
+   * class is retrieved via {@link Box.get} or {@link Box.new}.
+   *
+   * @example
+   * ```ts
+   * class UserService {
+   *   constructor(private db: Database, private logger: Logger) {}
+   *   static init(box: Box) {
+   *     return box.for(UserService).get(Database, LoggerFactory);
+   *   }
+   * }
+   * ```
+   */
   get(...args: ClassConstructorArgs<T>): InstanceType<T>;
 }
+/** A class with any constructor signature. */
 type ClassConstructor<T> = {
   new (...args: any): T;
 };
+/** Maps each constructor parameter to its corresponding {@link Constructor} type. */
 type ClassConstructorArgs<T extends ClassConstructor<any>, Args = ConstructorParameters<T>> = { [K in keyof Args]: Constructor<Args[K]> };
 //#endregion
-export { Box, Constructor, ConstructorInstanceType, constant, factory };
+export { Box, Construct, Constructor, ConstructorInstanceType, constant, factory, transient };

package/dist/index.d.mts

@@ -1,29 +1,183 @@
 //#region src/index.d.ts
+/**
+ * A type that can be resolved by a {@link Box}. Either an object with an
+ * `init(box: Box)` method, a class with a `static init(box: Box)` method
+ * that returns an instance, or a class with a no-argument constructor.
+ */
 type Constructor<T> = {
   init(box: Box): T;
 } | {
   new (): T;
 };
+/** Extracts the instance type from a {@link Constructor}. */
 type ConstructorInstanceType<T> = T extends Constructor<infer U> ? U : never;
+/**
+ * Creates a {@link Constructor} from a factory function.
+ * The factory receives the box as an argument, allowing it to resolve other dependencies.
+ *
+ * @example
+ * ```ts
+ * const LoggerFactory = factory((box: Box): Logger => {
+ *   return new ConsoleLogger();
+ * });
+ *
+ * const logger = box.get(LoggerFactory);
+ * ```
+ */
 declare function factory<T>(init: (box: Box) => T): Constructor<T>;
+/**
+ * Creates a {@link Constructor} from a factory function whose result is never cached.
+ * The factory is called on every resolution, always returning a fresh value
+ * even when retrieved via {@link Box.get}.
+ *
+ * @example
+ * ```ts
+ * const RequestId = transient(() => crypto.randomUUID());
+ * const id1 = box.get(RequestId);
+ * const id2 = box.get(RequestId);
+ * console.log(id1 === id2); // false
+ * ```
+ */
+declare function transient<T>(init: (box: Box) => T): Constructor<T>;
+/**
+ * Creates a {@link Constructor} that always resolves to the given constant value.
+ * Constant values are never cached since they are already fixed.
+ *
+ * @example
+ * ```ts
+ * const ApiUrl = constant("https://api.example.com");
+ * const port = box.get(ApiUrl); // "https://api.example.com"
+ * ```
+ */
 declare function constant<const T>(value: T): Constructor<T>;
+/**
+ * Dependency injection container that resolves and caches instances from
+ * a {@link Constructor}.
+ *
+ * A constructor is an object with an `init(box: Box)` method,
+ * a class with a `static init(box: Box)` method, or a class with a
+ * no-argument constructor. The {@link factory} and {@link constant} helpers
+ * create constructors from functions and values respectively.
+ *
+ * @example
+ * ```ts
+ * class Database {
+ *   connect() {}
+ * }
+ *
+ * class UserService {
+ *   constructor(private db: Database) {}
+ *   static init(box: Box) {
+ *     return new UserService(box.get(Database));
+ *   }
+ * }
+ *
+ * const box = new Box();
+ * const service = box.get(UserService);
+ * const db = box.get(Database);
+ *
+ * console.log(service.db === db); // true (cached)
+ * console.log(box.new(Database) === db); // false (transient)
+ * ```
+ */
 declare class Box {
   private cache;
+  /**
+   * Creates a new (transient) instance without caching. Useful for instances
+   * that should not be shared.
+   */
   new<T>(constructor: Constructor<T>): T;
+  /**
+   * Resolves an instance from the cache, or creates and caches a new one.
+   * Subsequent calls with the same constructor return the cached instance.
+   */
   get<T>(constructor: Constructor<T>): T;
+  /** Resolves multiple constructors at once. */
+  readonly all: BoxAll;
+  /**
+   * Returns a {@link Construct} builder for creating class instances by
+   * resolving constructors for each constructor parameter.
+   *
+   * Intended to be used inside a class's `static init` method. The instance
+   * returned by the builder is never cached itself, but can be cached when
+   * the class is retrieved via {@link Box.get} or kept transient via {@link Box.new}.
+   */
   for<T extends ClassConstructor<any>>(constructor: T): Construct<T>;
+  /**
+   * Registers a mock value in the box's cache for a given constructor.
+   * Useful for replacing dependencies in tests.
+   */
   static mock<T, V extends T = T>(box: Box, constructor: Constructor<T>, value: V): void;
+  /**
+   * Removes the instance from the box's cache for a given constructor.
+   * Removes all instances if no constructor is provided.
+   */
+  static clear<T>(box: Box, constructor?: Constructor<T>): void;
 }
+/** Resolves multiple constructors at once from a {@link Box}. */
+declare class BoxAll {
+  private box;
+  constructor(box: Box);
+  /**
+   * Resolves each constructor as a cached instance via {@link Box.get}.
+   * Accepts an array or object of constructors and returns instances in the same shape.
+   */
+  get<const T extends Constructor<any>[]>(constructors: T): { [K in keyof T]: ConstructorInstanceType<T[K]> };
+  get<T extends Record<string, Constructor<any>>>(constructors: T): { [K in keyof T]: ConstructorInstanceType<T[K]> };
+  /**
+   * Resolves each constructor as a new transient instance via {@link Box.new}.
+   * Accepts an array or object of constructors and returns instances in the same shape.
+   */
+  new<const T extends Constructor<any>[]>(constructors: T): { [K in keyof T]: ConstructorInstanceType<T[K]> };
+  new<T extends Record<string, Constructor<any>>>(constructors: T): { [K in keyof T]: ConstructorInstanceType<T[K]> };
+}
+/** Builder for creating class instances with constructor dependencies resolved from a {@link Box}. */
 declare class Construct<T extends ClassConstructor<any>> {
   private box;
   private construct;
   constructor(box: Box, construct: T);
+  /**
+   * Resolves each dependency as a new transient instance via {@link Box.new},
+   * meaning dependencies are not cached or shared.
+   *
+   * The returned instance is cached or transient depending on whether the
+   * class is retrieved via {@link Box.get} or {@link Box.new}.
+   *
+   * @example
+   * ```ts
+   * class UserService {
+   *   constructor(private db: Database, private logger: Logger) {}
+   *   static init(box: Box) {
+   *     return box.for(UserService).new(Database, LoggerFactory);
+   *   }
+   * }
+   * ```
+   */
   new(...args: ClassConstructorArgs<T>): InstanceType<T>;
+  /**
+   * Resolves each dependency as a cached instance via {@link Box.get},
+   * meaning dependencies are shared across the box.
+   *
+   * The returned instance is cached or transient depending on whether the
+   * class is retrieved via {@link Box.get} or {@link Box.new}.
+   *
+   * @example
+   * ```ts
+   * class UserService {
+   *   constructor(private db: Database, private logger: Logger) {}
+   *   static init(box: Box) {
+   *     return box.for(UserService).get(Database, LoggerFactory);
+   *   }
+   * }
+   * ```
+   */
   get(...args: ClassConstructorArgs<T>): InstanceType<T>;
 }
+/** A class with any constructor signature. */
 type ClassConstructor<T> = {
   new (...args: any): T;
 };
+/** Maps each constructor parameter to its corresponding {@link Constructor} type. */
 type ClassConstructorArgs<T extends ClassConstructor<any>, Args = ConstructorParameters<T>> = { [K in keyof Args]: Constructor<Args[K]> };
 //#endregion
-export { Box, Constructor, ConstructorInstanceType, constant, factory };
+export { Box, Construct, Constructor, ConstructorInstanceType, constant, factory, transient };

package/dist/index.mjs

@@ -1,37 +1,196 @@
 //#region src/index.ts
+/**
+* Creates a {@link Constructor} from a factory function.
+* The factory receives the box as an argument, allowing it to resolve other dependencies.
+*
+* @example
+* ```ts
+* const LoggerFactory = factory((box: Box): Logger => {
+*   return new ConsoleLogger();
+* });
+*
+* const logger = box.get(LoggerFactory);
+* ```
+*/
 function factory(init) {
 	return { init };
 }
+const noCacheSymbol = Symbol("Box constant");
+/**
+* Creates a {@link Constructor} from a factory function whose result is never cached.
+* The factory is called on every resolution, always returning a fresh value
+* even when retrieved via {@link Box.get}.
+*
+* @example
+* ```ts
+* const RequestId = transient(() => crypto.randomUUID());
+* const id1 = box.get(RequestId);
+* const id2 = box.get(RequestId);
+* console.log(id1 === id2); // false
+* ```
+*/
+function transient(init) {
+	return {
+		init,
+		[noCacheSymbol]: true
+	};
+}
+/**
+* Creates a {@link Constructor} that always resolves to the given constant value.
+* Constant values are never cached since they are already fixed.
+*
+* @example
+* ```ts
+* const ApiUrl = constant("https://api.example.com");
+* const port = box.get(ApiUrl); // "https://api.example.com"
+* ```
+*/
 function constant(value) {
-	return { init: () => value };
+	return {
+		init: () => value,
+		[noCacheSymbol]: true
+	};
 }
+/**
+* Dependency injection container that resolves and caches instances from
+* a {@link Constructor}.
+*
+* A constructor is an object with an `init(box: Box)` method,
+* a class with a `static init(box: Box)` method, or a class with a
+* no-argument constructor. The {@link factory} and {@link constant} helpers
+* create constructors from functions and values respectively.
+*
+* @example
+* ```ts
+* class Database {
+*   connect() {}
+* }
+*
+* class UserService {
+*   constructor(private db: Database) {}
+*   static init(box: Box) {
+*     return new UserService(box.get(Database));
+*   }
+* }
+*
+* const box = new Box();
+* const service = box.get(UserService);
+* const db = box.get(Database);
+*
+* console.log(service.db === db); // true (cached)
+* console.log(box.new(Database) === db); // false (transient)
+* ```
+*/
 var Box = class {
 	cache = /* @__PURE__ */ new Map();
+	/**
+	* Creates a new (transient) instance without caching. Useful for instances
+	* that should not be shared.
+	*/
 	new(constructor) {
 		return "init" in constructor ? constructor.init(this) : new constructor();
 	}
+	/**
+	* Resolves an instance from the cache, or creates and caches a new one.
+	* Subsequent calls with the same constructor return the cached instance.
+	*/
 	get(constructor) {
 		if (this.cache.has(constructor)) return this.cache.get(constructor);
 		const value = this.new(constructor);
-		this.cache.set(constructor, value);
+		if (!(noCacheSymbol in constructor && constructor[noCacheSymbol])) this.cache.set(constructor, value);
 		return value;
 	}
+	/** Resolves multiple constructors at once. */
+	all = new BoxAll(this);
+	/**
+	* Returns a {@link Construct} builder for creating class instances by
+	* resolving constructors for each constructor parameter.
+	*
+	* Intended to be used inside a class's `static init` method. The instance
+	* returned by the builder is never cached itself, but can be cached when
+	* the class is retrieved via {@link Box.get} or kept transient via {@link Box.new}.
+	*/
 	for(constructor) {
 		return new Construct(this, constructor);
 	}
+	/**
+	* Registers a mock value in the box's cache for a given constructor.
+	* Useful for replacing dependencies in tests.
+	*/
 	static mock(box, constructor, value) {
 		box.cache.set(constructor, value);
 	}
+	/**
+	* Removes the instance from the box's cache for a given constructor.
+	* Removes all instances if no constructor is provided.
+	*/
+	static clear(box, constructor) {
+		if (!constructor) return box.cache.clear();
+		box.cache.delete(constructor);
+	}
+};
+/** Resolves multiple constructors at once from a {@link Box}. */
+var BoxAll = class {
+	constructor(box) {
+		this.box = box;
+	}
+	get(constructors) {
+		if (Array.isArray(constructors)) return constructors.map((c) => this.box.get(c));
+		const result = {};
+		for (const [key, constructor] of Object.entries(constructors)) result[key] = this.box.get(constructor);
+		return result;
+	}
+	new(constructors) {
+		if (Array.isArray(constructors)) return constructors.map((c) => this.box.new(c));
+		const result = {};
+		for (const [key, constructor] of Object.entries(constructors)) result[key] = this.box.new(constructor);
+		return result;
+	}
 };
+/** Builder for creating class instances with constructor dependencies resolved from a {@link Box}. */
 var Construct = class {
 	constructor(box, construct) {
 		this.box = box;
 		this.construct = construct;
 	}
+	/**
+	* Resolves each dependency as a new transient instance via {@link Box.new},
+	* meaning dependencies are not cached or shared.
+	*
+	* The returned instance is cached or transient depending on whether the
+	* class is retrieved via {@link Box.get} or {@link Box.new}.
+	*
+	* @example
+	* ```ts
+	* class UserService {
+	*   constructor(private db: Database, private logger: Logger) {}
+	*   static init(box: Box) {
+	*     return box.for(UserService).new(Database, LoggerFactory);
+	*   }
+	* }
+	* ```
+	*/
 	new(...args) {
 		const instances = args.map((arg) => this.box.new(arg));
 		return new this.construct(...instances);
 	}
+	/**
+	* Resolves each dependency as a cached instance via {@link Box.get},
+	* meaning dependencies are shared across the box.
+	*
+	* The returned instance is cached or transient depending on whether the
+	* class is retrieved via {@link Box.get} or {@link Box.new}.
+	*
+	* @example
+	* ```ts
+	* class UserService {
+	*   constructor(private db: Database, private logger: Logger) {}
+	*   static init(box: Box) {
+	*     return box.for(UserService).get(Database, LoggerFactory);
+	*   }
+	* }
+	* ```
+	*/
 	get(...args) {
 		const instances = args.map((arg) => this.box.get(arg));
 		return new this.construct(...instances);
@@ -39,4 +198,4 @@ var Construct = class {
 };
 
 //#endregion
-export { Box, constant, factory };
+export { Box, Construct, constant, factory, transient };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "getbox",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "Lightweight dependency injection for TypeScript",
   "private": false,
   "main": "./dist/index.cjs",
@@ -16,15 +16,18 @@
         "types": "./dist/index.d.cts",
         "default": "./dist/index.cjs"
       }
+    },
+    "./context": {
+      "import": {
+        "types": "./dist/context.d.mts",
+        "default": "./dist/context.mjs"
+      },
+      "require": {
+        "types": "./dist/context.d.cts",
+        "default": "./dist/context.cjs"
+      }
     }
   },
-  "scripts": {
-    "build": "tsc && tsdown src/index.ts --format esm,cjs",
-    "release": "pnpm run build && changeset publish",
-    "watch": "vitest",
-    "test": "vitest run",
-    "test:coverage": "vitest run --coverage"
-  },
   "keywords": [
     "DI",
     "dependency injection",
@@ -44,9 +47,17 @@
   "homepage": "https://github.com/eriicafes/getbox#readme",
   "devDependencies": {
     "@changesets/cli": "^2.29.8",
+    "@types/node": "^25.2.3",
     "@vitest/coverage-v8": "^4.0.16",
     "tsdown": "^0.18.3",
     "typescript": "^5.9.3",
     "vitest": "^4.0.16"
+  },
+  "scripts": {
+    "build": "tsc && tsdown src/index.ts src/context.ts --format esm,cjs",
+    "release": "pnpm run build && changeset publish",
+    "watch": "vitest",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage"
   }
-}
+}