velocious 1.0.562 → 1.0.564

package/build/utils/backtrace-cleaner.js

@@ -1,3 +1,11 @@
+/**
+ * ParsedStackFrame type.
+ * @typedef {object} ParsedStackFrame
+ * @property {string | undefined} methodName - Method/function name from the stack frame.
+ * @property {string} sourcePath - File or URL path from the stack frame.
+ * @property {number} lineNumber - Source line number.
+ * @property {number | undefined} columnNumber - Source column number.
+ */
 // @ts-check
 
 /**
@@ -9,15 +17,6 @@ function escapeRegExp(value) {
   return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
 }
 
-/**
- * ParsedStackFrame type.
- * @typedef {object} ParsedStackFrame
- * @property {string | undefined} methodName - Method/function name from the stack frame.
- * @property {string} sourcePath - File or URL path from the stack frame.
- * @property {number} lineNumber - Source line number.
- * @property {number | undefined} columnNumber - Source column number.
- */
-
 /**
  * Runs normalize path.
  * @param {string | undefined} value - Path or file URL.

package/build/utils/model-scope.js

@@ -1,7 +1,3 @@
-// @ts-check
-
-const MODEL_SCOPE_DESCRIPTOR_MARKER = "velociousModelScopeDescriptor"
-
 /**
  * ModelScopeDescriptor type.
  * @typedef {object} ModelScopeDescriptor
@@ -10,6 +6,9 @@ const MODEL_SCOPE_DESCRIPTOR_MARKER = "velociousModelScopeDescriptor"
  * @property {typeof import("../database/record/index.js").default | import("../frontend-models/base.js").FrontendModelClass} modelClass - Owning model class.
  * @property {Array<?>} scopeArgs - Scope arguments.
  */
+// @ts-check
+
+const MODEL_SCOPE_DESCRIPTOR_MARKER = "velociousModelScopeDescriptor"
 
 /**
  * Runs the defineModelScope helper.

package/build/utils/ransack.js

@@ -4,50 +4,24 @@ import * as inflection from "inflection"
 import {isPlainObject} from "is-plain-object"
 import {resolveFrontendModelClass} from "../frontend-models/model-registry.js"
 
-/** Error raised when a Ransack descriptor is malformed. */
-export class RansackQueryError extends Error {
-  /**
-   * Creates a Ransack query error.
-   * @param {string} message - Error message.
-   */
-  constructor(message) {
-    super(message)
-
-    this.name = "RansackQueryError"
-  }
-}
-
-/**
- * Builds a Ransack query error.
- * @param {string} message - Error message.
- * @returns {RansackQueryError} - Ransack query error.
- */
-function ransackQueryError(message) {
-  return new RansackQueryError(message)
-}
-
 /**
  * RansackPredicate type.
  * @typedef {"cont" | "end" | "eq" | "gt" | "gteq" | "in" | "lt" | "lteq" | "not_eq" | "not_in" | "null" | "start"} RansackPredicate
  */
-
 /**
  * RansackCombinator type.
  * @typedef {"and" | "or"} RansackCombinator
  */
-
 /**
  * RansackModelClass type.
  * @typedef {typeof import("../database/record/index.js").default | import("../frontend-models/base.js").FrontendModelClass} RansackModelClass
  */
-
 /**
  * RansackAttribute type.
  * @typedef {object} RansackAttribute
  * @property {string} attributeName - Resolved attribute name.
  * @property {string[]} path - Resolved relationship path.
  */
-
 /**
  * RansackCondition type.
  * @typedef {object} RansackCondition
@@ -56,7 +30,6 @@ function ransackQueryError(message) {
  * @property {RansackPredicate} predicate - Parsed Ransack predicate.
  * @property {?} value - Normalized value.
  */
-
 /**
  * RansackGroup type.
  * @typedef {object} RansackGroup
@@ -64,6 +37,33 @@ function ransackQueryError(message) {
  * @property {RansackCondition[]} conditions - Conditions in this group.
  * @property {RansackGroup[]} groupings - Nested groups.
  */
