@quark-fw/clisma 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Drus
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,293 @@
+# clisma
+
+**Prisma-подобный клиент и мигратор для ClickHouse.**
+
+Зачем: в проектах, где Postgres (данные кампаний, Prisma) живёт рядом с ClickHouse
+(клики/события), запросы приходится писать двумя разными способами и вручную
+синхронизировать схемы. clisma даёт ClickHouse тот же синтаксис запросов, что у
+Prisma — `prisma.user.findMany(...)` переносится как `db.user.findMany(...)` почти
+без изменений — плюс миграции схемы.
+
+```ts
+const users = await db.users.findMany({
+	where: {
+		email: { endsWith: "@gmail.com" },
+		age: { gte: 18 },
+		OR: [{ name: null }, { name: { startsWith: "A" } }]
+	},
+	select: { id: true, email: true },
+	orderBy: { createdAt: "desc" },
+	take: 100
+})
+```
+
+---
+
+## Установка
+
+```bash
+npm i @quark-fw/clisma
+```
+
+Требования: Node.js >= 20. Пакет ESM-only (`import`), CommonJS-сборки нет.
+
+## Быстрый старт
+
+```ts
+// db.clisma.ts — схема
+import { createClisma, table, t } from "@quark-fw/clisma"
+
+export const schema = createClisma({
+	database: "analytics",
+	tables: {
+		users: table({
+			engine: "MergeTree",
+			orderBy: ["id"],
+			columns: {
+				id: t.uint64(),
+				email: t.string(),
+				name: t.nullable(t.string()),
+				age: t.nullable(t.uint8()),
+				createdAt: t.datetime()
+			}
+		})
+	}
+})
+```
+
+```ts
+// приложение
+import { createClient } from "@quark-fw/clisma"
+import { schema } from "./db.clisma.js"
+
+const db = createClient(schema, {
+	url: "http://localhost:8123",
+	username: "default",
+	password: "",
+	autoCreateDatabase: true
+})
+
+await db.$migrate()                      // привести БД к схеме
+
+const user = await db.users.create({
+	data: { email: "a@b.c", createdAt: new Date() }   // id сгенерируется
+})
+```
+
+Все типы выводятся из схемы: `db.users.findMany()` возвращает
+`{ id: bigint; email: string; name: string | null; age: number | null; createdAt: Date }[]`,
+`select` сужает тип результата, `where` принимает только существующие колонки.
+
+---
+
+## Перенос кода с Prisma
+
+| Prisma (Postgres)                    | clisma (ClickHouse)                  | Отличия |
+|--------------------------------------|--------------------------------------|---------|
+| `prisma.user.findMany(args)`         | `db.user.findMany(args)`             | тот же синтаксис `where/select/orderBy/take/skip` |
+| `prisma.user.findFirst(args)`        | `db.user.findFirst(args)`            | — |
+| `prisma.user.findUnique({where})`    | `db.user.findFirst({where})`         | в ClickHouse нет уникальных ключей — «уникальность» не гарантируется БД |
+| `prisma.user.create({data})`         | `db.user.create({data})`             | возвращаемая строка собирается на клиенте, см. ниже |
+| `prisma.user.createMany({data})`     | `db.user.createMany({data})`         | — |
+| `prisma.user.update({where, data})`  | `db.user.updateMany({where, data})`  | без unique-ключей одиночного `update` нет |
+| `prisma.user.updateMany(...)`        | `db.user.updateMany(...)`            | механика зависит от стратегии таблицы, см. «Мутации» |
+| `prisma.user.delete({where})`        | `db.user.deleteMany({where})`        | аналогично |
+| `prisma.user.deleteMany(...)`        | `db.user.deleteMany(...)`            | — |
+| `prisma.user.count({where})`         | `db.user.count({where})`             | — |
+| `aggregate` / `groupBy` / `distinct` | пока нет                             | в планах; `distinct` будет через `LIMIT 1 BY` |
+| `$transaction`                       | нет                                  | ClickHouse не транзакционен |
+
+### Операторы `where`
+
+Поддержан Prisma-синтаксис:
+
+- shorthand: `{ email: "a@b.c" }`, `{ name: null }` → `IS NULL`
+- сравнения: `equals`, `not` (значение или `null`), `in`, `notIn`, `lt`, `lte`, `gt`, `gte`
+- строки: `contains`, `startsWith`, `endsWith` (без LIKE — через `position()/startsWith()/endsWith()`, спецсимволы экранировать не нужно)
+- логика: `AND` (объект или массив), `OR` (массив), `NOT` — вкладываются рекурсивно
+- `in: []` не матчит ничего, `notIn: []` матчит всё (как в Prisma)
+
+Не поддержано (пока): вложенный фильтр в `not`, `mode: "insensitive"`,
+`has/hasSome/hasEvery` для Array-колонок (Array-колонки в `where` запрещены на уровне типов).
+
+---
+
+## Схема
+
+### Типы колонок
+
+| Фабрика            | ClickHouse            | TypeScript |
+|--------------------|-----------------------|------------|
+| `t.string()`       | `String`              | `string`   |
+| `t.uint8()`        | `UInt8`               | `number`   |
+| `t.int32()`        | `Int32`               | `number`   |
+| `t.uint64()`       | `UInt64`              | `bigint`   |
+| `t.boolean()`      | `Bool`                | `boolean`  |
+| `t.datetime()`     | `DateTime`            | `Date`     |
+| `t.nullable(col)`  | `Nullable(...)`       | `T \| null`|
+| `t.array(col)`     | `Array(...)`          | `T[]`      |
+
+Пока нет: `DateTime64`, `Decimal`, `Enum`, `LowCardinality`, `DEFAULT`,
+`PARTITION BY`, `TTL`.
+
+### Колонка `id`
+
+Если в таблице есть колонка `id` и при `create`/`insert` значение не передано,
+clisma генерирует уникальный `bigint` (timestamp в старших битах + счётчик —
+уникален в пределах процесса, монотонно растёт).
+
+---
+
+## Клиент
+
+```ts
+const db = createClient(schema, {
+	url,                       // http://host:8123
+	username, password,
+	database,                  // приоритетнее schema.database
+	autoCreateDatabase: true   // $init/$migrate создадут БД
+})
+```
+
+- `db.<table>` — клиент таблицы (см. API ниже)
+- `db.$init()` — создать БД и таблицы (`CREATE ... IF NOT EXISTS`), без диффа
+- `db.$migrate()` — привести БД к схеме (см. «Миграции»)
+
+## Миграции: `db.$migrate()`
+
+Сравнивает живую схему (`system.columns`) с кодом и применяет разницу:
+
+- таблицы нет → `CREATE TABLE`
+- колонки нет → `ALTER TABLE ... ADD COLUMN`
+- тип отличается → `ALTER TABLE ... MODIFY COLUMN`
+
+Возвращает `{ statements, warnings }` — применённые SQL и предупреждения.
+Повторный запуск на совпадающей схеме — пустой план (идемпотентно).
+
+**Ограничения (осознанные):**
+
+- лишние колонки в БД **никогда не удаляются** — только warning;
+- `ENGINE`, `ORDER BY`, `PARTITION BY` не диффятся — их изменение требует
+  пересоздания таблицы вручную;
+- `MODIFY COLUMN` ключевой колонки (из `ORDER BY`) отклонит сам ClickHouse;
+- нет файлов/истории миграций как у `prisma migrate` — сравнение всегда
+  с живой схемой.
+
+---
+
+## API таблицы
+
+### Чтение
+
+- `findMany({ where?, select?, orderBy?, take?, skip? })` → `Row[]`
+- `findFirst({ where?, select?, orderBy?, skip? })` → `Row | null`
+- `count({ where? })` → `number`
+
+### Запись
+
+- `create({ data })` → созданная строка. **Строка собирается на клиенте**
+  (data + сгенерированный id; пропущенные nullable-поля становятся `null`,
+  `Date` обрезается до секунд) — без чтения с сервера. Если в таблице появятся
+  серверные `DEFAULT`/`MATERIALIZED` колонки, в возвращённой строке их не будет.
+- `createMany({ data })` → `{ count }`; пустой массив не ходит в БД.
+- `insert(row | rows)` — низкоуровневая вставка без возврата строк.
+
+### Мутации
+
+- `updateMany({ where?, data })` → `{ count }`
+- `deleteMany({ where? })` → `{ count }`
+
+Без `where` операция затрагивает **все строки** таблицы.
+Обновлять колонки из `ORDER BY` нельзя (ошибка до запроса к БД).
+
+**`count` в ответе** считается отдельным запросом до мутации — при
+конкурентной записи между `count` и мутацией число может отличаться от
+фактически затронутых строк (ClickHouse не возвращает affected rows).
+
+---
+
+## Мутации: стратегия на уровне таблицы
+
+ClickHouse — не OLTP: `UPDATE`/`DELETE` в нём принципиально дороже, чем в
+Postgres. clisma поддерживает три механизма; выбор — поле `mutations` таблицы:
+
+```ts
+table({
+	engine: "ReplacingMergeTree",
+	orderBy: ["id"],
+	mutations: "replacing",   // "alter" (по умолчанию) | "lightweight" | "replacing"
+	columns: { ... }
+})
+```
+
+| Стратегия      | updateMany                        | deleteMany                  | Чтения       |
+|----------------|-----------------------------------|-----------------------------|--------------|
+| `"alter"` (default) | `ALTER TABLE ... UPDATE` (тяжёлая мутация, перезаписывает парты; ждём завершения — `mutations_sync=1`) | `ALTER TABLE ... DELETE` (аналогично) | обычные |
+| `"lightweight"`| **фолбэк на `ALTER UPDATE`** — стабильного lightweight update в ClickHouse нет | `DELETE FROM` (быстрые «надгробия», `lightweight_deletes_sync=2`) | обычные |
+| `"replacing"`  | SELECT подходящих строк (FINAL) → вставка новых версий строк | `DELETE FROM` (lightweight) | автоматически с `FINAL` |
+
+Как выбирать:
+
+- **append-only таблицы** (клики, события) — не трогайте мутации вообще;
+  стратегия не важна, оставьте `"alter"` по умолчанию.
+- **редкие массовые правки** (GDPR-удаление, backfill) — `"alter"`:
+  честная мутация, дорого, зато таблица остаётся обычным MergeTree.
+- **частые удаления, редкие обновления** — `"lightweight"`: удаление дешёвое,
+  но помните, что update молча превращается в тяжёлый ALTER.
+- **мутабельные сущности** (сессии, статусы, профили) — `"replacing"` +
+  `ReplacingMergeTree`: «обновление» — это дешёвая вставка новой версии.
+
+Особенности `"replacing"`:
+
+- требуется engine семейства `ReplacingMergeTree` (включая
+  `ReplicatedReplacingMergeTree`) — проверяется при объявлении таблицы;
+- все чтения (`findMany`/`findFirst`/`count`) идут с `FINAL` — корректно,
+  но дороже обычного SELECT на больших таблицах;
+- без колонки-версии `ReplacingMergeTree()` оставляет последнюю *вставленную*
+  строку; для детерминизма добавьте колонку версии
+  (`ReplacingMergeTree(ver)`) и включайте её в `data` при обновлении;
+- `updateMany` пере-вставляет строки с теми же значениями `ORDER BY` —
+  поэтому менять ключевые колонки запрещено.
+
+---
+
+## Особенности работы с ClickHouse (важно)
+
+Эти решения зашиты в clisma, потому что дефолты ClickHouse/клиента ломают
+корректность:
+
+1. **Вставки ждут флаша** (`wait_for_async_insert=1` на каждом insert).
+   Если на сервере включён `async_insert=1, wait_for_async_insert=0`,
+   вставки подтверждаются *до* парсинга: ошибки молча теряются вместе с
+   данными, а свежие строки не видны следующему SELECT.
+2. **Мутации синхронные** (`mutations_sync=1`, `lightweight_deletes_sync=2`) —
+   после `updateMany`/`deleteMany` чтение сразу видит результат.
+3. **`Date` ⇄ `DateTime`**: в параметрах и вставках даты передаются
+   unix-секундами (тип `DateTime` секундной точности не принимает ISO-строки
+   с миллисекундами); в ответах включён `date_time_output_format=iso`, и
+   строки парсятся в `Date` без таймзонной неоднозначности.
+4. **`bigint` без потери точности**: включён
+   `output_format_json_quote_64bit_integers=1` — `UInt64/Int64` приходят
+   строками и превращаются в `bigint` (иначе `JSON.parse` терял бы точность).
+5. Все идентификаторы (БД, таблицы, колонки) экранируются бэктиками; все
+   значения передаются серверными query-параметрами `{p:Тип}` с типом из
+   схемы — SQL-инъекции через значения невозможны.
+
+---
+
+## Тесты
+
+```bash
+npm run test:unit   # юнит-тесты (node:test): SQL-генерация, стратегии, миграции
+npm test            # smoke на живом ClickHouse (src/test/.env), убирает за собой
+npx tsc --noEmit    # проверка типов — обязательный гейт (tsx типы не проверяет)
+```
+
+## Ограничения / roadmap
+
+- нет `aggregate`, `groupBy`, `distinct` (план: `LIMIT 1 BY`), `findUnique`, `upsert`;
+- нет вложенного `not`, `mode: "insensitive"`, операторов для Array-колонок;
+- нет файлов миграций/истории; дифф только add/modify колонок;
+- нет `DateTime64`/`Decimal`/`Enum`/`LowCardinality`, `DEFAULT`, `PARTITION BY`, `TTL`;
+- `create` без серверного round-trip (см. выше);
+- нет relations/include — ClickHouse-философия: денормализуйте.

