@adonisjs/fold

@adonisjs/fold

Version 8.2.0
Published 1 year ago
80.9 kB
1 dependency
MIT license

Install

npm i @adonisjs/fold

yarn add @adonisjs/fold

pnpm add @adonisjs/fold

Overview

Dependency manager and IoC container for your next NodeJs application

Functions

function inject

inject: (value?: any) => {
    (target: any, propertyKey: string): void;
    (target: any): void;
};

Injects bindings to the class constructor

Classes

class Ioc

class Ioc implements IocContract {}

property importAliases

readonly importAliases: { [alias: string]: string };

Registered aliases. The key is the alias and value is the absolute directory path

property module

module: 'cjs' | 'esm';

Define the module type for resolving auto import aliases. Defaults to cjs

method alias

alias: (absolutePath: string, alias: string) => this;

Define an import alias

method bind

bind: (binding: string, callback: BindCallback<any, this>) => this;

method call

call: (target: any, method: any, args?: any[]) => any;

Call method on an object and automatically resolve its depdencies

method callAsync

callAsync: (target: any, method: any, args?: any[]) => Promise<any>;

Same as [[call]], but uses ES modules for resolving the auto import aliases

method fake

fake: (namespace: string, callback: FakeCallback<any, this>) => this;

Register a fake for a namespace. Fakes works both for "bindings" and "import aliases". Fakes only work when proxies are enabled using "useProxies".

method getResolver

getResolver: (
    fallbackMethod?: string,
    rcNamespaceKey?: string,
    fallbackNamespace?: string
) => IocResolver;

Returns the resolver instance to resolve Ioc container bindings with little ease. Since, the IocResolver uses an in-memory cache to improve the lookup speed, we suggest keeping a reference to the output of this method to leverage caching

method hasBinding

hasBinding: (namespace: string) => boolean;

Find if a binding exists for a given namespace

method hasFake

hasFake: (namespace: string) => boolean;

Find if a fake has been registered for a given namespace

method import

import: (namespace: string) => Promise<any>;

Import namespace from the auto import aliases. This method assumes you are using native ES modules

method isAliasPath

isAliasPath: (namespace: string) => boolean;

Find if a namespace is part of the auto import aliases. Returns false, when namespace is an alias path but has an explicit binding too

method lookup

lookup: (
    namespace: string | LookupNode<string>,
    prefixNamespace?: string
) => null | any;

Lookup a namespace. The output contains the complete namespace, along with its type. The type is an "alias" or a "binding".
Null is returned when unable to lookup the namespace inside the container
Note: This method just checks if a namespace is registered or binding or can be it resolved from auto import aliases or not. However, it doesn't check for the module existence on the disk.
Optionally you can define a prefix namespace to be used to build the complete namespace. For example:
- namespace: UsersController - prefixNamespace: App/Controllers/Http - Output: App/Controllers/Http/UsersController
Prefix namespace is ignored for absolute namespaces. For example:
- namespace: /App/UsersController - prefixNamespace: App/Controllers/Http - Output: App/UsersController

method lookupOrFail

lookupOrFail: (
    namespace: string | LookupNode<string>,
    prefixNamespace?: string
) => LookupNode<string>;

Same as [[lookup]]. But raises exception instead of returning null

method make

make: (namespace: LookupNode<string> | any, args?: any[]) => any;

Makes an instance of the class by first resolving it.

method makeAsync

makeAsync: (namespace: LookupNode<string> | any, args?: any[]) => Promise<any>;

Same as the [[make]] method, but instead uses ES modules for resolving the auto import aliases

method require

require: (namespace: string) => any;

Same as the "import" method, but uses CJS for requiring the module from its path

method resolveBinding

resolveBinding: (binding: string) => any;

Resolve a binding by invoking the binding factory function. An exception is raised, if the binding namespace is unregistered.

method restore

restore: (namespace?: string) => this;

Clear selected or all the fakes. Calling the method with no arguments will clear all the fakes

