@housekit/orm 0.1.1

package/dist/schema-builder.d.ts

@@ -0,0 +1,172 @@
+/**
+ * HouseKit Schema Builder - Fluent API for Table Definitions
+ *
+ * This module provides a modern fluent syntax for defining tables using
+ * a builder function pattern instead of individual imports.
+ *
+ * @example
+ * ```typescript
+ * import { defineTable, t } from '@housekit/orm';
+ *
+ * // Using the builder function pattern
+ * export const users = defineTable('users', (t) => ({
+ *     id: t.uuid('id').primaryKey(),
+ *     name: t.string('name'),
+ *     email: t.string('email'),
+ *     age: t.int32('age').nullable(),
+ *     createdAt: t.datetime('created_at').default('now()'),
+ * }), { engine: Engine.MergeTree(), orderBy: 'createdAt' });
+ * ```
+ */
+import { ClickHouseColumn } from './column';
+import { chView, type TableOptions, type TableDefinition, type RelationDefinition, 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';
+import { EngineConfiguration } from './engines';
+export { index };
+/**
+ * Enhanced table options with column key references for orderBy, partitionBy, etc.
+ */
+export type EnhancedTableOptions<TColKeys extends string = string> = Omit<TableOptions, 'orderBy' | 'partitionBy' | 'primaryKey' | 'sampleBy' | 'deduplicateBy' | 'versionColumn' | 'logicalPrimaryKey' | 'engine'> & {
+    engine: EngineConfiguration;
+    customEngine?: string;
+    /**
+     * Column(s) for ORDER BY. Can use column keys from your definition.
+     * @example orderBy: 'timestamp' or orderBy: ['user_id', 'timestamp']
+     */
+    orderBy?: TColKeys | TColKeys[] | string | string[];
+    /**
+     * Column(s) for PARTITION BY. Can use column keys from your definition.
+     */
+    partitionBy?: TColKeys | TColKeys[] | string | string[];
+    /**
+     * Column(s) for PRIMARY KEY. Can use column keys from your definition.
+     */
+    primaryKey?: TColKeys | TColKeys[] | string | string[];
+    /**
+     * Column(s) for SAMPLE BY. Can use column keys from your definition.
+     */
+    sampleBy?: TColKeys | TColKeys[] | string | string[];
+    /**
+     * Column(s) for deduplication (ReplacingMergeTree).
+     */
+    deduplicateBy?: TColKeys | TColKeys[] | string | string[];
+    /**
+     * Version column for ReplacingMergeTree.
+     */
+    versionColumn?: TColKeys | string;
+    /**
+     * Logical primary key (for documentation, not enforced).
+     */
+    logicalPrimaryKey?: TColKeys | TColKeys[] | string | string[];
+};
+/**
+ * ClickHouse data types builder.
+ * All columns are NOT NULL by default, following ClickHouse philosophy.
+ */
+export declare const t: {
+    int8: (name: string) => ClickHouseColumn<number, true, false>;
+    int16: (name: string) => ClickHouseColumn<number, true, false>;
+    integer: (name: string) => ClickHouseColumn<number, true, false>;
+    /**
+     * Int32 type. Signed 32-bit integer.
+     * @range -2147483648 to 2147483647
+     */
+    int32: (name: string) => ClickHouseColumn<number, true, false>;
+    int64: (name: string) => ClickHouseColumn<number, true, false>;
+    int128: (name: string) => ClickHouseColumn<number, true, false>;
+    int256: (name: string) => ClickHouseColumn<number, true, false>;
+    uint8: (name: string) => ClickHouseColumn<number, true, false>;
+    uint16: (name: string) => ClickHouseColumn<number, true, false>;
+    uint32: (name: string) => ClickHouseColumn<number, true, false>;
+    uint64: (name: string) => ClickHouseColumn<number, true, false>;
+    uint128: (name: string) => ClickHouseColumn<number, true, false>;
+    uint256: (name: string) => ClickHouseColumn<number, true, false>;
+    float32: (name: string) => ClickHouseColumn<number, true, false>;
+    float: (name: string) => ClickHouseColumn<number, true, false>;
+    float64: (name: string) => ClickHouseColumn<number, true, false>;
+    bfloat16: (name: string) => ClickHouseColumn<number, true, false>;
+    decimal: (name: string, precision?: number, scale?: number) => ClickHouseColumn<number, true, false>;
+    decimal32: (name: string, scale?: number) => ClickHouseColumn<number, true, false>;
+    decimal64: (name: string, scale?: number) => ClickHouseColumn<number, true, false>;
+    decimal128: (name: string, scale?: number) => ClickHouseColumn<number, true, false>;
+    decimal256: (name: string, scale?: number) => ClickHouseColumn<number, true, false>;
+    text: (name: string) => ClickHouseColumn<string, true, false>;
+    string: (name: string) => ClickHouseColumn<string, true, false>;
+    fixedString: (name: string, length: number) => ClickHouseColumn<string, true, false>;
+    varchar: (name: string, opts?: {
+        length?: number;
+    }) => ClickHouseColumn<string, true, false>;
+    date: (name: string) => ClickHouseColumn<string | Date, true, false>;
+    date32: (name: string) => ClickHouseColumn<string | Date, true, false>;
+    timestamp: (name: string, timezone?: string) => ClickHouseColumn<string | Date, true, false>;
+    /**
+     * DateTime type. Stores date and time.
+     * @param timezone - Optional. Example: 'UTC', 'Europe/Madrid'
+     */
+    datetime: (name: string, timezone?: string) => ClickHouseColumn<string | Date, true, false>;
+    datetime64: (name: string, precision?: number, timezone?: string) => ClickHouseColumn<string | Date, true, false>;
+    boolean: (name: string) => ClickHouseColumn<boolean, true, false>;
+    bool: (name: string) => ClickHouseColumn<boolean, true, false>;
+    uuid: (name: string) => ClickHouseColumn<string, true, false>;
+    ipv4: (name: string) => ClickHouseColumn<string, true, false>;
+    ipv6: (name: string) => ClickHouseColumn<string, true, false>;
+    array: <T>(col: ClickHouseColumn<T>) => ClickHouseColumn<T[], true, false>;
+    tuple: (name: string, types: string[]) => ClickHouseColumn<any, true, false>;
+    map: (name: string, keyType?: string, valueType?: string) => ClickHouseColumn<Record<string, any>, true, false>;
+    nested: (name: string, fields: Record<string, string>) => ClickHouseColumn<any, true, false>;
+    json: <TSchema = Record<string, any>>(name: string) => ClickHouseColumn<TSchema, false, false>;
+    dynamic: (name: string, maxTypes?: number) => ClickHouseColumn<any, true, false>;
+    /**
+     * LowCardinality type. Optimizes columns with few unique values
+     * (typically < 10,000) for ultra-fast reading.
+     * @see https://clickhouse.com/docs/en/sql-reference/data-types/lowcardinality
+     */
+    lowCardinality: <T, TNotNull extends boolean, TAutoGenerated extends boolean>(col: ClickHouseColumn<T, TNotNull, TAutoGenerated>) => ClickHouseColumn<T, TNotNull, TAutoGenerated>;
+    aggregateFunction: (name: string, funcName: string, ...argTypes: string[]) => ClickHouseColumn<any, true, false>;
+    simpleAggregateFunction: (name: string, funcName: string, argType: string) => ClickHouseColumn<any, true, false>;
+    point: (name: string) => ClickHouseColumn<[number, number], true, false>;
+    ring: (name: string) => ClickHouseColumn<[number, number][], true, false>;
+    polygon: (name: string) => ClickHouseColumn<[number, number][][], true, false>;
+    multiPolygon: (name: string) => ClickHouseColumn<[number, number][][][], true, false>;
+    enum: (name: string, values: readonly string[]) => ClickHouseColumn<string, false, false>;
+};
+export type ColumnBuilder = typeof t;
+/**
+ * Define a strongly-typed ClickHouse table.
+ *
+ * @param name - Physical table name in ClickHouse.
+ * @param columns - Column definition object or callback using `t` builder.
+ * @param options - Engine configuration, sorting keys, partitioning, etc.
+ */
+export declare function defineTable<T extends Record<string, ClickHouseColumn<any, any, any>>>(tableName: string, columnsOrCallback: T | ((t: ColumnBuilder) => T), options: EnhancedTableOptions<keyof T & string>): TableDefinition<T, TableOptions>;
+/**
+ * Aliases for modern API - providing both short and explicit naming.
+ *
+ * NOTE: defineTable is the preferred explicit naming for library consistency,
+ * while 'table' is provided as a shorthand similar to other ORMs.
+ */
+export declare const table: typeof defineTable;
+export declare const view: typeof chView;
+export declare const defineView: typeof chView;
+export declare const defineMaterializedView: typeof chMaterializedView;
+export declare const materializedView: typeof chMaterializedView;
+export declare const dictionary: typeof chDictionary;
+export declare const defineDictionary: typeof chDictionary;
+export { projection };
+export { chProjection as defineProjection };
+/**
+ * Define relations for a table using a callback pattern.
+ */
+export declare function relations<TTable extends TableDefinition<any>>(table: TTable, relationsBuilder: (helpers: {
+    one: (table: TableDefinition<any>, config: {
+        fields: ClickHouseColumn<any, any, any>[];
+        references: ClickHouseColumn<any, any, any>[];
+    }) => RelationDefinition;
+    many: (table: TableDefinition<any>, config?: {
+        fields?: ClickHouseColumn<any, any, any>[];
+        references?: ClickHouseColumn<any, any, any>[];
+    }) => RelationDefinition;
+}) => Record<string, RelationDefinition>): Record<string, RelationDefinition>;

package/dist/table.d.ts

@@ -0,0 +1,172 @@
+import { ClickHouseColumn } from './column';
+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[];
+    partitionBy?: string | string[];
+    primaryKey?: string | string[];
+    logicalPrimaryKey?: string | string[];
+    ttl?: TTLRule | TTLRule[] | string;
+    appendOnly?: boolean;
+    deduplicateBy?: string | string[];
+    versionColumn?: string;
+    externallyManaged?: boolean;
+    sampleBy?: string | string[];
+    onCluster?: string;
+    shardKey?: string | string[];
+    materializedView?: {
+        name: string;
+        toTable: string;
+        query: string;
+        populate?: boolean;
+    };
+    defaultFinal?: boolean;
+    metadataVersion?: MetadataVersion;
+    readOnly?: boolean;
+    indices?: IndexDefinition[];
+    projections?: ProjectionDefinition[];
+    asyncInsert?: boolean;
+}
+export type IndexDefinition = {
+    name: string;
+    cols: ClickHouseColumn[];
+    type: 'minmax' | 'set' | 'bloom_filter';
+    granularity?: number;
+};
+export type ProjectionDefinition = {
+    name: string;
+    query: string;
+};
+export declare const index: (name: string) => {
+    on: (...cols: ClickHouseColumn[]) => {
+        type: (type: IndexDefinition["type"], granularity?: number) => IndexDefinition;
+    };
+};
+export declare const projection: (name: string, query: string) => ProjectionDefinition;
+export type RelationDefinition = {
+    relation: 'one';
+    name: string;
+    table: TableDefinition<any>;
+    fields: ClickHouseColumn[];
+    references: ClickHouseColumn[];
+} | {
+    relation: 'many';
+    name: string;
+    table: TableDefinition<any>;
+    fields?: ClickHouseColumn[];
+    references?: ClickHouseColumn[];
+};
+export type TableColumns = Record<string, ClickHouseColumn<any, any, any>>;
+export type TableRow<TCols extends TableColumns> = {
+    [K in keyof TCols]: TCols[K] extends ClickHouseColumn<infer T, infer NotNull, any> ? NotNull extends true ? T : T | null : never;
+};
+export type TableInsert<TCols extends TableColumns> = {
+    [K in keyof TCols as TCols[K] extends ClickHouseColumn<any, infer NotNull, infer Auto> ? NotNull extends true ? Auto extends true ? never : K : never : never]: TCols[K] extends ClickHouseColumn<infer T, any, any> ? T : never;
+} & Partial<{
+    [K in keyof TCols as TCols[K] extends ClickHouseColumn<any, infer NotNull, infer Auto> ? NotNull extends true ? Auto extends true ? K : never : K : never]: TCols[K] extends ClickHouseColumn<infer T, any, any> ? T : never;
+}>;
+type GetColumnType<T extends ClickHouseColumn> = T extends ClickHouseColumn<infer Type, infer IsNotNull, any> ? IsNotNull extends true ? Type : Type | null : never;
+export type InferSelectModel<T extends {
+    $columns: TableColumns;
+}> = {
+    [K in keyof T['$columns']]: GetColumnType<T['$columns'][K]>;
+};
+export type InferInsertModel<T extends {
+    $columns: TableColumns;
+}> = TableInsert<T['$columns']>;
+export type TableDefinition<TCols extends TableColumns, TOptions = TableOptions> = {
+    $table: string;
+    $columns: TCols;
+    $options: TOptions;
+    $relations?: Record<string, RelationDefinition>;
+    toSQL(): string;
+    toSQLs?(): string[];
+    as(alias: string): TableDefinition<TCols, TOptions>;
+    $inferSelect?: InferSelectModel<{
+        $columns: TCols;
+    }>;
+    $inferInsert?: InferInsertModel<{
+        $columns: TCols;
+    }>;
+} & TCols;
+export interface VersionedMeta {
+    baseName: string;
+    version: string | number;
+    aliasName?: string;
+}
+type CommonViewOptions = {
+    onCluster?: string;
+    orReplace?: boolean;
+};
+export interface ViewOptions extends CommonViewOptions {
+    kind?: 'view';
+}
+export interface MaterializedViewOptions extends CommonViewOptions {
+    kind?: 'materializedView';
+    toTable?: string;
+    engine?: EngineConfiguration;
+    populate?: boolean;
+}
+export declare function chTable<T extends Record<string, ClickHouseColumn<any, any, any>>>(tableName: string, columns: T, options?: TableOptions): TableDefinition<T, TableOptions>;
+export declare function chView<T extends Record<string, ClickHouseColumn<any, any, any>>>(name: string, columns: T, options: ViewOptions & {
+    query: string;
+}): TableDefinition<T, ViewOptions & {
+    kind: 'view';
+    query: string;
+}> & {
+    toSQLs: () => string[];
+};
+export declare function chView<T extends Record<string, ClickHouseColumn<any, any, any>>>(name: string, columns: T, query: string, options?: ViewOptions): TableDefinition<T, ViewOptions & {
+    kind: 'view';
+    query: string;
+}> & {
+    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;
+}): TableDefinition<T> & {
+    $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[];
+    aggregates: Record<string, string>;
+    options?: TableOptions;
+}): 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/utils/background-batcher.d.ts

