velocious 1.0.591 → 1.0.593

package/README.md

@@ -14,7 +14,7 @@
 * Controllers and views for HTTP endpoints
 * Frontend-model transport for creating, updating, querying, and subscribing to query-filtered lifecycle events over HTTP/WebSocket, with structured per-attribute validation error responses and one-budget WebSocket startup controls (see [docs/frontend-models.md](docs/frontend-models.md) and [docs/websocket-channels.md](docs/websocket-channels.md))
 * Client-side offline sync mutation logs and frontend-model optimistic queueing primitives (see the [shared-resource sync developer guide](docs/shared-resource-sync-guide.md) and [offline sync architecture](docs/offline-sync.md))
-* Declarative client sync scopes with per-scope cursors, automatic mutation tracking, realtime delivery whose per-recipient authorization hook receives the complete persisted sync envelope, and `sync`/`pull` progress reporting for "X of Y" import screens (see [docs/sync-client.md](docs/sync-client.md) and [docs/offline-sync.md](docs/offline-sync.md))
+* Declarative client sync scopes with per-scope cursors, automatic mutation tracking, opt-in durable base-version conflict replay, realtime delivery whose per-recipient authorization hook receives the complete persisted sync envelope, and `sync`/`pull` progress reporting for "X of Y" import screens (see [docs/sync-client.md](docs/sync-client.md) and [docs/offline-sync.md](docs/offline-sync.md))
 * Reactive `useLiveQuery(Model.where(...))` queries that stay current from committed local model changes across local writes, pulls, and realtime (see [docs/live-queries.md](docs/live-queries.md))
 * Server-side sync envelope replay orchestration for app-owned sync receivers, including allowlisted authoritative values for conflict resolution (see [docs/sync-envelope-replay-service.md](docs/sync-envelope-replay-service.md))
 * Self-sustaining sync feeds: upstream imports triggered by the changes pull itself, with framework-owned coalescing and throttling (see [docs/sync-upstream-imports.md](docs/sync-upstream-imports.md))
