@lppedd/di-wise-neo 0.3.1 → 0.4.0

package/README.md

@@ -1,10 +1,15 @@
 <!--suppress HtmlDeprecatedAttribute -->
+<h1 align="center">di-wise-neo</h1>
+<p align="center">Lightweight, type-safe, flexible dependency injection library for TypeScript and JavaScript</p>
 <div align="center">
-  <h1>di-wise-neo</h1>
-  <p>Lightweight, type-safe, flexible dependency injection library for TypeScript and JavaScript</p>
-  <img src="./.github/images/neo-wall.jpg" title="di-wise-neo" alt="di-wise-neo" style="border: 3px solid black; border-radius: 15px;" />
-  <div><sub>yes, I like The Matrix</sub></div>
+
+[![test](https://img.shields.io/github/actions/workflow/status/lppedd/di-wise-neo/test.yml.svg?branch=main)](https://github.com/lppedd/di-wise-neo/actions/workflows/test.yml)
+[![npm](https://img.shields.io/npm/v/@lppedd/di-wise-neo?color=%23de1f1f&logo=npm)](https://www.npmjs.com/package/@lppedd/di-wise-neo)
+[![npm gzipped size](https://img.shields.io/bundlejs/size/@lppedd/di-wise-neo)](https://bundlejs.com/?q=@lppedd/di-wise-neo)
+[![license](https://img.shields.io/github/license/lppedd/di-wise-neo?color=blue)](https://github.com/lppedd/di-wise-neo/blob/main/LICENSE)
+
 </div>
+<img align="center" src="./.github/images/neo-wall.jpg" alt="di-wise-neo" style="border: 3px solid black; border-radius: 15px;" />
 
 > [!NOTE]
 >
@@ -16,12 +21,14 @@
 
 - [Why yet another library](#why-yet-another-library)
 - [Installation](#installation)
-- [Ergonomics](#ergonomics)
+- [API reference](#api-reference)
+- [Ergonomics & Requirements](#ergonomics)
 - [Quickstart](#quickstart)
 - [Container scopes](#container-scopes)
 - [Token registration](#token-registration)
 - [Function-based injection](#function-based-injection)
 - [Decorator-based injection](#decorator-based-injection)
+- [Behavioral decorators](#behavioral-decorators)
 - [Testing support](#testing-support)
 
 ## Why yet another library
@@ -75,7 +82,7 @@ production needs.
 ## Installation
 
 ```sh
-npm install @lppedd/di-wise-neo
+npm i @lppedd/di-wise-neo
 ```
 
 ```sh
@@ -86,12 +93,21 @@ pnpm add @lppedd/di-wise-neo
 yarn add @lppedd/di-wise-neo
 ```
 
+## API reference
+
+You can find the complete API reference at [lppedd.github.io/di-wise-neo](https://lppedd.github.io/di-wise-neo)
+
 ## Ergonomics
 
 - Does **not** depend on other libraries
 - Does **not** use [reflect-metadata](https://www.npmjs.com/package/reflect-metadata) to drive decorators
 - **Can** be used from JavaScript with function-based injection
 
+### Requirements
+
+- When using decorator-based injection, `experimentalDecorators` must be enabled in your `tsconfig.json` file
+- The JavaScript environment must support features such as `Array.flat`, `WeakSet`, `WeakMap`, `Set`, and `Map`
+
 ## Quickstart
 
 ```ts
@@ -139,7 +155,7 @@ const container = createContainer({
   defaultScope: Scope.Container,
 });
 
-// Register our managed dependencies into the container
+// Register our managed dependencies in the container
 container.register(ExtensionContext)
          .register(SecretStore)
          .register(ContributionRegistrar);
@@ -209,21 +225,21 @@ Alternatively, use an explicit `ClassProvider` object - useful when registering
 an interface or abstract type:
 
 ```ts
-const Store = Type<Store>("Store");
-container.register(Store, {
+const IStore = createType<Store>("Store");
+container.register(IStore, {
   useClass: SecretStore, // class SecretStore implements Store
 });
 ```
 
-Upon resolving `Store`, the container creates an instance of `SecretStore`,
-caching it according to the configured scope.
+Upon resolving `IStore` - which represents the `Store` interface - the container
+creates an instance of `SecretStore`, caching it according to the configured scope.
 
 ### FactoryProvider
 
 A lazily computed value can be registered using a factory function:
 
 ```ts
-const Env = Type<string>("Env")
+const Env = createType<string>("Env")
 container.register(Env, {
   useFactory: () => isNode() ? "Node.js" : "browser",
 });
@@ -234,10 +250,10 @@ according to the configured scope.
 
 ### ValueProvider
 
-A static value - always taken as-is and unaffected by scopes - can be registered using:
+A fixed value - always taken as-is and unaffected by scopes - can be registered using:
 
 ```ts
-const PID = Type<number>("PID");
+const PID = createType<number>("PID");
 const processId = spawnProcess();
 container.register(PID, {
   useValue: processId,
@@ -253,7 +269,7 @@ Registers an alias to another token, allowing multiple identifiers to resolve to
 Using the previous `PID` example, we can register a `TaskID` alias:
 
 ```ts
-const TaskID = Type<number>("TaskID");
+const TaskID = createType<number>("TaskID");
 container.register(TaskID, {
   useExisting: PID,
 });
@@ -299,7 +315,7 @@ never been registered in the container.
 
 ```ts
 export class ExtensionContext {
-  readonly stores /*: Store[] */ = injectAll(Store);
+  readonly stores /*: Store[] */ = injectAll(IStore);
 
   /* ... */
 
@@ -330,7 +346,7 @@ has never been registered in the container.
 ```ts
 export class ExtensionContext {
   // The type does not change compared to injectAll(T), but the call does not fail
-  readonly stores /*: Store[] */ = optionalAll(Store);
+  readonly stores /*: Store[] */ = optionalAll(IStore);
 
   /* ... */
 }
@@ -355,7 +371,7 @@ export class ProcessManager {
   /* ... */
 
   // The method is called immediately after instance construction
-  notifyListener(@Inject(ProcessListener) listeners: ProcessListener): void {
+  notifyListener(@Inject(ProcessListener) listener: ProcessListener): void {
     listener.processStarted(this.rootPID);
   }
 }
@@ -370,7 +386,7 @@ never been registered in the container.
 
 ```ts
 export class ExtensionContext {
-  constructor(@InjectAll(Store) readonly stores: Store[]) {}
+  constructor(@InjectAll(IStore) readonly stores: Store[]) {}
 
   /* ... */
 
@@ -401,7 +417,7 @@ has never been registered in the container.
 ```ts
 export class ExtensionContext {
   // The type does not change compared to @InjectAll, but construction does not fail
-  constructor(@OptionalAll(Store) readonly stores: Store[]) {}
+  constructor(@OptionalAll(IStore) readonly stores: Store[]) {}
 
   /* ... */
 }
@@ -412,22 +428,67 @@ export class ExtensionContext {
 Sometimes you may need to reference a token or class that is declared later in the file.  
 Normally, attempting to do that would result in a `ReferenceError`:
 
-> ReferenceError: Cannot access 'Store' before initialization
+> ReferenceError: Cannot access 'IStore' before initialization
 
 We can work around this problem by using the `forwardRef` helper function:
 
 ```ts
 export class ExtensionContext {
-  constructor(@OptionalAll(forwardRef(() => Store)) readonly stores: Store[]) {}
+  constructor(@OptionalAll(forwardRef(() => IStore)) readonly stores: Store[]) {}
+
+  /* ... */
+}
+```
+
+## Behavioral decorators
+
+The library includes two behavioral decorators that influence how classes are registered in the container.
+These decorators attach metadata to the class type, which is then interpreted by the container during registration.
 
+### `@Scoped`
+
+Specifies a default scope for the decorated class:
+
+```ts
+@Scoped(Scope.Container)
+export class ExtensionContext {
   /* ... */
 }
 ```
 
+Applying `@Scoped(Scope.Container)` to the `ExtensionContext` class instructs the DI container
+to register it with the **Container** scope by default.
+
+This default can be overridden by explicitly providing registration options:
+
+```ts
+container.register(
+  ExtensionContext,
+  { useClass: ExtensionContext },
+  { scope: Scope.Resolution },
+);
+```
+
+In this example, `ExtensionContext` will be registered with **Resolution** scope instead.
+
+### `@AutoRegister`
+
+Enables automatic registration of the decorated class if it has not been registered explicitly.
+
+```ts
+@AutoRegister()
+export class ExtensionContext {
+  /* ... */
+}
+
+// Resolve the class without prior registration. It works!
+container.resolve(ExtensionContext);
+```
+
 ## Testing support
 
 Testing is an important part of software development, and dependency injection is meant to make it easier.  
-The **di-wise-neo** container API exposes methods to more easily integrate with testing scenarios.
+The container API exposes methods to more easily integrate with testing scenarios.
 
 ### `resetRegistry`
 

package/dist/cjs/index.d.ts

@@ -1,46 +1,30 @@
-/**
- * Constructor type.
- */
-interface Constructor<Instance extends object> {
-    new (...args: any[]): Instance;
-    readonly name: string;
-    readonly length: number;
-}
-/**
- * Token type.
- */
-type Token<Value = any> = [Value] extends [object] ? Type<Value> | Constructor<Value> : Type<Value>;
-/**
- * Describes a {@link Token} array with at least one element.
- */
-type Tokens<Value = any> = [Token<Value>, ...Token<Value>[]];
 /**
  * Type API.
  */
 interface Type<A> {
     /**
-     * Name of the type.
+     * The name of the type.
      */
     readonly name: string;
     /**
-     * Create an intersection type from another type.
+     * Creates an intersection type from another type.
      *
      * @example
      * ```ts
-     * const A = Type<A>("A");
-     * const B = Type<B>("B");
+     * const A = createType<A>("A");
+     * const B = createType<B>("B");
      *
      * A.inter("I", B); // => Type<A & B>
      * ```
      */
     inter<B>(typeName: string, B: Type<B>): Type<A & B>;
     /**
-     * Create a union type from another type.
+     * Creates a union type from another type.
      *
      * @example
      * ```ts
-     * const A = Type<A>("A");
-     * const B = Type<B>("B");
+     * const A = createType<A>("A");
+     * const B = createType<B>("B");
      *
      * A.union("U", B); // => Type<A | B>
      * ```
@@ -48,16 +32,31 @@ interface Type<A> {
     union<B>(typeName: string, B: Type<B>): Type<A | B>;
 }
 /**
- * Create a type token.
+ * Constructor type.
+ */
+interface Constructor<Instance extends object> {
+    new (...args: any[]): Instance;
+    readonly name: string;
+}
+/**
+ * Token type.
+ */
+type Token<Value = any> = [Value] extends [object] ? Type<Value> | Constructor<Value> : Type<Value>;
+/**
+ * Describes a {@link Token} array with at least one element.
+ */
+type Tokens<Value = any> = [Token<Value>, ...Token<Value>[]];
+/**
+ * Creates a type token.
  *
  * @example
  * ```ts
- * const Spell = Type<Spell>("Spell");
+ * const ISpell = createType<Spell>("Spell");
  * ```
  *
  * @__NO_SIDE_EFFECTS__
  */
-declare function Type<T>(typeName: string): Type<T>;
+declare function createType<T>(typeName: string): Type<T>;
 
 /**
  * Provides a class instance for a token via a class constructor.
@@ -65,31 +64,33 @@ declare function Type<T>(typeName: string): Type<T>;
 interface ClassProvider<Instance extends object> {
     readonly useClass: Constructor<Instance>;
 }
-/**
- * Provides a value for a token via another existing token.
- */
-interface ExistingProvider<Value> {
-    readonly useExisting: Token<Value>;
-}
 /**
  * Provides a value for a token via a factory function.
  *
- * The factory function runs inside the injection context
- * and can thus access dependencies via {@link inject}.
+ * The factory function runs inside the injection context and can
+ * thus access dependencies via {@link inject}-like functions.
  */
 interface FactoryProvider<Value> {
     readonly useFactory: (...args: []) => Value;
 }
 /**
- * Provides a direct - already constructed - value for a token.
+ * Provides a static - already constructed - value for a token.
  */
 interface ValueProvider<T> {
     readonly useValue: T;
 }
+/**
+ * Aliases another registered token.
+ *
+ * Resolving this token will return the value of the aliased one.
+ */
+interface ExistingProvider<Value> {
+    readonly useExisting: Token<Value>;
+}
 /**
  * A token provider.
  */
-type Provider<Value = any> = ClassProvider<Value & object> | ExistingProvider<Value> | FactoryProvider<Value> | ValueProvider<Value>;
+type Provider<Value = any> = ClassProvider<Value & object> | FactoryProvider<Value> | ValueProvider<Value> | ExistingProvider<Value>;
 
 declare const Scope: {
     readonly Inherited: "Inherited";
@@ -115,7 +116,7 @@ interface RegistrationOptions {
  * ```ts
  * class Wizard {
  *   wand = inject(
- *     Build(() => {
+ *     build(() => {
  *       const wand = inject(Wand);
  *       wand.owner = this;
  *       // ...
@@ -127,7 +128,7 @@ interface RegistrationOptions {
  *
  * @__NO_SIDE_EFFECTS__
  */
-declare function Build<Value>(factory: (...args: []) => Value): Type<Value>;
+declare function build<Value>(factory: (...args: []) => Value): Type<Value>;
 
 /**
  * Container creation options.
@@ -212,35 +213,87 @@ interface Container {
      * Returns whether the token is registered in this container or in parent containers, if any.
      */
     isRegistered(token: Token): boolean;
+    /**
+     * Registers a concrete class, where the class acts as its own token.
+     *
+     * Tokens provided via the {@link Injectable} decorator applied to the class
+     * are also registered as aliases.
+     *
+     * The default registration scope is determined by the {@link Scoped} decorator,
+     * if present.
+     */
+    registerClass<Instance extends object>(Class: Constructor<Instance>): void;
+    /**
+     * Registers a concrete class with a token.
+     *
+     * The default registration scope is determined by the {@link Scoped} decorator
+     * applied to the class, if present, but it can be overridden by passing explicit
+     * registration options.
+     */
+    registerClass<Instance extends object, ProvidedInstance extends Instance>(token: Token<Instance>, Class: Constructor<ProvidedInstance>, options?: RegistrationOptions): void;
+    /**
+     * Registers a token whose value is produced by a factory function.
+     *
+     * The factory function runs inside the injection context and can
+     * thus access dependencies via {@link inject}-like functions.
+     */
+    registerFactory<Value, ProvidedValue extends Value>(token: Token<Value>, factory: (...args: []) => ProvidedValue, options?: RegistrationOptions): void;
+    /**
+     * Registers a token with a fixed value.
+     *
+     * The provided value is returned as-is when the token is resolved (scopes do not apply).
+     */
+    registerValue<Value, ProvidedValue extends Value>(token: Token<Value>, value: ProvidedValue): void;
+    /**
+     * Registers one or more tokens as aliases for a target token.
+     *
+     * When an alias is resolved, the target token is resolved instead.
+     */
+    registerAlias<Value, ProvidedValue extends Value>(targetToken: Token<ProvidedValue>, aliasTokens: Tokens<Value>): void;
     /**
      * Registers a {@link ClassProvider}, using the class itself as its token.
      *
-     * Tokens provided to the {@link Injectable} decorator applied to the class
-     * are also registered as aliases. The scope is determined by the {@link Scoped}
-     * decorator, if present.
+     * Tokens provided via the {@link Injectable} decorator applied to the class
+     * are also registered as aliases.
+     *
+     * The scope is determined by the {@link Scoped} decorator, if present.
+     *
+     * @see registerClass
      */
-    register<Instance extends object>(Class: Constructor<Instance>): this;
+    register<Instance extends object>(Class: Constructor<Instance>): Container;
     /**
      * Registers a {@link ClassProvider} with a token.
+     *
+     * The default registration scope is determined by the {@link Scoped} decorator
+     * applied to the provided class, if present, but it can be overridden by
+     * passing explicit registration options.
+     *
+     * @see registerClass
      */
-    register<Instance extends object, ProviderInstance extends Instance>(token: Token<Instance>, provider: ClassProvider<ProviderInstance>, options?: RegistrationOptions): this;
+    register<Instance extends object, ProviderInstance extends Instance>(token: Token<Instance>, provider: ClassProvider<ProviderInstance>, options?: RegistrationOptions): Container;
     /**
      * Registers a {@link FactoryProvider} with a token.
+     *
+     * @see registerFactory
      */
-    register<Value, ProviderValue extends Value>(token: Token<Value>, provider: FactoryProvider<ProviderValue>, options?: RegistrationOptions): this;
+    register<Value, ProviderValue extends Value>(token: Token<Value>, provider: FactoryProvider<ProviderValue>, options?: RegistrationOptions): Container;
     /**
      * Registers an {@link ExistingProvider} with a token.
      *
      * The token will alias the one set in `useExisting`.
+     *
+     * @see registerAlias
      */
-    register<Value, ProviderValue extends Value>(token: Token<Value>, provider: ExistingProvider<ProviderValue>): this;
+    register<Value, ProviderValue extends Value>(token: Token<Value>, provider: ExistingProvider<ProviderValue>): Container;
     /**
      * Registers a {@link ValueProvider} with a token.
      *
      * Values provided via `useValue` are never cached (scopes do not apply)
      * and are simply returned as-is.
+     *
+     * @see registerValue
      */
-    register<Value, ProviderValue extends Value>(token: Token<Value>, provider: ValueProvider<ProviderValue>): this;
+    register<Value, ProviderValue extends Value>(token: Token<Value>, provider: ValueProvider<ProviderValue>): Container;
     /**
      * Removes all registrations for the given token from the container's internal registry.
      *
@@ -364,8 +417,8 @@ interface Container {
 declare function createContainer(options?: Partial<ContainerOptions>): Container;
 
 /**
- * Class decorator for enabling auto-registration of an unregistered class
- * when first resolving it from the container.
+ * Class decorator that enables auto-registration of an unregistered class,
+ * when the class is first resolved from the container.
  *
  * @example
  * ```ts
@@ -387,9 +440,14 @@ interface TokenRef<Value = any> {
     readonly getRefToken: () => Token<Value>;
 }
 /**
- * Allows referencing a token that is declared later in the file by wrapping it in a function.
+ * Allows referencing tokens that are declared later in the file by wrapping them
+ * in a lazily evaluated function.
  */
 declare function forwardRef<Value>(token: () => Tokens<Value>): TokensRef<Value>;
+/**
+ * Allows referencing a token that is declared later in the file by wrapping it
+ * in a lazily evaluated function.
+ */
 declare function forwardRef<Value>(token: () => Token<Value>): TokenRef<Value>;
 
 /**
@@ -424,8 +482,8 @@ declare function Inject<Value>(token: Token<Value>): ParameterDecorator;
 declare function Inject<Value>(tokens: TokenRef<Value>): ParameterDecorator;
 
 /**
- * Class decorator for registering additional aliasing tokens for the decorated type
- * when registering it.
+ * Class decorator that registers additional aliasing tokens for the decorated type,
+ * when the type is first registered in the container.
  *
  * The container uses {@link ExistingProvider} under the hood.
  *
@@ -437,8 +495,8 @@ declare function Inject<Value>(tokens: TokenRef<Value>): ParameterDecorator;
  */
 declare function Injectable<This extends object, Value extends This>(...tokens: Tokens<Value>): ClassDecorator;
 /**
- * Class decorator for registering additional aliasing tokens for the decorated type
- * when registering it.
+ * Class decorator that registers additional aliasing tokens for the decorated type,
+ * when the type is first registered in the container.
  *
  * The container uses {@link ExistingProvider} under the hood.
  *
@@ -718,7 +776,7 @@ declare const Injector: Type<Injector>;
  */
 interface MiddlewareComposer {
     /**
-     * Add a middleware function to the composer.
+     * Adds a middleware function to the composer.
      */
     use<MethodKey extends keyof Container>(key: MethodKey, wrap: Container[MethodKey] extends Function ? (next: Container[MethodKey]) => Container[MethodKey] : never): MiddlewareComposer;
 }
@@ -744,7 +802,7 @@ interface Middleware {
     (composer: MiddlewareComposer, api: Readonly<Container>): void;
 }
 /**
- * Apply middleware functions to a container.
+ * Applies middleware functions to a container.
  *
  * Middlewares are applied in array order, but execute in reverse order.
  *
@@ -768,5 +826,5 @@ interface Middleware {
  */
 declare function applyMiddleware(container: Container, middlewares: Middleware[]): Container;
 
-export { AutoRegister, Build, Inject, InjectAll, Injectable, Injector, Optional, OptionalAll, Scope, Scoped, Type, applyMiddleware, createContainer, forwardRef, inject, injectAll, injectBy };
-export type { ClassProvider, Constructor, Container, ContainerOptions, ExistingProvider, FactoryProvider, Middleware, MiddlewareComposer, Provider, RegistrationOptions, Token, TokenRef, Tokens, TokensRef, ValueProvider };
+export { AutoRegister, Inject, InjectAll, Injectable, Injector, Optional, OptionalAll, Scope, Scoped, applyMiddleware, build, createContainer, createType, forwardRef, inject, injectAll, injectBy };
+export type { ClassProvider, Constructor, Container, ContainerOptions, ExistingProvider, FactoryProvider, Middleware, MiddlewareComposer, Provider, RegistrationOptions, Token, TokenRef, Tokens, TokensRef, Type, ValueProvider };