package/dist/client.d.ts

@@ -0,0 +1,18 @@
+import { TableClient } from "./table-client.js";
+import { InferRow } from "./table.js";
+import { MigrationPlan } from "./migrate.js";
+type ClientOptions = {
+    url: string;
+    username?: string;
+    password?: string;
+    database?: string;
+    autoCreateDatabase?: boolean;
+};
+export declare function createClient<TSchema extends {
+    database?: string;
+    tables: Record<string, any>;
+}>(schema: TSchema, options: ClientOptions): { [K in keyof TSchema["tables"]]: TableClient<InferRow<TSchema["tables"][K]>>; } & {
+    $init(): Promise<void>;
+    $migrate(): Promise<MigrationPlan>;
+};
+export {};

package/dist/client.js

@@ -0,0 +1,63 @@
+import { createClient as createCHClient } from "@clickhouse/client";
+import { TableClient } from "./table-client.js";
+import { buildCreateTableSQL } from "./ddl.js";
+import { escapeId } from "./sql.js";
+import { buildMigrationPlan } from "./migrate.js";
+export function createClient(schema, options) {
+    const database = options.database ?? schema.database ?? "default";
+    const ch = createCHClient({
+        url: options.url,
+        username: options.username,
+        password: options.password,
+        database
+    });
+    const db = {};
+    for (const tableName in schema.tables) {
+        db[tableName] = new TableClient(database, tableName, schema.tables[tableName], ch);
+    }
+    const ensureDatabase = async () => {
+        if (options.autoCreateDatabase) {
+            const rootClient = createCHClient({
+                url: options.url,
+                username: options.username,
+                password: options.password
+            });
+            try {
+                await rootClient.command({
+                    query: `CREATE DATABASE IF NOT EXISTS ${escapeId(database)}`
+                });
+            }
+            finally {
+                await rootClient.close();
+            }
+        }
+    };
+    db.$init = async () => {
+        await ensureDatabase();
+        for (const tableName in schema.tables) {
+            const table = schema.tables[tableName];
+            const createSQL = buildCreateTableSQL(database, tableName, table);
+            await ch.command({ query: createSQL });
+        }
+    };
+    db.$migrate = async () => {
+        await ensureDatabase();
+        const result = await ch.query({
+            query: `
+				SELECT table, name, type
+				FROM system.columns
+				WHERE database = {db:String}
+				ORDER BY table, position
+			`,
+            query_params: { db: database },
+            format: "JSONEachRow"
+        });
+        const existing = await result.json();
+        const plan = buildMigrationPlan(database, schema.tables, existing);
+        for (const statement of plan.statements) {
+            await ch.command({ query: statement });
+        }
+        return plan;
+    };
+    return db;
+}

