getbox 1.3.1 → 2.0.0

package/dist/index.cjs

@@ -1,5 +1,7 @@
 
 //#region src/index.ts
+const cacheSymbol = Symbol("Box.cache");
+const isClass = (fn) => fn.prototype !== void 0 && Function.prototype.toString.call(fn).startsWith("class");
 /**
 * Creates a {@link Constructor} from a factory function.
 * The factory receives the box as an argument, allowing it to resolve other dependencies.
@@ -14,31 +16,36 @@
 * ```
 */
 function factory(init) {
-	return { init };
+	return {
+		[cacheSymbol]: true,
+		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 = computed((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) {
-	return {
-		init,
-		[noCacheSymbol]: true
-	};
+function computed(init) {
+	return { 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
@@ -47,19 +54,15 @@ function transient(init) {
 * ```
 */
 function constant(value) {
-	return {
-		init: () => value,
-		[noCacheSymbol]: true
-	};
+	return { init: () => value };
 }
 /**
 * 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` function, a class with a
+* no-argument constructor, or a function-based constructor created by
+* {@link factory}, {@link computed}, or {@link constant}.
 *
 * @example
 * ```ts
@@ -69,9 +72,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,44 +80,38 @@ 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.
-	*/
-	new(constructor) {
-		return "init" in constructor ? constructor.init(this) : new constructor();
-	}
-	/**
-	* Resolves an instance from the cache, or creates and caches a new one.
-	* Subsequent calls with the same constructor return the cached instance.
-	*/
-	get(constructor) {
-		if (this.cache.has(constructor)) return this.cache.get(constructor);
-		const value = this.new(constructor);
-		if (!(noCacheSymbol in constructor && constructor[noCacheSymbol])) this.cache.set(constructor, value);
-		return value;
+	new(arg) {
+		if (Array.isArray(arg)) return arg.map((c) => this.new(c));
+		if (typeof arg === "function") return "init" in arg ? arg.init(this) : new arg();
+		if ("init" in arg && !isClass(arg.init)) return arg.init(this);
+		const result = {};
+		for (const [key, constructor] of Object.entries(arg)) result[key] = this.new(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.
-	*
-	* Intended to be used inside a class's `static init` method. The instance
-	* returned by the builder is never cached itself, but can be cached when
-	* the class is retrieved via {@link Box.get} or kept transient via {@link Box.new}.
-	*/
-	for(constructor) {
-		return new Construct(this, constructor);
+	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);
+			const value = "init" in arg ? arg.init(this) : new arg();
+			this.cache.set(arg, value);
+			return value;
+		}
+		if ("init" in arg && !isClass(arg.init)) {
+			if (this.cache.has(arg)) return this.cache.get(arg);
+			const value = arg.init(this);
+			if (cacheSymbol in arg) this.cache.set(arg, value);
+			return value;
+		}
+		const result = {};
+		for (const [key, constructor] of Object.entries(arg)) result[key] = this.get(constructor);
+		return result;
 	}
 	/**
-	* Returns a {@link StaticConstruct} builder for defining a `static init` method.
-	* The result can be assigned directly to `static init`.
+	* Returns a `static init` function builder.
 	*
 	* @example
 	* ```ts
@@ -127,7 +122,7 @@ var Box = class {
 	* ```
 	*/
 	static init(constructor) {
-		return new StaticConstruct(constructor);
+		return new StaticInit(constructor);
 	}
 	/**
 	* Registers a mock value in the box's cache for a given constructor.
@@ -139,107 +134,45 @@ var Box = class {
 	/**
 	* Removes the instance from the box's cache for a given constructor.
 	* Removes all instances if no constructor is provided.
-	*/
-	static clear(box, constructor) {
-		if (!constructor) return box.cache.clear();
-		box.cache.delete(constructor);
-	}
-};
-/** Resolves multiple constructors at once from a {@link Box}. */
-var BoxAll = class {
-	constructor(box) {
-		this.box = box;
-	}
-	get(constructors) {
-		if (Array.isArray(constructors)) return constructors.map((c) => this.box.get(c));
-		const result = {};
-		for (const [key, constructor] of Object.entries(constructors)) result[key] = this.box.get(constructor);
-		return result;
-	}
-	new(constructors) {
-		if (Array.isArray(constructors)) return constructors.map((c) => this.box.new(c));
-		const result = {};
-		for (const [key, constructor] of Object.entries(constructors)) result[key] = this.box.new(constructor);
-		return result;
-	}
-};
-/** Builder for creating class instances with constructor dependencies resolved from a {@link Box}. */
-var Construct = class {
-	constructor(box, construct) {
-		this.box = box;
-		this.construct = construct;
-	}
-	/**
-	* Resolves each dependency as a new transient instance via {@link Box.new},
-	* meaning dependencies are not cached or shared.
-	*
-	* The returned instance is cached or transient depending on whether the
-	* class is retrieved via {@link Box.get} or {@link Box.new}.
-	*
-	* @example
-	* ```ts
-	* class UserService {
-	*   constructor(private db: Database, private logger: Logger) {}
-	*   static init(box: Box) {
-	*     return box.for(UserService).new(Database, LoggerFactory);
-	*   }
-	* }
-	* ```
-	*/
-	new(...args) {
-		const instances = args.map((arg) => this.box.new(arg));
-		return new this.construct(...instances);
-	}
-	/**
-	* Resolves each dependency as a cached instance via {@link Box.get},
-	* meaning dependencies are shared across the box.
-	*
-	* The returned instance is cached or transient depending on whether the
-	* class is retrieved via {@link Box.get} or {@link Box.new}.
 	*
-	* @example
-	* ```ts
-	* class UserService {
-	*   constructor(private db: Database, private logger: Logger) {}
-	*   static init(box: Box) {
-	*     return box.for(UserService).get(Database, LoggerFactory);
-	*   }
-	* }
-	* ```
+	* Returns true if an instance existed and has been removed from the box's cache.
 	*/
-	get(...args) {
-		const instances = args.map((arg) => this.box.get(arg));
-		return new this.construct(...instances);
+	static clear(box, constructor) {
+		if (!constructor) {
+			const size = box.cache.size;
+			box.cache.clear();
+			return size > 0;
+		}
+		return box.cache.delete(constructor);
 	}
 };
 /**
 * Builder for creating a `static init` function with constructor dependencies
 * resolved from a {@link Box}.
 */
-var StaticConstruct = class {
+var StaticInit = class {
 	constructor(construct) {
 		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
 	* ```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 this.construct(...box.new(args));
 		};
 	}
 	/**
@@ -247,7 +180,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
@@ -260,16 +193,14 @@ var StaticConstruct = class {
 	*/
 	get(...args) {
 		return (box) => {
-			const instances = args.map((arg) => box.get(arg));
-			return new this.construct(...instances);
+			return new this.construct(...box.get(args));
 		};
 	}
 };
 
 //#endregion
 exports.Box = Box;
-exports.Construct = Construct;
-exports.StaticConstruct = StaticConstruct;
+exports.StaticInit = StaticInit;
+exports.computed = computed;
 exports.constant = constant;
-exports.factory = factory;
-exports.transient = transient;
+exports.factory = factory;

package/dist/index.d.cts

@@ -1,8 +1,9 @@
 //#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.
+ * A type that can be resolved by a {@link Box}. Either a class with a
+ * `static init` function that returns an instance, 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;
@@ -30,22 +31,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 = computed((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 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
@@ -58,10 +65,9 @@ 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` function, a class with a
+ * no-argument constructor, or a function-based constructor created by
+ * {@link factory}, {@link computed}, or {@link constant}.
  *
  * @example
  * ```ts
@@ -71,9 +77,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,35 +85,27 @@ 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.
+   * 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 kept transient 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 a `static init` function builder.
    *
    * @example
    * ```ts
@@ -119,7 +115,7 @@ declare class Box {
    * }
    * ```
    */
-  static init<T extends ClassConstructor<any>>(constructor: T): StaticConstruct<T>;
+  static init<T extends ClassConstructor<any>>(constructor: T): StaticInit<T>;
   /**
    * Registers a mock value in the box's cache for a given constructor.
    * Useful for replacing dependencies in tests.
@@ -128,88 +124,31 @@ declare class Box {
   /**
    * Removes the instance from the box's cache for a given constructor.
    * Removes all instances if no constructor is provided.
-   */
-  static clear<T>(box: Box, constructor?: Constructor<T>): void;
-}
-/** Resolves multiple constructors at once from a {@link Box}. */
-declare class BoxAll {
-  private box;
-  constructor(box: Box);
-  /**
-   * Resolves each constructor as a cached instance via {@link Box.get}.
-   * Accepts an array or object of constructors and returns instances in the same shape.
-   */
-  get<const T extends Constructor<any>[]>(constructors: T): { [K in keyof T]: ConstructorInstanceType<T[K]> };
-  get<T extends Record<string, Constructor<any>>>(constructors: T): { [K in keyof T]: ConstructorInstanceType<T[K]> };
-  /**
-   * Resolves each constructor as a new transient instance via {@link Box.new}.
-   * Accepts an array or object of constructors and returns instances in the same shape.
-   */
-  new<const T extends Constructor<any>[]>(constructors: T): { [K in keyof T]: ConstructorInstanceType<T[K]> };
-  new<T extends Record<string, Constructor<any>>>(constructors: T): { [K in keyof T]: ConstructorInstanceType<T[K]> };
-}
-/** Builder for creating class instances with constructor dependencies resolved from a {@link Box}. */
-declare class Construct<T extends ClassConstructor<any>> {
-  private box;
-  private construct;
-  constructor(box: Box, construct: T);
-  /**
-   * Resolves each dependency as a new transient instance via {@link Box.new},
-   * meaning dependencies are not cached or shared.
-   *
-   * The returned instance is cached or transient depending on whether the
-   * class is retrieved via {@link Box.get} or {@link Box.new}.
    *
-   * @example
-   * ```ts
-   * class UserService {
-   *   constructor(private db: Database, private logger: Logger) {}
-   *   static init(box: Box) {
-   *     return box.for(UserService).new(Database, LoggerFactory);
-   *   }
-   * }
-   * ```
+   * Returns true if an instance existed and has been removed from the box's cache.
    */
-  new(...args: ClassConstructorArgs<T>): InstanceType<T>;
-  /**
-   * Resolves each dependency as a cached instance via {@link Box.get},
-   * meaning dependencies are shared across the box.
-   *
-   * The returned instance is cached or transient depending on whether the
-   * class is retrieved via {@link Box.get} or {@link Box.new}.
-   *
-   * @example
-   * ```ts
-   * class UserService {
-   *   constructor(private db: Database, private logger: Logger) {}
-   *   static init(box: Box) {
-   *     return box.for(UserService).get(Database, LoggerFactory);
-   *   }
-   * }
-   * ```
-   */
-  get(...args: ClassConstructorArgs<T>): InstanceType<T>;
+  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>> {
+declare class StaticInit<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
    * ```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);
    * }
    * ```
    */
@@ -219,7 +158,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 +178,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, Constructor, ConstructorInstanceType, StaticInit, computed, constant, factory };