@zintrust/core 0.1.0

package/src/orm/DatabaseAdapter.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Database Adapter Interface
+ * Defines contract for different database implementations
+ */
+/**
+ * Minimal D1 Database interface for type safety
+ */
+export interface ID1Database {
+    prepare(sql: string): {
+        bind(...values: unknown[]): {
+            all<T = unknown>(): Promise<{
+                results?: T[];
+                success: boolean;
+                error?: string;
+            }>;
+            first<T = unknown>(): Promise<T | null>;
+            run(): Promise<{
+                success: boolean;
+                error?: string;
+            }>;
+        };
+    };
+}
+export interface DatabaseConfig {
+    d1?: ID1Database;
+    driver: 'sqlite' | 'postgresql' | 'mysql' | 'sqlserver' | 'd1';
+    database?: string;
+    host?: string;
+    port?: number;
+    username?: string;
+    password?: string;
+    synchronize?: boolean;
+    logging?: boolean;
+    readHosts?: string[];
+}
+export interface QueryResult {
+    rows: Record<string, unknown>[];
+    rowCount: number;
+}
+export interface IDatabaseAdapter {
+    /**
+     * Connect to database
+     */
+    connect(): Promise<void>;
+    /**
+     * Disconnect from database
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Execute a query
+     */
+    query(sql: string, parameters: unknown[]): Promise<QueryResult>;
+    /**
+     * Execute a query and return first result
+     */
+    queryOne(sql: string, parameters: unknown[]): Promise<Record<string, unknown> | null>;
+    /**
+     * Execute multiple queries in transaction
+     */
+    transaction<T>(callback: (adapter: IDatabaseAdapter) => Promise<T>): Promise<T>;
+    /**
+     * Execute raw SQL query (only available when USE_RAW_QRY=true)
+     * WARNING: Bypasses QueryBuilder safety. Use parameterized queries.
+     */
+    rawQuery<T = unknown>(sql: string, parameters?: unknown[]): Promise<T[]>;
+    /**
+     * Get database type
+     */
+    getType(): string;
+    /**
+     * Check connection status
+     */
+    isConnected(): boolean;
+    /**
+     * Get placeholder for parameterized query
+     */
+    getPlaceholder(index: number): string;
+}
+/**
+ * Base Adapter Utilities
+ * Refactored to Functional Object pattern
+ */
+export declare const BaseAdapter: Readonly<{
+    /**
+     * Sanitize parameter value
+     */
+    sanitize(value: unknown): string;
+    /**
+     * Build parameterized query (for adapters that need it)
+     */
+    buildParameterizedQuery(sql: string, parameters: unknown[], getPlaceholder?: (index: number) => string): {
+        sql: string;
+        parameters: unknown[];
+    };
+}>;
+//# sourceMappingURL=DatabaseAdapter.d.ts.map

package/src/orm/DatabaseAdapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DatabaseAdapter.d.ts","sourceRoot":"","sources":["../../../src/orm/DatabaseAdapter.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG;QACpB,IAAI,CAAC,GAAG,MAAM,EAAE,OAAO,EAAE,GAAG;YAC1B,GAAG,CAAC,CAAC,GAAG,OAAO,KAAK,OAAO,CAAC;gBAAE,OAAO,CAAC,EAAE,CAAC,EAAE,CAAC;gBAAC,OAAO,EAAE,OAAO,CAAC;gBAAC,KAAK,CAAC,EAAE,MAAM,CAAA;aAAE,CAAC,CAAC;YACjF,KAAK,CAAC,CAAC,GAAG,OAAO,KAAK,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;YACxC,GAAG,IAAI,OAAO,CAAC;gBAAE,OAAO,EAAE,OAAO,CAAC;gBAAC,KAAK,CAAC,EAAE,MAAM,CAAA;aAAE,CAAC,CAAC;SACtD,CAAC;KACH,CAAC;CACH;AAED,MAAM,WAAW,cAAc;IAC7B,EAAE,CAAC,EAAE,WAAW,CAAC;IACjB,MAAM,EAAE,QAAQ,GAAG,YAAY,GAAG,OAAO,GAAG,WAAW,GAAG,IAAI,CAAC;IAC/D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;CACtB;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC;IAChC,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,gBAAgB;IAC/B;;OAEG;IACH,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAEzB;;OAEG;IACH,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAE5B;;OAEG;IACH,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IAEhE;;OAEG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC,CAAC;IAEtF;;OAEG;IACH,WAAW,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,OAAO,EAAE,gBAAgB,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IAEhF;;;OAGG;IACH,QAAQ,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC;IAEzE;;OAEG;IACH,OAAO,IAAI,MAAM,CAAC;IAElB;;OAEG;IACH,WAAW,IAAI,OAAO,CAAC;IAEvB;;OAEG;IACH,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;CACvC;AAED;;;GAGG;AACH,eAAO,MAAM,WAAW;IACtB;;OAEG;oBACa,OAAO,GAAG,MAAM;IAiBhC;;OAEG;iCAEI,MAAM,cACC,OAAO,EAAE,mBACL,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,GACxC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,OAAO,EAAE,CAAA;KAAE;EASzC,CAAC"}