@@ -0,0 +1,20 @@
+import type { ClickHouseClient } from '@clickhouse/client';
+import type { TableDefinition } from '../core';
+export interface BatchConfig {
+    maxRows: number;
+    flushIntervalMs: number;
+}
+declare class BackgroundBatcher {
+    private client;
+    private queues;
+    private timers;
+    private tables;
+    private serializers;
+    constructor(client: ClickHouseClient);
+    private getSerializer;
+    add(table: TableDefinition<any>, row: any, config: BatchConfig): Promise<void>;
+    flush(tableName: string): Promise<void>;
+    flushAll(): Promise<void>;
+}
+export declare const globalBatcher: (client: ClickHouseClient) => BackgroundBatcher;
+export {};

package/dist/utils/batch-transform.d.ts

@@ -0,0 +1,20 @@
+import { Transform, type TransformCallback } from 'stream';
+import { InsertPlan } from './insert-processing';
+export interface BatchTransformOptions {
+    batchSize?: number;
+    maxProcessingTime?: number;
+}
+export declare class BatchTransformStream extends Transform {
+    private plan;
+    private mode;
+    private batch;
+    private processingTimer;
+    private readonly batchSize;
+    private readonly maxProcessingTime;
+    constructor(plan: InsertPlan, mode: 'compact' | 'json', options?: BatchTransformOptions);
+    _transform(chunk: any, _encoding: BufferEncoding, callback: TransformCallback): void;
+    _flush(callback: TransformCallback): void;
+    private scheduleProcessing;
+    private processBatch;
+}
+export declare function createBatchTransformStream(plan: InsertPlan, mode: 'compact' | 'json', options?: BatchTransformOptions): BatchTransformStream;

