На эту статью меня сподвигла переписка в комментах с коллегой @iliazeus и его вопрос, как в @teqfw/di код может зависеть от интерфейса, а не от его имплементации. В своём ответе я попытался провести параллели с героем Джейсона Стэйтэма из фильма "Перевозчик" - с Фрэнком Мартином. У Фрэнка было три правила (условия контракта) и любой, кто удовлетворял этим правилам (и имел достаточно денег), мог нанять Фрэнка в качестве первозчика.

Ниже я продемонстрирую на примере Фрэнка Мартина, каким образом могут работать интерфейсы в обычном JS (не TS).

Контракт

В первом фильме трилогии (прим. 1) у Фрэнка Мартина было три правила:

1. Никогда не изменять условия сделки.

2. Никаких имён.

3. Никогда не открывать посылку.

Вот третье правило как раз и описывает специфику использования интерфейсов в программировании (не только в JS, а вообще). Всё, что Фрэнку нужно было знать про посылку - это её размеры и вес, а про поездку - адрес начала и конца маршрута. На основании этой информации Фрэнк прикидывал, стоит ли браться за работу и за сколько.

В JS можно упрощённо описать эти условия так:

/** @interface */
class Trans_Api_Package {
    /** @return {{length: number, width: number, height: number}} */
    getSize() {}

    /** @return {number} */
    getWeight() {}
}

/** @interface */
class Trans_Api_Route {
    /** @return {string} */
    getPlaceFrom() {}

    /** @return {string} */
    getPlaceTo() {}  
}

На текущий момент нативных интерфейсов в JS пока ещё не завезли, поэтому приходится обходиться обычными классами (class) и аннотациями JSDoc - @interface и @implements.

Чтобы взять заказ и выполнить его, Фрэнку нужно знать лишь то, что он декларировал в контракте (интерфейсах). Детали за пределами оговоренного контракта его не волнуют на профессиональном уровне - "Никогда не открывать посылку."

Договор Фрэнка о предоставляемой услуге на языке JS мог бы выглядеть так:

class Trans_Drive {
    /**
     * @param {Trans_Api_Package} pack
     * @param {Trans_Api_Route} route
     */
    constructor(pack, route}
    ) {...}
}

В переводе на простой язык: "Вы даёте мне посылку, говорите, куда ехать - и я еду."

Фрэнк предоставляет услугу транспортировки любому лицу или организации, кто соответствует его требованиям.

Если переводить на язык программирования всё вышеизложенное в отрыве от Фрэнка Мартина, но в контексте использования @teqfw/di, то:

• Плагин определяет интерфейсы, которым должны соответствовать объекты, с которыми он может работать (классы в пространстве Trans_Api).

• За имплементацию интерфейсов отвечает приложение, которое этот плагин использует (Client1, Client2, ...).

• Так как в @teqfw/di IoC реализована в виде внедрения зависимостей через конструктор, то классы плагина используют интерфейсы для обозначения зависимостей, ожидаемых от Контейнера Объектов.

• Связывание имплементаций с интерфейсами происходит путём конфигурации Контейнера Объектов в соответствующем приложении (Client1, Client2, ...).

• При создании в runtime объектов пла2гина Контейнер внедряет имплементации в места соответствующих интерфейсов.

На схеме выше каждый блок соответствует отдельному npm-пакету.

Внедрение

В данной статье я исхожу из упрощения, что одно приложение (любой Client) использует плагин (Transporter) для однократной перевозки посылки (хотя бы в силу эксклюзивности услуг Фрэнка и их стоимости). Таким образом, объект поездки Trans_Drive в пределах любого приложения, его использующего, является объектом-одиночкой и инжектируется такими же зависимостями-одиночками при создании. В терминах @teqfw/di это выглядит так:

2export default class Trans_Drive {
    /**
     * @param {Trans_Api_Package} pack
     * @param {Trans_Api_Route} route
     */2
    constructor(
        {
            Trans_Api_Package$: pack,
            Trans_Api_Route$: route,
        }
    ) {...}
}

Согласно принципам IoC базовые объекты сами не создают нужные им зависимости, но дают возможность Контейнеру Объектов эти зависимости создать и внедрить. Поскольку описание требуемых зависимостей происходит на уровне плагина (пространство имён Trans_), то, как я отметил выше, в качестве идентификаторов зависимостей выступают имена интерфейсов (префикс Trans_Api_).

Имплементация

Приложение, чтобы использовать trans-плагин, должно имплементировать соответствующие интерфейсы.

В JS-коде это можно выразить так:

/** @implements Trans_Api_Package */
export default class Client1_Di_Package {
    /** @return {{length: number, width: number, height: number}} */
    getSize() {
        return {length: 150, width: 50, height: 50};
    }

    /** @return {number} */
    getWeight() {
        return 50;
    }
}

