@warlock.js/cascade 4.0.171 → 4.1.1

package/esm/drivers/postgres/postgres-sync-adapter.mjs

@@ -0,0 +1,162 @@
+//#region ../../@warlock.js/cascade/src/drivers/postgres/postgres-sync-adapter.ts
+/**
+* PostgreSQL Sync Adapter.
+*
+* Handles batch updates for embedded/denormalized data stored
+* in JSONB columns. In a normalized SQL world, this is less common
+* than in MongoDB, but still useful for JSONB documents.
+*
+* @example
+* ```typescript
+* const syncAdapter = driver.syncAdapter();
+*
+* // Update embedded user data in posts
+* await syncAdapter.executeBatch([
+*   {
+*     targetTable: 'posts',
+*     filter: { 'author.id': 123 },
+*     update: { 'author.name': 'New Name' },
+*     // ... other fields
+*   }
+* ]);
+* ```
+*/
+var PostgresSyncAdapter = class {
+	driver;
+	/**
+	* Create a new sync adapter.
+	*
+	* @param driver - The PostgreSQL driver instance
+	*/
+	constructor(driver) {
+		this.driver = driver;
+	}
+	/**
+	* Execute a batch of sync instructions.
+	*
+	* @param instructions - Array of sync instructions
+	* @returns Total number of affected rows
+	*/
+	async executeBatch(instructions) {
+		let totalAffected = 0;
+		for (const instruction of instructions) if (instruction.isArrayUpdate) totalAffected += await this.executeArrayUpdate(instruction);
+		else totalAffected += await this.executeOne(instruction);
+		return totalAffected;
+	}
+	/**
+	* Execute a single sync instruction.
+	*
+	* @param instruction - Sync instruction
+	* @returns Number of affected rows
+	*/
+	async executeOne(instruction) {
+		const { targetTable, filter, update } = instruction;
+		return this.executeJsonbUpdate(targetTable, filter, update);
+	}
+	/**
+	* Execute an array update instruction with positional operators.
+	*
+	* @param instruction - Sync instruction with array update info
+	* @returns Number of affected rows
+	*/
+	async executeArrayUpdate(instruction) {
+		const { targetTable, filter, update, arrayField, identifierField, identifierValue } = instruction;
+		if (!arrayField || !identifierField || identifierValue === void 0) return this.executeOne(instruction);
+		return this.executeArrayElementUpdate(targetTable, filter, arrayField, { [identifierField]: identifierValue }, update);
+	}
+	/**
+	* Execute an update on JSONB fields.
+	*
+	* @param table - Table name
+	* @param filter - Row filter
+	* @param update - Fields to update
+	* @returns Number of affected rows
+	*/
+	async executeJsonbUpdate(table, filter, update) {
+		const quotedTable = this.driver.dialect.quoteIdentifier(table);
+		const setClauses = [];
+		const params = [];
+		let paramIndex = 1;
+		for (const [path, value] of Object.entries(update)) if (path.includes(".")) {
+			const [column, ...pathParts] = path.split(".");
+			const quotedColumn = this.driver.dialect.quoteIdentifier(column);
+			const jsonPath = `{${pathParts.join(",")}}`;
+			const placeholder = this.driver.dialect.placeholder(paramIndex++);
+			params.push(JSON.stringify(value));
+			setClauses.push(`${quotedColumn} = jsonb_set(COALESCE(${quotedColumn}, '{}'::jsonb), '${jsonPath}', ${placeholder}::jsonb)`);
+		} else {
+			const quotedColumn = this.driver.dialect.quoteIdentifier(path);
+			const placeholder = this.driver.dialect.placeholder(paramIndex++);
+			params.push(value);
+			setClauses.push(`${quotedColumn} = ${placeholder}`);
+		}
+		const whereClauses = [];
+		for (const [key, value] of Object.entries(filter)) if (key.includes(".")) {
+			const [column, ...pathParts] = key.split(".");
+			const quotedColumn = this.driver.dialect.quoteIdentifier(column);
+			const intermediateExpr = pathParts.slice(0, -1).map((p) => `->'${p}'`).join("");
+			const finalExpr = `->>'${pathParts[pathParts.length - 1]}'`;
+			const placeholder = this.driver.dialect.placeholder(paramIndex++);
+			params.push(value);
+			whereClauses.push(`${quotedColumn}${intermediateExpr}${finalExpr} = ${placeholder}`);
+		} else {
+			const quotedKey = this.driver.dialect.quoteIdentifier(key);
+			const placeholder = this.driver.dialect.placeholder(paramIndex++);
+			params.push(value);
+			whereClauses.push(`${quotedKey} = ${placeholder}`);
+		}
+		const sql = `UPDATE ${quotedTable} SET ${setClauses.join(", ")} WHERE ${whereClauses.join(" AND ")}`;
+		return (await this.driver.query(sql, params)).rowCount ?? 0;
+	}
+	/**
+	* Execute an update on elements within a JSONB array.
+	*
+	* @param table - Table name
+	* @param filter - Row filter
+	* @param arrayField - JSONB array column
+	* @param arrayFilter - Filter to match array elements
+	* @param update - Fields to update on matched elements
+	* @returns Number of affected rows
+	*/
+	async executeArrayElementUpdate(table, filter, arrayField, arrayFilter, update) {
+		const quotedTable = this.driver.dialect.quoteIdentifier(table);
+		const quotedArrayField = this.driver.dialect.quoteIdentifier(arrayField);
+		const params = [];
+		let paramIndex = 1;
+		const sql = `
+      WITH updated AS (
+        SELECT ctid, (
+          SELECT jsonb_agg(
+            CASE
+              WHEN ${Object.entries(arrayFilter).map(([key, value]) => {
+			params.push(value);
+			return `elem->>'${key}' = ${this.driver.dialect.placeholder(paramIndex++)}`;
+		}).join(" AND ")}
+              THEN elem || jsonb_build_object(${Object.entries(update).map(([key, value]) => {
+			params.push(JSON.stringify(value));
+			return `'${key}', ${this.driver.dialect.placeholder(paramIndex++)}::jsonb`;
+		}).join(", ")})
+              ELSE elem
+            END
+          )
+          FROM jsonb_array_elements(${quotedArrayField}) elem
+        ) AS new_array
+        FROM ${quotedTable}
+        WHERE ${Object.entries(filter).map(([key, value]) => {
+			const quotedKey = this.driver.dialect.quoteIdentifier(key);
+			params.push(value);
+			return `${quotedKey} = ${this.driver.dialect.placeholder(paramIndex++)}`;
+		}).join(" AND ")}
+      )
+      UPDATE ${quotedTable} t
+      SET ${quotedArrayField} = u.new_array
+      FROM updated u
+      WHERE t.ctid = u.ctid
+    `;
+		return (await this.driver.query(sql, params)).rowCount ?? 0;
+	}
+};
+
+//#endregion
+export { PostgresSyncAdapter };
+//# sourceMappingURL=postgres-sync-adapter.mjs.map