+/**
+ * RansackSort type.
+ * @typedef {object} RansackSort
+ * @property {string} attribute - Resolved attribute name.
+ * @property {"asc" | "desc"} direction - Sort direction.
+ */
+/** Error raised when a Ransack descriptor is malformed. */
+export class RansackQueryError extends Error {
+  /**
+   * Creates a Ransack query error.
+   * @param {string} message - Error message.
+   */
+  constructor(message) {
+    super(message)
+
+    this.name = "RansackQueryError"
+  }
+}
+
+/**
+ * Builds a Ransack query error.
+ * @param {string} message - Error message.
+ * @returns {RansackQueryError} - Ransack query error.
+ */
+function ransackQueryError(message) {
+  return new RansackQueryError(message)
+}
 
 const supportedPredicates = [
   "not_in",
@@ -803,13 +803,6 @@ function normalizeRansackArray(value) {
   return [value]
 }
 
-/**
- * RansackSort type.
- * @typedef {object} RansackSort
- * @property {string} attribute - Resolved attribute name.
- * @property {"asc" | "desc"} direction - Sort direction.
- */
-
 /**
  * Parses a ransack `s` sort string against model attributes.
  * @param {RansackModelClass} modelClass - Model class for attribute lookup.

package/package.json

@@ -3,7 +3,7 @@
     "velocious": "build/bin/velocious.js"
   },
   "name": "velocious",
-  "version": "1.0.562",
+  "version": "1.0.564",
   "main": "build/index.js",
   "types": "build/index.d.ts",
   "files": [
@@ -20,6 +20,7 @@
     "benchmark:preloader-id-dedup": "node benchmark/preloader-id-dedup.js",
     "benchmark:mysql-result-row-materialization": "node benchmark/mysql-result-row-materialization.js",
     "benchmark:query-roundtrip-batching": "node benchmark/query-roundtrip-batching.js",
+    "benchmark:websocket-outbound-queue": "node benchmark/websocket-outbound-queue.js",
     "benchmark:websocket-frame-buffering": "node benchmark/websocket-frame-buffering.js",
     "build": "node scripts/clean-build.js && npm run compile",
     "compile": "tsc -b && npm run copy:js && npm run copy:ejs && npm run copy:templates && node scripts/ensure-bin-executable.js",
@@ -117,6 +118,7 @@
     "react": "^19.2.0",
     "react-dom": "^19.2.0",
     "release-patch": "^1.0.0",
+    "selenium-webdriver": "^4.39.0",
     "sqlite": "^5.1.1",
     "sqlite3": "^6.0.1",
     "system-testing": "^1.0.108",

package/scripts/eslint-rules/typedefs-first.js

@@ -0,0 +1,67 @@
+/**
+ * Reports top-level JSDoc typedef declarations placed after runtime declarations.
+ */
+export default {
+  meta: {
+    docs: {
+      description: "Require top-level JSDoc typedefs before runtime declarations"
+    },
+    messages: {
+      typedefsFirst: "Move top-level JSDoc typedef declarations before runtime declarations."
+    },
+    schema: [],
+    type: "suggestion",
+    fixable: "code"
+  },
+  create(context) {
+    const sourceCode = context.sourceCode
+
+    return {
+      "Program:exit"(program) {
+        const runtimeDeclarations = program.body.filter((node) => {
+          return node.type != "ImportDeclaration"
+        })
+        const firstRuntimeDeclaration = runtimeDeclarations[0]
+
+        if (!firstRuntimeDeclaration) return
+
+        const misplacedTypedefs = sourceCode.getAllComments().filter((comment) => {
+          if (!/@typedef(?:\s|\{)/u.test(comment.value)) return false
+          if (comment.range[0] < firstRuntimeDeclaration.range[0]) return false
+
+          return !runtimeDeclarations.some((node) => {
+            return node.range[0] < comment.range[0] && node.range[1] > comment.range[1]
+          })
+        })
+
+        if (misplacedTypedefs.length == 0) return
+
+        context.report({
+          loc: misplacedTypedefs[0].loc,
+          messageId: "typedefsFirst",
+          fix(fixer) {
+            const leadingComments = sourceCode.getCommentsBefore(firstRuntimeDeclaration)
+            const firstOrdinaryComment = leadingComments.find((comment) => comment.type != "Shebang")
+            const insertionPoint = firstOrdinaryComment?.range[0] ?? firstRuntimeDeclaration.range[0]
+            const movedComments = misplacedTypedefs.map((comment) => sourceCode.getText(comment)).join("\n")
+            const fixes = [fixer.insertTextBeforeRange([insertionPoint, insertionPoint], `${movedComments}\n`)]
+
+            for (const comment of misplacedTypedefs) {
+              let removalEnd = comment.range[1]
+
+              if (sourceCode.text[removalEnd] == "\r" && sourceCode.text[removalEnd + 1] == "\n") {
+                removalEnd += 2
+              } else if (sourceCode.text[removalEnd] == "\n") {
+                removalEnd++
+              }
+
+              fixes.push(fixer.removeRange([comment.range[0], removalEnd]))
+            }
+
+            return fixes
+          }
+        })
+      }
+    }
+  }
+}

package/scripts/prewarm-chromedriver.js

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+
+import fs from "node:fs"
+import { createRequire } from "node:module"
+
+const require = createRequire(import.meta.url)
+const { binaryPaths } = require("selenium-webdriver/common/seleniumManager.js")
+const { browserPath, driverPath } = binaryPaths([
+  "--browser",
+  "chrome",
+  "--language-binding",
+  "javascript",
+  "--output",
+  "json",
+  "--avoid-browser-download"
+])
+
+if (!browserPath || !fs.existsSync(browserPath)) {
+  throw new Error(`Selenium Manager did not find installed Chrome at ${browserPath || "<missing path>"}`)
+}
+
+if (!driverPath || !fs.existsSync(driverPath)) {
+  throw new Error(`Selenium Manager did not provision ChromeDriver at ${driverPath || "<missing path>"}`)
+}
+
+console.log(`Prewarmed ChromeDriver at ${driverPath} for Chrome at ${browserPath}`)

package/src/background-jobs/cron-expression.js

@@ -1,3 +1,15 @@
+/**
+ * ParsedCron type.
+ * @typedef {object} ParsedCron
+ * @property {Set<number>} minute - Allowed minute values (0-59).
+ * @property {Set<number>} hour - Allowed hour values (0-23).
+ * @property {Set<number>} dayOfMonth - Allowed day-of-month values (1-31).
+ * @property {Set<number>} month - Allowed month values (1-12).
+ * @property {Set<number>} dayOfWeek - Allowed day-of-week values (0-6, 0=Sun).
+ * @property {boolean} dayOfMonthRestricted - True when the dayOfMonth field is not `?`.
+ * @property {boolean} dayOfWeekRestricted - True when the dayOfWeek field is not `?`.
+ * @property {string} expression - Original expression for diagnostics.
+ */
 // @ts-check
 
 /**
@@ -36,19 +48,6 @@ const FIELDS = [
   {name: "dayOfWeek", min: 0, max: 7, names: DAY_NAMES}
 ]
 
-/**
- * ParsedCron type.
- * @typedef {object} ParsedCron
- * @property {Set<number>} minute - Allowed minute values (0-59).
- * @property {Set<number>} hour - Allowed hour values (0-23).
- * @property {Set<number>} dayOfMonth - Allowed day-of-month values (1-31).
- * @property {Set<number>} month - Allowed month values (1-12).
- * @property {Set<number>} dayOfWeek - Allowed day-of-week values (0-6, 0=Sun).
- * @property {boolean} dayOfMonthRestricted - True when the dayOfMonth field is not `?`.
- * @property {boolean} dayOfWeekRestricted - True when the dayOfWeek field is not `?`.
- * @property {string} expression - Original expression for diagnostics.
- */
-
 /**
  * Runs the parseCronExpression helper.
  * @param {string} expression - Cron expression or shortcut.

package/src/background-jobs/main.js

@@ -9,6 +9,12 @@ import PruneTerminalBackgroundJobsJob from "../jobs/prune-terminal-background-jo
 import VelociousError from "../velocious-error.js"
 import shutdownLifecycle from "../utils/shutdown-lifecycle.js"
 
+/**
+ * WorkerExecutionModeCapability type.
+ * @typedef {object} WorkerExecutionModeCapability
+ * @property {import("./types.js").BackgroundJobExecutionMode} executionMode - Execution mode.
+ * @property {(worker: JsonSocket) => boolean} accepts - Whether the worker accepts this mode.
+ */
 /**
  * Channel used by `background-jobs-main` to coordinate dispatch wake-ups
  * across processes via Beacon. Workers do NOT subscribe to this channel
@@ -28,12 +34,6 @@ const MAX_TIMER_MS = 2_147_483_647 // ~24.8 days
 const WORKER_STALE_TIMEOUT_MS = 60000
 /** How often the main scans workers for staleness. */
 const WORKER_LIVENESS_SWEEP_MS = 15000
-/**
- * WorkerExecutionModeCapability type.
- * @typedef {object} WorkerExecutionModeCapability
- * @property {import("./types.js").BackgroundJobExecutionMode} executionMode - Execution mode.
- * @property {(worker: JsonSocket) => boolean} accepts - Whether the worker accepts this mode.
- */
 /**
  * Worker execution mode capabilities.
  * @type {WorkerExecutionModeCapability[]} */

package/src/background-jobs/runner-graceful-shutdown.js

@@ -4,15 +4,14 @@ import timeout from "awaitery/build/timeout.js"
 
 import Configuration, {CurrentConfigurationNotSetError} from "../configuration.js"
 
-/** Bounded grace for closing framework connections on shutdown before forcing exit. */
-const SHUTDOWN_CLOSE_TIMEOUT_MS = 5000
-
 /**
  * The subset of a configuration a runner closes on shutdown. Typed structurally so
  * the shutdown path stays typechecked without a broad cast, and a future signature
  * drift surfaces at the call sites (and in tests) instead of hiding behind `any`.
  * @typedef {{disconnectBeacon: () => Promise<void>, closeDatabaseConnections: () => Promise<void>}} RunnerCloseableConfiguration
  */
+/** Bounded grace for closing framework connections on shutdown before forcing exit. */
+const SHUTDOWN_CLOSE_TIMEOUT_MS = 5000
 
 /**
  * Gracefully closes a background-job runner's framework connections (beacon +

package/src/background-jobs/scheduler.js

@@ -3,6 +3,9 @@
 import Logger from "../logger.js"
 import {nextCronFireDate, parseCronExpression} from "./cron-expression.js"
 
+/**
+ * DurationUnit type.
+ * @typedef {keyof typeof DURATION_MULTIPLIERS} DurationUnit */
 const DURATION_MULTIPLIERS = {
   d: 24 * 60 * 60 * 1000,
   day: 24 * 60 * 60 * 1000,
@@ -21,9 +24,6 @@ const DURATION_MULTIPLIERS = {
   week: 7 * 24 * 60 * 60 * 1000,
   weeks: 7 * 24 * 60 * 60 * 1000
 }
-/**
- * DurationUnit type.
- * @typedef {keyof typeof DURATION_MULTIPLIERS} DurationUnit */
 
 /**
  * Runs the parseScheduledDuration helper.

package/src/background-jobs/worker.js

@@ -10,6 +10,14 @@ import {randomUUID} from "crypto"
 import {fileURLToPath} from "node:url"
 import shutdownLifecycle from "../utils/shutdown-lifecycle.js"
 
+/**
+ * Per-forked-child timeout bookkeeping.
+ * @typedef {object} ForkedJobTimeoutState
+ * @property {boolean} timedOut - Whether the timeout fired and the child was terminated.
+ * @property {number | null} timeoutMs - The armed timeout in ms, or null when disabled.
+ * @property {ReturnType<typeof setTimeout> | null} timer - The pending timeout timer, cleared on exit.
+ * @property {ReturnType<typeof setTimeout> | null} sigkillTimer - The pending SIGKILL grace timer, cleared on exit.
+ */
 /** Grace period after SIGTERM before a lingering process runner is SIGKILLed. */
 const FORKED_CHILD_SIGKILL_GRACE_MS = 5000
 /**
@@ -48,15 +56,6 @@ function positiveNumber(value) {
   return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : undefined
 }
 
-/**
- * Per-forked-child timeout bookkeeping.
- * @typedef {object} ForkedJobTimeoutState
- * @property {boolean} timedOut - Whether the timeout fired and the child was terminated.
- * @property {number | null} timeoutMs - The armed timeout in ms, or null when disabled.
- * @property {ReturnType<typeof setTimeout> | null} timer - The pending timeout timer, cleared on exit.
- * @property {ReturnType<typeof setTimeout> | null} sigkillTimer - The pending SIGKILL grace timer, cleared on exit.
- */
-
 export default class BackgroundJobsWorker {
   /**
    * Runs constructor.

package/src/beacon/client.js

@@ -7,14 +7,13 @@ import timeout from "awaitery/build/timeout.js"
 import JsonSocket from "../background-jobs/json-socket.js"
 import EventEmitter from "../utils/event-emitter.js"
 
-const DEFAULT_RECONNECT_DELAY_MS = 1000
-const MAX_RECONNECT_DELAY_MS = 30_000
-const DEFAULT_CLOSE_TIMEOUT_MS = 1000
-
 /**
  * BeaconBroadcastHandler type.
  * @typedef {function(import("./types.js").BeaconBroadcastMessage): void} BeaconBroadcastHandler
  */
+const DEFAULT_RECONNECT_DELAY_MS = 1000
+const MAX_RECONNECT_DELAY_MS = 30_000
+const DEFAULT_CLOSE_TIMEOUT_MS = 1000
 
 /**
  * BeaconClient connects to a `velocious beacon` daemon and exchanges

package/src/configuration-types.js

@@ -255,6 +255,7 @@
  * @property {boolean} [inProcess] - Run HTTP handlers in the main thread instead of worker threads.
  * @property {number} [maxWorkers] - Backward-compatible alias for workers.
  * @property {number} [port] - Port to bind the HTTP server to.
+ * @property {{maxPendingBytes?: number, maxPendingFrames?: number}} [websocketOutboundQueue] - Per-client retained outbound WebSocket frame limits.
  * @property {number} [workers] - Worker handlers to start for the HTTP server.
  */
 

package/src/configuration.js

@@ -114,6 +114,25 @@ function resolveBeaconUnreachableReportMs(value) {
   return 30_000
 }
 
+const DEFAULT_WEBSOCKET_OUTBOUND_MAX_PENDING_BYTES = 16 * 1024 * 1024
+const DEFAULT_WEBSOCKET_OUTBOUND_MAX_PENDING_FRAMES = 256
+
+/**
+ * Validates a positive safe integer configuration value.
+ * @param {?} value - Configured positive safe integer.
+ * @param {string} name - Configuration key.
+ * @param {number} defaultValue - Default value.
+ * @returns {number} - Validated configured or default value.
+ */
+function positiveSafeInteger(value, name, defaultValue) {
+  if (value === undefined) return defaultValue
+  if (typeof value !== "number" || !Number.isSafeInteger(value) || value <= 0) {
+    throw new TypeError(`${name} must be a positive safe integer`)
+  }
+
+  return value
+}
+
 export default class VelociousConfiguration {
   /**
    * Close database connections promise.
@@ -209,7 +228,15 @@ export default class VelociousConfiguration {
      * @type {Promise<void> | undefined}
      */
     this._initializePromise = undefined
-    this.httpServer = httpServer || {}
+    const websocketOutboundQueue = httpServer?.websocketOutboundQueue
+
+    this.httpServer = {
+      ...(httpServer || {}),
+      websocketOutboundQueue: {
+        maxPendingBytes: positiveSafeInteger(websocketOutboundQueue?.maxPendingBytes, "httpServer.websocketOutboundQueue.maxPendingBytes", DEFAULT_WEBSOCKET_OUTBOUND_MAX_PENDING_BYTES),
+        maxPendingFrames: positiveSafeInteger(websocketOutboundQueue?.maxPendingFrames, "httpServer.websocketOutboundQueue.maxPendingFrames", DEFAULT_WEBSOCKET_OUTBOUND_MAX_PENDING_FRAMES)
+      }
+    }
     /**
      * Stores the http server instance value.
      * @type {{getDebugSnapshot: () => Promise<Record<string, ?>>} | undefined} */
@@ -1693,7 +1720,8 @@ export default class VelociousConfiguration {
       websocketEvents.broadcastV2({
         channel: message.channel,
         broadcastParams: message.broadcastParams,
-        body: message.body
+        body: message.body,
+        configuration: this
       })
       return
     }
@@ -2342,6 +2370,19 @@ export default class VelociousConfiguration {
    */
   getWebsocketSessionHeartbeatSeconds() { return this._websocketSessionHeartbeatSeconds }
 
+  /**
+   * Gets per-client WebSocket outbound queue limits.
+   * @returns {{maxBytes: number, maxFrames: number}} - Per-client outbound queue high-water marks.
+   */
+  getWebsocketOutboundQueueLimits() {
+    const queue = this.httpServer.websocketOutboundQueue
+
+    return {
+      maxBytes: queue.maxPendingBytes,
+      maxFrames: queue.maxPendingFrames
+    }
+  }
+
   /**
    * Registers a wrapper invoked around every WS-borne request /
    * connection message / channel dispatch. The wrapper receives the
@@ -2537,7 +2578,7 @@ export default class VelociousConfiguration {
     const websocketEvents = this._websocketEvents
 
     if (websocketEvents && typeof websocketEvents.broadcastV2 === "function") {
-      websocketEvents.broadcastV2({channel: name, broadcastParams, body})
+      websocketEvents.broadcastV2({channel: name, broadcastParams, body, configuration: this})
       return
     }
 

package/src/database/drivers/sqlite/web-persistence.js

@@ -2,9 +2,6 @@
 
 import BetterLocalStorage from "better-localstorage"
 
-const SUPPORT_CHECK_FILE = ".velocious-opfs-support-check"
-const SUPPORT_CHECK_BYTES = new Uint8Array([118, 101, 108, 111, 99, 105, 111, 117, 115])
-
 /**
  * SQLite web persistence adapter.
  * @typedef {object} SqliteWebPersistence
@@ -13,13 +10,14 @@ const SUPPORT_CHECK_BYTES = new Uint8Array([118, 101, 108, 111, 99, 105, 111, 11
  * @property {() => Promise<Uint8Array | undefined>} load - Loads persisted database bytes.
  * @property {(content: Uint8Array) => Promise<void>} save - Saves persisted database bytes.
  */
-
 /**
  * Browser-like environment used for web persistence detection.
  * @typedef {object} SqliteWebPersistenceEnvironment
  * @property {unknown} [indexedDB] - IndexedDB global.
  * @property {unknown} [navigator] - Navigator global.
  */
+const SUPPORT_CHECK_FILE = ".velocious-opfs-support-check"
+const SUPPORT_CHECK_BYTES = new Uint8Array([118, 101, 108, 111, 99, 105, 111, 117, 115])
 
 /**
  * Creates the best SQLite web persistence adapter supported by the current browser.
@@ -297,7 +295,6 @@ class LocalStoragePersistence {
   }
 }
 
-
 /**
  * Selects the preferred available SQLite web persistence backend.
  * @param {object} args - Arguments.