@housekit/orm 0.1.1

package/dist/modules/string.d.ts

@@ -0,0 +1,167 @@
+import { ClickHouseColumn } from '../core';
+import { SQLExpression } from '../expressions';
+/**
+ * Get string length
+ * @param col - Column or expression
+ */
+export declare function length(col: ClickHouseColumn | SQLExpression): SQLExpression;
+/**
+ * Get string length in UTF-8 bytes
+ * @param col - Column or expression
+ */
+export declare function lengthUTF8(col: ClickHouseColumn | SQLExpression): SQLExpression;
+/**
+ * Convert to lowercase
+ * @param col - Column or expression
+ */
+export declare function lower(col: ClickHouseColumn | SQLExpression): SQLExpression;
+/**
+ * Convert to uppercase
+ * @param col - Column or expression
+ */
+export declare function upper(col: ClickHouseColumn | SQLExpression): SQLExpression;
+/**
+ * Reverse string
+ * @param col - Column or expression
+ */
+export declare function reverse(col: ClickHouseColumn | SQLExpression): SQLExpression;
+/**
+ * Repeat string N times
+ * @param col - Column or expression
+ * @param n - Number of repetitions
+ */
+export declare function repeat(col: ClickHouseColumn | SQLExpression, n: number): SQLExpression;
+/**
+ * Get substring
+ * @param col - Column or expression
+ * @param offset - Starting position (1-based)
+ * @param length - Length of substring
+ */
+export declare function substring(col: ClickHouseColumn | SQLExpression, offset: number, length?: number): SQLExpression;
+/**
+ * Get substring from left
+ * @param col - Column or expression
+ * @param length - Length from left
+ */
+export declare function left(col: ClickHouseColumn | SQLExpression, length: number): SQLExpression;
+/**
+ * Get substring from right
+ * @param col - Column or expression
+ * @param length - Length from right
+ */
+export declare function right(col: ClickHouseColumn | SQLExpression, length: number): SQLExpression;
+/**
+ * Trim whitespace from string
+ * @param col - Column or expression
+ */
+export declare function stringTrim(col: ClickHouseColumn | SQLExpression): SQLExpression;
+/**
+ * Trim left whitespace
+ * @param col - Column or expression
+ */
+export declare function stringTrimLeft(col: ClickHouseColumn | SQLExpression): SQLExpression;
+/**
+ * Trim right whitespace
+ * @param col - Column or expression
+ */
+export declare function stringTrimRight(col: ClickHouseColumn | SQLExpression): SQLExpression;
+/**
+ * Check if string contains substring
+ * @param col - Column or expression
+ * @param substring - Substring to search for
+ */
+export declare function contains(col: ClickHouseColumn | SQLExpression, substring: string): SQLExpression;
+/**
+ * Check if string starts with substring
+ * @param col - Column or expression
+ * @param substring - Substring to check
+ */
+export declare function startsWith(col: ClickHouseColumn | SQLExpression, substring: string): SQLExpression;
+/**
+ * Check if string ends with substring
+ * @param col - Column or expression
+ * @param substring - Substring to check
+ */
+export declare function endsWith(col: ClickHouseColumn | SQLExpression, substring: string): SQLExpression;
+/**
+ * Find position of substring
+ * @param col - Column or expression
+ * @param substring - Substring to find
+ */
+export declare function position(col: ClickHouseColumn | SQLExpression, substring: string): SQLExpression;
+/**
+ * Count occurrences of substring
+ * @param col - Column or expression
+ * @param substring - Substring to count
+ */
+export declare function countMatches(col: ClickHouseColumn | SQLExpression, substring: string): SQLExpression;
+/**
+ * Concatenate strings
+ * @param cols - Strings to concatenate
+ */
+export declare function concat(...cols: (ClickHouseColumn | SQLExpression | string)[]): SQLExpression;
+/**
+ * Replace all occurrences of substring
+ * @param col - Column or expression
+ * @param pattern - Pattern to replace
+ * @param replacement - Replacement string
+ */
+export declare function replace(col: ClickHouseColumn | SQLExpression, pattern: string, replacement: string): SQLExpression;
+/**
+ * Replace using regex
+ * @param col - Column or expression
+ * @param pattern - Regex pattern
+ * @param replacement - Replacement string
+ */
+export declare function replaceRegexpAll(col: ClickHouseColumn | SQLExpression, pattern: string, replacement: string): SQLExpression;
+/**
+ * Match using regex (returns 1 if matches, 0 if not)
+ * @param col - Column or expression
+ * @param pattern - Regex pattern
+ */
+export declare function match(col: ClickHouseColumn | SQLExpression, pattern: string): SQLExpression;
+/**
+ * Check if string matches pattern (LIKE)
+ * @param col - Column or expression
+ * @param pattern - Pattern to match
+ */
+export declare function like(col: ClickHouseColumn | SQLExpression, pattern: string): SQLExpression;
+/**
+ * Check if string matches pattern (NOT LIKE)
+ * @param col - Column or expression
+ * @param pattern - Pattern to match
+ */
+export declare function notLike(col: ClickHouseColumn | SQLExpression, pattern: string): SQLExpression;
+/**
+ * Check if string matches pattern (ILIKE - case insensitive)
+ * @param col - Column or expression
+ * @param pattern - Pattern to match
+ */
+export declare function ilike(col: ClickHouseColumn | SQLExpression, pattern: string): SQLExpression;
+/**
+ * Check if string matches pattern (NOT ILIKE)
+ * @param col - Column or expression
+ * @param pattern - Pattern to match
+ */
+export declare function notIlike(col: ClickHouseColumn | SQLExpression, pattern: string): SQLExpression;
+/**
+ * Calculate SHA1 hash
+ * @param col - Column or expression
+ */
+export declare function sha1(col: ClickHouseColumn | SQLExpression): SQLExpression;
+/**
+ * Calculate SIP hash
+ * @param col - Column or expression
+ */
+export declare function sipHash64(col: ClickHouseColumn | SQLExpression): SQLExpression;
+/**
+ * Split string by delimiter
+ * @param col - Column or expression
+ * @param delimiter - Delimiter string
+ */
+export declare function splitByChar(col: ClickHouseColumn | SQLExpression, delimiter: string): SQLExpression;
+/**
+ * Split string by whitespace
+ * @param col - Column or expression
+ */
+export declare function splitByWhitespace(col: ClickHouseColumn | SQLExpression): SQLExpression;

