@housekit/orm 0.1.47 → 0.1.48

package/dist/schema-builder.js

@@ -0,0 +1,140 @@
+import { ClickHouseColumn } from './column';
+import { chTable, chView, index, projection } from './table';
+import { chMaterializedView, detectMaterializedViewDrift, extractMVQuery, createMigrationBridge, generateBlueGreenMigration } from './materialized-views';
+export { detectMaterializedViewDrift, extractMVQuery, createMigrationBridge, generateBlueGreenMigration };
+import { chDictionary } from './dictionary';
+import { chProjection } from './materialized-views';
+export { index };
+function primaryUuid(name) {
+    const colName = (name ?? 'id');
+    const column = new ClickHouseColumn(colName, 'UUID')
+        .autoGenerate()
+        .primaryKey();
+    return {
+        [colName]: column
+    };
+}
+function primaryUuidV7(name) {
+    const colName = (name ?? 'id');
+    const column = new ClickHouseColumn(colName, 'UUID')
+        .autoGenerate({ version: 7 })
+        .primaryKey();
+    return {
+        [colName]: column
+    };
+}
+export const t = {
+    int8: (name) => new ClickHouseColumn(name, 'Int8'),
+    int16: (name) => new ClickHouseColumn(name, 'Int16'),
+    integer: (name) => new ClickHouseColumn(name, 'Int32'),
+    int32: (name) => new ClickHouseColumn(name, 'Int32'),
+    int64: (name) => new ClickHouseColumn(name, 'Int64'),
+    int128: (name) => new ClickHouseColumn(name, 'Int128'),
+    int256: (name) => new ClickHouseColumn(name, 'Int256'),
+    uint8: (name) => new ClickHouseColumn(name, 'UInt8'),
+    uint16: (name) => new ClickHouseColumn(name, 'UInt16'),
+    uint32: (name) => new ClickHouseColumn(name, 'UInt32'),
+    uint64: (name) => new ClickHouseColumn(name, 'UInt64'),
+    uint128: (name) => new ClickHouseColumn(name, 'UInt128'),
+    uint256: (name) => new ClickHouseColumn(name, 'UInt256'),
+    float32: (name) => new ClickHouseColumn(name, 'Float32'),
+    float: (name) => new ClickHouseColumn(name, 'Float64'),
+    float64: (name) => new ClickHouseColumn(name, 'Float64'),
+    bfloat16: (name) => new ClickHouseColumn(name, 'BFloat16'),
+    decimal: (name, precision = 18, scale = 4) => new ClickHouseColumn(name, `Decimal(${precision}, ${scale})`),
+    decimal32: (name, scale = 4) => new ClickHouseColumn(name, `Decimal32(${scale})`),
+    decimal64: (name, scale = 4) => new ClickHouseColumn(name, `Decimal64(${scale})`),
+    decimal128: (name, scale = 4) => new ClickHouseColumn(name, `Decimal128(${scale})`),
+    decimal256: (name, scale = 4) => new ClickHouseColumn(name, `Decimal256(${scale})`),
+    text: (name) => new ClickHouseColumn(name, 'String'),
+    string: (name) => new ClickHouseColumn(name, 'String'),
+    fixedString: (name, length) => new ClickHouseColumn(name, `FixedString(${length})`),
+    varchar: (name, opts) => opts?.length
+        ? new ClickHouseColumn(name, `FixedString(${opts.length})`)
+        : new ClickHouseColumn(name, 'String'),
+    date: (name) => new ClickHouseColumn(name, 'Date'),
+    date32: (name) => new ClickHouseColumn(name, 'Date32'),
+    timestamp: (name, timezone) => new ClickHouseColumn(name, timezone ? `DateTime('${timezone}')` : 'DateTime'),
+    datetime: (name, timezone) => new ClickHouseColumn(name, timezone ? `DateTime('${timezone}')` : 'DateTime'),
+    datetime64: (name, precision = 3, timezone) => new ClickHouseColumn(name, timezone ? `DateTime64(${precision}, '${timezone}')` : `DateTime64(${precision})`),
+    boolean: (name) => new ClickHouseColumn(name, 'Bool'),
+    bool: (name) => new ClickHouseColumn(name, 'Bool'),
+    uuid: (name) => new ClickHouseColumn(name, 'UUID'),
+    ipv4: (name) => new ClickHouseColumn(name, 'IPv4'),
+    ipv6: (name) => new ClickHouseColumn(name, 'IPv6'),
+    array: (col) => {
+        const isInnerComposite = col.type.startsWith('Array(') || col.type.startsWith('Map(') || col.type.startsWith('Tuple(');
+        const innerType = (col.isNull && !isInnerComposite) ? `Nullable(${col.type})` : col.type;
+        return new ClickHouseColumn(col.name, `Array(${innerType})`);
+    },
+    tuple: (name, types) => {
+        if (!Array.isArray(types)) {
+            throw new Error(`tuple() expects an array of types, but received: ${typeof types}`);
+        }
+        return new ClickHouseColumn(name, `Tuple(${types.join(', ')})`);
+    },
+    map: (name, keyType = 'String', valueType = 'String') => new ClickHouseColumn(name, `Map(${keyType}, ${valueType})`),
+    nested: (name, fields) => {
+        const fieldDefs = Object.entries(fields).map(([k, v]) => `${k} ${v}`).join(', ');
+        return new ClickHouseColumn(name, `Nested(${fieldDefs})`);
+    },
+    json: (name) => new ClickHouseColumn(name, 'JSON', true, { isJson: true }),
+    dynamic: (name, maxTypes) => new ClickHouseColumn(name, maxTypes ? `Dynamic(max_types=${maxTypes})` : 'Dynamic'),
+    lowCardinality: (col) => col.clone({ type: `LowCardinality(${col.type})` }),
+    aggregateFunction: (name, funcName, ...argTypes) => new ClickHouseColumn(name, `AggregateFunction(${funcName}${argTypes.length > 0 ? ', ' + argTypes.join(', ') : ''})`),
+    simpleAggregateFunction: (name, funcName, argType) => new ClickHouseColumn(name, `SimpleAggregateFunction(${funcName}, ${argType})`),
+    point: (name) => new ClickHouseColumn(name, 'Point'),
+    ring: (name) => new ClickHouseColumn(name, 'Ring'),
+    polygon: (name) => new ClickHouseColumn(name, 'Polygon'),
+    multiPolygon: (name) => new ClickHouseColumn(name, 'MultiPolygon'),
+    enum: (name, values) => new ClickHouseColumn(name, 'String', true, { enumValues: values }),
+    timestamps: () => ({
+        created_at: new ClickHouseColumn('created_at', 'DateTime').default('now()'),
+        updated_at: new ClickHouseColumn('updated_at', 'DateTime').default('now()'),
+    }),
+    primaryUuid,
+    primaryUuidV7,
+    softDeletes: () => ({
+        is_deleted: new ClickHouseColumn('is_deleted', 'Bool').default(false),
+        deleted_at: new ClickHouseColumn('deleted_at', 'DateTime').nullable(),
+    }),
+};
+export function defineTable(tableName, columnsOrCallback, options) {
+    const columns = typeof columnsOrCallback === 'function'
+        ? columnsOrCallback(t)
+        : columnsOrCallback;
+    return chTable(tableName, columns, options);
+}
+export const table = defineTable;
+export const view = chView;
+export const defineView = chView;
+export const defineMaterializedView = chMaterializedView;
+export const materializedView = chMaterializedView;
+export const dictionary = chDictionary;
+export const defineDictionary = chDictionary;
+export { projection };
+export { chProjection as defineProjection };
+export function relations(table, relationsBuilder) {
+    const helpers = {
+        one: (targetTable, config) => ({
+            relation: 'one',
+            name: '',
+            table: targetTable,
+            fields: config.fields,
+            references: config.references,
+        }),
+        many: (targetTable, config) => ({
+            relation: 'many',
+            name: '',
+            table: targetTable,
+            fields: config?.fields,
+            references: config?.references,
+        }),
+    };
+    const rels = relationsBuilder(helpers);
+    for (const [name, rel] of Object.entries(rels)) {
+        rel.name = name;
+    }
+    table.$relations = rels;
+    return rels;
+}