@@ -328,6 +328,7 @@ npm run test:browser
 ```
 
 Browser system tests must be named `*.browser-test.js` or `*.browser-spec.js` (override with `VELOCIOUS_BROWSER_TEST_PATTERN`).
+The runner validates and persists the exact Chrome/ChromeDriver pair selected by `scripts/prewarm-chromedriver.js`, then owns ChromeDriver and Chrome as a managed process group. Startup failures report the runtime paths and versions, service URL, retained logs under `tmp/browser-test-chrome/`, and Chrome process state before and after cleanup.
 
 Use beforeAll/afterAll for suite-level setup/teardown.
 
@@ -2070,6 +2071,13 @@ If you are developing on Velocious, you can run the tests with:
 
 Tests default to a 60-second timeout. Override per test with `{timeoutSeconds: 5}` or set a suite-wide default via `configureTests({defaultTimeoutSeconds: 30})`.
 
+Truncation-based test cleanup batches eligible tables into one request on PostgreSQL,
+SQL Server, and SQLite while preserving each driver's existing identity behavior,
+foreign-key restoration, stale-schema retry, and SQL.js persistence guarantees.
+MySQL/MariaDB batching requires the database's existing `multipleStatements: true`
+option; the default configuration keeps sequential `TRUNCATE TABLE` requests. See
+[database cleanup guidance](docs/testing-guidelines.md#truncation-cleanup).
+
 Request tests share transaction-active, non-tenant database connections with their in-process HTTP handlers. Eligibility is evaluated when each request is dispatched, so a hook can start a transaction and issue a request in the same callback. This makes uncommitted setup visible to handlers while preserving rollback isolation. Without an active transaction, handlers use independent pooled connections, so concurrency and locking tests can opt out of transaction cleanup and exercise production-style connections. Shared connection state is scoped to the test lifecycle and cleared around each test. See [docs/testing-guidelines.md](docs/testing-guidelines.md#request-test-database-connections).
 
 Transactional tests also share active non-tenant connections with real forked, reusable pooled, and spawned background-job child runners through a per-attempt test-only loopback broker. Parent setup and child writes therefore occupy the same physical transaction and roll back together, including background-job persistence. Multiple configured databases route by identifier; tenant-only databases remain excluded. Tests using `{transaction: false, truncate: true}` retain ordinary independent physical connections for concurrency and locking coverage. See [docs/testing-guidelines.md](docs/testing-guidelines.md#request-test-database-connections).

package/build/configuration-types.js

@@ -72,7 +72,7 @@
  * @property {() => ReturnType<typeof JSON.parse>} [getConnection] - Custom connection factory override.
  * @property {string} [host] - Database host.
  * @property {boolean} [migrations] - Whether migrations are enabled for this database.
- * @property {boolean} [multipleStatements] - (MySQL) Opt in to multi-statement queries so a whole structure SQL dump loads in one round-trip via `StructureSqlLoader`. Off by default; ordinary queries otherwise reject stacked statements.
+ * @property {boolean} [multipleStatements] - (MySQL) Opt in to multi-statement queries so structure SQL loads and all-table cleanup can batch into one round-trip. Off by default; ordinary queries otherwise reject stacked statements.
  * @property {number} [maxRowsPerInsert] - Maximum rows per `INSERT ... VALUES (...), (...), ...` statement generated by `Record.insertMultiple`. Defaults to 500.
  * @property {number} [maxInsertSqlBytes] - Maximum serialized SQL size, in bytes, for a single `INSERT ... VALUES (...), (...), ...` statement. Defaults to 1 MiB (1048576).
  * @property {number} [maxInClauseValues] - Maximum values in a single `IN (...)` cohort used by preloads, association counts, and queryData aggregates. Defaults to 999.

package/build/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/build/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/build/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/build/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/build/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/build/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/build/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/build/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/build/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/build/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/build/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/build/src/configuration-types.d.ts

@@ -154,7 +154,7 @@ export type DatabaseConfigurationType = {
      */
     migrations?: boolean;
     /**
-     * - (MySQL) Opt in to multi-statement queries so a whole structure SQL dump loads in one round-trip via `StructureSqlLoader`. Off by default; ordinary queries otherwise reject stacked statements.
+     * - (MySQL) Opt in to multi-statement queries so structure SQL loads and all-table cleanup can batch into one round-trip. Off by default; ordinary queries otherwise reject stacked statements.
      */
     multipleStatements?: boolean;
     /**
@@ -1660,7 +1660,7 @@ export type ConfigurationArgsType = {
  * @property {() => ReturnType<typeof JSON.parse>} [getConnection] - Custom connection factory override.
  * @property {string} [host] - Database host.
  * @property {boolean} [migrations] - Whether migrations are enabled for this database.
- * @property {boolean} [multipleStatements] - (MySQL) Opt in to multi-statement queries so a whole structure SQL dump loads in one round-trip via `StructureSqlLoader`. Off by default; ordinary queries otherwise reject stacked statements.
+ * @property {boolean} [multipleStatements] - (MySQL) Opt in to multi-statement queries so structure SQL loads and all-table cleanup can batch into one round-trip. Off by default; ordinary queries otherwise reject stacked statements.
  * @property {number} [maxRowsPerInsert] - Maximum rows per `INSERT ... VALUES (...), (...), ...` statement generated by `Record.insertMultiple`. Defaults to 500.
  * @property {number} [maxInsertSqlBytes] - Maximum serialized SQL size, in bytes, for a single `INSERT ... VALUES (...), (...), ...` statement. Defaults to 1 MiB (1048576).
  * @property {number} [maxInClauseValues] - Maximum values in a single `IN (...)` cohort used by preloads, association counts, and queryData aggregates. Defaults to 999.