package/dist/modules/time.d.ts

@@ -0,0 +1,154 @@
+import { ClickHouseColumn } from '../core';
+import { SQLExpression } from '../expressions';
+/**
+ * Get current timestamp
+ */
+export declare function timeNow(): SQLExpression;
+/**
+ * Get current date (without time)
+ */
+export declare function timeToday(): SQLExpression;
+/**
+ * Get yesterday's date (without time)
+ */
+export declare function timeYesterday(): SQLExpression;
+/**
+ * Convert to Date type (without time)
+ * @param col - Date/datetime column or expression
+ */
+export declare function timeToDate(col: ClickHouseColumn | SQLExpression): SQLExpression;
+/**
+ * Convert to DateTime type
+ * @param col - Date/datetime column or expression
+ */
+export declare function timeToDateTime(col: ClickHouseColumn | SQLExpression): SQLExpression;
+/**
+ * Convert to Unix timestamp (super common in time-series analytics)
+ * @param col - DateTime column or expression
+ */
+export declare function toUnixTimestamp(col: ClickHouseColumn | SQLExpression): SQLExpression;
+/**
+ * Format datetime to string
+ * @param col - DateTime column or expression
+ * @param format - Format string (e.g., '%Y-%m-%d %H:%M:%S')
+ */
+export declare function timeFormatDateTime(col: ClickHouseColumn | SQLExpression, format: string): SQLExpression;
+/**
+ * Truncate to start of hour
+ * @param col - DateTime column or expression
+ */
+export declare function timeToStartOfHour(col: ClickHouseColumn | SQLExpression): SQLExpression;
+/**
+ * Truncate to start of day
+ * @param col - DateTime column or expression
+ */
+export declare function timeToStartOfDay(col: ClickHouseColumn | SQLExpression): SQLExpression;
+/**
+ * Truncate to start of week
+ * @param col - DateTime column or expression
+ */
+export declare function timeToStartOfWeek(col: ClickHouseColumn | SQLExpression): SQLExpression;
+/**
+ * Truncate to start of month
+ * @param col - DateTime column or expression
+ */
+export declare function timeToStartOfMonth(col: ClickHouseColumn | SQLExpression): SQLExpression;
+/**
+ * Truncate to start of quarter
+ * @param col - DateTime column or expression
+ */
+export declare function toStartOfQuarter(col: ClickHouseColumn | SQLExpression): SQLExpression;
+/**
+ * Truncate to start of year
+ * @param col - DateTime column or expression
+ */
+export declare function toStartOfYear(col: ClickHouseColumn | SQLExpression): SQLExpression;
+/**
+ * Truncate to start of interval (very flexible for custom time buckets)
+ * @param col - DateTime column or expression
+ * @param interval - Interval string (e.g., 'INTERVAL 1 HOUR', 'INTERVAL 15 MINUTE')
+ * @param timezone - Optional timezone
+ */
+export declare function toStartOfInterval(col: ClickHouseColumn | SQLExpression, interval: string, timezone?: string): SQLExpression;
+/**
+ * Calculate difference between two dates
+ * @param unit - Unit of difference ('year', 'quarter', 'month', 'week', 'day', 'hour', 'minute', 'second')
+ * @param start - Start date
+ * @param end - End date
+ */
+export declare function dateDiff(unit: 'year' | 'quarter' | 'month' | 'week' | 'day' | 'hour' | 'minute' | 'second', start: ClickHouseColumn | SQLExpression, end: ClickHouseColumn | SQLExpression): SQLExpression;
+/**
+ * Add interval to date
+ * @param unit - Unit to add ('year', 'quarter', 'month', 'week', 'day', 'hour', 'minute', 'second')
+ * @param amount - Amount to add
+ * @param date - Date to add to
+ */
+export declare function dateAdd(unit: 'year' | 'quarter' | 'month' | 'week' | 'day' | 'hour' | 'minute' | 'second', amount: number, date: ClickHouseColumn | SQLExpression): SQLExpression;
+/**
+ * Subtract interval from date
+ * @param unit - Unit to subtract ('year', 'quarter', 'month', 'week', 'day', 'hour', 'minute', 'second')
+ * @param amount - Amount to subtract
+ * @param date - Date to subtract from
+ */
+export declare function dateSub(unit: 'year' | 'quarter' | 'month' | 'week' | 'day' | 'hour' | 'minute' | 'second', amount: number, date: ClickHouseColumn | SQLExpression): SQLExpression;
+/**
+ * Convert datetime to different timezone
+ * @param col - DateTime column or expression
+ * @param timezone - Target timezone
+ */
+export declare function toTimezone(col: ClickHouseColumn | SQLExpression, timezone: string): SQLExpression;
+/**
+ * Get timezone offset for datetime
+ * @param col - DateTime column or expression
+ */
+export declare function timeOffset(col: ClickHouseColumn | SQLExpression): SQLExpression;
+/**
+ * Extract year from date
+ * @param col - Date/datetime column or expression
+ */
+export declare function toYear(col: ClickHouseColumn | SQLExpression): SQLExpression;
+/**
+ * Extract quarter from date
+ * @param col - Date/datetime column or expression
+ */
+export declare function toQuarter(col: ClickHouseColumn | SQLExpression): SQLExpression;
+/**
+ * Extract month from date
+ * @param col - Date/datetime column or expression
+ */
+export declare function toMonth(col: ClickHouseColumn | SQLExpression): SQLExpression;
+/**
+ * Extract day of month from date
+ * @param col - Date/datetime column or expression
+ */
+export declare function toDayOfMonth(col: ClickHouseColumn | SQLExpression): SQLExpression;
+/**
+ * Extract day of week from date
+ * @param col - Date/datetime column or expression
+ */
+export declare function toDayOfWeek(col: ClickHouseColumn | SQLExpression): SQLExpression;
+/**
+ * Extract hour from datetime
+ * @param col - DateTime column or expression
+ */
+export declare function toHour(col: ClickHouseColumn | SQLExpression): SQLExpression;
+/**
+ * Extract minute from datetime
+ * @param col - DateTime column or expression
+ */
+export declare function toMinute(col: ClickHouseColumn | SQLExpression): SQLExpression;
+/**
+ * Extract second from datetime
+ * @param col - DateTime column or expression
+ */
+export declare function toSecond(col: ClickHouseColumn | SQLExpression): SQLExpression;
+/**
+ * Get ISO week number from date
+ * @param col - Date/datetime column or expression
+ */
+export declare function toISOWeek(col: ClickHouseColumn | SQLExpression): SQLExpression;
+/**
+ * Get week number from date (ClickHouse-specific)
+ * @param col - Date/datetime column or expression
+ */
+export declare function toWeek(col: ClickHouseColumn | SQLExpression): SQLExpression;

