@comity/sql-kysely 0.9.0 → 0.9.1

package/README.md

@@ -53,7 +53,3 @@ No exhaustive reference; see docs for constraints.
 ## Status
 
 Stable
-
-_Review Completed: 2026-07-25_
-_Reviewer: Hobiri MAGI (DeepSeek v4 Pro)_
-_Compliance Score: 99.5% (Green)_

package/dist/cjs/batch/execute.js

@@ -0,0 +1,122 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.executeAtomicBatch = executeAtomicBatch;
+const errors_1 = require("@comity/sql/errors");
+const map_sql_error_js_1 = require("../internal/map-sql-error.js");
+/**
+ * Validate the complete batch before any execution is attempted.
+ *
+ * @param queries - Immutable SQL query payloads
+ * @param adapter - Adapter name for diagnostics
+ *
+ * @returns The normalised statements, or a failure when validation fails
+ */
+function prepareBatch(queries, adapter) {
+    const statements = [];
+    for (const query of queries) {
+        // Named parameters are unsupported by the existing execution path, so the
+        // batch path MUST NOT introduce a second parameter model.
+        if (query.params && !Array.isArray(query.params)) {
+            return {
+                success: false,
+                error: new errors_1.SqlError("invalid_query", {
+                    details: { retriable: false, adapter, operation: "batch" },
+                    context: { violation: "named_parameters" },
+                }),
+            };
+        }
+        statements.push({
+            statement: query.statement,
+            params: (query.params ?? []),
+        });
+    }
+    return { success: true, value: statements };
+}
+/**
+ * Map an executor statement result onto the generic SqlResult representation.
+ *
+ * @param result - Executor result for a single statement
+ *
+ * @returns SqlResult with mapped row count
+ */
+function toSqlResult(result) {
+    return {
+        rows: result.rows,
+        rowCount: typeof result.numAffectedRows === "bigint"
+            ? Number(result.numAffectedRows)
+            : result.rows.length,
+    };
+}
+/**
+ * Execute a batch of statements atomically via the injected executor.
+ *
+ * @param queries - Immutable SQL query payloads, executed in order
+ * @param executor - Atomic batch executor supplied by composition
+ * @param adapter - Adapter name for diagnostics
+ *
+ * @returns Operation result wrapping a SqlBatchResult aligned with `queries`
+ *
+ * @throws Errors are not thrown; failures are returned via SqlOperationResult
+ *
+ * @remarks
+ * Validation of the whole batch completes before the executor is invoked, so an
+ * invalid statement can never result in a partial execution.
+ *
+ * Atomicity is provided by the executor, not by this function. This function
+ * MUST NOT fall back to sequential execution or to a transaction, because either
+ * would violate the all-or-nothing guarantee. A failure yields exactly one
+ * SqlError and no partial result; the failing statement index is not reported
+ * because the contract does not define one.
+ */
+async function executeAtomicBatch(queries, executor, adapter) {
+    // An empty batch is rejected before the executor is consulted, so behaviour is
+    // deterministic and independent of whether an executor was supplied.
+    if (queries.length === 0) {
+        return {
+            success: false,
+            error: new errors_1.SqlError("invalid_query", {
+                details: { retriable: false, adapter, operation: "batch" },
+                context: { violation: "empty_batch" },
+            }),
+        };
+    }
+    // An unsupported capability is a configuration failure, not an exception.
+    if (!executor) {
+        return {
+            success: false,
+            error: new errors_1.SqlError("invalid_configuration", {
+                details: { retriable: false, adapter, operation: "batch" },
+                context: { violation: "atomic_batch_executor_missing" },
+            }),
+        };
+    }
+    const prepared = prepareBatch(queries, adapter);
+    if (!prepared.success) {
+        return prepared;
+    }
+    try {
+        const results = await executor.execute(prepared.value);
+        // The executor guarantees positional alignment; a mismatch is a defect in
+        // the injected implementation and is surfaced rather than silently accepted.
+        if (results.length !== queries.length) {
+            return {
+                success: false,
+                error: new errors_1.SqlError("query_failed", {
+                    details: { retriable: false, adapter, operation: "batch" },
+                    context: { violation: "executor_result_count_mismatch" },
+                }),
+            };
+        }
+        return {
+            success: true,
+            value: results.map(toSqlResult),
+        };
+    }
+    catch (e) {
+        return {
+            success: false,
+            error: (0, map_sql_error_js_1.mapSqlError)(e, "batch", adapter),
+        };
+    }
+}
+//# sourceMappingURL=execute.js.map

