@quark-fw/clisma 0.1.26 → 0.1.27

package/dist/src/sql-shared.js

@@ -0,0 +1,171 @@
+// src/sql-shared.ts
+// Shared helpers and types for the SQL builders (build-*.ts).
+import { escapeId } from "./escape-id.js";
+import { collapsingOf, keyColumns } from "./ddl-shared.js";
+// escapeId живёт отдельным файлом: он нужен и рендеру DDL, и билдерам
+// запросов, а взаимный импорт между ними создал бы цикл модулей
+export { escapeId } from "./escape-id.js";
+// UInt64 max — used to emulate a bare OFFSET (skip without take)
+export 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;
+}
+export 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 };
+}
+export function tableRef(database, tableName, table, final = false) {
+    const ref = `${escapeId(database)}.${escapeId(tableName)}`;
+    // replacing-таблицы обязаны читать последние версии строк; для остальных
+    // FINAL включается явно (например, чтобы прочитать коллапсирующую таблицу)
+    return table.mutations === "replacing" || final ? `${ref} FINAL` : ref;
+}
+// у коллапсирующих таблиц строка «существует», только если её знак не
+// погашен парой -1 — count() посчитал бы обе строки пары
+export function countExpr(table) {
+    const collapsing = collapsingOf(table.engine);
+    return collapsing ? `sum(${escapeId(collapsing.sign)})` : "count()";
+}
+export function checkPagination(name, value) {
+    if (!Number.isInteger(value) || value < 0) {
+        throw new Error(`"${name}" must be a non-negative integer, got: ${value}`);
+    }
+}
+// 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 (keyColumns(table.orderBy).includes(key)) {
+            throw new Error(`Cannot update ORDER BY key column "${key}" ` +
+                `of table "${tableName}"`);
+        }
+    }
+    return keys;
+}

package/dist/src/sql.d.ts

@@ -0,0 +1,6 @@
+export { escapeId, validateUpdateData, type FindManyArgs, type OrderByInput, type SQLBuildResult, } from "./sql-shared.js";
+export { buildFindManyQuery } from "./build-find-many-query.js";
+export { buildCountQuery } from "./build-count-query.js";
+export { buildUpdateQuery } from "./build-update-query.js";
+export { buildDeleteQuery } from "./build-delete-query.js";
+export { buildLightweightDeleteQuery } from "./build-lightweight-delete-query.js";

package/dist/src/sql.js

@@ -0,0 +1,9 @@
+// src/sql.ts
+// Public surface of the SQL builders; implementation is split by function
+// (one function per file), shared helpers live in sql-shared.ts.
+export { escapeId, validateUpdateData, } from "./sql-shared.js";
+export { buildFindManyQuery } from "./build-find-many-query.js";
+export { buildCountQuery } from "./build-count-query.js";
+export { buildUpdateQuery } from "./build-update-query.js";
+export { buildDeleteQuery } from "./build-delete-query.js";
+export { buildLightweightDeleteQuery } from "./build-lightweight-delete-query.js";

package/dist/src/table-client.d.ts

