getbox 1.3.1 → 1.4.0

package/CONTEXT.md

@@ -11,8 +11,8 @@ import { withBox } from "getbox/context";
 
 withBox(() => {
   // All code in this scope can resolve dependencies
-  const app = resolve(App);
-  app.start();
+  const service = inject(UserService);
+  service.createUser("Alice");
 });
 ```
 
@@ -23,24 +23,24 @@ import { Box } from "getbox";
 import { withBox } from "getbox/context";
 
 const box = new Box();
-Box.mock(box, LoggerFactory, new TestLogger());
+Box.mock(box, LoggerFactory, new MockLogger());
 
 withBox(box, () => {
-  const app = resolve(App);
-  app.start();
+  const service = inject(UserService);
+  service.createUser("Alice");
 });
 ```
 
 ## Resolving dependencies
 
-With the context pattern, classes can use `resolve` directly as field initializers. No `static init` method is needed.
+With the context pattern, classes can use `inject` directly as field initializers. No `static init` property is needed.
 
 ```ts
-import { resolve } from "getbox/context";
+import { inject } from "getbox/context";
 
 class UserService {
-  public db = resolve(Database);
-  public logger = resolve(LoggerFactory);
+  public db = inject(Database);
+  public logger = inject(LoggerFactory);
 
   createUser(name: string) {
     this.logger.log(`Creating user: ${name}`);
@@ -63,36 +63,21 @@ class UserService {
 
 ## Resolving multiple dependencies
 
-Use `resolveAll` to resolve multiple constructors at once. Accepts an object or array of constructors.
+Use `injectAll` 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 });
+  const { db, logger } = injectAll({ db: Database, logger: LoggerFactory });
 
   // Array form
-  const [db2, logger2] = resolveAll([Database, LoggerFactory]);
+  const [db2, logger2] = injectAll([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.
@@ -110,11 +95,11 @@ Each `withBox` call creates an independent scope. Nested scopes do not share the
 
 ```ts
 withBox(() => {
-  const db = resolve(Database);
+  const db = inject(Database);
 
-  // Inner scope gets a fresh box
+  // Inner scope gets a new box
   withBox(() => {
-    const db2 = resolve(Database);
+    const db2 = inject(Database);
     console.log(db === db2); // false (different scope)
   });
 });

package/README.md

@@ -2,9 +2,9 @@
 
 ### Lightweight dependency injection for TypeScript.
 
-`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.
+`getbox` is a lightweight inversion of control container for TypeScript. Constructors declare their own dependencies, keeping instantiation logic colocated with the type that owns it.
 
-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.
+Callers depend on types, not implementations. The box resolves and caches instances automatically on first use.
 
 ## Installation
 
@@ -16,252 +16,204 @@ npm install getbox
 
 `getbox` has a very small API surface. You typically only need `box.get()` and optionally `static init` or the `factory` helper.
 
-For an alternative pattern using AsyncLocalStorage where classes can resolve dependencies directly in their constructors, see [getbox/context](./CONTEXT.md).
+For an alternative pattern using AsyncLocalStorage where classes can resolve dependencies directly, see [getbox/context](./CONTEXT.md).
 
-### Create a class
+### Quick start
 
-Classes are instantiated once and cached. Subsequent calls return the cached instance.
+Create a `Box` instance and call `box.get()` to resolve instances. The box automatically resolves dependencies and caches every instance, so shared dependencies always point to the same reference.
 
 ```ts