package/dist/utils/binary-reader.d.ts

@@ -0,0 +1,48 @@
+/**
+ * HouseKit Binary Reader - Ultra-Fast RowBinary Decoding
+ *
+ * optimized for reading ClickHouse RowBinary format directly from buffers.
+ * This is 10-20x faster than JSON.parse() for large datasets.
+ */
+export declare class BinaryReader {
+    private buffer;
+    private offset;
+    private view;
+    constructor(buffer: Buffer);
+    reset(buffer: Buffer): void;
+    getOffset(): number;
+    isEOF(): boolean;
+    readInt8(): number;
+    readUInt8(): number;
+    readInt16(): number;
+    readUInt16(): number;
+    readInt32(): number;
+    readUInt32(): number;
+    readInt64(): bigint;
+    readUInt64(): bigint;
+    readInt128(): bigint;
+    readUInt128(): bigint;
+    readInt256(): bigint;
+    readUInt256(): bigint;
+    readFloat32(): number;
+    readFloat64(): number;
+    readVarInt(): number;
+    readString(): string;
+    readFixedString(length: number): string;
+    readUUID(): string;
+    readDate(): string;
+    readDate32(): string;
+    readDateTime(): Date;
+    readDateTime64(precision?: number): Date;
+    readNullable<T>(reader: () => T): T | null;
+    readArray<T>(itemReader: () => T): T[];
+    readMap<K, V>(keyReader: () => K, valueReader: () => V): Record<any, any>;
+    readDecimal32(scale: number): number;
+    readDecimal64(scale: number): number;
+    readDecimal128(scale: number): number;
+    readBool(): boolean;
+    readIPv4(): string;
+    readIPv6(): string;
+}
+export type BinaryDecoder = (reader: BinaryReader) => any;
+export declare function createBinaryDecoder(type: string): BinaryDecoder;

