getbox 1.4.0 → 2.1.0

package/CONTEXT.md

@@ -63,15 +63,15 @@ class UserService {
 
 ## Resolving multiple dependencies
 
-Use `injectAll` 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 } = injectAll({ db: Database, logger: LoggerFactory });
+  const { db, logger } = inject({ db: Database, logger: LoggerFactory });
 
   // Array form
-  const [db2, logger2] = injectAll([Database, LoggerFactory]);
+  const [db2, logger2] = inject([Database, LoggerFactory]);
 
   console.log(db === db2); // true (cached)
   console.log(logger === logger2); // true (cached)
@@ -80,11 +80,11 @@ withBox(() => {
 
 ## 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);
 });
 ```

package/README.md

@@ -14,7 +14,7 @@ npm install getbox
 
 ## Usage
 
-`getbox` has a very small API surface. You typically only need `box.get()` and optionally `static init` or the `factory` helper.
+`getbox` has a very small API surface. You typically only need `box.get()` and optionally `Box.init()` or the `factory` helper.
 
 For an alternative pattern using AsyncLocalStorage where classes can resolve dependencies directly, see [getbox/context](./CONTEXT.md).
 
@@ -49,7 +49,7 @@ console.log(office.printer === printer); // true
 
 ## 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.
+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
 
@@ -73,33 +73,35 @@ const service = box.get(UserService);
 service.createUser("Alice");
 ```
 
-`Box.init` is shorthand for writing the `static init` property yourself.
+Use `Box.fn` to write the initializer manually when you need more control.
 
 ```ts
 class UserService {
   constructor(private db: Database, private logger: Logger) {}
 
-  static init(box: Box) {
+  static init = Box.fn((box) => {
     return new UserService(box.get(Database), box.get(LoggerFactory));
-  }
+  });
 }
 ```
 
-Use `box.for()` when you need custom logic alongside dependency resolution.
+If a `static init` initializer is defined, it takes priority over the class constructor.
+
+Set `static [boxCache] = false` to opt a class out of caching. The box will call the initializer on every `box.get()` instead of returning a cached instance.
 
 ```ts
-class UserService {
-  constructor(private db: Database, private logger: Logger) {}
+import { Box, boxCache } from "getbox";
 
-  static init(box: Box) {
-    const logger = box.get(LoggerFactory);
-    logger.log("Initializing UserService");
-    return box.for(UserService).get(Database, LoggerFactory);
-  }
+class RequestContext {
+  timestamp = Date.now();
+  static [boxCache] = false;
 }
-```
 
-If `static init` is defined, it takes priority over the class constructor.
+const box = new Box();
+const ctx1 = box.get(RequestContext);
+const ctx2 = box.get(RequestContext);
+console.log(ctx1 === ctx2); // false
+```
 
 ### Factory functions
 
@@ -112,13 +114,11 @@ interface Logger {
   log(message: string): void;
 }
 
-const LoggerFactory = factory(
-  (): Logger => ({
-    log(message: string) {
-      console.log(`[LOG] ${message}`);
-    },
-  }),
-);
+const LoggerFactory = factory<Logger>(() => ({
+  log(message: string) {
+    console.log(`[LOG] ${message}`);
+  },
+}));
 
 const box = new Box();
 const logger = box.get(LoggerFactory);
@@ -126,18 +126,18 @@ const logger = box.get(LoggerFactory);
 logger.log("hello world");
 ```
 
-### Derived values
+### Computed values
 
-Use the `derive` helper to compute a value from the box without caching the result.
+Use the `computed` helper to compute a value from the box without caching the result.
 
 ```ts
-import { Box, derive } from "getbox";
+import { Box, computed } from "getbox";
 
 class Config {
   baseUrl = "https://example.com";
 }
 
-const RequestContext = derive((box) => ({
+const RequestContext = computed((box) => ({
   baseUrl: box.get(Config).baseUrl,
   timestamp: Date.now(),
 }));
@@ -152,7 +152,7 @@ console.log(ctx1 === ctx2); // false
 
 ### Constants
 
-Use the `constant` helper to wrap a fixed value as a constructor. Constant values are never cached and always return the same stable reference.
+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";
@@ -195,21 +195,34 @@ const db4 = box.new(Database);
 console.log(db3 === db4); // false (never cached)
 ```
 
-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.
+Both `box.get()` and `box.new()` also accept an array or object of constructors to resolve multiple at once.
 
 ```ts
 const box = new Box();
 
 // Cached
-const { db, logger } = box.all.get({ db: Database, logger: LoggerFactory });
-const [db2, logger2] = box.all.get([Database, LoggerFactory]);
+const { db, logger } = box.get({ db: Database, logger: LoggerFactory });
+const [db2, logger2] = box.get([Database, LoggerFactory]);
 
 // New instances
-const { db3 } = box.all.new({ db3: Database });
-const [db4] = box.all.new([Database]);
+const { db3 } = box.new({ db3: Database });
+const [db4] = box.new([Database]);
 ```
 
-> `box.get()` does not cache `derive` or `constant` values.
+> `box.get()` does not cache `computed` or `constant` values.
+
+`Box` itself can be resolved as a dependency. `box.get(Box)` returns the current box instance.
+
+```ts
+class ServiceLocator {
+  constructor(private box: Box) {}
+  static init = Box.init(ServiceLocator).get(Box);
+}
+
+const box = new Box();
+const locator = box.get(ServiceLocator);
+console.log(locator.box === box); // true
+```
 
 ## Mocking
 
@@ -243,17 +256,21 @@ 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

package/dist/context.cjs

@@ -8,48 +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 inject(constructor) {
-	return useBox().get(constructor);
-}
-/**
-* @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);
+function inject(arg) {
+	return getBox().get(arg);
 }
 
 //#endregion
-exports.construct = construct;
+exports.getBox = getBox;
 exports.inject = inject;
-exports.injectAll = injectAll;
-exports.resolve = resolve;
-exports.resolveAll = resolveAll;
-exports.useBox = useBox;
 exports.withBox = withBox;

package/dist/context.d.cts

@@ -1,44 +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.
+ * 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 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>;
+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, inject, injectAll, resolve, resolveAll, useBox, withBox };
+export { getBox, inject, withBox };

package/dist/context.d.mts

@@ -1,44 +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.
+ * 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 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>;
+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, inject, injectAll, resolve, resolveAll, useBox, withBox };
+export { getBox, inject, withBox };

package/dist/context.mjs

@@ -8,42 +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 inject(constructor) {
-	return useBox().get(constructor);
-}
-/**
-* @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);
+function inject(arg) {
+	return getBox().get(arg);
 }
 
 //#endregion
-export { construct, inject, injectAll, resolve, resolveAll, useBox, withBox };
+export { getBox, inject, withBox };