package/esm/drivers/postgres/postgres-sync-adapter.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"postgres-sync-adapter.mjs","names":[],"sources":["../../../../../../../@warlock.js/cascade/src/drivers/postgres/postgres-sync-adapter.ts"],"sourcesContent":["/**\r\n * PostgreSQL Sync Adapter\r\n *\r\n * Implements the SyncAdapterContract for batch update operations\r\n * on embedded/denormalized data in PostgreSQL.\r\n *\r\n * @module cascade/drivers/postgres\r\n */\r\n\r\nimport type { SyncAdapterContract, SyncInstruction } from \"../../contracts/sync-adapter.contract\";\r\nimport type { PostgresDriver } from \"./postgres-driver\";\r\n\r\n/**\r\n * PostgreSQL Sync Adapter.\r\n *\r\n * Handles batch updates for embedded/denormalized data stored\r\n * in JSONB columns. In a normalized SQL world, this is less common\r\n * than in MongoDB, but still useful for JSONB documents.\r\n *\r\n * @example\r\n * ```typescript\r\n * const syncAdapter = driver.syncAdapter();\r\n *\r\n * // Update embedded user data in posts\r\n * await syncAdapter.executeBatch([\r\n *   {\r\n *     targetTable: 'posts',\r\n *     filter: { 'author.id': 123 },\r\n *     update: { 'author.name': 'New Name' },\r\n *     // ... other fields\r\n *   }\r\n * ]);\r\n * ```\r\n */\r\nexport class PostgresSyncAdapter implements SyncAdapterContract {\r\n  /**\r\n   * Create a new sync adapter.\r\n   *\r\n   * @param driver - The PostgreSQL driver instance\r\n   */\r\n  public constructor(private readonly driver: PostgresDriver) {}\r\n\r\n  /**\r\n   * Execute a batch of sync instructions.\r\n   *\r\n   * @param instructions - Array of sync instructions\r\n   * @returns Total number of affected rows\r\n   */\r\n  public async executeBatch(instructions: SyncInstruction[]): Promise<number> {\r\n    let totalAffected = 0;\r\n\r\n    for (const instruction of instructions) {\r\n      if (instruction.isArrayUpdate) {\r\n        totalAffected += await this.executeArrayUpdate(instruction);\r\n      } else {\r\n        totalAffected += await this.executeOne(instruction);\r\n      }\r\n    }\r\n\r\n    return totalAffected;\r\n  }\r\n\r\n  /**\r\n   * Execute a single sync instruction.\r\n   *\r\n   * @param instruction - Sync instruction\r\n   * @returns Number of affected rows\r\n   */\r\n  public async executeOne(instruction: SyncInstruction): Promise<number> {\r\n    const { targetTable, filter, update } = instruction;\r\n    return this.executeJsonbUpdate(targetTable, filter, update);\r\n  }\r\n\r\n  /**\r\n   * Execute an array update instruction with positional operators.\r\n   *\r\n   * @param instruction - Sync instruction with array update info\r\n   * @returns Number of affected rows\r\n   */\r\n  public async executeArrayUpdate(instruction: SyncInstruction): Promise<number> {\r\n    const { targetTable, filter, update, arrayField, identifierField, identifierValue } =\r\n      instruction;\r\n\r\n    if (!arrayField || !identifierField || identifierValue === undefined) {\r\n      // Fall back to regular update if array info is missing\r\n      return this.executeOne(instruction);\r\n    }\r\n\r\n    return this.executeArrayElementUpdate(\r\n      targetTable,\r\n      filter,\r\n      arrayField,\r\n      { [identifierField]: identifierValue },\r\n      update,\r\n    );\r\n  }\r\n\r\n  /**\r\n   * Execute an update on JSONB fields.\r\n   *\r\n   * @param table - Table name\r\n   * @param filter - Row filter\r\n   * @param update - Fields to update\r\n   * @returns Number of affected rows\r\n   */\r\n  private async executeJsonbUpdate(\r\n    table: string,\r\n    filter: Record<string, unknown>,\r\n    update: Record<string, unknown>,\r\n  ): Promise<number> {\r\n    const quotedTable = this.driver.dialect.quoteIdentifier(table);\r\n    const setClauses: string[] = [];\r\n    const params: unknown[] = [];\r\n    let paramIndex = 1;\r\n\r\n    // Build SET clauses for each update field\r\n    for (const [path, value] of Object.entries(update)) {\r\n      if (path.includes(\".\")) {\r\n        // JSONB path update: \"column.nested.field\" -> jsonb_set\r\n        const [column, ...pathParts] = path.split(\".\");\r\n        const quotedColumn = this.driver.dialect.quoteIdentifier(column);\r\n        const jsonPath = `{${pathParts.join(\",\")}}`;\r\n        const placeholder = this.driver.dialect.placeholder(paramIndex++);\r\n        params.push(JSON.stringify(value));\r\n\r\n        setClauses.push(\r\n          `${quotedColumn} = jsonb_set(COALESCE(${quotedColumn}, '{}'::jsonb), '${jsonPath}', ${placeholder}::jsonb)`,\r\n        );\r\n      } else {\r\n        // Regular column update\r\n        const quotedColumn = this.driver.dialect.quoteIdentifier(path);\r\n        const placeholder = this.driver.dialect.placeholder(paramIndex++);\r\n        params.push(value);\r\n\r\n        setClauses.push(`${quotedColumn} = ${placeholder}`);\r\n      }\r\n    }\r\n\r\n    // Build WHERE clause\r\n    const whereClauses: string[] = [];\r\n    for (const [key, value] of Object.entries(filter)) {\r\n      if (key.includes(\".\")) {\r\n        // JSONB path filter: intermediate segments use -> (jsonb), final uses ->> (text).\r\n        // e.g. \"column.a\" → \"column\"->>'a', \"column.a.b\" → \"column\"->'a'->>'b'\r\n        const [column, ...pathParts] = key.split(\".\");\r\n        const quotedColumn = this.driver.dialect.quoteIdentifier(column);\r\n        const intermediateExpr = pathParts\r\n          .slice(0, -1)\r\n          .map((p) => `->'${p}'`)\r\n          .join(\"\");\r\n        const finalExpr = `->>'${pathParts[pathParts.length - 1]}'`;\r\n        const placeholder = this.driver.dialect.placeholder(paramIndex++);\r\n        params.push(value);\r\n\r\n        whereClauses.push(`${quotedColumn}${intermediateExpr}${finalExpr} = ${placeholder}`);\r\n      } else {\r\n        const quotedKey = this.driver.dialect.quoteIdentifier(key);\r\n        const placeholder = this.driver.dialect.placeholder(paramIndex++);\r\n        params.push(value);\r\n\r\n        whereClauses.push(`${quotedKey} = ${placeholder}`);\r\n      }\r\n    }\r\n\r\n    const sql = `UPDATE ${quotedTable} SET ${setClauses.join(\", \")} WHERE ${whereClauses.join(\" AND \")}`;\r\n\r\n    const result = await this.driver.query(sql, params);\r\n    return result.rowCount ?? 0;\r\n  }\r\n\r\n  /**\r\n   * Execute an update on elements within a JSONB array.\r\n   *\r\n   * @param table - Table name\r\n   * @param filter - Row filter\r\n   * @param arrayField - JSONB array column\r\n   * @param arrayFilter - Filter to match array elements\r\n   * @param update - Fields to update on matched elements\r\n   * @returns Number of affected rows\r\n   */\r\n  private async executeArrayElementUpdate(\r\n    table: string,\r\n    filter: Record<string, unknown>,\r\n    arrayField: string,\r\n    arrayFilter: Record<string, unknown>,\r\n    update: Record<string, unknown>,\r\n  ): Promise<number> {\r\n    const quotedTable = this.driver.dialect.quoteIdentifier(table);\r\n    const quotedArrayField = this.driver.dialect.quoteIdentifier(arrayField);\r\n\r\n    const params: unknown[] = [];\r\n    let paramIndex = 1;\r\n\r\n    // Build array element filter condition\r\n    const arrayFilterCondition = Object.entries(arrayFilter)\r\n      .map(([key, value]) => {\r\n        params.push(value);\r\n        return `elem->>'${key}' = ${this.driver.dialect.placeholder(paramIndex++)}`;\r\n      })\r\n      .join(\" AND \");\r\n\r\n    // Build update expression for matched elements\r\n    const updateExpr = Object.entries(update)\r\n      .map(([key, value]) => {\r\n        params.push(JSON.stringify(value));\r\n        return `'${key}', ${this.driver.dialect.placeholder(paramIndex++)}::jsonb`;\r\n      })\r\n      .join(\", \");\r\n\r\n    // Build WHERE clause for row filter\r\n    const whereClauses = Object.entries(filter).map(([key, value]) => {\r\n      const quotedKey = this.driver.dialect.quoteIdentifier(key);\r\n      params.push(value);\r\n      return `${quotedKey} = ${this.driver.dialect.placeholder(paramIndex++)}`;\r\n    });\r\n\r\n    // Use a CTE to update array elements.\r\n    // ctid is PostgreSQL's built-in physical row identifier, available on every\r\n    // table regardless of the primary key column name.\r\n    const sql = `\r\n      WITH updated AS (\r\n        SELECT ctid, (\r\n          SELECT jsonb_agg(\r\n            CASE\r\n              WHEN ${arrayFilterCondition}\r\n              THEN elem || jsonb_build_object(${updateExpr})\r\n              ELSE elem\r\n            END\r\n          )\r\n          FROM jsonb_array_elements(${quotedArrayField}) elem\r\n        ) AS new_array\r\n        FROM ${quotedTable}\r\n        WHERE ${whereClauses.join(\" AND \")}\r\n      )\r\n      UPDATE ${quotedTable} t\r\n      SET ${quotedArrayField} = u.new_array\r\n      FROM updated u\r\n      WHERE t.ctid = u.ctid\r\n    `;\r\n\r\n    const result = await this.driver.query(sql, params);\r\n    return result.rowCount ?? 0;\r\n  }\r\n}\r\n"],"mappings":"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"}

