Границы: свои модули, экспорт и «провайдер не виден»

У файла граница есть давно: то, что модуль не экспортировал, снаружи не видно. У контейнера её нет. Возьмём заметки, которые удаляются мягко: строка остаётся в хранилище с пометкой deleted, а правило «удалённое не показываем» живёт в NotesService. В другом углу приложения — еженедельная сводка для письма. Её автору нужны тексты заметок, и он просит у контейнера то, где тексты лежат, — NotesRepo. Контейнер из прошлой статьи — в подложке. Прогноз: что окажется на экране и что уйдёт в письмо?

declare function Injectable(options?: { deps?: Function[] }): (value: Function, context: ClassDecoratorContext) => void;
declare class Container {
  get<T>(cls: new (...args: any[]) => T): T;
}

@Injectable()
class NotesRepo {
  rows = [
    { text: "купить хлеб", deleted: false },
    { text: "пароль от почты", deleted: true },
    { text: "позвонить маме", deleted: false },
  ];
}

@Injectable({ deps: [NotesRepo] })
class NotesService {
  constructor(private readonly repo: NotesRepo) {}

  list() {
    return this.repo.rows.filter((note) => !note.deleted).map((note) => note.text);
  }
}

@Injectable({ deps: [NotesRepo] })
class DigestService {
  constructor(private readonly repo: NotesRepo) {}

  weekly() {
    return this.repo.rows.map((note) => note.text);
  }
}

const app = new Container();
console.log(`на экране: ${app.get(NotesService).list().join(", ")}`);
console.log(`в письме: ${app.get(DigestService).weekly().join(", ")}`);

Удалённый «пароль от почты» уехал в письмо. Каждый класс опять написан честно: сервис фильтрует, сводка читает хранилище. Беда в том, что правило записано в одном месте, а обойти его можно из любого. Контейнер отдал NotesRepo, потому что его попросили, а сказать «это внутренность заметок» ему нечем: в deps годится любой класс. И когда хранилище поменяет форму строки, сломается сводка, хотя в разделе заметок о ней никто не знал.

Nest отвечает на это модулем. Модуль — класс с декоратором @Module, и границу проводят три его списка. providers — что живёт внутри. exports — что из этого видно снаружи. imports — чьи экспорты модуль согласен видеть. Это граница файла, поднятая на уровень выше: у раздела заметок NotesService — экспорт, а NotesRepo — внутренняя кухня.

Экспорт — то, на что соседям можно опираться. Всё остальное хозяин раздела меняет, никого не спрашивая.

Научим контейнер модулям. Декоратор @Module кладёт три списка в WeakMap по классу модуля, как реестр метаданных. Контейнер теперь зовётся App, и его get принимает два аргумента: из какого модуля просят и что. Метод #owner ищет модуль, которому токен принадлежит: сначала среди провайдеров того, кто просит, потом по его imports, и в импортированном модуле токен обязан быть и в providers, и в exports. Найденный модуль — владелец. Объекты кешируются по владельцу, а зависимости провайдера get просит уже от имени его модуля. Сводок две: DigestService берёт тексты у NotesService, RawDigestService — по-старому, у хранилища. Прогноз: что напечатает первая сводка и что скажет вторая попытка?

type Class = new (...args: any[]) => object;
type ModuleOptions = { imports?: Class[]; providers?: Class[]; exports?: Class[] };

const depsOf = new WeakMap<Function, Class[]>();
const moduleOf = new WeakMap<Function, ModuleOptions>();

function Injectable(options: { deps?: Class[] } = {}) {
  return function (value: Class, context: ClassDecoratorContext) {
    depsOf.set(value, options.deps ?? []);
  };
}

function Module(options: ModuleOptions) {
  return function (value: Class, context: ClassDecoratorContext) {
    moduleOf.set(value, options);
  };
}

class App {
  #instances = new Map<Class, Map<Class, object>>();

