@lossless.org/client 0.1.0

package/ts/sqldb/clickhouse/smartclickhouse.classes.clickhousetable.ts

@@ -0,0 +1,372 @@
+import * as plugins from './smartclickhouse.plugins.js';
+import type { SmartClickHouseDb } from './smartclickhouse.classes.smartclickhouse.js';
+import { ClickhouseQueryBuilder } from './smartclickhouse.classes.querybuilder.js';
+import type {
+  IClickhouseTableOptions,
+  IColumnInfo,
+  IEngineConfig,
+  TClickhouseColumnType,
+} from './smartclickhouse.types.js';
+import { detectClickhouseType } from './smartclickhouse.types.js';
+import { quoteClickHouseIdentifier as quoteIdentifier } from '../interfaces.js';
+import { MetricWriter, type IMetricWriterOptions } from './classes.metricwriter.js';
+import { Operation } from '../../core/classes.operation.js';
+import { LosslessClientError } from '../../core/classes.error.js';
+import type { IOperationOptions } from '../../core/interfaces.js';
+
+export class ClickhouseTable<T extends Record<string, any>> {
+  // ---- STATIC FACTORY ----
+
+  public static async create<T extends Record<string, any>>(
+    db: SmartClickHouseDb,
+    options: IClickhouseTableOptions<T>,
+  ): Promise<ClickhouseTable<T>> {
+    const table = new ClickhouseTable<T>(db, options);
+    await table.setup();
+    return table;
+  }
+
+  // ---- INSTANCE ----
+
+  public db: SmartClickHouseDb;
+  public options: IClickhouseTableOptions<T> & { database: string; engine: IEngineConfig };
+  public columns: IColumnInfo[] = [];
+
+
+  constructor(db: SmartClickHouseDb, options: IClickhouseTableOptions<T>) {
+    this.db = db;
+    this.options = {
+      autoSchemaEvolution: true,
+      ...options,
+      database: options.database || db.options.database,
+      engine: options.engine || { engine: 'MergeTree' },
+    };
+  }
+
+  protected get qualifiedName(): string {
+    return quoteIdentifier(this.options.database) + '.' + quoteIdentifier(this.options.tableName);
+  }
+
+  private interval(value: string): string {
+    if (!/^[1-9][0-9]* (SECOND|MINUTE|HOUR|DAY|WEEK|MONTH|QUARTER|YEAR)$/i.test(value)) {
+      throw new RangeError('An interval must be a positive integer and a supported unit.');
+    }
+    return value;
+  }
+
+  // ---- SCHEMA MANAGEMENT ----
+
+  /**
+   * Creates the table if it doesn't exist and refreshes column metadata
+   */
+  public async setup(): Promise<void> {
+    const { database, tableName, engine, orderBy, partitionBy, primaryKey, ttl, retainDataForDays, columns } = this.options;
+
+    // Build column definitions
+    let columnDefs: string;
+    if (columns && columns.length > 0) {
+      columnDefs = columns.map((col) => {
+        let def = `${quoteIdentifier(col.name)} ${col.type}`;
+        if (col.defaultExpression) def += ` DEFAULT ${col.defaultExpression}`;
+        if (col.codec) def += ` CODEC(${col.codec})`;
+        return def;
+      }).join(',\n          ');
+    } else {
+      // Default minimal schema — downstream code can add columns via auto-schema evolution
+      columnDefs = `timestamp DateTime64(3, 'Europe/Berlin'),\n          message String`;
+    }
+
+    // Build engine clause
+    if (!['MergeTree', 'ReplacingMergeTree', 'SummingMergeTree', 'AggregatingMergeTree',
+      'CollapsingMergeTree', 'VersionedCollapsingMergeTree'].includes(engine.engine)) {
+      throw new RangeError('Unsupported table engine.');
+    }
+    let engineClause: string = engine.engine;
+    if (engine.engine === 'ReplacingMergeTree' && engine.versionColumn) {
+      engineClause = `ReplacingMergeTree(${quoteIdentifier(engine.versionColumn)})`;
+    } else if (engine.engine === 'CollapsingMergeTree' && engine.signColumn) {
+      engineClause = `CollapsingMergeTree(${quoteIdentifier(engine.signColumn)})`;
+    } else if (engine.engine === 'VersionedCollapsingMergeTree' && engine.signColumn && engine.versionColumn) {
+      engineClause = `VersionedCollapsingMergeTree(${quoteIdentifier(engine.signColumn)}, ${quoteIdentifier(engine.versionColumn)})`;
+    } else {
+      engineClause = `${engine.engine}()`;
+    }
+
+    // Build ORDER BY
+    const orderByStr = Array.isArray(orderBy) ? orderBy.map(quoteIdentifier).join(', ') : quoteIdentifier(orderBy);
+
+    let createSQL = `
+      CREATE TABLE IF NOT EXISTS ${this.qualifiedName} (
+          ${columnDefs}
+      ) ENGINE = ${engineClause}`;
+
+    if (partitionBy) {
+      createSQL += `\n      PARTITION BY ${partitionBy}`;
+    }
+
+    createSQL += `\n      ORDER BY (${orderByStr})`;
+
+    if (primaryKey) {
+      const primaryKeyStr = Array.isArray(primaryKey) ? primaryKey.map(quoteIdentifier).join(', ') : quoteIdentifier(primaryKey);
+      createSQL += `\n      PRIMARY KEY (${primaryKeyStr})`;
+    }
+
+    await this.db.clickhouseHttpClient.queryPromise(createSQL);
+
+    // Apply TTL if configured
+    if (ttl) {
+      await this.db.clickhouseHttpClient.queryPromise(`
+        ALTER TABLE ${this.qualifiedName}
+        MODIFY TTL toDateTime(${quoteIdentifier(String(ttl.column))}) + INTERVAL ${this.interval(ttl.interval)}
+      `);
+    } else if (retainDataForDays && retainDataForDays > 0) {
+      // Legacy shorthand
+      await this.db.clickhouseHttpClient.queryPromise(`
+        ALTER TABLE ${this.qualifiedName}
+        MODIFY TTL toDateTime(timestamp) + INTERVAL ${this.interval(retainDataForDays + ' DAY')}
+      `);
+    }
+
+    await this.updateColumns();
+  }
+
+  /**
+   * Refresh column metadata from system.columns
+   */
+  public async updateColumns(): Promise<IColumnInfo[]> {
+    this.columns = await this.db.clickhouseHttpClient.queryPromise(`
+      SELECT * FROM system.columns
+      WHERE database = {database:String}
+      AND table = {table:String}
+    `, { database: this.options.database, table: this.options.tableName });
+    return this.columns;
+  }
+
+  /**
+   * Auto-schema evolution: detect new columns from data and add them
+   */
+  public async syncSchema(data: Record<string, any>): Promise<void> {
+    const flatData = plugins.smartobject.toFlatObject(data);
+    for (const key of Object.keys(flatData)) {
+      if (key === 'timestamp') continue;
+      const value = flatData[key];
+      const clickhouseType = detectClickhouseType(value);
+      if (!clickhouseType) continue;
+      await this.ensureColumn(key, clickhouseType);
+    }
+  }
+
+  // ---- INSERT ----
+
+  /**
+   * Insert a single row
+   */
+  public async insert(data: Partial<T>): Promise<void> {
+
+    const storageDoc = await this.prepareDocument(data);
+    await this.executeInsert([storageDoc]);
+  }
+
+  /**
+   * Insert multiple rows
+   */
+  public async insertMany(data: Partial<T>[]): Promise<void> {
+    if (data.length === 0) return;
+
+    // Schema sync across all documents
+    if (this.options.autoSchemaEvolution) {
+      const allKeys = new Set<string>();
+      const sampleValues: Record<string, any> = {};
+      for (const doc of data) {
+        const flat = plugins.smartobject.toFlatObject(doc);
+        for (const [key, value] of Object.entries(flat)) {
+          if (!allKeys.has(key)) {
+            allKeys.add(key);
+            sampleValues[key] = value;
+          }
+        }
+      }
+      await this.syncSchema(sampleValues);
+    }
+
+    const storageDocs = data.map((doc) => this.flattenDocument(doc));
+    await this.executeInsert(storageDocs);
+  }
+
+  /**
+   * Insert in batches of configurable size
+   */
+  public async insertBatch(data: Partial<T>[], options?: { batchSize?: number }): Promise<void> {
+    const size = options?.batchSize ?? 500;
+    if (!Number.isSafeInteger(size) || size < 1) throw new RangeError('batchSize must be positive.');
+    for (let offset = 0; offset < data.length; offset += size) {
+      await this.insertMany(data.slice(offset, offset + size));
+    }
+  }
+
+  /** Await write() for backpressure and close() for the final acknowledged flush. */
+  public createInsertStream(options: IMetricWriterOptions = {}): MetricWriter<Partial<T>> {
+    return this.db.ownWriter(new MetricWriter<Partial<T>>(rows => this.insertMany(rows), options));
+  }
+
+  // ---- QUERY ----
+
+  /**
+   * Returns a fluent query builder for this table
+   */
+  public query(): ClickhouseQueryBuilder<T> {
+    return new ClickhouseQueryBuilder<T>(
+      this.options.tableName,
+      this.options.database,
+      this.db.clickhouseHttpClient,
+    );
+  }
+
+  // ---- UPDATE ----
+
+  /**
+   * Update rows matching a where condition (ClickHouse mutation - use sparingly)
+   */
+  public async update(
+    set: Partial<T>,
+    whereFn: (q: ClickhouseQueryBuilder<T>) => ClickhouseQueryBuilder<T>,
+  ): Promise<void> {
+    const qb = whereFn(new ClickhouseQueryBuilder<T>(this.options.tableName, this.options.database, this.db.clickhouseHttpClient));
+    const whereClause = qb.buildWhereClause();
+    if (!whereClause) {
+      throw new Error('UPDATE requires a WHERE clause. Use a where condition to target specific rows.');
+    }
+
+    const setClauses = Object.entries(set)
+      .map(([key, value]) => `${quoteIdentifier(key)} = ${qb.bind(value)}`)
+      .join(', ');
+
+    await this.db.clickhouseHttpClient.mutatePromise(
+      `ALTER TABLE ${this.qualifiedName} UPDATE ${setClauses} WHERE ${whereClause}`, qb.parameters
+    );
+    await this.waitForMutations();
+  }
+
+  // ---- DELETE ----
+
+  /**
+   * Delete rows matching a where condition (ClickHouse mutation)
+   */
+  public async deleteWhere(
+    whereFn: (q: ClickhouseQueryBuilder<T>) => ClickhouseQueryBuilder<T>,
+  ): Promise<void> {
+    const qb = whereFn(new ClickhouseQueryBuilder<T>(this.options.tableName, this.options.database, this.db.clickhouseHttpClient));
+    const whereClause = qb.buildWhereClause();
+    if (!whereClause) {
+      throw new Error('DELETE requires a WHERE clause.');
+    }
+
+    await this.db.clickhouseHttpClient.mutatePromise(
+      `ALTER TABLE ${this.qualifiedName} DELETE WHERE ${whereClause}`, qb.parameters
+    );
+    await this.waitForMutations();
+  }
+
+  /**
+   * Delete entries older than a given interval on a column
+   */
+  public async deleteOlderThan(column: keyof T & string, interval: string): Promise<void> {
+    await this.db.clickhouseHttpClient.mutatePromise(
+      `ALTER TABLE ${this.qualifiedName} DELETE WHERE ${quoteIdentifier(String(column))} < now() - INTERVAL ${this.interval(interval)}`
+    );
+    await this.waitForMutations();
+  }
+
+  /**
+   * Drop the entire table
+   */
+  public async drop(): Promise<void> {
+    await this.db.clickhouseHttpClient.queryPromise(
+      `DROP TABLE IF EXISTS ${this.qualifiedName}`
+    );
+    this.columns = [];
+  }
+
+  // ---- UTILITIES ----
+
+  /**
+   * Wait for all pending mutations on this table to complete
+   */
+  public async waitForMutations(options: IOperationOptions = {}): Promise<void> {
+    const operation = new Operation(options, this.db.options.timeoutMs);
+    try {
+      while (true) {
+        operation.check();
+        const rows = await this.db.clickhouseHttpClient.queryPromise(
+          'SELECT count() AS cnt FROM system.mutations WHERE is_done = 0 AND database = {database:String} AND table = {table:String}',
+          { database: this.options.database, table: this.options.tableName }, { signal: operation.signal });
+        if (BigInt(rows[0]?.cnt ?? 0) === 0n) return;
+        await plugins.smartdelay.delayFor(100);
+      }
+    } finally { operation.dispose(); }
+  }
+
+  /**
+   * Get the total row count
+   */
+  public async getRowCount(): Promise<number> {
+    const result = await this.db.clickhouseHttpClient.queryPromise(`
+      SELECT count() AS cnt FROM ${this.qualifiedName} FORMAT JSONEachRow
+    `);
+    const count = Number(result[0]?.cnt ?? 0);
+    if (!Number.isSafeInteger(count)) throw new RangeError('Count exceeds a safe JavaScript integer.');
+    return count;
+  }
+
+  /**
+   * Optimize table (useful for ReplacingMergeTree deduplication)
+   */
+  public async optimize(final: boolean = false): Promise<void> {
+    const finalClause = final ? ' FINAL' : '';
+    await this.db.clickhouseHttpClient.queryPromise(
+      `OPTIMIZE TABLE ${this.qualifiedName}${finalClause}`
+    );
+  }
+
+  // ---- OBSERVATION ----
+
+  /**
+   * Watch for new entries via polling. Returns an RxJS Observable.
+   */
+  public watch(_options?: { pollInterval?: number }): plugins.smartrx.rxjs.Observable<T> {
+    return new plugins.smartrx.rxjs.Observable<T>(observer => observer.error(
+      new LosslessClientError('unsupported_capability',
+        'Timestamp polling cannot guarantee delivery of equal-timestamp or late rows. Use an explicit stable ingestion cursor before enabling a watch.')));
+  }
+
+  // ---- PRIVATE HELPERS ----
+  private async ensureColumn(name: string, type: TClickhouseColumnType): Promise<void> {
+    if (this.columns.some(column => column.name === name)) return;
+    await this.db.clickhouseHttpClient.queryPromise(
+      `ALTER TABLE ${this.qualifiedName} ADD COLUMN IF NOT EXISTS ${quoteIdentifier(name)} ${type}`);
+    await this.updateColumns();
+  }
+
+  private flattenDocument(data: Partial<T>): Record<string, any> {
+    const flat = plugins.smartobject.toFlatObject(data);
+    const storageDoc: Record<string, any> = {};
+    for (const [key, value] of Object.entries(flat)) {
+      const type = detectClickhouseType(value);
+      if (type || key === 'timestamp') {
+        storageDoc[key] = value;
+      }
+    }
+    return storageDoc;
+  }
+
+  private async prepareDocument(data: Partial<T>): Promise<Record<string, any>> {
+    if (this.options.autoSchemaEvolution) {
+      await this.syncSchema(data as Record<string, any>);
+    }
+    return this.flattenDocument(data);
+  }
+
+  private async executeInsert(docs: Record<string, any>[]): Promise<void> {
+    await this.db.clickhouseHttpClient.insertPromise(this.options.database, this.options.tableName, docs);
+  }
+}

