@application-kit/typeorm

Курсорный листинг на TypeORM: контракты листинга (пагинатор, сортировка, фильтры), курсорный пагинатор поверх SelectQueryBuilder, перевод фильтров в where, ORM-база сущности и конфиг соединения с Postgres из окружения.

Установка

yarn add @application-kit/typeorm

Peer-зависимости: typeorm, @nestjs/common; для входа /nest — @nestjs/cqrs, @nestjs/typeorm, nestjs-pino, class-transformer, class-validator, reflect-metadata; для DatabaseLogger входа /logging — nestjs-pino (объявлены опциональными: корню и /listing они не нужны).

Точки входа

| Вход | Что внутри | Зависимости | |---|---|---| | @application-kit/typeorm/listing | FilterInterface, FiltersMatchMode, SortingInterface, SortOrder, PaginatorInterface, ListingRepositoryInterface | нет — годится для браузерного кода | | @application-kit/typeorm | getListByCursor, CursorPaginator, getWhereByFilters, isUniqueViolation, estimateRowCount, withIdTiebreaker, AbstractOrmEntity, PackageOrmInterface | typeorm, @nestjs/common | | @application-kit/typeorm/nest | TypeormRootModule, ListingQuery, ListingHandler, DatabaseConfig, DatabaseEnvironment, createCliDataSource | @nestjs/common, @nestjs/cqrs, @nestjs/typeorm, nestjs-pino, class-transformer, class-validator, reflect-metadata | | @application-kit/typeorm/logging | createTypeormLogger, TypeormQueryLogger, createSqlParameterMask, runAsInfrastructureQuery, isInfrastructureQuery, SqlLoggerInterface, DatabaseLogger | nestjs-pino — createTypeormLogger и DatabaseLogger |

Клиент (Vue, GraphQL-типы) импортирует только /listing: корень тянет TypeORM и Nest. Nest-интеграции (DI-модули, CQRS, конфиг) — только во входе /nest, корень их не реэкспортирует и @nestjs/typeorm/nestjs-pino не тянет.

Листинг в репозитории

import { getListByCursor } from '@application-kit/typeorm'
import type { ListingRepositoryInterface } from '@application-kit/typeorm/listing'

export class UserRepository implements ListingRepositoryInterface<User> {
  public async list(paginator, sorting, filters) {
    return getListByCursor(UserEntity, this.repository.createQueryBuilder('user'), toDomain, paginator, filters, sorting)
  }
}

Неверный курсор страницы — InvalidPageCursorError (BadRequestException, HTTP 400).

Обработчик query

import { ListingHandler, ListingQuery } from '@application-kit/typeorm/nest'

export class GetUsersQuery extends ListingQuery {}

@QueryHandler(GetUsersQuery)
export class GetUsersHandler extends ListingHandler<User> {
  public constructor(@Inject(USER_REPOSITORY) repository: UserRepository) {
    super(repository)
  }
}

ORM-база

AbstractOrmEntity — колонки id (uuid), createdAt, updatedAt; OrmEntityProps<E> — свойства сущности без них. Имя отличается от доменного AbstractEntity из DDD-библиотек намеренно.

Логгер SQL

TypeormQueryLogger — адаптер Logger TypeORM поверх любого pino-совместимого логгера (SqlLoggerInterface: debug/info/warn/error). SQL приложения пишется на info с bind-параметрами, медленный запрос — warn, упавший — error с ошибкой под ключом err; SQL из области runAsInfrastructureQuery (пробы health, которые иначе дают до 97 % потока логов сервиса) уходит на debug.

createTypeormLogger(pinoParams, maskSqlParameters?) — сборка на pino-логгере: TypeormQueryLogger поверх DatabaseLogger с маской по умолчанию. Одна сборка на корень соединения (TypeormRootModule) и CLI миграций — калибровка маски у них не разъедется. Маска bind-параметров — аргумент:

import { createSqlParameterMask, createTypeormLogger } from '@application-kit/typeorm/logging'

const maskSqlParameters = createSqlParameterMask({
  // Порог усечения строки; по умолчанию 256 — user-agent сессии доезжает целиком, дамп обрезается.
  maxValueLength: 256,
  // Формы потребителя проверяются раньше форм по умолчанию.
  forms: [{ label: 'session-token', pattern: /^[\da-f]{64}$/u }],
})

const logger = createTypeormLogger(pinoParams, maskSqlParameters)

