Logo for jsDocs.io

@adonisjs/fold

  • Version 8.2.0
  • Published
  • 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

Index

Functions

Classes

Interfaces

Type Aliases

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;

    • Register a binding with a callback. The callback return value will be used when binding is resolved

    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[]>;

      • Register an boot providers together.

      method useProviders

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

      • Register an array of provider paths

      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;
      };

      • Register a binding with a callback. The callback return value will be used when binding is resolved

      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)

            Dev Dependencies (23)

            Peer Dependencies (0)

            No peer dependencies.

            Badge

            To add a badge like this onejsDocs.io badgeto 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>