velocious 1.0.493 → 1.0.495

package/src/sync/sync-resource-base.js

@@ -3,7 +3,11 @@
 import {forcedNonBlankStringParam} from "typanic"
 
 import FrontendModelBaseResource from "../frontend-model-resource/base-resource.js"
+import normalizeAttributesWithSchema from "./sync-attribute-normalizer.js"
 import SyncModelChangeFeedService from "./sync-model-change-feed-service.js"
+import VelociousError from "../velocious-error.js"
+
+const QUICK_SEARCH_COLUMN = "quickSearch"
 
 /**
  * Optional client-declared sync scope carried on a changes request.
@@ -22,6 +26,105 @@ import SyncModelChangeFeedService from "./sync-model-change-feed-service.js"
  * @augments {FrontendModelBaseResource<TModelClass>}
  */
 export default class SyncResourceBase extends FrontendModelBaseResource {
+  /**
+   * Declarative quick-search text columns. When declared, an index search on
+   * the pseudo-column `quickSearch` expands to an OR of LIKE conditions over
+   * these root-table columns instead of hitting the controller default.
+   * @type {string[] | null} */
+  static quickSearchColumns = null
+
+  /**
+   * Declarative writable-attribute schema consumed by
+   * {@link SyncResourceBase#normalizeWritableAttributes}, keyed by camelCase
+   * attribute name.
+   * @type {Record<string, import("./sync-attribute-normalizer.js").SyncAttributeSchemaEntry> | null} */
+  static writableAttributes = null
+
+  /**
+   * Applies frontend-model index searches, expanding declared quick searches.
+   * @param {object} args - Search args.
+   * @param {import("../frontend-model-resource/base-resource.js").FrontendModelResourceController} args.controller - Controller handling the query.
+   * @param {import("../frontend-model-resource/base-resource.js").FrontendModelResourceAnyQuery} args.query - Query instance.
+   * @param {import("../frontend-model-resource/base-resource.js").FrontendModelResourceSearch} args.search - Search params.
+   * @returns {void}
+   */
+  applyFrontendModelIndexSearch({controller, query, search}) {
+    if (this.applyQuickSearch({query, search})) return
+
+    super.applyFrontendModelIndexSearch({controller, query, search})
+  }
+
+  /**
+   * Expands a `quickSearch` pseudo-column search into an OR of LIKE conditions
+   * over the declared {@link SyncResourceBase.quickSearchColumns}.
+   * @param {object} args - Search args.
+   * @param {import("../frontend-model-resource/base-resource.js").FrontendModelResourceAnyQuery} args.query - Query to filter.
+   * @param {import("../frontend-model-resource/base-resource.js").FrontendModelResourceSearch} args.search - Search payload.
+   * @returns {boolean} Whether the search was handled as a quick search.
+   */
+  applyQuickSearch({query, search}) {
+    const quickSearchColumns = /** @type {typeof SyncResourceBase} */ (this.constructor).quickSearchColumns
+
+    if (!quickSearchColumns || quickSearchColumns.length === 0) return false
+    if (search.path.length > 0 || search.column !== QUICK_SEARCH_COLUMN) return false
+
+    if (search.operator !== "like") {
+      throw VelociousError.safe("Sync quick search must use the like operator.", {code: "sync-invalid-quick-search"})
+    }
+
+    if (typeof search.value !== "string") {
+      throw VelociousError.safe("Sync quick search must be a string.", {code: "sync-invalid-quick-search"})
+    }
+
+    const trimmedValue = search.value.trim()
+
+    if (!trimmedValue) return true
+
+    const tableSql = query.driver.quoteTable(query.getTableReferenceForJoin())
+    const likeValue = `%${trimmedValue}%`
+    const conditions = quickSearchColumns.map((columnName) => (
+      `${tableSql}.${query.driver.quoteColumn(columnName)} LIKE ${query.driver.quote(likeValue)}`
+    ))
+
+    query.where(`(${conditions.join(" OR ")})`)
+
+    return true
+  }
+
+  /**
+   * Normalizes incoming writable attributes through the declared
+   * {@link SyncResourceBase.writableAttributes} schema: camelCase and
+   * snake_case input keys are accepted, values are validated per type and the
+   * normalized values are written under snake_case column keys. Validation
+   * failures throw client-safe errors built by
+   * {@link SyncResourceBase#writableAttributeError}.
+   * @param {Record<string, ?>} attributes - Raw incoming attributes.
+   * @param {{unknownAttributes?: "error" | "ignore"}} [options] - Unknown input-key handling. Defaults to "error".
+   * @returns {Record<string, ?>} Normalized attributes keyed by column names.
+   */
+  normalizeWritableAttributes(attributes, options = {}) {
+    const schema = /** @type {typeof SyncResourceBase} */ (this.constructor).writableAttributes
+
+    if (!schema) throw new Error(`${this.constructor.name} must define static writableAttributes to use normalizeWritableAttributes`)
+
+    return normalizeAttributesWithSchema({
+      attributes,
+      errorFactory: (message, details) => this.writableAttributeError(message, details),
+      schema,
+      unknownAttributes: options.unknownAttributes
+    })
+  }
+
+  /**
+   * Builds the client-safe error thrown for a failed writable-attribute validation.
+   * @param {string} message - Human-readable validation message.
+   * @param {{cause?: Error, code: string}} details - Stable machine-readable code and optional cause.
+   * @returns {Error} Client-safe error.
+   */
+  writableAttributeError(message, {cause, code}) {
+    return VelociousError.safe(message, cause ? {cause, code} : {code})
+  }
+
   /**
    * Returns a stable change-feed page after app authorization.
    * @returns {Promise<Record<string, ?>>} Change-feed page result.

package/src/testing/test-runner.js

@@ -187,6 +187,8 @@ export default class TestRunner {
     this._testsCount = 0
     this._activeAfterAllScopes = []
     this._failedTestDetails = []
+    /** @type {{fullDescription: string, filePath: string, line: number} | null} */
+    this._lastTestContext = null
   }
 
   /**
@@ -638,16 +640,80 @@ export default class TestRunner {
    * Runs run.
    * @returns {Promise<void>} - Resolves when complete.
    */