package/src/orm/DatabaseAdapter.js

@@ -0,0 +1,40 @@
+/**
+ * Database Adapter Interface
+ * Defines contract for different database implementations
+ */
+/**
+ * Base Adapter Utilities
+ * Refactored to Functional Object pattern
+ */
+export const BaseAdapter = Object.freeze({
+    /**
+     * Sanitize parameter value
+     */
+    sanitize(value) {
+        if (value === null || value === undefined) {
+            return 'NULL';
+        }
+        if (typeof value === 'string') {
+            return `'${value.replaceAll("'", "''")}'`;
+        }
+        if (typeof value === 'boolean') {
+            return value ? '1' : '0';
+        }
+        if (typeof value === 'number') {
+            return String(value);
+        }
+        // For objects, convert to JSON string representation
+        return `'${JSON.stringify(value).replaceAll("'", "''")}'`;
+    },
+    /**
+     * Build parameterized query (for adapters that need it)
+     */
+    buildParameterizedQuery(sql, parameters, getPlaceholder = () => '?') {
+        let paramIndex = 0;
+        const processedSql = sql.replaceAll('?', () => {
+            paramIndex++;
+            return getPlaceholder(paramIndex);
+        });
+        return { sql: processedSql, parameters };
+    },
+});

package/src/orm/Model.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Enhanced Model with Relationships
+ * Full ORM capabilities with eager/lazy loading
+ */
+import { IQueryBuilder } from './QueryBuilder';
+import { IRelationship } from './Relationships';
+export interface ModelConfig {
+    table: string;
+    fillable: string[];
+    hidden: string[];
+    timestamps: boolean;
+    casts: Record<string, string>;
+}
+export interface ModelConfig {
+    table: string;
+    fillable: string[];
+    hidden: string[];
+    timestamps: boolean;
+    casts: Record<string, string>;
+    connection?: string;
+}
+export interface ModelStatic {
+    query(): IQueryBuilder;
+    getTable?(): string;
+    name?: string;
+}
+export interface IModel {
+    fill(attributes: Record<string, unknown>): IModel;
+    setAttribute(key: string, value: unknown): IModel;
+    getAttribute(key: string): unknown;
+    getAttributes(): Record<string, unknown>;
+    save(): Promise<boolean>;
+    delete(): Promise<boolean>;
+    toJSON(): Record<string, unknown>;
+    isDirty(key?: string): boolean;
+    getTable(): string;
+    exists(): boolean;
+    setExists(exists: boolean): void;
+    hasOne(relatedModel: ModelStatic, foreignKey?: string): IRelationship;
+    hasMany(relatedModel: ModelStatic, foreignKey?: string): IRelationship;
+    belongsTo(relatedModel: ModelStatic, foreignKey?: string): IRelationship;
+    belongsToMany(relatedModel: ModelStatic, throughTable?: string, foreignKey?: string, relatedKey?: string): IRelationship;
+}
+/**
+ * Create a new model instance
+ */
+export declare const createModel: (config: ModelConfig, attributes?: Record<string, unknown>) => IModel;
+/**
+ * Get a query builder for a table
+ */
+export declare const query: (table: string, connection?: string) => IQueryBuilder;
+/**
+ * Find a model by ID
+ */
+export declare const find: (config: ModelConfig, id: unknown) => Promise<IModel | null>;
+/**
+ * Get all records for a model
+ */
+export declare const all: (config: ModelConfig) => Promise<IModel[]>;
+type UnboundModelMethods = Record<string, (m: IModel, ...args: unknown[]) => unknown>;
+type BoundModelMethods = Record<string, (...args: never[]) => unknown>;
+type BoundFromUnbound<T extends UnboundModelMethods> = {
+    [K in keyof T]: T[K] extends (m: IModel, ...args: infer A) => infer R ? (...args: A) => R : never;
+};
+type DefinedModel<T extends BoundModelMethods> = {
+    create: (attributes?: Record<string, unknown>) => IModel & T;
+    find: (id: unknown) => Promise<(IModel & T) | null>;
+    all: () => Promise<Array<IModel & T>>;
+    query: () => IQueryBuilder;
+    getTable: () => string;
+};
+/**
+ * Define a new model type
+ */
+export declare function define<const T extends UnboundModelMethods>(config: ModelConfig, methods?: T): DefinedModel<BoundFromUnbound<T>>;
+export declare function define<const T extends BoundModelMethods>(config: ModelConfig, plan: (model: IModel) => T): DefinedModel<T>;
+/**
+ * Model namespace - sealed namespace object grouping all model operations
+ * Frozen to prevent accidental mutation
+ *
+ * @see FRAMEWORK_REFACTOR_FUNCTION_PATTERN.md for Pattern 2 details
+ */
+export declare const Model: Readonly<{
+    create: (config: ModelConfig, attributes?: Record<string, unknown>) => IModel;
+    query: (table: string, connection?: string) => IQueryBuilder;
+    find: (config: ModelConfig, id: unknown) => Promise<IModel | null>;
+    all: (config: ModelConfig) => Promise<IModel[]>;
+    define: typeof define;
+}>;
+export {};
+//# sourceMappingURL=Model.d.ts.map