  get<T extends object>(from: Class, token: new (...args: any[]) => T): T {
    const owner = this.#owner(from, token);
    if (!owner) throw new Error(`${token.name} не виден в ${from.name}`);
    const own = this.#instances.get(owner) ?? new Map<Class, object>();
    this.#instances.set(owner, own);
    const ready = own.get(token);
    if (ready) return ready as T;
    const args = (depsOf.get(token) ?? []).map((dep) => this.get(owner, dep));
    const instance = new token(...args);
    own.set(token, instance);
    return instance;
  }

  #owner(from: Class, token: Class): Class | undefined {
    const { providers = [], imports = [] } = moduleOf.get(from) ?? {};
    if (providers.includes(token)) return from;
    for (const imported of imports) {
      const owner = this.#exportedBy(imported, token);
      if (owner) return owner;
    }
  }

  #exportedBy(mod: Class, token: Class): Class | undefined {
    const { providers = [], exports = [] } = moduleOf.get(mod) ?? {};
    if (exports.includes(token) && providers.includes(token)) return mod;
  }
}

@Injectable()
class NotesRepo {
  rows = [
    { text: "купить хлеб", deleted: false },
    { text: "пароль от почты", deleted: true },
    { text: "позвонить маме", deleted: false },
  ];
}

@Injectable({ deps: [NotesRepo] })
class NotesService {
  constructor(private readonly repo: NotesRepo) {}

  list() {
    return this.repo.rows.filter((note) => !note.deleted).map((note) => note.text);
  }
}

@Module({ providers: [NotesRepo, NotesService], exports: [NotesService] })
class NotesModule {}

@Injectable({ deps: [NotesService] })
class DigestService {
  constructor(private readonly notes: NotesService) {}

  weekly() {
    return this.notes.list();
  }
}

@Injectable({ deps: [NotesRepo] })
class RawDigestService {
  constructor(private readonly repo: NotesRepo) {}

  weekly() {
    return this.repo.rows.map((note) => note.text);
  }
}

@Module({ imports: [NotesModule], providers: [DigestService, RawDigestService] })
class DigestModule {}

const app = new App();
console.log(`в письме: ${app.get(DigestModule, DigestService).weekly().join(", ")}`);
try {
  console.log(`в письме: ${app.get(DigestModule, RawDigestService).weekly().join(", ")}`);
} catch (err) {
  console.log((err as Error).message);
}

Первая сводка получила только живые заметки, вторая упала: «NotesRepo не виден в DigestModule». Интереснее, почему не упала первая. NotesService сам зависит от NotesRepo, которого DigestModule не видит. Но свои зависимости сервис получает в модуле, где записан: #owner вернул владельца NotesModule, и get(NotesModule, NotesRepo) нашёл хранилище среди его провайдеров. Импортирующий видит лицо модуля, а собирается это лицо внутри. Поэтому NotesModule может заменить хранилище, добавить кеш или разбить сервис на три класса, и DigestModule этого не заметит, пока NotesService отвечает по-прежнему.

Наш контейнер бросил ошибку при первом get, то есть на первом запросе к сводке. Nest проверяет то же при старте: внутри NestFactory.create он создаёт все провайдеры, и невидимая зависимость роняет запуск. Прочитать его сообщение и найти в нём модуль, где зависимости не хватило, научит статья о трёх причинах «Nest can't resolve dependencies».

Импортирующий видит лицо модуля. Всё, от чего это лицо зависит, остаётся внутри.

Сообщение «NotesRepo не виден в DigestModule» подсказывает самый короткий путь: раз не виден, вписать NotesRepo в providers модуля сводки. Ошибка уходит сразу. Ниже хранилище держит строки в памяти, заметки создаются через NotesService, а сводка считает строки в хранилище. App из прошлого примера — в подложке. Прогноз: сколько заметок насчитает сводка и что покажет сравнение в последней строке?

type Class = new (...args: any[]) => object;
declare function Injectable(options?: { deps?: Class[] }): (value: Class, context: ClassDecoratorContext) => void;
declare function Module(options: { imports?: Class[]; providers?: Class[]; exports?: Class[] }): (value: Class, context: ClassDecoratorContext) => void;
declare class App {
  get<T extends object>(from: Class, token: new (...args: any[]) => T): T;
}

