@teqfw/di

0.22.0 • Public • Published

@teqfw/di

A Dependency Injection container for regular JavaScript is provided, which can be used in both browser and Node.js applications. This library exclusively supports ES6 modules. The primary objective of this library is late binding with minimal manual configuration for the container. All linking instructions are encapsulated within the dependency identifiers and source path resolver. Additionally, the container offers the capability to modify object identifiers (preprocessing) and the created objects (postprocessing). These features enable you to more comprehensively distribute the necessary functionality across npm packages and reuse npm packages in different projects, following a ' modular monolith' architecture (see the sample).

Inversion of Control

The primary motivation for creating this library was the concept that JavaScript is a language in which the entire application can be written, both on the front end and the back end. The idea was to enable the use of the same JavaScript code seamlessly on both the front end and the back end without requiring any changes, including additional transpilation.

The main challenge encountered along this path was static importing. When the entire application can fit into a single npm package, all sources can be linked to each other through relative paths. However, if the sources are distributed across different npm packages, addressing them becomes problematic:

import something from '@vendor/package/src/Module.js'; // backend style
import something from 'https://domain.com/@vendor/package/src/Module.js'; // frontend style

The inversion of control (IoC) design pattern came to the rescue. In this pattern, any software object with external dependencies provides a mechanism for obtaining these dependencies. The external environment, whether it's a test unit or an object container, is responsible for creating these dependencies and providing them to the software object.

// constructor-based injection
class Service {
  constructor(config, logger) {}
}

If all dependencies are added to software objects through a similar mechanism, there is no need to use static imports in the source code itself. Now, they can be used without any changes, both on the front end and on the back end.

Object Container

Many programming languages implement the Dependency Injection pattern. In this pattern, an application typically utilizes an object container, responsible for creating all the application's objects and their dependencies. The @teqfw/di package provides precisely such an object container (src/Container.js). This object container is initialized and configured at the outset of application execution, after which it assumes responsibility for creating the remaining application objects:

import Container from '@teqfw/di';

const container = new Container();
const resolver = container.getResolver();
resolver.addNamespaceRoot('App_', pathApp);
resolver.addNamespaceRoot('Sample_Lib_', pathLib);
const app = await container.get('App_Main$');

Since JavaScript does not have its own namespaces, similar to packages in Java and namespaces in PHP, the experience of Zend 1 is used as the basis for identifiers.

Namespaces

The primary purpose of namespaces is to address code elements within an application. In JavaScript (JS) applications, code is organized into npm packages, within which the sources reside in files and directories. Each npm package and its root directory can be linked to a namespace:

Vendor_Package_ => /home/user/app/node_modules/@vendor/package/src/....

This way, you can reference any ES6 module in any npm package:

Venodr_Package_Shared_Dto_Service_Save => /home/user/app/node_modules/@vendor/package/src/Shared/Dto/Service/Save.js 

Depending on the execution environment, the mapping may be different:

Vendor_Package_ => /home/user/app/node_modules/@vendor/package/src    // Linux style
Vendor_Package_ => C:\projects\app\node_modules\@vendor\package\src   // Window style
Vendor_Package_ => https://unpkg.com/@vendor/package/src              // Web style

The source code employs namespaces to reference dependencies, while the object container utilizes a resolver to translate the namespace into the corresponding path to the source code file, contingent upon the runtime environment:

Venodr_Package_Shared_Dto_Service_Save => /home/user/app/node_modules/@vendor/package/src/Shared/Dto/Service/Save.js
Venodr_Package_Shared_Dto_Service_Save => C:\projects\app\node_modules\@vendor\package\src\Shared\Dto\Service\Save.js
Venodr_Package_Shared_Dto_Service_Save => https://unpkg.com/@vendor/package/src/Shared/Dto/Service/Save.js

Dependency Specification

JavaScript lacks reflection capabilities similar to Java or PHP. Consequently, to enable the object container to comprehend the necessary dependencies for creating a specific object, a distinct convention is employed - a dependency specification. A dependency specification is an object where each key represents the identifier of the required dependency:

class Service {
  constructor(
          {
            App_Config: config,
            App_Logger: logger
          }
  ) {}
}

In the object container, the required object is created as follows:

const App_Config = await container.get('App_Config');
const App_Logger = await container.get('App_Logger');
const spec = {App_Config, App_Logger};
const obj = new Service(spec);