package/dist/modules/types.d.ts

@@ -0,0 +1,177 @@
+export type JsonValue = Record<string, any> | any[];
+import { ClickHouseColumn } from '../column';
+/**
+ * Low cardinality string column (very common for dimensions)
+ * @param name - Column name
+ */
+export declare function lowCardinalityString(name: string): ClickHouseColumn<string>;
+/**
+ * Low cardinality nullable string column
+ * @param name - Column name
+ */
+export declare function lowCardinalityNullableString(name: string): ClickHouseColumn<string | null>;
+/**
+ * Nullable JSON column
+ * @param name - Column name
+ */
+export declare function nullableJson(name: string): ClickHouseColumn<JsonValue | null>;
+/**
+ * Low cardinality JSON column
+ * @param name - Column name
+ */
+export declare function lowCardinalityJson(name: string): ClickHouseColumn<JsonValue>;
+/**
+ * Low cardinality nullable JSON column
+ * @param name - Column name
+ */
+export declare function lowCardinalityNullableJson(name: string): ClickHouseColumn<JsonValue | null>;
+/**
+ * Create an Enum8 column with TypeScript union type support
+ * @param name - Column name
+ * @param values - Array of possible values
+ */
+export declare function enum8<T extends string>(name: string, values: readonly T[]): ClickHouseColumn<T>;
+/**
+ * Create a nullable Enum8 column with TypeScript union type support
+ * @param name - Column name
+ * @param values - Array of possible values
+ */
+export declare function nullableEnum8<T extends string>(name: string, values: readonly T[]): ClickHouseColumn<T | null>;
+/**
+ * Create an Enum16 column with TypeScript union type support
+ * @param name - Column name
+ * @param values - Array of possible values
+ */
+export declare function enum16<T extends string>(name: string, values: readonly T[]): ClickHouseColumn<T>;
+/**
+ * Create a nullable Enum16 column with TypeScript union type support
+ * @param name - Column name
+ * @param values - Array of possible values
+ */
+export declare function nullableEnum16<T extends string>(name: string, values: readonly T[]): ClickHouseColumn<T | null>;
+/**
+ * Array of strings with low cardinality
+ * @param name - Column name
+ */
+export declare function lowCardinalityStringArray(name: string): ClickHouseColumn<string[]>;
+/**
+ * Nullable array of strings
+ * @param name - Column name
+ */
+export declare function nullableStringArray(name: string): ClickHouseColumn<string[] | null>;
+/**
+ * Array of nullable strings
+ * @param name - Column name
+ */
+export declare function stringNullableArray(name: string): ClickHouseColumn<(string | null)[]>;
+/**
+ * Array of integers with low cardinality
+ * @param name - Column name
+ */
+export declare function lowCardinalityInt32Array(name: string): ClickHouseColumn<number[]>;
+/**
+ * Email column (low cardinality string)
+ * @param name - Column name
+ */
+export declare function email(name: string): ClickHouseColumn<string>;
+/**
+ * Nullable email column
+ * @param name - Column name
+ */
+export declare function nullableEmail(name: string): ClickHouseColumn<string | null>;
+/**
+ * Phone number column (low cardinality string)
+ * @param name - Column name
+ */
+export declare function phone(name: string): ClickHouseColumn<string>;
+/**
+ * Nullable phone number column
+ * @param name - Column name
+ */
+export declare function nullablePhone(name: string): ClickHouseColumn<string | null>;
+/**
+ * Country code column (Enum8 with common country codes)
+ * @param name - Column name
+ */
+export declare function countryCode(name: string): ClickHouseColumn<string>;
+/**
+ * Nullable country code column
+ * @param name - Column name
+ */
+export declare function nullableCountryCode(name: string): ClickHouseColumn<string | null>;
+/**
+ * Status column (Enum8 with common statuses)
+ * @param name - Column name
+ */
+export declare function status<T extends string>(name: string, values: readonly T[]): ClickHouseColumn<T>;
+/**
+ * Nullable status column
+ * @param name - Column name
+ * @param values - Array of possible status values
+ */
+export declare function nullableStatus<T extends string>(name: string, values: readonly T[]): ClickHouseColumn<T | null>;
+/**
+ * Common status values for reference
+ */
+export declare const COMMON_STATUSES: {
+    readonly ACTIVE: "active";
+    readonly INACTIVE: "inactive";
+    readonly PENDING: "pending";
+    readonly COMPLETED: "completed";
+    readonly FAILED: "failed";
+    readonly CANCELLED: "cancelled";
+    readonly DRAFT: "draft";
+    readonly PUBLISHED: "published";
+    readonly ARCHIVED: "archived";
+    readonly DELETED: "deleted";
+};
+/**
+ * Create a status column with common predefined values
+ * @param name - Column name
+ * @param customValues - Optional custom status values
+ */
+export declare function commonStatus(name: string, customValues?: readonly string[]): ClickHouseColumn<string>;
+/**
+ * Create a nullable status column with common predefined values
+ * @param name - Column name
+ * @param customValues - Optional custom status values
+ */
+export declare function nullableCommonStatus(name: string, customValues?: readonly string[]): ClickHouseColumn<string | null>;
+/**
+ * Created at timestamp column (DateTime with default now())
+ * @param name - Column name
+ * @param timezone - Optional timezone
+ */
+export declare function createdAt(name?: string, timezone?: string): ClickHouseColumn<string>;
+/**
+ * Updated at timestamp column (DateTime with default now() and on update)
+ * @param name - Column name
+ * @param timezone - Optional timezone
+ */
+export declare function updatedAt(name?: string, timezone?: string): ClickHouseColumn<string>;
+/**
+ * Deleted at timestamp column (nullable DateTime for soft deletes)
+ * @param name - Column name
+ * @param timezone - Optional timezone
+ */
+export declare function deletedAt(name?: string, timezone?: string): ClickHouseColumn<string | null>;
+/**
+ * Auto-generated UUID primary key
+ * @param name - Column name
+ */
+export declare function uuidPrimaryKey(name?: string): ClickHouseColumn<string>;
+/**
+ * Auto-generated UUID primary key with low cardinality (for distributed systems)
+ * @param name - Column name
+ */
+export declare function lowCardinalityUuidPrimaryKey(name?: string): ClickHouseColumn<string>;
+/**
+ * Sequential integer primary key
+ * @param name - Column name
+ */
+export declare function int32PrimaryKey(name?: string): ClickHouseColumn<number>;
+/**
+ * Sequential big integer primary key
+ * @param name - Column name
+ */
+export declare function int64PrimaryKey(name?: string): ClickHouseColumn<number>;