package/dist/column.d.ts

@@ -0,0 +1,17 @@
+export type Column<T> = {
+    clickhouseType: string;
+    nullable: boolean;
+    __type?: T;
+};
+type NullableColumn<C extends Column<any>> = C extends Column<infer T> ? Column<T | null> : never;
+export declare const t: {
+    string: () => Column<string>;
+    uint8: () => Column<number>;
+    uint64: () => Column<bigint>;
+    int32: () => Column<number>;
+    boolean: () => Column<boolean>;
+    datetime: () => Column<Date>;
+    nullable<C extends Column<any>>(col: C): NullableColumn<C>;
+    array<C extends Column<any>>(col: C): Column<C extends Column<infer T> ? T[] : never>;
+};
+export {};

package/dist/column.js

@@ -0,0 +1,31 @@
+// src/column.ts
+function makeColumn(clickhouseType, nullable = false) {
+    return {
+        clickhouseType,
+        nullable,
+    };
+}
+function uint64Id() {
+    return {
+        clickhouseType: "UInt64",
+        nullable: false,
+        autoId: true // phantom field для TS
+    };
+}
+export const t = {
+    string: () => makeColumn("String"),
+    uint8: () => makeColumn("UInt8"),
+    uint64: () => makeColumn("UInt64"),
+    int32: () => makeColumn("Int32"),
+    boolean: () => makeColumn("Bool"),
+    datetime: () => makeColumn("DateTime"),
+    nullable(col) {
+        return {
+            clickhouseType: `Nullable(${col.clickhouseType})`,
+            nullable: true,
+        };
+    },
+    array(col) {
+        return makeColumn(`Array(${col.clickhouseType})`);
+    }
+};