package/ts/sqldb/clickhouse/smartclickhouse.classes.httpclient.ts

@@ -0,0 +1,52 @@
+import { ClickHouseConnection } from '../classes.clickhouseconnection.js';
+import type { IOperationOptions } from '../../core/interfaces.js';
+import type { IQueryOptions } from '../interfaces.js';
+
+export interface IClickhouseHttpClientOptions {
+  username?: string;
+  password?: string;
+  url: string;
+  timeoutMs?: number;
+}
+
+/** Migrated public transport API, using the official streaming ClickHouse connector. */
+export class ClickhouseHttpClient {
+  public readonly connection: ClickHouseConnection;
+  private readonly ownsConnection: boolean;
+  constructor(public options: IClickhouseHttpClientOptions, connection?: ClickHouseConnection) {
+    this.ownsConnection = !connection;
+    this.connection = connection ?? new ClickHouseConnection({ ...options, backend: 'clickhouse', database: 'default' });
+  }
+  public static async createAndStart(options: IClickhouseHttpClientOptions) {
+    const instance = new ClickhouseHttpClient(options);
+    await instance.start();
+    return instance;
+  }
+  public async start(): Promise<void> { await this.connection.connect(); }
+  public async close(): Promise<void> { if (this.ownsConnection) await this.connection.close(); }
+  public async ping(options: IOperationOptions = {}): Promise<boolean> { return (await this.connection.ready(options)).ready; }
+
+  public async queryPromise(query: string, values?: Record<string, unknown>, options: IQueryOptions = {}): Promise<any[]> {
+    const sql = query.trim().replace(/\s+FORMAT\s+JSONEachRow\s*;?$/i, '');
+    if (/^(SELECT|WITH|SHOW|DESCRIBE|DESC|EXISTS|EXPLAIN)\b/i.test(sql)) {
+      return this.connection.query({ sql, values }, options);
+    }
+    await this.connection.execute({ sql, values }, options);
+    return [];
+  }
+  public async queryTyped<T>(query: string, values?: Record<string, unknown>, options: IQueryOptions = {}): Promise<T[]> {
+    return this.queryPromise(query, values, options) as Promise<T[]>;
+  }
+  public async insertPromise(database: string, table: string, documents: Record<string, unknown>[]) {
+    return this.connection.insertQualified(database, table, documents);
+  }
+  public async insertBatch(database: string, table: string, documents: Record<string, unknown>[], batchSize = 10_000) {
+    if (!Number.isSafeInteger(batchSize) || batchSize < 1) throw new RangeError('batchSize must be positive.');
+    for (let i = 0; i < documents.length; i += batchSize) {
+      await this.insertPromise(database, table, documents.slice(i, i + batchSize));
+    }
+  }
+  public async mutatePromise(query: string, values?: Record<string, unknown>, options: IOperationOptions = {}): Promise<void> {
+    await this.connection.execute({ sql: query, values }, options);
+  }
+}

