Schema-driven ORM для TypeScript: @cleverbrush/knex-schema и @cleverbrush/orm

Значимый прорыв формирует отрасль ИИ: andrew_zol 37 минут назад Schema-driven ORM для TypeScript: @cleverbrush/knex-schema и @cleverbrush/orm Средний 13 мин 757 JavaScript * TypeScript * Статья о том, как превратить TypeScript-схему в единый источник истины для работы с базой данных: из одного определения получить типы строк, имена таблиц и колонок, типизированные запросы, связи, миграции и unit-of-work поверх Knex. Все примеры ниже взяты из xpenser — open-source приложения для учёта личных доходов и расходов. Это одновременно полезное приложение, которым я сам пользуюсь, и референсная реализация Cleverbrush Framework: контракты, сервер, клиент, формы, auth, observability, PostgreSQL, Telegram bot и MCP endpoint живут в одном репозитории.

com/cleverbrush/xpenser. Дисклеймер: все описываемые библиотеки носят экспериментальный характер. Несмотря на это, покрытие тестами у них достаточно хорошее.

Технические детали

Также в данный момент в этих библиотеках поддерживается лишь Postgres в качестве сервера баз данных. ПредысторияВ предыдущих статьях я рассказывал о @cleverbrush/schema, о типизированном HTTP API через @cleverbrush/server и @cleverbrush/client, а затем о @cleverbrush/log и @cleverbrush/otel. Общая идея у всех этих пакетов одна: схема должна быть не просто валидатором, а источником структурной информации.

Если схема уже знает, что у объекта есть поле userId, что это число, что оно обязательно, и что для него можно получить PropertyDescriptor через t => t. userId, то возникает естественный вопрос: почему бы не использовать это же знание для SQL? Небольшое отступление для тех, кто не работал с Knex.

Knex — это query builder для Node. js: он позволяет писать SQL-запросы цепочками методов вместо ручной сборки строк, умеет работать с PostgreSQL, MySQL, SQLite и другими SQL-базами, поддерживает транзакции, connection pool, migrations и schema builder. Люди часто выбирают Knex, когда хотят оставаться близко к SQL, но не хотят каждый раз руками собирать SELECT ...

Отраслевые последствия

и следить за плейсхолдерами. Это хороший промежуточный слой между raw SQL и тяжёлой ORM: меньше магии, проще предсказать итоговый запрос, легко упасть на обычный SQL там, где query builder мешает. Но у Knex есть естественный предел.

TypeScript может помочь с типом строки через knex('users но имена таблиц и колонок всё равно часто остаются строками: 'users', 'user_id', 'created_at'. Если в коде доменная модель живёт в camelCase, база в snake_case, а рядом ещё есть API-контракты и валидация, появляется риск рассинхронизации. Именно этот зазор я и хотел закрыть schema-driven слоем поверх Knex.

Так появились два пакета:@cleverbrush/knex-schema — schema-aware слой поверх Knex: имена таблиц и колонок, DDL-метаданные, типизированный query builder, projections, scopes, eager loading. @cleverbrush/orm — более высокий уровень: defineEntity(), DbContext, DbSet, relations, транзакции, save graph и tracking context. Knex при этом никуда не исчезает.

Событие, по словам экспертов, усилит конкуренцию в сфере ИИ.