package/dist/ddl.d.ts

@@ -0,0 +1,2 @@
+import { TableDefinition } from "./table.js";
+export declare function buildCreateTableSQL(database: string, tableName: string, table: TableDefinition<any>): string;

package/dist/ddl.js

@@ -0,0 +1,17 @@
+// src/ddl.ts
+import { escapeId } from "./sql.js";
+export function buildCreateTableSQL(database, tableName, table) {
+    const columnsSQL = Object.entries(table.columns)
+        .map(([name, col]) => {
+        return `${escapeId(name)} ${col.clickhouseType}`;
+    })
+        .join(",\n");
+    return `
+    CREATE TABLE IF NOT EXISTS ${escapeId(database)}.${escapeId(tableName)}
+    (
+      ${columnsSQL}
+    )
+    ENGINE = ${table.engine}
+    ORDER BY (${table.orderBy.map(escapeId).join(", ")})
+  `.trim();
+}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export * from "./column.js";
+export * from "./table.js";
+export * from "./schema.js";
+export * from "./client.js";
+export * from "./where.js";
+export * from "./sql.js";
+export * from "./table-client.js";
+export * from "./rows.js";
+export * from "./migrate.js";

package/dist/index.js

@@ -0,0 +1,9 @@
+export * from "./column.js";
+export * from "./table.js";
+export * from "./schema.js";
+export * from "./client.js";
+export * from "./where.js";
+export * from "./sql.js";
+export * from "./table-client.js";
+export * from "./rows.js";
+export * from "./migrate.js";

package/dist/migrate.d.ts

@@ -0,0 +1,11 @@
+import { TableDefinition } from "./table.js";
+export type DbColumn = {
+    table: string;
+    name: string;
+    type: string;
+};
+export type MigrationPlan = {
+    statements: string[];
+    warnings: string[];
+};
+export declare function buildMigrationPlan(database: string, tables: Record<string, TableDefinition<any>>, existing: DbColumn[]): MigrationPlan;

package/dist/migrate.js

@@ -0,0 +1,42 @@
+// src/migrate.ts
+import { buildCreateTableSQL } from "./ddl.js";
+import { escapeId } from "./sql.js";
+export function buildMigrationPlan(database, tables, existing) {
+    const statements = [];
+    const warnings = [];
+    const dbTables = new Map();
+    for (const col of existing) {
+        let cols = dbTables.get(col.table);
+        if (!cols) {
+            cols = new Map();
+            dbTables.set(col.table, cols);
+        }
+        cols.set(col.name, col.type);
+    }
+    for (const tableName in tables) {
+        const def = tables[tableName];
+        const dbCols = dbTables.get(tableName);
+        if (!dbCols) {
+            statements.push(buildCreateTableSQL(database, tableName, def));
+            continue;
+        }
+        const tableRef = `${escapeId(database)}.${escapeId(tableName)}`;
+        for (const colName in def.columns) {
+            const wanted = def.columns[colName].clickhouseType;
+            const actual = dbCols.get(colName);
+            if (actual === undefined) {
+                statements.push(`ALTER TABLE ${tableRef} ADD COLUMN ${escapeId(colName)} ${wanted}`);
+            }
+            else if (actual !== wanted) {
+                statements.push(`ALTER TABLE ${tableRef} MODIFY COLUMN ${escapeId(colName)} ${wanted}`);
+            }
+        }
+        for (const dbColName of dbCols.keys()) {
+            if (!(dbColName in def.columns)) {
+                warnings.push(`Column "${dbColName}" exists in ${database}.${tableName} ` +
+                    `but not in the schema — not dropped, remove it manually if unneeded`);
+            }
+        }
+    }
+    return { statements, warnings };
+}

package/dist/rows.d.ts

@@ -0,0 +1,2 @@
+import { Column } from "./column.js";
+export declare function deserializeRows<T>(rows: any[], columns: Record<string, Column<any>>): T[];

package/dist/rows.js

@@ -0,0 +1,31 @@
+// src/rows.ts
+const BIGINT_TYPES = new Set([
+    "UInt64", "Int64", "UInt128", "Int128", "UInt256", "Int256"
+]);
+function convertValue(value, chType) {
+    if (value === null || value === undefined)
+        return value;
+    const nullable = /^Nullable\((.+)\)$/.exec(chType);
+    if (nullable)
+        return convertValue(value, nullable[1]);
+    const array = /^Array\((.+)\)$/.exec(chType);
+    if (array) {
+        return value.map(v => convertValue(v, array[1]));
+    }
+    if (BIGINT_TYPES.has(chType))
+        return BigInt(value);
+    if (chType.startsWith("DateTime") || chType.startsWith("Date")) {
+        return new Date(value);
+    }
+    return value;
+}
+export function deserializeRows(rows, columns) {
+    return rows.map(row => {
+        const out = {};
+        for (const k in row) {
+            const col = columns[k];
+            out[k] = col ? convertValue(row[k], col.clickhouseType) : row[k];
+        }
+        return out;
+    });
+}

package/dist/schema.d.ts