+  /**
+   * Records an asynchronous crash (an unhandled promise rejection detached from
+   * any await, e.g. a `void connection.afterCommit(async () => broadcast(...))`
+   * frontend-model publish) as a real, visible, attributed test failure.
+   *
+   * Without this, such a rejection has no handler, so on modern Node the process
+   * is TERMINATED — the run ends with no reported failures and CI just sees a
+   * crashed/retried shard with an empty result (the recurring "silent
+   * test-runner death": invisible and impossible to diagnose). Turning it into a
+   * failure makes the run go red with something debuggable instead of vanishing.
+   * @param {"unhandledRejection"} kind - Async-crash kind.
+   * @param {unknown} reason - Rejection reason.
+   * @returns {void}
+   */
+  recordAsyncCrash(kind, reason) {
+    const error = reason instanceof Error ? reason : new Error(`${kind}: ${String(reason)}`)
+    const near = this._lastTestContext
+    const attribution = near ? `, near test: ${near.fullDescription} (${near.filePath}:${near.line})` : ""
+
+    this._failedTests = (this._failedTests || 0) + 1
+    this._failedTestDetails.push({
+      fullDescription: `<${kind} during test run${attribution}>`,
+      filePath: near ? near.filePath : "<test runner>",
+      line: near ? near.line : 0,
+      error,
+      consoleOutput: undefined
+    })
+
+    console.error(picocolors.red(`\n[test-runner] ${kind} during the test run — this would otherwise terminate the process silently and surface only as a crashed/retried shard with zero reported failures.${attribution}`))
+    console.error(error)
+  }
+
   async run() {
-    await this.getConfiguration().ensureConnections({name: "Test runner suite"}, async () => {
-      await this.runTests({
-        afterEaches: [],
-        beforeEaches: [],
-        tests,
-        descriptions: [],
-        indentLevel: 0
+    /**
+     * Handles a process-level unhandled rejection during the run.
+     * @param {unknown} reason - Rejection reason.
+     * @returns {void}
+     */
+    const onUnhandledRejection = (reason) => {
+      // If a test attached its OWN unhandledRejection listener, it is
+      // intentionally observing/triggering the rejection (e.g. beacon
+      // error-reporting-spec.js) — Node dispatches to EVERY listener, so also
+      // failing the suite here would break those tests. Defer to the test's
+      // handler; only treat a rejection as a silent-death crash when ours is the
+      // sole listener (no persistent framework listener exists to mask this).
+      if (process.listenerCount("unhandledRejection") > 1) return
+
+      this.recordAsyncCrash("unhandledRejection", reason)
+    }
+
+    process.on("unhandledRejection", onUnhandledRejection)
+
+    try {
+      await this.getConfiguration().ensureConnections({name: "Test runner suite"}, async () => {
+        await this.runTests({
+          afterEaches: [],
+          beforeEaches: [],
+          tests,
+          descriptions: [],
+          indentLevel: 0
+        })
+
+        // A rejection scheduled by the final test (a detached rejected promise,
+        // or an afterCommit callback rejecting as the suite drains) is reported
+        // by Node on a LATER turn. Drain a few turns while the handler is still
+        // attached — and connections still open — so those late rejections are
+        // recorded instead of escaping to the default crash path after cleanup.
+        for (let drainTurn = 0; drainTurn < 3; drainTurn++) {
+          await new Promise((resolve) => setImmediate(resolve))
+        }
       })
-    })
+    } finally {
+      process.off("unhandledRejection", onUnhandledRejection)
+    }
   }
 
   /**
@@ -798,6 +864,14 @@ export default class TestRunner {
                     await beforeEachData.callback({configuration: this.getConfiguration(), testArgs, testData})
                   }
 
+                  // Record which test is running so an async crash (an unhandled
+                  // rejection detached from any await) that fires during or shortly
+                  // after this test can be attributed to it in run()'s handler.
+                  this._lastTestContext = {
+                    fullDescription: this.buildFullDescription(descriptions, testDescription),
+                    filePath: testData.filePath ?? "<unknown>",
+                    line: testData.line ?? 0
+                  }
                   await testData.function(testArgs)
                   this._successfulTests++
                 } finally {