package/src/orm/Model.d.ts.map

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

package/src/orm/Model.js

@@ -0,0 +1,206 @@
+/**
+ * Enhanced Model with Relationships
+ * Full ORM capabilities with eager/lazy loading
+ */
+import { DEFAULTS } from '../config/constants';
+import { ErrorFactory } from '../exceptions/ZintrustError';
+import { useDatabase } from './Database';
+import { QueryBuilder } from './QueryBuilder';
+import { BelongsTo, BelongsToMany, HasMany, HasOne } from './Relationships';
+const getRelatedTableName = (relatedModel) => {
+    if (typeof relatedModel.getTable === 'function') {
+        return relatedModel.getTable();
+    }
+    throw ErrorFactory.createConfigError('Related model does not provide a table name');
+};
+/**
+ * Cast attribute value based on config
+ */
+const castAttribute = (config, key, value) => {
+    const castType = config.casts[key];
+    if (castType === undefined)
+        return value;
+    switch (castType) {
+        case 'boolean':
+            return value === true || value === 1 || value === '1';
+        case 'integer':
+            return Number.parseInt(String(value), 10);
+        case 'float':
+            return Number.parseFloat(String(value));
+        case 'date':
+            return new Date(String(value)).toISOString().split('T')[0];
+        case 'datetime':
+            return new Date(String(value)).toISOString();
+        case 'json':
+            return typeof value === 'string' ? JSON.parse(value) : value;
+        default:
+            return value;
+    }
+};
+/**
+ * Fill attributes based on fillable config
+ */
+const fillAttributes = (config, attrs, newAttrs) => {
+    for (const [key, value] of Object.entries(newAttrs)) {
+        if (config.fillable.length === 0 || config.fillable.includes(key)) {
+            attrs[key] = castAttribute(config, key, value);
+        }
+    }
+};
+const createModelJSON = (config, attrs) => {
+    const json = {};
+    for (const [key, value] of Object.entries(attrs)) {
+        if (!config.hidden.includes(key))
+            json[key] = value;
+    }
+    return json;
+};
+const createModelRelationships = (config) => ({
+    hasOne: (relatedModel, foreignKey) => HasOne.create(relatedModel, foreignKey ?? `${config.table.slice(0, -1)}_id`, 'id'),
+    hasMany: (relatedModel, foreignKey) => HasMany.create(relatedModel, foreignKey ?? `${config.table.slice(0, -1)}_id`, 'id'),
+    belongsTo: (relatedModel, foreignKey) => {
+        const relatedTable = getRelatedTableName(relatedModel);
+        return BelongsTo.create(relatedModel, foreignKey ?? `${relatedTable.slice(0, -1)}_id`, 'id');
+    },
+    belongsToMany: (relatedModel, throughTable, foreignKey, relatedKey) => {
+        const relatedTable = getRelatedTableName(relatedModel);
+        const table = throughTable ?? [config.table, relatedTable].sort((a, b) => a.localeCompare(b)).join('_');
+        return BelongsToMany.create(relatedModel, table, foreignKey ?? `${config.table.slice(0, -1)}_id`, relatedKey ?? `${relatedTable.slice(0, -1)}_id`);
+    },
+});
+/**
+ * Create a new model instance
+ */
+export const createModel = (config, attributes = {}) => {
+    const connection = config.connection ?? DEFAULTS.CONNECTION;
+    const db = useDatabase(undefined, connection);
+    const attrs = {};
+    let original = {};
+    let isExists = false;
+    fillAttributes(config, attrs, attributes);
+    original = { ...attrs };
+    const model = {
+        fill: (newAttrs) => {
+            fillAttributes(config, attrs, newAttrs);
+            return model;
+        },
+        setAttribute: (key, value) => {
+            attrs[key] = castAttribute(config, key, value);
+            return model;
+        },
+        getAttribute: (key) => attrs[key],
+        getAttributes: () => ({ ...attrs }),
+        // remove in production - use saveChanges pattern
+        // eslint-disable-next-line @typescript-eslint/require-await
+        async save() {
+            if (db === undefined)
+                throw ErrorFactory.createDatabaseError('Database not initialized');
+            if (config.timestamps) {
+                attrs['created_at'] = attrs['created_at'] ?? new Date().toISOString();
+                attrs['updated_at'] = new Date().toISOString();
+            }
+            isExists = true;
+            original = { ...attrs };
+            return true;
+        },
+        // remove in production - use delete pattern
+        // eslint-disable-next-line @typescript-eslint/require-await
+        async delete() {
+            if (!isExists || db === undefined)
+                return false;
+            return true;
+        },
+        toJSON: () => createModelJSON(config, attrs),
+        isDirty: (key) => key === undefined
+            ? JSON.stringify(attrs) !== JSON.stringify(original)
+            : attrs[key] !== original[key],
+        getTable: () => config.table,
+        exists: () => isExists,
+        setExists: (exists) => {
+            isExists = exists;
+        },
+        ...createModelRelationships(config),
+    };
+    return model;
+};
+/**
+ * Get a query builder for a table
+ */
+export const query = (table, connection) => {
+    const db = useDatabase(undefined, connection ?? DEFAULTS.CONNECTION);
+    return QueryBuilder.create(table, db);
+};
+/**
+ * Find a model by ID
+ */
+export const find = async (config, id) => {
+    const builder = query(config.table, config.connection);
+    builder.where('id', '=', String(id)).limit(1);
+    const result = await builder.first();
+    if (result === null)
+        return null;
+    const model = createModel(config, result);
+    model.setExists(true);
+    return model;
+};
+/**
+ * Get all records for a model
+ */
+export const all = async (config) => {
+    const builder = query(config.table, config.connection);
+    const results = await builder.get();
+    return results.map((result) => {
+        const model = createModel(config, result);
+        model.setExists(true);
+        return model;
+    });
+};
+const bindUnboundMethods = (model, methods) => {
+    const bound = {};
+    for (const [name, method] of Object.entries(methods)) {
+        bound[name] = (...args) => method(model, ...args);
+    }
+    return bound;
+};
+const extendModel = (model, methods) => {
+    const extended = { ...model };
+    for (const [name, method] of Object.entries(methods)) {
+        extended[name] = method;
+    }
+    return extended;
+};
+export function define(config, methodsOrPlan) {
+    const isPlan = typeof methodsOrPlan === 'function';
+    const attach = (model) => {
+        const methods = isPlan
+            ? methodsOrPlan(model)
+            : bindUnboundMethods(model, methodsOrPlan ?? {});
+        return extendModel(model, methods);
+    };
+    return {
+        create: (attributes = {}) => attach(createModel(config, attributes)),
+        find: async (id) => {
+            const model = await find(config, id);
+            return model === null ? null : attach(model);
+        },
+        all: async () => {
+            const models = await all(config);
+            return models.map((m) => attach(m));
+        },
+        query: () => query(config.table, config.connection),
+        getTable: () => config.table,
+    };
+}
+/**
+ * Model namespace - sealed namespace object grouping all model operations
+ * Frozen to prevent accidental mutation
+ *
+ * @see FRAMEWORK_REFACTOR_FUNCTION_PATTERN.md for Pattern 2 details
+ */
+export const Model = Object.freeze({
+    create: createModel,
+    query,
+    find,
+    all,
+    define,
+});