@@ -0,0 +1,5 @@
+export type ClismaSchema<TTables extends Record<string, any>> = {
+    database?: string;
+    tables: TTables;
+};
+export declare function createClisma<TTables extends Record<string, any>>(schema: ClismaSchema<TTables>): ClismaSchema<TTables>;

package/dist/schema.js

@@ -0,0 +1,4 @@
+// src/schema.ts
+export function createClisma(schema) {
+    return schema;
+}

package/dist/sql.d.ts

@@ -0,0 +1,25 @@
+import { TableDefinition } from "./table.js";
+import { WhereInput } from "./where.js";
+export type SQLBuildResult = {
+    sql: string;
+    params: Record<string, any>;
+};
+export type OrderByInput<T> = {
+    [K in keyof T]?: "asc" | "desc";
+};
+export type FindManyArgs<T> = {
+    where?: WhereInput<T>;
+    select?: {
+        [K in keyof T]?: boolean;
+    };
+    orderBy?: OrderByInput<T> | OrderByInput<T>[];
+    take?: number;
+    skip?: number;
+};
+export declare function escapeId(name: string): string;
+export declare function buildFindManyQuery(database: string, tableName: string, table: TableDefinition<any>, args?: FindManyArgs<any>): SQLBuildResult;
+export declare function buildCountQuery(database: string, tableName: string, table: TableDefinition<any>, where?: WhereInput<any>): SQLBuildResult;
+export declare function validateUpdateData(table: TableDefinition<any>, tableName: string, data: Record<string, any>): string[];
+export declare function buildUpdateQuery(database: string, tableName: string, table: TableDefinition<any>, where: WhereInput<any> | undefined, data: Record<string, any>): SQLBuildResult;
+export declare function buildDeleteQuery(database: string, tableName: string, table: TableDefinition<any>, where?: WhereInput<any>): SQLBuildResult;
+export declare function buildLightweightDeleteQuery(database: string, tableName: string, table: TableDefinition<any>, where?: WhereInput<any>): SQLBuildResult;

package/dist/sql.js

