velocious 1.0.652 → 1.0.654

package/README.md

@@ -178,7 +178,7 @@ Baselines are generated against a fresh checkout (no generated dummy `configurat
 # Testing
 
 Application tests may import the testing DSL from the independent public package.
-`@velocious/testing` `0.0.9` is the declaration and execution engine. Compatible
+`@velocious/testing` `0.0.12` is the declaration and execution engine. Compatible
 installed copies share one protocol-1/schema-3 default registry. Velocious adapts each
 package-owned attempt with its database, request, profiling, and cleanup behavior; the
 existing Velocious facade exports the same declaration DSL and remains supported.
@@ -327,6 +327,8 @@ Use `consoleOutput: "live"` to preserve the previous passthrough behavior where
 
 Listen for attempt and retry events if you need to reset shared state after a failed attempt or log retry lifecycle details. `testAttemptFailed` fires after every failed attempt, including the final failed attempt when no retries remain. `testRetrying` only fires before a retry, and `testFailed` only fires after retries are exhausted.
 
+A shared resource owner may throw an error carrying `terminalResource: {scope: "run", name: "shared-resource"}`. With a compatible `@velocious/testing` runner, Velocious preserves this contract through causes and aggregate errors, reports the originating failure with full causal stacks, suppresses retries, and emits `testNotRun` for later selected cases instead of running their callbacks. `testNotRun` receives `{configuration, test, testRunner}`; `test` has `status: "not-run"`, `fullName`, `location`, and the originating `reason`. `testRunner.getNotRunTests()` and `getNotRunTestDetails()` expose this separate accounting. Entered suites clean up once; the CLI exits unsuccessfully even for terminal setup with zero executed cases. Unmatched filters retain their explanatory message and `no-tests` profile status, independently of terminal setup failures. This does not restart a browser or cancel already-issued work. Upgrade the shared runner and this reporter adapter together before enabling terminal resource owners; earlier shared runners ignore the marker. See [terminal resource reporting](docs/terminal-resource-reporting.md).
+
 ```js
 import {testEvents} from "velocious/build/src/testing/test.js"
 
@@ -1683,9 +1685,20 @@ const tasks = await Task.all().toArray()
 
 ### Filtering
 
+Use `{in: [...]}` for explicit null-aware membership. Mixed lists match either
+IN members or SQL NULL, grouped locally so sibling and chained filters still
+apply. Null-only lists use IS NULL; empty lists match nothing. Direct arrays keep
+their existing driver-specific behavior, including string-null quoting and
+column collation. See [Query filtering](docs/query-filtering.md) for
+validation, normalization, negation, relationships and raw-query boundaries.
+
 ```js
 const tasks = await Task.where({status: "open"}).toArray()
 
+const nullOrManualTasks = await Task
+  .where({projectId: project.id(), description: {in: [null, "manual"]}})
+  .toArray()
+
 const tasksForActiveProjects = await Task.where({
   project: {projectDetail: {isActive: true}}
 }).toArray()

package/build/database/query/model-class-query.js

@@ -1468,7 +1468,9 @@ function splitWhereHash({hash, modelClass}) {
     const isNested = isPlainObject(value)
     const relationship = getRelationshipByName(modelClass, key)
 
-    if (isNested) {
+    if (isNested && !relationship && resolveColumnName(modelClass, key)) {
+      resolvedHash[key] = value
+    } else if (isNested) {
       if (relationship) {
         const rawTargetModelClass = relationship.getTargetModelClass()
         if (!rawTargetModelClass) {

package/build/database/query/where-hash.js

@@ -1,6 +1,7 @@
 // @ts-check
 
 import WhereBase from "./where-base.js"
+import WhereIn from "./where-in.js"
 
 /**
  * VelociousDatabaseQueryWhereHash class.
@@ -50,7 +51,17 @@ export default class VelociousDatabaseQueryWhereHash extends WhereBase {
         if (index > 0) sql += " AND "
         sql += "1=0"
       } else if (!Array.isArray(whereValue) && whereValue !== null && typeof whereValue == "object") {
-        sql += this._whereSQLFromHash(whereValue, whereKey, index)
+        if (tableName && "in" in whereValue) {
+          if (index > 0) sql += " AND "
+
+          sql += WhereIn.toSql({
+            columnSql: `${options.quoteTableName(tableName)}.${options.quoteColumnName(whereKey)}`,
+            options,
+            values: WhereIn.values(whereValue)
+          })
+        } else {
+          sql += this._whereSQLFromHash(whereValue, whereKey, index)
+        }
       } else {
         if (index > 0) sql += " AND "
 

package/build/database/query/where-in.js

@@ -0,0 +1,48 @@
+// @ts-check
+
+/** @typedef {string | number | boolean | null} InValue */
+
+export default class WhereIn {
+  /**
+   * Validates an explicit membership descriptor at a column boundary.
+   * @param {unknown} condition - Untrusted column condition, narrowed before use.
+   * @returns {InValue[]} - Validated members in a new array.
+   */
+  static values(condition) {
+    if (condition === null || typeof condition !== "object" ||
+      !Object.hasOwn(condition, "in") || !("in" in condition) ||
+      Reflect.ownKeys(condition).length !== 1 || !Array.isArray(condition.in)) {
+      throw new Error("Invalid IN condition: expected an object with only an own 'in' array")
+    }
+
+    /** @type {InValue[]} */
+    const values = []
+
+    for (const value of condition.in) {
+      if (value !== null && typeof value !== "string" && typeof value !== "boolean" &&
+        !(typeof value === "number" && Number.isFinite(value))) {
+        throw new Error("Invalid IN condition: members must be strings, finite numbers, booleans or null")
+      }
+
+      values.push(value)
+    }
+
+    return values
+  }
+
+  /**
+   * Renders membership without letting its null branch escape sibling filters.
+   * @param {{columnSql: string, inColumnSql?: string, values: InValue[], options: import("../query-parser/options.js").default}} args - Quoted column operands, normalized members and driver quoting.
+   * @returns {string} - Complete membership predicate.
+   */
+  static toSql({columnSql, inColumnSql = columnSql, values, options}) {
+    const nonNullValues = values.filter((value) => value !== null)
+    const includesNull = values.includes(null)
+
+    if (nonNullValues.length === 0) return includesNull ? `${columnSql} IS NULL` : "1=0"
+
+    const membershipSql = `${inColumnSql} IN (${nonNullValues.map((value) => options.quote(value)).join(", ")})`
+
+    return includesNull ? `(${membershipSql} OR ${columnSql} IS NULL)` : membershipSql
+  }
+}

package/build/database/query/where-model-class-hash.js

@@ -3,6 +3,7 @@
 import * as inflection from "inflection"
 import {isPlainObject} from "is-plain-object"
 import WhereBase from "./where-base.js"
+import WhereIn from "./where-in.js"
 
 /**
  * No match.
@@ -378,6 +379,34 @@ export default class VelociousDatabaseQueryWhereModelClassHash extends WhereBase
     return normalized
   }
 
+  /**
+   * Normalizes explicit membership through the model's column metadata.
+   * @param {{modelClass: typeof import("../record/index.js").default, columnName: string, tableName?: string, condition: unknown}} args - Resolved column and untrusted membership descriptor.
+   * @returns {string} - Complete column membership predicate.
+   */
+  _whereSQLFromInCondition({modelClass, columnName, tableName, condition}) {
+    const options = this.getOptions()
+    const values = WhereIn.values(condition)
+    const normalizedValues = this._normalizeSqliteBooleanValue({columnName, modelClass, value: values})
+    /** @type {import("./where-in.js").InValue[] | typeof NO_MATCH} */
+    const typedValues = this._normalizeValueForColumnType({columnName, modelClass, value: normalizedValues})
+
+    if (typedValues === NO_MATCH) return "1=0"
+
+    const columnSql = tableName
+      ? `${options.quoteTableName(tableName)}.${options.quoteColumnName(columnName)}`
+      : options.quoteColumnName(columnName)
+    const columnType = modelClass.getColumnTypeByName(columnName)
+    const castText = this.getQuery().driver.getType() === "mssql" && columnType?.toLowerCase() === "text"
+
+    return WhereIn.toSql({
+      columnSql,
+      inColumnSql: castText ? `CAST(${columnSql} AS NVARCHAR(MAX))` : columnSql,
+      options,
+      values: typedValues
+    })
+  }
+
   /**
    * Runs where sqlfrom hash.
    * @param {WhereHash} hash - Hash.
@@ -400,7 +429,11 @@ export default class VelociousDatabaseQueryWhereModelClassHash extends WhereBase
         : null
       const resolvedColumnName = this._resolveColumnName(modelClass, whereKey)
 
-      if (relationship && tuples) {
+      if (resolvedColumnName && !relationship && isPlainObject(whereValue)) {
+        if (index > 0) sql += " AND "
+
+        sql += this._whereSQLFromInCondition({columnName: resolvedColumnName, condition: whereValue, modelClass, tableName})
+      } else if (relationship && tuples) {
         if (index > 0) sql += " AND "
 
         const rawTargetModelClass = relationship.getTargetModelClass()

package/build/environment-handlers/node/cli/commands/test.js

@@ -203,7 +203,7 @@ export default class VelociousCliCommandsTest extends BaseCommand {
       const hasExampleFilters = examplePatterns.length > 0
       const hasTagFilters = includeTags.length > 0 || effectiveExcludeTagCount > 0
 
-      if ((hasTagFilters || hasLineFilters || hasExampleFilters) && executedTests === 0) {
+      if ((hasTagFilters || hasLineFilters || hasExampleFilters) && testRunner.hasNoMatches()) {
         console.error(picocolors.red("\nNo tests matched the provided filters"))
         await finalizeProfile("no-tests")
         process.exit(1)
@@ -247,6 +247,7 @@ export default class VelociousCliCommandsTest extends BaseCommand {
           }
         }
 
+        if (testRunner.getNotRunTests() > 0) console.error(`${testRunner.getNotRunTests()} tests not run because a shared resource failed`)
         console.error(picocolors.red(`\nTest run failed with ${testRunner.getFailedTests()} failed tests and ${testRunner.getSuccessfulTests()} successfull`))
         await finalizeProfile("failed")
         process.exit(1)