@lppedd/di-wise-neo 0.11.1 → 0.12.0

package/README.md

@@ -3,17 +3,17 @@
 <p align="center">Lightweight, type-safe, flexible dependency injection library for TypeScript and JavaScript</p>
 <div align="center">
 
+[![npm](https://img.shields.io/npm/v/@lppedd/di-wise-neo?color=%23de1f1f&logo=npm)](https://www.npmjs.com/package/@lppedd/di-wise-neo)
+[![ecmascript](https://img.shields.io/badge/ES-2022-blue?logo=javascript)](https://en.wikipedia.org/wiki/ECMAScript_version_history#13th_edition_%E2%80%93_ECMAScript_2022)
+[![status](https://img.shields.io/badge/status-beta-AC29EC)](https://github.com/lppedd/di-wise-neo/blob/main/CHANGELOG.md#0100)
 [![build](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)
 [![coverage](https://img.shields.io/codecov/c/github/lppedd/di-wise-neo/main?token=R9XZFTQ0BA)](https://app.codecov.io/gh/lppedd/di-wise-neo/tree/main/src)
-[![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]
->
 > **di-wise-neo** is a fork of [di-wise][di-wise], aiming to provide a simpler yet more powerful API,
 > in part thanks to TypeScript's experimental decorators. Shout out to [@exuanbo](https://github.com/exuanbo)
 > for the strong foundations!
@@ -42,7 +42,7 @@ Part of the problem is the crazy amount of parameter passing, and the many expor
 global values floating around waiting to be imported and to generate yet another
 coupling point.
 
-My background with Java is full of such cases, that have been (partially) mitigated
+My background with Java is full of such cases that have been (partially) mitigated
 by introducing dependency-injection libraries based on Java's powerful Contexts and
 Dependency Injection (see [Weld][cdi-weld], the reference implementation).
 
@@ -53,24 +53,23 @@ I've also explored on my own and discovered [redi][redi] and [di-wise][di-wise].
 
 What I was looking for is a lightweight solution that offers:
 
-- full type safety
-- scoped resolution of dependencies
-- optional decorator support for constructor and method injection.  
-  Yes I know, forget type-safety with decorators, but they are extremely
-  intuitive to pick up for Java devs.
-- no dependency on [reflect-metadata][reflect-metadata], as I'm an ESBuild user
-  and ESBuild [does not][esbuild-issue] support `emitDecoratorMetadata`
+- Full type safety.
+- Scoped resolution of dependencies.
+- Optional decorator support for constructor and method injection.  
+  Yes, I know, forget type-safety with decorators, but they are extremely intuitive to pick up for Java devs.
+- No dependency on [reflect-metadata][reflect-metadata], as I'm an ESBuild user and ESBuild
+  [does not][esbuild-issue] support `emitDecoratorMetadata`.
 
-Unfortunately both [tsyringe][tsyringe] and [InversifyJS][InversifyJS] require
+Unfortunately, both [tsyringe][tsyringe] and [InversifyJS][InversifyJS] require
 [reflect-metadata][reflect-metadata] to run correctly. [Awilix][Awilix] looks good,
 but it's probably too much for what I need to do, and it does not support decorators.
 Plus, the API just didn't click for me.
 
 [redi][redi] focuses _only_ on constructor injection via decorators, which is nice.
 However, it falls short when it comes to type safety and resolution scopes:
-it only supports singletons, with a decorator-based trick to create fresh instances.
+it only supports singletons with a decorator-based trick to create fresh instances.
 
-And lastly, [di-wise][di-wise]. This small library was quite the surprise! Easy to pick up,
+And lastly, [di-wise][di-wise]. This small library was quite a surprise! Easy to pick up,
 no scope creep, injection context support, and full type safety via Angular-like
 `inject<T>()` functions (that's more like a service locator, but whatever).
 The only problems are the slightly overcomplicated API - especially regarding typings - and
@@ -95,18 +94,21 @@ 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)
+You can find the complete API reference at [lppedd.github.io/di-wise-neo][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
+- Does **not** depend on other libraries.
+- Does **not** use [reflect-metadata][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`
+- The JS environment must support features such as `Array.at`, `Array.flat`, `WeakRef`, `WeakMap`, `Set`, `Map`.
+
+#### Decorator-based injection
+
+- When using decorator-based injection, `experimentalDecorators` must be enabled in your `tsconfig.json` file.
 
 ## Quickstart
 
@@ -175,9 +177,9 @@ values are cached and reused.
 
 Creates a new value every time the dependency is resolved, which means values are never cached.
 
-- a class registered via `ClassProvider` is instantiated on each resolution
-- a factory function registered via `FactoryProvider` is invoked on each resolution
-- a value registered via `ValueProvider` is always returned as-is
+- A class registered via `ClassProvider` is instantiated on each resolution
+- A factory function registered via `FactoryProvider` is invoked on each resolution
+- A value registered via `ValueProvider` is always returned as-is
 
 > [!NOTE]
 > When a **Transient** or **Resolution**-scoped value is injected into a **Container**-scoped
@@ -187,8 +189,7 @@ Creates a new value every time the dependency is resolved, which means values ar
 ### Resolution
 
 Creates and caches a single value per resolution graph.  
-The same value is reused during a single resolution request, but a new one is created
-for each separate request.
+The same value is reused during a single resolution request, but a new one is created for each request.
 
 ### Container
 
@@ -196,7 +197,7 @@ Creates and caches a single value per container.
 If the value is not found in the current container, it is looked up in the parent container,
 and so on.
 
-It effectively behaves like a **singleton** scope, but allows container-specific overrides.
+It effectively behaves like a **singleton** scope but allows container-specific overrides.
 
 ## Token registration
 
@@ -291,9 +292,10 @@ All injection functions must be invoked inside an _injection context_, which sto
 the currently active container.  
 The _injection context_ is available in these situations:
 
-- inside the `constructor` of a class instantiated by the DI container
-- in property initializers of such classes
-- within factory functions used by `FactoryProvider`
+- Inside the `constructor` of a class instantiated by the DI container.
+- In property initializers of such classes.
+- Within factory functions used by `FactoryProvider`.
+- Within functions passed to `Injector.runInContext`.
 
 ### `inject<T>(Token): T`
 
@@ -342,7 +344,7 @@ export class ProcessManager {
 
 ### `optionalAll<T>(Token): T[]`
 
-Injects all values associated with a token, or an **empty array** if the token
+Injects all values associated with a token or an **empty array** if the token
 has never been registered in the container.
 
 ```ts
@@ -356,10 +358,11 @@ export class ExtensionContext {
 
 ## Decorator-based injection
 
-You can also perform dependency injection using TypeScript's experimental decorators.
+You can also perform dependency injection using TypeScript's experimental decorators.  
+**di-wise-neo** supports decorating constructor and instance method parameters.
 
-**di-wise-neo** supports decorating constructor's and instance method's parameters.  
-It does not support property injection by design.
+> [!NOTE]
+> Property injection is **not** supported by design.
 
 ### `@Inject(Token)`
 
@@ -413,7 +416,7 @@ export class ProcessManager {
 
 ### `@OptionalAll(Token)`
 
-Injects all values associated with a token, or an **empty array** if the token
+Injects all values associated with a token or an **empty array** if the token
 has never been registered in the container.
 
 ```ts
@@ -427,7 +430,7 @@ export class ExtensionContext {
 
 ### Forward references
 
-Sometimes you may need to reference a token or class that is declared later in the file.  
+Sometimes you may need to reference a token or class declared later in the file.  
 Normally, attempting to do that would result in a `ReferenceError`:
 
 > ReferenceError: Cannot access 'IStore' before initialization
@@ -501,8 +504,8 @@ The container will throw an error at registration time if the name is already ta
 
 ### `@AutoRegister`
 
-Enables automatic registration of the decorated class when it is resolved,
-if it has not been registered beforehand.
+Enables automatic registration of the decorated class when it is resolved if it has not
+been registered beforehand.
 
 ```ts
 @AutoRegister()
@@ -516,8 +519,7 @@ container.resolve(ExtensionContext);
 
 ### `@EagerInstantiate`
 
-Sets the default class scope to **Container** and marks the class for eager instantiation
-upon registration.
+Sets the default class scope to **Container** and marks the class for eager instantiation upon registration.
 
 This causes the container to immediately create and cache the instance of the class
 at registration time, instead of deferring instantiation until the first resolution.
@@ -596,6 +598,7 @@ All credits to the original author for focusing on a clean architecture and on c
 [InversifyJS]: https://github.com/inversify/InversifyJS
 [redi]: https://github.com/wzhudev/redi
 [di-wise]: https://github.com/exuanbo/di-wise
+[di-wise-neo]: https://lppedd.github.io/di-wise-neo
 [reflect-metadata]: https://github.com/microsoft/reflect-metadata
 [esbuild-issue]: https://github.com/evanw/esbuild/issues/257
 [source-container]: https://github.com/lppedd/di-wise-neo/blob/main/src/container.ts#L29

package/dist/cjs/index.d.ts

@@ -145,7 +145,19 @@ interface ValueProvider<Value> {
  */
 interface ExistingProvider<Value> {
     /**
-     * The existing token to alias.
+     * The existing token to alias, with an optional name qualifier.
+     *
+     * @example
+     * ```ts
+     * container.register(ISecretStorage, {
+     *   useExisting: PersistentSecretStorage,
+     * });
+     *
+     * // Or in case we need to alias a name-qualified token
+     * container.register(ISecretStorage, {
+     *   useExisting: [PersistentSecretStorage, "fileSystem"],
+     * });
+     * ```
      */
     readonly useExisting: Token<Value> | [Token<Value>, string?];
     /**
@@ -171,8 +183,22 @@ interface ExistingProvider<Value> {
 type Provider<Value = any> = ClassProvider<Value & object> | FactoryProvider<Value> | ValueProvider<Value> | ExistingProvider<Value>;
 
 declare const Scope: {
+    /**
+     * Creates a new value every time the token is resolved.
+     */
     readonly Transient: "Transient";
+    /**
+     * Creates and caches a single value per token resolution graph.
+     *
+     * The same value is reused during a single resolution request and is subsequently discarded.
+     */
     readonly Resolution: "Resolution";
+    /**
+     * Creates and caches a single value per container.
+     *
+     * If the value is not found in the current container, it is looked up in the parent container,
+     * and so on. It effectively behaves like a _singleton_ scope but allows container-specific overrides.
+     */
     readonly Container: "Container";
 };
 type Scope = (typeof Scope)[keyof typeof Scope];
@@ -345,9 +371,8 @@ interface Container {
      * The scope for the automatic registration is determined by either
      * the {@link Scoped} decorator on the class, or {@link ContainerOptions.defaultScope}.
      *
-     * If `optional` is false or is not passed and the class is not registered in the container
-     * (and could not be auto-registered), an error is thrown.
-     * Otherwise, if `optional` is true, `undefined` is returned.
+     * If the class is not registered in this container or any of its parent containers
+     * and could not be auto-registered, an error is thrown.
      *
      * The resolution behavior depends on the {@link Provider} used during registration:
      * - For {@link ValueProvider}, the explicitly provided instance is returned.
@@ -359,17 +384,13 @@ interface Container {
      * in the container's internal registry.
      */
     resolve<Instance extends object>(Class: Constructor<Instance>, name?: string): Instance;
-    resolve<Instance extends object>(Class: Constructor<Instance>, optional?: false, name?: string): Instance;
-    resolve<Instance extends object>(Class: Constructor<Instance>, optional: true, name?: string): Instance | undefined;
-    resolve<Instance extends object>(Class: Constructor<Instance>, optional?: boolean, name?: string): Instance | undefined;
     /**
      * Resolves the given token to the value associated with it.
      *
      * If the token is registered in this container or any of its parent containers,
      * its value is resolved using the most recent registration.
      *
-     * If `optional` is false or not passed and the token is not registered in the container,
-     * an error is thrown. Otherwise, if `optional` is true, `undefined` is returned.
+     * If the token is not registered in this container or any of its parent containers, an error is thrown.
      *
      * The resolution behavior depends on the {@link Provider} used during registration:
      * - For {@link ValueProvider}, the explicitly provided value is returned.
@@ -381,9 +402,51 @@ interface Container {
      * in the container's internal registry.
      */
     resolve<Value>(token: Token<Value>, name?: string): Value;
-    resolve<Value>(token: Token<Value>, optional?: false, name?: string): Value;
-    resolve<Value>(token: Token<Value>, optional: true, name?: string): Value | undefined;
-    resolve<Value>(token: Token<Value>, optional?: boolean, name?: string): Value | undefined;
+    /**
+     * Resolves the given class to the instance associated with it.
+     *
+     * If the class is registered in this container or any of its parent containers,
+     * an instance is created using the most recent registration.
+     *
+     * If the class is not registered, but it is decorated with {@link AutoRegister},
+     * or {@link ContainerOptions.autoRegister} is true, the class is registered automatically.
+     * Otherwise, the resolution fails.
+     *
+     * The scope for the automatic registration is determined by either
+     * the {@link Scoped} decorator on the class, or {@link ContainerOptions.defaultScope}.
+     *
+     * If the class is not registered in this container or any of its parent containers
+     * and could not be auto-registered, `undefined` is returned instead.
+     *
+     * The resolution behavior depends on the {@link Provider} used during registration:
+     * - For {@link ValueProvider}, the explicitly provided instance is returned.
+     * - For {@link FactoryProvider}, the factory function is invoked to create the instance.
+     * - For {@link ClassProvider}, a new instance of the class is created according to its scope.
+     * - For {@link ExistingProvider}, the instance is resolved by referring to another registered token.
+     *
+     * If the class is registered with _container_ scope, the resolved instance is cached
+     * in the container's internal registry.
+     */
+    tryResolve<Instance extends object>(Class: Constructor<Instance>, name?: string): Instance | undefined;
+    /**
+     * Tries to resolve the given token to the value associated with it.
+     *
+     * If the token is registered in this container or any of its parent containers,
+     * its value is resolved using the most recent registration.
+     *
+     * If the token is not registered in this container or any of its parent containers,
+     * `undefined` is returned instead.
+     *
+     * The resolution behavior depends on the {@link Provider} used during registration:
+     * - For {@link ValueProvider}, the explicitly provided value is returned.
+     * - For {@link FactoryProvider}, the factory function is invoked to create the value.
+     * - For {@link ClassProvider}, a new instance of the class is created according to its scope.
+     * - For {@link ExistingProvider}, the value is resolved by referring to another registered token.
+     *
+     * If the token is registered with _container_ scope, the resolved value is cached
+     * in the container's internal registry.
+     */
+    tryResolve<Value>(token: Token<Value>, name?: string): Value | undefined;
     /**
      * Resolves the given class to all instances provided by the registrations associated with it.
      *
@@ -394,9 +457,8 @@ interface Container {
      * The scope for the automatic registration is determined by either
      * the {@link Scoped} decorator on the class, or {@link ContainerOptions.defaultScope}.
      *
-     * If `optional` is false or is not passed and the class is not registered in the container
-     * (and could not be auto-registered), an error is thrown.
-     * Otherwise, if `optional` is true, an empty array is returned.
+     * If the class is not registered in this container or any of its parent containers
+     * and could not be auto-registered, an error is thrown.
      *
      * The resolution behavior depends on the {@link Provider} used during registration:
      * - For {@link ValueProvider}, the explicitly provided instance is returned.
@@ -408,17 +470,12 @@ interface Container {
      * in the container's internal registry.
      *
      * A separate instance of the class is created for each provider.
-     *
-     * @see The documentation for `resolve(Class: Constructor)`
      */
-    resolveAll<Instance extends object>(Class: Constructor<Instance>, optional?: false): Instance[];
-    resolveAll<Instance extends object>(Class: Constructor<Instance>, optional: true): Instance[];
-    resolveAll<Instance extends object>(Class: Constructor<Instance>, optional?: boolean): Instance[];
+    resolveAll<Instance extends object>(Class: Constructor<Instance>): Instance[];
     /**
      * Resolves the given token to all values provided by the registrations associated with it.
      *
-     * If `optional` is false or not passed and the token is not registered in the container,
-     * an error is thrown. Otherwise, if `optional` is true, an empty array is returned.
+     * If the token is not registered in this container or any of its parent containers, an error is thrown.
      *
      * The resolution behavior depends on the {@link Provider} used during registration:
      * - For {@link ValueProvider}, the explicitly provided value is returned.
@@ -428,12 +485,49 @@ interface Container {
      *
      * If the token is registered with _container_ scope, the resolved values are cached
      * in the container's internal registry.
+     */
+    resolveAll<Value>(token: Token<Value>): Value[];
+    /**
+     * Resolves the given class to all instances provided by the registrations associated with it.
+     *
+     * If the class is not registered, but it is decorated with {@link AutoRegister},
+     * or {@link ContainerOptions.autoRegister} is true, the class is registered automatically.
+     * Otherwise, the resolution fails.
      *
-     * @see The documentation for `resolve(token: Token)`
+     * The scope for the automatic registration is determined by either
+     * the {@link Scoped} decorator on the class, or {@link ContainerOptions.defaultScope}.
+     *
+     * If the class is not registered in this container or any of its parent containers
+     * and could not be auto-registered, an empty array is returned instead.
+     *
+     * The resolution behavior depends on the {@link Provider} used during registration:
+     * - For {@link ValueProvider}, the explicitly provided instance is returned.
+     * - For {@link FactoryProvider}, the factory function is invoked to create the instance.
+     * - For {@link ClassProvider}, a new instance of the class is created according to its scope.
+     * - For {@link ExistingProvider}, the instance is resolved by referring to another registered token.
+     *
+     * If the class is registered with _container_ scope, the resolved instances are cached
+     * in the container's internal registry.
+     *
+     * A separate instance of the class is created for each provider.
+     */
+    tryResolveAll<Instance extends object>(Class: Constructor<Instance>): Instance[];
+    /**
+     * Resolves the given token to all values provided by the registrations associated with it.
+     *
+     * If the token is not registered in this container or any of its parent containers,
+     * an empty array is returned instead.
+     *
+     * The resolution behavior depends on the {@link Provider} used during registration:
+     * - For {@link ValueProvider}, the explicitly provided value is returned.
+     * - For {@link FactoryProvider}, the factory function is invoked to create the value.
+     * - For {@link ClassProvider}, a new instance of the class is created according to its scope.
+     * - For {@link ExistingProvider}, the value is resolved by referring to another registered token.
+     *
+     * If the token is registered with _container_ scope, the resolved values are cached
+     * in the container's internal registry.
      */
-    resolveAll<Value>(token: Token<Value>, optional?: false): NonNullable<Value>[];
-    resolveAll<Value>(token: Token<Value>, optional: true): NonNullable<Value>[];
-    resolveAll<Value>(token: Token<Value>, optional?: boolean): NonNullable<Value>[];
+    tryResolveAll<Value>(token: Token<Value>): Value[];
     /**
      * Disposes this container and all its cached values.
      *
@@ -450,7 +544,7 @@ interface Container {
 declare function createContainer(options?: Partial<ContainerOptions>): Container;
 
 /**
- * Class decorator that enables auto-registration of an unregistered class,
+ * Class decorator that enables auto-registration of an unregistered class
  * when the class is first resolved from the container.
  *
  * @example
@@ -536,7 +630,7 @@ declare function Inject<Value>(token: Token<Value>): ParameterDecorator;
 declare function Inject<Value>(tokens: TokenRef<Value>): ParameterDecorator;
 
 /**
- * Class decorator that registers additional aliasing tokens for the decorated type,
+ * 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.
@@ -549,7 +643,7 @@ declare function Inject<Value>(tokens: TokenRef<Value>): ParameterDecorator;
  */
 declare function Injectable<This extends object, Value extends This>(...tokens: Tokens<Value>): ClassDecorator;
 /**
- * Class decorator that registers additional aliasing tokens for the decorated type,
+ * 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.
@@ -651,19 +745,19 @@ declare function Optional<Value>(tokens: TokenRef<Value>): ParameterDecorator;
 
 /**
  * Parameter decorator that injects all instances provided by the registrations
- * associated with the given class, or an empty array if the class is not registered
+ * associated with the given class or an empty array if the class is not registered
  * in the container.
  */
 declare function OptionalAll<Instance extends object>(Class: Constructor<Instance>): ParameterDecorator;
 /**
  * Parameter decorator that injects all values provided by the registrations
- * associated with the given token, or an empty array if the token is not registered
+ * associated with the given token or an empty array if the token is not registered
  * in the container.
  */
 declare function OptionalAll<Value>(token: Token<Value>): ParameterDecorator;
 /**
  * Parameter decorator that injects all values provided by the registrations
- * associated with the given token, or an empty array if the token is not registered
+ * associated with the given token or an empty array if the token is not registered
  * in the container.
  *
  * Allows referencing a token declared later in the file by using the
@@ -776,7 +870,7 @@ declare function injectAll<Instance extends object>(Class: Constructor<Instance>
  *
  * Throws an error if the token is not registered in the container.
  */
-declare function injectAll<Value>(token: Token<Value>): NonNullable<Value>[];
+declare function injectAll<Value>(token: Token<Value>): Value[];
 
 /**
  * Injector API.
@@ -805,7 +899,7 @@ interface Injector {
      *
      * Throws an error if the token is not registered in the container.
      */
-    injectAll<Value>(token: Token<Value>): NonNullable<Value>[];
+    injectAll<Value>(token: Token<Value>): Value[];
     /**
      * Injects the instance associated with the given class,
      * or `undefined` if the class is not registered in the container.
@@ -817,15 +911,15 @@ interface Injector {
      */
     optional<Value>(token: Token<Value>, name?: string): Value | undefined;
     /**
-     * Injects all instances provided by the registrations associated with the given class,
+     * Injects all instances provided by the registrations associated with the given class
      * or an empty array if the class is not registered in the container.
      */
     optionalAll<Instance extends object>(Class: Constructor<Instance>): Instance[];
     /**
-     * Injects all values provided by the registrations associated with the given token,
+     * Injects all values provided by the registrations associated with the given token
      * or an empty array if the token is not registered in the container.
      */
-    optionalAll<Value>(token: Token<Value>): NonNullable<Value>[];
+    optionalAll<Value>(token: Token<Value>): Value[];
     /**
      * Runs a function inside the injection context of this injector.
      *
@@ -833,7 +927,7 @@ interface Injector {
      * are only usable synchronously: they cannot be called from asynchronous callbacks
      * or after any `await` points.
      *
-     * @param fn The function to be run in the context of this injector.
+     * @param fn - The function to be run in the context of this injector.
      * @returns The return value of the function, if any.
      */
     runInContext<ReturnType>(fn: () => ReturnType): ReturnType;
@@ -865,8 +959,8 @@ declare const Injector: Type<Injector>;
  * This allows libraries or consumers that manipulate constructors, such as through
  * class decorators, to inform the DI system about the real "identity" of a class.
  *
- * @param transformedClass The constructor function returned by a class decorator or factory.
- * @param originalClass The original constructor function.
+ * @param transformedClass - The constructor function returned by a class decorator or factory.
+ * @param originalClass - The original constructor function.
  *
  * @remarks
  * This API affects the core class identity resolution mechanism of the DI system.
@@ -909,7 +1003,7 @@ interface Middleware {
 /**
  * Applies middleware functions to a container.
  *
- * Middlewares are applied in array order, but execute in reverse order.
+ * Middlewares are applied in array order but execute in reverse order.
  *
  * @example
  * ```ts
@@ -967,15 +1061,15 @@ declare function optionalBy<Instance extends object>(thisArg: any, Class: Constr
 declare function optionalBy<Value>(thisArg: any, token: Token<Value>, name?: string): Value | undefined;
 
 /**
- * Injects all instances provided by the registrations associated with the given class,
+ * Injects all instances provided by the registrations associated with the given class
  * or an empty array if the class is not registered in the container.
  */
 declare function optionalAll<Instance extends object>(Class: Constructor<Instance>): Instance[];
 /**
- * Injects all values provided by the registrations associated with the given token,
+ * Injects all values provided by the registrations associated with the given token
  * or an empty array if the token is not registered in the container.
  */
-declare function optionalAll<Value>(token: Token<Value>): NonNullable<Value>[];
+declare function optionalAll<Value>(token: Token<Value>): Value[];
 
 export { AutoRegister, EagerInstantiate, Inject, InjectAll, Injectable, Injector, Named, Optional, OptionalAll, Scope, Scoped, applyMiddleware, build, createContainer, createType, forwardRef, inject, injectAll, injectBy, optional, optionalAll, optionalBy, setClassIdentityMapping };
 export type { ClassProvider, Constructor, Container, ContainerOptions, ExistingProvider, FactoryProvider, Middleware, MiddlewareComposer, Provider, RegistrationOptions, Token, TokenRef, Tokens, TokensRef, Type, ValueProvider };