@@ -0,0 +1,255 @@
+// src/sql.ts
+export function escapeId(name) {
+    return "`" + name.replace(/\\/g, "\\\\").replace(/`/g, "\\`") + "`";
+}
+// UInt64 max — used to emulate a bare OFFSET (skip without take)
+const NO_LIMIT = "18446744073709551615";
+// DateTime is second-precision; the client would send Date with
+// a fractional part, which ClickHouse rejects — send unix seconds.
+function serialize(value) {
+    if (value instanceof Date) {
+        return Math.floor(value.getTime() / 1000);
+    }
+    if (Array.isArray(value)) {
+        return value.map(serialize);
+    }
+    return value;
+}
+function createBuildContext(tableName, columns) {
+    const params = {};
+    let paramIndex = 0;
+    function colRef(key) {
+        if (!columns[key]) {
+            throw new Error(`Unknown column "${key}" in table "${tableName}"`);
+        }
+        return escapeId(key);
+    }
+    function baseType(key) {
+        const chType = columns[key].clickhouseType;
+        const m = /^Nullable\((.+)\)$/.exec(chType);
+        return m ? m[1] : chType;
+    }
+    function addParam(value, type) {
+        const name = `p${paramIndex++}`;
+        params[name] = serialize(value);
+        return `{${name}:${type}}`;
+    }
+    function buildFieldFilter(key, filter) {
+        const col = colRef(key);
+        const conditions = [];
+        for (const op in filter) {
+            const value = filter[op];
+            if (value === undefined)
+                continue;
+            switch (op) {
+                case "equals":
+                    conditions.push(value === null
+                        ? `${col} IS NULL`
+                        : `${col} = ${addParam(value, baseType(key))}`);
+                    break;
+                case "not":
+                    conditions.push(value === null
+                        ? `${col} IS NOT NULL`
+                        : `${col} != ${addParam(value, baseType(key))}`);
+                    break;
+                case "in":
+                    conditions.push(value.length === 0
+                        ? "0"
+                        : `${col} IN ${addParam(value, `Array(${baseType(key)})`)}`);
+                    break;
+                case "notIn":
+                    if (value.length > 0) {
+                        conditions.push(`${col} NOT IN ${addParam(value, `Array(${baseType(key)})`)}`);
+                    }
+                    break;
+                case "lt":
+                case "lte":
+                case "gt":
+                case "gte": {
+                    const cmp = { lt: "<", lte: "<=", gt: ">", gte: ">=" }[op];
+                    conditions.push(`${col} ${cmp} ${addParam(value, baseType(key))}`);
+                    break;
+                }
+                case "contains":
+                    conditions.push(`position(${col}, ${addParam(value, "String")}) > 0`);
+                    break;
+                case "startsWith":
+                    conditions.push(`startsWith(${col}, ${addParam(value, "String")})`);
+                    break;
+                case "endsWith":
+                    conditions.push(`endsWith(${col}, ${addParam(value, "String")})`);
+                    break;
+                default:
+                    throw new Error(`Unknown operator "${op}" for column "${key}"`);
+            }
+        }
+        return conditions;
+    }
+    function isFilterObject(value) {
+        return (value !== null &&
+            typeof value === "object" &&
+            !(value instanceof Date) &&
+            !Array.isArray(value));
+    }
+    function whereSQL(where) {
+        const parts = [];
+        for (const key in where) {
+            const value = where[key];
+            if (value === undefined)
+                continue;
+            if (key === "AND") {
+                const list = Array.isArray(value) ? value : [value];
+                for (const w of list) {
+                    const c = whereSQL(w);
+                    if (c)
+                        parts.push(`(${c})`);
+                }
+            }
+            else if (key === "OR") {
+                const conds = value
+                    .map((w) => whereSQL(w))
+                    .filter(Boolean)
+                    .map((c) => `(${c})`);
+                if (conds.length)
+                    parts.push(`(${conds.join(" OR ")})`);
+            }
+            else if (key === "NOT") {
+                const list = Array.isArray(value) ? value : [value];
+                for (const w of list) {
+                    const c = whereSQL(w);
+                    if (c)
+                        parts.push(`NOT (${c})`);
+                }
+            }
+            else if (value === null) {
+                parts.push(`${colRef(key)} IS NULL`);
+            }
+            else if (isFilterObject(value)) {
+                parts.push(...buildFieldFilter(key, value));
+            }
+            else {
+                parts.push(`${colRef(key)} = ${addParam(value, baseType(key))}`);
+            }
+        }
+        return parts.join(" AND ");
+    }
+    return { params, colRef, baseType, addParam, whereSQL };
+}
+function tableRef(database, tableName, table) {
+    const ref = `${escapeId(database)}.${escapeId(tableName)}`;
+    // replacing tables must read the latest row versions
+    return table.mutations === "replacing" ? `${ref} FINAL` : ref;
+}
+function checkPagination(name, value) {
+    if (!Number.isInteger(value) || value < 0) {
+        throw new Error(`"${name}" must be a non-negative integer, got: ${value}`);
+    }
+}
+export function buildFindManyQuery(database, tableName, table, args = {}) {
+    const ctx = createBuildContext(tableName, table.columns);
+    // SELECT
+    let selectSQL = "*";
+    if (args.select) {
+        const keys = Object.keys(args.select).filter(k => args.select[k] === true);
+        if (keys.length) {
+            selectSQL = keys.map(ctx.colRef).join(", ");
+        }
+    }
+    const clauses = [
+        `SELECT ${selectSQL} FROM ${tableRef(database, tableName, table)}`
+    ];
+    // WHERE
+    if (args.where) {
+        const where = ctx.whereSQL(args.where);
+        if (where)
+            clauses.push(`WHERE ${where}`);
+    }
+    // ORDER BY
+    if (args.orderBy) {
+        const list = Array.isArray(args.orderBy)
+            ? args.orderBy
+            : [args.orderBy];
+        const orders = [];
+        for (const entry of list) {
+            for (const key in entry) {
+                const dir = entry[key];
+                if (dir === undefined)
+                    continue;
+                if (dir !== "asc" && dir !== "desc") {
+                    throw new Error(`Invalid sort direction "${dir}" for column "${key}"`);
+                }
+                orders.push(`${ctx.colRef(key)} ${dir.toUpperCase()}`);
+            }
+        }
+        if (orders.length)
+            clauses.push(`ORDER BY ${orders.join(", ")}`);
+    }
+    // LIMIT / OFFSET
+    if (args.take !== undefined)
+        checkPagination("take", args.take);
+    if (args.skip !== undefined)
+        checkPagination("skip", args.skip);
+    if (args.take !== undefined && args.skip !== undefined) {
+        clauses.push(`LIMIT ${args.take} OFFSET ${args.skip}`);
+    }
+    else if (args.take !== undefined) {
+        clauses.push(`LIMIT ${args.take}`);
+    }
+    else if (args.skip !== undefined) {
+        clauses.push(`LIMIT ${NO_LIMIT} OFFSET ${args.skip}`);
+    }
+    return { sql: clauses.join(" "), params: ctx.params };
+}
+export function buildCountQuery(database, tableName, table, where) {
+    const inner = buildFindManyQuery(database, tableName, table, { where });
+    // with no select arg the query starts with "SELECT * FROM ..." —
+    // swap the projection for count()
+    const from = inner.sql.indexOf(" FROM ");
+    return {
+        sql: "SELECT count() AS count" + inner.sql.slice(from),
+        params: inner.params
+    };
+}
+// shared by buildUpdateQuery and the replacing-strategy update path
+export function validateUpdateData(table, tableName, data) {
+    const keys = Object.keys(data).filter(k => data[k] !== undefined);
+    if (keys.length === 0) {
+        throw new Error(`updateMany requires non-empty data`);
+    }
+    for (const key of keys) {
+        if (table.orderBy.includes(key)) {
+            throw new Error(`Cannot update ORDER BY key column "${key}" ` +
+                `of table "${tableName}"`);
+        }
+    }
+    return keys;
+}
+export function buildUpdateQuery(database, tableName, table, where, data) {
+    const keys = validateUpdateData(table, tableName, data);
+    const ctx = createBuildContext(tableName, table.columns);
+    const sets = keys.map(k => `${ctx.colRef(k)} = ${ctx.addParam(data[k], ctx.baseType(k))}`);
+    const whereSQL = where ? ctx.whereSQL(where) : "";
+    return {
+        sql: `ALTER TABLE ${escapeId(database)}.${escapeId(tableName)} ` +
+            `UPDATE ${sets.join(", ")} WHERE ${whereSQL || "1"}`,
+        params: ctx.params
+    };
+}
+export function buildDeleteQuery(database, tableName, table, where) {
+    const ctx = createBuildContext(tableName, table.columns);
+    const whereSQL = where ? ctx.whereSQL(where) : "";
+    return {
+        sql: `ALTER TABLE ${escapeId(database)}.${escapeId(tableName)} ` +
+            `DELETE WHERE ${whereSQL || "1"}`,
+        params: ctx.params
+    };
+}
+export function buildLightweightDeleteQuery(database, tableName, table, where) {
+    const ctx = createBuildContext(tableName, table.columns);
+    const whereSQL = where ? ctx.whereSQL(where) : "";
+    return {
+        sql: `DELETE FROM ${escapeId(database)}.${escapeId(tableName)} ` +
+            `WHERE ${whereSQL || "1"}`,
+        params: ctx.params
+    };
+}

package/dist/table-client.d.ts

@@ -0,0 +1,55 @@
+import type { ClickHouseClient } from "@clickhouse/client";
+import { TableDefinition } from "./table.js";
+import { Simplify } from "./types.js";
+import { WhereInput } from "./where.js";
+import { FindManyArgs } from "./sql.js";
+export type FindManyResult<T, A> = A extends {
+    select: infer S;
+} ? Simplify<{
+    [K in keyof S & keyof T as S[K] extends true ? K : never]: T[K];
+}> : T;
+type NullableKeys<T> = {
+    [K in keyof T]-?: null extends T[K] ? K : never;
+}[keyof T];
+type OptionalCreateKeys<T> = NullableKeys<T> | ("id" & keyof T);
+export type CreateData<T> = Simplify<Omit<T, OptionalCreateKeys<T>> & {
+    [K in OptionalCreateKeys<T>]?: T[K];
+}>;
+export declare class TableClient<T> {
+    private database;
+    private tableName;
+    private table;
+    private client;
+    constructor(database: string, tableName: string, table: TableDefinition<any>, client: ClickHouseClient);
+    private get tableRef();
+    private runQuery;
+    findMany<A extends FindManyArgs<T>>(args?: A): Promise<FindManyResult<T, A>[]>;
+    findFirst<A extends Omit<FindManyArgs<T>, "take">>(args?: A): Promise<FindManyResult<T, A> | null>;
+    count(args?: {
+        where?: WhereInput<T>;
+    }): Promise<number>;
+    private prepareRows;
+    private insertWire;
+    insert(rows: Partial<T> | Partial<T>[]): Promise<void>;
+    create(args: {
+        data: CreateData<T>;
+    }): Promise<T>;
+    private get strategy();
+    updateMany(args: {
+        where?: WhereInput<T>;
+        data: Partial<T>;
+    }): Promise<{
+        count: number;
+    }>;
+    deleteMany(args?: {
+        where?: WhereInput<T>;
+    }): Promise<{
+        count: number;
+    }>;
+    createMany(args: {
+        data: CreateData<T>[];
+    }): Promise<{
+        count: number;
+    }>;
+}
+export {};

package/dist/table-client.js

@@ -0,0 +1,186 @@
+// src/table-client.ts
+import { buildFindManyQuery, buildCountQuery, buildUpdateQuery, buildDeleteQuery, buildLightweightDeleteQuery, validateUpdateData, escapeId } from "./sql.js";
+import { deserializeRows } from "./rows.js";
+// process-unique id: ms timestamp in the high bits + 20-bit counter
+let idCounter = 0n;
+function generateId() {
+    return (BigInt(Date.now()) << 20n) | (idCounter++ & 0xfffffn);
+}
+export class TableClient {
+    database;
+    tableName;
+    table;
+    client;
+    constructor(database, tableName, table, client) {
+        this.database = database;
+        this.tableName = tableName;
+        this.table = table;
+        this.client = client;
+    }
+    get tableRef() {
+        return `${escapeId(this.database)}.${escapeId(this.tableName)}`;
+    }
+    async runQuery(sql, params) {
+        const result = await this.client.query({
+            query: sql,
+            query_params: params,
+            format: "JSONEachRow",
+            clickhouse_settings: {
+                // ISO with Z: the default DateTime rendering is in server
+                // timezone with no offset, which is unparseable correctly
+                date_time_output_format: "iso",
+                // force 64-bit ints to arrive as strings so BigInt() is
+                // lossless even if the server default was changed
+                output_format_json_quote_64bit_integers: 1
+            }
+        });
+        return result.json();
+    }
+    async findMany(args) {
+        const { sql, params } = buildFindManyQuery(this.database, this.tableName, this.table, args);
+        const rows = await this.runQuery(sql, params);
+        return deserializeRows(rows, this.table.columns);
+    }
+    async findFirst(args) {
+        const rows = await this.findMany({ ...args, take: 1 });
+        return rows[0] ?? null;
+    }
+    async count(args) {
+        const { sql, params } = buildCountQuery(this.database, this.tableName, this.table, args?.where);
+        const rows = await this.runQuery(sql, params);
+        return Number(rows[0].count);
+    }
+    // wire: values serialized for JSONEachRow; completed: JS values
+    // including the generated id (what create() returns)
+    prepareRows(arr) {
+        const hasIdColumn = "id" in this.table.columns;
+        const wire = [];
+        const completed = [];
+        for (const r of arr) {
+            const full = { ...r };
+            if (hasIdColumn && full.id === undefined) {
+                full.id = generateId();
+            }
+            // the returned row must match both its type and what a
+            // subsequent read returns: omitted nullable columns are null,
+            // DateTime values are stored with second precision
+            for (const colName in this.table.columns) {
+                if (full[colName] === undefined && this.table.columns[colName].nullable) {
+                    full[colName] = null;
+                }
+                else if (full[colName] instanceof Date) {
+                    full[colName] = new Date(Math.floor(full[colName].getTime() / 1000) * 1000);
+                }
+            }
+            const obj = {};
+            for (const k in full) {
+                const v = full[k];
+                if (v === undefined)
+                    continue;
+                if (typeof v === "bigint") {
+                    obj[k] = v.toString();
+                }
+                else if (v instanceof Date) {
+                    // unix seconds: ISO strings are rejected by DateTime
+                    // columns in the default (basic) input format
+                    obj[k] = Math.floor(v.getTime() / 1000);
+                }
+                else {
+                    obj[k] = v;
+                }
+            }
+            wire.push(obj);
+            completed.push(full);
+        }
+        return { wire, completed };
+    }
+    async insertWire(wire) {
+        await this.client.insert({
+            table: this.tableRef,
+            values: wire,
+            format: "JSONEachRow",
+            clickhouse_settings: {
+                // with wait_for_async_insert=0 on the server, inserts are
+                // acked before flush: errors are swallowed and rows are not
+                // immediately readable — force read-your-writes semantics
+                wait_for_async_insert: 1
+            }
+        });
+    }
+    async insert(rows) {
+        const arr = Array.isArray(rows) ? rows : [rows];
+        if (arr.length === 0)
+            return;
+        const { wire } = this.prepareRows(arr);
+        await this.insertWire(wire);
+    }
+    async create(args) {
+        const { wire, completed } = this.prepareRows([args.data]);
+        await this.insertWire(wire);
+        return completed[0];
+    }
+    get strategy() {
+        return this.table.mutations ?? "alter";
+    }
+    async updateMany(args) {
+        if (this.strategy === "replacing") {
+            const keys = validateUpdateData(this.table, this.tableName, args.data);
+            // re-insert new versions of the matching rows;
+            // FINAL on the read keeps this idempotent
+            const rows = await this.findMany({ where: args.where });
+            if (rows.length === 0)
+                return { count: 0 };
+            const patch = {};
+            for (const k of keys)
+                patch[k] = args.data[k];
+            const { wire } = this.prepareRows(rows.map(r => ({ ...r, ...patch })));
+            await this.insertWire(wire);
+            return { count: rows.length };
+        }
+        // "alter" and "lightweight" (ClickHouse has no stable lightweight
+        // UPDATE — lightweight tables fall back to a heavy ALTER mutation)
+        const { sql, params } = buildUpdateQuery(this.database, this.tableName, this.table, args.where, args.data);
+        const count = await this.count({ where: args.where });
+        if (count === 0)
+            return { count: 0 };
+        await this.client.command({
+            query: sql,
+            query_params: params,
+            clickhouse_settings: {
+                // wait for the mutation so subsequent reads see the change
+                mutations_sync: "1"
+            }
+        });
+        return { count };
+    }
+    async deleteMany(args) {
+        const count = await this.count({ where: args?.where });
+        if (count === 0)
+            return { count: 0 };
+        if (this.strategy === "alter") {
+            const { sql, params } = buildDeleteQuery(this.database, this.tableName, this.table, args?.where);
+            await this.client.command({
+                query: sql,
+                query_params: params,
+                clickhouse_settings: { mutations_sync: "1" }
+            });
+        }
+        else {
+            // "lightweight" and "replacing": fast tombstone-based delete
+            const { sql, params } = buildLightweightDeleteQuery(this.database, this.tableName, this.table, args?.where);
+            await this.client.command({
+                query: sql,
+                query_params: params,
+                clickhouse_settings: { lightweight_deletes_sync: "2" }
+            });
+        }
+        return { count };
+    }
+    async createMany(args) {
+        if (args.data.length === 0)
+            return { count: 0 };
+        const { wire } = this.prepareRows(args.data);
+        await this.insertWire(wire);
+        return { count: args.data.length };
+    }
+}

package/dist/table.d.ts

@@ -0,0 +1,13 @@
+import { Column } from "./column.js";
+import { Simplify } from "./types.js";
+export type MutationStrategy = "alter" | "lightweight" | "replacing";
+export type TableDefinition<TColumns extends Record<string, Column<any>>> = {
+    engine: string;
+    orderBy: string[];
+    mutations?: MutationStrategy;
+    columns: TColumns;
+};
+export declare function table<TColumns extends Record<string, Column<any>>>(def: TableDefinition<TColumns>): TableDefinition<TColumns>;
+export type InferRow<TTable> = TTable extends TableDefinition<infer TColumns> ? Simplify<{
+    [K in keyof TColumns]: TColumns[K] extends Column<infer T> ? T : never;
+}> : never;

package/dist/table.js

@@ -0,0 +1,9 @@
+// src/table.ts
+export function table(def) {
+    if (def.mutations === "replacing" &&
+        !def.engine.includes("ReplacingMergeTree")) {
+        throw new Error(`mutations: "replacing" requires a ReplacingMergeTree engine ` +
+            `(got "${def.engine}")`);
+    }
+    return def;
+}

package/dist/types.d.ts

@@ -0,0 +1,4 @@
+export type Primitive = string | number | bigint | boolean | Date | null;
+export type Simplify<T> = {
+    [K in keyof T]: T[K];
+} & {};

package/dist/types.js

@@ -0,0 +1,2 @@
+// src/types.ts
+export {};

package/dist/where.d.ts

@@ -0,0 +1,24 @@
+export type ComparableFilter<T> = {
+    lt?: T;
+    lte?: T;
+    gt?: T;
+    gte?: T;
+};
+export type StringFilter = {
+    contains?: string;
+    startsWith?: string;
+    endsWith?: string;
+};
+export type ScalarFilter<T> = {
+    equals?: T | null;
+    not?: T | null;
+    in?: T[];
+    notIn?: T[];
+} & (T extends number | bigint | Date | string ? ComparableFilter<T> : {}) & (T extends string ? StringFilter : {});
+export type WhereInput<T> = {
+    AND?: WhereInput<T> | WhereInput<T>[];
+    OR?: WhereInput<T>[];
+    NOT?: WhereInput<T> | WhereInput<T>[];
+} & {
+    [K in keyof T]?: T[K] extends readonly any[] ? never : T[K] | ScalarFilter<NonNullable<T[K]>> | null;
+};

package/dist/where.js

@@ -0,0 +1,2 @@
+// src/where.ts
+export {};

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@quark-fw/clisma",
+  "version": "0.1.0",
+  "description": "Prisma-like typed client and schema migrator for ClickHouse",
+  "keywords": [
+    "clickhouse",
+    "orm",
+    "prisma",
+    "query-builder",
+    "migrations",
+    "typescript"
+  ],
+  "license": "MIT",
+  "author": "Drus",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "tsx --env-file=./src/test/.env ./src/test/index.ts",
+    "test:unit": "tsx --test src/test/unit.test.ts",
+    "prepublishOnly": "npm run typecheck && npm run test:unit && npm run build"
+  },
+  "dependencies": {
+    "@clickhouse/client": "^1.17.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.3.3",
+    "tsx": "^4.21.0",
+    "typescript": "^5.5.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}