package/esm/drivers/postgres/types.d.mts

@@ -0,0 +1,105 @@
+//#region ../../@warlock.js/cascade/src/drivers/postgres/types.d.ts
+/**
+ * PostgreSQL Driver Types
+ *
+ * Type definitions specific to the PostgreSQL driver implementation.
+ *
+ * @module cascade/drivers/postgres
+ */
+/**
+ * PostgreSQL connection configuration options.
+ */
+type PostgresConnectionConfig = {
+  /** Database host (default: "localhost") */readonly host?: string; /** Database port (default: 5432) */
+  readonly port?: number; /** Database name */
+  readonly database: string; /** Database user */
+  readonly user?: string; /** Database password */
+  readonly password?: string; /** Connection string (alternative to individual options) */
+  readonly connectionString?: string; /** SSL configuration */
+  readonly ssl?: boolean | {
+    readonly rejectUnauthorized?: boolean;
+    readonly ca?: string;
+    readonly cert?: string;
+    readonly key?: string;
+  }; /** Enable database operation logging (queries, execution time, parameters) */
+  readonly logging?: boolean;
+};
+/**
+ * PostgreSQL pool configuration options.
+ */
+type PostgresPoolConfig = PostgresConnectionConfig & {
+  /** Maximum number of clients in the pool (default: 10) */readonly max?: number; /** Minimum number of clients in the pool (default: 0) */
+  readonly min?: number; /** How long a client can sit idle before being closed (ms) */
+  readonly idleTimeoutMillis?: number; /** How long to wait for a client before timing out (ms) */
+  readonly connectionTimeoutMillis?: number; /** Maximum times to use a connection before destroying it */
+  readonly maxUses?: number; /** Application name for connection identification */
+  readonly application_name?: string;
+};
+/**
+ * PostgreSQL query result wrapper.
+ */
+type PostgresQueryResult<T = Record<string, unknown>> = {
+  /** Array of rows returned by the query */readonly rows: T[]; /** Number of rows affected by INSERT/UPDATE/DELETE */
+  readonly rowCount: number | null; /** Column definitions from the result */
+  readonly fields: Array<{
+    readonly name: string;
+    readonly dataTypeID: number;
+  }>; /** Command that was executed (SELECT, INSERT, etc.) */
+  readonly command: string;
+};
+/**
+ * PostgreSQL transaction isolation levels.
+ */
+type PostgresIsolationLevel = "read uncommitted" | "read committed" | "repeatable read" | "serializable";
+/**
+ * PostgreSQL transaction options.
+ */
+type PostgresTransactionOptions = {
+  /** Isolation level for the transaction */readonly isolationLevel?: PostgresIsolationLevel; /** Whether the transaction is read-only */
+  readonly readOnly?: boolean; /** Use deferrable mode (for serializable + read-only) */
+  readonly deferrable?: boolean;
+};
+/**
+ * PostgreSQL-specific operation types used in the query builder.
+ */
+type PostgresOperation = {
+  /** Operation stage (select, where, join, etc.) */readonly stage: "select" | "from" | "join" | "where" | "groupBy" | "having" | "orderBy" | "limit" | "offset"; /** Operation type/name */
+  readonly type: string; /** Operation payload/data */
+  readonly data: Record<string, unknown>;
+};
+/**
+ * Internal representation of a pending WHERE clause.
+ */
+type PostgresWhereClause = {
+  /** Boolean operator to combine with previous clause */readonly boolean: "and" | "or"; /** Type of where clause */
+  readonly type: "basic" | "raw" | "null" | "notNull" | "in" | "notIn" | "between" | "notBetween" | "exists" | "notExists" | "nested" | "column"; /** Column/field name */
+  readonly column?: string; /** Comparison operator */
+  readonly operator?: string; /** Value to compare */
+  readonly value?: unknown; /** Raw SQL expression */
+  readonly raw?: string; /** Parameter bindings */
+  readonly bindings?: unknown[]; /** Nested conditions */
+  readonly nested?: PostgresWhereClause[];
+};
+/**
+ * PostgreSQL NOTIFY payload structure.
+ */
+type PostgresNotification = {
+  /** Channel name */readonly channel: string; /** Notification payload */
+  readonly payload?: string; /** Process ID of the notifying backend */
+  readonly processId: number;
+};
+/**
+ * PostgreSQL COPY options for bulk operations.
+ */
+type PostgresCopyOptions = {
+  /** Format (text, csv, binary) */readonly format?: "text" | "csv" | "binary"; /** Field delimiter for text/csv */
+  readonly delimiter?: string; /** Quote character for csv */
+  readonly quote?: string; /** Escape character for csv */
+  readonly escape?: string; /** Include header row */
+  readonly header?: boolean; /** Null string representation */
+  readonly null?: string; /** Column list */
+  readonly columns?: string[];
+};
+//#endregion
+export { PostgresConnectionConfig, PostgresCopyOptions, PostgresIsolationLevel, PostgresNotification, PostgresOperation, PostgresPoolConfig, PostgresQueryResult, PostgresTransactionOptions, PostgresWhereClause };
+//# sourceMappingURL=types.d.mts.map