Эти параметры соответствуют сумке с дочкой босса китайской мафии, озвученным в в первом фильме: вес - 50 кг, размер - полтора метра на полметра.

Конфигурация Контейнера Объектов

Каждое приложение, использующее @teqfw/di, должно первым делом сконфигурировать Контейнер Объектов. Для начала указать правила разрешения имён:

import {dirname, join} from 'node:path';
import {fileURLToPath} from 'node:url';
import Container from '@teqfw/di';

const url = new URL(import.meta.url);
const script = fileURLToPath(url);
const current = dirname(script);
const scope = join(current, 'node_modules', '@flancer64');
const container = new Container();
const resolver = container.getResolver();
resolver.addNamespaceRoot('Client1_', join(current, 'src'));
resolver.addNamespaceRoot('Trans_', join(scope, 'demo-di-if-plugin', 'src'));

А затем указать правила преобразования имён интерфейсов в имена соответствующих имплементаций:

/**
 * The preprocessor chunk to replace interfaces with the implementations in this app.
 * @implements TeqFw_Di_Api_Container_PreProcessor_Chunk
 */
const replaceChunk = {
    modify(depId, originalId, stack) {
        // FUNCS
        /**
         * @param {TeqFw_Di_DepId} id - structured data about interface
         * @param {string} nsImpl - the namespace for the implementation
         */
        function replace(id, nsImpl) {
            id.moduleName = nsImpl;
            return id;
        }

        // MAIN
        switch (originalId.moduleName) {
            case 'Trans_Api_Package':
                return replace(depId, 'Client1_Di_Package');
            case 'Trans_Api_Route':
                return replace(depId, 'Client1_Di_Route');
        }
        return depId;
    }
};

container.getPreProcessor().addChunk(replaceChunk);

Контейнер объектов в @teqfw/di имеет возможность подключать цепочку обработчиков в препроцессор. Каждый обработчик должен имплементировать интерфейс TeqFw_Di_Api_Container_PreProcessor_Chunk и может изменять структуру идентификатора зависимости до того, как будет создан соответствующий ей объект:

container.getPreProcessor().addChunk(new Replace());

В нашем случае проще всего связать каждый интерфейс с соответствующей имплементацией напрямую через switch. Но в других приложениях маппинг может быть более "кучерявым" (например, через внешний JSON/YAML/XML или через сопоставление структур каталогов в плагине и приложении: id.moduleName.replace('Trans_Api_', 'Client1_Di_')).

Итого

Код в плагине на момент написания, конечно же, зависит от интерфейса - плагин просто ничего не знает про другие приложения и их имплементации его интерфейсов. Зато знают сами приложения (вернее, их разработчики). И эти знания позволяют конфигурировать Контейнер Объектов в приложении таким образом, чтобы в runtime вместо интерфейсов использовались соответствующие им имплементации.

Использование интерфейсов на уровне плагинов позволяют уменьшить зацепление кода между npm-пакетами и увеличить возможности повторного использования npm-пакетов в различных приложениях.

Кстати, совершенно необязательно делать это при помощи IoC - аннотации JSDoc так же хорошо позволяют навигировать по коду и при "ручном" связывании объектов при помощи обычных статических import'ов (раннее связывание). Но позднее связывание объектов в runtime при помощи Контейнера даёт разработчику больше пространства для манёвра за счёт пред- и особенно пост-обработки создаваемых и внедряемых зависимостей.

Заключение

• Контейнер Объектов в @teqfw/di позволяет модифицировать идентификатор зависимостей перед созданием соответствующего ему объекта (цепочка обработчиков в препроцессоре).

• Плагин, который используется в приложении (или другими плагинами), объявляет классы без имплементации методов и маркирует их с помощью JSDoc-аннотации @interface .

• Интерфейсные классы являются по сути документацией и в норме не должны порождать runtime-объектов.

• Код внутри самого плагина завязан на интерфейсы через JSDoc-аннотации, что позволяет использовать autocomplete в IDE.

• Приложение (или другие плагины) имплементируют соответствующий интерфейс и маркирует имплементацию при помощи JSDoc-аннотации @implements для возможности навигации по коду в IDE.

• Приложение инициализирует Контейнер Объектов при старте и конфигурирует замену в runtime интерфейсов их имплементациями с учётом всех используемых в приложении плагинов.

Исходный код демо-плагина и приложений:

• flancer64/demo-di-if-plugin: собственно сам Фрэнк Мартин со своим профессиональным нелюбопытством (интерфейсы)

• flancer64/demo-di-if-app1: первый заказ на перевозку из Марселя в Ницу сумки с девушкой-китаянкой внутри.

• flancer64/demo-di-if-app2: второй заказ на перевозку дипломата со взрывчаткой из Ницы в Гренобль.

Примечания

1. Лично я считаю "Перевозчик" трилогией хотя бы только потому, что Эд Скрейн ну совсем не Джейсон Стэйтэм.