getbox 1.1.0 → 1.3.0

package/CONTEXT.md

@@ -57,9 +57,7 @@ import { Box } from "getbox";
 class UserService {
   constructor(private db: Database, private logger: Logger) {}
 
-  static init(box: Box) {
-    return box.for(UserService).get(Database, LoggerFactory);
-  }
+  static init = Box.init(UserService).get(Database, LoggerFactory);
 }
 ```
 

package/README.md

@@ -43,10 +43,7 @@ import { Printer } from "./printer";
 export class Office {
   constructor(public printer: Printer) {}
 
-  static init(box: Box) {
-    const printer = box.get(Printer);
-    return new Office(printer);
-  }
+  static init = Box.init(Office).get(Printer);
 }
 ```
 
@@ -125,10 +122,7 @@ import { Logger, LoggerFactory } from "./logger";
 export class UserService {
   constructor(private logger: Logger) {}
 
-  static init(box: Box) {
-    const logger = box.get(LoggerFactory);
-    return new UserService(logger);
-  }
+  static init = Box.init(UserService).get(LoggerFactory);
 
   createUser(name: string) {
     this.logger.log(`Creating user: ${name}`);
@@ -172,6 +166,23 @@ const ApiUrl = factory((box: Box) => {
 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.
@@ -202,18 +213,15 @@ console.log(db === db2); // false (transient)
 
 ## Class constructors
 
-Use `box.for()` inside a class's `static init` method to resolve constructor dependencies automatically. The instance returned by the builder is cached or transient depending on whether the class is retrieved via `box.get()` or `box.new()`.
+Use `Box.init` to allow resolving classes that have constructor parameters.
 
 ```ts
-import { Box, factory } from "getbox";
+import { Box } from "getbox";
 
 class UserService {
   constructor(private db: Database, private logger: Logger) {}
 
-  static init(box: Box) {
-    // Create new instance with cached dependencies
-    return box.for(UserService).get(Database, LoggerFactory);
-  }
+  static init = Box.init(UserService).get(Database, LoggerFactory);
 
   createUser(name: string) {
     this.logger.log(`Creating user: ${name}`);
@@ -225,6 +233,34 @@ 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) {}
+
+  static init(box: Box) {
+    return new UserService(box.get(Database), box.get(LoggerFactory));
+  }
+}
+```
+
+Use `box.for()` when you need custom logic alongside dependency resolution.
+
+```ts
+class UserService {
+  constructor(private db: Database, private logger: Logger) {}
+
+  static init(box: Box) {
+    const logger = box.get(LoggerFactory);
+    logger.log("Initializing UserService");
+    return box.for(UserService).get(Database, LoggerFactory);
+  }
+}
+```
+
+Classes with no constructor parameters are resolved automatically without needing `static init`. If `static init` is defined, it takes priority over the default constructor.
+
 ## Mocking
 
 You can mock dependencies for testing using `Box.mock`. This is particularly useful with factories and interfaces.

package/dist/context.d.cts

@@ -17,7 +17,7 @@ declare function useBox(): Box;
  * Resolves a cached instance from the current {@link withBox} scope.
  * Shorthand for `useBox().get(constructor)`.
  */
-declare function resolve<T>(constructor: Constructor<T>): T;
+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)`.

package/dist/context.d.mts

@@ -17,7 +17,7 @@ declare function useBox(): Box;
  * Resolves a cached instance from the current {@link withBox} scope.
  * Shorthand for `useBox().get(constructor)`.
  */
-declare function resolve<T>(constructor: Constructor<T>): T;
+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)`.

package/dist/index.cjs

@@ -16,7 +16,26 @@
 function factory(init) {
 	return { init };
 }
-const constantSymbol = Symbol("Box constant");
+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}.
+*
+* @example
+* ```ts
+* const RequestId = transient(() => crypto.randomUUID());
+* const id1 = box.get(RequestId);
+* const id2 = box.get(RequestId);
+* console.log(id1 === id2); // false
+* ```
+*/
+function transient(init) {
+	return {
+		init,
+		[noCacheSymbol]: true
+	};
+}
 /**
 * Creates a {@link Constructor} that always resolves to the given constant value.
 * Constant values are never cached since they are already fixed.
@@ -30,7 +49,7 @@ const constantSymbol = Symbol("Box constant");
 function constant(value) {
 	return {
 		init: () => value,
-		[constantSymbol]: true
+		[noCacheSymbol]: true
 	};
 }
 /**
@@ -79,7 +98,7 @@ var Box = class {
 	get(constructor) {
 		if (this.cache.has(constructor)) return this.cache.get(constructor);
 		const value = this.new(constructor);
-		if (!(constantSymbol in constructor && constructor[constantSymbol])) this.cache.set(constructor, value);
+		if (!(noCacheSymbol in constructor && constructor[noCacheSymbol])) this.cache.set(constructor, value);
 		return value;
 	}
 	/** Resolves multiple constructors at once. */
@@ -96,6 +115,21 @@ var Box = class {
 		return new Construct(this, constructor);
 	}
 	/**
+	* Returns a {@link StaticConstruct} builder for defining a `static init` method.
+	* The result can be assigned directly to `static init`.
+	*
+	* @example
+	* ```ts
+	* class UserService {
+	*   constructor(private db: Database, private logger: Logger) {}
+	*   static init = Box.init(UserService).get(Database, LoggerFactory);
+	* }
+	* ```
+	*/
+	static init(constructor) {
+		return new StaticConstruct(constructor);
+	}
+	/**
 	* Registers a mock value in the box's cache for a given constructor.
 	* Useful for replacing dependencies in tests.
 	*/
@@ -178,9 +212,64 @@ var Construct = class {
 		return new this.construct(...instances);
 	}
 };
+/**
+* Builder for creating a `static init` function with constructor dependencies
+* resolved from a {@link Box}.
+*/
+var StaticConstruct = class {
+	constructor(construct) {
+		this.construct = construct;
+	}
+	/**
+	* Resolves each dependency as a new transient 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
+	* 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);
+	* }
+	* ```
+	*/
+	new(...args) {
+		return (box) => {
+			const instances = args.map((arg) => 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.
+	* Returns a function compatible with `static init` that can be assigned directly.
+	*
+	* 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.init(UserService).get(Database, LoggerFactory);
+	* }
+	* ```
+	*/
+	get(...args) {
+		return (box) => {
+			const instances = args.map((arg) => box.get(arg));
+			return new this.construct(...instances);
+		};
+	}
+};
 
 //#endregion
 exports.Box = Box;
 exports.Construct = Construct;
+exports.StaticConstruct = StaticConstruct;
 exports.constant = constant;
-exports.factory = factory;
+exports.factory = factory;
+exports.transient = transient;

package/dist/index.d.cts

@@ -10,7 +10,11 @@ type Constructor<T> = {
   new (): T;
 };
 /** Extracts the instance type from a {@link Constructor}. */
-type ConstructorInstanceType<T> = T extends Constructor<infer U> ? U : never;
+type ConstructorInstanceType<T> = T extends {
+  init(box: Box): infer U;
+} ? U : T extends {
+  new (): infer U;
+} ? U : never;
 /**
  * Creates a {@link Constructor} from a factory function.
  * The factory receives the box as an argument, allowing it to resolve other dependencies.
@@ -25,6 +29,20 @@ type ConstructorInstanceType<T> = T extends Constructor<infer U> ? U : never;
  * ```
  */
 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}.
+ *
+ * @example
+ * ```ts
+ * const RequestId = transient(() => crypto.randomUUID());
+ * const id1 = box.get(RequestId);
+ * const id2 = box.get(RequestId);
+ * console.log(id1 === id2); // false
+ * ```
+ */
+declare function transient<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.
@@ -72,12 +90,12 @@ declare class Box {
    * Creates a new (transient) instance without caching. Useful for instances
    * that should not be shared.
    */
-  new<T>(constructor: Constructor<T>): T;
+  new<T extends Constructor<any>>(constructor: T): ConstructorInstanceType<T>;
   /**
    * Resolves an instance from the cache, or creates and caches a new one.
    * Subsequent calls with the same constructor return the cached instance.
    */
-  get<T>(constructor: Constructor<T>): T;
+  get<T extends Constructor<any>>(constructor: T): ConstructorInstanceType<T>;
   /** Resolves multiple constructors at once. */
   readonly all: BoxAll;
   /**
@@ -89,6 +107,19 @@ declare class Box {
    * the class is retrieved via {@link Box.get} or kept transient via {@link Box.new}.
    */
   for<T extends ClassConstructor<any>>(constructor: T): Construct<T>;
+  /**
+   * Returns a {@link StaticConstruct} builder for defining a `static init` method.
+   * The result can be assigned directly to `static init`.
+   *
+   * @example
+   * ```ts
+   * class UserService {
+   *   constructor(private db: Database, private logger: Logger) {}
+   *   static init = Box.init(UserService).get(Database, LoggerFactory);
+   * }
+   * ```
+   */
+  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.
@@ -159,6 +190,48 @@ declare class Construct<T extends ClassConstructor<any>> {
    */
   get(...args: ClassConstructorArgs<T>): InstanceType<T>;
 }
+/**
+ * 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);
+  /**
+   * Resolves each dependency as a new transient 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
+   * 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);
+   * }
+   * ```
+   */
+  new(...args: ClassConstructorArgs<T>): (box: Box) => InstanceType<T>;
+  /**
+   * 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 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.init(UserService).get(Database, LoggerFactory);
+   * }
+   * ```
+   */
+  get(...args: ClassConstructorArgs<T>): (box: Box) => InstanceType<T>;
+}
 /** A class with any constructor signature. */
 type ClassConstructor<T> = {
   new (...args: any): T;
@@ -166,4 +239,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, constant, factory };
+export { Box, Construct, Constructor, ConstructorInstanceType, StaticConstruct, constant, factory, transient };

package/dist/index.d.mts

@@ -10,7 +10,11 @@ type Constructor<T> = {
   new (): T;
 };
 /** Extracts the instance type from a {@link Constructor}. */
-type ConstructorInstanceType<T> = T extends Constructor<infer U> ? U : never;
+type ConstructorInstanceType<T> = T extends {
+  init(box: Box): infer U;
+} ? U : T extends {
+  new (): infer U;
+} ? U : never;
 /**
  * Creates a {@link Constructor} from a factory function.
  * The factory receives the box as an argument, allowing it to resolve other dependencies.
@@ -25,6 +29,20 @@ type ConstructorInstanceType<T> = T extends Constructor<infer U> ? U : never;
  * ```
  */
 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}.
+ *
+ * @example
+ * ```ts
+ * const RequestId = transient(() => crypto.randomUUID());
+ * const id1 = box.get(RequestId);
+ * const id2 = box.get(RequestId);
+ * console.log(id1 === id2); // false
+ * ```
+ */
+declare function transient<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.
@@ -72,12 +90,12 @@ declare class Box {
    * Creates a new (transient) instance without caching. Useful for instances
    * that should not be shared.
    */
-  new<T>(constructor: Constructor<T>): T;
+  new<T extends Constructor<any>>(constructor: T): ConstructorInstanceType<T>;
   /**
    * Resolves an instance from the cache, or creates and caches a new one.
    * Subsequent calls with the same constructor return the cached instance.
    */
-  get<T>(constructor: Constructor<T>): T;
+  get<T extends Constructor<any>>(constructor: T): ConstructorInstanceType<T>;
   /** Resolves multiple constructors at once. */
   readonly all: BoxAll;
   /**
@@ -89,6 +107,19 @@ declare class Box {
    * the class is retrieved via {@link Box.get} or kept transient via {@link Box.new}.
    */
   for<T extends ClassConstructor<any>>(constructor: T): Construct<T>;
+  /**
+   * Returns a {@link StaticConstruct} builder for defining a `static init` method.
+   * The result can be assigned directly to `static init`.
+   *
+   * @example
+   * ```ts
+   * class UserService {
+   *   constructor(private db: Database, private logger: Logger) {}
+   *   static init = Box.init(UserService).get(Database, LoggerFactory);
+   * }
+   * ```
+   */
+  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.
@@ -159,6 +190,48 @@ declare class Construct<T extends ClassConstructor<any>> {
    */
   get(...args: ClassConstructorArgs<T>): InstanceType<T>;
 }
+/**
+ * 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);
+  /**
+   * Resolves each dependency as a new transient 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
+   * 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);
+   * }
+   * ```
+   */
+  new(...args: ClassConstructorArgs<T>): (box: Box) => InstanceType<T>;
+  /**
+   * 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 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.init(UserService).get(Database, LoggerFactory);
+   * }
+   * ```
+   */
+  get(...args: ClassConstructorArgs<T>): (box: Box) => InstanceType<T>;
+}
 /** A class with any constructor signature. */
 type ClassConstructor<T> = {
   new (...args: any): T;
@@ -166,4 +239,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, constant, factory };
+export { Box, Construct, Constructor, ConstructorInstanceType, StaticConstruct, constant, factory, transient };

package/dist/index.mjs

@@ -15,7 +15,26 @@
 function factory(init) {
 	return { init };
 }
-const constantSymbol = Symbol("Box constant");
+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}.
+*
+* @example
+* ```ts
+* const RequestId = transient(() => crypto.randomUUID());
+* const id1 = box.get(RequestId);
+* const id2 = box.get(RequestId);
+* console.log(id1 === id2); // false
+* ```
+*/
+function transient(init) {
+	return {
+		init,
+		[noCacheSymbol]: true
+	};
+}
 /**
 * Creates a {@link Constructor} that always resolves to the given constant value.
 * Constant values are never cached since they are already fixed.
@@ -29,7 +48,7 @@ const constantSymbol = Symbol("Box constant");
 function constant(value) {
 	return {
 		init: () => value,
-		[constantSymbol]: true
+		[noCacheSymbol]: true
 	};
 }
 /**
@@ -78,7 +97,7 @@ var Box = class {
 	get(constructor) {
 		if (this.cache.has(constructor)) return this.cache.get(constructor);
 		const value = this.new(constructor);
-		if (!(constantSymbol in constructor && constructor[constantSymbol])) this.cache.set(constructor, value);
+		if (!(noCacheSymbol in constructor && constructor[noCacheSymbol])) this.cache.set(constructor, value);
 		return value;
 	}
 	/** Resolves multiple constructors at once. */
@@ -95,6 +114,21 @@ var Box = class {
 		return new Construct(this, constructor);
 	}
 	/**
+	* Returns a {@link StaticConstruct} builder for defining a `static init` method.
+	* The result can be assigned directly to `static init`.
+	*
+	* @example
+	* ```ts
+	* class UserService {
+	*   constructor(private db: Database, private logger: Logger) {}
+	*   static init = Box.init(UserService).get(Database, LoggerFactory);
+	* }
+	* ```
+	*/
+	static init(constructor) {
+		return new StaticConstruct(constructor);
+	}
+	/**
 	* Registers a mock value in the box's cache for a given constructor.
 	* Useful for replacing dependencies in tests.
 	*/
@@ -177,6 +211,59 @@ var Construct = class {
 		return new this.construct(...instances);
 	}
 };
+/**
+* Builder for creating a `static init` function with constructor dependencies
+* resolved from a {@link Box}.
+*/
+var StaticConstruct = class {
+	constructor(construct) {
+		this.construct = construct;
+	}
+	/**
+	* Resolves each dependency as a new transient 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
+	* 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);
+	* }
+	* ```
+	*/
+	new(...args) {
+		return (box) => {
+			const instances = args.map((arg) => 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.
+	* Returns a function compatible with `static init` that can be assigned directly.
+	*
+	* 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.init(UserService).get(Database, LoggerFactory);
+	* }
+	* ```
+	*/
+	get(...args) {
+		return (box) => {
+			const instances = args.map((arg) => box.get(arg));
+			return new this.construct(...instances);
+		};
+	}
+};
 
 //#endregion
-export { Box, Construct, constant, factory };
+export { Box, Construct, StaticConstruct, constant, factory, transient };

package/package.json

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