@Injectable()
class NotesRepo {
  rows: string[] = [];
}

@Injectable({ deps: [NotesRepo] })
class NotesService {
  constructor(private readonly repo: NotesRepo) {}

  create(text: string) {
    this.repo.rows.push(text);
  }
}

@Module({ providers: [NotesRepo, NotesService], exports: [NotesService] })
class NotesModule {}

@Injectable({ deps: [NotesRepo] })
class DigestService {
  constructor(private readonly repo: NotesRepo) {}

  weekly() {
    return `заметок за неделю: ${this.repo.rows.length}`;
  }
}

@Module({ imports: [NotesModule], providers: [NotesRepo, DigestService] })
class DigestModule {}

const app = new App();
const notes = app.get(NotesModule, NotesService);
notes.create("купить хлеб");
notes.create("позвонить маме");
console.log(app.get(DigestModule, DigestService).weekly());
console.log(app.get(DigestModule, NotesRepo) === app.get(NotesModule, NotesRepo));

Ноль заметок и false. DigestModule получил не доступ к хранилищу заметок, а собственное хранилище: #owner нашёл NotesRepo среди его провайдеров, и объект лёг в кеш под владельцем DigestModule. Это правило из таблицы прошлой статьи: один объект на токен в модуле. Класс, записанный в providers двух модулей, даёт два объекта, как один класс под двумя токенами. С массивом в памяти ошибку выдал ноль. Хранилище поверх базы строки бы нашло, но если оно держит пул соединений или кеш, пулов станет два, а кеши разойдутся.

Лечение зависит от того, что сводке нужно на самом деле. Нужны тексты по правилам заметок — просить их у экспорта, как DigestService в прошлом примере, и при нужде дописать сервису метод. Нужно само хранилище — экспортировать его из NotesModule: это решение хозяина раздела, и оно записано в его @Module. А чужой класс в providers — повод спросить, действительно ли модулю нужен свой отдельный экземпляр.

Не виден — значит, экспортировать или импортировать. Копия в providers даёт второй объект, а не доступ к первому.

Теперь база. DatabaseModule экспортирует Db, NotesModule импортирует DatabaseModule, DigestModule импортирует NotesModule. Сводке нужны и заметки, и база — для собственного запроса. Цепочка вроде бы есть: сводка → заметки → база. Модулей сводки ниже два: DigestModule импортирует только заметки, DigestWithDbModule — ещё и базу. Прогноз: увидит ли первый Db и один ли Db достанется сводке и заметкам во втором?

type Class = new (...args: any[]) => object;
declare function Injectable(options?: { deps?: Class[] }): (value: Class, context: ClassDecoratorContext) => void;
declare function Module(options: { imports?: Class[]; providers?: Class[]; exports?: Class[] }): (value: Class, context: ClassDecoratorContext) => void;
declare class App {
  get<T extends object>(from: Class, token: new (...args: any[]) => T): T;
}

@Injectable()
class Db {
  readonly url = "postgres://localhost/app";
}

@Module({ providers: [Db], exports: [Db] })
class DatabaseModule {}

@Injectable({ deps: [Db] })
class NotesService {
  constructor(readonly db: Db) {}
}

@Module({ imports: [DatabaseModule], providers: [NotesService], exports: [NotesService] })
class NotesModule {}

@Injectable({ deps: [NotesService, Db] })
class DigestService {
  constructor(readonly notes: NotesService, readonly db: Db) {}
}

@Module({ imports: [NotesModule], providers: [DigestService] })
class DigestModule {}

@Module({ imports: [NotesModule, DatabaseModule], providers: [DigestService] })
class DigestWithDbModule {}

const app = new App();
for (const from of [DigestModule, DigestWithDbModule]) {
  try {
    const digest = app.get(from, DigestService);
    console.log(`${from.name}: один Db у сводки и заметок — ${digest.db === digest.notes.db}`);
  } catch (err) {
    console.log((err as Error).message);
  }
}