package/dist/modules/window.d.ts

@@ -0,0 +1,27 @@
+import { ClickHouseColumn } from '../core';
+import { type SQLExpression, type SQLValue } from '../expressions';
+type OrderDirection = 'ASC' | 'DESC';
+export type WindowPartition = ClickHouseColumn | SQLExpression;
+export type WindowOrder = WindowPartition | {
+    col: WindowPartition;
+    dir?: OrderDirection;
+};
+export interface WindowSpec {
+    partitionBy?: WindowPartition | WindowPartition[];
+    orderBy?: WindowOrder | WindowOrder[];
+}
+export declare function over<T>(expr: SQLExpression<T>, spec?: WindowSpec): SQLExpression<T>;
+export declare function rowNumber(spec?: WindowSpec): SQLExpression<number>;
+export declare function rank(spec?: WindowSpec): SQLExpression<number>;
+export declare function denseRank(spec?: WindowSpec): SQLExpression<number>;
+export declare function lag<T>(col: ClickHouseColumn<T, any, any> | SQLExpression<T>, offset?: number, defaultValue?: SQLValue, spec?: WindowSpec): SQLExpression<T>;
+export declare function lead<T>(col: ClickHouseColumn<T, any, any> | SQLExpression<T>, offset?: number, defaultValue?: SQLValue, spec?: WindowSpec): SQLExpression<T>;
+export declare const windowFns: {
+    over: typeof over;
+    rowNumber: typeof rowNumber;
+    rank: typeof rank;
+    denseRank: typeof denseRank;
+    lag: typeof lag;
+    lead: typeof lead;
+};
+export {};