method singleton

singleton: (binding: string, callback: BindCallback<any, this>) => this;

Same as the [[bind]] method, but registers a singleton only. Singleton's callback is invoked only for the first time and then the cached value is used

method trap

trap: (callback: (namespace: string) => any) => this;

Trap container lookup calls. It includes
- Ioc.use - Ioc.useAsync - Ioc.make - Ioc.makeAsync - Ioc.require - Ioc.import - Ioc.resolveBinding

method use

use: (namespace: string | LookupNode<string>) => any;

The use method looks up a namespace inside both the bindings and the auto import aliases

method useAsync

useAsync: (namespace: string | LookupNode<string>) => Promise<any>;

Same as the [[use]] method, but instead uses ES modules for resolving the auto import aliases

method useProxies

useProxies: (enable?: boolean) => this;

Enable/disable proxies. Proxies are mainly required for fakes to work

method with

with: (namespaces: readonly any[], cb: (...args: any) => void) => void;

@deprecated: Use "withBindings" instead

method withBindings

withBindings: (namespaces: readonly any[], cb: (...args: any) => void) => void;

Define a callback to be called when all of the container bindings are available.
Note: This method is exclusive for bindings and doesn't resolve auto import aliases

class Registrar

class Registrar {}

Registrar is used to register and boot the providers

constructor

constructor(providerConstructorParams: any[], basePath?: string);

method boot

boot: () => Promise<void>;

Boot all the providers by calling the boot method. Boot methods are called in series.

method register

register: () => Promise<any[]>;

Register all the providers by instantiating them and calling the register method.
The provider instance will be returned, which can be used to boot them as well.

method registerAndBoot

registerAndBoot: () => Promise<any[]>;

method useProviders

useProviders: (
    providersPaths: string[],
    callback?: <T extends Constructor<any>>(provider: T) => InstanceType<T>
) => this;

Interfaces

interface IocContract

interface IocContract<ContainerBindings extends any = any> {}

Ioc container interface

property importAliases

importAliases: {
    [alias: string]: string;
};

Registered aliases. The key is the alias and value is the absolute directory path

property module

module: 'cjs' | 'esm';

Define the module type for resolving auto import aliases. Defaults to cjs

property with

with: WithBindings<ContainerBindings>;

@deprecated: Use "withBindings" instead

property withBindings

withBindings: WithBindings<ContainerBindings>;

The "withBindings" method invokes the defined callback when it is able to resolve all the mentioned bindings.

method alias

alias: (absolutePath: string, alias: string) => this;

Define an import alias

method bind

bind: {
    <Binding extends keyof ContainerBindings>(
        binding: Binding,
        callback: BindCallback<ContainerBindings[Binding], this>
    ): this;
    <Binding extends string>(
        binding: Binding,
        callback: BindCallback<
            Binding extends keyof ContainerBindings
                ? ContainerBindings[Binding]
                : any,
            this
        >
    ): this;
};

method call

call: <T extends unknown, Method extends ExtractFunctions<T>>(
    target: T,
    method: Method,
    args?: any[]
) => T[Method] extends Function ? ReturnType<T[Method]> : any;

Call a method on an object and automatically inject its depdencies

method callAsync

callAsync: <T extends unknown, Method extends ExtractFunctions<T>>(
    target: T,
    method: Method,
    args?: any[]
) => T[Method] extends Function
    ? Promise<UnWrapPromise<ReturnType<T[Method]>>>
    : Promise<any>;

Call a method on an object and automatically inject its depdencies

method fake

fake: {
    <Namespace extends keyof ContainerBindings>(
        namespace: Namespace,
        callback: FakeCallback<ContainerBindings[Namespace], this>
    ): this;
    <Namespace extends string>(
        namespace: Namespace,
        callback: FakeCallback<
            Namespace extends keyof ContainerBindings
                ? ContainerBindings[Namespace]
                : any,
            this
        >
    ): this;
};