@@ -0,0 +1,55 @@
+import type { ClickHouseClient } from "@clickhouse/client";
+import { AnyTable } 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 extends Record<string, unknown>> {
+    private database;
+    private tableName;
+    private table;
+    private client;
+    constructor(database: string, tableName: string, table: AnyTable, 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/src/table-client.js

@@ -0,0 +1,198 @@
+// src/table-client.ts
+import { buildFindManyQuery, buildCountQuery, buildUpdateQuery, buildDeleteQuery, buildLightweightDeleteQuery, validateUpdateData, escapeId, } from "./sql.js";
+import { deserializeRows } from "./rows.js";
+import { collapsingOf } from "./ddl-shared.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, settings = {}) {
+        const result = await this.client.query({
+            query: sql,
+            query_params: params,
+            format: "JSONEachRow",
+            clickhouse_settings: {
+                ...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) {
+        // сырые строки коллапсирующей таблицы содержат и погашенные версии —
+        // без FINAL такой результат вводит в заблуждение
+        if (collapsingOf(this.table.engine) && !args?.final) {
+            throw new Error(`Table "${this.tableName}" uses a collapsing engine: pass final: true to findMany`);
+        }
+        const { sql, params } = buildFindManyQuery(this.database, this.tableName, this.table, args);
+        const rows = await this.runQuery(sql, params, args?.settings);
+        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/src/table.d.ts

@@ -0,0 +1,37 @@
+import { Column } from "./column.js";
+import type { EngineSpec } from "./engine.js";
+import type { KeyPart } from "./expr.js";
+import { Simplify } from "./types.js";
+export type MutationStrategy = "alter" | "lightweight" | "replacing";
+export type IndexType = "bloom_filter" | "set" | "minmax" | "tokenbf_v1" | "ngrambf_v1";
+export type IndexDefinition = {
+    name: string;
+    expr: KeyPart;
+    type: IndexType;
+    args?: (number | string)[];
+    granularity?: number;
+};
+export type TableDefinition<TColumns extends Record<string, Column<unknown>>> = {
+    engine: string | EngineSpec;
+    replication?: {
+        path: string;
+        replica: string;
+    };
+    orderBy: KeyPart[];
+    primaryKey?: KeyPart[];
+    partitionBy?: KeyPart;
+    sampleBy?: KeyPart;
+    indexes?: IndexDefinition[];
+    ttl?: string;
+    settings?: Record<string, string | number>;
+    comment?: string;
+    mutations?: MutationStrategy;
+    columns: TColumns;
+};
+export type AnyColumns = Record<string, Column<unknown>>;
+export type AnyTable = TableDefinition<AnyColumns>;
+export declare function table<TColumns extends Record<string, Column<unknown>>>(def: TableDefinition<TColumns>): TableDefinition<TColumns>;
+export type InferColumns<TColumns extends Record<string, Column<unknown>>> = Simplify<{
+    [K in keyof TColumns]: TColumns[K] extends Column<infer T> ? T : never;
+}>;
+export type InferRow<TTable> = TTable extends TableDefinition<infer TColumns> ? InferColumns<TColumns> : never;

package/dist/src/table.js

@@ -0,0 +1,30 @@
+// src/table.ts
+import { collapsingOf, isReplacingEngine, keyColumns } from "./ddl-shared.js";
+const INTEGER_TYPE = /^(U?Int(8|16|32|64))$/;
+export function table(def) {
+    if (def.mutations === "replacing" && !isReplacingEngine(def.engine)) {
+        throw new Error(`mutations: "replacing" requires a ReplacingMergeTree engine ` +
+            `(got "${typeof def.engine === "string" ? def.engine : def.engine.family}")`);
+    }
+    // коллапс работает только с целочисленным знаком и версией — ошибка
+    // схемы должна всплыть при объявлении, а не при первом INSERT
+    const collapsing = collapsingOf(def.engine);
+    if (collapsing) {
+        const sign = def.columns[collapsing.sign];
+        if (!sign || sign.clickhouseType !== "Int8") {
+            throw new Error(`Collapsing engine requires sign column "${collapsing.sign}" of type Int8`);
+        }
+        if (collapsing.version) {
+            const version = def.columns[collapsing.version];
+            if (!version || !INTEGER_TYPE.test(version.clickhouseType)) {
+                throw new Error(`VersionedCollapsingMergeTree requires integer version column "${collapsing.version}"`);
+            }
+        }
+    }
+    for (const key of keyColumns([...def.orderBy, ...(def.primaryKey ?? [])])) {
+        if (!def.columns[key]) {
+            throw new Error(`Key column "${key}" is not declared in columns`);
+        }
+    }
+    return def;
+}

package/dist/src/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/src/types.js

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

package/dist/src/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> : unknown) & (T extends string ? StringFilter : unknown);
+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 unknown[] ? never : T[K] | ScalarFilter<NonNullable<T[K]>> | null;
+};

package/dist/src/where.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@quark-fw/clisma",
-	"version": "0.1.26",
+	"version": "0.1.27",
 	"description": "Prisma-like typed client and schema migrator for ClickHouse",
 	"keywords": [
 		"clickhouse",
@@ -29,8 +29,8 @@
 		"node": ">=20"
 	},
 	"scripts": {
-		"build": "tsc -p tsconfig.build.json",
-		"typecheck": "tsc --noEmit",
+		"build": "node ../../node_modules/tsgo/bin/tsc -p tsconfig.build.json",
+		"typecheck": "node ../../node_modules/tsgo/bin/tsc --noEmit",
 		"test:integration": "tsx --env-file=./src/test/.env ./src/test/index.ts",
 		"test": "tsx --test src/test/unit.test.ts src/test/ddl.test.ts src/test/migrate-nodes.test.ts",
 		"prepublishOnly": "npm run typecheck && npm test && npm run build"