package/dist/table.d.ts

@@ -3,13 +3,6 @@ import { TTLRule } from './data-types';
 import { EngineConfiguration } from './engines';
 import { type MetadataVersion } from './metadata';
 export interface TableOptions {
-    /**
-     * ClickHouse table engine configuration.
-     *
-     * // Raw string (escape hatch)
-     * customEngine: 'MergeTree()'
-     * ```
-     */
     engine?: EngineConfiguration;
     customEngine?: string;
     orderBy?: string | string[];
@@ -67,9 +60,6 @@ export type RelationDefinition<TTarget extends TableDefinition<any> = TableDefin
     references?: ClickHouseColumn[];
 };
 export type TableColumns = Record<string, ClickHouseColumn<any, any, any>>;
-/**
- * Utility to force TypeScript to expand computed types for cleaner tooltips.
- */
 export type Prettify<T> = {
     [K in keyof T]: T[K];
 } & {};
@@ -90,20 +80,6 @@ export type InferSelectModel<T extends {
 export type InferInsertModel<T extends {
     $columns: TableColumns;
 }> = Prettify<TableInsert<T['$columns']>>;
-type InferInsertFromColumns<T> = T extends {
-    $columns: infer TCols extends TableColumns;
-} ? TableInsert<TCols> : never;
-type InferSelectFromColumns<T> = T extends {
-    $columns: infer TCols extends TableColumns;
-} ? InferSelectModel<{
-    $columns: TCols;
-}> : never;
-export type CleanInsert<T> = T extends {
-    $inferInsert: infer I;
-} ? I : InferInsertFromColumns<T>;
-export type CleanSelect<T> = T extends {
-    $inferSelect: infer S;
-} ? S : InferSelectFromColumns<T>;
 export type InferInsertValue<TCols extends TableColumns, K extends keyof TCols> = TCols[K] extends ClickHouseColumn<infer Type, infer NotNull, any> ? NotNull extends true ? Type : Type | undefined | null : never;
 export type TableInsertArray<T extends TableDefinition<TableColumns>> = T['$inferInsert'][];
 export type TableModel<T extends TableDefinition<TableColumns>> = PublicSelectModel<T>;
@@ -179,17 +155,8 @@ export declare function chView<T extends Record<string, ClickHouseColumn<any, an
 }> & {
     toSQLs: () => string[];
 };