If dependencies are injected into a factory function, it appears as follows:

function Factory({App_Config: config, App_Logger: logger}) {
  // perform operations with dependencies and compose the result
  return res;
}

Es6 export

In ES6+, a distinct building block in application development is the act of exporting:

export {
  obj1 as default, obj2, obj3
};

Static linking through imports is performed at the level of these building blocks:

import obj1 from './mod.js';
import {obj2} from './mod.js';

This implies that the dependency identifier must have the capability to reference not only the ES6 module itself but also a specific export within it, as illustrated in this example:

const exp = 'Vendor_Package_Module.export';
const def = 'Vendor_Package_Module.default';
const obj2 = 'Vendor_Package_Module.obj2';

In this case, the dependency declaration in a constructor or factory function could look like this:

class Service {
  constructor(
          {
            'App_Config.default': config,
            'App_Util.logger': logger
          }
  ) {}
}

Late binding

The object container links objects not at the source code level but in runtime mode. In my applications, I have encountered two particularly useful runtime object lifecycles:

  • Singleton: It exists in a single instance within the application.
  • Instance: A new object is created each time.

Since any string can be used as an object key in a dependency specification, various formats can be devised to specify the lifecycle of the required dependency. I have personally chosen the following format:

const asIs = 'Vendor_Package_Module.default';
const asSingleton = 'Vendor_Package_Module.default$';
const asInstance = 'Vendor_Package_Module.default$$';

In principle, each package can have its own format for describing the dependencies it uses internally. The TeqFw_Di_Container_Parser object is responsible for applying the appropriate format within the required namespace.

Transforming the Result

Here are the steps for the object container:

processing steps

There are two stages involved here:

  • Preprocessing: the modification of the dependency identifier
  • Postprocessing: the modification of the created object

Preprocessing

At times, situations may arise, especially when utilizing various extensions of the core functionality, where it becomes necessary to redefine certain objects within the application. For such scenarios, @teqfw/di includes a preprocessor:

/** @type {TeqFw_Di_Api_Container_PreProcessor} */
const pre = container.getPreProcessor();

You can add handlers (chunks) to the preprocessor that are capable of modifying the initial depId:

/** @type {TeqFw_Di_Api_Container_PreProcessor_Chunk} */
const replace = new ReplaceChunk(); // some implementation of the interface
pre.addChunk(replace);

The preprocessor calls the handlers sequentially and can, for example, replace a dependency from the base npm package (App_Base_Mod_Api_Service_Auth) with another dependency from one of the npm packages (Auth_Password_Mod_Service or OAuth2_Mod_Service), depending on the npm packages included in the application compilation.

By using such replacements, you can implement the core functionality in one npm package, while in other npm packages, you can implement the additional functionality required by the core package.

Postprocessing

Since the container creates all objects in the application, it can also perform additional actions on newly created objects, such as adding extra functionality to them in the form of a wrapper.

@teqfw/di enables you to add individual handlers to the post-processing stage and modify the result. For example, you can wrap a finished object or perform various operations on it:

// ./PostChunk.js
/**
 * @implements TeqFw_Di_Api_Container_PostProcessor_Chunk
 */
export default {
    modify: function (obj, originalId, stack) {
        if (originalId.wrappers.indexOf('proxy') !== -1)
            return new Proxy(obj, {
                get: async function (base, name) { /* do something */ }
            });
        else return obj;
    }
};
// ./main.js
import postChunk from './PostChunk.mjs';

container.getPostProcessor().addChunk(postChunk);

Resume

@teqfw/di offers Dependency Injection for regular JavaScript with minimal manual configuration, supporting both browser and Node.js environments. Its use of late binding and an object container in JavaScript applications, along with the ability to modify the behavior of created objects (via pseudo-interfaces and wrappers), allows you to apply architectural solutions from other languages (such as Java, PHP, C#) and fully harness the capabilities of npm packages and ES6 modules in JavaScript applications, particularly in the Node.js environment.

Dependencies (0)

    Dev Dependencies (6)

    Package Sidebar

    Install

    npm i @teqfw/di

    Weekly Downloads

    14

    Version

    0.22.0

    License

    Apache-2.0

    Unpacked Size

    986 kB

    Total Files

    51

    Last publish

    Collaborators

    • flancer32