velocious 1.0.592 → 1.0.593

package/src/database/drivers/base.js

@@ -65,6 +65,7 @@
  * @property {boolean} [processListComment] - Whether to add process-list comments to the query.
  * @property {boolean} [retry] - Whether retryable errors may retry the query; defaults to true.
  * @property {boolean} [sessionTimeZone] - Whether to ensure the configured database session time zone before the query.
+ * @property {boolean} [sqliteScript] - Internal SQLite flag selecting native multi-statement script execution.
  * @property {AbortSignal} [signal] - Aborts the in-flight query (destroying its connection) when it fires.
  * @property {string} [sourceStack] - Stack captured at the caller boundary.
  * @property {symbol} [operationOwner] - Opaque owner for an operation-leased connection.
@@ -141,7 +142,8 @@ import TableData from "../table-data/index.js"
 import TableColumn from "../table-data/table-column.js"
 import TableForeignKey from "../table-data/table-foreign-key.js"
 import wait from "awaitery/build/wait.js"
-import {optionalPositiveInteger} from "typanic"
+import { optionalPositiveInteger } from "typanic"
+import { coordinateSharedTransactionConnection } from "../../testing/shared-transaction-connection-coordinator.js"
 
 /** Maximum characters inspected when building the debug SQL preview. */
 const SQL_PREVIEW_SCAN_LIMIT = 4096
