@hypequery/clickhouse 1.3.1-beta.0 → 1.3.2

package/dist/core/query-builder.js

@@ -8,26 +8,23 @@ import { ExecutorFeature } from './features/executor.js';
 import { QueryModifiersFeature } from './features/query-modifiers.js';
 import { FilterValidator } from './validators/filter-validator.js';
 import { PaginationFeature } from './features/pagination.js';
+import { createPredicateBuilder, } from './utils/predicate-builder.js';
 import { CrossFilteringFeature } from './features/cross-filtering.js';
 /**
  * Type guard to check if a config is a client-based configuration.
  */
 export function isClientConfig(config) {
-    return 'client' in config && !('host' in config);
+    return 'client' in config && config.client !== undefined;
 }
 /**
  * A type-safe query builder for ClickHouse databases.
- * @template Schema - The full database schema
- * @template T - The schema type of the current table
- * @template HasSelect - Whether a SELECT clause has been applied
- * @template Aggregations - The type of any aggregation functions applied
+ * The builder carries a single state object that encodes scope, output, and schema metadata.
  */
 export class QueryBuilder {
     static relationships;
     config = {};
     tableName;
-    schema;
-    originalSchema;
+    state;
     formatter = new SQLFormatter();
     aggregations;
     joins;
@@ -37,10 +34,9 @@ export class QueryBuilder {
     modifiers;
     pagination;
     crossFiltering;
-    constructor(tableName, schema, originalSchema) {
+    constructor(tableName, state) {
         this.tableName = tableName;
-        this.schema = schema;
-        this.originalSchema = originalSchema;
+        this.state = state;
         this.aggregations = new AggregationFeature(this);
         this.joins = new JoinFeature(this);
         this.filtering = new FilteringFeature(this);
@@ -50,28 +46,18 @@ export class QueryBuilder {
         this.pagination = new PaginationFeature(this);
         this.crossFiltering = new CrossFilteringFeature(this);
     }
+    fork(state, config) {
+        const builder = new QueryBuilder(this.tableName, state);
+        builder.config = { ...config };
+        return builder;
+    }
     debug() {
         console.log('Current Type:', {
-            schema: this.schema,
-            originalSchema: this.originalSchema,
+            state: this.state,
             config: this.config
         });
         return this;
     }
-    clone() {
-        const newBuilder = new QueryBuilder(this.tableName, this.schema, this.originalSchema);
-        newBuilder.config = { ...this.config };
-        // Initialize features with the new builder
-        newBuilder.aggregations = new AggregationFeature(newBuilder);
-        newBuilder.joins = new JoinFeature(newBuilder);
-        newBuilder.filtering = new FilteringFeature(newBuilder);
-        newBuilder.analytics = new AnalyticsFeature(newBuilder);
-        newBuilder.executor = new ExecutorFeature(newBuilder);
-        newBuilder.modifiers = new QueryModifiersFeature(newBuilder);
-        newBuilder.pagination = new PaginationFeature(newBuilder);
-        newBuilder.crossFiltering = new CrossFilteringFeature(newBuilder);
-        return newBuilder;
-    }
     // --- Analytics Helper: Add a CTE.
     withCTE(alias, subquery) {
         this.config = this.analytics.addCTE(alias, subquery);
@@ -90,7 +76,7 @@ export class QueryBuilder {
    * @returns The current QueryBuilder instance.
    */
     groupByTimeInterval(column, interval, method = 'toStartOfInterval') {
-        this.config = this.analytics.addTimeInterval(column, interval, method);
+        this.config = this.analytics.addTimeInterval(String(column), interval, method);
         return this;
     }
     // --- Analytics Helper: Add a raw SQL fragment.
@@ -116,23 +102,34 @@ export class QueryBuilder {
         this.config = this.crossFiltering.applyCrossFilters(crossFilter);
         return this;
     }
-    // Implementation
-    select(columns) {
-        // Create a new builder with the appropriate type parameters
-        const newBuilder = new QueryBuilder(this.tableName, {
-            name: this.schema.name,
-            columns: this.schema.columns
-        }, this.originalSchema);
-        // Handle both string and array cases
-        const processedColumns = typeof columns === 'string'
-            ? [columns]
-            : columns.map((col) => {
-                if (typeof col === 'object' && col !== null && '__type' in col) {
-                    return col.toSql();
-                }
-                return String(col);
-            });
-        newBuilder.config = {
+    select(columnsOrAsterisk) {
+        if (columnsOrAsterisk === '*') {
+            const nextState = {
+                ...this.state,
+                output: {}
+            };
+            const nextConfig = {
+                ...this.config,
+                select: ['*'],
+                orderBy: this.config.orderBy?.map(({ column, direction }) => ({
+                    column: String(column),
+                    direction
+                }))
+            };
+            return this.fork(nextState, nextConfig);
+        }
+        const columns = columnsOrAsterisk;
+        const processedColumns = columns.map(col => {
+            if (typeof col === 'object' && col !== null && '__type' in col) {
+                return col.toSql();
+            }
+            return String(col);
+        });
+        const nextState = {
+            ...this.state,
+            output: {}
+        };
+        const nextConfig = {
             ...this.config,
             select: processedColumns,
             orderBy: this.config.orderBy?.map(({ column, direction }) => ({
@@ -140,32 +137,35 @@ export class QueryBuilder {
                 direction
             }))
         };
-        return newBuilder;
+        return this.fork(nextState, nextConfig);
+    }
+    selectConst(...columns) {
+        return this.select(columns);
     }
     sum(column, alias) {
-        const newBuilder = this.clone();
-        newBuilder.config = this.aggregations.sum(column, alias);
-        return newBuilder;
+        return this.applyAggregation(column, alias, 'sum', (col, finalAlias) => this.aggregations.sum(col, finalAlias));
     }
     count(column, alias) {
-        const newBuilder = this.clone();
-        newBuilder.config = this.aggregations.count(column, alias);
-        return newBuilder;
+        return this.applyAggregation(column, alias, 'count', (col, finalAlias) => this.aggregations.count(col, finalAlias));
     }
     avg(column, alias) {
-        const newBuilder = this.clone();
-        newBuilder.config = this.aggregations.avg(column, alias);
-        return newBuilder;
+        return this.applyAggregation(column, alias, 'avg', (col, finalAlias) => this.aggregations.avg(col, finalAlias));
     }
     min(column, alias) {
-        const newBuilder = this.clone();
-        newBuilder.config = this.aggregations.min(column, alias);
-        return newBuilder;
+        return this.applyAggregation(column, alias, 'min', (col, finalAlias) => this.aggregations.min(col, finalAlias));
     }
     max(column, alias) {
-        const newBuilder = this.clone();
-        newBuilder.config = this.aggregations.max(column, alias);
-        return newBuilder;
+        return this.applyAggregation(column, alias, 'max', (col, finalAlias) => this.aggregations.max(col, finalAlias));
+    }
+    applyAggregation(column, alias, suffix, updater) {
+        const columnName = String(column);
+        const finalAlias = (alias || `${columnName}_${suffix}`);
+        const nextState = {
+            ...this.state,
+            output: {}
+        };
+        const nextConfig = updater(columnName, finalAlias);
+        return this.fork(nextState, nextConfig);
     }
     // Make needed properties accessible to features
     getTableName() {
@@ -223,39 +223,52 @@ export class QueryBuilder {
         if (advancedInOperators.includes(operator)) {
             return;
         }
-        if (FilterValidator.validateJoinedColumn(String(column)))
+        const columnName = String(column);
+        if (FilterValidator.validateJoinedColumn(columnName))
             return;
-        const columnType = this.schema.columns[column];
-        FilterValidator.validateFilterCondition({ column: String(column), operator, value }, columnType);
+        const baseColumns = this.state.base;
+        const columnType = baseColumns[columnName];
+        FilterValidator.validateFilterCondition({ column: columnName, operator, value }, columnType);
     }
     where(columnOrColumns, operator, value) {
+        if (typeof columnOrColumns === 'function') {
+            const expression = columnOrColumns(createPredicateBuilder());
+            this.config = this.filtering.addExpressionCondition('AND', expression);
+            return this;
+        }
+        if (operator === undefined) {
+            throw new Error('Operator is required when specifying a column for where()');
+        }
         // Handle tuple operations
         if (Array.isArray(columnOrColumns) && (operator === 'inTuple' || operator === 'globalInTuple')) {
-            // For tuple operations, we need to handle the column array specially
             const columns = columnOrColumns;
             this.validateFilterValue(columns, operator, value);
-            this.config = this.filtering.addCondition('AND', columns, operator, value);
+            this.config = this.filtering.addCondition('AND', columns.map(String), operator, value);
             return this;
         }
-        // Handle regular operations
         const column = columnOrColumns;
         this.validateFilterValue(column, operator, value);
-        this.config = this.filtering.addCondition('AND', column, operator, value);
+        this.config = this.filtering.addCondition('AND', String(column), operator, value);
         return this;
     }
     orWhere(columnOrColumns, operator, value) {
-        // Handle tuple operations
+        if (typeof columnOrColumns === 'function') {
+            const expression = columnOrColumns(createPredicateBuilder());
+            this.config = this.filtering.addExpressionCondition('OR', expression);
+            return this;
+        }
+        if (operator === undefined) {
+            throw new Error('Operator is required when specifying a column for orWhere()');
+        }
         if (Array.isArray(columnOrColumns) && (operator === 'inTuple' || operator === 'globalInTuple')) {
-            // For tuple operations, we need to handle the column array specially
             const columns = columnOrColumns;
             this.validateFilterValue(columns, operator, value);
-            this.config = this.filtering.addCondition('OR', columns, operator, value);
+            this.config = this.filtering.addCondition('OR', columns.map(String), operator, value);
             return this;
         }
-        // Handle regular operations
         const column = columnOrColumns;
         this.validateFilterValue(column, operator, value);
-        this.config = this.filtering.addCondition('OR', column, operator, value);
+        this.config = this.filtering.addCondition('OR', String(column), operator, value);
         return this;
     }
     /**
@@ -302,7 +315,8 @@ export class QueryBuilder {
      * ```
      */
     groupBy(columns) {
-        this.config = this.modifiers.addGroupBy(columns);
+        const normalized = Array.isArray(columns) ? columns.map(String) : String(columns);
+        this.config = this.modifiers.addGroupBy(normalized);
         return this;
     }
     limit(count) {
@@ -324,7 +338,7 @@ export class QueryBuilder {
      * ```
      */
     orderBy(column, direction = 'ASC') {
-        this.config = this.modifiers.addOrderBy(column, direction);
+        this.config = this.modifiers.addOrderBy(String(column), direction);
         return this;
     }
     /**
@@ -351,24 +365,24 @@ export class QueryBuilder {
         return this.where(column, 'between', [min, max]);
     }
     innerJoin(table, leftColumn, rightColumn, alias) {
-        const newBuilder = this.clone();
-        newBuilder.config = this.joins.addJoin('INNER', table, leftColumn, rightColumn, alias);
-        return newBuilder;
+        return this.applyJoin('INNER', table, leftColumn, rightColumn, alias);
     }
     leftJoin(table, leftColumn, rightColumn, alias) {
-        const newBuilder = this.clone();
-        newBuilder.config = this.joins.addJoin('LEFT', table, leftColumn, rightColumn, alias);
-        return newBuilder;
+        return this.applyJoin('LEFT', table, leftColumn, rightColumn, alias);
     }
     rightJoin(table, leftColumn, rightColumn, alias) {
-        const newBuilder = this.clone();
-        newBuilder.config = this.joins.addJoin('RIGHT', table, leftColumn, rightColumn, alias);
-        return newBuilder;
+        return this.applyJoin('RIGHT', table, leftColumn, rightColumn, alias);
     }
     fullJoin(table, leftColumn, rightColumn, alias) {
-        const newBuilder = this.clone();
-        newBuilder.config = this.joins.addJoin('FULL', table, leftColumn, rightColumn, alias);
-        return newBuilder;
+        return this.applyJoin('FULL', table, leftColumn, rightColumn, alias);
+    }
+    applyJoin(type, table, leftColumn, rightColumn, alias) {
+        const nextState = {
+            ...this.state,
+            aliases: alias ? { ...this.state.aliases, [alias]: table } : this.state.aliases
+        };
+        const nextConfig = this.joins.addJoin(type, table, String(leftColumn), rightColumn, alias);
+        return this.fork(nextState, nextConfig);
     }
     // Make config accessible to features
     getConfig() {
@@ -412,7 +426,8 @@ export class QueryBuilder {
                 const type = options?.type || joinPath.type || 'INNER';
                 const alias = options?.alias || joinPath.alias;
                 const table = String(joinPath.to);
-                this.config = this.joins.addJoin(type, table, joinPath.leftColumn, `${table}.${joinPath.rightColumn}`, alias);
+                const rightColumn = `${table}.${joinPath.rightColumn}`;
+                this.config = this.joins.addJoin(type, table, joinPath.leftColumn, rightColumn, alias);
             });
         }
         else {
@@ -420,7 +435,8 @@ export class QueryBuilder {
             const type = options?.type || path.type || 'INNER';
             const alias = options?.alias || path.alias;
             const table = String(path.to);
-            this.config = this.joins.addJoin(type, table, path.leftColumn, `${table}.${path.rightColumn}`, alias);
+            const rightColumn = `${table}.${path.rightColumn}`;
+            this.config = this.joins.addJoin(type, table, path.leftColumn, rightColumn, alias);
         }
         return this;
     }
@@ -429,10 +445,15 @@ export function createQueryBuilder(config) {
     ClickHouseConnection.initialize(config);
     return {
         table(tableName) {
-            return new QueryBuilder(tableName, {
-                name: tableName,
-                columns: {}
-            }, {});
+            const state = {
+                schema: {},
+                tables: tableName,
+                output: {},
+                baseTable: tableName,
+                base: {},
+                aliases: {}
+            };
+            return new QueryBuilder(tableName, state);
         }
     };
 }

package/dist/core/tests/integration/setup.d.ts

@@ -1,5 +1,5 @@
 export declare const initializeTestConnection: () => Promise<{
-    table<TableName extends never>(tableName: TableName): import("../../query-builder.js").QueryBuilder<{}, {}[TableName], false, {}, {}[TableName]>;
+    table<TableName extends never>(tableName: TableName): import("../../query-builder.js").SelectQB<import("../../types/builder-state.js").SchemaDefinition<unknown>, TableName, import("../../../index.js").TableRecord<import("../../types/builder-state.js").SchemaDefinition<unknown>[TableName]>, TableName>;
 }>;
 export declare const ensureConnectionInitialized: () => import("@clickhouse/client").ClickHouseClient | import("@clickhouse/client-web").ClickHouseClient;
 export declare const isDockerAvailable: () => Promise<boolean>;

package/dist/core/tests/test-utils.d.ts

@@ -1,4 +1,5 @@
-import { QueryBuilder } from '../query-builder.js';
+import { SelectQB } from '../query-builder.js';
+import type { TableRecord } from '../../types/schema.js';
 export type TestTableSchema = {
     id: 'Int32';
     name: 'String';
@@ -38,6 +39,6 @@ export interface TestSchema {
     users: UsersSchema;
 }
 export declare const TEST_SCHEMAS: TestSchema;
-export declare function setupUsersBuilder(): QueryBuilder<TestSchema, TestSchema['users'], false, {}, TestSchema['users']>;
-export declare function setupTestBuilder(): QueryBuilder<TestSchema, TestSchema['test_table'], false, {}, TestSchema['test_table']>;
+export declare function setupUsersBuilder(): SelectQB<TestSchema, 'users', TableRecord<TestSchema['users']>, 'users'>;
+export declare function setupTestBuilder(): SelectQB<TestSchema, 'test_table', TableRecord<TestSchema['test_table']>, 'test_table'>;
 //# sourceMappingURL=test-utils.d.ts.map

package/dist/core/tests/test-utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"test-utils.d.ts","sourceRoot":"","sources":["../../../src/core/tests/test-utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAEnD,MAAM,MAAM,eAAe,GAAG;IAC5B,EAAE,EAAE,OAAO,CAAC;IACZ,IAAI,EAAE,QAAQ,CAAC;IACf,KAAK,EAAE,SAAS,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,QAAQ,CAAC;IACnB,MAAM,EAAE,OAAO,CAAC;IAChB,UAAU,EAAE,OAAO,CAAC;IACpB,UAAU,EAAE,OAAO,CAAC;IACpB,MAAM,EAAE,QAAQ,CAAC;IACjB,KAAK,EAAE,QAAQ,CAAC;IAChB,KAAK,EAAE,OAAO,CAAC;IACf,QAAQ,EAAE,QAAQ,CAAC;IAEnB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,qBAAqB,CAAC;IAChC,IAAI,EAAE,eAAe,CAAC;IACtB,QAAQ,EAAE,qCAAqC,CAAC;IAChD,aAAa,EAAE,kBAAkB,CAAC;IAClC,UAAU,EAAE,+BAA+B,CAAC;IAC5C,aAAa,EAAE,4CAA4C,CAAC;IAC5D,aAAa,EAAE,yBAAyB,CAAC;IACzC,WAAW,EAAE,4BAA4B,CAAC;IAC1C,iBAAiB,EAAE,eAAe,CAAC;CACpC,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG;IACxB,EAAE,EAAE,OAAO,CAAC;IACZ,SAAS,EAAE,QAAQ,CAAC;IACpB,KAAK,EAAE,QAAQ,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IAEnB,OAAO,EAAE,qBAAqB,CAAC;IAC/B,WAAW,EAAE,+CAA+C,CAAC;IAC7D,KAAK,EAAE,+BAA+B,CAAC;IACvC,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,MAAM,WAAW,UAAU;IACzB,UAAU,EAAE,eAAe,CAAC;IAC5B,KAAK,EAAE,WAAW,CAAC;CACpB;AAED,eAAO,MAAM,YAAY,EAAE,UAmC1B,CAAC;AAGF,wBAAgB,iBAAiB,IAAI,YAAY,CAAC,UAAU,EAAE,UAAU,CAAC,OAAO,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE,UAAU,CAAC,OAAO,CAAC,CAAC,CASjH;AAED,wBAAgB,gBAAgB,IAAI,YAAY,CAAC,UAAU,EAAE,UAAU,CAAC,YAAY,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE,UAAU,CAAC,YAAY,CAAC,CAAC,CAS1H"}
+{"version":3,"file":"test-utils.d.ts","sourceRoot":"","sources":["../../../src/core/tests/test-utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAE7D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAEzD,MAAM,MAAM,eAAe,GAAG;IAC5B,EAAE,EAAE,OAAO,CAAC;IACZ,IAAI,EAAE,QAAQ,CAAC;IACf,KAAK,EAAE,SAAS,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,QAAQ,CAAC;IACnB,MAAM,EAAE,OAAO,CAAC;IAChB,UAAU,EAAE,OAAO,CAAC;IACpB,UAAU,EAAE,OAAO,CAAC;IACpB,MAAM,EAAE,QAAQ,CAAC;IACjB,KAAK,EAAE,QAAQ,CAAC;IAChB,KAAK,EAAE,OAAO,CAAC;IACf,QAAQ,EAAE,QAAQ,CAAC;IAEnB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,qBAAqB,CAAC;IAChC,IAAI,EAAE,eAAe,CAAC;IACtB,QAAQ,EAAE,qCAAqC,CAAC;IAChD,aAAa,EAAE,kBAAkB,CAAC;IAClC,UAAU,EAAE,+BAA+B,CAAC;IAC5C,aAAa,EAAE,4CAA4C,CAAC;IAC5D,aAAa,EAAE,yBAAyB,CAAC;IACzC,WAAW,EAAE,4BAA4B,CAAC;IAC1C,iBAAiB,EAAE,eAAe,CAAC;CACpC,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG;IACxB,EAAE,EAAE,OAAO,CAAC;IACZ,SAAS,EAAE,QAAQ,CAAC;IACpB,KAAK,EAAE,QAAQ,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IAEnB,OAAO,EAAE,qBAAqB,CAAC;IAC/B,WAAW,EAAE,+CAA+C,CAAC;IAC7D,KAAK,EAAE,+BAA+B,CAAC;IACvC,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,MAAM,WAAW,UAAU;IACzB,UAAU,EAAE,eAAe,CAAC;IAC5B,KAAK,EAAE,WAAW,CAAC;CACpB;AAED,eAAO,MAAM,YAAY,EAAE,UAmC1B,CAAC;AAgBF,wBAAgB,iBAAiB,IAAI,QAAQ,CAAC,UAAU,EAAE,OAAO,EAAE,WAAW,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,EAAE,OAAO,CAAC,CAU5G;AAED,wBAAgB,gBAAgB,IAAI,QAAQ,CAAC,UAAU,EAAE,YAAY,EAAE,WAAW,CAAC,UAAU,CAAC,YAAY,CAAC,CAAC,EAAE,YAAY,CAAC,CAU1H"}

package/dist/core/tests/test-utils.js

@@ -36,14 +36,24 @@ export const TEST_SCHEMAS = {
     }
 };
 export function setupUsersBuilder() {
-    return new QueryBuilder('users', {
-        name: 'users',
-        columns: TEST_SCHEMAS.users
-    }, TEST_SCHEMAS);
+    const state = {
+        schema: TEST_SCHEMAS,
+        tables: 'users',
+        output: {},
+        baseTable: 'users',
+        base: TEST_SCHEMAS.users,
+        aliases: {}
+    };
+    return new QueryBuilder('users', state);
 }
 export function setupTestBuilder() {
-    return new QueryBuilder('test_table', {
-        name: 'test_table',
-        columns: TEST_SCHEMAS.test_table
-    }, TEST_SCHEMAS);
+    const state = {
+        schema: TEST_SCHEMAS,
+        tables: 'test_table',
+        output: {},
+        baseTable: 'test_table',
+        base: TEST_SCHEMAS.test_table,
+        aliases: {}
+    };
+    return new QueryBuilder('test_table', state);
 }

package/dist/core/types/builder-state.d.ts

@@ -0,0 +1,25 @@
+import type { ColumnType, InferColumnType, TableRecord } from '../../types/schema.js';
+import type { Simplify } from './type-helpers.js';
+export type SchemaDefinition<Schema extends Record<string, any> = Record<string, any>> = {
+    [K in keyof Schema]: Record<string, ColumnType>;
+};
+export type BuilderState<Schema extends SchemaDefinition<Schema>, VisibleTables extends string, OutputRow, BaseTable extends keyof Schema, Aliases extends Partial<Record<string, keyof Schema>> = {}> = {
+    schema: Schema;
+    tables: VisibleTables;
+    output: OutputRow;
+    baseTable: BaseTable;
+    base: Schema[BaseTable];
+    aliases: Aliases;
+};
+export type AnyBuilderState = BuilderState<any, any, any, any, any>;
+export type BaseRow<State extends AnyBuilderState> = Simplify<{
+    [K in keyof State['base']]: State['base'][K] extends ColumnType ? InferColumnType<State['base'][K]> : never;
+}>;
+export type WidenTables<State extends AnyBuilderState, Table extends keyof State['schema']> = BuilderState<State['schema'], State['tables'] | (Table & string), State['output'], State['baseTable'], State['aliases']>;
+export type UpdateOutput<State extends AnyBuilderState, Output> = BuilderState<State['schema'], State['tables'], Output, State['baseTable'], State['aliases']>;
+export type InitialState<Schema extends SchemaDefinition<Schema>, Table extends keyof Schema> = BuilderState<Schema, Table & string, TableRecord<Schema[Table]>, Table, {}>;
+export type ExplicitSelectionState<State extends AnyBuilderState> = BaseRow<State> extends State['output'] ? State['output'] extends BaseRow<State> ? false : true : true;
+export type AppendToOutput<State extends AnyBuilderState, Added> = UpdateOutput<State, ExplicitSelectionState<State> extends true ? Simplify<State['output'] & Added> : Simplify<Added>>;
+export type AddAlias<State extends AnyBuilderState, Alias extends string, Table extends keyof State['schema']> = BuilderState<State['schema'], State['tables'] | Alias, State['output'], State['baseTable'], State['aliases'] & Record<Alias, Table>>;
+export type ResolveTableSchema<State extends AnyBuilderState, Table extends string> = Table extends keyof State['schema'] ? State['schema'][Table] : Table extends keyof State['aliases'] ? State['schema'][State['aliases'][Table]] : never;
+//# sourceMappingURL=builder-state.d.ts.map

package/dist/core/types/builder-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"builder-state.d.ts","sourceRoot":"","sources":["../../../src/core/types/builder-state.ts"],"names":[],"mappings":"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"}

package/dist/core/types/builder-state.js

@@ -0,0 +1 @@
+export {};

package/dist/core/types/select-types.d.ts

@@ -0,0 +1,25 @@
+import type { SqlExpression, AliasedExpression } from '../utils/sql-expressions.js';
+import type { ColumnType, InferColumnType } from '../../types/schema.js';
+import type { AnyBuilderState, BaseRow, ResolveTableSchema } from './builder-state.js';
+import { Simplify, UnionToIntersection } from './type-helpers.js';
+type TableIdentifiers<State extends AnyBuilderState> = State['tables'] & string;
+type QualifiedColumnsFor<State extends AnyBuilderState, Table extends string> = ResolveTableSchema<State, Table> extends Record<string, ColumnType> ? `${Table}.${Extract<keyof ResolveTableSchema<State, Table>, string>}` : never;
+export type QualifiedColumnKeys<State extends AnyBuilderState> = {
+    [Table in TableIdentifiers<State>]: QualifiedColumnsFor<State, Table>;
+}[TableIdentifiers<State>];
+export type BaseColumnKeys<State extends AnyBuilderState> = keyof BaseRow<State>;
+export type OutputColumnKeys<State extends AnyBuilderState> = keyof State['output'];
+export type SelectableColumn<State extends AnyBuilderState> = OutputColumnKeys<State> | BaseColumnKeys<State> | QualifiedColumnKeys<State>;
+export type SelectableItem<State extends AnyBuilderState> = SelectableColumn<State> | SqlExpression;
+export type ColumnSelectionKey<P> = P extends `${string}.${infer C}` ? C : P;
+type QualifiedColumnValue<State extends AnyBuilderState, P> = P extends `${infer Table}.${infer Column}` ? ResolveTableSchema<State, Table> extends Record<string, ColumnType> ? Column extends keyof ResolveTableSchema<State, Table> ? ResolveTableSchema<State, Table>[Column] extends ColumnType ? InferColumnType<ResolveTableSchema<State, Table>[Column]> : never : never : never : never;
+export type ColumnSelectionValue<State extends AnyBuilderState, P> = P extends OutputColumnKeys<State> ? State['output'][P] : P extends BaseColumnKeys<State> ? BaseRow<State>[P] : QualifiedColumnValue<State, P>;
+export type ColumnSelectionRecord<State extends AnyBuilderState, K> = {
+    [P in Extract<K, SelectableColumn<State>> as ColumnSelectionKey<P>]: ColumnSelectionValue<State, P>;
+};
+export type ExpressionSelectionRecord<K> = UnionToIntersection<K extends AliasedExpression<infer R, infer A> ? {
+    [P in A]: R;
+} : {}>;
+export type SelectionResult<State extends AnyBuilderState, K> = Simplify<ColumnSelectionRecord<State, K> & ExpressionSelectionRecord<K>>;
+export {};
+//# sourceMappingURL=select-types.d.ts.map

package/dist/core/types/select-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"select-types.d.ts","sourceRoot":"","sources":["../../../src/core/types/select-types.ts"],"names":[],"mappings":"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"}

package/dist/core/types/select-types.js

@@ -0,0 +1 @@
+export {};

package/dist/core/types/type-helpers.d.ts

@@ -0,0 +1,5 @@
+export type UnionToIntersection<U> = (U extends any ? (k: U) => void : never) extends (k: infer I) => void ? I : never;
+export type Simplify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+//# sourceMappingURL=type-helpers.d.ts.map

package/dist/core/types/type-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"type-helpers.d.ts","sourceRoot":"","sources":["../../../src/core/types/type-helpers.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,mBAAmB,CAAC,CAAC,IAC/B,CAAC,CAAC,SAAS,GAAG,GAAG,CAAC,CAAC,EAAE,CAAC,KAAK,IAAI,GAAG,KAAK,CAAC,SAAS,CAAC,CAAC,EAAE,MAAM,CAAC,KAAK,IAAI,GAAG,CAAC,GAAG,KAAK,CAAC;AAEpF,MAAM,MAAM,QAAQ,CAAC,CAAC,IAAI;KAAG,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;CAAE,GAAG,EAAE,CAAC"}

package/dist/core/types/type-helpers.js

@@ -0,0 +1 @@
+export {};

package/dist/core/utils/predicate-builder.d.ts

@@ -0,0 +1,29 @@
+import type { AnyBuilderState, BaseRow } from '../types/builder-state.js';
+import type { SelectableColumn } from '../types/select-types.js';
+export type PredicatePrimitive = string | number | boolean | Date | null;
+type PredicateValue = Exclude<PredicatePrimitive, string>;
+export interface PredicateExpression<T = unknown> {
+    __type: 'predicate_expression';
+    sql: string;
+    parameters: any[];
+    readonly expressionType?: T | undefined;
+}
+export interface PredicateLiteral<T = PredicatePrimitive> {
+    __type: 'predicate_literal';
+    value: T;
+}
+export type ColumnReference<State extends AnyBuilderState> = keyof BaseRow<State> | keyof State['output'] | Extract<SelectableColumn<State>, string>;
+export type PredicateArg<State extends AnyBuilderState> = ColumnReference<State> | PredicateExpression | PredicateLiteral | PredicateValue | PredicatePrimitive[];
+export interface PredicateBuilder<State extends AnyBuilderState> {
+    fn<T = unknown>(name: string, ...args: Array<PredicateArg<State>>): PredicateExpression<T>;
+    col(column: ColumnReference<State>): PredicateExpression;
+    value<T extends PredicatePrimitive>(value: T): PredicateLiteral<T>;
+    literal<T extends PredicatePrimitive>(value: T): PredicateLiteral<T>;
+    array(values: Array<PredicatePrimitive | PredicateLiteral>): PredicateExpression;
+    raw(sql: string): PredicateExpression;
+    and(expressions: PredicateExpression[]): PredicateExpression<boolean>;
+    or(expressions: PredicateExpression[]): PredicateExpression<boolean>;
+}
+export declare function createPredicateBuilder<State extends AnyBuilderState>(): PredicateBuilder<State>;
+export {};
+//# sourceMappingURL=predicate-builder.d.ts.map

package/dist/core/utils/predicate-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"predicate-builder.d.ts","sourceRoot":"","sources":["../../../src/core/utils/predicate-builder.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,OAAO,EAAE,MAAM,2BAA2B,CAAC;AAC1E,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAEjE,MAAM,MAAM,kBAAkB,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,GAAG,IAAI,CAAC;AACzE,KAAK,cAAc,GAAG,OAAO,CAAC,kBAAkB,EAAE,MAAM,CAAC,CAAC;AAE1D,MAAM,WAAW,mBAAmB,CAAC,CAAC,GAAG,OAAO;IAC9C,MAAM,EAAE,sBAAsB,CAAC;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,EAAE,GAAG,EAAE,CAAC;IAClB,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC,GAAG,SAAS,CAAC;CACzC;AAED,MAAM,WAAW,gBAAgB,CAAC,CAAC,GAAG,kBAAkB;IACtD,MAAM,EAAE,mBAAmB,CAAC;IAC5B,KAAK,EAAE,CAAC,CAAC;CACV;AAED,MAAM,MAAM,eAAe,CAAC,KAAK,SAAS,eAAe,IACrD,MAAM,OAAO,CAAC,KAAK,CAAC,GACpB,MAAM,KAAK,CAAC,QAAQ,CAAC,GACrB,OAAO,CAAC,gBAAgB,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC,CAAC;AAE7C,MAAM,MAAM,YAAY,CAAC,KAAK,SAAS,eAAe,IAClD,eAAe,CAAC,KAAK,CAAC,GACtB,mBAAmB,GACnB,gBAAgB,GAChB,cAAc,GACd,kBAAkB,EAAE,CAAC;AAEzB,MAAM,WAAW,gBAAgB,CAAC,KAAK,SAAS,eAAe;IAC7D,EAAE,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,KAAK,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC,GAAG,mBAAmB,CAAC,CAAC,CAAC,CAAC;IAC3F,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC,KAAK,CAAC,GAAG,mBAAmB,CAAC;IACzD,KAAK,CAAC,CAAC,SAAS,kBAAkB,EAAE,KAAK,EAAE,CAAC,GAAG,gBAAgB,CAAC,CAAC,CAAC,CAAC;IACnE,OAAO,CAAC,CAAC,SAAS,kBAAkB,EAAE,KAAK,EAAE,CAAC,GAAG,gBAAgB,CAAC,CAAC,CAAC,CAAC;IACrE,KAAK,CAAC,MAAM,EAAE,KAAK,CAAC,kBAAkB,GAAG,gBAAgB,CAAC,GAAG,mBAAmB,CAAC;IACjF,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,mBAAmB,CAAC;IACtC,GAAG,CAAC,WAAW,EAAE,mBAAmB,EAAE,GAAG,mBAAmB,CAAC,OAAO,CAAC,CAAC;IACtE,EAAE,CAAC,WAAW,EAAE,mBAAmB,EAAE,GAAG,mBAAmB,CAAC,OAAO,CAAC,CAAC;CACtE;AA4GD,wBAAgB,sBAAsB,CAAC,KAAK,SAAS,eAAe,KAAK,gBAAgB,CAAC,KAAK,CAAC,CAY/F"}

package/dist/core/utils/predicate-builder.js

@@ -0,0 +1,92 @@
+function createExpression(sql, parameters = []) {
+    return {
+        __type: 'predicate_expression',
+        sql,
+        parameters,
+        expressionType: undefined
+    };
+}
+function literal(value) {
+    return {
+        __type: 'predicate_literal',
+        value
+    };
+}
+function isPredicateExpression(value) {
+    return value?.__type === 'predicate_expression';
+}
+function isPredicateLiteral(value) {
+    return value?.__type === 'predicate_literal';
+}
+function buildArrayLiteral(values) {
+    const parts = [];
+    const parameters = [];
+    values.forEach(value => {
+        const normalized = normalizeLiteralValue(value);
+        parts.push(normalized.sql);
+        parameters.push(...normalized.parameters);
+    });
+    return createExpression(`[${parts.join(', ')}]`, parameters);
+}
+function normalizeLiteralValue(value) {
+    if (isPredicateLiteral(value)) {
+        return createExpression('?', [value.value]);
+    }
+    if (value === null) {
+        return createExpression('NULL');
+    }
+    if (value instanceof Date || typeof value === 'number' || typeof value === 'boolean' || typeof value === 'string') {
+        return createExpression('?', [value]);
+    }
+    throw new Error('Unsupported literal value in predicate array');
+}
+function normalizeArgument(arg) {
+    if (isPredicateExpression(arg)) {
+        return arg;
+    }
+    if (isPredicateLiteral(arg)) {
+        return createExpression('?', [arg.value]);
+    }
+    if (Array.isArray(arg)) {
+        return buildArrayLiteral(arg);
+    }
+    if (arg === null) {
+        return createExpression('NULL');
+    }
+    if (arg instanceof Date || typeof arg === 'number' || typeof arg === 'boolean') {
+        return createExpression('?', [arg]);
+    }
+    if (typeof arg === 'string') {
+        return createExpression(arg);
+    }
+    throw new Error('Unsupported predicate argument type');
+}
+function buildFunctionExpression(name, args) {
+    const builtArgs = args.map(arg => normalizeArgument(arg));
+    const sql = `${name}(${builtArgs.map(arg => arg.sql).join(', ')})`;
+    const parameters = builtArgs.flatMap(arg => arg.parameters);
+    return createExpression(sql, parameters);
+}
+function buildLogical(operator, expressions) {
+    if (!expressions.length) {
+        throw new Error(`${operator} requires at least one expression`);
+    }
+    if (expressions.length === 1) {
+        return expressions[0];
+    }
+    const sql = expressions.map(expr => `(${expr.sql})`).join(` ${operator} `);
+    const parameters = expressions.flatMap(expr => expr.parameters);
+    return createExpression(sql, parameters);
+}
+export function createPredicateBuilder() {
+    return {
+        fn: (name, ...args) => buildFunctionExpression(name, args),
+        col: column => createExpression(String(column)),
+        value: value => literal(value),
+        literal: value => literal(value),
+        array: values => buildArrayLiteral(values),
+        raw: sql => createExpression(sql),
+        and: expressions => buildLogical('AND', expressions),
+        or: expressions => buildLogical('OR', expressions)
+    };
+}