Первый модуль Db не увидел. #owner перебирает импорты DigestModule и смотрит только их экспорты, а NotesModule экспортирует NotesService, не Db. Что NotesModule импортирует сам, соседям закрыто, так же как import внутри файла не делает чужие имена его экспортом. Второй модуль импортировал базу сам, и Db оказался тем же объектом, что у заметок: владелец у него один, DatabaseModule, сколько бы модулей его ни импортировали. Так и require выполняет файл один раз, из скольких бы мест его ни подключили.

Почему бы не передавать импорты дальше? Тогда видимое сводке зависело бы от того, что заметки импортируют сегодня. Раздел заметок перешёл на кеш и убрал DatabaseModule из своих imports — и сломалась сводка, в которой не поменяли ни строки. С нетранзитивными импортами каждый модуль перечисляет всё, чем пользуется сам, и его @Module читается как полный список зависимостей раздела. Цена — длинные imports: базу и настройки приходится импортировать почти в каждый модуль.

На этот случай в Nest есть реэкспорт: модуль кладёт в exports не провайдер, а импортированный модуль целиком, и его экспорты становятся видны тем, кто импортирует посредника. Так собирают общий CoreModule с базой и настройками, как файл-витрина собирает экспорты пакета. Передача остаётся явной: открывается только то, что посредник назвал. Научить этому App — вторая задача.

imports — кого модуль видит сам. Дальше передаётся только то, что назвали в exports.

Модель повторяет поиск Nest: сначала провайдеры модуля, затем импорты, и в импортированном модуле токен обязан быть и в providers, и в exports. Прогон ниже собирает те же разделы на Nest 12.0.3. Команда nest start из пакета @nestjs/cli компилирует проект tsc по tsconfig.json и запускает результат node. В tsconfig.json включён emitDecoratorMetadata, поэтому deps не нужен. Каждый вариант связей — свой корневой модуль и своё приложение. createApplicationContext — это NestFactory.create без HTTP: только модули и провайдеры. Вместо сообщения печатается имя исключения, а если приложение собралось — «создано». Прогноз: какие из шести корней соберутся, сколько будет хранилищ и баз там, где соберутся, и найдут ли неэкспортированное хранилище два app.get в конце?

import 'reflect-metadata';
import { Injectable, Module, type Type } from '@nestjs/common';
import { NestFactory } from '@nestjs/core';

@Injectable()
class Db {}

@Module({ providers: [Db], exports: [Db] })
class DatabaseModule {}

@Injectable()
class NotesRepo {
  constructor(readonly db: Db) {}
}

@Injectable()
class NotesService {
  constructor(readonly repo: NotesRepo) {}
}

@Module({ imports: [DatabaseModule], providers: [NotesRepo, NotesService], exports: [NotesService] })
class NotesModule {}

@Injectable()
class RawDigestService {
  constructor(readonly repo: NotesRepo) {}
}

@Injectable()
class DigestService {
  constructor(readonly notes: NotesService, readonly db: Db) {}
}

// каждый корень ниже — отдельный вариант связей и отдельное приложение
@Module({ imports: [NotesModule], providers: [RawDigestService] })
class RepoNotExported {}

@Module({ imports: [NotesModule, DatabaseModule], providers: [NotesRepo, RawDigestService] })
class RepoCopied {}

@Module({ imports: [NotesModule], providers: [DigestService] })
class DbThroughNotes {}

@Module({ imports: [NotesModule, DatabaseModule], providers: [DigestService] })
class DbImported {}

@Module({ imports: [DatabaseModule], providers: [NotesRepo, NotesService], exports: [NotesService, DatabaseModule] })
class NotesReexportingDb {}

@Module({ imports: [NotesReexportingDb], providers: [DigestService] })
class DbReexported {}

@Module({ imports: [DatabaseModule], providers: [NotesRepo, NotesService], exports: [NotesService, Db] })
class NotesExportingDb {}

