async-injection 1.2.4 → 1.3.0

package/Changelog.md

@@ -2,7 +2,7 @@
 Fix issue #1  
 Update ts-node and source-map-support devDependencies  
 Add tslint and Changelog  
-Update ReadMe with badges
+Update ReadMe with badges  
 
 **1.0.8 / 2020-06-08**  
 Add ability to walk up the parent container hierarchy to methods Injector.isIdKnown and Container.removeBinding  
@@ -13,3 +13,45 @@ Update ts-node and nyc devDependencies.
 Add post construction handling feature to Binder.bindClass.  This is for scenarios where it is not feasible to add the @PostConstruct decorator to the target class.  
 Updated tslib  
 Updated jasmine devDependency.  
+
+**1.2.0 / 2021-06-08**  
+New Feature: Allow alternate polyfill for Reflect API  
+WARNING: This is a a breaking change release.  
+The API and code have not changed, but you will need to explicitly import a polyfill into your own code in order to use this release (see the ReadMe).  
+Previously Async-Injection relied on reflect-metadata (which is still supported), but this release also allows for the use of alternative implementations such as:  
+    core-js (core-js/es7/reflect)
+    reflection
+Thank you to @tripodsgames for this contribution.  
+
+**1.2.3 / 2021-06-11**  
+cjs and esm distributions.  
+Build now generates both cjs and esm distributions.  
+tslib (where used) is now inlined instead of imported.  
+No other code changes.  
+
+**1.2.4 / 2021-06-17**  
+Build esm into esm dir (not mjs).  
+No actual source code changes.  
+
+**1.2.5 / 2021-06-28**  
+No actual source code changes.  
+Added Reflect type from reflect-metadata in order to remove the @ts-ignore comments.  
+Improved tsconfig.json structure for IDE compatibility.  
+Thanks to @tripodsgames for those contributions.  
+Update tsc devDependency from 4.3.3 to 4.3.4.  
+Update the ChangeLog to properly reflect recent GitHub releases.  
+
+**1.2.6 / 2021-07-14**  
+Merge PR #9 [ESLINT integration + Improvements](https://github.com/pcafstockf/async-injection/pull/9).  
+Update devDependencies.  
+Resolved a couple of eslint warnings.  
+tsc no longer removes comments in generated code.  This can cause problems with post-processing tools such as istanbul. If file size is of concern to you, you should probably be minifying anyway.  
+
+**1.2.7 / 2021-08-02**  
+Revert type declaration for AbstractConstructor which was broken during eslint integration.  
+Update eslint related dev-dependencies.
+
+**1.3.0 / 2021-11-27**  
+Support Container driven release of Singleton allocated resources (see Container.releaseSingletons).  
+Update devDependencies.  
+Minor updates to ReadMe.

package/ReadMe.md

@@ -18,7 +18,8 @@ You can get the latest release using npm:
 $ npm install async-injection --save
 ```
 
-Add a polyfill for the Reflect API (examples below use reflect-metadata). You can use:
+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:
 
 - [reflect-metadata](https://www.npmjs.com/package/reflect-metadata)
 - [core-js (core-js/es7/reflect)](https://www.npmjs.com/package/core-js)
@@ -32,6 +33,9 @@ import "reflect-metadata";
 // Your code here...
 ```
 