package/dist/utils/binary-serializer.d.ts

@@ -0,0 +1,160 @@
+/**
+ * HouseKit Binary Serializer - Ultra-Fast RowBinary Encoding
+ *
+ * ClickHouse's RowBinary format sends data directly as bytes with no parsing overhead.
+ * This is the fastest possible way to insert data into ClickHouse.
+ *
+ * Benefits over JSONEachRow:
+ * - No JSON.stringify() overhead
+ * - No string escaping
+ * - No parsing on ClickHouse side
+ * - Smaller payload (Int64 = 8 bytes vs up to 20 bytes as string)
+ * - Lower GC pressure (no intermediate strings)
+ */
+/**
+ * Efficient binary buffer writer that minimizes allocations.
+ * Uses a pre-allocated buffer that grows as needed.
+ */
+export declare class BinaryWriter {
+    private buffer;
+    private offset;
+    constructor(initialSize?: number);
+    /**
+     * Ensure buffer has enough space for n more bytes
+     */
+    private ensureCapacity;
+    /**
+     * Reset the writer for reuse (avoids allocating new buffer)
+     */
+    reset(): void;
+    /**
+     * Get the final buffer with only written bytes
+     */
+    getBuffer(): Buffer;
+    /**
+     * Get a copy of the buffer (safe to use after reset)
+     */
+    toBuffer(): Buffer;
+    writeInt8(value: number): void;
+    writeUInt8(value: number): void;
+    writeInt16(value: number): void;
+    writeUInt16(value: number): void;
+    writeInt32(value: number): void;
+    writeUInt32(value: number): void;
+    writeInt64(value: bigint | number): void;
+    writeUInt64(value: bigint | number): void;
+    writeInt128(value: bigint): void;
+    writeUInt128(value: bigint): void;
+    writeInt256(value: bigint): void;
+    writeUInt256(value: bigint): void;
+    writeFloat32(value: number): void;
+    writeFloat64(value: number): void;
+    /**
+     * Write a variable-length integer (LEB128).
+     * Used for string lengths in RowBinary format.
+     */
+    writeVarInt(value: number): void;
+    /**
+     * Write a string in RowBinary format: [VarInt length][UTF-8 bytes]
+     */
+    writeString(value: string): void;
+    /**
+     * Write a FixedString(N) - padded with null bytes if shorter
+     */
+    writeFixedString(value: string, length: number): void;
+    /**
+     * Write raw bytes directly
+     */
+    writeBytes(data: Buffer): void;
+    /**
+     * Write a UUID (16 bytes).
+     * ClickHouse stores UUIDs as two UInt64 in big-endian order!
+     * This is different from the usual little-endian storage.
+     */
+    writeUUID(value: string): void;
+    /**
+     * Write a Date (days since epoch as UInt16)
+     */
+    writeDate(value: Date | number): void;
+    /**
+     * Write a Date32 (days since epoch as Int32)
+     */
+    writeDate32(value: Date | number): void;
+    /**
+     * Write a DateTime (seconds since epoch as UInt32)
+     */
+    writeDateTime(value: Date | number): void;
+    /**
+     * Write a DateTime64 with specified precision
+     */
+    writeDateTime64(value: Date | number, precision?: number): void;
+    /**
+     * Write a nullable prefix (0 = not null, 1 = null)
+     */
+    writeNullable(isNull: boolean): void;
+    /**
+     * Write array length prefix
+     */
+    writeArrayLength(length: number): void;
+    /**
+     * Write Decimal32 (stored as Int32)
+     */
+    writeDecimal32(value: number, scale: number): void;
+    /**
+     * Write Decimal64 (stored as Int64)
+     */
+    writeDecimal64(value: number, scale: number): void;
+    /**
+     * Write Decimal128 (stored as Int128)
+     */
+    writeDecimal128(value: number | bigint, scale: number): void;
+    writeBool(value: boolean): void;
+    /**
+     * Write IPv4 address (UInt32 in network byte order)
+     */
+    writeIPv4(value: string | number): void;
+    /**
+     * Write IPv6 address (16 bytes)
+     */
+    writeIPv6(value: string | Buffer): void;
+    private expandIPv6;
+    writeEnum8(value: number): void;
+    writeEnum16(value: number): void;
+}
+export type BinaryEncoder = (writer: BinaryWriter, value: any) => void;
+/**
+ * Create a binary encoder for a ClickHouse column type
+ */
+export declare function createBinaryEncoder(clickhouseType: string, isNullable?: boolean): BinaryEncoder;
+/**
+ * Configuration for binary serialization
+ */
+export interface BinarySerializationConfig {
+    /** Column names in order */
+    columns: Array<{
+        name: string;
+        type: string;
+        isNullable: boolean;
+    }>;
+    /** Property key mapping (propKey -> column index) */
+    keyMapping: Map<string, number>;
+    /** Pre-compiled encoders for each column */
+    encoders: BinaryEncoder[];
+}
+/**
+ * Build a binary serialization configuration from a table definition
+ */
+export declare function buildBinaryConfig(columns: Array<{
+    name: string;
+    type: string;
+    isNull: boolean;
+    propKey: string;
+}>): BinarySerializationConfig;
+/**
+ * Serialize a single row to RowBinary format
+ */
+export declare function serializeRowBinary(row: Record<string, any>, config: BinarySerializationConfig, writer?: BinaryWriter): Buffer;
+/**
+ * Serialize multiple rows to a single RowBinary buffer
+ */
+export declare function serializeRowsBinary(rows: Array<Record<string, any>>, config: BinarySerializationConfig): Buffer;

