assemblerjs 0.3.25 → 0.4.1

package/README.md

@@ -2,7 +2,7 @@
 
 A general purpose and zero-dependency [Dependency Injection](https://en.wikipedia.org/wiki/Dependency_injection) library for node and browser.
 
-![Statements](https://img.shields.io/badge/statements-89.74%25-yellow.svg?style=flat) ![Branches](https://img.shields.io/badge/branches-78.6%25-red.svg?style=flat) ![Functions](https://img.shields.io/badge/functions-86.51%25-yellow.svg?style=flat) ![Lines](https://img.shields.io/badge/lines-89.87%25-yellow.svg?style=flat)
+![Statements](https://img.shields.io/badge/statements-90.38%25-brightgreen.svg?style=flat) ![Branches](https://img.shields.io/badge/branches-80.73%25-yellow.svg?style=flat) ![Functions](https://img.shields.io/badge/functions-86.48%25-yellow.svg?style=flat) ![Lines](https://img.shields.io/badge/lines-90%25-brightgreen.svg?style=flat)
 
 ---
 

package/dist/index.d.ts

@@ -38,13 +38,16 @@ export declare abstract class AbstractAssemblage {
     abstract whenReady?(): Promise<void>;
 }
 
+/**
+ * `Assembler` abstraction.
+ */
 export declare abstract class AbstractAssembler extends AbstractEventManager {
     abstract privateContext: AssemblerContext;
     abstract publicContext: AssemblerContext;
     abstract size: number;
     abstract register<T>(injection: Injection<T>, instance?: boolean): Injectable<T>;
     abstract use<T>(identifier: string | Symbol, object: T): T;
-    abstract prepareInit<T = AbstractAssemblage>(instance: T): unknown[];
+    abstract prepareInitHook<T = AbstractAssemblage>(instance: T): unknown[];
     abstract has<T>(identifier: Identifier<T>): boolean;
     abstract require<T>(identifier: Identifier<T>): T;
     abstract tagged(...tags: string[]): any[];
@@ -62,6 +65,25 @@ export declare abstract class AbstractEventManager {
     abstract emit(channel: string, ...args: any[]): AbstractEventManager;
 }
 
+declare abstract class AbstractInjectable<T> {
+    abstract readonly privateContext: AssemblerPrivateContext;
+    abstract readonly publicContext: AssemblerContext;
+    abstract readonly identifier: Identifier<T> | string | Symbol;
+    abstract readonly concrete: Concrete<T>;
+    abstract readonly configuration: Record<string, any>;
+    abstract dependencies: (Identifier<unknown> | any)[];
+    abstract definition: AssemblageDefinition;
+    abstract isSingleton: boolean;
+    abstract singleton: T | undefined;
+    abstract injections: Injection<unknown>[];
+    abstract objects: InstanceInjection<unknown>[];
+    abstract tags: string[];
+    abstract events: string[];
+    static of<TNew>(buildable: Buildable<TNew>, privateContext: AssemblerPrivateContext, publicContext: AssemblerContext): void;
+    abstract dispose(): void;
+    abstract build(): T;
+}
+
 /**
  * Generic `Array` items.
  */
@@ -72,6 +94,12 @@ declare type ArrayItems<T extends Array<any>> = T extends Array<infer TItems> ?
  */
 declare type ArrayLengthMutationKeys = 'splice' | 'push' | 'pop' | 'shift' | 'unshift' | number;
 
+/**
+ * Mark a class as `Assemblage` and cache its definition.
+ *
+ * @param { AssemblageDefinition } definition Definition of the assemblage that provides injections, etc.
+ * @returns { ClassDecorator } The decorated class.
+ */
 export declare const Assemblage: (definition?: AssemblageDefinition) => ClassDecorator;
 
 declare interface AssemblageDefinition {
@@ -83,7 +111,17 @@ declare interface AssemblageDefinition {
     metadata?: Record<string, any>;
 }
 
+/**
+ * `assembler.js` dependency injection container and handler.
+ */
 export declare class Assembler extends EventManager implements AbstractAssembler {
+    /**
+     * Build the dependencies tree from an assemblage as entry point.
+     *
+     * @param { Concrete<T> } entry An assemblage concrete class.
+     * @returns { T } An instance of `entry` marked as singleton.
+     */
+    static build<T>(entry: Concrete<T>): T;
     protected injectables: Map<Identifier<unknown>, Injectable<unknown>>;
     protected objects: Map<string | Symbol, unknown>;
     private initCache;
@@ -95,14 +133,21 @@ export declare class Assembler extends EventManager implements AbstractAssembler
      * Context passed to assemblages.
      */
     readonly publicContext: AssemblerContext;
-    static build<T>(entry: Concrete<T>): T;
     private constructor();
+    /**
+     * Dispose assembler and all its injectables.
+     * Note that injectables' instances will be disposed only if
+     * the are singletons.
+     *
+     * Transient instances must be disposed by the user.
+     */
     dispose(): void;
     /**
      * Recursively register an `Injection` tuple and its inner injected dependencies.
      *
      * @param { Injection<T> } injection The injection tuple to register.
-     * @param { boolean | undefined } instance The injection binds an instance to an identifier.
+     * @param { boolean | undefined } instance Set to `true` if the injection binds an instance
+     * to an identifier (defaults to `false`).
      * @returns { Injectable<T> } An injectable of type `T`.
      */
     register<T>(injection: Injection<T>, instance?: boolean): Injectable<T>;
@@ -112,238 +157,299 @@ export declare class Assembler extends EventManager implements AbstractAssembler
      * @param { string | symbol } identifier The identifier to register.
      * @param { T } object The object to use with the identifier.
      * @returns { T } The object.
+     *
+     * @example
+     * ```typescript
+     * import express from 'express';
+     *
+     * @Assemblage({
+     *   use: [
+     *     ['express', express]
+     *   ]
+     * });
+     * class MyAssemblage implements AbstractAssemblage {
+     *   constructor(@Use('express) private express) {
+     *     // Use express.
+     *   }
+     * }
+     * ```
      */
     use<T>(identifier: string | Symbol, object: T): T;
-    prepareInit<T = AbstractAssemblage>(instance: T): unknown[];
     /**
-     * Check if `Assembler` has given identifier registered.
+     * Cache an instaance to be inited with `onInit` hook
+     * when the dependency tree will be fully resolved.
      *
-     * @param { Identifier<T> | string | symbol } identifier An abstract or concrete class
-     * identifier or a string or Symbol one.
-     * @returns { boolean } `true` if dependency has been registered.
-     */
-    has<T>(identifier: Identifier<T> | string | Symbol): boolean;
+     * @param { T = AbstractAssemblage } instance The built instance.
+         * @returns { unknown[] } The instances to be inited as this point.
+         */
+     prepareInitHook<T = AbstractAssemblage>(instance: T): unknown[];
+     /**
+      * Check if `Assembler` has given identifier registered.
+      *
+      * @param { Identifier<T> | string | symbol } identifier An abstract or concrete class,
+      * or a string or Symbol as identifier.
+      * @returns { boolean } `true` if dependency has been registered.
+      */
+     has<T>(identifier: Identifier<T> | string | Symbol): boolean;
+     /**
+      * Get or instantiate an assemblage for given identifier.
+      *
+      * @param { Identifier<T> | string | symbol } identifier The identifier to get instance from.
+      * @returns { T } An instance of Concrete<T>.
+      */
+     require<T>(identifier: Identifier<T> | string | Symbol): T;
+     /**
+      * Require dependencies by tag passed in assemblage's definition.
+      *
+      * @param { string[] } tags The tags to get dependencies.
+      * @returns { unknown[] } An array of instances for the given tags. If registered
+      * identifier is not marked as 'singleton', will resolve in a new instance.
+      */
+     tagged(...tags: string[]): unknown[];
+     /**
+      * Size of the assembler: number of registered dependencies.
+      */
+     get size(): number;
+    }
+
     /**
-     * Get or instantiate an assemblage for given identifier.
-     *
-     * @param { Identifier<T> | string | symbol } identifier The identifier to get instance from.
-     * @returns { T } An instance of Concrete<T>.
+     * Assembler public context that provide
+     * access to some useful `Assembler` methods.
      */
-    require<T>(identifier: Identifier<T> | string | Symbol): T;
+    export declare interface AssemblerContext {
+        has: AbstractAssembler['has'];
+        require: AbstractAssembler['require'];
+        tagged: AbstractAssembler['tagged'];
+        on: AbstractAssembler['on'];
+        once: AbstractAssembler['once'];
+        off: AbstractAssembler['off'];
+        events: AbstractAssembler['channels'];
+    }
+
     /**
-     * Require dependencies by tag passed in assemblage's definition.
-     *
-     * @param { string | string[] } tags The tag(s) to get dependencies.
-     * @returns { unknown[] } An array of instances for the given tags. If registered
-     * identifier is not marked as 'singleton', will resolve in a new instance.
+     * `Assembler` dispose method type.
      */
-    tagged(...tags: string[]): unknown[];
+    export declare type AssemblerDispose = AbstractAssembler['dispose'];
+
     /**
-     * Size of the assembler: number of registered dependencies.
+     * Assembler private context that provide
+     * access to some `Assembler` methods
+     * used internally.
      */
-    get size(): number;
-}
-
-export declare interface AssemblerContext {
-    has: AbstractAssembler['has'];
-    require: AbstractAssembler['require'];
-    tagged: AbstractAssembler['tagged'];
-    on: AbstractAssembler['on'];
-    once: AbstractAssembler['once'];
-    off: AbstractAssembler['off'];
-    events: AbstractAssembler['channels'];
-}
-
-export declare type AssemblerDispose = AbstractAssembler['dispose'];
+    declare interface AssemblerPrivateContext extends AssemblerContext {
+        register: AbstractAssembler['register'];
+        use: AbstractAssembler['use'];
+        dispose: AssemblerDispose;
+        prepareInitHook: AbstractAssembler['prepareInitHook'];
+        emit: AbstractAssembler['emit'];
+        addChannels: AbstractAssembler['addChannels'];
+        removeChannels: AbstractAssembler['removeChannels'];
+    }
 
-declare interface AssemblerPrivateContext extends AssemblerContext {
-    register: AbstractAssembler['register'];
-    use: AbstractAssembler['use'];
-    prepareInit: AbstractAssembler['prepareInit'];
-    dispose: AssemblerDispose;
-    emit: AbstractAssembler['emit'];
-    addChannels: AbstractAssembler['addChannels'];
-    removeChannels: AbstractAssembler['removeChannels'];
-}
-
-/**
- * Recursively check if a property is defined and truthy to call an async method.
- *
- * @param { string } property The name of the class proprty to wait for.
- * @param { number | undefined } interval The interval in milliseconds at which the value is checked (defaults to 25 milliseconds).
- * @returns { Promise<void> } A promise that calls the original method when resolving.
- */
-export declare const Await: (property: string, interval?: number) => MethodDecorator;
-
-/**
- * Injectable binds a concrete class to an abstract class as identifier without configuration.
- */
-declare type BaseInjection<T> = Tuple<[Abstract<T>, Concrete<T>]>;
-
-/**
- * Describes a buildable object.
- */
-declare interface Buildable<T> {
-    identifier: Identifier<T>;
-    concrete: Concrete<T>;
-    instance?: T;
-    configuration: Record<string, any>;
-}
-
-/**
- * A concrete (newable) class.
- */
-declare interface Concrete<T> extends Function {
-    new (...args: any[]): T;
-}
-
-/**
- * Injection binds a concrete class to itself as identifier
- * and provides a configuration object that will be passed to context.
- */
-declare type ConcreteConfiguredInjection<T> = Tuple<[
-Concrete<T>,
-Record<string, any>
-]>;
-
-/**
- * Injectable binds a conrete class to itself as identifier.
- */
-declare type ConcreteInjection<T> = Tuple<[Concrete<T>]>;
-
-/**
- * Injects the assemblage's configuration object.
- */
-export declare const Configuration: () => ParameterDecorator;
-
-/**
- * Injectable binds a concrete class to an abstract class as identifier
- * and provides a configuration object that will be passed to context.
- */
-declare type ConfiguredInjection<T> = Tuple<[
-Abstract<T>,
-Concrete<T>,
-Record<string, any>
-]>;
-
-/**
- * Injects the Assembler's context.
- */
-export declare const Context: () => ParameterDecorator;
-
-/**
- * Injects the assemblage's definition object.
- */
-export declare const Definition: () => ParameterDecorator;
+    /**
+     * Check at given interval if a property is defined and truthy to call an async method.
+     *
+     * @param { string } property The name of the class proprty to wait for.
+     * @param { number | undefined } interval The interval in milliseconds at which the value is checked (defaults to 25 milliseconds).
+     * @returns { Promise<void> } A promise that calls the original method when resolving.
+     */
+    export declare const Await: (property: string, interval?: number) => MethodDecorator;
 
-/**
- * Injects the Assembler's 'dispose' method.
- */
-export declare const Dispose: () => ParameterDecorator;
+    /**
+     * Injectable binds a concrete class to an abstract class as identifier without configuration.
+     */
+    declare type BaseInjection<T> = Tuple<[Abstract<T>, Concrete<T>]>;
 
-export declare class EventManager implements AbstractEventManager {
-    private readonly listeners;
-    private readonly onceListeners;
-    readonly channels: Set<string>;
-    constructor(...allowedChannels: string[]);
-    dispose(): void;
-    addChannels(...channels: string[]): EventManager;
-    removeChannels(...channels: string[]): EventManager;
-    on(channel: string, callback: Listener): EventManager;
-    once(channel: string, callback: Listener): EventManager;
-    off(channel: string, callback?: Listener): EventManager;
-    emit(channel: string, ...args: any[]): EventManager;
-    private run;
-    private cleanChannel;
-}
+    /**
+     * Describes a buildable object.
+     */
+    declare interface Buildable<T> {
+        identifier: Identifier<T>;
+        concrete: Concrete<T>;
+        instance?: T;
+        configuration: Record<string, any>;
+    }
 
-/**
- * An identifier can be an abstract or a concrete class.
- */
-declare type Identifier<T> = Concrete<T> | Abstract<T>;
+    /**
+     * A concrete (newable) class.
+     */
+    declare interface Concrete<T> extends Function {
+        new (...args: any[]): T;
+    }
 
-declare class Injectable<T> {
-    readonly privateContext: AssemblerPrivateContext;
-    readonly publicContext: AssemblerContext;
-    readonly identifier: Identifier<T> | string | Symbol;
-    readonly concrete: Concrete<T>;
-    readonly configuration: Record<string, any>;
-    private dependenciesIds;
-    private singletonInstance;
-    static of<TNew>(buildable: Buildable<TNew>, privateContext: AssemblerPrivateContext, publicContext: AssemblerContext): Injectable<TNew>;
-    private constructor();
     /**
-     * Dispose the injectable by deleting its singleton if exists
-     * and deleting all injectable's properties.
+     * Injection binds a concrete class to itself as identifier
+     * and provides a configuration object that will be passed to context.
      */
-    dispose(): void;
+    declare type ConcreteConfiguredInjection<T> = Tuple<[
+    Concrete<T>,
+    Record<string, any>
+    ]>;
+
     /**
-     * Instantiate the assemblage or get its singleton instance.
-     *
-     * @returns { T } The assemblage instance.
+     * Injectable binds a conrete class to itself as identifier.
      */
-    build(): T;
+    declare type ConcreteInjection<T> = Tuple<[Concrete<T>]>;
+
     /**
-     * Injectable assemblage's dependencies passed as 'constructor' parameters.
+     * Injects the assemblage's configuration object.
      */
-    get dependencies(): (Identifier<unknown> | any)[];
+    export declare const Configuration: () => ParameterDecorator;
+
     /**
-     * Metadatas passed in assemblage's definition or in its parent definition.
+     * Injectable binds a concrete class to an abstract class as identifier
+     * and provides a configuration object that will be passed to context.
      */
-    get definition(): AssemblageDefinition;
+    declare type ConfiguredInjection<T> = Tuple<[
+    Abstract<T>,
+    Concrete<T>,
+    Record<string, any>
+    ]>;
+
     /**
-     * `true` if assemblage is a singleton.
+     * Injects the Assembler's context.
      */
-    get isSingleton(): boolean;
+    export declare const Context: () => ParameterDecorator;
+
     /**
-     * The singleton instance if this `Injectable` wraps a singleton assemblage.
+     * Injects the assemblage's definition object.
      */
-    get singleton(): T | undefined;
+    export declare const Definition: () => ParameterDecorator;
+
     /**
-     * Injectable assemblage's own injections defined in its decorator's definition.
+     * Injects the Assembler's 'dispose' method.
      */
-    get injections(): Injection<unknown>[];
+    export declare const Dispose: () => ParameterDecorator;
+
+    export declare class EventManager implements AbstractEventManager {
+        private readonly listeners;
+        private readonly onceListeners;
+        readonly channels: Set<string>;
+        constructor(...allowedChannels: string[]);
+        dispose(): void;
+        addChannels(...channels: string[]): EventManager;
+        removeChannels(...channels: string[]): EventManager;
+        on(channel: string, callback: Listener): EventManager;
+        once(channel: string, callback: Listener): EventManager;
+        off(channel: string, callback?: Listener): EventManager;
+        emit(channel: string, ...args: any[]): EventManager;
+        private run;
+        private cleanChannel;
+    }
+
+    export declare const getDecoratedParametersIndexes: <T>(target: Concrete<T>) => {
+        context: number[];
+        definition: number[];
+        configuration: number[];
+        dispose: number[];
+        use: number[];
+    };
+
     /**
-     * Injectable assemblage's own objects (e.g. instances) injections defined in its decorator's definition.
+     * An identifier can be an abstract or a concrete class.
      */
-    get objects(): InstanceInjection<unknown>[];
+    declare type Identifier<T> = Concrete<T> | Abstract<T>;
+
+    declare class Injectable<T> implements AbstractInjectable<T> {
+        readonly privateContext: AssemblerPrivateContext;
+        readonly publicContext: AssemblerContext;
+        readonly identifier: Identifier<T> | string | Symbol;
+        readonly concrete: Concrete<T>;
+        readonly configuration: Record<string, any>;
+        private dependenciesIds;
+        private singletonInstance;
+        static of<TNew>(buildable: Buildable<TNew>, privateContext: AssemblerPrivateContext, publicContext: AssemblerContext): Injectable<TNew>;
+        private constructor();
+        /**
+         * Dispose the injectable by deleting its singleton if exists
+         * and deleting all injectable's properties.
+         */
+        dispose(): void;
+        /**
+         * Instantiate the assemblage or get its singleton instance.
+         *
+         * @returns { T } The assemblage instance.
+         */
+        build(): T;
+        /**
+         * Injectable assemblage's dependencies passed as 'constructor' parameters.
+         */
+        get dependencies(): (Identifier<unknown> | any)[];
+        /**
+         * Metadatas passed in assemblage's definition or in its parent definition.
+         */
+        get definition(): AssemblageDefinition;
+        /**
+         * `true` if assemblage is a singleton.
+         */
+        get isSingleton(): boolean;
+        /**
+         * The singleton instance if this `Injectable` wraps a singleton assemblage.
+         */
+        get singleton(): T | undefined;
+        /**
+         * Injectable assemblage's own injections defined in its decorator's definition.
+         */
+        get injections(): Injection<unknown>[];
+        /**
+         * Injectable assemblage's own objects (e.g. instances) injections defined in its decorator's definition.
+         */
+        get objects(): InstanceInjection<unknown>[];
+        /**
+         * Tags passed in assemblage's definition.
+         */
+        get tags(): string[];
+        /**
+         * Event channels passed in assemblage's definition.
+         */
+        get events(): string[];
+    }
+
     /**
-     * Tags passed in assemblage's definition.
+     * A generic injection tuple.
      */
-    get tags(): string[];
+    declare type Injection<T> = BaseInjection<T> | ConfiguredInjection<T> | ConcreteInjection<T> | ConcreteConfiguredInjection<T>;
+
     /**
-     * Event channels passed in assemblage's definition.
+     * Injectable binds an instance of a class to an identifier (abstract or concrete).
      */
-    get events(): string[];
-}
+    declare type InstanceInjection<T> = Tuple<[Identifier<T> | string | Symbol, T]>;
 
-/**
- * A generic injection tuple.
- */
-declare type Injection<T> = BaseInjection<T> | ConfiguredInjection<T> | ConcreteInjection<T> | ConcreteConfiguredInjection<T>;
+    /**
+     * Describes a listener type as a function taking any number of arguments and returning `void`.
+     */
+    declare type Listener = (...args: any[]) => void | Promise<void>;
 
-/**
- * Injectable binds an instance of a class to an identifier (abstract or concrete).
- */
-declare type InstanceInjection<T> = Tuple<[Identifier<T> | string | Symbol, T]>;
+    /**
+     * Internal `Reflect` parameters decorators' indexes in constructor.
+     */
+    export declare enum ReflectParamIndex {
+        Context = "assembler:context.param.index",
+        Dispose = "assembler:dispose.param.index",
+        Definition = "assemblage:definition.param.index",
+        Configuration = "assemblage:configuration.param.index",
+        Use = "assemblage:use.param.index"
+    }
 
-/**
- * Describes a listener type as a function taking any number of arguments and returning `void`.
- */
-declare type Listener = (...args: any[]) => void | Promise<void>;
+    /**
+     * Internal `Reflect` parameters decorators' values.
+     */
+    export declare enum ReflectParamValue {
+        UseIdentifier = "assemblage:use.param.value"
+    }
 
-/**
- * An array of fixed length typed values.
- *
- * @see https://stackoverflow.com/a/59906630/1060921
- */
-declare type Tuple<T extends any[]> = Pick<T, Exclude<keyof T, ArrayLengthMutationKeys>> & {
-    [Symbol.iterator]: () => IterableIterator<ArrayItems<T>>;
-};
+    /**
+     * An array of fixed length typed values.
+     *
+     * @see https://stackoverflow.com/a/59906630/1060921
+     */
+    declare type Tuple<T extends any[]> = Pick<T, Exclude<keyof T, ArrayLengthMutationKeys>> & {
+        [Symbol.iterator]: () => IterableIterator<ArrayItems<T>>;
+    };
 
-/**
- * Injects an object passed with `string` or `Symbol` identifier.
- */
-export declare const Use: (identifier: string | Symbol) => ParameterDecorator;
+    /**
+     * Injects an object passed with `string` or `Symbol` identifier.
+     */
+    export declare const Use: (identifier: string | Symbol) => ParameterDecorator;
 
-export { }
+    export { }