package/esm/drivers/postgres/types.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.mts","names":[],"sources":["../../../../../../../@warlock.js/cascade/src/drivers/postgres/types.ts"],"mappings":";;AAWA;;;;;;;;;KAAY,wBAAA;EAcD,oDAZA,IAAA,WAgBM;EAAA,SAdN,IAAA,WAgBM;EAAA,SAdN,QAAA,UAiBO;EAAA,SAfP,IAAA,WAqBC;EAAA,SAnBD,QAAA;WAEA,gBAAA,WAiBsB;EAAA,SAftB,GAAA;IAAA,SAGM,kBAAA;IAAA,SACA,EAAA;IAAA,SACA,IAAA;IAAA,SACA,GAAA;EAAA,GAqBU;EAAA,SAlBhB,OAAA;AAAA;;;;KAMC,kBAAA,GAAqB,wBAAwB;EAwBtC,mEAtBR,GAAA,WAsBa;EAAA,SApBb,GAAA,WAcyB;EAAA,SAZzB,iBAAA,WAcM;EAAA,SAZN,uBAAA,WAgBA;EAAA,SAdA,OAAA,WAeE;EAAA,SAbF,gBAAA;AAAA;;AAiBO;AAMlB;KAjBY,mBAAA,KAAwB,MAAA;qDAEzB,IAAA,EAAM,CAAA,IAeiB;EAAA,SAbvB,QAAA,iBAsB2B;EAAA,SApB3B,MAAA,EAAQ,KAAA;IAAA,SACN,IAAA;IAAA,SACA,UAAA;EAAA,IAsBF;EAAA,SAnBA,OAAA;AAAA;AAqBU;AAMrB;;AANqB,KAfT,sBAAA;;;;KASA,0BAAA;EA2BK,mDAzBN,cAAA,GAAiB,sBAAsB,EAyB3B;EAAA,SAvBZ,QAAA,YA6BoB;EAAA,SA3BpB,UAAA;AAAA;;;;KAMC,iBAAA;EA2CD,2DAzCA,KAAA,gGA6CA;EAAA,SAlCA,IAAA,UAoCS;EAAA,SAlCT,IAAA,EAAM,MAAM;AAAA;AAwCvB;;;AAAA,KAlCY,mBAAA;EAoCD,gEAlCA,OAAA,gBAsCA;EAAA,SApCA,IAAA,mIAoCS;EAAA,SAtBT,MAAA,WA4BoB;EAAA,SA1BpB,QAAA,WA0BoB;EAAA,SAxBpB,KAAA,YA4BA;EAAA,SA1BA,GAAA,WA8BA;EAAA,SA5BA,QAAA,cAgCA;EAAA,SA9BA,MAAA,GAAS,mBAAmB;AAAA;AAgCrB;;;AAAA,KA1BN,oBAAA;8BAED,OAAA;WAEA,OAAA;WAEA,SAAA;AAAA;;;;KAMC,mBAAA;4CAED,MAAA;WAEA,SAAA;WAEA,KAAA;WAEA,MAAA;WAEA,MAAA;WAEA,IAAA;WAEA,OAAA;AAAA"}