async function start(root: Type) {
  try {
    // abortOnError: false — иначе Nest при ошибке сборки завершает процесс, а не бросает исключение
    const app = await NestFactory.createApplicationContext(root, { logger: false, abortOnError: false });
    console.log(`${root.name}: создано`);
    return app;
  } catch (err) {
    console.log(`${root.name}: ${(err as Error).constructor.name}`);
  }
}

await start(RepoNotExported);

const copied = await start(RepoCopied);
console.log('  NotesRepo один:', copied?.get(RawDigestService).repo === copied?.get(NotesService).repo);

await start(DbThroughNotes);

const imported = await start(DbImported);
console.log('  Db один:', imported?.get(DigestService).db === imported?.get(NotesService).repo.db);

const reexported = await start(DbReexported);
console.log('  Db один:', reexported?.get(DigestService).db === reexported?.get(NotesService).repo.db);

await start(NotesExportingDb);

console.log('app.get(NotesRepo):', imported?.get(NotesRepo).constructor.name);
try {
  imported?.get(NotesRepo, { strict: true });
} catch (err) {
  console.log('app.get(NotesRepo, { strict: true }):', (err as Error).constructor.name);
}

RepoNotExported: UnknownDependenciesException
RepoCopied: создано
  NotesRepo один: false
DbThroughNotes: UnknownDependenciesException
DbImported: создано
  Db один: true
DbReexported: создано
  Db один: true
NotesExportingDb: UnknownExportException
app.get(NotesRepo): NotesRepo
app.get(NotesRepo, { strict: true }): UnknownElementException

Всё, что наш контейнер делал при первом get, Nest сделал при сборке: RepoNotExported и DbThroughNotes не собрались вовсе. Копия NotesRepo в RepoCopied собралась, и хранилищ стало два. DatabaseModule, импортированный и заметками, и сводкой, дал один Db. Реэкспорт через NotesReexportingDb сработал, а NotesExportingDb, который кладёт в exports чужой Db вместо модуля, упал с UnknownExportException. Экспортировать в Nest можно свои провайдеры и импортированные модули, но не провайдеры этих модулей по одному. Экспорты Nest проверяет, пока собирает дерево модулей, ещё до первого конструктора, и называет в сообщении модуль, который экспортирует лишнее.

Последние строки прогона — о том, где граница кончается. app.get(NotesRepo) нашёл хранилище, которое не экспортировано никуда: без strict он ищет токен во всех модулях приложения, а если токен записан в двух, отдаёт последний зарегистрированный. Со strict: true он смотрит только провайдеры самого модуля, корневого или выбранного через app.select, и в импорты не заглядывает. Граница Nest — правило внедрения через конструктор, а не замок: тест или main.ts обходят её одним вызовом. Поэтому проверять видимость через app.get бессмысленно: он найдёт и то, чего не получит конструктор в чужом модуле.

Ослабить границу можно и намеренно. @Global() над модулем заставляет Nest дописать его в imports каждого модуля приложения. Видны при этом по-прежнему только его exports, а сам модуль нужно импортировать хотя бы раз, обычно в корневом: иначе Nest о нём не узнает. Так подключают настройки — ConfigModule.forRoot с isGlobal: true: модулю, который возвращает forRoot, этот флаг даёт то же, что @Global() над классом. Когда глобальный модуль уместен, а когда прячет зависимости и что такое динамический модуль вроде forRoot, разберёт статья о модулях и областях.

И последнее: граница решает, кто видит провайдер, но не то, создаётся ли он. Неэкспортированный NotesRepo Nest создаёт при старте, как любой провайдер с областью по умолчанию, и создал бы, даже не будь у него в модуле ни одного потребителя. Зато модуль, до которого нельзя дойти по imports от корня, в приложении не существует. Декоратор @Module лишь оставил сведения о классе, а читает их Nest, начиная с корня: провайдеры забытого модуля не создаются, и обработчик очереди в нём молча не работает.