package/ts/sqldb/clickhouse/smartclickhouse.classes.querybuilder.ts

@@ -0,0 +1,120 @@
+import type { ClickhouseHttpClient } from './smartclickhouse.classes.httpclient.js';
+import { ClickhouseResultSet } from './smartclickhouse.classes.resultset.js';
+import type { TComparisonOperator } from './smartclickhouse.types.js';
+import { quoteClickHouseIdentifier as quoteIdentifier } from '../interfaces.js';
+import type { IClickHouseStatement, IQueryOptions } from '../interfaces.js';
+import { LosslessClientError } from '../../core/classes.error.js';
+
+interface IWhereClause { connector: 'AND' | 'OR'; expression: string }
+
+/** Identifier methods quote names. Methods ending in Raw and having() accept trusted SQL expressions. */
+export class ClickhouseQueryBuilder<T extends Record<string, any>> {
+  private selectColumns = ['*'];
+  private whereClauses: IWhereClause[] = [];
+  private orderByClauses: string[] = [];
+  private groupByClauses: string[] = [];
+  private havingClauses: string[] = [];
+  private limitValue: number | null = null;
+  private offsetValue: number | null = null;
+  private readonly values: Record<string, unknown> = {};
+
+  constructor(private tableName: string, private database: string, private httpClient: ClickhouseHttpClient) {}
+
+  public select<K extends keyof T & string>(...columns: K[]): this {
+    this.selectColumns = columns.map(quoteIdentifier); return this;
+  }
+  public selectRaw(...expressions: string[]): this { this.selectColumns = expressions; return this; }
+  public where<K extends keyof T & string>(column: K, operator: TComparisonOperator, value: unknown): this {
+    return this.and(column, operator, value);
+  }
+  public and<K extends keyof T & string>(column: K, operator: TComparisonOperator, value: unknown): this {
+    this.whereClauses.push({ connector: 'AND', expression: this.buildCondition(column, operator, value) }); return this;
+  }
+  public or<K extends keyof T & string>(column: K, operator: TComparisonOperator, value: unknown): this {
+    this.whereClauses.push({ connector: 'OR', expression: this.buildCondition(column, operator, value) }); return this;
+  }
+  public whereRaw(expression: string): this {
+    this.whereClauses.push({ connector: 'AND', expression }); return this;
+  }
+  public orderBy(column: (keyof T & string) | string, direction: 'ASC' | 'DESC' = 'ASC'): this {
+    if (!['ASC', 'DESC'].includes(direction)) throw new RangeError('Invalid sort direction.');
+    this.orderByClauses.push(quoteIdentifier(column) + ' ' + direction); return this;
+  }
+  public groupBy<K extends keyof T & string>(...columns: K[]): this {
+    this.groupByClauses.push(...columns.map(quoteIdentifier)); return this;
+  }
+  public having(expression: string): this { this.havingClauses.push(expression); return this; }
+  public limit(count: number): this { this.validateCount(count); this.limitValue = count; return this; }
+  public offset(count: number): this { this.validateCount(count); this.offsetValue = count; return this; }
+  private validateCount(count: number): void {
+    if (!Number.isSafeInteger(count) || count < 0) throw new RangeError('Limit and offset must be nonnegative safe integers.');
+  }
+  public async execute(options: IQueryOptions = {}): Promise<ClickhouseResultSet<T>> {
+    return new ClickhouseResultSet<T>(await this.httpClient.queryTyped<T>(this.toSQL(), this.parameters, options));
+  }
+  public async first(): Promise<T | null> { this.limitValue = 1; return (await this.execute()).first(); }
+  public async count(): Promise<number> {
+    const selected = this.selectColumns;
+    this.selectColumns = ['count() as _count'];
+    let sql: string;
+    try { sql = this.toSQL(); } finally { this.selectColumns = selected; }
+    const rows = await this.httpClient.queryTyped<{ _count: string }>(sql, this.parameters);
+    const count = Number(rows[0]?._count ?? 0);
+    if (!Number.isSafeInteger(count)) throw new RangeError('Count exceeds a safe JavaScript integer; select count() as a string.');
+    return count;
+  }
+  public async toArray(options: IQueryOptions = {}): Promise<T[]> { return (await this.execute(options)).toArray(); }
+  /** SQL contains typed placeholders. Pass parameters alongside it, or use toStatement(). */
+  public toSQL(): string {
+    const parts = ['SELECT ' + this.selectColumns.join(', '), 'FROM ' + quoteIdentifier(this.database) + '.' + quoteIdentifier(this.tableName)];
+    const where = this.buildWhereClause();
+    if (where) parts.push('WHERE ' + where);
+    if (this.groupByClauses.length) parts.push('GROUP BY ' + this.groupByClauses.join(', '));
+    if (this.havingClauses.length) parts.push('HAVING ' + this.havingClauses.join(' AND '));
+    if (this.orderByClauses.length) parts.push('ORDER BY ' + this.orderByClauses.join(', '));
+    if (this.limitValue !== null) parts.push('LIMIT ' + this.limitValue);
+    if (this.offsetValue !== null) parts.push('OFFSET ' + this.offsetValue);
+    return parts.join(' ');
+  }
+  public get parameters(): Record<string, unknown> { return { ...this.values }; }
+  public toStatement(): IClickHouseStatement { return { sql: this.toSQL(), values: this.parameters }; }
+  public buildWhereClause(): string {
+    return this.whereClauses.map((clause, index) => (index ? clause.connector + ' ' : '') + '(' + clause.expression + ')').join(' ');
+  }
+  /** Bind a scalar for table mutations as well as predicates. */
+  public bind(value: unknown): string {
+    let type: string;
+    if (value === null) type = 'Nullable(String)';
+    else if (typeof value === 'string') type = 'String';
+    else if (typeof value === 'boolean') type = 'Bool';
+    else if (typeof value === 'bigint') {
+      if (value < -(2n ** 255n) || value >= 2n ** 255n) throw new RangeError('Integer exceeds Int256.');
+      type = 'Int256'; value = value.toString();
+    } else if (typeof value === 'number' && Number.isFinite(value)) {
+      if (Number.isInteger(value) && !Number.isSafeInteger(value)) throw new RangeError('Use bigint for large integers.');
+      type = Number.isInteger(value) ? 'Int64' : 'Float64';
+    } else if (value instanceof Date && Number.isFinite(value.getTime())) {
+      type = "DateTime64(3, 'UTC')"; value = value.toISOString().replace('T', ' ').replace('Z', '');
+    } else throw new LosslessClientError('invalid_argument', 'Use a supported scalar query parameter.');
+    const key = 'p' + Object.keys(this.values).length;
+    this.values[key] = value;
+    return '{' + key + ':' + type + '}';
+  }
+  private buildCondition(column: string, operator: TComparisonOperator, value: unknown): string {
+    const name = quoteIdentifier(column);
+    if (!['=', '!=', '>', '>=', '<', '<=', 'LIKE', 'NOT LIKE', 'IN', 'NOT IN', 'BETWEEN'].includes(operator)) {
+      throw new RangeError('Invalid comparison operator.');
+    }
+    if (value === null && (operator === '=' || operator === '!=')) return name + (operator === '=' ? ' IS NULL' : ' IS NOT NULL');
+    if (operator === 'IN' || operator === 'NOT IN') {
+      if (!Array.isArray(value)) throw new RangeError('IN requires an array.');
+      if (!value.length) return operator === 'IN' ? '0' : '1';
+      return name + ' ' + operator + ' (' + value.map(item => this.bind(item)).join(', ') + ')';
+    }
+    if (operator === 'BETWEEN') {
+      if (!Array.isArray(value) || value.length !== 2) throw new RangeError('BETWEEN requires two values.');
+      return name + ' BETWEEN ' + this.bind(value[0]) + ' AND ' + this.bind(value[1]);
+    }
+    return name + ' ' + operator + ' ' + this.bind(value);
+  }
+}