Register a fake for a namespace. Fakes works both for "bindings" and "import aliases". Fakes only work when proxies are enabled using "useProxies".

method getResolver

getResolver: (
    fallbackMethod?: string,
    rcNamespaceKey?: string,
    fallbackNamespace?: string
) => IocResolverContract<ContainerBindings>;

Returns the resolver instance to resolve Ioc container bindings with little ease. Since, the IocResolver uses an in-memory cache to improve the lookup speed, we suggest keeping a reference to the output of this method to leverage caching

method hasBinding

hasBinding: {
    <Binding extends keyof ContainerBindings>(namespace: Binding): boolean;
    (namespace: string): boolean;
};

Find if a binding exists for a given namespace

method hasFake

hasFake: {
    <Namespace extends keyof ContainerBindings>(namespace: Namespace): boolean;
    (namespace: string): boolean;
};

Find if a fake has been registered for a given namespace

method import

import: (namespace: string) => Promise<any>;

Import namespace from the auto import aliases. This method assumes you are using native ES modules

method isAliasPath

isAliasPath: (namespace: string) => boolean;

Find if a namespace is part of the auto import aliases. Returns false, when namespace is an alias path but has an explicit binding too

method lookup

lookup: {
    <Namespace extends Extract<keyof ContainerBindings, string>>(
        namespace: Namespace | LookupNode<Namespace>,
        prefixNamespace?: string
    ): LookupNode<Namespace>;
    <Namespace extends string>(
        namespace: Namespace | LookupNode<Namespace>,
        prefixNamespace?: string
    ): Namespace extends keyof ContainerBindings
        ? LookupNode<Namespace>
        : LookupNode<string>;
};

Lookup a namespace. The output contains the complete namespace, along with its type. The type is an "alias" or a "binding".
Null is returned when unable to lookup the namespace inside the container
Note: This method just checks if a namespace is registered or binding or can be it resolved from auto import aliases or not. However, it doesn't check for the module existence on the disk.
Optionally you can define a prefix namespace to be used to build the complete namespace. For example:
- namespace: UsersController - prefixNamespace: App/Controllers/Http - Output: App/Controllers/Http/UsersController
Prefix namespace is ignored for absolute namespaces. For example:
- namespace: /App/UsersController - prefixNamespace: App/Controllers/Http - Output: App/UsersController

method lookupOrFail

lookupOrFail: {
    <Namespace extends Extract<keyof ContainerBindings, string>>(
        namespace: Namespace | LookupNode<Namespace>,
        prefixNamespace?: string
    ): LookupNode<Namespace>;
    <Namespace extends string>(
        namespace: Namespace | LookupNode<Namespace>,
        prefixNamespace?: string
    ): Namespace extends keyof ContainerBindings
        ? LookupNode<Namespace>
        : LookupNode<string>;
};

Same as [[lookup]]. But raises exception instead of returning null

method make

make: {
    <Binding extends Extract<keyof ContainerBindings, string>>(
        lookupNode: Binding | LookupNode<Binding>,
        args?: any[]
    ): ContainerBindings[Binding];
    <T extends unknown>(
        value: LookupNode<string> | T,
        args?: any[]
    ): T extends keyof ContainerBindings
        ? ContainerBindings[T]
        : InferMakeType<T>;
};

Makes an instance of the class by first resolving it.

method makeAsync

makeAsync: {
    <Binding extends Extract<keyof ContainerBindings, string>>(
        lookupNode: Binding | LookupNode<Binding>,
        args?: any[]
    ): Promise<ContainerBindings[Binding]>;
    <T extends unknown>(value: LookupNode<string> | T, args?: any[]): Promise<
        T extends keyof ContainerBindings
            ? ContainerBindings[T]
            : InferMakeType<T>
    >;
};

Same as the [[make]] method, but instead uses ES modules for resolving the auto import aliases

method require

require: (namespace: string) => any;

Same as the "import" method, but uses CJS for requiring the module from its path

