getbox 1.2.0 → 1.3.1

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

@@ -6,8 +6,6 @@
 
 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.
 
-For an alternative pattern using AsyncLocalStorage where classes can resolve dependencies directly in their constructors, see [getbox/context](./CONTEXT.md).
-
 ## Installation
 
 ```sh
@@ -16,7 +14,9 @@ npm install getbox
 
 ## Usage
 
-`getbox` has a very small API surface. You typically only need to use the `Box.get()` and optionally static init methods or the `factory` helper.
+`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).
 
 ### Create a class
 
@@ -33,20 +33,17 @@ export class Printer {
 
 ### Use in another class
 
-Retrieve instances by calling `box.get(Constructor)` within your class constructor or factory function.
+The `static init` property tells the box what dependencies to pass when instantiating the class.
 
 ```ts
 // office.ts
-import { Box, factory } from "getbox";
+import { Box } from "getbox";
 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);
 }
 ```
 
@@ -106,14 +103,12 @@ export interface Logger {
   log(message: string): void;
 }
 
-export class ConsoleLogger implements Logger {
-  log(message: string): void {
-    console.log(`[LOG] ${message}`);
-  }
-}
-
 const LoggerFactory = factory((box: Box): Logger => {
-  return new ConsoleLogger();
+  return {
+    log(message: string): void {
+      console.log(`[LOG] ${message}`);
+    },
+  };
 });
 ```
 
@@ -125,10 +120,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}`);
@@ -219,18 +211,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}`);
@@ -242,6 +231,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,7 @@
 function factory(init) {
 	return { init };
 }
-const noCacheSymbol = 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
@@ -115,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.
 	*/
@@ -197,10 +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.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.
@@ -86,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;
   /**
@@ -103,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.
@@ -173,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;
@@ -180,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, transient };
+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.
@@ -86,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;
   /**
@@ -103,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.
@@ -173,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;
@@ -180,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, transient };
+export { Box, Construct, Constructor, ConstructorInstanceType, StaticConstruct, constant, factory, transient };

package/dist/index.mjs

@@ -15,7 +15,7 @@
 function factory(init) {
 	return { init };
 }
-const noCacheSymbol = 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
@@ -114,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.
 	*/
@@ -196,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, transient };
+export { Box, Construct, StaticConstruct, constant, factory, transient };

package/package.json

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