getbox 1.4.0 → 2.1.0

package/dist/index.cjs

@@ -1,6 +1,19 @@
 
 //#region src/index.ts
 /**
+* Symbol key used to opt a constructor out of caching.
+* When set to `false`, {@link Box.get} will not cache the resolved value.
+*
+* @example
+* ```ts
+* class MyService {
+*   static [boxCache] = false;
+*   static init = Box.init(MyService).get(Database);
+* }
+* ```
+*/
+const boxCache = Symbol("Box.cache");
+/**
 * Creates a {@link Constructor} from a factory function.
 * The factory receives the box as an argument, allowing it to resolve other dependencies.
 *
@@ -14,9 +27,8 @@
 * ```
 */
 function factory(init) {
-	return { init };
+	return { init: new Init(init) };
 }
-const noCacheSymbol = Symbol("Box.noCache");
 /**
 * Creates a {@link Constructor} that computes a value from the box without caching the result.
 *
@@ -26,7 +38,7 @@ const noCacheSymbol = Symbol("Box.noCache");
 *   baseUrl = "https://example.com";
 * }
 *
-* const RequestContext = derive((box) => ({
+* const RequestContext = computed((box) => ({
 *   baseUrl: box.get(Config).baseUrl,
 *   timestamp: Date.now(),
 * }));
@@ -36,42 +48,37 @@ const noCacheSymbol = Symbol("Box.noCache");
 * console.log(ctx1 === ctx2); // false
 * ```
 */