package/esm/drivers/sql/sql-dialect.contract.d.mts

@@ -0,0 +1,221 @@
+import { AggregateExpression } from "../../expressions/aggregate-expressions.mjs";
+
+//#region ../../@warlock.js/cascade/src/drivers/sql/sql-dialect.contract.d.ts
+/**
+ * Contract that SQL dialects must implement to handle database-specific
+ * SQL syntax variations.
+ *
+ * Each SQL database (PostgreSQL, MySQL, SQLite) has subtle differences
+ * in how they handle parameters, identifiers, and certain SQL features.
+ * This interface abstracts those differences.
+ *
+ * @example
+ * ```typescript
+ * class PostgresDialect implements SqlDialectContract {
+ *   placeholder(index: number): string {
+ *     return `$${index}`;  // PostgreSQL uses $1, $2, etc.
+ *   }
+ * }
+ *
+ * class MySqlDialect implements SqlDialectContract {
+ *   placeholder(index: number): string {
+ *     return '?';  // MySQL uses ? for all parameters
+ *   }
+ * }
+ * ```
+ */
+interface SqlDialectContract {
+  /**
+   * The name of the dialect for identification purposes.
+   *
+   * @example "postgres", "mysql", "sqlite"
+   */
+  readonly name: string;
+  /**
+   * Generate a parameter placeholder for the given index.
+   *
+   * Different databases use different placeholder styles:
+   * - PostgreSQL: `$1`, `$2`, `$3`
+   * - MySQL/SQLite: `?` (positional)
+   *
+   * @param index - The 1-based parameter index
+   * @returns The placeholder string to use in the SQL query
+   *
+   * @example
+   * ```typescript
+   * dialect.placeholder(1); // "$1" for PostgreSQL
+   * dialect.placeholder(2); // "?" for MySQL
+   * ```
+   */
+  placeholder(index: number): string;
+  /**
+   * Quote an identifier (table name, column name) for safe use in SQL.
+   *
+   * Different databases use different quote characters:
+   * - PostgreSQL: `"column_name"`
+   * - MySQL: `` `column_name` ``
+   *
+   * This also handles escaping if the identifier contains the quote character.
+   *
+   * @param identifier - The identifier to quote
+   * @returns The quoted identifier safe for use in SQL
+   *
+   * @example
+   * ```typescript
+   * dialect.quoteIdentifier('user'); // '"user"' for PostgreSQL
+   * dialect.quoteIdentifier('order'); // '`order`' for MySQL
+   * ```
+   */
+  quoteIdentifier(identifier: string): string;
+  /**
+   * Convert a boolean value to the appropriate SQL literal.
+   *
+   * Different databases represent booleans differently:
+   * - PostgreSQL: `TRUE` / `FALSE`
+   * - MySQL: `1` / `0`
+   *
+   * @param value - The boolean value to convert
+   * @returns The SQL literal string
+   *
+   * @example
+   * ```typescript
+   * dialect.booleanLiteral(true); // "TRUE" for PostgreSQL
+   * dialect.booleanLiteral(false); // "0" for MySQL
+   * ```
+   */
+  booleanLiteral(value: boolean): string;
+  /**
+   * Whether the database supports the RETURNING clause for INSERT/UPDATE/DELETE.
+   *
+   * - PostgreSQL: `true` (supports `RETURNING *`)
+   * - MySQL: `false` (must use `LAST_INSERT_ID()`)
+   */
+  readonly supportsReturning: boolean;
+  /**
+   * The keyword used for upsert (insert or update) operations.
+   *
+   * - PostgreSQL: `"ON CONFLICT"`
+   * - MySQL: `"ON DUPLICATE KEY"`
+   */
+  readonly upsertKeyword: "ON CONFLICT" | "ON DUPLICATE KEY";
+  /**
+   * Build the LIMIT/OFFSET clause for pagination.
+   *
+   * Most databases use `LIMIT x OFFSET y`, but syntax may vary.
+   *
+   * @param limit - Maximum number of rows to return (undefined = no limit)
+   * @param offset - Number of rows to skip (undefined = no offset)
+   * @returns The SQL clause string (e.g., "LIMIT 10 OFFSET 20")
+   *
+   * @example
+   * ```typescript
+   * dialect.limitOffset(10, 20); // "LIMIT 10 OFFSET 20"
+   * dialect.limitOffset(10);     // "LIMIT 10"
+   * dialect.limitOffset(undefined, 20); // "OFFSET 20"
+   * ```
+   */
+  limitOffset(limit?: number, offset?: number): string;
+  /**
+   * Build a JSON path extraction expression.
+   *
+   * Different databases have different JSON operators:
+   * - PostgreSQL: `column->>'path'` or `column->'path'`
+   * - MySQL: `JSON_EXTRACT(column, '$.path')`
+   *
+   * @param column - The JSON/JSONB column name
+   * @param path - The path to extract (dot notation)
+   * @returns The SQL expression for extracting the path
+   *
+   * @example
+   * ```typescript
+   * dialect.jsonExtract('data', 'user.name');
+   * // PostgreSQL: "data"->>'user'->>'name'
+   * // MySQL: JSON_EXTRACT("data", '$.user.name')
+   * ```
+   */
+  jsonExtract(column: string, path: string): string;
+  /**
+   * Check if a JSON column contains a value.
+   *
+   * - PostgreSQL: `column @> '{"key": "value"}'::jsonb`
+   * - MySQL: `JSON_CONTAINS(column, '"value"', '$.key')`
+   *
+   * @param column - The JSON/JSONB column name
+   * @param value - The value to check for
+   * @param path - Optional path within the JSON
+   * @returns The SQL expression
+   */
+  jsonContains(column: string, value: unknown, path?: string): string;
+  /**
+   * Build a LIKE pattern with proper escaping.
+   *
+   * @param pattern - The pattern (may include % and _ wildcards)
+   * @param caseInsensitive - Whether to use case-insensitive matching
+   * @returns Object with the SQL operator and escaped pattern
+   *
+   * @example
+   * ```typescript
+   * dialect.likePattern('%test%', true);
+   * // PostgreSQL: { operator: 'ILIKE', pattern: '%test%' }
+   * // MySQL: { operator: 'LIKE', pattern: '%test%' } (case-insensitive by default)
+   * ```
+   */
+  likePattern(pattern: string, caseInsensitive?: boolean): {
+    operator: string;
+    pattern: string;
+  };
+  /**
+   * Build an array contains expression.
+   *
+   * - PostgreSQL: `$1 = ANY(column)` or `column @> ARRAY[$1]`
+   * - MySQL: `JSON_CONTAINS(column, ...)` for JSON arrays
+   *
+   * @param column - The array column name
+   * @param paramIndex - The parameter index for the value
+   * @returns The SQL expression
+   */
+  arrayContains(column: string, paramIndex: number): string;
+  /**
+   * Get the SQL type name for common abstract types.
+   *
+   * @param type - The abstract type name
+   * @param options - Type-specific options (length, precision, scale)
+   * @returns The database-specific SQL type
+   *
+   * @example
+   * ```typescript
+   * dialect.getSqlType('string', { length: 255 }); // "VARCHAR(255)"
+   * dialect.getSqlType('json'); // "JSONB" for PostgreSQL, "JSON" for MySQL
+   * ```
+   */
+  getSqlType(type: string, options?: {
+    length?: number;
+    precision?: number;
+    scale?: number;
+    dimensions?: number;
+  }): string;
+  /**
+   * Translate a database-agnostic aggregate expression to its SQL form.
+   *
+   * Supported aggregates return their SQL function call. Aggregates a given
+   * dialect cannot express as a scalar `GROUP BY` aggregate (e.g. `distinct`,
+   * `floor`, `first`, `last` on PostgreSQL) MUST throw with an actionable
+   * message naming the SQL escape hatch — never emit a silently-different
+   * semantic. Making this part of the contract forces every SQL dialect to
+   * decide its own aggregate capability matrix explicitly.
+   *
+   * @param expression - The abstract aggregate (`$agg.*`) to translate
+   * @returns The SQL fragment (e.g. `SUM("amount")`, `COUNT(*)`)
+   *
+   * @example
+   * ```typescript
+   * dialect.aggregateToSql($agg.sum("amount")); // 'SUM("amount")'
+   * dialect.aggregateToSql($agg.count());       // "COUNT(*)"
+   * dialect.aggregateToSql($agg.distinct("c")); // throws — use selectRaw escape hatch
+   * ```
+   */
+  aggregateToSql(expression: AggregateExpression): string;
+}
+//#endregion
+export { SqlDialectContract };
+//# sourceMappingURL=sql-dialect.contract.d.mts.map