package/src/orm/QueryBuilder.d.ts

@@ -0,0 +1,52 @@
+/**
+ * QueryBuilder - Type-Safe Query Builder
+ * Build queries without raw SQL
+ */
+import { IDatabase } from './Database';
+export interface WhereClause {
+    column: string;
+    operator: string;
+    value: unknown;
+}
+export interface IQueryBuilder {
+    select(...columns: string[]): IQueryBuilder;
+    where(column: string, operator: string | number | boolean | null, value?: unknown): IQueryBuilder;
+    andWhere(column: string, operator: string, value?: unknown): IQueryBuilder;
+    orWhere(column: string, operator: string, value?: unknown): IQueryBuilder;
+    join(table: string, on: string): IQueryBuilder;
+    leftJoin(table: string, on: string): IQueryBuilder;
+    orderBy(column: string, direction?: 'ASC' | 'DESC'): IQueryBuilder;
+    limit(count: number): IQueryBuilder;
+    offset(count: number): IQueryBuilder;
+    getWhereClauses(): WhereClause[];
+    getSelectColumns(): string[];
+    getTable(): string;
+    getLimit(): number | undefined;
+    getOffset(): number | undefined;
+    getOrderBy(): {
+        column: string;
+        direction: 'ASC' | 'DESC';
+    } | undefined;
+    getJoins(): Array<{
+        table: string;
+        on: string;
+    }>;
+    isReadOperation(): boolean;
+    toSQL(): string;
+    getParameters(): unknown[];
+    first<T>(): Promise<T | null>;
+    get<T>(): Promise<T[]>;
+}
+/**
+ * QueryBuilder - Type-Safe Query Builder
+ * Sealed namespace object following Pattern 2
+ *
+ * @see FRAMEWORK_REFACTOR_FUNCTION_PATTERN.md for Pattern 2 details
+ */
+export declare const QueryBuilder: Readonly<{
+    /**
+     * Create a new query builder instance
+     */
+    create(table: string, db?: IDatabase): IQueryBuilder;
+}>;
+//# sourceMappingURL=QueryBuilder.d.ts.map