-function derive(init) {
+function computed(init) {
 	return {
-		init,
-		[noCacheSymbol]: true
+		init: new Init(init),
+		[boxCache]: false
 	};
 }
 /**
-* @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.
+* Constant values are already fixed and do not need caching.
 *
 * @example
 * ```ts
 * const ApiUrl = constant("https://api.example.com");
-* const port = box.get(ApiUrl); // "https://api.example.com"
+* const url = box.get(ApiUrl); // "https://api.example.com"
 * ```
 */
 function constant(value) {
 	return {
-		init: () => value,
-		[noCacheSymbol]: true
+		init: new Init(() => value),
+		[boxCache]: false
 	};
 }
 /**
 * 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.
+* A constructor is a class with a `static init` property set to an initializer,
+* a class with a no-argument constructor, or a function-based constructor created by
+* {@link factory}, {@link computed}, or {@link constant}.
+*
+* `Box` can be resolved as a dependency — `box.get(Box)` returns the current instance.
 *
 * @example
 * ```ts
@@ -89,53 +96,65 @@ function constant(value) {
 * const db = box.get(Database);
 *
 * console.log(service.db === db); // true (cached)
+* console.log(box.get(Box) === box); // true
 * ```
 */
-var Box = class {
+var Box = class Box {
 	cache = /* @__PURE__ */ new Map();
-	/**
-	* Creates a new instance without caching.
-	*/
-	new(constructor) {
-		return "init" in constructor ? constructor.init(this) : new constructor();
+	new(arg) {
+		if (Array.isArray(arg)) return arg.map((c) => this.new(c));
+		if (typeof arg === "function") return arg.init instanceof Init ? arg.init.fn(this) : new arg();
+		if (arg.init instanceof Init) return arg.init.fn(this);
+		const result = {};
+		for (const [key, constructor] of Object.entries(arg)) result[key] = this.new(constructor);
+		return result;
 	}
-	/**
-	* 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);
-		if (!(noCacheSymbol in constructor && constructor[noCacheSymbol])) this.cache.set(constructor, value);
-		return value;
+	get(arg) {
+		if (Array.isArray(arg)) return arg.map((c) => this.get(c));
+		if (typeof arg === "function") {
+			if (this.cache.has(arg)) return this.cache.get(arg);
+			if (arg === Box) return this;
+			const value = arg.init instanceof Init ? arg.init.fn(this) : new arg();
+			if (arg[boxCache] !== false) this.cache.set(arg, value);
+			return value;
+		}
+		if (arg.init instanceof Init) {
+			if (this.cache.has(arg)) return this.cache.get(arg);
+			const value = arg.init.fn(this);
+			if (arg[boxCache] !== false) this.cache.set(arg, value);
+			return value;
+		}
+		const result = {};
+		for (const [key, constructor] of Object.entries(arg)) result[key] = this.get(constructor);
+		return result;
 	}
-	/** 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.
+	* Returns an initializer builder for a class constructor.
 	*
-	* 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 new via {@link Box.new}.
+	* @example
+	* ```ts
+	* class UserService {
+	*   constructor(private db: Database, private logger: Logger) {}
+	*   static init = Box.init(UserService).get(Database, LoggerFactory);
+	* }
+	* ```
 	*/
-	for(constructor) {
-		return new Construct(this, constructor);
+	static init(ctor) {
+		return new StaticInit(ctor);
 	}
 	/**
-	* Returns a {@link StaticConstruct} builder for defining a `static init` method.
-	* The result can be assigned directly to `static init`.
+	* Returns an initializer from a factory function.
 	*
 	* @example
 	* ```ts
 	* class UserService {
-	*   constructor(private db: Database, private logger: Logger) {}
-	*   static init = Box.init(UserService).get(Database, LoggerFactory);
+	*   constructor(private db: Database) {}
+	*   static init = Box.fn((box) => new UserService(box.get(Database)));
 	* }
 	* ```
 	*/
-	static init(constructor) {
-		return new StaticConstruct(constructor);
+	static fn(fn) {
+		return new Init(fn);
 	}
 	/**
 	* Registers a mock value in the box's cache for a given constructor.
@@ -147,116 +166,49 @@ var Box = class {
 	/**
 	* Removes the instance from the box's cache for a given constructor.
 	* Removes all instances if no constructor is provided.
+	*
+	* Returns true if an instance existed and has been removed from the box's cache.
 	*/
 	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;
-	}
-	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;
+		if (!constructor) {
+			const size = box.cache.size;
+			box.cache.clear();
+			return size > 0;
+		}
+		return box.cache.delete(constructor);
 	}
 };
-/** 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 instance via {@link Box.new},
-	* meaning dependencies are not cached or shared.
-	*
-	* The returned instance is cached or new 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 new 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);
+/** An initializer wrapping a factory function for use as a {@link Constructor}. */
+var Init = class {
+	constructor(fn) {
+		this.fn = fn;
 	}
 };
-/**
-* Builder for creating a `static init` function with constructor dependencies
-* resolved from a {@link Box}.
-*/
-var StaticConstruct = class {
-	constructor(construct) {
-		this.construct = construct;
+/** Builder that creates an initializer with dependencies resolved from a {@link Box}. */
+var StaticInit = class {
+	constructor(ctor) {
+		this.ctor = ctor;
 	}
 	/**
-	* 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 new depending on whether the
-	* class is retrieved via {@link Box.get} or {@link Box.new}.
+	* Resolves each dependency as a new instance via {@link Box.new}.
+	* Dependencies are not cached or shared.
+	* Returns an initializer.
 	*
 	* @example
 	* ```ts
 	* class UserService {
 	*   constructor(private db: Database, private logger: Logger) {}
-	*   static init = Box.init(UserService).get(Database, LoggerFactory);
+	*   static init = Box.init(UserService).new(Database, LoggerFactory);
 	* }
 	* ```
 	*/
 	new(...args) {
-		return (box) => {
-			const instances = args.map((arg) => box.new(arg));
-			return new this.construct(...instances);
-		};
+		return new Init((box) => new this.ctor(...box.new(args)));
 	}
 	/**
-	* Resolves each dependency as a cached instance via {@link Box.get},
-	* 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 new depending on whether the
-	* class is retrieved via {@link Box.get} or {@link Box.new}.
+	* Resolves each dependency as a cached instance via {@link Box.get}.
+	* Dependencies are cached and shared.
+	* Returns an initializer.
 	*
 	* @example
 	* ```ts
@@ -267,18 +219,15 @@ var StaticConstruct = class {
 	* ```
 	*/
 	get(...args) {
-		return (box) => {
-			const instances = args.map((arg) => box.get(arg));
-			return new this.construct(...instances);
-		};
+		return new Init((box) => new this.ctor(...box.get(args)));
 	}
 };
 
 //#endregion
 exports.Box = Box;
-exports.Construct = Construct;
-exports.StaticConstruct = StaticConstruct;
+exports.Init = Init;
+exports.StaticInit = StaticInit;
+exports.boxCache = boxCache;
+exports.computed = computed;
 exports.constant = constant;
-exports.derive = derive;
-exports.factory = factory;
-exports.transient = transient;
+exports.factory = factory;

package/dist/index.d.cts

@@ -1,17 +1,31 @@
 //#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.
+ * Symbol key used to opt a constructor out of caching.
+ * When set to `false`, {@link Box.get} will not cache the resolved value.
+ *
+ * @example
+ * ```ts
+ * class MyService {
+ *   static [boxCache] = false;
+ *   static init = Box.init(MyService).get(Database);
+ * }
+ * ```
+ */
+declare const boxCache: unique symbol;
+/**
+ * A type that can be resolved by a {@link Box}. Either a class with a
+ * `static init` property set to an initializer, a class with a no-argument
+ * constructor, or a function-based constructor created by {@link factory},
+ * {@link computed}, or {@link constant}.
  */
 type Constructor<T> = {
-  init(box: Box): T;
+  init: Init<T>;
 } | {
   new (): T;
 };
 /** Extracts the instance type from a {@link Constructor}. */
 type ConstructorInstanceType<T> = T extends {
-  init(box: Box): infer U;
+  init: Init<infer U>;
 } ? U : T extends {
   new (): infer U;
 } ? U : never;
@@ -38,7 +52,7 @@ declare function factory<T>(init: (box: Box) => T): Constructor<T>;
  *   baseUrl = "https://example.com";
  * }
  *
- * const RequestContext = derive((box) => ({
+ * const RequestContext = computed((box) => ({
  *   baseUrl: box.get(Config).baseUrl,
  *   timestamp: Date.now(),
  * }));
@@ -48,19 +62,15 @@ declare function factory<T>(init: (box: Box) => T): Constructor<T>;
  * 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>;
+declare function computed<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.
+ * Constant values are already fixed and do not need caching.
  *
  * @example
  * ```ts
  * const ApiUrl = constant("https://api.example.com");
- * const port = box.get(ApiUrl); // "https://api.example.com"
+ * const url = box.get(ApiUrl); // "https://api.example.com"
  * ```
  */
 declare function constant<const T>(value: T): Constructor<T>;
@@ -68,10 +78,11 @@ 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.
+ * A constructor is a class with a `static init` property set to an initializer,
+ * a class with a no-argument constructor, or a function-based constructor created by
+ * {@link factory}, {@link computed}, or {@link constant}.
+ *
+ * `Box` can be resolved as a dependency — `box.get(Box)` returns the current instance.
  *
  * @example
  * ```ts
@@ -89,33 +100,28 @@ declare function constant<const T>(value: T): Constructor<T>;
  * const db = box.get(Database);
  *
  * console.log(service.db === db); // true (cached)
+ * console.log(box.get(Box) === box); // true
  * ```
  */
 declare class Box {
   protected cache: Map<Constructor<any>, any>;
   /**
    * Creates a new instance without caching.
+   * Accepts a single constructor, an array of constructors, or an object map of constructors.
    */
   new<T extends Constructor<any>>(constructor: T): ConstructorInstanceType<T>;
+  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 an instance from the cache, or creates and caches a new one.
    * Subsequent calls with the same constructor return the cached instance.
+   * Accepts a single constructor, an array of constructors, or an object map of constructors.
    */
   get<T extends Constructor<any>>(constructor: T): ConstructorInstanceType<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 new via {@link Box.new}.
-   */
-  for<T extends ClassConstructor<any>>(constructor: T): Construct<T>;
+  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]> };
   /**
-   * Returns a {@link StaticConstruct} builder for defining a `static init` method.
-   * The result can be assigned directly to `static init`.
+   * Returns an initializer builder for a class constructor.
    *
    * @example
    * ```ts
@@ -125,108 +131,59 @@ declare class Box {
    * }
    * ```
    */
-  static init<T extends ClassConstructor<any>>(constructor: T): StaticConstruct<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 new 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]> };
-  /**
-   * 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]> };
-}
-/** 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);
+  static init<T extends ClassConstructor<any>>(ctor: T): StaticInit<T>;
   /**
-   * Resolves each dependency as a new instance via {@link Box.new},
-   * meaning dependencies are not cached or shared.
-   *
-   * The returned instance is cached or new depending on whether the
-   * class is retrieved via {@link Box.get} or {@link Box.new}.
+   * Returns an initializer from a factory function.
    *
    * @example
    * ```ts
    * class UserService {
-   *   constructor(private db: Database, private logger: Logger) {}
-   *   static init(box: Box) {
-   *     return box.for(UserService).new(Database, LoggerFactory);
-   *   }
+   *   constructor(private db: Database) {}
+   *   static init = Box.fn((box) => new UserService(box.get(Database)));
    * }
    * ```
    */
-  new(...args: ClassConstructorArgs<T>): InstanceType<T>;
+  static fn<T>(fn: (box: Box) => T): Init<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 new depending on whether the
-   * class is retrieved via {@link Box.get} or {@link Box.new}.
+   * 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.
    *
-   * @example
-   * ```ts
-   * class UserService {
-   *   constructor(private db: Database, private logger: Logger) {}
-   *   static init(box: Box) {
-   *     return box.for(UserService).get(Database, LoggerFactory);
-   *   }
-   * }
-   * ```
+   * Returns true if an instance existed and has been removed from the box's cache.
    */
-  get(...args: ClassConstructorArgs<T>): InstanceType<T>;
+  static clear<T>(box: Box, constructor?: Constructor<T>): boolean;
 }
-/**
- * Builder for creating a `static init` function with constructor dependencies
- * resolved from a {@link Box}.
- */
-declare class StaticConstruct<T extends ClassConstructor<any>> {
-  private construct;
-  constructor(construct: T);
+/** An initializer wrapping a factory function for use as a {@link Constructor}. */
+declare class Init<T> {
+  readonly fn: (box: Box) => T;
+  constructor(fn: (box: Box) => T);
+}
+/** Builder that creates an initializer with dependencies resolved from a {@link Box}. */
+declare class StaticInit<C extends ClassConstructor<any>> {
+  private ctor;
+  constructor(ctor: C);
   /**
-   * 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 new depending on whether the
-   * class is retrieved via {@link Box.get} or {@link Box.new}.
+   * Resolves each dependency as a new instance via {@link Box.new}.
+   * Dependencies are not cached or shared.
+   * Returns an initializer.
    *
    * @example
    * ```ts
    * class UserService {
    *   constructor(private db: Database, private logger: Logger) {}
-   *   static init = Box.init(UserService).get(Database, LoggerFactory);
+   *   static init = Box.init(UserService).new(Database, LoggerFactory);
    * }
    * ```
    */
-  new(...args: ClassConstructorArgs<T>): (box: Box) => InstanceType<T>;
+  new(...args: ClassConstructorArgs<C>): Init<InstanceType<C>>;
   /**
-   * Resolves each dependency as a cached instance via {@link Box.get},
-   * 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 new depending on whether the
-   * class is retrieved via {@link Box.get} or {@link Box.new}.
+   * Resolves each dependency as a cached instance via {@link Box.get}.
+   * Dependencies are cached and shared.
+   * Returns an initializer.
    *
    * @example
    * ```ts
@@ -236,13 +193,13 @@ declare class StaticConstruct<T extends ClassConstructor<any>> {
    * }
    * ```
    */
-  get(...args: ClassConstructorArgs<T>): (box: Box) => InstanceType<T>;
+  get(...args: ClassConstructorArgs<C>): Init<InstanceType<C>>;
 }
 /** 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]> };
+type ClassConstructorArgs<C extends ClassConstructor<any>, Args = ConstructorParameters<C>> = { [K in keyof Args]: Constructor<Args[K]> };
 //#endregion
-export { Box, Construct, Constructor, ConstructorInstanceType, StaticConstruct, constant, derive, factory, transient };
+export { Box, Constructor, ConstructorInstanceType, Init, StaticInit, boxCache, computed, constant, factory };