Маска смотрит на форму значения, а не на имя колонки (параметры TypeORM позиционные): по умолчанию скрываются bcrypt-хеши, JWT, hex-хеши от 32 символов, шифротекст AES-GCM из трёх base64-кусков, base32 от 16 символов и base64 от 40 — на месте значения метка [masked:<label>]; значение длиннее порога — префикс с пометкой …[truncated:<длина>]. Остальные значения (email, идентификаторы, числа) остаются в логе: по ним разбирают заявки. Массив параметром обходится поэлементно, объекты (JSONB) — нет. Секрет с формой обычного текста маска не ловит.

DatabaseLogger — отдельный PinoLogger с контекстом DatabaseLogger: контекст живёт в экземпляре, и общий логгер приложения под SQL занимать нельзя. Область пробы открывает вызывающий:

return runAsInfrastructureQuery(async () => this.health.check(indicators))

Соединение с Postgres

DatabaseConfig собирает DataSourceOptions из окружения DB_* (DatabaseEnvironment — класс валидации class-validator): соединение всегда с верификацией сертификата сервера, statement_timeout сессии, стратегия имён TypeormPluralNamingStrategy (зависимость пакета) — под неё пишутся сущности и миграции потребителя. entities, migrations и logger в опциях нет — их добавляет вызывающий.

| Переменная | Назначение | |---|---| | DB_HOST, DB_PORT, DB_DATABASE, DB_USERNAME, DB_PASSWORD | адрес и учётные данные | | DB_SSL_CA_FILE | путь к CA сервера БД — обязателен во всех окружениях; нечитаемый файл роняет процесс на буте, а не отключает проверку | | DB_STATEMENT_TIMEOUT_MS | потолок времени SQL-запроса, мс; не задан — без потолка. Задаётся процессам, обслуживающим пользовательские запросы; миграциям, CLI и консьюмерам — нет: у них легитимно долгие запросы |

Регистрацию и валидацию окружения делает приложение — пакет отдаёт классы и корень соединения:

import { DatabaseConfig, DatabaseEnvironment, TypeormRootModule } from '@application-kit/typeorm/nest'

// @libs-for-dev/nestjs-config-module: конфиг и env-класс — провайдеры, валидация на старте
const databaseConfigsModule = ConfigsModule.forFeature([DatabaseConfig], [DatabaseEnvironment])

TypeormRootModule.forRoot({ imports: [databaseConfigsModule] })

TypeormRootModule.forRoot({ imports, maskSqlParameters? }) — TypeOrmModule.forRootAsync с опциями DatabaseConfig, autoLoadEntities (entities пакетов kit регистрирует их собственный TypeOrmModule.forFeature) и логгером createTypeormLogger. Логгер собирается из параметров глобального LoggerModule nestjs-pino (PARAMS_PROVIDER_TOKEN): он обязан быть в графе процесса.

createDataSourceOptions({ maxQueryExecutionTime }) — порог медленного запроса для логгера TypeORM, по умолчанию 1000 мс.

CLI миграций

createCliDataSource собирает DataSource для typeorm -d без Nest-контейнера: опции DatabaseConfig, миграции и entities продукта глобами и таблицы пакетов — их объекты orm (PackageOrmInterface: классы entities и миграций).

import { orm as mailerOrm } from '@application-kit/mailer'
import { orm as outboxOrm } from '@application-kit/transaction-outbox'
import { createCliDataSource, DatabaseConfig, DatabaseEnvironment } from '@application-kit/typeorm/nest'

export default createCliDataSource({
  app: { buildDirs: ['modules', 'libs'], sourceDirs: ['src'] },
  config: new DatabaseConfig(exposeObjectWithValidation(process.env, DatabaseEnvironment)),
  logger: typeormQueryLogger,
  packages: [outboxOrm, mailerOrm],
})

Каталоги — относительно cwd CLI; внутри каждого миграции ищутся по **/typeorm/migrations/, entities — по **/typeorm/entities/. sourceDirs — исходники под ts-node: миграции .ts/.js и entities (по ним migration:generate сравнивает схему). buildDirs — скомпилированный код образа: только миграции .js (рядом лежат .d.ts), entities для migration:run не нужны. Глоб по корню образа не годится — он нашёл бы миграции пакетов в node_modules дважды (ESM и CJS), поэтому пакеты отдают классы. logger обязателен: без него CLI пишет дефолтным логгером TypeORM простым текстом, мимо маски bind-параметров (/logging).