method resolveBinding

resolveBinding: {
    <Binding extends Extract<keyof ContainerBindings, string>>(
        binding: Binding
    ): ContainerBindings[Binding];
    <Binding extends string>(
        namespace: Binding
    ): Binding extends keyof ContainerBindings
        ? ContainerBindings[Binding]
        : any;
};

Resolve a binding by invoking the binding factory function. An exception is raised, if the binding namespace is unregistered.

method restore

restore: {
    <Namespace extends keyof ContainerBindings>(namespace?: Namespace): this;
    (namespace?: string): this;
};

Clear selected or all the fakes. Calling the method with no arguments will clear all the fakes

method singleton

singleton: {
    <Binding extends keyof ContainerBindings>(
        binding: Binding,
        callback: BindCallback<ContainerBindings[Binding], this>
    ): this;
    <Binding extends string>(
        binding: Binding,
        callback: BindCallback<
            Binding extends keyof ContainerBindings
                ? ContainerBindings[Binding]
                : any,
            this
        >
    ): this;
};

Same as the [[bind]] method, but registers a singleton only. Singleton's callback is invoked only for the first time and then the cached value is used

method trap

trap: (callback: (namespace: string) => any) => this;

Trap container lookup calls. It includes
- Ioc.use - Ioc.useAsync - Ioc.make - Ioc.makeAsync - Ioc.require - Ioc.import - Ioc.resolveBinding

method use

use: {
    <Binding extends Extract<keyof ContainerBindings, string>>(
        lookupNode: Binding | LookupNode<Binding>
    ): ContainerBindings[Binding];
    <Binding extends string>(
        lookupNode: Binding | LookupNode<Binding>
    ): Binding extends keyof ContainerBindings
        ? ContainerBindings[Binding]
        : any;
};

The use method looks up a namespace inside both the bindings and the auto import aliases

method useAsync

useAsync: {
    <Binding extends Extract<keyof ContainerBindings, string>>(
        lookupNode: Binding | LookupNode<Binding>
    ): Promise<ContainerBindings[Binding]>;
    <Binding extends string>(lookupNode: Binding | LookupNode<Binding>): Promise<
        Binding extends keyof ContainerBindings
            ? ContainerBindings[Binding]
            : any
    >;
};

Same as the [[use]] method, but instead uses ES modules for resolving the auto import aliases

method useProxies

useProxies: (enable?: boolean) => this;

Enable/disable proxies. Proxies are mainly required for fakes to work

interface IocResolverContract

interface IocResolverContract<ContainerBindings extends any> {}

IoC resolver allows resolving IoC container bindings by defining prefix namespaces

method call

call: {
    <Namespace extends Extract<keyof ContainerBindings, string>>(
        namespace: Namespace | string,
        prefixNamespace?: string,
        args?: any[] | ((instance: any) => any[])
    ): Promise<any>;
    <Namespace extends Extract<keyof ContainerBindings, string>>(
        namespace: IocResolverLookupNode<string | Namespace>,
        prefixNamespace: undefined,
        args?: any[] | ((instance: any) => any[])
    ): Promise<any>;
};

Call method on an IoC container binding

method resolve

resolve: {
    <Namespace extends Extract<keyof ContainerBindings, string>>(
        namespace: Namespace,
        prefixNamespace?: string
    ): IocResolverLookupNode<Namespace>;
    <Namespace extends string>(
        namespace: Namespace,
        prefixNamespace?: string
    ): Namespace extends keyof ContainerBindings
        ? IocResolverLookupNode<Namespace>
        : IocResolverLookupNode<string>;
};

Resolve IoC container binding

interface WithBindings

interface WithBindings<ContainerBindings extends any> {}

Type of the "withBindings" method

call signature

<Bindings extends (keyof ContainerBindings)[]>(
    namespaces: [...Bindings],
    cb: (
        ...args: {
            [M in keyof Bindings]: Bindings[M] extends keyof ContainerBindings
                ? ContainerBindings[Bindings[M]]
                : any;
        }
    ) => void
): void;