-/**
- * Define a reusable set of columns with type inference.
- */
 export declare function defineColumns<T extends TableColumns>(cols: T): T;
-/**
- * Compose column sets, throwing on duplicate keys to avoid accidental overrides.
- */
 export declare function extendColumns<Base extends TableColumns, Extra extends TableColumns>(base: Base, extra: Extra): Base & Extra;
-/**
- * Define a versioned table (e.g., base_v2) with optional view alias to point to the latest version.
- */
 export declare function versionedTable<T extends TableColumns>(baseName: string, version: string | number, columns: T, options?: TableOptions & {
     latestAlias?: boolean;
     aliasName?: string;
@@ -197,9 +164,6 @@ export declare function versionedTable<T extends TableColumns>(baseName: string,
     $versionMeta: VersionedMeta;
     toSQLs: () => string[];
 };
-/**
- * Define a derived (aggregated) table with a backing table and materialized view.
- */
 export declare function deriveTable<T extends TableColumns>(source: TableDefinition<T>, config: {
     name: string;
     groupBy: string | string[];
@@ -208,12 +172,6 @@ export declare function deriveTable<T extends TableColumns>(source: TableDefinit
 }): TableDefinition<any> & {
     toSQLs: () => string[];
 };
-/**
- * Render CREATE statements for preview.
- */
 export declare function renderSchema(def: TableDefinition<any>): any;
-/**
- * Generate a TypeScript type from a table definition (best effort mapping).
- */
 export declare function generateTypes<T extends TableColumns>(def: TableDefinition<T>, typeName?: string): string;
 export {};

package/dist/table.js

@@ -0,0 +1,406 @@
+import { ClickHouseColumn } from './column';
+import { renderEngineSQL, isMergeTreeFamily, getVersionColumn, Engine } from './engines';
+import { assertMetadataVersion, buildHousekitMetadata, defaultMetadataVersion, getMetadataDefaults } from './metadata';
+export const index = (name) => ({
+    on: (...cols) => ({
+        type: (type, granularity) => ({
+            name,
+            cols,
+            type,
+            granularity
+        })
+    })
+});
+export const projection = (name, query) => ({
+    name,
+    query
+});
+function attachTableName(tableName, columns) {
+    for (const col of Object.values(columns)) {
+        col.tableName = tableName;
+    }
+}
+function assignColumnsToTable(target, columns, tableName) {
+    for (const [key, col] of Object.entries(columns)) {
+        const column = col;
+        column.tableName = tableName;
+        target[key] = column;
+    }
+    return target;
+}
+export function chTable(tableName, columns, options = {}) {
+    attachTableName(tableName, columns);
+    let resolvedMetadataVersion;
+    if (options.metadataVersion) {
+        const versionStr = String(options.metadataVersion);
+        assertMetadataVersion(versionStr);
+        resolvedMetadataVersion = versionStr;
+    }
+    else {
+        resolvedMetadataVersion = defaultMetadataVersion;
+    }
+    const defaults = getMetadataDefaults(resolvedMetadataVersion);
+    const finalOptions = {
+        appendOnly: options.appendOnly ?? defaults.appendOnly,
+        metadataVersion: resolvedMetadataVersion,
+        readOnly: options.readOnly ?? (defaults.readOnly ?? false),
+        deduplicateBy: options.deduplicateBy,
+        customEngine: options.customEngine,
+        engine: options.engine,
+        orderBy: options.orderBy,
+        partitionBy: options.partitionBy,
+        primaryKey: options.primaryKey,
+        sampleBy: options.sampleBy,
+        logicalPrimaryKey: options.logicalPrimaryKey,
+        ttl: options.ttl,
+        versionColumn: options.versionColumn,
+        externallyManaged: options.externallyManaged,
+        onCluster: options.onCluster,
+        shardKey: options.shardKey,
+        materializedView: options.materializedView,
+        indices: options.indices,
+        projections: options.projections,
+        asyncInsert: options.asyncInsert
+    };
+    if (finalOptions.onCluster && !finalOptions.engine) {
+        finalOptions.engine = Engine.ReplicatedMergeTree();
+    }
+    const engineConfig = finalOptions.engine;
+    const engineStr = renderEngineSQL(engineConfig);
+    const isMergeTreeFamilyEngine = isMergeTreeFamily(engineConfig);
+    if (finalOptions.defaultFinal === undefined && /ReplacingMergeTree/i.test(engineStr)) {
+        finalOptions.defaultFinal = true;
+    }
+    if (!finalOptions.versionColumn) {
+        const extractedVersion = getVersionColumn(engineConfig);
+        if (extractedVersion) {
+            finalOptions.versionColumn = extractedVersion;
+        }
+    }
+    const onClusterClause = finalOptions.onCluster ? `ON CLUSTER ${finalOptions.onCluster}` : '';
+    const normalizeList = (val) => {
+        if (!val)
+            return [];
+        if (Array.isArray(val))
+            return val.map(v => v.toString().trim()).filter(Boolean);
+        return val.split(',').map(v => v.trim()).filter(Boolean);
+    };
+    const ensureColumnsExist = (label, raw) => {
+        const identifiers = normalizeList(raw).filter(v => /^[a-zA-Z_][a-zA-Z0-9_]*$/.test(v));
+        const validColumnNames = new Set(Object.values(columns).map(c => c.name));
+        for (const id of identifiers) {
+            const exists = columns[id] || validColumnNames.has(id);
+            if (!exists) {
+                if (id.includes('('))
+                    continue;
+                throw new Error(`Column "${id}" referenced in ${label} does not exist in table ${tableName}`);
+            }
+        }
+    };
+    if (isMergeTreeFamilyEngine) {
+        if (!finalOptions.orderBy || normalizeList(finalOptions.orderBy).length === 0) {
+            throw new Error(`orderBy is required for MergeTree-family tables (${tableName})`);
+        }
+        ensureColumnsExist('orderBy', finalOptions.orderBy);
+        ensureColumnsExist('primaryKey', finalOptions.primaryKey);
+        ensureColumnsExist('partitionBy', finalOptions.partitionBy);
+        ensureColumnsExist('sampleBy', finalOptions.sampleBy);
+        if (engineStr.toLowerCase().includes('replacingmergetree') && !finalOptions.versionColumn) {
+            throw new Error(`versionColumn is required for ReplacingMergeTree in table ${tableName}`);
+        }
+        const isDeduplicationEngine = engineStr.toLowerCase().includes('replacingmergetree') ||
+            engineStr.toLowerCase().includes('collapsingmergetree');
+        if (finalOptions.engine?.type === 'MergeTree' && finalOptions.deduplicateBy) {
+            console.warn(`[housekit] Table "${tableName}" uses "deduplicateBy" but engine is MergeTree. Deduplication won't happen. Did you mean ReplacingMergeTree?`);
+        }
+        if (finalOptions.logicalPrimaryKey && !isDeduplicationEngine) {
+            console.warn(`[housekit] Table "${tableName}" uses "logicalPrimaryKey" but engine is ${finalOptions.engine?.type || 'MergeTree'}. Standard MergeTree does not enforce uniqueness. Did you mean ReplacingMergeTree or CollapsingMergeTree?`);
+        }
+        if (finalOptions.deduplicateBy) {
+            ensureColumnsExist('deduplicateBy', finalOptions.deduplicateBy);
+            if (!finalOptions.versionColumn) {
+                throw new Error(`versionColumn is required when deduplicateBy is set in table ${tableName}`);
+            }
+            if (!columns[finalOptions.versionColumn]) {
+                throw new Error(`versionColumn "${finalOptions.versionColumn}" not found in table ${tableName}`);
+            }
+        }
+    }
+    else {
+        ensureColumnsExist('orderBy', finalOptions.orderBy);
+        ensureColumnsExist('primaryKey', finalOptions.primaryKey);
+        ensureColumnsExist('partitionBy', finalOptions.partitionBy);
+        ensureColumnsExist('sampleBy', finalOptions.sampleBy);
+    }
+    const tableDefBase = {
+        $table: tableName,
+        $columns: columns,
+        $options: finalOptions,
+        toSQL: () => {
+            if (finalOptions.externallyManaged) {
+                return '';
+            }
+            const colDefs = Object.values(columns).map(col => {
+                return `\`${col.name}\` ${col.toSQL()}`;
+            });
+            const formatIndexExpr = (cols) => {
+                const parts = cols.map(c => `\`${c.name}\``);
+                return cols.length > 1 ? `tuple(${parts.join(', ')})` : parts[0];
+            };
+            if (finalOptions.indices?.length) {
+                for (const idx of finalOptions.indices) {
+                    if (!idx.cols || idx.cols.length === 0)
+                        continue;
+                    const expr = formatIndexExpr(idx.cols);
+                    const granularity = idx.granularity ?? 1;
+                    const granularityClause = granularity ? ` GRANULARITY ${granularity}` : '';
+                    colDefs.push(`INDEX \`${idx.name}\` ${expr} TYPE ${idx.type}${granularityClause}`);
+                }
+            }
+            if (finalOptions.projections?.length) {
+                for (const proj of finalOptions.projections) {
+                    const query = proj.query.trim();
+                    if (!query)
+                        continue;
+                    colDefs.push(`PROJECTION \`${proj.name}\` (${query})`);
+                }
+            }
+            const clusterClause = finalOptions.onCluster ? ` ON CLUSTER ${finalOptions.onCluster}` : '';
+            let finalEngineSQL = finalOptions.customEngine || engineStr;
+            if (finalOptions.versionColumn && !finalEngineSQL.includes('Replacing')) {
+                finalEngineSQL = `ReplacingMergeTree(${finalOptions.versionColumn})`;
+            }
+            let sql = `CREATE TABLE IF NOT EXISTS \`${tableName}\`${clusterClause} (${colDefs.join(', ')}) ENGINE = ${finalEngineSQL}`;
+            const mapColumnList = (val) => {
+                if (!val)
+                    return '';
+                const list = Array.isArray(val) ? val : val.split(',').map(v => v.trim());
+                return list.map(id => {
+                    const col = columns[id];
+                    if (col)
+                        return `\`${col.name}\``;
+                    if (/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(id)) {
+                        return `\`${id}\``;
+                    }
+                    return id;
+                }).join(', ');
+            };
+            if (finalOptions.orderBy) {
+                const orderBy = mapColumnList(finalOptions.orderBy);
+                sql += ` ORDER BY (${orderBy})`;
+            }
+            else if (isMergeTreeFamilyEngine) {
+                if (finalOptions.primaryKey) {
+                    const pk = mapColumnList(finalOptions.primaryKey);
+                    sql += ` ORDER BY (${pk})`;
+                }
+                else {
+                    sql += ` ORDER BY tuple()`;
+                }
+            }
+            if (finalOptions.primaryKey) {
+                const pk = mapColumnList(finalOptions.primaryKey);
+                sql += ` PRIMARY KEY (${pk})`;
+            }
+            if (finalOptions.partitionBy) {
+                const partition = mapColumnList(finalOptions.partitionBy);
+                sql += ` PARTITION BY (${partition})`;
+            }
+            if (finalOptions.sampleBy) {
+                const sample = mapColumnList(finalOptions.sampleBy);
+                sql += ` SAMPLE BY (${sample})`;
+            }
+            if (finalOptions.ttl) {
+                let ttlClause = '';
+                if (Array.isArray(finalOptions.ttl)) {
+                    const ttlParts = finalOptions.ttl.map(ttl => {
+                        let part = ttl.expression;
+                        if (ttl.action === 'TO DISK' && ttl.target) {
+                            part += ` TO DISK '${ttl.target}'`;
+                        }
+                        else if (ttl.action === 'TO VOLUME' && ttl.target) {
+                            part += ` TO VOLUME '${ttl.target}'`;
+                        }
+                        return part;
+                    });
+                    ttlClause = `TTL ${ttlParts.join(', ')}`;
+                }
+                else if (typeof finalOptions.ttl === 'string') {
+                    ttlClause = `TTL ${finalOptions.ttl}`;
+                }
+                else {
+                    const ttl = finalOptions.ttl;
+                    let part = ttl.expression;
+                    if (ttl.action === 'TO DISK' && ttl.target) {
+                        part += ` TO DISK '${ttl.target}'`;
+                    }
+                    else if (ttl.action === 'TO VOLUME' && ttl.target) {
+                        part += ` TO VOLUME '${ttl.target}'`;
+                    }
+                    ttlClause = `TTL ${part}`;
+                }
+                sql += ` ${ttlClause}`;
+            }
+            const meta = {
+                housekit: buildHousekitMetadata(resolvedMetadataVersion, {
+                    appendOnly: finalOptions.appendOnly,
+                    readOnly: finalOptions.readOnly
+                })
+            };
+            const comment = JSON.stringify(meta);
+            sql += ` COMMENT '${comment.replace(/'/g, "\\'")}'`;
+            return sql;
+        },
+        toSQLs: function () {
+            const base = this.toSQL();
+            if (finalOptions.materializedView) {
+                const mv = finalOptions.materializedView;
+                const populateClause = mv.populate ? ' POPULATE' : '';
+                const mvSQL = `CREATE MATERIALIZED VIEW IF NOT EXISTS \`${mv.name}\`${populateClause} TO \`${mv.toTable}\` AS ${mv.query}`;
+                return [base, mvSQL];
+            }
+            return [base];
+        },
+        as: (alias) => {
+            return chTable(alias, columns, { ...finalOptions, externallyManaged: true });
+        }
+    };
+    return assignColumnsToTable(tableDefBase, columns, tableName);
+}
+export function chView(name, columns, queryOrOptions, optionsParam) {
+    attachTableName(name, columns);
+    let query;
+    let options;
+    if (typeof queryOrOptions === 'string') {
+        query = queryOrOptions;
+        options = optionsParam || {};
+    }
+    else {
+        query = queryOrOptions.query;
+        const { query: _, ...restOptions } = queryOrOptions;
+        options = restOptions;
+    }
+    const onClusterClause = options.onCluster ? ` ON CLUSTER ${options.onCluster}` : '';
+    const replaceClause = options.orReplace ? ' OR REPLACE' : '';
+    const ifNotExistsClause = options.orReplace ? '' : ' IF NOT EXISTS';
+    const toSQL = () => `CREATE${replaceClause} VIEW${ifNotExistsClause} \`${name}\`${onClusterClause} AS ${query}`;
+    const base = {
+        $table: name,
+        $columns: columns,
+        $options: { ...options, kind: 'view', query },
+        toSQL,
+        toSQLs: () => [toSQL()]
+    };
+    return assignColumnsToTable(base, columns, name);
+}
+export function defineColumns(cols) {
+    return cols;
+}
+export function extendColumns(base, extra) {
+    for (const key of Object.keys(extra)) {
+        if (key in base) {
+            throw new Error(`Column "${key}" already exists in base definition`);
+        }
+    }
+    return { ...base, ...extra };
+}
+export function versionedTable(baseName, version, columns, options = {}) {
+    const actualName = `${baseName}_v${version}`;
+    const baseTable = chTable(actualName, columns, options);
+    const aliasName = options.aliasName || baseName;
+    const latestAlias = options.latestAlias ?? true;
+    const viewSQL = latestAlias
+        ? `CREATE VIEW IF NOT EXISTS \`${aliasName}\` AS SELECT * FROM \`${actualName}\``
+        : null;
+    return {
+        ...baseTable,
+        $versionMeta: { baseName, version, aliasName: latestAlias ? aliasName : undefined },
+        toSQLs: () => viewSQL ? [baseTable.toSQL(), viewSQL] : [baseTable.toSQL()]
+    };
+}
+export function deriveTable(source, config) {
+    const groupList = Array.isArray(config.groupBy) ? config.groupBy : [config.groupBy];
+    const groupCols = groupList.map(g => g.trim()).filter(Boolean);
+    const targetColumns = {};
+    for (const g of groupCols) {
+        const col = source.$columns[g];
+        targetColumns[g] = col ? col : new ClickHouseColumn(g, 'String');
+    }
+    for (const [alias] of Object.entries(config.aggregates)) {
+        targetColumns[alias] = new ClickHouseColumn(alias, 'Float64');
+    }
+    const opts = {
+        engine: Engine.AggregatingMergeTree(),
+        orderBy: groupCols,
+        partitionBy: config.options?.partitionBy,
+        primaryKey: config.options?.primaryKey,
+        ttl: config.options?.ttl,
+        onCluster: config.options?.onCluster,
+        shardKey: config.options?.shardKey,
+        logicalPrimaryKey: config.options?.logicalPrimaryKey,
+        appendOnly: config.options?.appendOnly ?? true
+    };
+    const derived = chTable(config.name, targetColumns, opts);
+    const groupBySQL = groupCols.join(', ');
+    const aggSQL = Object.entries(config.aggregates)
+        .map(([alias, expr]) => `${expr} AS \`${alias}\``)
+        .join(', ');
+    const selectParts = [];
+    if (groupCols.length > 0)
+        selectParts.push(groupBySQL);
+    if (aggSQL)
+        selectParts.push(aggSQL);
+    const selectSQL = selectParts.join(', ');
+    const mvSQL = `CREATE MATERIALIZED VIEW IF NOT EXISTS \`${config.name}_mv\` TO \`${config.name}\` AS SELECT ${selectSQL} FROM \`${source.$table}\` GROUP BY ${groupBySQL}`;
+    return {
+        ...derived,
+        toSQLs: () => [derived.toSQL(), mvSQL]
+    };
+}
+export function renderSchema(def) {
+    if (typeof def.toSQLs === 'function') {
+        return def.toSQLs().join('\n\n');
+    }
+    return def.toSQL();
+}
+export function generateTypes(def, typeName) {
+    const name = typeName || pascalCase(def.$table);
+    const lines = Object.entries(def.$columns).map(([key, col]) => {
+        const tsType = clickHouseToTS(col.type);
+        const optional = col.isNull ? '?' : '';
+        return `  ${key}${optional}: ${tsType};`;
+    });
+    return `export interface ${name} {\n${lines.join('\n')}\n}`;
+}
+function clickHouseToTS(type) {
+    const normalized = type.replace(/\s+/g, '').toLowerCase();
+    const arrayMatch = normalized.match(/^array\((.+)\)$/);
+    if (arrayMatch) {
+        return `${clickHouseToTS(arrayMatch[1])}[]`;
+    }
+    if (normalized.startsWith('map('))
+        return 'Record<string, any>';
+    if (normalized.includes('uuid'))
+        return 'string';
+    if (normalized.startsWith('decimal')) {
+        return 'string';
+    }
+    if (normalized.startsWith('int') || normalized.startsWith('uint') || normalized.startsWith('float'))
+        return 'number';
+    if (normalized.startsWith('bool'))
+        return 'boolean';
+    if (normalized.startsWith('date') || normalized.startsWith('datetime'))
+        return 'string';
+    if (normalized.startsWith('enum'))
+        return 'string';
+    if (normalized.startsWith('aggregatefunction'))
+        return 'any';
+    if (normalized.startsWith('lowcardinality(')) {
+        const inner = normalized.slice('lowcardinality('.length, -1);
+        return clickHouseToTS(inner);
+    }
+    return 'string';
+}
+function pascalCase(name) {
+    return name.replace(/(^|_|-)(\w)/g, (_, _sep, c) => c.toUpperCase());
+}