velocious 1.0.652 → 1.0.653

package/README.md

@@ -1683,9 +1683,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()