package/esm/drivers/sql/sql-dialect.contract.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sql-dialect.contract.d.mts","names":[],"sources":["../../../../../../../@warlock.js/cascade/src/drivers/sql/sql-dialect.contract.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;UAmCiB,kBAAA;EA4Kf;;;;;EAAA,SAtKS,IAAA;EAwKP;;;;;AAuB4C;;;;;;;;;;;EA7K9C,WAAA,CAAY,KAAA;;;;;;;;;;;;;;;;;;;EAoBZ,eAAA,CAAgB,UAAA;;;;;;;;;;;;;;;;;EAkBhB,cAAA,CAAe,KAAA;;;;;;;WAQN,iBAAA;;;;;;;WAQA,aAAA;;;;;;;;;;;;;;;;;EAkBT,WAAA,CAAY,KAAA,WAAgB,MAAA;;;;;;;;;;;;;;;;;;;EAoB5B,WAAA,CAAY,MAAA,UAAgB,IAAA;;;;;;;;;;;;EAa5B,YAAA,CAAa,MAAA,UAAgB,KAAA,WAAgB,IAAA;;;;;;;;;;;;;;;EAgB7C,WAAA,CAAY,OAAA,UAAiB,eAAA;IAA8B,QAAA;IAAkB,OAAA;EAAA;;;;;;;;;;;EAY7E,aAAA,CAAc,MAAA,UAAgB,UAAA;;;;;;;;;;;;;;EAe9B,UAAA,CACE,IAAA,UACA,OAAA;IAAY,MAAA;IAAiB,SAAA;IAAoB,KAAA;IAAgB,UAAA;EAAA;;;;;;;;;;;;;;;;;;;;;EAuBnE,cAAA,CAAe,UAAA,EAAY,mBAAmB;AAAA"}