call signature

<Namespace extends (keyof ContainerBindings | string)[]>(
    namespaces: readonly [...Namespace],
    cb: (
        ...args: {
            [M in keyof Namespace]: Namespace[M] extends keyof ContainerBindings
                ? ContainerBindings[Namespace[M]]
                : any;
        }
    ) => void
): void;

Type Aliases

type BindCallback

type BindCallback<ReturnValue extends any, Container extends IocContract> = (
    container: Container
) => ReturnValue;

Shape of the bind callback method

type Constructor

type Constructor<T> = new (...args: any[]) => T;

Shape of class constructor

type ExtractFunctions

type ExtractFunctions<T> = {
    [P in keyof T]: T[P] extends Function ? P : never;
}[keyof T];

type FakeCallback

type FakeCallback<ReturnValue extends any, Container extends IocContract> = (
    container: Container,
    originalValue: ReturnValue
) => ReturnValue;

Shape of the fake callback method

type InferMakeType

type InferMakeType<T> = T extends string | LookupNode<string>
    ? any
    : T extends PlainConstructor
    ? T
    : T extends Constructor<infer A>
    ? A
    : T;

Finding return type of the ioc.make method based upon the input argument.
- String and LookupNode = Returns any - Class constructor with "makePlain" are returned as it is - Otherwise an instance of the class constructor is returned - All other values are returned as it is

type IocResolverLookupNode

type IocResolverLookupNode<Namespace extends string> = {
    namespace: Namespace;
    type: 'binding' | 'alias';
    method: string;
};

Shape of resolved lookup node, resolved using getResolver().resolve() method.

type LookupNode

type LookupNode<Namespace extends string> = {
    namespace: Namespace;
    type: 'binding' | 'alias';
};

Shape of lookup node pulled using ioc.lookup method. This node can be passed to ioc.use, or ioc.make to skip many checks and resolve the binding right away.

type PlainConstructor

type PlainConstructor = {
    makePlain: true;
};

Shape of class constructor with makePlain property

Package Files (5)

Dependencies (1)

@poppinss/utils

Peer Dependencies (0)

No peer dependencies.

Badge

To add a badge like this oneto your package's README, use the codes available below.

You may also use Shields.io to create a custom badge linking to https://www.jsdocs.io/package/@adonisjs/fold.

Markdown

[![jsDocs.io](https://img.shields.io/badge/jsDocs.io-reference-blue)](https://www.jsdocs.io/package/@adonisjs/fold)

HTML

<a href="https://www.jsdocs.io/package/@adonisjs/fold"><img src="https://img.shields.io/badge/jsDocs.io-reference-blue" alt="jsDocs.io"></a>

Updated 1 year ago.
Package analyzed in 3431 ms.
Missing or incorrect documentation? Open an issue for this package.

@adonisjs/fold

Install

Overview

Index

Functions

Classes

Interfaces

Type Aliases

Functions

function inject

Classes

class Ioc

property importAliases

property module

method alias

method bind

method call

method callAsync

method fake

method getResolver

method hasBinding

method hasFake

method import

method isAliasPath

method lookup

method lookupOrFail

method make

method makeAsync

method require

method resolveBinding

method restore

method singleton

method trap

method use

method useAsync

method useProxies

method with

method withBindings

class Registrar

constructor

method boot

method register

method registerAndBoot

method useProviders

Interfaces

interface IocContract

property importAliases

property module

property with

property withBindings

method alias

method bind

method call

method callAsync

method fake

method getResolver

method hasBinding

method hasFake

method import

method isAliasPath

method lookup

method lookupOrFail

method make

method makeAsync

method require

method resolveBinding

method restore

method singleton

method trap

method use

method useAsync

method useProxies

interface IocResolverContract

method call

method resolve

interface WithBindings

call signature

call signature

Type Aliases

type BindCallback