package/dist/relational.d.ts

@@ -0,0 +1,33 @@
+import { type TableDefinition } from './core';
+import type { SQLExpression } from './expressions';
+/**
+ * Join strategy for relational queries
+ */
+export type JoinStrategy = 'auto' | 'standard' | 'global' | 'any' | 'global_any';
+export type RelationalFindOptions<TTable = any> = {
+    where?: SQLExpression | ((columns: TTable extends TableDefinition<infer TCols> ? TCols : any) => SQLExpression);
+    limit?: number;
+    offset?: number;
+    with?: Record<string, boolean | RelationalFindOptions>;
+    /**
+     * Join strategy for related data.
+     *
+     * - 'auto': Automatically uses GLOBAL when table has onCluster option
+     * - 'standard': Regular LEFT JOIN
+     * - 'global': Force GLOBAL JOIN (for clusters)
+     * - 'any': Use ANY JOIN (faster, single match)
+     * - 'global_any': Combine GLOBAL and ANY
+     *
+     * @default 'auto'
+     */
+    joinStrategy?: JoinStrategy;
+};
+/**
+ * Build a modern relational API with ClickHouse optimizations.
+ *
+ * Key improvements over standard ORMs:
+ * - Automatic GLOBAL JOIN detection for distributed tables
+ * - Join strategy selection for performance tuning
+ * - Support for dictionary lookups as alternative to JOINs
+ */
+export declare function buildRelationalAPI(client: any, schema?: Record<string, TableDefinition<any>>): Record<string, any> | undefined;

package/dist/relations.d.ts

@@ -0,0 +1,15 @@
+import type { ClickHouseColumn, RelationDefinition, TableDefinition } from './core';
+type OneConfig = {
+    fields: ClickHouseColumn[];
+    references: ClickHouseColumn[];
+};
+type ManyConfig = {
+    fields?: ClickHouseColumn[];
+    references?: ClickHouseColumn[];
+};
+type RelationBuilderHelpers = {
+    one: (table: TableDefinition<any>, config: OneConfig) => RelationDefinition;
+    many: (table: TableDefinition<any>, config?: ManyConfig) => RelationDefinition;
+};
+export declare function relations<TTable extends TableDefinition<any>, TRelations extends Record<string, RelationDefinition>>(table: TTable, callback: (helpers: RelationBuilderHelpers) => TRelations): TRelations;
+export {};