getbox 1.3.1 → 2.0.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,43 +63,28 @@ class UserService {
 
 ## Resolving multiple dependencies
 
-Use `resolveAll` to resolve multiple constructors at once. Accepts an object or array of constructors.
+Pass an array or object of constructors to `inject` to resolve multiple at once.
 
 ```ts
 withBox(() => {
   // Object form
-  const { db, logger } = resolveAll({ db: Database, logger: LoggerFactory });
+  const { db, logger } = inject({ db: Database, logger: LoggerFactory });
 
   // Array form
-  const [db2, logger2] = resolveAll([Database, LoggerFactory]);
+  const [db2, logger2] = inject([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.
+Use `getBox()` 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 box = getBox();
   const db = box.new(Database);
 });
 ```
@@ -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,121 +16,127 @@ 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
 
-Use `box.new()` to create a new instance each time without caching. This is useful for instances that should not be shared.
+Constructors define what the box resolves. `getbox` supports classes, factories, computed values, and constants. Because constructors act as interfaces, the underlying implementation can change without affecting any consumer.
+
+### Classes
+
+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 service = box.get(UserService);
+service.createUser("Alice");
+```
 
-const db1 = box.new(Database);
-const db2 = box.new(Database);
+`Box.init` is shorthand for writing the `static init` function yourself.
 
-console.log(db1 === db2); // false
+```ts
+class UserService {
+  constructor(private db: Database, private logger: Logger) {}
+
+  static init(box: Box) {
+    return new UserService(box.get(Database), box.get(LoggerFactory));
+  }
+}
 ```
 
-## Factory functions
+If `static init` is defined, it takes priority over the class constructor.
+
+### Factory functions
 
 Use the `factory` helper to create function-based constructors instead of classes. Factories work well with interfaces for better abstraction.
 
 ```ts
-// logger.ts
 import { Box, factory } from "getbox";
 
-export interface Logger {
+interface Logger {
   log(message: string): void;
 }
 
-const LoggerFactory = factory((box: Box): Logger => {
-  return {
-    log(message: string): void {
-      console.log(`[LOG] ${message}`);
-    },
-  };
-});
+const LoggerFactory = factory<Logger>(() => ({
+  log(message: string) {
+    console.log(`[LOG] ${message}`);
+  },
+}));
+
+const box = new Box();
+const logger = box.get(LoggerFactory);
+
+logger.log("hello world");
 ```
 
-```ts
-// service.ts
-import { Box } from "getbox";
-import { Logger, LoggerFactory } from "./logger";
+### Computed values
 
-export class UserService {
-  constructor(private logger: Logger) {}
+Use the `computed` helper to compute a value from the box without caching the result.
 
-  static init = Box.init(UserService).get(LoggerFactory);
+```ts
+import { Box, computed } from "getbox";
 
-  createUser(name: string) {
-    this.logger.log(`Creating user: ${name}`);
-  }
+class Config {
+  baseUrl = "https://example.com";
 }
+
+const RequestContext = computed((box) => ({
+  baseUrl: box.get(Config).baseUrl,
+  timestamp: Date.now(),
+}));
+
+const box = new Box();
+
+const ctx1 = box.get(RequestContext);
+const ctx2 = box.get(RequestContext);
+
+console.log(ctx1 === ctx2); // false
 ```
 
-## Constants
+### 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.
+Use the `constant` helper to wrap a fixed value as a constructor. Constant values are already fixed and do not need caching.
 
 ```ts
 import { Box, constant } from "getbox";
@@ -144,124 +150,54 @@ const Config = constant({
 
 const box = new Box();
 
-const apiUrl = box.get(ApiUrl);
-const port = box.get(Port);
-const config = box.get(Config);
-
-console.log(apiUrl); // "https://api.example.com"
-console.log(port); // 3000
-console.log(config.timeout); // 5000
+console.log(box.get(ApiUrl)); // "https://api.example.com"
+console.log(box.get(Port)); // 3000
+console.log(box.get(Config).timeout); // 5000
 ```
 
-Since constructors act as interfaces, a `constant` can later be replaced with a `factory` without changing any callers.
+## Resolving instances
 
-```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 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
-import { Box, transient } from "getbox";
-
-const RequestId = transient(() => crypto.randomUUID());
-
-const box = new Box();
-
-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
-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)
-```
-
-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.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.
+const db1 = box.get(Database);
+const db2 = box.get(Database);
+console.log(db1 === db2); // true (cached)
 
-```ts
-class UserService {
-  constructor(private db: Database, private logger: Logger) {}
-
-  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.
+Both `box.get()` and `box.new()` also accept an array or object of constructors to resolve multiple at once.
 
 ```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.get({ db: Database, logger: LoggerFactory });
+const [db2, logger2] = box.get([Database, LoggerFactory]);
+
+// New instances
+const { db3 } = box.new({ db3: Database });
+const [db4] = box.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 `computed` 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
@@ -291,22 +227,26 @@ console.log(mockLogger.messages); // ["Creating user: Alice"]
 
 Use `Box.clear` to remove cached instances. Pass a specific constructor to clear a single entry, or omit it to clear all cached instances.
 
+Returns `true` if an instance was removed, `false` otherwise.
+
 ```ts
 const box = new Box();
 
 const db = box.get(Database);
 
 // Clear a specific constructor
-Box.clear(box, Database);
+const cleared = Box.clear(box, Database);
+console.log(cleared);
 console.log(box.get(Database) === db); // false (new instance)
 
 // Clear all cached instances
-Box.clear(box);
+const clearedAll = Box.clear(box);
+console.log(clearedAll);
 ```
 
 ## 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

@@ -8,35 +8,19 @@ function withBox(boxOrFn, fn) {
 	return storage.run(boxOrFn, fn);
 }
 /**
-* Returns the current {@link Box} from the active {@link withBox} scope.
-* Throws if called outside a scope.
+* Returns the current Box from the active Box scope.
+* Throws if called outside a Box scope.
 */
-function useBox() {
+function getBox() {
 	const box = storage.getStore();
-	if (!box) throw new Error("useBox() must be called within a withBox() scope");
-	return box;
+	if (box) return box;
+	throw new Error("getBox() must be called within a withBox() scope");
 }
-/**
-* 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);
+function inject(arg) {
+	return getBox().get(arg);
 }
 
 //#endregion
-exports.construct = construct;
-exports.resolve = resolve;
-exports.resolveAll = resolveAll;
-exports.useBox = useBox;
+exports.getBox = getBox;
+exports.inject = inject;
 exports.withBox = withBox;

package/dist/context.d.cts

@@ -1,33 +1,27 @@
-import { Box, Construct, Constructor, ConstructorInstanceType } from "./index.cjs";
+import { Box, 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.
+ * Runs a function within a Box scope using AsyncLocalStorage.
+ * Creates a new Box if none is provided.
+ *
+ * If the callback function throws an error, the error is thrown by withBox too.
  */
 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.
+ * Returns the current Box from the active Box scope.
+ * Throws if called outside a Box scope.
  */
-declare function useBox(): Box;
+declare function getBox(): Box;
 /**
- * Resolves a cached instance from the current {@link withBox} scope.
- * Shorthand for `useBox().get(constructor)`.
+ * Resolves instances from the active Box scope.
+ * Accepts a single constructor, an array of constructors, or an object map of constructors.
+ * Throws if called outside a Box scope.
  */
-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 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>;
+declare function inject<T extends Constructor<any>>(constructor: T): ConstructorInstanceType<T>;
+declare function inject<const T extends Constructor<any>[]>(constructors: T): { [K in keyof T]: ConstructorInstanceType<T[K]> };
+declare function inject<T extends Record<string, Constructor<any>>>(constructors: T): { [K in keyof T]: ConstructorInstanceType<T[K]> };
 //#endregion
-export { construct, resolve, resolveAll, useBox, withBox };
+export { getBox, inject, withBox };

package/dist/context.d.mts

@@ -1,33 +1,27 @@
-import { Box, Construct, Constructor, ConstructorInstanceType } from "./index.mjs";
+import { Box, 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.
+ * Runs a function within a Box scope using AsyncLocalStorage.
+ * Creates a new Box if none is provided.
+ *
+ * If the callback function throws an error, the error is thrown by withBox too.
  */
 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.
+ * Returns the current Box from the active Box scope.
+ * Throws if called outside a Box scope.
  */
-declare function useBox(): Box;
+declare function getBox(): Box;
 /**
- * Resolves a cached instance from the current {@link withBox} scope.
- * Shorthand for `useBox().get(constructor)`.
+ * Resolves instances from the active Box scope.
+ * Accepts a single constructor, an array of constructors, or an object map of constructors.
+ * Throws if called outside a Box scope.
  */
-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 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>;
+declare function inject<T extends Constructor<any>>(constructor: T): ConstructorInstanceType<T>;
+declare function inject<const T extends Constructor<any>[]>(constructors: T): { [K in keyof T]: ConstructorInstanceType<T[K]> };
+declare function inject<T extends Record<string, Constructor<any>>>(constructors: T): { [K in keyof T]: ConstructorInstanceType<T[K]> };
 //#endregion
-export { construct, resolve, resolveAll, useBox, withBox };
+export { getBox, inject, withBox };

package/dist/context.mjs

@@ -8,31 +8,17 @@ function withBox(boxOrFn, fn) {
 	return storage.run(boxOrFn, fn);
 }
 /**
-* Returns the current {@link Box} from the active {@link withBox} scope.
-* Throws if called outside a scope.
+* Returns the current Box from the active Box scope.
+* Throws if called outside a Box scope.
 */
-function useBox() {
+function getBox() {
 	const box = storage.getStore();
-	if (!box) throw new Error("useBox() must be called within a withBox() scope");
-	return box;
+	if (box) return box;
+	throw new Error("getBox() must be called within a withBox() scope");
 }
-/**
-* 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);
+function inject(arg) {
+	return getBox().get(arg);
 }
 
 //#endregion
-export { construct, resolve, resolveAll, useBox, withBox };
+export { getBox, inject, withBox };