async-injection 2.2.0 → 3.0.0

package/ReadMe.md

@@ -1,42 +1,26 @@
 # Async-Injection
-[![CI Actions](https://github.com/pcafstockf/async-injection/workflows/CI/badge.svg)](https://github.com/pcafstockf/async-injection/actions)
-[![Publish Actions](https://github.com/pcafstockf/async-injection/workflows/NPM%20Publish/badge.svg)](https://github.com/pcafstockf/async-injection/actions)
+
+[![CI](https://github.com/pcafstockf/async-injection/workflows/CI/badge.svg)](https://github.com/pcafstockf/async-injection/actions)
+[![npm version](https://img.shields.io/npm/v/async-injection)](https://www.npmjs.com/package/async-injection)
+[![codecov](https://codecov.io/gh/pcafstockf/async-injection/graph/badge.svg)](https://codecov.io/gh/pcafstockf/async-injection)
 [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
 ![OSS Lifecycle](https://img.shields.io/osslifecycle/pcafstockf/async-injection.svg)
-[![npm version](https://img.shields.io/npm/v/async-injection)](https://www.npmjs.com/package/async-injection)
-
-A robust lightweight dependency injection library for TypeScript.
-
-## About
-Async-Injection is a small IoC container with support for both synchronous and asynchronous dependency injection, as well as isolated and/or hierarchical scopes.
-
-## Installation
-
-You can get the latest release from [npm](https://www.npmjs.com/package/async-injection):
 
-```
-$ npm install async-injection --save
-```
+**Lightweight TypeScript dependency injection — with first-class async support.**
 
-To enhance flexibility, Async-Injection does not dictate which Reflect API implementation you use.  However, you will need to explicitly choose and load one.  
-You can use:
+Most DI containers assume your dependencies are ready the moment they are constructed.  `async-injection` doesn't.  
+Synchronous and asynchronous dependencies can coexist naturally in the same container, and the library resolves each correctly — whether you get them immediately or need to await them.
 
-- [reflect-metadata](https://www.npmjs.com/package/reflect-metadata)
-- [core-js (core-js/es7/reflect)](https://www.npmjs.com/package/core-js)
-- [reflection](https://www.npmjs.com/package/@abraham/reflection)
+## Install
 
-The Reflect polyfill import should only be added once, and before Async-Injection is used:
-
-```typescript
-// entry.ts
-import "reflect-metadata";
-// Your code here...
+```bash
+npm install async-injection
 ```
 
-Please note that this library supports a wide variety of runtimes and is distributed as both esm and cjs modules, side by side.  
+Works in Node, browsers, Electron, and other runtimes.  
+Ships as both ESM and CJS side by side.
 
-## Basic Usage (synchronous)
-Here we 'get' a new transaction handling object, that itself, relies on a shared service:
+## Quick start
 
 ```typescript
 @Injectable()
@@ -49,209 +33,165 @@ class TransactionHandler {
     constructor(svc: SharedService) { }
 }
 
-// Create a simple container (we will bind providers into it).
 const container = new Container();
+container.bindClass(SharedService).asSingleton();  // one shared instance
+container.bindClass(TransactionHandler);           // new instance on each get
+container.bindConstant('LogLevel', 'info');        // override defaulted 'warn' level
 
-// A single instance will be created and shared by everyone.
-container.bindClass(SharedService).asSingleton();
-
-// A new instance will be created each time one is requested.
-container.bindClass(TransactionHandler);
-
-// If we omit this line, the logLevel of SharedService will be initialized to 'warn'
-container.bindConstant('LogLevel', 'info');
-
-// In our request processing code (which would be an anti-pattern)...
-// Instantiate a new transaction handler (it will be injected with the shared service).
 const tx = container.get(TransactionHandler);
 ```
-**NOTE:**  
-The examples in this ReadMe are contrived to quickly communicate concepts and usage.  
-Your real world project should of course follow best practices like [separation of concerns](https://medium.com/machine-words/separation-of-concerns-1d735b703a60), having a [composition root](https://medium.com/@cfryerdev/dependency-injection-composition-root-418a1bb19130), and should avoid anti-patterns like [service locator](http://scotthannen.org/blog/2018/11/27/stop-worrying-love-service-locator.html).
 
-## Scopes
-Scopes can be created using multiple Containers, and/or a hierarchy of Containers.
+> **Tip:**  
+> Real-world projects should follow best practices like [separation of concerns](https://medium.com/machine-words/separation-of-concerns-1d735b703a60), having a [composition root](https://medium.com/@cfryerdev/dependency-injection-composition-root-418a1bb19130), and should avoid anti-patterns like [service locator](http://scotthannen.org/blog/2018/11/27/stop-worrying-love-service-locator.html).
 
-## IoC Modules
-Why reinvent the wheel?  TypeScript is great!  
-Implement the "module" you want and just import it:
+## Setup
 
-`my-http-ioc-module.ts`
-```typescript
-import {myContainer} from './app';
-import {Logger, HttpClient} from './services';
-import {HttpClientGotWrapper} from './impl';
+Two `tsconfig.json` settings are required:
 
-myContainer.bind(Logger).asSingleton();
-myContainer.bind(HttpClient, HttpClientGotWrapper);
+```json
+{
+  "experimentalDecorators": true,
+  "emitDecoratorMetadata": true
+}
 ```
 
-## Asynchronous Support
-For simplicity, it is recommended that you use traditional synchronous injection for any class where that is possible.  
-But when that's just to much work, you can "blend" synchronous and asynchronous injection.
-To support "blending", we introduce three new methods on the `Container` which will be explained below.
+Reflection metadata is also required.  Rather than mandate a specific library, you have the freedom to bring your own — choose whichever fits your project:
+* [reflect-metadata](https://www.npmjs.com/package/reflect-metadata)
+* [core-js/es7/reflect](https://www.npmjs.com/package/core-js)
+* [@abraham/reflection](https://www.npmjs.com/package/@abraham/reflection)
 
-## Asynchronous Usage
-Perhaps in the example above, our `SharedService` is useless until it has established a database connection.  
-Of course such a simple scenario could easily be handled in user-land code, but as application complexity grows, this becomes more tedious and difficult to maintain.  
-Let's modify the example as follows:
+Import it once at your entry point, before anything else:
 ```typescript
-@Injectable()
-class SharedService {
-    constructor() { }
-    connect(): Promise<void> { ... }
-}
+import 'reflect-metadata';
+```
 
-const container = new Container();
+## Async dependencies
+
+Synchronous injection is straightforward and well understood.  
+Asynchronous injection is also well established.  
+But when you are **blending** the two in the same container, it requires a little care.
+
+### `get` vs `resolve`
+
+Think of `get(X)` / `resolve(X)` as a request not just for `X`, but for the entire tree of objects `X` depends on.  
+`get` is only safe when every node in that tree is already settled.
+
+| Condition | When to use |
+|---|---|
+| All dependencies are synchronous, **or** async singletons are already resolved | `container.get(X)` |
+| Any dependency in the tree may still be pending | `await container.resolve(X)` |
+
+> **Tip:**  
+> Call `resolveSingletons(true)` after your last `bindXXX` call and before any `get` call to avoid hard-to-debug timing issues.
+
+**When a dependency must do async work before it is usable** — open a database connection, load remote config, etc. — there are two ways to handle it:
 
-// Bind a factory function that awaits until it can fully create a SharedService.
+#### **Async factory** — bind an async factory that performs the initialization and returns the ready instance:
+
+```typescript
 container.bindAsyncFactory(SharedService, async () => {
-    let svc = new SharedService();
-    return await svc.connect();
+    const svc = new SharedService();
+    return svc.connect();           // returns Promise<SharedService>
 }).asSingleton();
 
-// A new transient instance will be created each time one is requested.
-container.bindClass(TransactionHandler);    
-
-// Wait for all bound asynchronous factory functions to complete.
-// This step is optional.  You could omit and use Container.resolve instead (see alternative below).
+// Option A — resolve everything up front, then use get() as normal
 await container.resolveSingletons(true);
-// We are now connected to the database
-
-// In our request processing code...
 const tx = container.get(TransactionHandler);
-```
-As an alternative, we could **remove** the call to `Container.resolveSingletons`, and in our request processing code, simply call `Container.resolve`.
-```typescript
+
+// Option B — resolve on demand
 const tx = await container.resolve(TransactionHandler);
 ```
 
-## Important - Container.resolve vs Container.get
-Blending synchronous and asynchronous injection adds complexity to your application.  
-The key to successful blending is to think of the object you are requesting, not as an object, but as a tree of objects with your object at the top.  
-Keep in mind that you may have **transient** objects which need to be created each time, as well as existing **singleton** objects in your dependency tree.  
-If you know ahead of time that every object which you depend on is immediately (synchronously) available, **or** if they are asynchronous **singletons** which have already been resolved (via `Container.resolveSingletons`, or a previous call to `Container.resolve`), then no need to wait, you can just `Container.get` the tree.  
-Otherwise you need to await the full resolution of the tree with `await Container.resolve`.  
+> **Note:**  
+> A factory takes full responsibility for constructing and initializing its object — `@PostConstruct` is not called on factory-returned instances.  
+> `bindFactory` and `bindAsyncFactory` are therefore the right choice when you need complete control over how an object is built, or when you cannot annotate the class.
+
+#### **`@PostConstruct`** — mark an initialization method to run on the fully constructed object after the constructor returns.  
+The method can be synchronous or asynchronous, which is especially useful since a class constructor can never be async.  
+It is also useful because a base class constructor cannot call methods overridden by a subclass.  
+The method can have parameters which can be annotated with `@Inject` and `@Optional` — the container resolves and injects them before calling the method.  
+This lets you avoid storing dependencies from the constructor solely for post-construction use:
 
-## @PostConstruct Support
-It is not always possible to fully initialize your object in the class constructor.
-This (albeit contrived) demo shows that the `Employee` class is not yet initialized when the `Person` subclass tries to call the overridden `state` method.
 ```typescript
-class Person {
-	public constructor() { this.describe(); }
-	protected state() { return "relaxing"; }
-	public describe() { console.log("Hi I'm '" + this.state() + "'"); }
-}
-class Employee extends Person {
-	constructor(private manager: boolean) {	super(); }
-	protected state() { return this.manager ? "busy" : "producing"; }
+@Injectable()
+class DatabasePool {
+    @PostConstruct()
+    async init(@Inject(DbConfig) config: DbConfig): Promise<void> {
+        this.pool = await createPool(config);  // config is injected, not stored
+    }
 }
-// This will print: 
-//  "Hi I'm 'producing", even though the author probably expected 
-//  "Hi I'm busy", because they passed true for the 'manager' parameter.
-new Employee(true); 
 ```
-Can we refactor code to work around this?  Sure.  You may have to submit a couple of PR's, re-write legacy code that has no unit tests, trash encapsulation, skip a few nights sleep, etc.  But why?  
-A PostConstruct annotation ensure's your initialization method is working on a fully constructed version of your object.
-Even better, since constructors cannot be asynchronous, PostConstruct gives you an easy way to asynchronously prepare an object before it's put into service.
 
-## @PostConstruct Usage
-Post construction methods can be either synchronous or asynchronous.
+> **Important:**  
+> Always explicitly declare the return type (`void` or `Promise<void>`, never leave it to be inferred).  
+> `container.get()` will throw if the return type is missing and the method actually does return a Promise.  
+> Constructor and `@PostConstruct` parameters follow the same rules: class-typed params are auto-resolved by reflected type; use `@Inject` for interface or primitive types. Use `@Optional()` with no argument to pass `undefined` if you want to allow a JS parameter default.
 
-```typescript
-class A {
-    public constructor() { }
+## Scopes
 
-    // Called before the object is placed into the container (or is returned from get/resolve)
-    @PostConstruct()
-    public init(): void { ... } 
-}
-class D {
-    public constructor() { }
+Create isolated or hierarchical scopes using multiple containers.  
+A child container searches its own bindings first, then walks up the parent hierarchy:
 
-    // Will not be placed into the container (or returned) until the Promise has been resolved.
-    @PostConstruct()
-    public init(): Promise<void> { ... }    
-}
+```typescript
+const child = new Container(parent);
 ```
 
-### @PostConstruct Guidelines:
-- Ensure your post construction method signature properly **declares** it's return type.  
-**WARNING!**  An unspecified return type signature where the type is implied by `return new Promise(...)` is not sufficient!  You must explicitly declare the return type.  
-- `Container.get` will throw an exception if you try to retrieve a class with `@PostConstruct` on a method that returns a `Promise`, but which does not **declare** it's return type to be `Promise`.
-- The library will not invoke @PostConstruct on an object returned from a factory.  It is the factory's responsibility to construct and initialize before returning.
-- You will likely want a `Container.resolveSingletons(true)` call between your last `Container.bindXXX()` call and any `Container.get` call.
-
-## API Overview
-Async-Injection tries to follow the common API patterns found in most other DI implementations.  Please refer to the examples above or the linked elements below for specific syntax.
-- The 
-[Container](https://pcafstockf.github.io/async-injection/api-docs/container.html) class implements a 
-[Binder](https://pcafstockf.github.io/async-injection/api-docs/binder.html) interface, which allows you to bind a 
-[Constant](https://pcafstockf.github.io/async-injection/api-docs/container.html#bindconstant), 
-[Factory](https://pcafstockf.github.io/async-injection/api-docs/container.html#bindfactory), 
-[AsyncFactory](https://pcafstockf.github.io/async-injection/api-docs/container.html#bindasyncfactory), or 
-[Class](https://pcafstockf.github.io/async-injection/api-docs/container.html#bindclass) value to an 
-[InjectableId](https://pcafstockf.github.io/async-injection/api-docs/globals.html#injectableid) (aka key) within a 
-[Container](https://pcafstockf.github.io/async-injection/api-docs/container.html).
-- The 
-[Container](https://pcafstockf.github.io/async-injection/api-docs/container.html) also implements an 
-[Injector](https://pcafstockf.github.io/async-injection/api-docs/injector.html) interface which allows you to synchronously 
-[get](https://pcafstockf.github.io/async-injection/api-docs/container.html#get) or asynchronously 
-[resolve](https://pcafstockf.github.io/async-injection/api-docs/container.html#resolve) anything that has been bound.
-- When binding a 
-[Factory](https://pcafstockf.github.io/async-injection/api-docs/container.html#bindfactory), 
-[AsyncFactory](https://pcafstockf.github.io/async-injection/api-docs/container.html#bindasyncfactory) or 
-[Class](https://pcafstockf.github.io/async-injection/api-docs/container.html#bindclass) to an 
-[InjectableId](https://pcafstockf.github.io/async-injection/api-docs/globals.html#injectableid), you can chain the result of the call to specify the binding as a 
-[Singleton](https://pcafstockf.github.io/async-injection/api-docs/bindas.html#assingleton), and/or configure an 
-[Error Handler](https://pcafstockf.github.io/async-injection/api-docs/bindas.html#onerror).
-- Containers may be nested by passing a parent Container to the 
-[constructor](https://pcafstockf.github.io/async-injection/api-docs/container.html#constructor) of a child Container.
-- To bind a 
-[Class](https://pcafstockf.github.io/async-injection/api-docs/container.html#bindclass) into the 
-[Container](https://pcafstockf.github.io/async-injection/api-docs/container.html), you must add the 
-[@Injectable](https://pcafstockf.github.io/async-injection/api-docs/globals.html#injectable) decorator (aka annotation) to your class (see examples above).
-- You may optionally add a 
-[@PostConstruct](https://pcafstockf.github.io/async-injection/api-docs/globals.html#postconstruct) decorator to a method of your class to perform synchronous or asynchronous initialization of a new instance.
-- By default, Async-Injection will examine the parameters of a class constructor and do it's best to match those to a bound 
-[InjectableId](https://pcafstockf.github.io/async-injection/api-docs/globals.html#injectableid).  
-- You may use the 
-[@Inject](https://pcafstockf.github.io/async-injection/api-docs/globals.html#inject) decorator to explicitly declare which 
-[InjectableId](https://pcafstockf.github.io/async-injection/api-docs/globals.html#injectableid) should be used (generally required for a 
-[Constant](https://pcafstockf.github.io/async-injection/api-docs/container.html#bindconstant) binding as in the logLevel example above).
-- The 
-[@Optional](https://pcafstockf.github.io/async-injection/api-docs/globals.html#optional) decorator allows you to specify a default value for a class constructor parameter in the event that no matching 
-[InjectableId](https://pcafstockf.github.io/async-injection/api-docs/globals.html#injectableid) can be found.
-- The Container's 
-[resolveSingletons](https://pcafstockf.github.io/async-injection/api-docs/container.html#resolvesingletons) method may be used to wait for any bound (a)synchronous [Singletons](https://en.wikipedia.org/wiki/Singleton_pattern) to finish initialization before continuing execution of your application.
+## IoC modules
 
-## Acknowledgements
-Thanks to all the contributors at [InversifyJS](https://github.com/inversify/InversifyJS).  It is a powerful, clean, flexible, inspiring design.
+No special module system needed — TypeScript's own `import` is your module system.  Create a file, import your container, and register your bindings.
+
+## API
+
+A Container's life follows a simple arc: *configure* it by registering bindings, *activate* it so async singletons can initialize, then *use* it to retrieve objects.
 
-Thanks to everyone at [NestJS](https://docs.nestjs.com/fundamentals/async-providers) for giving us Asynchronous providers.
+#### Configure
 
-Thanks to Darcy Rayner for describing a [DI implementation](https://dev.to/darcyrayner/typescript-dependency-injection-in-200-loc-12j7) so simply and clearly.
+| |                                                                |
+|---|----------------------------------------------------------------|
+| `new Container(parent?)` | Create a container; optionally inherit bound ids from a parent |
+| `bindConstant(id, value)` | Bind a fixed value                                             |
+| `bindClass(id, class?)` | Bind a class (requires `@Injectable`)                          |
+| `bindFactory(id, fn)` | Bind a synchronous factory function                            |
+| `bindAsyncFactory(id, fn)` | Bind an asynchronous factory function                          |
+| `.asSingleton()` | Chain: share one instance across the Container                 |
+| `.onError(cb)` | Chain: handle construction errors                              |
 
-Thanks to Carlos Delgado for the idea of a ["QuerablePromise"](https://ourcodeworld.com/articles/read/317/how-to-check-if-a-javascript-promise-has-been-fulfilled-rejected-or-resolved) which allowed us to blend asynchronous DI with the simplicity of synchronous DI.
+#### Activate
 
-## MIT License
+| | |
+|---|---|
+| `resolveSingletons(true)` | Await all async singleton initializations |
+
+#### Use
+
+| | |
+|---|---|
+| `get(id)` | Synchronously retrieve a bound value |
+| `resolve(id)` | Asynchronously retrieve a bound value (see [`get` vs `resolve`](#get-vs-resolve)) |
+
+#### Annotate your classes
+
+| | |
+|---|---|
+| `@Injectable()` | Required on any class bound with `bindClass` |
+| `@Inject(id)` | Explicitly declare which id to inject into a constructor parameter |
+| `@Optional(default?)` | Provide a fallback if the id is not bound; omit the argument to let a JS parameter default apply |
+| `@PostConstruct()` | Mark a method to run after full construction (sync or async); parameters annotated with `@Inject`/`@Optional` are injected by the container |
+| `@Release()` | Mark a method to call when a singleton is released |
+| `InjectionToken<T>` | Create a typed token for binding interfaces or primitives |
+
+## Acknowledgements
 
-Copyright (c) 2020-2023 Frank Stock
+Inspired by [InversifyJS](https://github.com/inversify/InversifyJS), [NestJS async providers](https://docs.nestjs.com/fundamentals/async-providers), [Darcy Rayner's DI walkthrough](https://dev.to/darcyrayner/typescript-dependency-injection-in-200-loc-12j7), and Carlos Delgado's [QueryablePromise](https://ourcodeworld.com/articles/read/317/how-to-check-if-a-javascript-promise-has-been-fulfilled-rejected-or-resolved) idea.
 
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
+## Support Resources
+The [`support/`](./support) directory contains supplementary guides that are **not** part of the library itself:
+- [`lazy-loading/`](./support/lazy-loading.md) — patterns for on-demand, split-bundle DI module loading
+- [`react-integration/`](./support/react-integration.md) — using with React applications, including scoped child containers and testing patterns
+- [`migrate-from-inversify/`](./support/migrate-from-inversify/ReadMe.md) — shim files and a two-phase migration guide for InversifyJS users
+- [`migrate-from-tsyringe/`](./support/migrate-from-tsyringe.md) — migration guide for TSyringe users
+- [`migrate-from-typedi/`](./support/migrate-from-typedi.md) — migration guide for TypeDI users
 
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
+## License
 
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+[MIT](./License.txt) © 2020–2024 Frank Stock

package/lib/async-factory-provider.d.ts

@@ -1,7 +1,7 @@
-import { BindableProvider } from './bindable-provider.js';
-import { AsyncFactory } from './binder.js';
-import { InjectableId, Injector } from './injector.js';
-import { State } from './state.js';
+import { BindableProvider } from './bindable-provider';
+import { AsyncFactory } from './binding';
+import { InjectableId, Injector } from './injector';
+import { State } from './state';
 /**
  * @inheritDoc
  * This specialization invokes it's configured Factory asynchronously and waits until it can provide the result.

package/lib/bindable-provider.d.ts

@@ -1,6 +1,6 @@
-import { AsyncFactory, BindAs, OnErrorCallback, OnSuccessCallback, SyncFactory } from './binder.js';
-import { ClassConstructor, InjectableId, Injector } from './injector.js';
-import { Provider } from './provider.js';
+import { AsyncFactory, BindAs, OnErrorCallback, OnSuccessCallback, SyncFactory } from './binding';
+import { ClassConstructor, InjectableId, Injector } from './injector';
+import { Provider } from './provider';
 /**
  * @inheritDoc
  * This abstraction is for Providers that can be additionally configured as Singletons and/or configured with error and/or success handling callback(s).
@@ -21,7 +21,7 @@ export declare abstract class BindableProvider<T, M = ClassConstructor<T> | Sync
      */
     protected errorHandler?: OnErrorCallback<T, any>;
     /**
-     * Invoked by the Binder to create chain-able configuration
+     * Invoked by the Container to create chain-able configuration
      *
      * @see BindAs
      */

package/lib/binding.d.ts

@@ -0,0 +1,80 @@
+import { ClassConstructor, InjectableId, Injector } from './injector';
+/**
+ * Type definition for functions that return a value.
+ * The function should return a valid value, but may throw an exception if it cannot.
+ */
+export type SyncFactory<T> = (injector: Injector) => T;
+/**
+ * Type definition for functions that return a Promise for a value.
+ * The function *must* not throw and must return a valid Promise (e.g. pending, resolved, rejected).
+ */
+export type AsyncFactory<T> = (injector: Injector) => Promise<T>;
+/**
+ * You may bind an error handler which will be invoked if the bound InjectableId could not be put into service.
+ * An error handler *must* not throw, but may return an Error that will be propagated back up the call chain.
+ *
+ * @param injector   The Injector that experienced the error.
+ * @param id   The identifier for what was trying to be made.
+ * @param maker   The thing that made (or tried to make) the value.  Will be one of type ClassConstructor, SyncFactory, or AsyncFactory, depending on how you registered the binding.
+ * @param error   Identifies the problem that occurred.
+ * @param value   If the 'maker' was able to create the thing, but it had an error during post construction, the made thing will be passed here.
+ * @returns one of 3 results...
+ * A substitute thing (kind of like a 'maker' do-over) which must be fully operational (e.g. any `@PostConstruct` will be ignored).
+ * An alternate Error which will be propagated back up the call chain.
+ * Undefined, which means the 'error' parameter will be propagated back up the call chain.
+ */
+export type OnErrorCallback<T, M = unknown> = (injector: Injector, id: InjectableId<T>, maker: M, error: unknown, value?: T) => T | Error | void;
+/**
+ * You may bind a success handler which will be invoked just before the bound InjectableId is put into service.
+ * This is an alternative to the more preferred `@PostConstruct` decorator for scenarios when usage of that decorator is not feasible.
+ * WARNING:
+ * By registering a success handler, you override and nullify any `@PostConstruct` decorator on the class.
+ * In such a scenario, the success handler should perform whatever care and feeding the class expected from the `@PostConstruct` decorator.
+ * A success handler *must* not throw, but may return an Error that will be propagated back up the call chain.
+ *
+ * @param value   The thing that was made.
+ * @param injector   The Injector that performed the construction.
+ * @param id   The identifier for what was made.
+ * @param maker   The thing that made.  Will be one of type ClassConstructor, SyncFactory, or AsyncFactory, depending on how you registered the binding.
+ * @returns one of 3 results...
+ * An Error which will be propagated back up the call chain.
+ * Undefined, which means the object is ready to be placed into service.
+ * A Promise that resolves to one of the above two values (undefined or Error).
+ */
+export type OnSuccessCallback<T, M = unknown> = (value: T, injector: Injector, id: InjectableId<T>, maker: M) => Promise<Error | void> | Error | void;
+/**
+ * Descriptor object used with {@link Container.register} to specify how an id should be bound.
+ * Mirrors the TSyringe registration API.
+ */
+export type RegisterDescriptor<T> = {
+    useClass: ClassConstructor<T>;
+} | {
+    useValue: T;
+} | {
+    useFactory: SyncFactory<T>;
+} | {
+    useAsyncFactory: AsyncFactory<T>;
+};
+/**
+ * An interface allowing binding of an error handler.
+ *
+ * @see OnErrorCallback
+ */
+export interface BindErrHandler<T, M = unknown> {
+    onError(cb: OnErrorCallback<T, M>): void;
+}
+/**
+ * An interface allowing binding of a post construction handler.
+ *
+ * @see OnSuccessCallback
+ */
+export interface BindHandler<T, M = unknown> extends BindErrHandler<T, M> {
+    onSuccess(cb: OnSuccessCallback<T, M>): BindErrHandler<T, M>;
+}
+/**
+ * @inheritDoc
+ * This specialization also allows you to specify that the binding is 'Singleton' (e.g. only one in the system).
+ */
+export interface BindAs<T, M = unknown> extends BindHandler<T, M> {
+    asSingleton(): BindHandler<T, M>;
+}

package/lib/cjs/async-factory-provider.js

@@ -1,13 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AsyncFactoryBasedProvider = void 0;
-const bindable_provider_js_1 = require("./bindable-provider.js");
-const state_js_1 = require("./state.js");
+const bindable_provider_1 = require("./bindable-provider");
+const state_1 = require("./state");
 /**
  * @inheritDoc
  * This specialization invokes it's configured Factory asynchronously and waits until it can provide the result.
  */
-class AsyncFactoryBasedProvider extends bindable_provider_js_1.BindableProvider {
+class AsyncFactoryBasedProvider extends bindable_provider_1.BindableProvider {
     constructor(injector, id, maker) {
         super(injector, id, maker);
     }
@@ -19,8 +19,8 @@ class AsyncFactoryBasedProvider extends bindable_provider_js_1.BindableProvider
         let retVal = this.singleton;
         if (!retVal) {
             // Wrap the async factory's Promise in an errorHandler aware Promise.
-            // Our contract is that an AsyncFactory may not throw and must return a valid Promise (e.g. pending, resolved, rejected, etc).
-            retVal = state_js_1.State.MakeState(this.makePromiseForObj(this.maker(this.injector), obj => obj));
+            // Our contract is that an AsyncFactory may not throw and must return a valid Promise (e.g., pending, resolved, rejected, etc).
+            retVal = state_1.State.MakeState(this.makePromiseForObj(this.maker(this.injector), obj => obj));
         }
         if (this.singleton === null)
             this.singleton = retVal;

package/lib/cjs/async-factory-provider.js.map

@@ -1 +1 @@
-{"version":3,"file":"async-factory-provider.js","sourceRoot":"","sources":["../../src/async-factory-provider.ts"],"names":[],"mappings":";;;AAAA,iEAAwD;AAGxD,yCAAiC;AAEjC;;;GAGG;AACH,MAAa,yBAA6B,SAAQ,uCAAoC;IACrF,YAAY,QAAkB,EAAE,EAAmB,EAAE,KAAsB;QAC1E,KAAK,CAAC,QAAQ,EAAE,EAAE,EAAE,KAAK,CAAC,CAAC;IAC5B,CAAC;IAED;;;OAGG;IACH,cAAc;QACb,IAAI,MAAM,GAAG,IAAI,CAAC,SAAS,CAAC;QAC5B,IAAI,CAAC,MAAM,EAAE;YACZ,qEAAqE;YACrE,8HAA8H;YAC9H,MAAM,GAAG,gBAAK,CAAC,SAAS,CAAI,IAAI,CAAC,iBAAiB,CAAI,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;SAC9F;QACD,IAAI,IAAI,CAAC,SAAS,KAAK,IAAI;YAC1B,IAAI,CAAC,SAAS,GAAG,MAAM,CAAC;QACzB,OAAO,MAAM,CAAC;IACf,CAAC;CACD;AApBD,8DAoBC","sourcesContent":["import {BindableProvider} from './bindable-provider.js';\nimport {AsyncFactory} from './binder.js';\nimport {InjectableId, Injector} from './injector.js';\nimport {State} from './state.js';\n\n/**\n * @inheritDoc\n * This specialization invokes it's configured Factory asynchronously and waits until it can provide the result.\n */\nexport class AsyncFactoryBasedProvider<T> extends BindableProvider<T, AsyncFactory<T>> {\n\tconstructor(injector: Injector, id: InjectableId<T>, maker: AsyncFactory<T>) {\n\t\tsuper(injector, id, maker);\n\t}\n\n\t/**\n\t * @inheritDoc\n\t * This specialization invokes it's configured Factory and provides the result (or invokes the error handler if necessary).\n\t */\n\tprovideAsState(): State<T> {\n\t\tlet retVal = this.singleton;\n\t\tif (!retVal) {\n\t\t\t// Wrap the async factory's Promise in an errorHandler aware Promise.\n\t\t\t// Our contract is that an AsyncFactory may not throw and must return a valid Promise (e.g. pending, resolved, rejected, etc).\n\t\t\tretVal = State.MakeState<T>(this.makePromiseForObj<T>(this.maker(this.injector), obj => obj));\n\t\t}\n\t\tif (this.singleton === null)\n\t\t\tthis.singleton = retVal;\n\t\treturn retVal;\n\t}\n}\n"]}
+{"version":3,"file":"async-factory-provider.js","sourceRoot":"","sources":["../../src/async-factory-provider.ts"],"names":[],"mappings":";;;AAAA,2DAAqD;AAGrD,mCAA8B;AAE9B;;;GAGG;AACH,MAAa,yBAA6B,SAAQ,oCAAoC;IACrF,YAAY,QAAkB,EAAE,EAAmB,EAAE,KAAsB;QAC1E,KAAK,CAAC,QAAQ,EAAE,EAAE,EAAE,KAAK,CAAC,CAAC;IAC5B,CAAC;IAED;;;OAGG;IACH,cAAc;QACb,IAAI,MAAM,GAAG,IAAI,CAAC,SAAS,CAAC;QAC5B,IAAI,CAAC,MAAM,EAAE,CAAC;YACb,qEAAqE;YACrE,+HAA+H;YAC/H,MAAM,GAAG,aAAK,CAAC,SAAS,CAAI,IAAI,CAAC,iBAAiB,CAAI,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;QAC/F,CAAC;QACD,IAAI,IAAI,CAAC,SAAS,KAAK,IAAI;YAC1B,IAAI,CAAC,SAAS,GAAG,MAAM,CAAC;QACzB,OAAO,MAAM,CAAC;IACf,CAAC;CACD;AApBD,8DAoBC","sourcesContent":["import {BindableProvider} from './bindable-provider';\nimport {AsyncFactory} from './binding';\nimport {InjectableId, Injector} from './injector';\nimport {State} from './state';\n\n/**\n * @inheritDoc\n * This specialization invokes it's configured Factory asynchronously and waits until it can provide the result.\n */\nexport class AsyncFactoryBasedProvider<T> extends BindableProvider<T, AsyncFactory<T>> {\n\tconstructor(injector: Injector, id: InjectableId<T>, maker: AsyncFactory<T>) {\n\t\tsuper(injector, id, maker);\n\t}\n\n\t/**\n\t * @inheritDoc\n\t * This specialization invokes it's configured Factory and provides the result (or invokes the error handler if necessary).\n\t */\n\tprovideAsState(): State<T> {\n\t\tlet retVal = this.singleton;\n\t\tif (!retVal) {\n\t\t\t// Wrap the async factory's Promise in an errorHandler aware Promise.\n\t\t\t// Our contract is that an AsyncFactory may not throw and must return a valid Promise (e.g., pending, resolved, rejected, etc).\n\t\t\tretVal = State.MakeState<T>(this.makePromiseForObj<T>(this.maker(this.injector), obj => obj));\n\t\t}\n\t\tif (this.singleton === null)\n\t\t\tthis.singleton = retVal;\n\t\treturn retVal;\n\t}\n}\n"]}