package/dist/cjs/client/create-kysely.js

@@ -1,8 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createKyselySqlClient = createKyselySqlClient;
-const execute_js_1 = require("../query/execute.js");
-const execute_js_2 = require("../transaction/execute.js");
+const execute_js_1 = require("../batch/execute.js");
+const execute_js_2 = require("../query/execute.js");
+const execute_js_3 = require("../transaction/execute.js");
 /**
  * Create a SqlClient backed by a Kysely database instance.
  *
@@ -21,9 +22,11 @@ const execute_js_2 = require("../transaction/execute.js");
 function createKyselySqlClient(options) {
     return {
         /** @inheritdoc  */
-        query: (q) => (0, execute_js_1.executeQuery)(options.db, q, options.adapter),
+        query: (q) => (0, execute_js_2.executeQuery)(options.db, q, options.adapter),
         /** @inheritdoc */
-        begin: () => (0, execute_js_2.executeTransaction)(options.db, options.adapter),
+        begin: () => (0, execute_js_3.executeTransaction)(options.db, options.adapter),
+        /** @inheritdoc */
+        atomicBatch: (queries) => (0, execute_js_1.executeAtomicBatch)(queries, options.atomicBatchExecutor, options.adapter),
     };
 }
 //# sourceMappingURL=create-kysely.js.map

package/dist/esm/batch/execute.js

@@ -0,0 +1,119 @@
+import { SqlError } from "@comity/sql/errors";
+import { mapSqlError } from "../internal/map-sql-error.js";
+/**
+ * Validate the complete batch before any execution is attempted.
+ *
+ * @param queries - Immutable SQL query payloads
+ * @param adapter - Adapter name for diagnostics
+ *
+ * @returns The normalised statements, or a failure when validation fails
+ */
+function prepareBatch(queries, adapter) {
+    const statements = [];
+    for (const query of queries) {
+        // Named parameters are unsupported by the existing execution path, so the
+        // batch path MUST NOT introduce a second parameter model.
+        if (query.params && !Array.isArray(query.params)) {
+            return {
+                success: false,
+                error: new SqlError("invalid_query", {
+                    details: { retriable: false, adapter, operation: "batch" },
+                    context: { violation: "named_parameters" },
+                }),
+            };
+        }
+        statements.push({
+            statement: query.statement,
+            params: (query.params ?? []),
+        });
+    }
+    return { success: true, value: statements };
+}
+/**
+ * Map an executor statement result onto the generic SqlResult representation.
+ *
+ * @param result - Executor result for a single statement
+ *
+ * @returns SqlResult with mapped row count
+ */
+function toSqlResult(result) {
+    return {
+        rows: result.rows,
+        rowCount: typeof result.numAffectedRows === "bigint"
+            ? Number(result.numAffectedRows)
+            : result.rows.length,
+    };
+}
+/**
+ * Execute a batch of statements atomically via the injected executor.
+ *
+ * @param queries - Immutable SQL query payloads, executed in order
+ * @param executor - Atomic batch executor supplied by composition
+ * @param adapter - Adapter name for diagnostics
+ *
+ * @returns Operation result wrapping a SqlBatchResult aligned with `queries`
+ *
+ * @throws Errors are not thrown; failures are returned via SqlOperationResult
+ *
+ * @remarks
+ * Validation of the whole batch completes before the executor is invoked, so an
+ * invalid statement can never result in a partial execution.
+ *
+ * Atomicity is provided by the executor, not by this function. This function
+ * MUST NOT fall back to sequential execution or to a transaction, because either
+ * would violate the all-or-nothing guarantee. A failure yields exactly one
+ * SqlError and no partial result; the failing statement index is not reported
+ * because the contract does not define one.
+ */
+export async function executeAtomicBatch(queries, executor, adapter) {
+    // An empty batch is rejected before the executor is consulted, so behaviour is
+    // deterministic and independent of whether an executor was supplied.
+    if (queries.length === 0) {
+        return {
+            success: false,
+            error: new SqlError("invalid_query", {
+                details: { retriable: false, adapter, operation: "batch" },
+                context: { violation: "empty_batch" },
+            }),
+        };
+    }
+    // An unsupported capability is a configuration failure, not an exception.
+    if (!executor) {
+        return {
+            success: false,
+            error: new SqlError("invalid_configuration", {
+                details: { retriable: false, adapter, operation: "batch" },
+                context: { violation: "atomic_batch_executor_missing" },
+            }),
+        };
+    }
+    const prepared = prepareBatch(queries, adapter);
+    if (!prepared.success) {
+        return prepared;
+    }
+    try {
+        const results = await executor.execute(prepared.value);
+        // The executor guarantees positional alignment; a mismatch is a defect in
+        // the injected implementation and is surfaced rather than silently accepted.
+        if (results.length !== queries.length) {
+            return {
+                success: false,
+                error: new SqlError("query_failed", {
+                    details: { retriable: false, adapter, operation: "batch" },
+                    context: { violation: "executor_result_count_mismatch" },
+                }),
+            };
+        }
+        return {
+            success: true,
+            value: results.map(toSqlResult),
+        };
+    }
+    catch (e) {
+        return {
+            success: false,
+            error: mapSqlError(e, "batch", adapter),
+        };
+    }
+}
+//# sourceMappingURL=execute.js.map