package/esm/drivers/sql/sql-types.d.mts

@@ -0,0 +1,150 @@
+//#region ../../@warlock.js/cascade/src/drivers/sql/sql-types.d.ts
+/**
+ * SQL Types and Definitions
+ *
+ * Shared type definitions used across SQL database drivers (PostgreSQL, MySQL, SQLite).
+ * These types represent common SQL operations and their parameters.
+ *
+ * @module cascade/drivers/sql
+ */
+/**
+ * Result of building a SQL query with parameterized values.
+ *
+ * Contains the SQL string with placeholders and the corresponding parameter values.
+ * This separation prevents SQL injection by ensuring values are properly escaped.
+ */
+type SqlQueryResult = {
+  /** The SQL query string with parameter placeholders ($1, $2, etc. or ?) */readonly sql: string; /** The parameter values in order matching the placeholders */
+  readonly params: unknown[];
+};
+/**
+ * Supported SQL JOIN types.
+ */
+type SqlJoinType = "inner" | "left" | "right" | "full" | "cross";
+/**
+ * SQL JOIN clause definition.
+ *
+ * Represents a JOIN between two tables with its condition.
+ */
+type SqlJoinClause = {
+  /** Type of JOIN operation */readonly type: SqlJoinType; /** Target table to join */
+  readonly table: string; /** Optional alias for the joined table */
+  readonly alias?: string; /** JOIN condition */
+  readonly on: {
+    /** Field from the left (current) table */readonly left: string; /** Comparison operator (usually "=") */
+    readonly operator: string; /** Field from the right (joined) table */
+    readonly right: string;
+  }; /** Additional ON conditions (for complex joins) */
+  readonly additionalConditions?: Array<{
+    readonly left: string;
+    readonly operator: string;
+    readonly right: string;
+  }>;
+};
+/**
+ * SQL ORDER BY clause definition.
+ */
+type SqlOrderClause = {
+  /** Column to order by */readonly column: string; /** Sort direction */
+  readonly direction: "asc" | "desc"; /** Nulls position (PostgreSQL-specific) */
+  readonly nulls?: "first" | "last";
+};
+/**
+ * SQL GROUP BY clause definition.
+ */
+type SqlGroupClause = {
+  /** Columns to group by */readonly columns: string[];
+};
+/**
+ * SQL HAVING clause condition.
+ */
+type SqlHavingClause = {
+  /** Aggregate function (count, sum, avg, etc.) */readonly aggregate: string; /** Column the aggregate operates on */
+  readonly column: string; /** Comparison operator */
+  readonly operator: string; /** Value to compare against */
+  readonly value: unknown;
+};
+/**
+ * SQL WHERE clause operation types.
+ */
+type SqlWhereType = "where" | "orWhere" | "whereRaw" | "orWhereRaw" | "whereNot" | "orWhereNot" | "whereExists" | "whereNotExists";
+/**
+ * SQL WHERE clause operation.
+ *
+ * Represents a single WHERE condition with its type, field, operator, and value.
+ */
+type SqlWhereOperation = {
+  /** Type of WHERE clause (where, orWhere, whereRaw, etc.) */readonly type: SqlWhereType; /** Field name (for standard where clauses) */
+  readonly field?: string; /** Comparison operator */
+  readonly operator?: string; /** Value to compare against */
+  readonly value?: unknown; /** Raw SQL expression (for whereRaw clauses) */
+  readonly raw?: string; /** Parameter bindings for raw expressions */
+  readonly bindings?: unknown[]; /** Nested conditions (for grouped where clauses) */
+  readonly nested?: SqlWhereOperation[];
+};
+/**
+ * SQL SELECT clause definition.
+ */
+type SqlSelectClause = {
+  /** Column name or expression */readonly expression: string; /** Optional alias for the column */
+  readonly alias?: string; /** Whether this is a raw expression */
+  readonly isRaw?: boolean;
+};
+/**
+ * Configuration for building SQL queries.
+ */
+type SqlQueryConfig = {
+  /** Target table name */readonly table: string; /** Table alias (optional) */
+  readonly alias?: string; /** SELECT columns (empty = SELECT *) */
+  readonly select: SqlSelectClause[]; /** JOIN clauses */
+  readonly joins: SqlJoinClause[]; /** WHERE conditions */
+  readonly where: SqlWhereOperation[]; /** GROUP BY columns */
+  readonly groupBy: string[]; /** HAVING conditions */
+  readonly having: SqlHavingClause[]; /** ORDER BY clauses */
+  readonly orderBy: SqlOrderClause[]; /** LIMIT value */
+  readonly limit?: number; /** OFFSET value */
+  readonly offset?: number; /** DISTINCT flag */
+  readonly distinct?: boolean;
+};
+/**
+ * SQL INSERT operation definition.
+ */
+type SqlInsertOperation = {
+  /** Target table */readonly table: string; /** Column names */
+  readonly columns: string[]; /** Values to insert (array of arrays for multi-row insert) */
+  readonly values: unknown[][]; /** Whether to return the inserted rows */
+  readonly returning?: string[] | boolean; /** Conflict resolution (upsert) */
+  readonly onConflict?: {
+    readonly columns: string[];
+    readonly action: "update" | "nothing";
+    readonly updateColumns?: string[];
+  };
+};
+/**
+ * SQL UPDATE operation definition.
+ */
+type SqlUpdateOperation = {
+  /** Target table */readonly table: string; /** Columns to set with their values */
+  readonly set: Record<string, unknown>; /** Columns to increment */
+  readonly increment?: Record<string, number>; /** Columns to set to NULL */
+  readonly unset?: string[]; /** WHERE conditions */
+  readonly where: SqlWhereOperation[]; /** Whether to return updated rows */
+  readonly returning?: string[] | boolean; /** Maximum rows to update (some databases support LIMIT in UPDATE) */
+  readonly limit?: number;
+};
+/**
+ * SQL DELETE operation definition.
+ */
+type SqlDeleteOperation = {
+  /** Target table */readonly table: string; /** WHERE conditions */
+  readonly where: SqlWhereOperation[]; /** Whether to return deleted rows */
+  readonly returning?: string[] | boolean; /** Maximum rows to delete */
+  readonly limit?: number;
+};
+/**
+ * Aggregate function types supported in SQL.
+ */
+type SqlAggregateFunction = "count" | "sum" | "avg" | "min" | "max" | "array_agg" | "string_agg" | "jsonb_agg";
+//#endregion
+export { SqlAggregateFunction, SqlDeleteOperation, SqlGroupClause, SqlHavingClause, SqlInsertOperation, SqlJoinClause, SqlJoinType, SqlOrderClause, SqlQueryConfig, SqlQueryResult, SqlSelectClause, SqlUpdateOperation, SqlWhereOperation, SqlWhereType };
+//# sourceMappingURL=sql-types.d.mts.map