package/src/orm/QueryBuilder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"QueryBuilder.d.ts","sourceRoot":"","sources":["../../../src/orm/QueryBuilder.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAE1C,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,CAAC,GAAG,OAAO,EAAE,MAAM,EAAE,GAAG,aAAa,CAAC;IAC5C,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,EAAE,KAAK,CAAC,EAAE,OAAO,GAAG,aAAa,CAAC;IAClG,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO,GAAG,aAAa,CAAC;IAC3E,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO,GAAG,aAAa,CAAC;IAC1E,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,aAAa,CAAC;IAC/C,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,aAAa,CAAC;IACnD,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,KAAK,GAAG,MAAM,GAAG,aAAa,CAAC;IACnE,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,aAAa,CAAC;IACpC,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,aAAa,CAAC;IACrC,eAAe,IAAI,WAAW,EAAE,CAAC;IACjC,gBAAgB,IAAI,MAAM,EAAE,CAAC;IAC7B,QAAQ,IAAI,MAAM,CAAC;IACnB,QAAQ,IAAI,MAAM,GAAG,SAAS,CAAC;IAC/B,SAAS,IAAI,MAAM,GAAG,SAAS,CAAC;IAChC,UAAU,IAAI;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,KAAK,GAAG,MAAM,CAAA;KAAE,GAAG,SAAS,CAAC;IACxE,QAAQ,IAAI,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACjD,eAAe,IAAI,OAAO,CAAC;IAC3B,KAAK,IAAI,MAAM,CAAC;IAChB,aAAa,IAAI,OAAO,EAAE,CAAC;IAC3B,KAAK,CAAC,CAAC,KAAK,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IAC9B,GAAG,CAAC,CAAC,KAAK,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC;CACxB;AA2ID;;;;;GAKG;AACH,eAAO,MAAM,YAAY;IACvB;;OAEG;kBACW,MAAM,OAAO,SAAS,GAAG,aAAa;EAUpD,CAAC"}

package/src/orm/QueryBuilder.js