package/dist/utils/binary-worker-code.d.ts

@@ -0,0 +1 @@
+export declare const binaryWorkerCode = "import{parentPort as D,workerData as d}from\"worker_threads\";var X=[];for(let x=0;x<256;++x)X.push((x+256).toString(16).slice(1));function B(x,U=0){return(X[x[U+0]]+X[x[U+1]]+X[x[U+2]]+X[x[U+3]]+\"-\"+X[x[U+4]]+X[x[U+5]]+\"-\"+X[x[U+6]]+X[x[U+7]]+\"-\"+X[x[U+8]]+X[x[U+9]]+\"-\"+X[x[U+10]]+X[x[U+11]]+X[x[U+12]]+X[x[U+13]]+X[x[U+14]]+X[x[U+15]]).toLowerCase()}import{randomFillSync as o}from\"node:crypto\";var N=new Uint8Array(256),G=N.length;function P(){if(G>N.length-16)o(N),G=0;return N.slice(G,G+=16)}import{randomUUID as n}from\"node:crypto\";var S={randomUUID:n};function y(x,U,I){x=x||{};let A=x.random??x.rng?.()??P();if(A.length<16)throw Error(\"Random bytes length must be >= 16\");if(A[6]=A[6]&15|64,A[8]=A[8]&63|128,U){if(I=I||0,I<0||I+16>U.length)throw RangeError(`UUID byte range ${I}:${I+15} is out of buffer bounds`);for(let H=0;H<16;++H)U[I+H]=A[H];return U}return B(A)}function p(x,U,I){if(S.randomUUID&&!U&&!x)return S.randomUUID();return y(x,U,I)}var W=p;class z{buffer;offset=0;constructor(x=4096){this.buffer=Buffer.allocUnsafe(x)}ensureCapacity(x){let U=this.offset+x;if(U>this.buffer.length){let I=Math.max(this.buffer.length*2,U),A=Buffer.allocUnsafe(I);this.buffer.copy(A,0,0,this.offset),this.buffer=A}}reset(){this.offset=0}getBuffer(){return this.buffer.subarray(0,this.offset)}toBuffer(){return Buffer.from(this.buffer.subarray(0,this.offset))}writeInt8(x){this.ensureCapacity(1),this.buffer.writeInt8(x,this.offset),this.offset+=1}writeUInt8(x){this.ensureCapacity(1),this.buffer.writeUInt8(x,this.offset),this.offset+=1}writeInt16(x){this.ensureCapacity(2),this.buffer.writeInt16LE(x,this.offset),this.offset+=2}writeUInt16(x){this.ensureCapacity(2),this.buffer.writeUInt16LE(x,this.offset),this.offset+=2}writeInt32(x){this.ensureCapacity(4),this.buffer.writeInt32LE(x,this.offset),this.offset+=4}writeUInt32(x){this.ensureCapacity(4),this.buffer.writeUInt32LE(x,this.offset),this.offset+=4}writeInt64(x){this.ensureCapacity(8),this.buffer.writeBigInt64LE(BigInt(x),this.offset),this.offset+=8}writeUInt64(x){this.ensureCapacity(8),this.buffer.writeBigUInt64LE(BigInt(x),this.offset),this.offset+=8}writeInt128(x){this.ensureCapacity(16);let U=x&BigInt(\"0xFFFFFFFFFFFFFFFF\"),I=x>>BigInt(64);this.buffer.writeBigUInt64LE(U,this.offset),this.buffer.writeBigInt64LE(I,this.offset+8),this.offset+=16}writeUInt128(x){this.ensureCapacity(16);let U=x&BigInt(\"0xFFFFFFFFFFFFFFFF\"),I=x>>BigInt(64);this.buffer.writeBigUInt64LE(U,this.offset),this.buffer.writeBigUInt64LE(I,this.offset+8),this.offset+=16}writeInt256(x){this.ensureCapacity(32);for(let U=0;U<4;U++){let I=x&BigInt(\"0xFFFFFFFFFFFFFFFF\");this.buffer.writeBigUInt64LE(I,this.offset+U*8),x>>=BigInt(64)}this.offset+=32}writeUInt256(x){this.writeInt256(x)}writeFloat32(x){this.ensureCapacity(4),this.buffer.writeFloatLE(x,this.offset),this.offset+=4}writeFloat64(x){this.ensureCapacity(8),this.buffer.writeDoubleLE(x,this.offset),this.offset+=8}writeVarInt(x){if(x<128){this.ensureCapacity(1),this.buffer[this.offset++]=x;return}if(x<16384){this.ensureCapacity(2),this.buffer[this.offset++]=x&127|128,this.buffer[this.offset++]=x>>7;return}if(x<2097152){this.ensureCapacity(3),this.buffer[this.offset++]=x&127|128,this.buffer[this.offset++]=x>>7&127|128,this.buffer[this.offset++]=x>>14;return}this.ensureCapacity(10);while(x>=128)this.buffer[this.offset++]=x&127|128,x>>>=7;this.buffer[this.offset++]=x}writeString(x){let U=Buffer.from(x,\"utf-8\");this.writeVarInt(U.length),this.ensureCapacity(U.length),U.copy(this.buffer,this.offset),this.offset+=U.length}writeFixedString(x,U){this.ensureCapacity(U);let I=Buffer.from(x,\"utf-8\"),A=Math.min(I.length,U);if(I.copy(this.buffer,this.offset,0,A),A<U)this.buffer.fill(0,this.offset+A,this.offset+U);this.offset+=U}writeBytes(x){this.ensureCapacity(x.length),x.copy(this.buffer,this.offset),this.offset+=x.length}writeUUID(x){this.ensureCapacity(16);let U=x.replace(/-/g,\"\");if(U.length!==32)throw Error(`Invalid UUID: ${x}`);let I=Buffer.from(U,\"hex\");for(let A=7;A>=0;A--)this.buffer[this.offset++]=I[A];for(let A=15;A>=8;A--)this.buffer[this.offset++]=I[A]}writeDate(x){let U=typeof x===\"number\"?x:Math.floor(x.getTime()/86400000);this.writeUInt16(U)}writeDate32(x){let U=typeof x===\"number\"?x:Math.floor(x.getTime()/86400000);this.writeInt32(U)}writeDateTime(x){let U=typeof x===\"number\"?x:Math.floor(x.getTime()/1000);this.writeUInt32(U)}writeDateTime64(x,U=3){let I=Math.pow(10,U),A=typeof x===\"number\"?BigInt(Math.round(x*I)):BigInt(Math.round(x.getTime()*I/1000));this.writeInt64(A)}writeNullable(x){this.writeUInt8(x?1:0)}writeArrayLength(x){this.writeUInt64(x)}writeDecimal32(x,U){let I=Math.round(x*Math.pow(10,U));this.writeInt32(I)}writeDecimal64(x,U){let I=BigInt(Math.round(x*Math.pow(10,U)));this.writeInt64(I)}writeDecimal128(x,U){let I;if(typeof x===\"bigint\")I=x*BigInt(Math.pow(10,U));else I=BigInt(Math.round(x*Math.pow(10,U)));this.writeInt128(I)}writeBool(x){this.writeUInt8(x?1:0)}writeIPv4(x){if(typeof x===\"number\"){this.writeUInt32(x);return}let U=x.split(\".\").map(Number);if(U.length!==4)throw Error(`Invalid IPv4: ${x}`);let I=U[0]<<24|U[1]<<16|U[2]<<8|U[3];this.writeUInt32(I>>>0)}writeIPv6(x){if(Buffer.isBuffer(x)){if(x.length!==16)throw Error(\"IPv6 must be 16 bytes\");this.writeBytes(x);return}let I=this.expandIPv6(x).split(\":\");this.ensureCapacity(16);for(let A of I){let H=parseInt(A,16);this.buffer.writeUInt16BE(H,this.offset),this.offset+=2}}expandIPv6(x){let U=x.split(\"::\");if(U.length===1)return x;let I=U[0]?U[0].split(\":\"):[],A=U[1]?U[1].split(\":\"):[],H=8-I.length-A.length,K=Array(H).fill(\"0000\");return[...I,...K,...A].map((L)=>L.padStart(4,\"0\")).join(\":\")}writeEnum8(x){this.writeInt8(x)}writeEnum16(x){this.writeInt16(x)}}function m(x){let U=[],I=\"\",A=0;for(let H=0;H<x.length;H++){let K=x[H];if(K===\",\"&&A===0)U.push(I.trim()),I=\"\";else{if(K===\"(\")A++;if(K===\")\")A--;I+=K}}if(I.trim())U.push(I.trim());return U}function Q(x,U=!1){let I=x.toLowerCase().trim(),A=I.match(/^nullable\\((.+)\\)$/);if(A){let C=Q(A[1],!1);return($,F)=>{if(F===null||F===void 0)$.writeNullable(!0);else $.writeNullable(!1),C($,F)}}let H=I.match(/^array\\((.+)\\)$/);if(H){let C=Q(H[1],!1);return($,F)=>{let O=Array.isArray(F)?F:[];$.writeArrayLength(O.length);for(let J of O)C($,J)}}let K=I.match(/^map\\((.+)\\)$/);if(K){let[C,$]=m(K[1]);if(!C||!$)throw Error(`Invalid Map type: ${I}`);let F=Q(C),O=Q($);return(J,j)=>{let V;if(j instanceof Map)V=Array.from(j.entries());else if(typeof j===\"object\"&&j!==null)V=Object.entries(j);else V=[];J.writeUInt64(V.length);for(let[Y,q]of V)F(J,Y),O(J,q)}}let L=I.match(/^tuple\\((.+)\\)$/);if(L){let $=m(L[1]).map((F)=>Q(F));return(F,O)=>{let J=Array.isArray(O)?O:[];for(let j=0;j<$.length;j++)$[j](F,J[j])}}let T=I.match(/^nested\\((.+)\\)$/);if(T){let C=m(T[1]),F=`Tuple(${C.map((J)=>{let j=J.trim().split(/\\s+/);if(j.length<2)return\"String\";return j.slice(1).join(\" \")}).join(\", \")})`,O=Q(F);return(J,j)=>{let V=Array.isArray(j)?j:[];J.writeArrayLength(V.length);for(let Y of V){let q=Y;if(!Array.isArray(Y)&&typeof Y===\"object\")q=C.map((h)=>{let g=h.trim().split(/\\s+/)[0];return Y[g]});O(J,q)}}}let b=I.match(/^lowcardinality\\((.+)\\)$/);if(b)return Q(b[1]);let k=I.match(/^fixedstring\\((\\d+)\\)$/);if(k){let C=parseInt(k[1],10);return($,F)=>{$.writeFixedString(String(F??\"\"),C)}}let E=I.match(/^decimal(?:32|64|128)?\\((\\d+),\\s*(\\d+)\\)$/);if(E){let C=parseInt(E[2],10);if(I.includes(\"decimal128\"))return($,F)=>$.writeDecimal128(F,C);if(I.includes(\"decimal64\"))return($,F)=>$.writeDecimal64(F,C);return($,F)=>$.writeDecimal32(F,C)}let M=I.match(/^datetime64\\((\\d+)/);if(M){let C=parseInt(M[1],10);return($,F)=>$.writeDateTime64(F,C)}if(I.match(/^enum8\\(/))return(C,$)=>C.writeEnum8(Number($));if(I.match(/^enum16\\(/))return(C,$)=>C.writeEnum16(Number($));let R=w(I);if(U)return(C,$)=>{if($===null||$===void 0)C.writeNullable(!0);else C.writeNullable(!1),R(C,$)};if(I===\"uuid\")return(C,$)=>{if($===void 0||$===null)R(C,W());else R(C,$)};return R}function w(x){if(x===\"int8\")return(U,I)=>U.writeInt8(Number(I));if(x===\"uint8\")return(U,I)=>U.writeUInt8(Number(I));if(x===\"int16\")return(U,I)=>U.writeInt16(Number(I));if(x===\"uint16\")return(U,I)=>U.writeUInt16(Number(I));if(x===\"int32\")return(U,I)=>U.writeInt32(Number(I));if(x===\"uint32\")return(U,I)=>U.writeUInt32(Number(I));if(x===\"int64\")return(U,I)=>U.writeInt64(I);if(x===\"uint64\")return(U,I)=>U.writeUInt64(I);if(x===\"int128\")return(U,I)=>U.writeInt128(BigInt(I));if(x===\"uint128\")return(U,I)=>U.writeUInt128(BigInt(I));if(x===\"int256\")return(U,I)=>U.writeInt256(BigInt(I));if(x===\"uint256\")return(U,I)=>U.writeUInt256(BigInt(I));if(x===\"float32\")return(U,I)=>U.writeFloat32(Number(I));if(x===\"float64\")return(U,I)=>U.writeFloat64(Number(I));if(x===\"string\")return(U,I)=>U.writeString(String(I??\"\"));if(x===\"uuid\")return(U,I)=>U.writeUUID(String(I));if(x===\"date\")return(U,I)=>U.writeDate(I);if(x===\"date32\")return(U,I)=>U.writeDate32(I);if(x===\"datetime\")return(U,I)=>U.writeDateTime(I);if(x.startsWith(\"datetime64\"))return(U,I)=>U.writeDateTime64(I,3);if(x===\"bool\"||x===\"boolean\")return(U,I)=>U.writeBool(Boolean(I));if(x===\"ipv4\")return(U,I)=>U.writeIPv4(I);if(x===\"ipv6\")return(U,I)=>U.writeIPv6(I);return(U,I)=>U.writeString(String(I??\"\"))}var Z=null,_=null;function s(x,U){if(!Z||!_)throw Error(\"Worker not configured\");_.reset();for(let I of x)for(let A=0;A<Z.columns.length;A++){let H=Z.columns[A],K=I[H.name];Z.encoders[A](_,K)}return _.toBuffer()}function f(x){try{switch(x.type){case\"configure\":{let U=x.columns.map((I)=>Q(I.type,I.isNullable));Z={columns:x.columns,keyMapping:new Map,encoders:U},_=new z(1048576),D?.postMessage({type:\"ready\"});break}case\"serialize\":{let U=s(x.rows,x.batchId),I=new ArrayBuffer(U.length);new Uint8Array(I).set(U),D?.postMessage({type:\"result\",batchId:x.batchId,buffer:Buffer.from(I),rowCount:x.rows.length},[I]);break}case\"shutdown\":process.exit(0)}}catch(U){D?.postMessage({type:\"error\",batchId:x.batchId,error:U instanceof Error?U.message:String(U)})}}if(D){if(D.on(\"message\",f),d?.columns)f({type:\"configure\",columns:d.columns})}\n";