ditox
    TypeScript icon, indicating that this package has built-in type declarations

    1.3.0 • Public • Published

    Ditox.js

    lemon

    Detoxed dependency injection container.

    npm downloads types licence Coverage Status

    Table of Contents

    Features

    • Simple and functional API
    • Container hierarchy
    • Scoped containers
    • Dependency modules
    • Multi-value tokens
    • Typescript and Flow typings
    • Supports Node.js, Deno and browsers

    Installation

    Install with npm

    npm install ditox --save
    

    Or yarn

    yarn add ditox
    

    You can also use the UMD build from unpkg

    <script src="https://unpkg.com/ditox/dist/index.browser.js" />
    <script>
      const container = Ditox.createContainer();
    </script>

    Usage with Deno:

    import {createContainer} from 'https://deno.land/x/ditox/mod.ts';
    
    const container = createContainer();

    Usage

    Ditox.js works with containers, tokens, values and value factories. There are no class decorators, field injectors and other magic stuff. Only explicit binding and resolving.

    In general, all you need is to do the following:

    • Create binding tokens.
    • Create a container.
    • Register values and factories in the container using the tokens.
    • Resolve the tokens and use the provided values.
    import {createContainer, injectable, optional, token} from 'ditox';
    
    // This is app code, some factory functions and classes:
    function createStorage(config) {}
    
    function createLogger(config) {}
    
    class UserService {
      constructor(storage, logger) {}
    }
    
    // Define tokens for injections.
    // Token can be optional to provide default values.
    const TOKENS = {
      StorageConfig: optional(token(), {name: 'default storage'}),
      Storage: token('Token description for debugging'),
      Logger: token(),
      UserService: token(),
    };
    
    // Create the container.
    const container = createContainer();
    
    // Provide a value to the container.
    container.bindValue(TOKENS.StorageConfig, {name: 'custom storage'});
    
    // Dynamic values are provided by factories.
    
    // A factory can be decorated with `injectable()` to resolve its arguments.
    // By default, a factory has `singleton` lifetime.
    container.bindFactory(
      TOKENS.Storage,
      injectable(createStorage, TOKENS.StorageConfig),
    );
    
    // A factory can have `transient` lifetime to create a value on each resolving.
    container.bindFactory(TOKENS.Logger, createLogger, {scope: 'transient'});
    
    // Classes are provided by factories.
    container.bindFactory(
      TOKENS.UserService,
      injectable(
        (storage, logger) => new UserService(storage, logger),
        TOKENS.Storage,
        // A token can be made optional to resolve with a default value
        // when it is not found during resolving.
        optional(TOKENS.Logger),
      ),
      {
        // `scoped` and `singleton` scopes can have `onRemoved` callback.
        // It is called when a token is removed from the container.
        scope: 'scoped',
        onRemoved: (userService) => userService.destroy(),
      },
    );
    
    // Get a value from the container, it returns `undefined` in case a value is not found.
    const logger = container.get(TOKENS.Logger);
    
    // Resolve a value, it throws `ResolverError` in case a value is not found.
    const userService = container.resolve(TOKENS.userService);
    
    // Remove a value from the container.
    container.remove(TOKENS.Logger);
    
    // Clean up the container.
    container.removeAll();

    Container Hierarchy

    Ditox.js supports "parent-child" hierarchy. If the child container cannot to resolve a token, it asks the parent container to resolve it:

    import {creatContainer, token} from 'ditox';
    
    const V1 = token();
    const V2 = token();
    
    const parent = createContainer();
    parent.bindValue(V1, 10);
    parent.bindValue(V2, 20);
    
    const container = createContainer(parent);
    container.bindValue(V2, 21);
    
    container.resolve(V1); // 10
    container.resolve(V2); // 21

    Factory Lifetimes

    Ditox.js supports managing the lifetime of values which are produced by factories. There are the following types:

    • singleton - This is the default. The value is created and cached by the container which registered the factory.
    • scoped - The value is created and cached by the container which starts resolving.
    • transient - The value is created every time it is resolved.

    singleton

    This is the default scope. "Singleton" allows to cache a produced value by a parent container which registered the factory:

    import {creatContainer, token} from 'ditox';
    
    const TAG = token();
    const LOGGER = token();
    
    const createLogger = (tag) => (message) => console.log(`[${tag}] ${message}`);
    
    const parent = createContainer();
    parent.bindValue(TAG, 'parent');
    parent.bindFactory(LOGGER, injectable(createLogger, TAG, {scope: 'singleton'}));
    
    const container1 = createContainer(parent);
    container1.bindValue(TAG, 'container1');
    
    const container2 = createContainer(parent);
    container2.bindValue(TAG, 'container2');
    
    parent.resolve(LOGGER)('xyz'); // [parent] xyz
    container1.resolve(LOGGER)('foo'); // [parent] foo
    container2.resolve(LOGGER)('bar'); // [parent] bar

    scoped

    "Scoped" lifetime allows to have sub-containers with own instances of some services which can be disposed. For example, a context during HTTP request handling, or other unit of work:

    import {creatContainer, token} from 'ditox';
    
    const TAG = token();
    const LOGGER = token();
    
    const createLogger = (tag) => (message) => console.log(`[${tag}] ${message}`);
    
    const parent = createContainer();
    // `scoped` is default scope and can be omitted.
    parent.bindFactory(LOGGER, injectable(createLogger, TAG, {scope: 'scoped'}));
    
    const container1 = createContainer(parent);
    container1.bindValue(TAG, 'container1');
    
    const container2 = createContainer(parent);
    container2.bindValue(TAG, 'container2');
    
    parent.resolve(LOGGER)('xyz'); // throws ResolverError, the parent does not have TAG value.
    container1.resolve(LOGGER)('foo'); // [container1] foo
    container2.resolve(LOGGER)('bar'); // [container2] bar
    
    // Dispose a container.
    container1.removeAll();

    transient

    "Transient" makes to a produce values by the factory for each resolving:

    import {creatContainer, token} from 'ditox';
    
    const TAG = token();
    const LOGGER = token();
    
    const createLogger = (tag) => (message) => console.log(`[${tag}] ${message}`);
    
    const parent = createContainer();
    parent.bindValue(TAG, 'parent');
    parent.bindFactory(LOGGER, injectable(createLogger, TAG, {scope: 'singleton'}));
    
    const container1 = createContainer(parent);
    container1.bindValue(TAG, 'container1');
    
    const container2 = createContainer(parent);
    container2.bindValue(TAG, 'container2');
    
    parent.resolve(LOGGER)('xyz'); // [parent] xyz
    container1.resolve(LOGGER)('foo'); // [container1] foo
    container2.resolve(LOGGER)('bar'); // [container2] bar
    
    parent.bindValue(TAG, 'parent-rebind');
    parent.resolve(LOGGER)('xyz'); // [parent-rebind] xyz

    Dependency modules

    Dependencies can be organized as modules in declarative way with ModuleDeclaration. It is useful for providing pieces of functionality from libraries to an app which depends on them.

    type LoggerModule = Module<{logger: Logger}>;
    
    const LOGGER_MODULE_TOKEN = token<LoggerModule>;
    
    const LOGGER_MODULE: ModuleDeclaration<LoggerModule> = {
      token: LOGGER_MODULE_TOKEN,
      factory: (container) => {
        const transport = container.resolve(TRANSPORT_TOKEN).open();
        return {
          logger: {log: (message) => transport.write(message)},
          destroy: () => transport.close(),
        };
      },
      exportedProps: {
        logger: LOGGER_TOKEN,
      },
    };

    Later such module declarations can be bound to a container:

    const container = createContainer();
    
    // bind a single module
    bindModule(container, LOGGER_MODULE);
    
    // or bind multiple depenendency modules
    bindModules(container, [DATABASE_MODULE, CONFIG_MODULE, API_MODULE]);

    There are utility functions for module declarations:

    • declareModule() – declare a module as ModuleDeclaration however token field can be optional for anonymous modules.
    • declareModuleBindings() – declares an anonymous module with imports. This module binds the provided ones to a container.

    Example for these functions:

    const LOGGER_MODULE = declareModule<LoggerModule>({
      factory: createLoggerModule,
      exportedProps: {
        logger: LOGGER_TOKEN,
      },
    });
    
    const APP_MODULE = declareModuleBinding([LOGGER_MODULE, DATABASE_MODULE]);

    API References


    © 2020-2021 Mikhail Nasyrov, MIT license

    Install

    npm i ditox

    DownloadsWeekly Downloads

    34

    Version

    1.3.0

    License

    MIT

    Unpacked Size

    253 kB

    Total Files

    37

    Last publish

    Collaborators

    • mnasyrov