package/ts/sqldb/clickhouse/smartclickhouse.classes.resultset.ts

@@ -0,0 +1,44 @@
+import * as plugins from './smartclickhouse.plugins.js';
+
+export class ClickhouseResultSet<T> {
+  public rows: T[];
+  public rowCount: number;
+
+  constructor(rows: T[]) {
+    this.rows = rows;
+    this.rowCount = rows.length;
+  }
+
+  public first(): T | null {
+    return this.rows[0] ?? null;
+  }
+
+  public last(): T | null {
+    return this.rows[this.rows.length - 1] ?? null;
+  }
+
+  public isEmpty(): boolean {
+    return this.rows.length === 0;
+  }
+
+  public toArray(): T[] {
+    return this.rows;
+  }
+
+  public map<U>(fn: (row: T) => U): U[] {
+    return this.rows.map(fn);
+  }
+
+  public filter(fn: (row: T) => boolean): ClickhouseResultSet<T> {
+    return new ClickhouseResultSet<T>(this.rows.filter(fn));
+  }
+
+  public toObservable(): plugins.smartrx.rxjs.Observable<T> {
+    return new plugins.smartrx.rxjs.Observable<T>((observer) => {
+      for (const row of this.rows) {
+        observer.next(row);
+      }
+      observer.complete();
+    });
+  }
+}