package/dist/esm/client/create-kysely.js

@@ -1,3 +1,4 @@
+import { executeAtomicBatch } from "../batch/execute.js";
 import { executeQuery } from "../query/execute.js";
 import { executeTransaction } from "../transaction/execute.js";
 /**
@@ -21,6 +22,8 @@ export function createKyselySqlClient(options) {
         query: (q) => executeQuery(options.db, q, options.adapter),
         /** @inheritdoc */
         begin: () => executeTransaction(options.db, options.adapter),
+        /** @inheritdoc */
+        atomicBatch: (queries) => executeAtomicBatch(queries, options.atomicBatchExecutor, options.adapter),
     };
 }
 //# sourceMappingURL=create-kysely.js.map

package/dist/types/batch/execute.d.ts

@@ -0,0 +1,24 @@
+import type { SqlBatchResult, SqlOperationResult, SqlQuery } from "@comity/sql";
+import type { KyselyAtomicBatchExecutor } from "../client/types.js";
+/**
+ * Execute a batch of statements atomically via the injected executor.
+ *
+ * @param queries - Immutable SQL query payloads, executed in order
+ * @param executor - Atomic batch executor supplied by composition
+ * @param adapter - Adapter name for diagnostics
+ *
+ * @returns Operation result wrapping a SqlBatchResult aligned with `queries`
+ *
+ * @throws Errors are not thrown; failures are returned via SqlOperationResult
+ *
+ * @remarks
+ * Validation of the whole batch completes before the executor is invoked, so an
+ * invalid statement can never result in a partial execution.
+ *
+ * Atomicity is provided by the executor, not by this function. This function
+ * MUST NOT fall back to sequential execution or to a transaction, because either
+ * would violate the all-or-nothing guarantee. A failure yields exactly one
+ * SqlError and no partial result; the failing statement index is not reported
+ * because the contract does not define one.
+ */
+export declare function executeAtomicBatch(queries: readonly Readonly<SqlQuery>[], executor: KyselyAtomicBatchExecutor | undefined, adapter: string): Promise<SqlOperationResult<SqlBatchResult>>;

package/dist/types/client/create-kysely.d.ts

@@ -1,5 +1,6 @@
 import type { SqlClient, SqlClientOptions } from "@comity/sql";
 import type { Kysely } from "kysely";
+import type { KyselyAtomicBatchExecutor } from "./types.js";
 /**
  * Kysely client factory options.
  *
@@ -10,6 +11,15 @@ export interface KyselySqlClientOptions<DB> extends SqlClientOptions {
     readonly db: Kysely<DB>;
     /** Adapter name for diagnostics */
     readonly adapter: string;