+Please note that this library supports a wide variety of runtimes and is distributed as both esm and cjs modules, side by side.  
+Please see this [link](https://github.com/pcafstockf/async-injection/issues/10) if you experience module errors when compiling.
+
 ## Basic Usage (synchronous)
 Here we 'get' a new transaction handling object, that itself, relies on a shared service:
 
@@ -233,7 +237,7 @@ Thanks to Carlos Delgado for the idea of a ["QuerablePromise"](https://ourcodewo
 
 ## MIT License
 
-Copyright (c) 2020 Frank Stock
+Copyright (c) 2021 Frank Stock
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

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

@@ -1,8 +1,16 @@
-import { InjectableId, Injector } from './injector';
+import { BindableProvider } from './bindable-provider';
 import { AsyncFactory } from './binder';
+import { InjectableId, Injector } from './injector';
 import { State } from './state';
-import { BindableProvider } from './bindable-provider';
+/**
+ * @inheritDoc
+ * This specialization invokes it's configured Factory asynchronously and waits until it can provide the result.
+ */
 export declare class AsyncFactoryBasedProvider<T> extends BindableProvider<T, AsyncFactory<T>> {
     constructor(injector: Injector, id: InjectableId<T>, maker: AsyncFactory<T>);
+    /**
+     * @inheritDoc
+     * This specialization invokes it's configured Factory and provides the result (or invokes the error handler if necessary).
+     */
     provideAsState(): State<T>;
 }

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

@@ -1,15 +1,25 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AsyncFactoryBasedProvider = void 0;
-const state_1 = require("./state");
 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_1.BindableProvider {
     constructor(injector, id, maker) {
         super(injector, id, maker);
     }
+    /**
+     * @inheritDoc
+     * This specialization invokes it's configured Factory and provides the result (or invokes the error handler if necessary).
+     */
     provideAsState() {
         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_1.State.MakeState(this.makePromiseForObj(this.maker(this.injector), obj => obj));
         }
         if (this.singleton === null)

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":";;;AAEA,mCAA8B;AAC9B,2DAAqD;AAMrD,MAAa,yBAA6B,SAAQ,oCAAoC;IACrF,YAAY,QAAkB,EAAE,EAAmB,EAAE,KAAsB;QAC1E,KAAK,CAAC,QAAQ,EAAE,EAAE,EAAE,KAAK,CAAC,CAAC;IAC5B,CAAC;IAMD,cAAc;QACb,IAAI,MAAM,GAAG,IAAI,CAAC,SAAS,CAAC;QAC5B,IAAI,CAAC,MAAM,EAAE;YAGZ,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;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 {InjectableId, Injector} from './injector';\nimport {AsyncFactory} from './binder';\nimport {State} from './state';\nimport {BindableProvider} from './bindable-provider';\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,2DAAuD;AAGvD,mCAAgC;AAEhC;;;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;YACZ,qEAAqE;YACrE,8HAA8H;YAC9H,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;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';\nimport { AsyncFactory } from './binder';\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"]}

package/lib/cjs/bindable-provider.d.ts

@@ -1,14 +1,46 @@
-import { InjectableId, Injector, ClassConstructor } from './injector';
 import { AsyncFactory, BindAs, OnErrorCallback, OnSuccessCallback, SyncFactory } from './binder';
+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).
+ */
 export declare abstract class BindableProvider<T, M = ClassConstructor<T> | SyncFactory<T> | AsyncFactory<T>> extends Provider<T> {
     protected injector: Injector;
     protected id: InjectableId<T>;
     protected maker: M;
     protected constructor(injector: Injector, id: InjectableId<T>, maker: M);
+    /**
+     * A user supplied success handling function.
+     * Default value is undefined.
+     */
     protected successHandler?: OnSuccessCallback<T, any>;
+    /**
+     * A user supplied error handling function.
+     * Default value is undefined.
+     */
     protected errorHandler?: OnErrorCallback<T, any>;
+    /**
+     * Invoked by the Binder to create chain-able configuration
+     *
+     * @see BindAs
+     */
     makeBindAs(): BindAs<T, M>;
-    protected queryErrorHandler(err: Error, obj?: any): T;
+    /**
+     * Encapsulate the logic of invoking any configured error handler, and processing it's result.
+     *
+     * @see OnErrorCallback
+     *
+     * @returns The object substituted by the callback (otherwise this method throws the appropriate error).
+     */
+    protected queryErrorHandler(err: Error, obj?: T): T;
+    /**
+     * This is like a retry mechanism that uses the Provider's errorHandler (if any) to attempt recovery whenever the supplied Promise rejects.
+     * This method returns a Promise that rejects if recovery was not possible.
+     * If the supplied Promise resolves, then this method passes the result to the callback, and then resolve as whatever that callback returns.
+     *
+     * @param waitFor   The supplied Promise.
+     * @param cb    Callback to be invoked if the supplied Promise resolves.
+     */
     protected makePromiseForObj<R>(waitFor: Promise<R>, cb: (result: R) => T): Promise<T>;
 }

package/lib/cjs/bindable-provider.js

@@ -2,11 +2,11 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.BindableProvider = void 0;
 const provider_1 = require("./provider");
-function isErrorObj(err) {
-    if (err instanceof Error)
-        return true;
-    return err && typeof err.message === 'string' && typeof err.stack === 'string';
-}
+const utils_1 = require("./utils");
+/**
+ * @inheritDoc
+ * This abstraction is for Providers that can be additionally configured as Singletons and/or configured with error and/or success handling callback(s).
+ */
 class BindableProvider extends provider_1.Provider {
     constructor(injector, id, maker) {
         super();
@@ -14,47 +14,77 @@ class BindableProvider extends provider_1.Provider {
         this.id = id;
         this.maker = maker;
     }
+    /**
+     * Invoked by the Binder to create chain-able configuration
+     *
+     * @see BindAs
+     */
     makeBindAs() {
-        let retVal = {};
-        retVal.onError = (cb) => {
-            this.errorHandler = cb;
-        };
-        retVal.onSuccess = (cb) => {
-            this.successHandler = cb;
-            return retVal;
-        };
-        retVal.asSingleton = () => {
-            this.singleton = null;
-            return retVal;
+        const retVal = {
+            onError: (cb) => {
+                this.errorHandler = cb;
+            },
+            onSuccess: (cb) => {
+                this.successHandler = cb;
+                return retVal;
+            },
+            asSingleton: () => {
+                this.singleton = null; // Flag state as no longer undefined.
+                return retVal;
+            }
         };
         return retVal;
     }
+    /**
+     * Encapsulate the logic of invoking any configured error handler, and processing it's result.
+     *
+     * @see OnErrorCallback
+     *
+     * @returns The object substituted by the callback (otherwise this method throws the appropriate error).
+     */
     queryErrorHandler(err, obj) {
+        // There was an error during construction, see if an error handler was provided, and if so, see what it wants to do.
         if (this.errorHandler) {
-            let handlerResult = this.errorHandler(this.injector, this.id, this.maker, err, obj);
-            if (isErrorObj(handlerResult))
+            const handlerResult = this.errorHandler(this.injector, this.id, this.maker, err, obj);
+            // Error handler wants us to propagate an error.
+            if (utils_1.isErrorObj(handlerResult))
                 throw handlerResult;
+            // Error handler has no opinion, so provideAsState a state that reflects the error we just caught.
             if (typeof handlerResult === 'undefined')
                 throw err;
+            // Error handler provided a valid (fully resolved) replacement.
             return handlerResult;
         }
+        // No error handler, provideAsState a state that reflects the error we just caught.
         throw err;
     }
+    /**
+     * This is like a retry mechanism that uses the Provider's errorHandler (if any) to attempt recovery whenever the supplied Promise rejects.
+     * This method returns a Promise that rejects if recovery was not possible.
+     * If the supplied Promise resolves, then this method passes the result to the callback, and then resolve as whatever that callback returns.
+     *
+     * @param waitFor   The supplied Promise.
+     * @param cb    Callback to be invoked if the supplied Promise resolves.
+     */
     makePromiseForObj(waitFor, cb) {
         return new Promise((resolve, reject) => {
             const errHandlerFn = (err) => {
+                // There was an error during async post construction, see if an error handler was provided, and if so, see what it wants to do.
                 if (this.errorHandler) {
-                    let handlerResult = this.errorHandler(this.injector, this.id, this.maker, err);
-                    if (isErrorObj(handlerResult))
-                        err = handlerResult;
+                    const handlerResult = this.errorHandler(this.injector, this.id, this.maker, err);
+                    // Error handler wants us to propagate an alternative error.
+                    if (utils_1.isErrorObj(handlerResult))
+                        err = handlerResult; // Fall thru
                     else if (typeof handlerResult !== 'undefined') {
-                        resolve(handlerResult);
+                        resolve(handlerResult); // Error handler provided a replacement, so change the State that we returned from pending to resolved.
                         return;
                     }
                 }
+                // This will change the State that we returned from pending to rejected.
                 reject(err);
             };
             waitFor.then((result) => {
+                // This will change the State that we returned from pending to resolved.
                 try {
                     resolve(cb(result));
                 }

package/lib/cjs/bindable-provider.js.map

@@ -1 +1 @@
-{"version":3,"file":"bindable-provider.js","sourceRoot":"","sources":["../../src/bindable-provider.ts"],"names":[],"mappings":";;;AAEA,yCAAoC;AAEpC,SAAS,UAAU,CAAC,GAAQ;IAC3B,IAAI,GAAG,YAAY,KAAK;QACvB,OAAO,IAAI,CAAC;IACb,OAAO,GAAG,IAAI,OAAO,GAAG,CAAC,OAAO,KAAK,QAAQ,IAAI,OAAO,GAAG,CAAC,KAAK,KAAK,QAAQ,CAAC;AAChF,CAAC;AAMD,MAAsB,gBAAgF,SAAQ,mBAAW;IACxH,YAAgC,QAAkB,EAAY,EAAmB,EAAY,KAAQ;QACpG,KAAK,EAAE,CAAC;QADuB,aAAQ,GAAR,QAAQ,CAAU;QAAY,OAAE,GAAF,EAAE,CAAiB;QAAY,UAAK,GAAL,KAAK,CAAG;IAErG,CAAC;IAkBD,UAAU;QACT,IAAI,MAAM,GAAiB,EAAE,CAAC;QAC9B,MAAM,CAAC,OAAO,GAAG,CAAC,EAAyB,EAAE,EAAE;YAC9C,IAAI,CAAC,YAAY,GAAG,EAAE,CAAC;QACxB,CAAC,CAAC;QACF,MAAM,CAAC,SAAS,GAAG,CAAC,EAA2B,EAAE,EAAE;YAClD,IAAI,CAAC,cAAc,GAAG,EAAE,CAAC;YACzB,OAAO,MAAM,CAAC;QACf,CAAC,CAAC;QACF,MAAM,CAAC,WAAW,GAAG,GAAG,EAAE;YACzB,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC;YACtB,OAAO,MAAM,CAAC;QACf,CAAC,CAAC;QACF,OAAO,MAAM,CAAC;IACf,CAAC;IAQS,iBAAiB,CAAC,GAAU,EAAE,GAAS;QAEhD,IAAI,IAAI,CAAC,YAAY,EAAE;YACtB,IAAI,aAAa,GAAG,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,EAAE,EAAE,IAAI,CAAC,KAAK,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC;YAEpF,IAAI,UAAU,CAAC,aAAa,CAAC;gBAC5B,MAAM,aAAa,CAAC;YAErB,IAAI,OAAO,aAAa,KAAK,WAAW;gBACvC,MAAM,GAAG,CAAC;YAEX,OAAU,aAAa,CAAC;SACxB;QAED,MAAM,GAAG,CAAC;IACX,CAAC;IAUS,iBAAiB,CAAI,OAAmB,EAAE,EAAoB;QACvE,OAAO,IAAI,OAAO,CAAI,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;YACzC,MAAM,YAAY,GAAG,CAAC,GAAQ,EAAE,EAAE;gBAEjC,IAAI,IAAI,CAAC,YAAY,EAAE;oBACtB,IAAI,aAAa,GAAG,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,EAAE,EAAE,IAAI,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;oBAE/E,IAAI,UAAU,CAAC,aAAa,CAAC;wBAC5B,GAAG,GAAG,aAAa,CAAC;yBAChB,IAAI,OAAO,aAAa,KAAK,WAAW,EAAE;wBAC9C,OAAO,CAAI,aAAa,CAAC,CAAC;wBAC1B,OAAO;qBACP;iBACD;gBAED,MAAM,CAAC,GAAG,CAAC,CAAC;YACb,CAAC,CAAC;YACF,OAAO,CAAC,IAAI,CACX,CAAC,MAAM,EAAE,EAAE;gBAEV,IAAI;oBACH,OAAO,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC;iBACpB;gBACD,OAAO,GAAG,EAAE;oBACX,YAAY,CAAC,GAAG,CAAC,CAAC;iBAClB;YACF,CAAC,CACD,CAAC,KAAK,CACN,CAAC,GAAG,EAAE,EAAE;gBACP,YAAY,CAAC,GAAG,CAAC,CAAC;YACnB,CAAC,CACD,CAAC;QACH,CAAC,CAAC,CAAC;IACJ,CAAC;CACD;AAtGD,4CAsGC","sourcesContent":["import {InjectableId, Injector, ClassConstructor} from './injector';\nimport {AsyncFactory, BindAs, OnErrorCallback, OnSuccessCallback, SyncFactory} from './binder';\nimport {Provider} from './provider';\n\nfunction isErrorObj(err: any): boolean {\n\tif (err instanceof Error)\n\t\treturn true;\n\treturn err && typeof err.message === 'string' && typeof err.stack === 'string';\n}\n\n/**\n * @inheritDoc\n * This abstraction is for Providers that can be additionally configured as Singletons and/or configured with error and/or success handling callback(s).\n */\nexport abstract class BindableProvider<T, M = ClassConstructor<T> | SyncFactory<T> | AsyncFactory<T>> extends Provider<T> {\n\tprotected constructor(protected injector: Injector, protected id: InjectableId<T>, protected maker: M) {\n\t\tsuper();\n\t}\n\n\t/**\n\t * A user supplied success handling function.\n\t * Default value is undefined.\n\t */\n\tprotected successHandler?: OnSuccessCallback<T, any>;\n\n\t/**\n\t * A user supplied error handling function.\n\t * Default value is undefined.\n\t */\n\tprotected errorHandler?: OnErrorCallback<T, any>;\n\n\t/**\n\t * Invoked by the Binder to create chain-able configuration\n\t * @see BindAs\n\t */\n\tmakeBindAs(): BindAs<T, M> {\n\t\tlet retVal = <BindAs<T, M>>{};\n\t\tretVal.onError = (cb: OnErrorCallback<T, M>) => {\n\t\t\tthis.errorHandler = cb;\n\t\t};\n\t\tretVal.onSuccess = (cb: OnSuccessCallback<T, M>) => {\n\t\t\tthis.successHandler = cb;\n\t\t\treturn retVal;\n\t\t};\n\t\tretVal.asSingleton = () => {\n\t\t\tthis.singleton = null; // Flag state as no longer undefined.\n\t\t\treturn retVal;\n\t\t};\n\t\treturn retVal;\n\t}\n\n\t/**\n\t * Encapsulate the logic of invoking any configured error handler, and processing it's result.\n\t * @see OnErrorCallback\n\t *\n\t * @returns The object substituted by the callback (otherwise this method throws the appropriate error).\n\t */\n\tprotected queryErrorHandler(err: Error, obj?: any): T {\n\t\t// There was an error during construction, see if an error handler was provided, and if so, see what it wants to do.\n\t\tif (this.errorHandler) {\n\t\t\tlet handlerResult = this.errorHandler(this.injector, this.id, this.maker, err, obj);\n\t\t\t// Error handler wants us to propagate an error.\n\t\t\tif (isErrorObj(handlerResult))\n\t\t\t\tthrow handlerResult;\n\t\t\t// Error handler has no opinion, so provideAsState a state that reflects the error we just caught.\n\t\t\tif (typeof handlerResult === 'undefined')\n\t\t\t\tthrow err;\n\t\t\t// Error handler provided a valid (fully resolved) replacement.\n\t\t\treturn <T>handlerResult;\n\t\t}\n\t\t// No error handler, provideAsState a state that reflects the error we just caught.\n\t\tthrow err;\n\t}\n\n\t/**\n\t * This is like a retry mechanism that uses the Provider's errorHandler (if any) to attempt recovery whenever the supplied Promise rejects.\n\t * This method returns a Promise that rejects if recovery was not possible.\n\t * If the supplied Promise resolves, then this method passes the result to the callback, and then resolve as whatever that callback returns.\n\t *\n\t * @param waitFor   The supplied Promise.\n\t * @param cb    Callback to be invoked if the supplied Promise resolves.\n\t */\n\tprotected makePromiseForObj<R>(waitFor: Promise<R>, cb: (result: R) => T) {\n\t\treturn new Promise<T>((resolve, reject) => {\n\t\t\tconst errHandlerFn = (err: any) => {\n\t\t\t\t// There was an error during async post construction, see if an error handler was provided, and if so, see what it wants to do.\n\t\t\t\tif (this.errorHandler) {\n\t\t\t\t\tlet handlerResult = this.errorHandler(this.injector, this.id, this.maker, err);\n\t\t\t\t\t// Error handler wants us to propagate an alternative error.\n\t\t\t\t\tif (isErrorObj(handlerResult))\n\t\t\t\t\t\terr = handlerResult;   // Fall thru\n\t\t\t\t\telse if (typeof handlerResult !== 'undefined') {\n\t\t\t\t\t\tresolve(<T>handlerResult);    // Error handler provided a replacement, so change the State that we returned from pending to resolved.\n\t\t\t\t\t\treturn;\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t\t// This will change the State that we returned from pending to rejected.\n\t\t\t\treject(err);\n\t\t\t};\n\t\t\twaitFor.then(\n\t\t\t\t(result) => {\n\t\t\t\t\t// This will change the State that we returned from pending to resolved.\n\t\t\t\t\ttry {\n\t\t\t\t\t\tresolve(cb(result));\n\t\t\t\t\t}\n\t\t\t\t\tcatch (err) {\n\t\t\t\t\t\terrHandlerFn(err);\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t).catch(\n\t\t\t\t(err) => {\n\t\t\t\t\terrHandlerFn(err);\n\t\t\t\t}\n\t\t\t);\n\t\t});\n\t}\n}\n"]}
+{"version":3,"file":"bindable-provider.js","sourceRoot":"","sources":["../../src/bindable-provider.ts"],"names":[],"mappings":";;;AAEA,yCAAsC;AACtC,mCAAqC;AAErC;;;GAGG;AACH,MAAsB,gBAAgF,SAAQ,mBAAW;IACxH,YAAgC,QAAkB,EAAY,EAAmB,EAAY,KAAQ;QACpG,KAAK,EAAE,CAAC;QADuB,aAAQ,GAAR,QAAQ,CAAU;QAAY,OAAE,GAAF,EAAE,CAAiB;QAAY,UAAK,GAAL,KAAK,CAAG;IAErG,CAAC;IAcD;;;;OAIG;IACH,UAAU;QACT,MAAM,MAAM,GAAiB;YAC5B,OAAO,EAAE,CAAC,EAAyB,EAAE,EAAE;gBACtC,IAAI,CAAC,YAAY,GAAG,EAAE,CAAC;YACxB,CAAC;YACD,SAAS,EAAE,CAAC,EAA2B,EAAE,EAAE;gBAC1C,IAAI,CAAC,cAAc,GAAG,EAAE,CAAC;gBACzB,OAAO,MAAM,CAAC;YACf,CAAC;YACD,WAAW,EAAE,GAAG,EAAE;gBACjB,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,CAAC,qCAAqC;gBAC5D,OAAO,MAAM,CAAC;YACf,CAAC;SACD,CAAC;QACF,OAAO,MAAM,CAAC;IACf,CAAC;IAED;;;;;;OAMG;IACO,iBAAiB,CAAC,GAAU,EAAE,GAAO;QAC9C,oHAAoH;QACpH,IAAI,IAAI,CAAC,YAAY,EAAE;YACtB,MAAM,aAAa,GAAG,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,EAAE,EAAE,IAAI,CAAC,KAAK,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC;YACtF,gDAAgD;YAChD,IAAI,kBAAU,CAAC,aAAa,CAAC;gBAC5B,MAAM,aAAa,CAAC;YACrB,kGAAkG;YAClG,IAAI,OAAO,aAAa,KAAK,WAAW;gBACvC,MAAM,GAAG,CAAC;YACX,+DAA+D;YAC/D,OAAO,aAAa,CAAC;SACrB;QACD,mFAAmF;QACnF,MAAM,GAAG,CAAC;IACX,CAAC;IAED;;;;;;;OAOG;IACO,iBAAiB,CAAI,OAAmB,EAAE,EAAoB;QACvE,OAAO,IAAI,OAAO,CAAI,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;YACzC,MAAM,YAAY,GAAG,CAAC,GAAQ,EAAE,EAAE;gBACjC,+HAA+H;gBAC/H,IAAI,IAAI,CAAC,YAAY,EAAE;oBACtB,MAAM,aAAa,GAAG,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,EAAE,EAAE,IAAI,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;oBACjF,4DAA4D;oBAC5D,IAAI,kBAAU,CAAC,aAAa,CAAC;wBAC5B,GAAG,GAAG,aAAa,CAAC,CAAG,YAAY;yBAC/B,IAAI,OAAO,aAAa,KAAK,WAAW,EAAE;wBAC9C,OAAO,CAAC,aAAa,CAAC,CAAC,CAAI,uGAAuG;wBAClI,OAAO;qBACP;iBACD;gBACD,wEAAwE;gBACxE,MAAM,CAAC,GAAG,CAAC,CAAC;YACb,CAAC,CAAC;YACF,OAAO,CAAC,IAAI,CACX,CAAC,MAAM,EAAE,EAAE;gBACV,wEAAwE;gBACxE,IAAI;oBACH,OAAO,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC;iBACpB;gBACD,OAAO,GAAG,EAAE;oBACX,YAAY,CAAC,GAAG,CAAC,CAAC;iBAClB;YACF,CAAC,CACD,CAAC,KAAK,CACN,CAAC,GAAG,EAAE,EAAE;gBACP,YAAY,CAAC,GAAG,CAAC,CAAC;YACnB,CAAC,CACD,CAAC;QACH,CAAC,CAAC,CAAC;IACJ,CAAC;CACD;AAzGD,4CAyGC","sourcesContent":["import { AsyncFactory, BindAs, OnErrorCallback, OnSuccessCallback, SyncFactory } from './binder';\nimport { ClassConstructor, InjectableId, Injector } from './injector';\nimport { Provider } from './provider';\nimport { isErrorObj } from './utils';\n\n/**\n * @inheritDoc\n * This abstraction is for Providers that can be additionally configured as Singletons and/or configured with error and/or success handling callback(s).\n */\nexport abstract class BindableProvider<T, M = ClassConstructor<T> | SyncFactory<T> | AsyncFactory<T>> extends Provider<T> {\n\tprotected constructor(protected injector: Injector, protected id: InjectableId<T>, protected maker: M) {\n\t\tsuper();\n\t}\n\n\t/**\n\t * A user supplied success handling function.\n\t * Default value is undefined.\n\t */\n\tprotected successHandler?: OnSuccessCallback<T, any>;\n\n\t/**\n\t * A user supplied error handling function.\n\t * Default value is undefined.\n\t */\n\tprotected errorHandler?: OnErrorCallback<T, any>;\n\n\t/**\n\t * Invoked by the Binder to create chain-able configuration\n\t *\n\t * @see BindAs\n\t */\n\tmakeBindAs(): BindAs<T, M> {\n\t\tconst retVal: BindAs<T, M> = {\n\t\t\tonError: (cb: OnErrorCallback<T, M>) => {\n\t\t\t\tthis.errorHandler = cb;\n\t\t\t},\n\t\t\tonSuccess: (cb: OnSuccessCallback<T, M>) => {\n\t\t\t\tthis.successHandler = cb;\n\t\t\t\treturn retVal;\n\t\t\t},\n\t\t\tasSingleton: () => {\n\t\t\t\tthis.singleton = null; // Flag state as no longer undefined.\n\t\t\t\treturn retVal;\n\t\t\t}\n\t\t};\n\t\treturn retVal;\n\t}\n\n\t/**\n\t * Encapsulate the logic of invoking any configured error handler, and processing it's result.\n\t *\n\t * @see OnErrorCallback\n\t *\n\t * @returns The object substituted by the callback (otherwise this method throws the appropriate error).\n\t */\n\tprotected queryErrorHandler(err: Error, obj?: T): T {\n\t\t// There was an error during construction, see if an error handler was provided, and if so, see what it wants to do.\n\t\tif (this.errorHandler) {\n\t\t\tconst handlerResult = this.errorHandler(this.injector, this.id, this.maker, err, obj);\n\t\t\t// Error handler wants us to propagate an error.\n\t\t\tif (isErrorObj(handlerResult))\n\t\t\t\tthrow handlerResult;\n\t\t\t// Error handler has no opinion, so provideAsState a state that reflects the error we just caught.\n\t\t\tif (typeof handlerResult === 'undefined')\n\t\t\t\tthrow err;\n\t\t\t// Error handler provided a valid (fully resolved) replacement.\n\t\t\treturn handlerResult;\n\t\t}\n\t\t// No error handler, provideAsState a state that reflects the error we just caught.\n\t\tthrow err;\n\t}\n\n\t/**\n\t * This is like a retry mechanism that uses the Provider's errorHandler (if any) to attempt recovery whenever the supplied Promise rejects.\n\t * This method returns a Promise that rejects if recovery was not possible.\n\t * If the supplied Promise resolves, then this method passes the result to the callback, and then resolve as whatever that callback returns.\n\t *\n\t * @param waitFor   The supplied Promise.\n\t * @param cb    Callback to be invoked if the supplied Promise resolves.\n\t */\n\tprotected makePromiseForObj<R>(waitFor: Promise<R>, cb: (result: R) => T): Promise<T> {\n\t\treturn new Promise<T>((resolve, reject) => {\n\t\t\tconst errHandlerFn = (err: any) => {\n\t\t\t\t// There was an error during async post construction, see if an error handler was provided, and if so, see what it wants to do.\n\t\t\t\tif (this.errorHandler) {\n\t\t\t\t\tconst handlerResult = this.errorHandler(this.injector, this.id, this.maker, err);\n\t\t\t\t\t// Error handler wants us to propagate an alternative error.\n\t\t\t\t\tif (isErrorObj(handlerResult))\n\t\t\t\t\t\terr = handlerResult;   // Fall thru\n\t\t\t\t\telse if (typeof handlerResult !== 'undefined') {\n\t\t\t\t\t\tresolve(handlerResult);    // Error handler provided a replacement, so change the State that we returned from pending to resolved.\n\t\t\t\t\t\treturn;\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t\t// This will change the State that we returned from pending to rejected.\n\t\t\t\treject(err);\n\t\t\t};\n\t\t\twaitFor.then(\n\t\t\t\t(result) => {\n\t\t\t\t\t// This will change the State that we returned from pending to resolved.\n\t\t\t\t\ttry {\n\t\t\t\t\t\tresolve(cb(result));\n\t\t\t\t\t}\n\t\t\t\t\tcatch (err) {\n\t\t\t\t\t\terrHandlerFn(err);\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t).catch(\n\t\t\t\t(err) => {\n\t\t\t\t\terrHandlerFn(err);\n\t\t\t\t}\n\t\t\t);\n\t\t});\n\t}\n}\n"]}

package/lib/cjs/binder.d.ts

@@ -1,22 +1,106 @@
-import { ClassConstructor, InjectableId, Injector, AbstractConstructor } from './injector';
+import { AbstractConstructor, 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 declare 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 declare 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 binder   The Binder that experienced the error.
+ * @param id   The identifier for what was trying to be made.
+ * @param maker   The thing that made (or tried to provideAsState).  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 declare type OnErrorCallback<T, M> = (injector: Injector, id: InjectableId<T>, maker: M, error: Error, 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 binder   The Binder 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.
+ * @param value   The thing that was made.
+ * @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 declare type OnSuccessCallback<T, M> = (value: T, injector: Injector, id: InjectableId<T>, maker: M) => Promise<Error | void> | Error | void;
+/**
+ * An interface allowing binding of an error handler.
+ *
+ * @see OnErrorCallback
+ */
 export interface BindErrHandler<T, M> {
     onError(cb: OnErrorCallback<T, M>): void;
 }
+/**
+ * An interface allowing binding of a post construction handler.
+ *
+ * @see OnSuccessCallback
+ */
 export interface BindHandler<T, M> 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> extends BindHandler<T, M> {
     asSingleton(): BindHandler<T, M>;
 }
+/**
+ * Bind Ids to producers.
+ */
 export interface Binder extends Injector {
+    /**
+     * Bind an InjectableId to a constant value.
+     * Constants are by their very nature singleton, and are assumed to be error proof.
+     */
     bindConstant<T>(id: InjectableId<T>, value: T): void;
+    /**
+     * Bind an InjectableId to a class (actually it's constructor).
+     * As a shortcut, you may use the class constructor as the 'id' (e.g. container.bindClass(A); ).
+     * The container will also invoke any `@PostConstruct` present on the class.
+     */
     bindClass<T>(id: ClassConstructor<T>, constructor?: ClassConstructor<T>): BindAs<T, ClassConstructor<T>>;
     bindClass<T>(id: string | symbol | AbstractConstructor<T>, constructor: ClassConstructor<T>): BindAs<T, ClassConstructor<T>>;
+    /**
+     * Bind an InjectableId to a synchronous factory that will be invoked on demand when the object is needed.
+     * The factory should produce the needed value
+     * NOTE:  The container will not invoke any `@PostConstruct` present on the class, this is the responsibility of the factory.
+     */
     bindFactory<T>(id: InjectableId<T>, factory: SyncFactory<T>): BindAs<T, SyncFactory<T>>;
+    /**
+     * Bind an InjectableId to an asynchronous factory that will be invoked on demand when the object is needed.
+     * The factory should produce the needed value (asynchronously of course).
+     * NOTE:  The container will not invoke any `@PostConstruct` present on the class, this is the responsibility of the factory.
+     * WARNING!!! The factory may not throw and must return a valid Promise (which can be pending, resolved, rejected, etc.).
+     */
     bindAsyncFactory<T>(id: InjectableId<T>, factory: AsyncFactory<T>): BindAs<T, AsyncFactory<T>>;
+    /**
+     * This essentially pre creates/loads all *singleton* InjectableIds currently known to the Binder.
+     * This *may* be helpful if you wish to use Injector.get on a dependency tree that has asynchronous singletons within the tree.
+     *
+     * @param asyncOnly     Only resolve AsyncFactorys as well as any bound classes that have an asynchronous `@PostConstruct` decorator.  WARNING: If true, SyncFactorys will *not* be resolved even if they are Singletons.
+     * @param parentRecursion   If true and the the container has a parent, resolveIfSingleton will first be called for the parent
+     * @returns A Promise that resolves when all Singleton's have been resolved, OR rejects if one or more of the Singleton's failed to resolve.  NOTE: Rejection does not occur until all Singleton resolutions have settled, and the rejection reason/err will be a Map<InjectableId, Error>
+     */
     resolveSingletons(asyncOnly?: boolean, parentRecursion?: boolean): Promise<void>;
 }

package/lib/cjs/binder.js.map

@@ -1 +1 @@
-{"version":3,"file":"binder.js","sourceRoot":"","sources":["../../src/binder.ts"],"names":[],"mappings":"","sourcesContent":["import {ClassConstructor, InjectableId, Injector, AbstractConstructor} from './injector';\n\n/**\n * Type definition for functions that return a value.\n * The function should return a valid value, but may throw an exception if it cannot.\n */\nexport type SyncFactory<T> = (injector: Injector) => T;\n\n/**\n * Type definition for functions that return a Promise for a value.\n * The function *must* not throw and must return a valid Promise (e.g. pending, resolved, rejected).\n */\nexport type AsyncFactory<T> = (injector: Injector) => Promise<T>;\n\n/**\n * You may bind an error handler which will be invoked, if the bound InjectableId could not be put into service.\n * An error handler *must* not throw, but may return an Error that will be propagated back up the call chain.\n *\n * @param binder   The Binder that experienced the error.\n * @param id   The identifier for what was trying to be made.\n * @param maker   The thing that made (or tried to provideAsState).  Will be one of type ClassConstructor, SyncFactory, or AsyncFactory, depending on how you registered the binding.\n * @param error   Identifies the problem that occurred.\n * @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.\n * @returns one of 3 results...\n *      A substitute thing (kind of like a 'maker' do-over) which must be fully operational (e.g. any @PostConstruct will be ignored).\n *      An alternate Error which will be propagated back up the call chain.\n *      Undefined, which means the 'error' parameter will be propagated back up the call chain.\n */\nexport type OnErrorCallback<T, M> = (injector: Injector, id: InjectableId<T>, maker: M, error: Error, value?: T) => T | Error | void;\n\n/**\n * You may bind a success handler which will be invoked just before the bound InjectableId is put into service.\n * This is an alternative to the more preferred @PostConstruct decorator for scenarios when usage of that decorator is not feasible.\n * WARNING:\n *      By registering a success handler, you override and nullify any @PostConstruct decorator on the class.\n *      In such a scenario, the success handler should perform whatever care and feeding the class expected from the @PostConstruct decorator.\n * A success handler *must* not throw, but may return an Error that will be propagated back up the call chain.\n *\n * @param binder   The Binder that performed the construction.\n * @param id   The identifier for what was made.\n * @param maker   The thing that made.  Will be one of type ClassConstructor, SyncFactory, or AsyncFactory, depending on how you registered the binding.\n * @param value   The thing that was made.\n * @returns one of 3 results...\n *      An Error which will be propagated back up the call chain.\n *      Undefined, which means the object is ready to be placed into service.\n *      A Promise that resolves to one of the above two values (undefined or Error).\n */\nexport type OnSuccessCallback<T, M> = (value: T, injector: Injector, id: InjectableId<T>, maker: M) => Promise<Error|void> | Error | void;\n\n/**\n * An interface allowing binding of an error handler.\n * @see OnErrorCallback\n */\nexport interface BindErrHandler<T, M> {\n\tonError(cb: OnErrorCallback<T, M>): void;\n}\n/**\n * An interface allowing binding of a post construction handler.\n * @see OnSuccessCallback\n */\nexport interface BindHandler<T, M> extends BindErrHandler<T, M> {\n\tonSuccess(cb: OnSuccessCallback<T, M>): BindErrHandler<T, M>;\n}\n\n/**\n * @inheritDoc\n * This specialization also allows you to specify that the binding is 'Singleton' (e.g. only one in the system).\n */\nexport interface BindAs<T, M> extends BindHandler<T, M> {\n\tasSingleton(): BindHandler<T, M>;\n}\n\n/**\n * Bind Ids to producers.\n */\nexport interface Binder extends Injector {\n\n\t/**\n\t * Bind an InjectableId to a constant value.\n\t * Constants are by their very nature singleton, and are assumed to be error proof.\n\t */\n\tbindConstant<T>(id: InjectableId<T>, value: T): void;\n\n\t/**\n\t * Bind an InjectableId to a class (actually it's constructor).\n\t * As a shortcut, you may use the class constructor as the 'id' (e.g. container.bindClass(A); ).\n\t * The container will also invoke any @PostConstruct present on the class.\n\t */\n\tbindClass<T>(id: ClassConstructor<T>, constructor?: ClassConstructor<T>): BindAs<T, ClassConstructor<T>>;\n\tbindClass<T>(id: string | symbol | AbstractConstructor<T>, constructor: ClassConstructor<T>): BindAs<T, ClassConstructor<T>>;\n\n\t/**\n\t * Bind an InjectableId to a synchronous factory that will be invoked on demand when the object is needed.\n\t * The factory should produce the needed value\n\t * NOTE:  The container will not invoke any @PostConstruct present on the class, this is the responsibility of the factory.\n\t */\n\tbindFactory<T>(id: InjectableId<T>, factory: SyncFactory<T>): BindAs<T, SyncFactory<T>>;\n\n\t/**\n\t * Bind an InjectableId to an asynchronous factory that will be invoked on demand when the object is needed.\n\t * The factory should produce the needed value (asynchronously of course).\n\t * NOTE:  The container will not invoke any @PostConstruct present on the class, this is the responsibility of the factory.\n\t * WARNING!!! The factory may not throw and must return a valid Promise (which can be pending, resolved, rejected, etc.).\n\t */\n\tbindAsyncFactory<T>(id: InjectableId<T>, factory: AsyncFactory<T>): BindAs<T, AsyncFactory<T>>;\n\n\t/**\n\t * This essentially pre creates/loads all *singleton* InjectableIds currently known to the Binder.\n\t * This *may* be helpful if you wish to use Injector.get on a dependency tree that has asynchronous singletons within the tree.\n\t *\n\t * @param asyncOnly     Only resolve AsyncFactorys as well as any bound classes that have an asynchronous @PostConstruct decorator.  WARNING: If true, SyncFactorys will *not* be resolved even if they are Singletons.\n\t * @param parentRecursion   If true and the the container has a parent, resolveIfSingleton will first be called for the parent\n\t * @returns A Promise that resolves when all Singleton's have been resolved, OR rejects if one or more of the Singleton's failed to resolve.  NOTE: Rejection does not occur until all Singleton resolutions have settled, and the rejection reason/err will be a Map<InjectableId, Error>\n\t */\n\tresolveSingletons(asyncOnly?: boolean, parentRecursion?: boolean): Promise<void>;\n}\n"]}
+{"version":3,"file":"binder.js","sourceRoot":"","sources":["../../src/binder.ts"],"names":[],"mappings":"","sourcesContent":["import { AbstractConstructor, ClassConstructor, InjectableId, Injector } from './injector';\n\n/**\n * Type definition for functions that return a value.\n * The function should return a valid value, but may throw an exception if it cannot.\n */\nexport type SyncFactory<T> = (injector: Injector) => T;\n\n/**\n * Type definition for functions that return a Promise for a value.\n * The function *must* not throw and must return a valid Promise (e.g. pending, resolved, rejected).\n */\nexport type AsyncFactory<T> = (injector: Injector) => Promise<T>;\n\n/**\n * You may bind an error handler which will be invoked, if the bound InjectableId could not be put into service.\n * An error handler *must* not throw, but may return an Error that will be propagated back up the call chain.\n *\n * @param binder   The Binder that experienced the error.\n * @param id   The identifier for what was trying to be made.\n * @param maker   The thing that made (or tried to provideAsState).  Will be one of type ClassConstructor, SyncFactory, or AsyncFactory, depending on how you registered the binding.\n * @param error   Identifies the problem that occurred.\n * @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.\n * @returns one of 3 results...\n * A substitute thing (kind of like a 'maker' do-over) which must be fully operational (e.g. any `@PostConstruct` will be ignored).\n * An alternate Error which will be propagated back up the call chain.\n * Undefined, which means the 'error' parameter will be propagated back up the call chain.\n */\nexport type OnErrorCallback<T, M> = (injector: Injector, id: InjectableId<T>, maker: M, error: Error, value?: T) => T | Error | void;\n\n/**\n * You may bind a success handler which will be invoked just before the bound InjectableId is put into service.\n * This is an alternative to the more preferred `@PostConstruct` decorator for scenarios when usage of that decorator is not feasible.\n * WARNING:\n * By registering a success handler, you override and nullify any `@PostConstruct` decorator on the class.\n * In such a scenario, the success handler should perform whatever care and feeding the class expected from the `@PostConstruct` decorator.\n * A success handler *must* not throw, but may return an Error that will be propagated back up the call chain.\n *\n * @param binder   The Binder that performed the construction.\n * @param id   The identifier for what was made.\n * @param maker   The thing that made.  Will be one of type ClassConstructor, SyncFactory, or AsyncFactory, depending on how you registered the binding.\n * @param value   The thing that was made.\n * @returns one of 3 results...\n * An Error which will be propagated back up the call chain.\n * Undefined, which means the object is ready to be placed into service.\n * A Promise that resolves to one of the above two values (undefined or Error).\n */\nexport type OnSuccessCallback<T, M> = (value: T, injector: Injector, id: InjectableId<T>, maker: M) => Promise<Error | void> | Error | void;\n\n/**\n * An interface allowing binding of an error handler.\n *\n * @see OnErrorCallback\n */\nexport interface BindErrHandler<T, M> {\n\tonError(cb: OnErrorCallback<T, M>): void;\n}\n/**\n * An interface allowing binding of a post construction handler.\n *\n * @see OnSuccessCallback\n */\nexport interface BindHandler<T, M> extends BindErrHandler<T, M> {\n\tonSuccess(cb: OnSuccessCallback<T, M>): BindErrHandler<T, M>;\n}\n\n/**\n * @inheritDoc\n * This specialization also allows you to specify that the binding is 'Singleton' (e.g. only one in the system).\n */\nexport interface BindAs<T, M> extends BindHandler<T, M> {\n\tasSingleton(): BindHandler<T, M>;\n}\n\n/**\n * Bind Ids to producers.\n */\nexport interface Binder extends Injector {\n\n\t/**\n\t * Bind an InjectableId to a constant value.\n\t * Constants are by their very nature singleton, and are assumed to be error proof.\n\t */\n\tbindConstant<T>(id: InjectableId<T>, value: T): void;\n\n\t/**\n\t * Bind an InjectableId to a class (actually it's constructor).\n\t * As a shortcut, you may use the class constructor as the 'id' (e.g. container.bindClass(A); ).\n\t * The container will also invoke any `@PostConstruct` present on the class.\n\t */\n\tbindClass<T>(id: ClassConstructor<T>, constructor?: ClassConstructor<T>): BindAs<T, ClassConstructor<T>>;\n\tbindClass<T>(id: string | symbol | AbstractConstructor<T>, constructor: ClassConstructor<T>): BindAs<T, ClassConstructor<T>>;\n\n\t/**\n\t * Bind an InjectableId to a synchronous factory that will be invoked on demand when the object is needed.\n\t * The factory should produce the needed value\n\t * NOTE:  The container will not invoke any `@PostConstruct` present on the class, this is the responsibility of the factory.\n\t */\n\tbindFactory<T>(id: InjectableId<T>, factory: SyncFactory<T>): BindAs<T, SyncFactory<T>>;\n\n\t/**\n\t * Bind an InjectableId to an asynchronous factory that will be invoked on demand when the object is needed.\n\t * The factory should produce the needed value (asynchronously of course).\n\t * NOTE:  The container will not invoke any `@PostConstruct` present on the class, this is the responsibility of the factory.\n\t * WARNING!!! The factory may not throw and must return a valid Promise (which can be pending, resolved, rejected, etc.).\n\t */\n\tbindAsyncFactory<T>(id: InjectableId<T>, factory: AsyncFactory<T>): BindAs<T, AsyncFactory<T>>;\n\n\t/**\n\t * This essentially pre creates/loads all *singleton* InjectableIds currently known to the Binder.\n\t * This *may* be helpful if you wish to use Injector.get on a dependency tree that has asynchronous singletons within the tree.\n\t *\n\t * @param asyncOnly     Only resolve AsyncFactorys as well as any bound classes that have an asynchronous `@PostConstruct` decorator.  WARNING: If true, SyncFactorys will *not* be resolved even if they are Singletons.\n\t * @param parentRecursion   If true and the the container has a parent, resolveIfSingleton will first be called for the parent\n\t * @returns A Promise that resolves when all Singleton's have been resolved, OR rejects if one or more of the Singleton's failed to resolve.  NOTE: Rejection does not occur until all Singleton resolutions have settled, and the rejection reason/err will be a Map<InjectableId, Error>\n\t */\n\tresolveSingletons(asyncOnly?: boolean, parentRecursion?: boolean): Promise<void>;\n}\n"]}

package/lib/cjs/class-provider.d.ts

@@ -2,12 +2,34 @@ import { BindableProvider } from './bindable-provider';
 import { ClassConstructor, InjectableId, Injector } from './injector';
 import { State } from './state';
 export declare type ResolveStateCallback = (id: InjectableId<any>) => State;
+/**
+ * @inheritDoc
+ * This specialization invokes it's configured class constructor synchronously and then scans for (and invokes) any @PostConstruct (which may be synchronous or asynchronous).
+ */
 export declare class ClassBasedProvider<T> extends BindableProvider<T, ClassConstructor<T>> {
     protected stateResolver: ResolveStateCallback;
     constructor(injector: Injector, id: InjectableId<T>, maker: ClassConstructor<T>, stateResolver: ResolveStateCallback);
+    /**
+     * @inheritDoc
+     * @see the class description for this Provider.
+     * This method is just a singleton guard, the real work is done by provideAsStateImpl.
+     */
     provideAsState(): State<T>;
+    /**
+     * @inheritDoc
+     * This specialization returns undefined if 'asyncOnly' is true and there is no asynchronous PostConstruct annotation (since class constructors can never by asynchronous).
+     */
     resolveIfSingleton(asyncOnly: boolean): Promise<T>;
-    protected makePostConstructState(obj: any): State<T>;
-    protected getConstructorParameterStates<T>(): State[];
+    /**
+     * Make a resolved or pending State that reflects any @PostConstruct annotations.
+     */
+    protected makePostConstructState(obj: T): State<T>;
+    /**
+     * This method collects the States of all the constructor parameters for our target class.
+     */
+    protected getConstructorParameterStates(): State[];
+    /**
+     * Gather the needed constructor parameters, invoke the constructor, and figure out what post construction needs done.
+     */
     private provideAsStateImpl;
 }