@@ -1594,13 +1596,16 @@ export default class VelociousDatabaseDriversBase {
   async affectedRows(sql, options = {}) {
     await this._waitForOperationLease(options.operationOwner)
     this._assertWritableQuery(sql)
-    await this.beforeQuery(sql, options)
 
-    try {
-      return await this._affectedRowsActual(sql)
-    } finally {
-      await this.afterQuery(sql, options)
-    }
+    return await coordinateSharedTransactionConnection(this, async () => {
+      await this.beforeQuery(sql, options)
+
+      try {
+        return await this._affectedRowsActual(sql)
+      } finally {
+        await this.afterQuery(sql, options)
+      }
+    }, options.operationOwner)
   }
 
   /**
@@ -1663,13 +1668,15 @@ export default class VelociousDatabaseDriversBase {
    * @returns {Promise<QueryResultType>} - Resolves with the query.
    */
   async _queryActualWithHooks(sql, options) {
-    await this.beforeQuery(sql, options)
+    return await coordinateSharedTransactionConnection(this, async () => {
+      await this.beforeQuery(sql, options)
 
-    try {
-      return await this._queryActual(sql, options)
-    } finally {
-      await this.afterQuery(sql, options)
-    }
+      try {
+        return await this._queryActual(sql, options)
+      } finally {
+        await this.afterQuery(sql, options)
+      }
+    }, options.operationOwner)
   }
 
   /**
@@ -2214,42 +2221,54 @@ export default class VelociousDatabaseDriversBase {
     await this.query(`ROLLBACK TO SAVEPOINT ${savePointName}`, options)
   }
 
+  /**
+   * Truncates the given table snapshot. Drivers can override this to issue one batch.
+   * @protected
+   * @param {Array<import("./base-table.js").default>} tables - Eligible tables for this cleanup attempt.
+   * @returns {Promise<void>} - Resolves when every table has been cleaned.
+   */
+  async truncateTables(tables) {
+    const truncateErrors = []
+
+    for (const table of tables) {
+      try {
+        await table.truncate({cascade: true})
+      } catch (error) {
+        truncateErrors.push(error)
+      }
+    }
+
+    if (truncateErrors.length > 0) throw truncateErrors[0]
+  }
+
   /**
    * Runs truncate all tables.
    * @returns {Promise<void>} - Resolves when complete.
    */
   async truncateAllTables() {
     this._assertNotReadOnly()
-    await this.withDisabledForeignKeys(async () => {
-      let tries = 0
+    let tables = (await this.getTables()).filter((table) => table.getName() != "schema_migrations")
 
-      while(tries <= 5) {
-        tries++
+    if (tables.length == 0) return
 
-        const tables = await this.getTables()
-        const truncateErrors = []
+    await this.withDisabledForeignKeys(async () => {
+      for (let tries = 1; tries <= 6; tries++) {
+        try {
+          await this.truncateTables(tables)
+          return
+        } catch (error) {
+          console.error(error)
 
-        for (const table of tables) {
-          if (table.getName() != "schema_migrations") {
-            try {
-              await table.truncate({cascade: true})
-            } catch (error) {
-              console.error(error)
-              truncateErrors.push(error)
-            }
-          }
-        }
+          if (tries == 6) throw error
 
-        if (truncateErrors.length == 0) {
-          break
-        } else if (tries <= 5) {
           // A truncate failed — the schema cache may still list a table that was
           // dropped out from under us (e.g. a db:rollback test that left the
           // shared DB rolled back). Clear it so the next pass re-reads the live
           // table list and no longer tries to truncate a table that is gone.
           this.clearSchemaCache()
-        } else {
-          throw truncateErrors[0]
+          tables = (await this.getTables()).filter((table) => table.getName() != "schema_migrations")
+
+          if (tables.length == 0) return
         }
       }
     })

package/src/database/drivers/mssql/index.js

@@ -506,6 +506,38 @@ export default class VelociousDatabaseDriversMssql extends Base{
     })
   }
 
+  /**
+   * Truncates all eligible tables in one SQL Server request, retaining the
+   * recognized foreign-key fallback used by the per-table implementation.
+   * @param {Array<import("../base-table.js").default>} tables - Eligible tables.
+   * @returns {Promise<void>} - Resolves when the batch completes.
+   */
+  async truncateTables(tables) {
+    const statements = []
+
+    for (const table of tables) {
+      const quotedTable = this.quoteTable(table.getName())
+
+      statements.push(
+        "BEGIN TRY",
+        `  TRUNCATE TABLE ${quotedTable};`,
+        "END TRY",
+        "BEGIN CATCH",
+        "  IF ERROR_NUMBER() = 4712",
+        "  BEGIN",
+        `    DELETE FROM ${quotedTable};`,
+        "  END",
+        "  ELSE",
+        "  BEGIN",
+        "    THROW;",
+        "  END",
+        "END CATCH;"
+      )
+    }
+
+    await this.query(statements.join("\n"))
+  }
+
   async lastInsertID(options = {}) {
     const result = await this.query("SELECT SCOPE_IDENTITY() AS last_insert_id", options)
     const lastInsertID = digg(result, 0, "last_insert_id")

package/src/database/drivers/mysql/index.js

@@ -486,6 +486,23 @@ export default class VelociousDatabaseDriversMysql extends Base{
     return true
   }
 
+  /**
+   * Uses one multi-statement request only when the existing connection option
+   * explicitly allows it; otherwise retains the base sequential behavior.
+   * @param {Array<import("../base-table.js").default>} tables - Eligible tables.
+   * @returns {Promise<void>} - Resolves when every table has been truncated.
+   */
+  async truncateTables(tables) {
+    if (!this.getArgs().multipleStatements) {
+      await super.truncateTables(tables)
+      return
+    }
+
+    const statements = tables.map((table) => `TRUNCATE TABLE ${this.quoteTable(table.getName())}`)
+
+    await this.query(statements.join(";\n"))
+  }
+
   /**
    * Runs query to sql.
    * @param {import("../../query/index.js").default} query - Query instance.

package/src/database/drivers/pgsql/index.js

@@ -326,6 +326,17 @@ export default class VelociousDatabaseDriversPgsql extends Base{
     })
   }
 
+  /**
+   * Truncates all eligible tables in one PostgreSQL request.
+   * @param {Array<import("../base-table.js").default>} tables - Eligible tables.
+   * @returns {Promise<void>} - Resolves when the batch completes.
+   */
+  async truncateTables(tables) {
+    const quotedTables = tables.map((table) => this.quoteTable(table.getName()))
+
+    await this.query(`TRUNCATE TABLE ${quotedTables.join(", ")} CASCADE`)
+  }
+
   async lastInsertID(options = {}) {
     const result = await this.query("SELECT LASTVAL() AS last_insert_id", options)
 

package/src/database/drivers/sqlite/base.js

@@ -161,6 +161,18 @@ export default class VelociousDatabaseDriversSqliteBase extends Base {
     })
   }
 
+  /**
+   * Deletes every eligible table through the platform driver's native SQLite
+   * script path so the whole cleanup is submitted as one request.
+   * @param {Array<import("../base-table.js").default>} tables - Eligible tables.
+   * @returns {Promise<void>} - Resolves when the script completes.
+   */
+  async truncateTables(tables) {
+    const statements = tables.map((table) => `DELETE FROM ${this.quoteTable(table.getName())}`)
+
+    await this.query(statements.join(";\n"), {sqliteScript: true})
+  }
+
   /**
    * Runs insert multiple.
    * @param {string} tableName - Table name.

package/src/database/drivers/sqlite/connection-sql-js.js

@@ -89,14 +89,15 @@ export default class VelociousDatabaseDriversSqliteConnectionSqlJs {
   /**
    * Runs query.
    * @param {string} sql - SQL string.
+   * @param {{mutation?: boolean}} [options] - Internal query classification options.
    * @returns {Promise<Record<string, ReturnType<typeof JSON.parse>>[]>} - Resolves with the query.
    */
-  async query(sql) {
+  async query(sql, {mutation = false} = {}) {
     const result = await queryWeb(this.connection, sql)
     const downcasedSQL = sql.toLowerCase().trim()
 
     // Auto-save database in local storage in case we can find manipulating instructions in the SQL
-    if (downcasedSQL.startsWith("delete ") || downcasedSQL.startsWith("insert into ") || downcasedSQL.startsWith("update ")) {
+    if (mutation || downcasedSQL.startsWith("delete ") || downcasedSQL.startsWith("insert into ") || downcasedSQL.startsWith("update ")) {
       this.saveDatabaseDebounce()
     }
 

package/src/database/drivers/sqlite/index.js

@@ -84,11 +84,17 @@ export default class VelociousDatabaseDriversSqliteNode extends Base {
   /**
    * Runs query actual.
    * @param {string} sql - SQL string.
+   * @param {import("../base.js").QueryOptions} [options] - Query options.
    * @returns {Promise<Record<string, ReturnType<typeof JSON.parse>>[]>} - Resolves with the query actual.
    */
-  async _queryActual(sql) {
+  async _queryActual(sql, options = {}) {
     if (!this.connection) throw new Error("No connection")
 
+    if (options.sqliteScript) {
+      await this.connection.exec(sql)
+      return []
+    }
+
     return await query(this.connection, sql)
   }
 

package/src/database/drivers/sqlite/index.native.js

@@ -82,13 +82,19 @@ export default class VelociousDatabaseDriversSqliteNative extends Base {
   /**
    * Runs query actual.
    * @param {string} sql - SQL string.
+   * @param {import("../base.js").QueryOptions} [options] - Query options.
    * @returns {Promise<Record<string, ReturnType<typeof JSON.parse>>[]>} - Query result rows.
    */
-  async _queryActual(sql) {
-    return await this._queryMutex.sync(() => {
+  async _queryActual(sql, options = {}) {
+    return await this._queryMutex.sync(async () => {
       if (!this.connection) throw new Error("Not connected yet")
 
-      return query(this.connection, sql)
+      if (options.sqliteScript) {
+        await this.connection.execAsync(sql)
+        return []
+      }
+
+      return await query(this.connection, sql)
     })
   }
 

package/src/database/drivers/sqlite/index.web.js

@@ -178,13 +178,16 @@ export default class VelociousDatabaseDriversSqliteWeb extends Base {
   /**
    * Runs query actual.
    * @param {string} sql - SQL string.
+   * @param {import("../base.js").QueryOptions} [options] - Query options.
    * @returns {Promise<Record<string, ReturnType<typeof JSON.parse>>[]>} - Resolves with the query actual.
    */
-  async _queryActual(sql) {
-    const result = await this.getConnection().query(sql)
+  async _queryActual(sql, options = {}) {
+    const connection = this.getConnection()
+    const result = connection instanceof ConnectionSqlJs
+      ? await connection.query(sql, {mutation: options.sqliteScript === true})
+      : await connection.query(sql)
 
     if (!Array.isArray(result)) {
-      const connection = this.getConnection()
       const connectionName = connection?.constructor?.name || "UnknownConnection"
 
       throw new Error(`Sqlite web connection ${connectionName} returned a non-array result: ${typeof result}`)

package/src/environment-handlers/base.js

@@ -27,6 +27,24 @@ export default class VelociousEnvironmentHandlerBase {
    */
   async createTestSharedTransactionConnection(_args) { return undefined }
 
+  /**
+   * Gets the active shared-transaction coordinator owner for a connection.
+   * Browser runtimes never install the Node test broker.
+   * @param {object} _connection - Parent physical connection.
+   * @returns {symbol | undefined} - Active coordinator owner.
+   */
+  getSharedTransactionCoordinatorOwner(_connection) { return undefined }
+
+  /**
+   * Runs work as the current shared-transaction coordinator owner.
+   * @template T
+   * @param {object} _connection - Parent physical connection.
+   * @param {symbol} _owner - Coordinator owner.
+   * @param {() => T} callback - Owned work.
+   * @returns {T} - Callback result.
+   */
+  runWithSharedTransactionCoordinatorOwner(_connection, _owner, callback) { return callback() }
+
   /**
    * Mutable ambient tenant used by runtimes without async-context storage.
    * @type {ReturnType<typeof JSON.parse> | undefined}

package/src/environment-handlers/node.js

@@ -80,6 +80,38 @@ export default class VelociousEnvironmentHandlerNode extends Base{
    * @type {import("node:async_hooks").AsyncLocalStorage<TimezoneStore> | undefined} */
   _timezoneAsyncLocalStorage = NodeAsyncLocalStorage ? new NodeAsyncLocalStorage() : undefined
 
+  /**
+   * Shared-transaction coordinator ownership by physical connection.
+   * @type {import("node:async_hooks").AsyncLocalStorage<Map<object, symbol>> | undefined}
+   */
+  _sharedTransactionCoordinatorAsyncLocalStorage = NodeAsyncLocalStorage ? new NodeAsyncLocalStorage() : undefined
+
+  /**
+   * Gets the active shared-transaction coordinator owner for a connection.
+   * @param {object} connection - Parent physical connection.
+   * @returns {symbol | undefined} - Active coordinator owner.
+   */
+  getSharedTransactionCoordinatorOwner(connection) {
+    return this._sharedTransactionCoordinatorAsyncLocalStorage?.getStore()?.get(connection)
+  }
+
+  /**
+   * Runs work as the current shared-transaction coordinator owner.
+   * @template T
+   * @param {object} connection - Parent physical connection.
+   * @param {symbol} owner - Coordinator owner.
+   * @param {() => T} callback - Owned work.
+   * @returns {T} - Callback result.
+   */
+  runWithSharedTransactionCoordinatorOwner(connection, owner, callback) {
+    if (!this._sharedTransactionCoordinatorAsyncLocalStorage) return callback()
+
+    const owners = new Map(this._sharedTransactionCoordinatorAsyncLocalStorage.getStore())
+
+    owners.set(connection, owner)
+    return this._sharedTransactionCoordinatorAsyncLocalStorage.run(owners, callback)
+  }
+
   /**
    * Find commands result.
    * @type {import("./base.js").CommandFileObjectType[] | undefined} */

package/src/testing/shared-transaction-broker.js

@@ -5,7 +5,7 @@ import { createServer } from "node:http"
 import { EventEmitter } from "node:events"
 import { WebSocketServer } from "ws"
 import { decodeBrokerValue, encodeBrokerValue } from "./shared-transaction-codec.js"
-import {clearSharedTransactionCoordinator, setSharedTransactionCoordinator} from "./shared-transaction-connection-coordinator.js"
+import { clearSharedTransactionCoordinator, setSharedTransactionCoordinator } from "./shared-transaction-connection-coordinator.js"
 
 /** @typedef {{queue: Promise<void>, rootSessions: Set<import("ws").WebSocket>, lease?: {operations: Promise<void>, release: () => void, savePointName: string, socket: import("ws").WebSocket}}} ConnectionState */
 
@@ -38,6 +38,23 @@ function capabilityMatches(provided, expected) {
   return providedBytes.length === expectedBytes.length && timingSafeEqual(providedBytes, expectedBytes)
 }
 
+/**
+ * Adds broker ownership to decoded driver options.
+ * @param {ReturnType<typeof JSON.parse>} value - Decoded options.
+ * @param {symbol} operationOwner - Broker coordinator owner.
+ * @returns {Record<string, ReturnType<typeof JSON.parse>> & {operationOwner: symbol}} - Owned options.
+ */
+function ownedOperationOptions(value, operationOwner) {
+  if (value === undefined) return {operationOwner}
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new TypeError("Shared transaction broker driver options must be an object")
+  }
+
+  const options = /** @type {Record<string, ReturnType<typeof JSON.parse>>} */ (value)
+
+  return {...options, operationOwner}
+}
+
 export default class SharedTransactionBroker extends EventEmitter {
   /**
    * Creates a broker around parent-owned physical connections.
@@ -60,6 +77,8 @@ export default class SharedTransactionBroker extends EventEmitter {
     this.closePromise = undefined
     /** @type {Map<object, (callback: () => Promise<ReturnType<typeof JSON.parse>>) => Promise<ReturnType<typeof JSON.parse>>>} */
     this.connectionCoordinators = new Map()
+    /** @type {Map<object, symbol>} */
+    this.connectionCoordinatorOwners = new Map()
     for (const connection of new Set(Object.values(connections))) {
       /**
        * Serializes parent operations with child broker traffic.
@@ -68,7 +87,7 @@ export default class SharedTransactionBroker extends EventEmitter {
        */
       const coordinator = async (callback) => await this.serialize(this.connectionState(connection), callback)
       this.connectionCoordinators.set(connection, coordinator)
-      setSharedTransactionCoordinator(connection, coordinator)
+      this.connectionCoordinatorOwners.set(connection, setSharedTransactionCoordinator(connection, coordinator))
     }
     this.httpServer = createServer()
     this.websocketServer = new WebSocketServer({server: this.httpServer, maxPayload: 16 * 1024 * 1024})
@@ -144,10 +163,10 @@ export default class SharedTransactionBroker extends EventEmitter {
             : request.method === "rootTransactionRollback"
               ? "rollbackSavePoint"
               : request.method
-        const connectionMethods = /** @type {Record<string, (...methodArgs: Array<ReturnType<typeof JSON.parse>>) => ReturnType<typeof JSON.parse>>} */ (connection)
+        const connectionMethods = /** @type {Record<string, (...methodArgs: Array<ReturnType<typeof JSON.parse> | {operationOwner: symbol}>) => ReturnType<typeof JSON.parse>>} */ (connection)
         const method = connectionMethods[physicalMethod]
         if (typeof method !== "function") throw new Error(`Connection does not support shared transaction method: ${request.method}`)
-        return await method.apply(connection, args)
+        return await method.apply(connection, this.ownedMethodArgs({args, connection, method: physicalMethod}))
       })
       if (socket.readyState === socket.OPEN) socket.send(JSON.stringify({requestId, result: encodeBrokerValue(result)}))
     } catch (error) {
@@ -156,6 +175,25 @@ export default class SharedTransactionBroker extends EventEmitter {
     }
   }
 
+  /**
+   * Adds the broker owner to public driver methods that re-enter coordinated query work.
+   * @param {{args: Array<ReturnType<typeof JSON.parse>>, connection: object, method: string}} args - Physical invocation.
+   * @returns {Array<ReturnType<typeof JSON.parse> | {operationOwner: symbol}>} - Owned method arguments.
+   */
+  ownedMethodArgs({args, connection, method}) {
+    const operationOwner = this.connectionCoordinatorOwners.get(connection)
+
+    if (!operationOwner) throw new Error("Shared transaction broker connection owner is missing")
+    if (["_startTransactionAction", "_commitTransactionAction", "_rollbackTransactionAction"].includes(method)) {
+      return [ownedOperationOptions(args[0], operationOwner)]
+    }
+    if (["query", "affectedRows", "startSavePoint", "releaseSavePoint", "rollbackSavePoint"].includes(method)) {
+      return [args[0], ownedOperationOptions(args[1], operationOwner)]
+    }
+
+    return args
+  }
+
   /**
    * Gets mutable serialization state for one physical connection.
    * @param {object} connection - Physical connection.
@@ -324,16 +362,19 @@ export default class SharedTransactionBroker extends EventEmitter {
    * @returns {Promise<void>} - Resolves after rollback and release.
    */
   async rollbackRootSavePoint(connection, savePointName) {
-    const methods = /** @type {{releaseSavePoint: (name: string) => Promise<void>, rollbackSavePoint: (name: string) => Promise<void>}} */ (connection)
+    const methods = /** @type {{releaseSavePoint: (name: string, options?: {operationOwner?: symbol}) => Promise<void>, rollbackSavePoint: (name: string, options?: {operationOwner?: symbol}) => Promise<void>}} */ (connection)
+    const operationOwner = this.connectionCoordinatorOwners.get(connection)
+
+    if (!operationOwner) throw new Error("Shared transaction broker connection owner is missing")
     /** @type {Array<Error>} */
     const errors = []
     try {
-      await methods.rollbackSavePoint(savePointName)
+      await methods.rollbackSavePoint(savePointName, {operationOwner})
     } catch (error) {
       errors.push(error instanceof Error ? error : new Error(String(error)))
     }
     try {
-      await methods.releaseSavePoint(savePointName)
+      await methods.releaseSavePoint(savePointName, {operationOwner})
     } catch (error) {
       errors.push(error instanceof Error ? error : new Error(String(error)))
     }

package/src/testing/shared-transaction-connection-coordinator.js

@@ -1,16 +1,19 @@
 // @ts-check
 
-/** @type {WeakMap<object, (callback: () => Promise<unknown>) => Promise<unknown>>} */
+/** @type {WeakMap<object, {coordinator: (callback: () => Promise<unknown>) => Promise<unknown>, owner: symbol}>} */
 const coordinators = new WeakMap()
 
 /**
  * Registers test-only serialization owned by the active broker.
  * @param {object} connection - Parent physical connection.
  * @param {(callback: () => Promise<unknown>) => Promise<unknown>} coordinator - Serializer.
- * @returns {void}
+ * @returns {symbol} - Opaque owner for broker-internal connection calls.
  */
 export function setSharedTransactionCoordinator(connection, coordinator) {
-  coordinators.set(connection, coordinator)
+  const owner = Symbol("shared-transaction-coordinator")
+
+  coordinators.set(connection, {coordinator, owner})
+  return owner
 }
 
 /**
@@ -20,19 +23,30 @@ export function setSharedTransactionCoordinator(connection, coordinator) {
  * @returns {void}
  */
 export function clearSharedTransactionCoordinator(connection, coordinator) {
-  if (coordinators.get(connection) === coordinator) coordinators.delete(connection)
+  if (coordinators.get(connection)?.coordinator === coordinator) coordinators.delete(connection)
 }
 
 /**
  * Runs parent work through broker serialization when registered.
  * @template T
- * @param {object} connection - Parent physical connection.
+ * @param {import("../database/drivers/base.js").default} connection - Parent physical connection.
  * @param {() => Promise<T>} callback - Parent operation.
+ * @param {symbol} [operationOwner] - Broker owner for an already-coordinated operation.
  * @returns {Promise<T>} - Operation result.
  */
-export async function coordinateSharedTransactionConnection(connection, callback) {
-  const coordinator = coordinators.get(connection)
+export async function coordinateSharedTransactionConnection(connection, callback, operationOwner) {
+  const registration = coordinators.get(connection)
+
+  if (!registration) return await callback()
+  if (operationOwner === registration.owner) return await callback()
+
+  const environmentHandler = connection.configuration.getEnvironmentHandler()
+
+  if (environmentHandler.getSharedTransactionCoordinatorOwner(connection) === registration.owner) {
+    return await callback()
+  }
 
-  if (!coordinator) return await callback()
-  return /** @type {T} */ (await coordinator(callback))
+  return /** @type {T} */ (await registration.coordinator(async () => {
+    return await environmentHandler.runWithSharedTransactionCoordinatorOwner(connection, registration.owner, callback)
+  }))
 }