velocious 1.0.549 → 1.0.552

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

@@ -190,6 +190,10 @@ export default class VelociousDatabaseDriversMysql extends Base{
 
     if ("username" in args) connectArgs["user"] = args["username"]
     if ("charset" in args) connectArgs["charset"] = args["charset"]
+    // Opt-in only. Lets a whole structure SQL dump run in one round-trip via
+    // {@link execStructureScript}; off by default so ordinary queries keep rejecting
+    // stacked statements.
+    if ("multipleStatements" in args) connectArgs["multipleStatements"] = Boolean(digg(args, "multipleStatements"))
 
     return connectArgs
   }
@@ -417,6 +421,36 @@ export default class VelociousDatabaseDriversMysql extends Base{
     })
   }
 
+  /**
+   * Executes a full multi-statement structure SQL script in one round-trip when the
+   * connection was configured with `multipleStatements: true`. Runs on the pooled
+   * connection so the caller's `SET FOREIGN_KEY_CHECKS = 0` applies. Returns false so
+   * the caller runs statements individually when multi-statement queries are off.
+   * @param {string} structureSql - Full multi-statement structure SQL.
+   * @returns {Promise<boolean>} - Whether the script was executed as one batch.
+   */
+  async execStructureScript(structureSql) {
+    if (!this.getArgs().multipleStatements) return false
+
+    // The batched pool call below bypasses Base#query, so re-run the same read-only
+    // write guard the per-statement path applies before executing the dump.
+    this._assertWritableQuery(structureSql)
+
+    if (!this.pool) await this.connect()
+    if (!this.pool) throw new Error("MySQL pool failed to initialize")
+
+    const pool = this.pool
+
+    await new Promise((resolve, reject) => {
+      pool.query(structureSql, (error) => {
+        if (error) reject(error)
+        else resolve(undefined)
+      })
+    })
+
+    return true
+  }
+
   /**
    * Runs query to sql.
    * @param {import("../../query/index.js").default} query - Query instance.

package/src/database/structure-sql-loader.js

@@ -31,17 +31,23 @@ export default class StructureSqlLoader {
     await db.disableForeignKeys()
 
     try {
-      if (executableConnection) {
-        await executableConnection.exec(structureSql)
-      } else {
-        for (const statement of statements) {
-          await db.query(statement)
+      // Prefer a single round-trip for the whole dump: a driver-native multi-statement
+      // batch (e.g. MySQL with `multipleStatements`) first, then a native `exec`
+      // connection (e.g. SQLite), and finally per-statement execution. Running the
+      // whole dump at once is far faster than issuing every CREATE separately.
+      if (!await db.execStructureScript(structureSql)) {
+        if (executableConnection) {
+          await executableConnection.exec(structureSql)
+        } else {
+          for (const statement of statements) {
+            await db.query(statement)
+          }
         }
       }
     } finally {
       await db.enableForeignKeys()
 
-      // The native `exec` path mutates the schema outside `Base#query`, so the
+      // The batch / native `exec` paths mutate the schema outside `Base#query`, so the
       // usual post-DDL schema-cache invalidation never runs. Clear it here so a
       // caller that read schema metadata before provisioning (e.g. an empty table
       // list) does not keep seeing the pre-load schema afterwards. Harmless for the

package/src/testing/test.js

@@ -4,6 +4,7 @@ import path from "path"
 import {fileURLToPath} from "url"
 import EventEmitter from "../utils/event-emitter.js"
 import Expect from "./expect.js"
+import waitForEvent from "./wait-for-event.js"
 import {arrayContaining, objectContaining} from "./expect-utils.js"
 
 /**
@@ -351,7 +352,7 @@ globalThis.fit = fit
 globalThis.testEvents = testEvents
 globalThis.configureTests = configureTests
 
-export {afterAll, afterEach, beforeAll, beforeEach, configureTests, describe, expect, fit, it, arrayContaining, objectContaining, testConfig, testEvents, tests}
+export {afterAll, afterEach, beforeAll, beforeEach, configureTests, describe, expect, fit, it, arrayContaining, objectContaining, testConfig, testEvents, tests, waitForEvent}
 /**
  * VelociousTestConfig type.
  * @typedef {object} VelociousTestConfig

package/src/testing/wait-for-event.js

@@ -0,0 +1,72 @@
+// @ts-check
+
+/**
+ * @typedef {object} WaitForEventOptions
+ * @property {number} [timeoutMs] Timeout in milliseconds (default: 5000).
+ * @property {(...args: Array<?>) => boolean} [filter] Only resolve when this predicate returns true for the emitted arguments.
+ */
+
+/**
+ * @typedef {object} EventEmitterLike
+ * @property {(event: string, listener: (...args: Array<?>) => void) => void} on Registers a listener.
+ * @property {(event: string, listener: (...args: Array<?>) => void) => void} off Removes a listener.
+ */
+
+/**
+ * Resolves the moment `eventName` fires on `emitter` — optionally only when `filter`
+ * matches the emitted arguments — instead of sleeping a fixed duration. Rejects with a
+ * timeout error if the event does not fire within `timeoutMs`. The listener is always
+ * removed (on resolve and on timeout).
+ *
+ * Use this to await a real signal (a background job finishing, a model update, a
+ * websocket message) rather than guessing a delay. To poll an arbitrary condition
+ * instead of a discrete event, use awaitery's `waitFor`.
+ * @param {EventEmitterLike} emitter - Event emitter exposing `on`/`off` (Node EventEmitter, eventemitter3, velocious `testEvents`, ...).
+ * @param {string} eventName - The event to wait for.
+ * @param {WaitForEventOptions} [options] - Options.
+ * @returns {Promise<?>} - Resolves with the single emitted argument, an array when the event emits multiple, or undefined when it emits none.
+ */
+export default function waitForEvent(emitter, eventName, options = {}) {
+  const {timeoutMs = 5000, filter} = options
+
+  return new Promise((resolve, reject) => {
+    /** @type {ReturnType<typeof setTimeout>} */
+    let timer
+
+    /**
+     * Resolves the wait when a matching event fires, removing itself first. A filter
+     * that throws (e.g. it assumes an event shape an intermediate emission doesn't
+     * have) rejects immediately rather than leaving the waiter pending until timeout.
+     * @param {...?} args - Emitted arguments.
+     * @returns {void}
+     */
+    const listener = (...args) => {
+      if (filter) {
+        let matched
+
+        try {
+          matched = filter(...args)
+        } catch (error) {
+          clearTimeout(timer)
+          emitter.off(eventName, listener)
+          reject(error)
+
+          return
+        }
+
+        if (!matched) return
+      }
+
+      clearTimeout(timer)
+      emitter.off(eventName, listener)
+      resolve(args.length > 1 ? args : args[0])
+    }
+
+    timer = setTimeout(() => {
+      emitter.off(eventName, listener)
+      reject(new Error(`Timed out after ${timeoutMs}ms waiting for event ${JSON.stringify(eventName)}`))
+    }, timeoutMs)
+
+    emitter.on(eventName, listener)
+  })
+}