@crossfox/db

MySQL-слой экосистемы для Bun.SQL: QueryBuilder (100+ методов), createSchema-модели (find/insert/update, joins, hasMany, scopes, EAV-meta), кэш запросов с инвалидацией, SQL-маркеры (dbNow, dateRange, raw…), транзакции.

Runtime: только Bun (engines.bun, Bun.SQL) — не для Node.js / Deno.

Установка и старт

bun add @crossfox/db

import { initMysql, createSchema, dbBuild, configureDbEnv } from "@crossfox/db";

// boot: подключение (+ ping)
await initMysql({ host, port, database, user, password, tls: false, connectionTimeoutSec: 15 });

// Модель
type User = { id: number; name: string; status: number };
const modelUser = createSchema<User>("users", { primaryKey: "id" });

await modelUser().find({ status: 1 }, ["id", "name"]);
await modelUser().findOne({ id: 5 });
await modelUser().insert({ name: "Jan", status: 1 });

// Сложные запросы — QueryBuilder
const rows = await dbBuild()
  .select(["id", "name"]) 
  .from("users")
  .where({ status: 1, deleted_at: null })
  .order("id", "DESC")
  .paginate(1, 20);

Маркеры (вычисляются на стороне MySQL):

import { dbNow, dateRange, between, raw, inc } from "@crossfox/db/markers";

await modelToken().insert({ expires_at: dbNow(15, "minute") });
await modelOrder().find({ created_at: dateRange("2026-01-01", "2026-12-31") });
await modelItem().update({ views: inc(1) }, { id: 5 });

Интеграция с приложением (DI)

Пакет самодостаточен, но на boot можно привязать окружение приложения:

import { configureDbEnv, setApiError } from "@crossfox/db";

configureDbEnv({
  isDev: config.isDev,                       // dev: подробные ошибки, explain(), SQL-логи
  logger: myLogger,                          // logger.error(app, msg, err) → app_errors
  translate: (msg, ctx) => l(msg, ctx),      // локализация "Record not found" и т.п.
});

// Ошибки БД бросаются как твой HTTP-класс (Elysia ErrorHandler и т.п.)
setApiError((status, message, data) => { throw new MyApiError(status, message, data); });

Кэш запросов на Redis (опционально, peer-зависимость redis):

import { bindQueryCacheRedis } from "@crossfox/db";
bindQueryCacheRedis(redisClient);

Entry points

| импорт | что внутри | |---|---| | @crossfox/db | всё: dbBuild, createSchema, markers, runtime, env, ErrorHandler | | @crossfox/db/markers | dbNow, dateRange, between, raw, inc/dec… | | @crossfox/db/runtime | initMysql, connectMysql, pingMysql, closeMysql, bindQueryCacheRedis | | @crossfox/db/types | все интерфейсы (SchemaFactory, WhereCondition…) | | @crossfox/db/env | configureDbEnv / dbEnv |

Полный справочник API — JSDoc в types и шпаргалки в CLAUDE.md бэкенд-проектов экосистемы.

Разработка

bun install
bun run test               # 250 юнит-тестов (без БД)
bun run test:integration   # против живой MySQL (env: DB_HOST/PORT/USER/PASSWORD/DATABASE)
bun run check              # typecheck + test
bun run build              # dist/ (tsc, d.ts)

Связанные пакеты

• @crossfox/ws — надёжный WebSocket (протокол/клиент/react).
• queryHandler (декларативные списки поверх этого пакета) пока живёт в back-template — переедет в @crossfox/query-handler, когда API устоится.

License

PolyForm Noncommercial 1.0.0 — free for non-commercial use; copyright notice required (Required Notice: Copyright Oleksii Fursov).

Commercial use (for-profit products, SaaS, client work, etc.) needs a separate written license from the author: [email protected].