@@ -0,0 +1,134 @@
+/**
+ * QueryBuilder - Type-Safe Query Builder
+ * Build queries without raw SQL
+ */
+import { ErrorFactory } from '../exceptions/ZintrustError';
+/**
+ * Escape SQL identifier
+ */
+const escapeIdentifier = (id) => `"${id.replaceAll('"', '""')}"`;
+/**
+ * Build SELECT clause
+ */
+const buildSelectClause = (columns) => columns.map((c) => (c === '*' ? c : escapeIdentifier(c))).join(', ');
+/**
+ * Build WHERE clause
+ */
+const buildWhereClause = (conditions) => {
+    if (conditions.length === 0)
+        return '';
+    const sql = conditions
+        .map((clause) => `${escapeIdentifier(clause.column)} ${clause.operator} ?`)
+        .join(' AND ');
+    return ` WHERE ${sql}`;
+};
+/**
+ * Build ORDER BY clause
+ */
+const buildOrderByClause = (orderBy) => {
+    if (!orderBy)
+        return '';
+    return ` ORDER BY ${orderBy.column} ${orderBy.direction}`;
+};
+/**
+ * Build LIMIT and OFFSET clause
+ */
+const buildLimitOffsetClause = (limit, offset) => {
+    let sql = '';
+    if (limit !== undefined && limit !== null)
+        sql += ` LIMIT ${limit}`;
+    if (offset !== undefined && offset !== null)
+        sql += ` OFFSET ${offset}`;
+    return sql;
+};
+/**
+ * Execute query and return first result
+ */
+async function executeFirst(builder, db) {
+    if (!db)
+        throw ErrorFactory.createDatabaseError('Database instance not provided to QueryBuilder');
+    builder.limit(1);
+    const results = (await db.query(builder.toSQL(), builder.getParameters(), builder.isReadOperation()));
+    return results[0] ?? null;
+}
+/**
+ * Execute query and return all results
+ */
+async function executeGet(builder, db) {
+    if (!db)
+        throw ErrorFactory.createDatabaseError('Database instance not provided to QueryBuilder');
+    return (await db.query(builder.toSQL(), builder.getParameters(), builder.isReadOperation()));
+}
+/**
+ * Create the builder object
+ */
+function createBuilder(state, db) {
+    const builder = {
+        select: (...columns) => {
+            state.selectColumns = columns.length > 0 ? columns : ['*'];
+            return builder;
+        },
+        where: (column, operator, value) => {
+            const finalOperator = value === undefined ? '=' : operator;
+            const finalValue = value === undefined ? operator : value;
+            state.whereConditions.push({ column, operator: finalOperator, value: finalValue });
+            return builder;
+        },
+        andWhere: (column, operator, value) => builder.where(column, operator, value),
+        orWhere: (column, operator, value) => builder.where(column, operator, value),
+        join: (tableJoin, on) => {
+            state.joins.push({ table: tableJoin, on });
+            return builder;
+        },
+        leftJoin: (tableJoin, on) => builder.join(tableJoin, on),
+        orderBy: (column, direction = 'ASC') => {
+            state.orderByClause = { column, direction };
+            return builder;
+        },
+        limit: (count) => {
+            state.limitValue = count;
+            return builder;
+        },
+        offset: (count) => {
+            state.offsetValue = count;
+            return builder;
+        },
+        getWhereClauses: () => state.whereConditions,
+        getSelectColumns: () => state.selectColumns,
+        getTable: () => state.tableName,
+        getLimit: () => state.limitValue,
+        getOffset: () => state.offsetValue,
+        getOrderBy: () => state.orderByClause,
+        getJoins: () => state.joins,
+        isReadOperation: () => true,
+        toSQL: () => {
+            const columns = buildSelectClause(state.selectColumns);
+            const tableEscaped = escapeIdentifier(state.tableName);
+            return `SELECT ${columns} FROM ${tableEscaped}${buildWhereClause(state.whereConditions)}${buildOrderByClause(state.orderByClause)}${buildLimitOffsetClause(state.limitValue, state.offsetValue)}`;
+        },
+        getParameters: () => state.whereConditions.map((clause) => clause.value),
+        first: async () => executeFirst(builder, db),
+        get: async () => executeGet(builder, db),
+    };
+    return builder;
+}
+/**
+ * QueryBuilder - Type-Safe Query Builder
+ * Sealed namespace object following Pattern 2
+ *
+ * @see FRAMEWORK_REFACTOR_FUNCTION_PATTERN.md for Pattern 2 details
+ */
+export const QueryBuilder = Object.freeze({
+    /**
+     * Create a new query builder instance
+     */
+    create(table, db) {
+        const state = {
+            tableName: table,
+            whereConditions: [],
+            selectColumns: ['*'],
+            joins: [],
+        };
+        return createBuilder(state, db);
+    },
+});