-// printer.ts
-export class Printer {
-  print(text: string): string {
+import { Box } from "getbox";
+
+class Printer {
+  print(text: string) {
     return text.toUpperCase();
   }
 }
-```
-
-### Use in another class
-
-The `static init` property tells the box what dependencies to pass when instantiating the class.
 
-```ts
-// office.ts
-import { Box } from "getbox";
-import { Printer } from "./printer";
-
-export class Office {
+class Office {
   constructor(public printer: Printer) {}
 
   static init = Box.init(Office).get(Printer);
 }
-```
-
-### Use in application
-
-Create a Box instance to hold cached instances.
-
-When initializing a class, any dependencies it has will also be cached, ensuring that shared dependencies use the same instance.
-
-```ts
-// main.ts
-import { Box } from "getbox";
-import { Office } from "./office";
-import { Printer } from "./printer";
 
 const box = new Box();
 
 const office = box.get(Office);
 office.printer.print("hello world");
 
-// Instances are cached and shared
+// Dependencies are cached and shared
 const printer = box.get(Printer);
 console.log(office.printer === printer); // true
 ```
 
-## Transient instances
+## Constructors
+
+Constructors define what the box resolves. `getbox` supports classes, factories, derived values, and constants. Because constructors act as interfaces, the underlying implementation can change without affecting any consumer.
+
+### Classes
 
-Use `box.new()` to create a new instance each time without caching. This is useful for instances that should not be shared.
+Define a `static init` property to allow the box to resolve classes that have constructor parameters. Classes with no parameters do not require it.
 
 ```ts
-// main.ts
 import { Box } from "getbox";
 
-class Database {
-  connect() {
-    /* ... */
+class UserService {
+  constructor(private db: Database, private logger: Logger) {}
+
+  static init = Box.init(UserService).get(Database, LoggerFactory);
+
+  createUser(name: string) {
+    this.logger.log(`Creating user: ${name}`);
   }
 }
 
 const box = new Box();
-
-const db1 = box.new(Database);
-const db2 = box.new(Database);
-
-console.log(db1 === db2); // false
+const service = box.get(UserService);
+service.createUser("Alice");
 ```
 
-## Factory functions
-
-Use the `factory` helper to create function-based constructors instead of classes. Factories work well with interfaces for better abstraction.
+`Box.init` is shorthand for writing the `static init` property yourself.
 
 ```ts
-// logger.ts
-import { Box, factory } from "getbox";
+class UserService {
+  constructor(private db: Database, private logger: Logger) {}
 
-export interface Logger {
-  log(message: string): void;
+  static init(box: Box) {
+    return new UserService(box.get(Database), box.get(LoggerFactory));
+  }
 }
-
-const LoggerFactory = factory((box: Box): Logger => {
-  return {
-    log(message: string): void {
-      console.log(`[LOG] ${message}`);
-    },
-  };
-});
 ```
 
-```ts
-// service.ts
-import { Box } from "getbox";
-import { Logger, LoggerFactory } from "./logger";
-
-export class UserService {
-  constructor(private logger: Logger) {}
+Use `box.for()` when you need custom logic alongside dependency resolution.
 
-  static init = Box.init(UserService).get(LoggerFactory);
+```ts
+class UserService {
+  constructor(private db: Database, private logger: Logger) {}
 
-  createUser(name: string) {
-    this.logger.log(`Creating user: ${name}`);
+  static init(box: Box) {
+    const logger = box.get(LoggerFactory);
+    logger.log("Initializing UserService");
+    return box.for(UserService).get(Database, LoggerFactory);
   }
 }
 ```
 
-## Constants
-
-Use the `constant` helper to register constant values without needing a factory or class. Constant values are never cached since they are already fixed.
+If `static init` is defined, it takes priority over the class constructor.
 
-```ts
-import { Box, constant } from "getbox";
-
-const ApiUrl = constant("https://api.example.com");
-const Port = constant(3000);
-const Config = constant({
-  baseUrl: "https://example.com",
-  timeout: 5000,
-});
+### Factory functions
 
-const box = new Box();
+Use the `factory` helper to create function-based constructors instead of classes. Factories work well with interfaces for better abstraction.
 
-const apiUrl = box.get(ApiUrl);
-const port = box.get(Port);
-const config = box.get(Config);
+```ts
+import { Box, factory } from "getbox";
 
-console.log(apiUrl); // "https://api.example.com"
-console.log(port); // 3000
-console.log(config.timeout); // 5000
-```
+interface Logger {
+  log(message: string): void;
+}
 
-Since constructors act as interfaces, a `constant` can later be replaced with a `factory` without changing any callers.
+const LoggerFactory = factory(
+  (): Logger => ({
+    log(message: string) {
+      console.log(`[LOG] ${message}`);
+    },
+  }),
+);
 
-```ts
-const ApiUrl = factory((box: Box) => {
-  const config = box.get(Config);
-  return `${config.baseUrl}/api`;
-});
+const box = new Box();
+const logger = box.get(LoggerFactory);
 
-const apiUrl = box.get(ApiUrl); // "https://example.com/api"
+logger.log("hello world");
 ```
 
-## Transient factories
+### Derived values
 
-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()`.
+Use the `derive` helper to compute a value from the box without caching the result.
 
 ```ts
-import { Box, transient } from "getbox";
+import { Box, derive } from "getbox";
 
-const RequestId = transient(() => crypto.randomUUID());
+class Config {
+  baseUrl = "https://example.com";
+}
+
+const RequestContext = derive((box) => ({
+  baseUrl: box.get(Config).baseUrl,
+  timestamp: Date.now(),
+}));
 
 const box = new Box();
 
-const id1 = box.get(RequestId);
-const id2 = box.get(RequestId);
+const ctx1 = box.get(RequestContext);
+const ctx2 = box.get(RequestContext);
 
-console.log(id1 === id2); // false
+console.log(ctx1 === ctx2); // false
 ```
 
-## Resolving multiple constructors
+### Constants
 
-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.
+Use the `constant` helper to wrap a fixed value as a constructor. Constant values are never cached and always return the same stable reference.
 
 ```ts
-import { Box } from "getbox";
-
-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)
-```
+import { Box, constant } from "getbox";
 
-Use `box.all.new()` to resolve multiple constructors as transient instances.
+const ApiUrl = constant("https://api.example.com");
+const Port = constant(3000);
+const Config = constant({
+  baseUrl: "https://example.com",
+  timeout: 5000,
+});
 
-```ts
-const { db } = box.all.new({ db: Database });
-const [db2] = box.all.new([Database]);
+const box = new Box();
 
-console.log(db === db2); // false (transient)
+console.log(box.get(ApiUrl)); // "https://api.example.com"
+console.log(box.get(Port)); // 3000
+console.log(box.get(Config).timeout); // 5000
 ```
 
-## Class constructors
+## Resolving instances
 
-Use `Box.init` to allow resolving classes that have constructor parameters.
+Use `box.get()` to resolve a cached instance. The box resolves the constructor on first call and returns the same instance on every subsequent call. Use `box.new()` to always get a new instance without caching.
 
 ```ts
 import { Box } from "getbox";
 
-class UserService {
-  constructor(private db: Database, private logger: Logger) {}
-
-  static init = Box.init(UserService).get(Database, LoggerFactory);
-
-  createUser(name: string) {
-    this.logger.log(`Creating user: ${name}`);
+class Database {
+  connect() {
+    /* ... */
   }
 }
 
 const box = new Box();
-const service = box.get(UserService);
-service.createUser("Alice");
-```
-
-`Box.init` is shorthand for writing the `static init` method yourself.
 
-```ts
-class UserService {
-  constructor(private db: Database, private logger: Logger) {}
+const db1 = box.get(Database);
+const db2 = box.get(Database);
+console.log(db1 === db2); // true (cached)
 
-  static init(box: Box) {
-    return new UserService(box.get(Database), box.get(LoggerFactory));
-  }
-}
+const db3 = box.new(Database);
+const db4 = box.new(Database);
+console.log(db3 === db4); // false (never cached)
 ```
 
-Use `box.for()` when you need custom logic alongside dependency resolution.
+Use `box.all.get()` or `box.all.new()` to resolve multiple constructors at once. Pass an array to get an array of instances, or an object to get an object of instances.
 
 ```ts
-class UserService {
-  constructor(private db: Database, private logger: Logger) {}
+const box = new Box();
 
-  static init(box: Box) {
-    const logger = box.get(LoggerFactory);
-    logger.log("Initializing UserService");
-    return box.for(UserService).get(Database, LoggerFactory);
-  }
-}
+// Cached
+const { db, logger } = box.all.get({ db: Database, logger: LoggerFactory });
+const [db2, logger2] = box.all.get([Database, LoggerFactory]);
+
+// New instances
+const { db3 } = box.all.new({ db3: Database });
+const [db4] = box.all.new([Database]);
 ```
 
-Classes with no constructor parameters are resolved automatically without needing `static init`. If `static init` is defined, it takes priority over the default constructor.
+> `box.get()` does not cache `derive` or `constant` values.
 
 ## Mocking
 
-You can mock dependencies for testing using `Box.mock`. This is particularly useful with factories and interfaces.
+You can mock dependencies for testing using `Box.mock`.
 
 ```ts
 // service.test.ts
@@ -306,7 +258,7 @@ Box.clear(box);
 
 ## Circular dependencies
 
-`getbox` does not prevent circular dependencies. You should structure your code to avoid circular imports between modules.
+`getbox` does not prevent circular dependencies. You should structure your code to avoid them.
 
 ## License
 

package/dist/context.cjs

@@ -20,15 +20,26 @@ function useBox() {
 * Resolves a cached instance from the current {@link withBox} scope.
 * Shorthand for `useBox().get(constructor)`.
 */
-function resolve(constructor) {
+function inject(constructor) {
 	return useBox().get(constructor);
 }
-function resolveAll(constructors) {
+/**
+* @deprecated Use {@link inject} instead.
+*/
+function resolve(constructor) {
+	return inject(constructor);
+}
+function injectAll(constructors) {
 	return useBox().all.get(constructors);
 }
+function resolveAll(constructors) {
+	return injectAll(constructors);
+}
 /**
 * Returns a builder for creating a class instance with resolved constructor
 * parameters from the current {@link withBox} scope. Shorthand for `useBox().for(constructor)`.
+*
+* @deprecated
 */
 function construct(constructor) {
 	return useBox().for(constructor);
@@ -36,6 +47,8 @@ function construct(constructor) {
 
 //#endregion
 exports.construct = construct;
+exports.inject = inject;
+exports.injectAll = injectAll;
 exports.resolve = resolve;
 exports.resolveAll = resolveAll;
 exports.useBox = useBox;

package/dist/context.d.cts

@@ -4,7 +4,7 @@ import { Box, Construct, Constructor, ConstructorInstanceType } from "./index.cj
 
 /**
  * Runs a function within a scoped {@link Box} context using AsyncLocalStorage.
- * Creates a fresh Box if none is provided.
+ * Creates a new Box if none is provided.
  */
 declare function withBox<T>(fn: () => T): T;
 declare function withBox<T>(box: Box, fn: () => T): T;
@@ -17,17 +17,28 @@ declare function useBox(): Box;
  * Resolves a cached instance from the current {@link withBox} scope.
  * Shorthand for `useBox().get(constructor)`.
  */
+declare function inject<T extends Constructor<any>>(constructor: T): ConstructorInstanceType<T>;
+/**
+ * @deprecated Use {@link inject} instead.
+ */
 declare function resolve<T extends Constructor<any>>(constructor: T): ConstructorInstanceType<T>;
 /**
  * Resolves multiple cached instances from the current {@link withBox} scope.
  * Shorthand for `useBox().all.get(constructors)`.
  */
+declare function injectAll<const T extends Constructor<any>[]>(constructors: T): { [K in keyof T]: ConstructorInstanceType<T[K]> };
+declare function injectAll<T extends Record<string, Constructor<any>>>(constructors: T): { [K in keyof T]: ConstructorInstanceType<T[K]> };
+/**
+ * @deprecated Use {@link injectAll} instead.
+ */
 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)`.
+ *
+ * @deprecated
  */
 declare function construct<T extends new (...args: any) => any>(constructor: T): Construct<T>;
 //#endregion
-export { construct, resolve, resolveAll, useBox, withBox };
+export { construct, inject, injectAll, resolve, resolveAll, useBox, withBox };

package/dist/context.d.mts

@@ -4,7 +4,7 @@ import { Box, Construct, Constructor, ConstructorInstanceType } from "./index.mj
 
 /**
  * Runs a function within a scoped {@link Box} context using AsyncLocalStorage.
- * Creates a fresh Box if none is provided.
+ * Creates a new Box if none is provided.
  */
 declare function withBox<T>(fn: () => T): T;
 declare function withBox<T>(box: Box, fn: () => T): T;
@@ -17,17 +17,28 @@ declare function useBox(): Box;
  * Resolves a cached instance from the current {@link withBox} scope.
  * Shorthand for `useBox().get(constructor)`.
  */
+declare function inject<T extends Constructor<any>>(constructor: T): ConstructorInstanceType<T>;
+/**
+ * @deprecated Use {@link inject} instead.
+ */
 declare function resolve<T extends Constructor<any>>(constructor: T): ConstructorInstanceType<T>;
 /**
  * Resolves multiple cached instances from the current {@link withBox} scope.
  * Shorthand for `useBox().all.get(constructors)`.
  */
+declare function injectAll<const T extends Constructor<any>[]>(constructors: T): { [K in keyof T]: ConstructorInstanceType<T[K]> };
+declare function injectAll<T extends Record<string, Constructor<any>>>(constructors: T): { [K in keyof T]: ConstructorInstanceType<T[K]> };
+/**
+ * @deprecated Use {@link injectAll} instead.
+ */
 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)`.
+ *
+ * @deprecated
  */
 declare function construct<T extends new (...args: any) => any>(constructor: T): Construct<T>;
 //#endregion
-export { construct, resolve, resolveAll, useBox, withBox };
+export { construct, inject, injectAll, resolve, resolveAll, useBox, withBox };

package/dist/context.mjs

@@ -20,19 +20,30 @@ function useBox() {
 * Resolves a cached instance from the current {@link withBox} scope.
 * Shorthand for `useBox().get(constructor)`.
 */
-function resolve(constructor) {
+function inject(constructor) {
 	return useBox().get(constructor);
 }
-function resolveAll(constructors) {
+/**
+* @deprecated Use {@link inject} instead.
+*/
+function resolve(constructor) {
+	return inject(constructor);
+}
+function injectAll(constructors) {
 	return useBox().all.get(constructors);
 }
+function resolveAll(constructors) {
+	return injectAll(constructors);
+}
 /**
 * Returns a builder for creating a class instance with resolved constructor
 * parameters from the current {@link withBox} scope. Shorthand for `useBox().for(constructor)`.
+*
+* @deprecated
 */
 function construct(constructor) {
 	return useBox().for(constructor);
 }
 
 //#endregion
-export { construct, resolve, resolveAll, useBox, withBox };
+export { construct, inject, injectAll, resolve, resolveAll, useBox, withBox };

package/dist/index.cjs

@@ -18,25 +18,37 @@ function factory(init) {
 }
 const noCacheSymbol = Symbol("Box.noCache");
 /**
-* 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}.
+* Creates a {@link Constructor} that computes a value from the box without caching the result.
 *
 * @example
 * ```ts
-* const RequestId = transient(() => crypto.randomUUID());
-* const id1 = box.get(RequestId);
-* const id2 = box.get(RequestId);
-* console.log(id1 === id2); // false
+* class Config {
+*   baseUrl = "https://example.com";
+* }
+*
+* const RequestContext = derive((box) => ({
+*   baseUrl: box.get(Config).baseUrl,
+*   timestamp: Date.now(),
+* }));
+*
+* const ctx1 = box.get(RequestContext);
+* const ctx2 = box.get(RequestContext);
+* console.log(ctx1 === ctx2); // false
 * ```
 */
-function transient(init) {
+function derive(init) {
 	return {
 		init,
 		[noCacheSymbol]: true
 	};
 }
 /**
+* @deprecated Use {@link derive} instead.
+*/
+function transient(init) {
+	return derive(init);
+}
+/**
 * Creates a {@link Constructor} that always resolves to the given constant value.
 * Constant values are never cached since they are already fixed.
 *
@@ -69,9 +81,7 @@ function constant(value) {
 *
 * class UserService {
 *   constructor(private db: Database) {}
-*   static init(box: Box) {
-*     return new UserService(box.get(Database));
-*   }
+*   static init = Box.init(UserService).get(Database);
 * }
 *
 * const box = new Box();
@@ -79,14 +89,12 @@ function constant(value) {
 * 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.
+	* Creates a new instance without caching.
 	*/
 	new(constructor) {
 		return "init" in constructor ? constructor.init(this) : new constructor();
@@ -109,7 +117,7 @@ var Box = class {
 	*
 	* 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}.
+	* the class is retrieved via {@link Box.get} or new via {@link Box.new}.
 	*/
 	for(constructor) {
 		return new Construct(this, constructor);
@@ -150,18 +158,18 @@ 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;
 	}
+	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;
+	}
 };
 /** Builder for creating class instances with constructor dependencies resolved from a {@link Box}. */
 var Construct = class {
@@ -170,10 +178,10 @@ var Construct = class {
 		this.construct = construct;
 	}
 	/**
-	* Resolves each dependency as a new transient instance via {@link Box.new},
+	* Resolves each dependency as a new instance via {@link Box.new},
 	* meaning dependencies are not cached or shared.
 	*
-	* The returned instance is cached or transient depending on whether the
+	* The returned instance is cached or new depending on whether the
 	* class is retrieved via {@link Box.get} or {@link Box.new}.
 	*
 	* @example
@@ -194,7 +202,7 @@ var Construct = class {
 	* 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
+	* The returned instance is cached or new depending on whether the
 	* class is retrieved via {@link Box.get} or {@link Box.new}.
 	*
 	* @example
@@ -221,11 +229,11 @@ var StaticConstruct = class {
 		this.construct = construct;
 	}
 	/**
-	* Resolves each dependency as a new transient instance via {@link Box.new},
+	* Resolves each dependency as a new instance via {@link Box.new},
 	* meaning dependencies are not cached or shared.
 	* Returns a function compatible with `static init` that can be assigned directly.
 	*
-	* The returned instance is cached or transient depending on whether the
+	* The returned instance is cached or new depending on whether the
 	* class is retrieved via {@link Box.get} or {@link Box.new}.
 	*
 	* @example
@@ -247,7 +255,7 @@ var StaticConstruct = class {
 	* meaning dependencies are shared across the box.
 	* Returns a function compatible with `static init` that can be assigned directly.
 	*
-	* The returned instance is cached or transient depending on whether the
+	* The returned instance is cached or new depending on whether the
 	* class is retrieved via {@link Box.get} or {@link Box.new}.
 	*
 	* @example
@@ -271,5 +279,6 @@ exports.Box = Box;
 exports.Construct = Construct;
 exports.StaticConstruct = StaticConstruct;
 exports.constant = constant;
+exports.derive = derive;
 exports.factory = factory;
 exports.transient = transient;

package/dist/index.d.cts

@@ -30,18 +30,28 @@ type ConstructorInstanceType<T> = T extends {
  */
 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}.
+ * Creates a {@link Constructor} that computes a value from the box without caching the result.
  *
  * @example
  * ```ts
- * const RequestId = transient(() => crypto.randomUUID());
- * const id1 = box.get(RequestId);
- * const id2 = box.get(RequestId);
- * console.log(id1 === id2); // false
+ * class Config {
+ *   baseUrl = "https://example.com";
+ * }
+ *
+ * const RequestContext = derive((box) => ({
+ *   baseUrl: box.get(Config).baseUrl,
+ *   timestamp: Date.now(),
+ * }));
+ *
+ * const ctx1 = box.get(RequestContext);
+ * const ctx2 = box.get(RequestContext);
+ * console.log(ctx1 === ctx2); // false
  * ```
  */
+declare function derive<T>(init: (box: Box) => T): Constructor<T>;
+/**
+ * @deprecated Use {@link derive} instead.
+ */
 declare function transient<T>(init: (box: Box) => T): Constructor<T>;
 /**
  * Creates a {@link Constructor} that always resolves to the given constant value.
@@ -71,9 +81,7 @@ declare function constant<const T>(value: T): Constructor<T>;
  *
  * class UserService {
  *   constructor(private db: Database) {}
- *   static init(box: Box) {
- *     return new UserService(box.get(Database));
- *   }
+ *   static init = Box.init(UserService).get(Database);
  * }
  *
  * const box = new Box();
@@ -81,14 +89,12 @@ declare function constant<const T>(value: T): Constructor<T>;
  * 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;
+  protected cache: Map<Constructor<any>, any>;
   /**
-   * Creates a new (transient) instance without caching. Useful for instances
-   * that should not be shared.
+   * Creates a new instance without caching.
    */
   new<T extends Constructor<any>>(constructor: T): ConstructorInstanceType<T>;
   /**
@@ -104,7 +110,7 @@ declare class Box {
    *
    * 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}.
+   * the class is retrieved via {@link Box.get} or new via {@link Box.new}.
    */
   for<T extends ClassConstructor<any>>(constructor: T): Construct<T>;
   /**
@@ -136,17 +142,17 @@ declare class BoxAll {
   private box;
   constructor(box: Box);
   /**
-   * Resolves each constructor as a cached instance via {@link Box.get}.
+   * Resolves each constructor as a new instance via {@link Box.new}.
    * 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]> };
+  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]> };
   /**
-   * Resolves each constructor as a new transient instance via {@link Box.new}.
+   * 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.
    */
-  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]> };
+  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]> };
 }
 /** Builder for creating class instances with constructor dependencies resolved from a {@link Box}. */
 declare class Construct<T extends ClassConstructor<any>> {
@@ -154,10 +160,10 @@ declare class Construct<T extends ClassConstructor<any>> {
   private construct;
   constructor(box: Box, construct: T);
   /**
-   * Resolves each dependency as a new transient instance via {@link Box.new},
+   * Resolves each dependency as a new instance via {@link Box.new},
    * meaning dependencies are not cached or shared.
    *
-   * The returned instance is cached or transient depending on whether the
+   * The returned instance is cached or new depending on whether the
    * class is retrieved via {@link Box.get} or {@link Box.new}.
    *
    * @example
@@ -175,7 +181,7 @@ declare class Construct<T extends ClassConstructor<any>> {
    * 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
+   * The returned instance is cached or new depending on whether the
    * class is retrieved via {@link Box.get} or {@link Box.new}.
    *
    * @example
@@ -198,11 +204,11 @@ declare class StaticConstruct<T extends ClassConstructor<any>> {
   private construct;
   constructor(construct: T);
   /**
-   * Resolves each dependency as a new transient instance via {@link Box.new},
+   * Resolves each dependency as a new instance via {@link Box.new},
    * meaning dependencies are not cached or shared.
    * Returns a function compatible with `static init` that can be assigned directly.
    *
-   * The returned instance is cached or transient depending on whether the
+   * The returned instance is cached or new depending on whether the
    * class is retrieved via {@link Box.get} or {@link Box.new}.
    *
    * @example
@@ -219,7 +225,7 @@ declare class StaticConstruct<T extends ClassConstructor<any>> {
    * meaning dependencies are shared across the box.
    * Returns a function compatible with `static init` that can be assigned directly.
    *
-   * The returned instance is cached or transient depending on whether the
+   * The returned instance is cached or new depending on whether the
    * class is retrieved via {@link Box.get} or {@link Box.new}.
    *
    * @example
@@ -239,4 +245,4 @@ type ClassConstructor<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, Construct, Constructor, ConstructorInstanceType, StaticConstruct, constant, factory, transient };
+export { Box, Construct, Constructor, ConstructorInstanceType, StaticConstruct, constant, derive, factory, transient };

package/dist/index.d.mts

@@ -30,18 +30,28 @@ type ConstructorInstanceType<T> = T extends {
  */
 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}.
+ * Creates a {@link Constructor} that computes a value from the box without caching the result.
  *
  * @example
  * ```ts
- * const RequestId = transient(() => crypto.randomUUID());
- * const id1 = box.get(RequestId);
- * const id2 = box.get(RequestId);
- * console.log(id1 === id2); // false
+ * class Config {
+ *   baseUrl = "https://example.com";
+ * }
+ *
+ * const RequestContext = derive((box) => ({
+ *   baseUrl: box.get(Config).baseUrl,
+ *   timestamp: Date.now(),
+ * }));
+ *
+ * const ctx1 = box.get(RequestContext);
+ * const ctx2 = box.get(RequestContext);
+ * console.log(ctx1 === ctx2); // false
  * ```
  */
+declare function derive<T>(init: (box: Box) => T): Constructor<T>;
+/**
+ * @deprecated Use {@link derive} instead.
+ */
 declare function transient<T>(init: (box: Box) => T): Constructor<T>;
 /**
  * Creates a {@link Constructor} that always resolves to the given constant value.
@@ -71,9 +81,7 @@ declare function constant<const T>(value: T): Constructor<T>;
  *
  * class UserService {
  *   constructor(private db: Database) {}
- *   static init(box: Box) {
- *     return new UserService(box.get(Database));
- *   }
+ *   static init = Box.init(UserService).get(Database);
  * }
  *
  * const box = new Box();
@@ -81,14 +89,12 @@ declare function constant<const T>(value: T): Constructor<T>;
  * 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;
+  protected cache: Map<Constructor<any>, any>;
   /**
-   * Creates a new (transient) instance without caching. Useful for instances
-   * that should not be shared.
+   * Creates a new instance without caching.
    */
   new<T extends Constructor<any>>(constructor: T): ConstructorInstanceType<T>;
   /**
@@ -104,7 +110,7 @@ declare class Box {
    *
    * 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}.
+   * the class is retrieved via {@link Box.get} or new via {@link Box.new}.
    */
   for<T extends ClassConstructor<any>>(constructor: T): Construct<T>;
   /**
@@ -136,17 +142,17 @@ declare class BoxAll {
   private box;
   constructor(box: Box);
   /**
-   * Resolves each constructor as a cached instance via {@link Box.get}.
+   * Resolves each constructor as a new instance via {@link Box.new}.
    * 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]> };
+  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]> };
   /**
-   * Resolves each constructor as a new transient instance via {@link Box.new}.
+   * 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.
    */
-  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]> };
+  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]> };
 }
 /** Builder for creating class instances with constructor dependencies resolved from a {@link Box}. */
 declare class Construct<T extends ClassConstructor<any>> {
@@ -154,10 +160,10 @@ declare class Construct<T extends ClassConstructor<any>> {
   private construct;
   constructor(box: Box, construct: T);
   /**
-   * Resolves each dependency as a new transient instance via {@link Box.new},
+   * Resolves each dependency as a new instance via {@link Box.new},
    * meaning dependencies are not cached or shared.
    *
-   * The returned instance is cached or transient depending on whether the
+   * The returned instance is cached or new depending on whether the
    * class is retrieved via {@link Box.get} or {@link Box.new}.
    *
    * @example
@@ -175,7 +181,7 @@ declare class Construct<T extends ClassConstructor<any>> {
    * 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
+   * The returned instance is cached or new depending on whether the
    * class is retrieved via {@link Box.get} or {@link Box.new}.
    *
    * @example
@@ -198,11 +204,11 @@ declare class StaticConstruct<T extends ClassConstructor<any>> {
   private construct;
   constructor(construct: T);
   /**
-   * Resolves each dependency as a new transient instance via {@link Box.new},
+   * Resolves each dependency as a new instance via {@link Box.new},
    * meaning dependencies are not cached or shared.
    * Returns a function compatible with `static init` that can be assigned directly.
    *
-   * The returned instance is cached or transient depending on whether the
+   * The returned instance is cached or new depending on whether the
    * class is retrieved via {@link Box.get} or {@link Box.new}.
    *
    * @example
@@ -219,7 +225,7 @@ declare class StaticConstruct<T extends ClassConstructor<any>> {
    * meaning dependencies are shared across the box.
    * Returns a function compatible with `static init` that can be assigned directly.
    *
-   * The returned instance is cached or transient depending on whether the
+   * The returned instance is cached or new depending on whether the
    * class is retrieved via {@link Box.get} or {@link Box.new}.
    *
    * @example
@@ -239,4 +245,4 @@ type ClassConstructor<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, Construct, Constructor, ConstructorInstanceType, StaticConstruct, constant, factory, transient };
+export { Box, Construct, Constructor, ConstructorInstanceType, StaticConstruct, constant, derive, factory, transient };

package/dist/index.mjs

@@ -17,25 +17,37 @@ function factory(init) {
 }
 const noCacheSymbol = Symbol("Box.noCache");
 /**
-* 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}.
+* Creates a {@link Constructor} that computes a value from the box without caching the result.
 *
 * @example
 * ```ts
-* const RequestId = transient(() => crypto.randomUUID());
-* const id1 = box.get(RequestId);
-* const id2 = box.get(RequestId);
-* console.log(id1 === id2); // false
+* class Config {
+*   baseUrl = "https://example.com";
+* }
+*
+* const RequestContext = derive((box) => ({
+*   baseUrl: box.get(Config).baseUrl,
+*   timestamp: Date.now(),
+* }));
+*
+* const ctx1 = box.get(RequestContext);
+* const ctx2 = box.get(RequestContext);
+* console.log(ctx1 === ctx2); // false
 * ```
 */
-function transient(init) {
+function derive(init) {
 	return {
 		init,
 		[noCacheSymbol]: true
 	};
 }
 /**
+* @deprecated Use {@link derive} instead.
+*/
+function transient(init) {
+	return derive(init);
+}
+/**
 * Creates a {@link Constructor} that always resolves to the given constant value.
 * Constant values are never cached since they are already fixed.
 *
@@ -68,9 +80,7 @@ function constant(value) {
 *
 * class UserService {
 *   constructor(private db: Database) {}
-*   static init(box: Box) {
-*     return new UserService(box.get(Database));
-*   }
+*   static init = Box.init(UserService).get(Database);
 * }
 *
 * const box = new Box();
@@ -78,14 +88,12 @@ function constant(value) {
 * 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.
+	* Creates a new instance without caching.
 	*/
 	new(constructor) {
 		return "init" in constructor ? constructor.init(this) : new constructor();
@@ -108,7 +116,7 @@ var Box = class {
 	*
 	* 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}.
+	* the class is retrieved via {@link Box.get} or new via {@link Box.new}.
 	*/
 	for(constructor) {
 		return new Construct(this, constructor);
@@ -149,18 +157,18 @@ 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;
 	}
+	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;
+	}
 };
 /** Builder for creating class instances with constructor dependencies resolved from a {@link Box}. */
 var Construct = class {
@@ -169,10 +177,10 @@ var Construct = class {
 		this.construct = construct;
 	}
 	/**
-	* Resolves each dependency as a new transient instance via {@link Box.new},
+	* Resolves each dependency as a new instance via {@link Box.new},
 	* meaning dependencies are not cached or shared.
 	*
-	* The returned instance is cached or transient depending on whether the
+	* The returned instance is cached or new depending on whether the
 	* class is retrieved via {@link Box.get} or {@link Box.new}.
 	*
 	* @example
@@ -193,7 +201,7 @@ var Construct = class {
 	* 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
+	* The returned instance is cached or new depending on whether the
 	* class is retrieved via {@link Box.get} or {@link Box.new}.
 	*
 	* @example
@@ -220,11 +228,11 @@ var StaticConstruct = class {
 		this.construct = construct;
 	}
 	/**
-	* Resolves each dependency as a new transient instance via {@link Box.new},
+	* Resolves each dependency as a new instance via {@link Box.new},
 	* meaning dependencies are not cached or shared.
 	* Returns a function compatible with `static init` that can be assigned directly.
 	*
-	* The returned instance is cached or transient depending on whether the
+	* The returned instance is cached or new depending on whether the
 	* class is retrieved via {@link Box.get} or {@link Box.new}.
 	*
 	* @example
@@ -246,7 +254,7 @@ var StaticConstruct = class {
 	* meaning dependencies are shared across the box.
 	* Returns a function compatible with `static init` that can be assigned directly.
 	*
-	* The returned instance is cached or transient depending on whether the
+	* The returned instance is cached or new depending on whether the
 	* class is retrieved via {@link Box.get} or {@link Box.new}.
 	*
 	* @example
@@ -266,4 +274,4 @@ var StaticConstruct = class {
 };
 
 //#endregion
-export { Box, Construct, StaticConstruct, constant, factory, transient };
+export { Box, Construct, StaticConstruct, constant, derive, factory, transient };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "getbox",
-  "version": "1.3.1",
+  "version": "1.4.0",
   "description": "Lightweight dependency injection for TypeScript",
   "private": false,
   "main": "./dist/index.cjs",