velocious 1.0.548 → 1.0.551

package/package.json

@@ -3,7 +3,7 @@
     "velocious": "build/bin/velocious.js"
   },
   "name": "velocious",
-  "version": "1.0.548",
+  "version": "1.0.551",
   "main": "build/index.js",
   "types": "build/index.d.ts",
   "files": [
@@ -52,7 +52,7 @@
   "description": "",
   "dependencies": {
     "@js-temporal/polyfill": "^0.5.1",
-    "awaitery": "^1.0.6",
+    "awaitery": "^1.0.17",
     "bcryptjs": "^3.0.2",
     "better-localstorage": "^1.0.7",
     "debounce": "^3.0.0",

package/src/database/advisory-lock-runner.js

@@ -1,6 +1,6 @@
 // @ts-check
 
-import timeout from "awaitery/build/timeout.js"
+import timeout, {TimeoutError} from "awaitery/build/timeout.js"
 
 /**
  * Thrown when an advisory lock could not be acquired before `timeoutMs` elapsed.
@@ -67,9 +67,12 @@ export default class AdvisoryLockRunner {
 
   /**
    * Runs a callback after acquiring the advisory lock, waiting up to `timeoutMs`.
+   * When a `holdTimeoutMs` is set the callback receives a `TimeoutControl` from
+   * awaitery for cooperative cancellation (`control.check()`, `control.signal`,
+   * `control.timedOut`, `control.remaining()`).
    * @template T
    * @param {string} name - Lock name.
-   * @param {() => Promise<T>} callback - Callback to invoke while the lock is held.
+   * @param {(args?: {control: import("awaitery/build/timeout.js").TimeoutControl}) => Promise<T>} callback - Callback to invoke while the lock is held.
    * @param {{timeoutMs?: number | null, holdTimeoutMs?: number | null}} [args] - Lock and hold timeout options.
    * @returns {Promise<T>} - Resolves with the callback result.
    */
@@ -87,9 +90,11 @@ export default class AdvisoryLockRunner {
 
   /**
    * Runs a callback only if the advisory lock can be acquired immediately.
+   * When a `holdTimeoutMs` is set the callback receives a `TimeoutControl` from
+   * awaitery for cooperative cancellation.
    * @template T
    * @param {string} name - Lock name.
-   * @param {() => Promise<T>} callback - Callback to invoke while the lock is held.
+   * @param {(args?: {control: import("awaitery/build/timeout.js").TimeoutControl}) => Promise<T>} callback - Callback to invoke while the lock is held.
    * @param {{holdTimeoutMs?: number | null}} [args] - Hold timeout options.
    * @returns {Promise<T>} - Resolves with the callback result.
    */
@@ -108,7 +113,7 @@ export default class AdvisoryLockRunner {
   /**
    * Runs the lock holder callback and releases the lock from its owning connection.
    * @template T
-   * @param {{callback: () => Promise<T>, connection: import("./drivers/base.js").default, holdTimeoutMs?: number | null, name: string}} args - Locked callback args.
+   * @param {{callback: (args?: {control: import("awaitery/build/timeout.js").TimeoutControl}) => Promise<T>, connection: import("./drivers/base.js").default, holdTimeoutMs?: number | null, name: string}} args - Locked callback args.
    * @returns {Promise<T>} - Resolves with the callback result.
    */
   async runLockedCallback({callback, connection, holdTimeoutMs, name}) {
@@ -160,9 +165,13 @@ export default class AdvisoryLockRunner {
    * Runs `callback`, rejecting with `AdvisoryLockHoldTimeoutError` if it has
    * not settled within `holdTimeoutMs`. The callback is not cancelled; callers
    * use a dedicated advisory-lock connection so the lock can still be released.
+   *
+   * The callback receives a `TimeoutControl` from awaitery, enabling cooperative
+   * cancellation via `control.check()`, `control.signal`, `control.timedOut`,
+   * and `control.remaining()`.
    * @template T
    * @param {string} name - Lock name (for the error message).
-   * @param {() => Promise<T>} callback - Callback holding the lock.
+   * @param {(args?: {control: import("awaitery/build/timeout.js").TimeoutControl}) => Promise<T>} callback - Callback holding the lock.
    * @param {number | null} [holdTimeoutMs] - Max hold time; falsy disables the timeout.
    * @returns {Promise<T>} - Resolves with the callback result.
    */
@@ -174,15 +183,15 @@ export default class AdvisoryLockRunner {
     let callbackSettled = false
 
     try {
-      return await timeout({timeout: holdTimeoutMs}, async () => {
+      return await timeout({timeout: holdTimeoutMs}, async ({control}) => {
         try {
-          return await callback()
+          return await callback({control})
         } finally {
           callbackSettled = true
         }
       })
     } catch (error) {
-      if (!callbackSettled) {
+      if (!callbackSettled || error instanceof TimeoutError) {
         throw new AdvisoryLockHoldTimeoutError(`Advisory lock ${JSON.stringify(name)} held longer than ${holdTimeoutMs}ms`, {name})
       }
 

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

@@ -0,0 +1,68 @@
+// @ts-check
+
+import splitSqlStatements from "../utils/split-sql-statements.js"
+
+/**
+ * Loads a database structure SQL dump into a connection in one pass. Foreign keys are
+ * disabled around the load so tables can be created in any order, and the driver's
+ * native multi-statement `exec` is used when available (a single round-trip) instead
+ * of issuing every statement separately. This is much faster than materializing a
+ * schema table by table (e.g. cloning), so it is the preferred way to provision a
+ * tenant/test database from a structure dump.
+ *
+ * Used by the `db:schema:load` CLI command and reusable by any caller that needs to
+ * apply a structure dump to a specific connection.
+ */
+export default class StructureSqlLoader {
+  /**
+   * Loads `structureSql` into `db`.
+   * @param {object} args - Options object.
+   * @param {import("./drivers/base.js").default} args.db - Target database connection.
+   * @param {string} args.structureSql - Structure SQL to load.
+   * @returns {Promise<void>} - Resolves when the structure has been loaded.
+   */
+  async load({db, structureSql}) {
+    const statements = splitSqlStatements(structureSql)
+
+    if (statements.length == 0) return
+
+    const executableConnection = this.executableConnection(db)
+
+    await db.disableForeignKeys()
+
+    try {
+      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
+      // 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
+      // per-statement path, which already invalidates as each DDL statement runs.
+      db.clearSchemaCache()
+    }
+  }
+
+  /**
+   * Returns the underlying connection when it exposes a native multi-statement
+   * `exec` (a single round-trip for the whole dump), otherwise undefined so the
+   * caller falls back to per-statement execution.
+   * @param {import("./drivers/base.js").default} db - Database connection.
+   * @returns {{exec: (sql: string) => Promise<?>} | undefined} - Connection with exec support.
+   */
+  executableConnection(db) {
+    const dbWithConnection = /** @type {import("./drivers/base.js").default & {connection?: ?}} */ (db)
+    const connection = dbWithConnection.connection
+
+    if (connection && typeof connection == "object" && "exec" in connection && typeof connection.exec == "function") {
+      return /** @type {{exec: (sql: string) => Promise<?>}} */ (connection)
+    }
+  }
+}

package/src/environment-handlers/node/cli/commands/db/schema/load.js

@@ -1,7 +1,7 @@
 import BaseCommand from "../../../../../../cli/base-command.js"
 import fs from "fs/promises"
 import path from "path"
-import splitSqlStatements from "../../../../../../utils/split-sql-statements.js"
+import StructureSqlLoader from "../../../../../../database/structure-sql-loader.js"
 
 /** Node CLI command for loading DB structure SQL files. */
 export default class DbSchemaLoad extends BaseCommand {
@@ -11,57 +11,15 @@ export default class DbSchemaLoad extends BaseCommand {
   async execute() {
     await this.getConfiguration().ensureConnections({name: "DB schema load"}, async (dbs) => {
       const dbDir = path.join(this.directory(), "db")
+      const loader = new StructureSqlLoader()
 
       for (const identifier of Object.keys(dbs)) {
         const db = dbs[identifier]
         const structureFilePath = path.join(dbDir, `structure-${identifier}.sql`)
         const structureSql = await fs.readFile(structureFilePath, "utf8")
 
-        await this.loadStructureSql({db, structureSql})
+        await loader.load({db, structureSql})
       }
     })
   }
-
-  /**
-   * Runs load structure sql.
-   * @param {object} args - Options object.
-   * @param {import("../../../../../../database/drivers/base.js").default} args.db - Database connection.
-   * @param {string} args.structureSql - Structure SQL to load.
-   * @returns {Promise<void>} - Resolves when complete.
-   */
-  async loadStructureSql({db, structureSql}) {
-    const statements = splitSqlStatements(structureSql)
-
-    if (statements.length == 0) return
-
-    const executableConnection = this.executableConnection(db)
-
-    await db.disableForeignKeys()
-
-    try {
-      if (executableConnection) {
-        await executableConnection.exec(structureSql)
-      } else {
-        for (const statement of statements) {
-          await db.query(statement)
-        }
-      }
-    } finally {
-      await db.enableForeignKeys()
-    }
-  }
-
-  /**
-   * Runs executable connection.
-   * @param {import("../../../../../../database/drivers/base.js").default} db - Database connection.
-   * @returns {{exec: (sql: string) => Promise<?>} | undefined} - Connection with exec support.
-   */
-  executableConnection(db) {
-    const dbWithConnection = /** @type {import("../../../../../../database/drivers/base.js").default & {connection?: ?}} */ (db)
-    const connection = dbWithConnection.connection
-
-    if (connection && typeof connection == "object" && "exec" in connection && typeof connection.exec == "function") {
-      return /** @type {{exec: (sql: string) => Promise<?>}} */ (connection)
-    }
-  }
 }

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)
+  })
+}