+    /**
+     * Executor providing atomic all-or-nothing multi-statement execution.
+     *
+     * @remarks
+     * Injected by composition because Kysely exposes no such primitive. When
+     * omitted, `atomicBatch` reports `invalid_configuration` rather than falling
+     * back to sequential execution.
+     */
+    readonly atomicBatchExecutor?: KyselyAtomicBatchExecutor;
 }
 /**
  * Create a SqlClient backed by a Kysely database instance.

package/dist/types/client/types.d.ts

@@ -1,4 +1,58 @@
 import type { Compilable } from "kysely";
+/**
+ * A single already-parameterised statement submitted to an atomic batch executor.
+ *
+ * @remarks
+ * Deliberately free of Comity and database-engine concepts. It carries only
+ * normalised SQL text and positional parameters.
+ */
+export interface KyselyAtomicStatement {
+    /** Normalised SQL statement text */
+    readonly statement: string;
+    /** Positional parameters bound to `statement` */
+    readonly params: readonly unknown[];
+}
+/**
+ * Outcome of a single statement within an atomic batch.
+ */
+export interface KyselyAtomicStatementResult {
+    /** Rows produced by the statement */
+    readonly rows: readonly unknown[];
+    /** Optional affected rows count */
+    readonly numAffectedRows?: bigint;
+}
+/**
+ * Executes a set of already-parameterised statements as one all-or-nothing
+ * operation and returns one result per statement in input order.
+ *
+ * @remarks
+ * This abstraction exists because Kysely's public API does not expose an atomic
+ * multi-statement primitive. Composition injects the implementation that
+ * provides one, for example by delegating to a database-specific batch call.
+ *
+ * Implementations MUST provide all-or-nothing semantics: either every statement
+ * takes effect, or none does. They MUST NOT apply retries, sequential fallback,
+ * or compensation.
+ *
+ * Implementations MUST NOT assume atomicity on their own behalf; an
+ * implementation that cannot guarantee it must not be injected here.
+ *
+ * The adapter maps `numAffectedRows` to `SqlResult.rowCount`. A statement that
+ * affects zero rows is still a successful result; the executor MUST NOT treat a
+ * zero count as a failure.
+ */
+export interface KyselyAtomicBatchExecutor {
+    /**
+     * Execute every statement atomically.
+     *
+     * @param statements - Statements to execute, in execution order
+     *
+     * @returns One result per statement, positionally aligned with `statements`
+     *
+     * @throws Underlying driver failures. The adapter maps them to SqlError.
+     */
+    execute(statements: readonly KyselyAtomicStatement[]): Promise<readonly KyselyAtomicStatementResult[]>;
+}
 /**
  * Minimal Kysely database interface used by this adapter.
  */

package/dist/types/index.d.ts

@@ -1 +1,2 @@
+export type { KyselyAtomicBatchExecutor, KyselyAtomicStatement, KyselyAtomicStatementResult, } from "./client/types.js";
 export { createKyselySqlClient } from "./client/create-kysely.js";

package/dist/types/internal/map-sql-error.d.ts

@@ -22,5 +22,5 @@ export declare const DRIVER_ERROR_MAPPINGS: Record<string, Record<string, ErrorD
  *
  * @returns A standardized SqlError instance
  */
-export declare function mapSqlError(cause: unknown, operation: "connect" | "query" | "transaction", adapter: string): SqlError;
+export declare function mapSqlError(cause: unknown, operation: "connect" | "query" | "transaction" | "batch", adapter: string): SqlError;
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@comity/sql-kysely",
-  "version": "0.9.0",
+  "version": "0.9.1",
   "description": "Kysely ORM adapter for @comity/sql contracts",
   "type": "module",
   "private": false,
@@ -58,13 +58,13 @@
   "sideEffects": false,
   "peerDependencies": {
     "kysely": "^0.28.0",
-    "@comity/sql": "0.9.0"
+    "@comity/sql": "0.9.1"
   },
   "dependencies": {
-    "@comity/sql": "0.9.0"
+    "@comity/sql": "0.9.1"
   },
   "devDependencies": {
-    "@types/node": "^24.13.4",
+    "@types/node": "^24.19.1",
     "kysely": "^0.28.17",
     "typescript": "^5.9.3"
   },