@uniweb/core 0.26.2 → 0.28.0

package/src/where.js

@@ -7,6 +7,14 @@
  * (which translate to their native query language) or to this evaluator
  * (which walks the object against a record).
  *
+ * ⭐ ONE LANGUAGE, ONE MEANING PER OPERATOR, on every lane. A compiled site
+ * evaluates a query here; a host that answers queries evaluates the same
+ * language at the source. The set below is the language ruled on 2026-09-13
+ * [Diego] for a stored query and a question alike, so a query answers the same
+ * wherever it is asked. ⛔ Until then this evaluator had `like` and `nin` and none
+ * of `contains`, `starts_with`, `ends_with`, and it read `exists`, comparisons on
+ * a list and an empty `and` differently (measured).
+ *
  * Shape:
  *
  *   {
@@ -18,7 +26,7 @@
  *     // For non-equality, the value is an operator object.
  *     start_year: { gte: 2010 },
  *     rank: { in: ['associate', 'full'] },
- *     title: { like: 'Origin*' },
+ *     title: { starts_with: 'the' },
  *
  *     // Explicit composition keys at any nesting level.
  *     and: [{ tenured: true }, { rank: 'full' }],
@@ -28,57 +36,84 @@
  *
  * Operators (in operator-object form):
  *
- *   eq      Equal (also implicit when the value is bare, non-object, non-null).
- *   ne      Not equal.
- *   gt/gte  Greater than / greater than or equal.
- *   lt/lte  Less than / less than or equal.
- *   in      Value is in the listed array.
- *   nin     Value is not in the listed array.
- *   like    Glob match (`*` any run, `?` one char). String fields only.
- *   exists  Field is truthy (boolean toggle).
+ *   eq            Equal (also implicit when the value is bare).
+ *   ne            Not equal.
+ *   gt/gte        Greater than / greater than or equal.
+ *   lt/lte        Less than / less than or equal.
+ *   in            Equal to one of the listed values.
+ *   not_in        Equal to none of the listed values.
+ *   exists        `true`: the field has a value — not missing, null, "" or [].
+ *                 `false`: it has none.
+ *   contains      On a list, holds an item equal to the value; on a text, holds
+ *                 the value as a piece of it (plain text, case-insensitive).
+ *   starts_with   A text that starts with the value (plain text, case-insensitive).
+ *   ends_with     A text that ends with the value (plain text, case-insensitive).
  *
  * Composition keys:
  *
- *   and     Array of sub-predicates; all must match.
- *   or      Array of sub-predicates; at least one must match.
- *   not     Single sub-predicate; must not match.
+ *   and     A non-empty list of sub-predicates; all must match.
+ *   or      A non-empty list of sub-predicates; at least one must match.
+ *   not     One sub-predicate; must not match.
  *
- * ⛔ **`under` is retired (2026-09-11 [Diego]).** It existed for `where: { path:
- * { under: X } }` — a folder branch, written before a query had `scope:`. A branch
- * is a scope now, on both lanes (`./scope.js`), and the build refuses `under` with
- * a message naming `scope:`. An operator object carrying it is no longer an
- * operator object here, so it matches nothing: the build's refusal is the guard.
+ * ⭐ A LIST FIELD (`tags: ['news', 'rust']`) holds a condition when ANY member
+ * satisfies it: `tags: news` has `news`, `ne: news` does not have it, `not_in`
+ * has none of the values, a comparison holds for some member. Values stay typed:
+ * `'3'` does not equal `3`. A field a record has no value for satisfies `ne`,
+ * `not_in` and `exists: false`, and nothing else.
  *
- * Dotted paths descend into nested objects: `tenure.start: { gte: 2015 }`.
+ * ⛔ A WHERE OUTSIDE THE LANGUAGE SELECTS NO RECORDS — an unknown or retired
+ * operator (`like`, `nin`, `under`), an empty `and` / `or`, a text operator with an
+ * empty argument. It never falls back to a wider answer. `whereOutsideLanguage`
+ * says why, so a producer can refuse the declaration where the author wrote it.
  *
- * Type safety: type mismatches return `false` rather than throwing
- * (e.g., comparing a string to a number with `gt`). Missing fields
- * return `false` for equality and most operators; `exists: false` matches
- * missing/falsy fields.
+ * Dotted paths descend into nested objects: `tenure.start: { gte: 2015 }` — never one with
+ * an empty step, nor one starting at a `$` field (`field-path.js`). ⭐ A
+ * path that meets a list descends into each item, and the values it reaches are
+ * read as a list field — so `education.degree: PhD` matches a record any of whose
+ * `education` entries has that degree. (Kept on this lane by ruling 2026-09-13
+ * [Diego]; a host's records service may not answer them.)
  */
 
-const COMPOSITION_KEYS = new Set(['and', 'or', 'not'])
+import { fieldPathProblem } from './field-path.js'
+
 const OPERATORS = new Set([
-  'eq', 'ne', 'gt', 'gte', 'lt', 'lte', 'in', 'nin', 'like', 'exists',
+  'eq', 'ne', 'gt', 'gte', 'lt', 'lte', 'in', 'not_in', 'exists', 'contains', 'starts_with', 'ends_with',
 ])
 
+/** Retired spellings, each with the sentence that names its replacement. */
+const RETIRED_OPERATORS = {
+  nin: '`nin` is spelled `not_in`',
+  like: '`like` is retired — use `starts_with`, `ends_with` or `contains`',
+  under: '`under` is retired — a folder branch is `scope:`',
+}
+
+/**
+ * Why a where-object is outside the language, or null when it is inside.
+ *
+ * @param {*} where
+ * @returns {string|null} the first problem found, as a sentence
+ */
+export function whereOutsideLanguage(where) {
+  if (where == null) return null
+  if (typeof where !== 'object' || Array.isArray(where)) return 'a where is an object of conditions'
+  for (const [key, value] of Object.entries(where)) {
+    const problem = clauseProblem(key, value)
+    if (problem) return problem
+  }
+  return null
+}
+
 /**
  * Evaluate a where-object against a single record.
  *
  * @param {Object} where - The where-object predicate.
  * @param {Object} record - The record to test.
- * @returns {boolean} true if the record matches.
+ * @returns {boolean} true if the record matches; false for a where outside the language.
  */
 export function evaluate(where, record) {
   if (where == null) return true
-  if (typeof where !== 'object' || Array.isArray(where)) return false
-  if (record == null || typeof record !== 'object') return false
-
-  // Implicit AND across all top-level keys.
-  for (const key of Object.keys(where)) {
-    if (!evaluateClause(key, where[key], record)) return false
-  }
-  return true
+  if (whereOutsideLanguage(where)) return false
+  return test(where, record)
 }
 
 /**
@@ -86,142 +121,169 @@ export function evaluate(where, record) {
  *
  * @param {Object} where - The where-object predicate.
  * @param {Array<Object>} records - The records to filter.
- * @returns {Array<Object>} Records in source order for which the predicate is true.
+ * @returns {Array<Object>} Records in source order for which the predicate is true;
+ *   none for a where outside the language.
  */
 export function match(where, records) {
   if (!Array.isArray(records)) return []
   if (where == null) return records.slice()
-  return records.filter((r) => evaluate(where, r))
+  if (whereOutsideLanguage(where)) return []
+  return records.filter((r) => test(where, r))
 }
 
 // ─── Internals ────────────────────────────────────────────────────
 
-function evaluateClause(key, value, record) {
-  // Composition keys.
-  if (key === 'and') {
-    if (!Array.isArray(value)) return false
-    return value.every((sub) => evaluate(sub, record))
-  }
-  if (key === 'or') {
-    if (!Array.isArray(value)) return false
-    return value.some((sub) => evaluate(sub, record))
+function clauseProblem(key, value) {
+  if (key === 'and' || key === 'or') {
+    if (!Array.isArray(value) || value.length === 0) return `\`${key}\` takes a non-empty list of conditions`
+    for (const sub of value) {
+      const problem = sub && typeof sub === 'object' && !Array.isArray(sub)
+        ? whereOutsideLanguage(sub)
+        : `each item of \`${key}\` is an object of conditions`
+      if (problem) return problem
+    }
+    return null
   }
   if (key === 'not') {
-    return !evaluate(value, record)
+    if (!value || typeof value !== 'object' || Array.isArray(value)) return '`not` takes one object of conditions'
+    return whereOutsideLanguage(value)
   }
-
-  // Field clause: key is a (possibly dotted) field name; value is either
-  // a bare value (implicit eq) or an operator-object.
-  const fieldValue = getPath(record, key)
-
-  if (value === null) {
-    return fieldValue === null || fieldValue === undefined
+  // A field clause: a bare value, null, or an operator object — under a key that is a
+  // field or a path the language admits (`field-path.js`).
+  const pathProblem = fieldPathProblem(key)
+  if (pathProblem) return pathProblem
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) return null
+  const ops = Object.keys(value)
+  if (ops.length === 0) return `the condition on \`${key}\` is empty`
+  for (const op of ops) {
+    if (RETIRED_OPERATORS[op]) return RETIRED_OPERATORS[op]
+    if (!OPERATORS.has(op)) return `\`${op}\` (on \`${key}\`) is not an operator`
+    const arg = value[op]
+    if ((op === 'in' || op === 'not_in') && !Array.isArray(arg)) return `\`${op}\` takes a list of values`
+    if (op === 'exists' && typeof arg !== 'boolean') return '`exists` takes true or false'
+    if ((op === 'starts_with' || op === 'ends_with') && (typeof arg !== 'string' || arg === '')) {
+      return `\`${op}\` takes non-empty text`
+    }
+    if (op === 'contains' && arg === '') return '`contains` takes a value that is not empty text'
   }
+  return null
+}
 
-  if (typeof value === 'object' && !Array.isArray(value) && isOperatorObject(value)) {
-    return evaluateOperatorObject(value, fieldValue)
+function test(where, record) {
+  if (record == null || typeof record !== 'object') return false
+  for (const key of Object.keys(where)) {
+    if (!testClause(key, where[key], record)) return false
   }
-
-  // Bare value (string, number, boolean, array): implicit equality.
-  return matchEqual(fieldValue, value)
+  return true
 }
 
-function isOperatorObject(value) {
-  if (value == null || typeof value !== 'object' || Array.isArray(value)) return false
-  // An operator-object's keys are all in OPERATORS. If even one key isn't
-  // an operator, it's not an operator-object — it might be a nested
-  // sub-predicate or a structured equality target. The latter is rare;
-  // we treat any object whose keys are all known operators as an
-  // operator-object, otherwise fall back to deep-equality matching.
-  const keys = Object.keys(value)
-  if (keys.length === 0) return false
-  return keys.every((k) => OPERATORS.has(k))
-}
+function testClause(key, value, record) {
+  if (key === 'and') return value.every((sub) => test(sub, record))
+  if (key === 'or') return value.some((sub) => test(sub, record))
+  if (key === 'not') return !test(value, record)
 
-function evaluateOperatorObject(opObject, fieldValue) {
-  for (const op of Object.keys(opObject)) {
-    if (!evaluateOperator(op, opObject[op], fieldValue)) return false
+  const fieldValue = getPath(record, key)
+  if (value === null) return fieldValue === null || fieldValue === undefined
+  if (typeof value === 'object' && !Array.isArray(value)) {
+    for (const op of Object.keys(value)) {
+      if (!testOperator(op, value[op], fieldValue)) return false
+    }
+    return true
   }
-  return true
+  // Bare value: implicit equality.
+  return equals(fieldValue, value)
 }
 
-function evaluateOperator(op, opValue, fieldValue) {
+function testOperator(op, arg, fieldValue) {
   switch (op) {
     case 'eq':
-      return matchEqual(fieldValue, opValue)
+      return equals(fieldValue, arg)
     case 'ne':
-      return !matchEqual(fieldValue, opValue)
+      return !equals(fieldValue, arg)
     case 'gt':
-      return compareCanRun(fieldValue, opValue) && fieldValue > opValue
+      return someMember(fieldValue, (v) => comparable(v, arg) && v > arg)
     case 'gte':
-      return compareCanRun(fieldValue, opValue) && fieldValue >= opValue
+      return someMember(fieldValue, (v) => comparable(v, arg) && v >= arg)
     case 'lt':
-      return compareCanRun(fieldValue, opValue) && fieldValue < opValue
+      return someMember(fieldValue, (v) => comparable(v, arg) && v < arg)
     case 'lte':
-      return compareCanRun(fieldValue, opValue) && fieldValue <= opValue
+      return someMember(fieldValue, (v) => comparable(v, arg) && v <= arg)
     case 'in':
-      if (!Array.isArray(opValue)) return false
-      return opValue.some((v) => matchEqual(fieldValue, v))
-    case 'nin':
-      if (!Array.isArray(opValue)) return false
-      return !opValue.some((v) => matchEqual(fieldValue, v))
-    case 'like':
-      if (typeof fieldValue !== 'string' || typeof opValue !== 'string') return false
-      return globMatch(opValue, fieldValue)
+      return arg.some((a) => equals(fieldValue, a))
+    case 'not_in':
+      return !arg.some((a) => equals(fieldValue, a))
     case 'exists':
-      return Boolean(fieldValue) === Boolean(opValue)
+      return hasValue(fieldValue) === arg
+    case 'contains':
+      if (Array.isArray(fieldValue)) return fieldValue.some((v) => v === arg)
+      if (typeof fieldValue === 'string' && typeof arg === 'string') {
+        return fieldValue.toLowerCase().includes(arg.toLowerCase())
+      }
+      return false
+    case 'starts_with':
+      return someMember(fieldValue, (v) => typeof v === 'string' && v.toLowerCase().startsWith(arg.toLowerCase()))
+    case 'ends_with':
+      return someMember(fieldValue, (v) => typeof v === 'string' && v.toLowerCase().endsWith(arg.toLowerCase()))
     default:
-      // Unknown operator → fail closed.
       return false
   }
 }
 
-function matchEqual(a, b) {
-  if (a === b) return true
-  if (a == null || b == null) return false
-  // Array-on-either-side: if `a` is an array (record's field), match if
-  // any element equals b. This makes `tags: 'featured'` match a record
-  // with `tags: ['featured', 'sale']`.
-  if (Array.isArray(a) && !Array.isArray(b)) {
-    return a.some((v) => v === b)
-  }
-  if (typeof a === 'object' || typeof b === 'object') {
-    // No deep equality for objects in v1 — keep the surface narrow.
-    return false
-  }
-  return false
+/** Equality, typed; a list field equals a value when any member does. */
+function equals(fieldValue, arg) {
+  if (Array.isArray(fieldValue)) return fieldValue.some((v) => v === arg)
+  return fieldValue === arg
+}
+
+/** A condition on a value, or on any member when the field holds a list. */
+function someMember(fieldValue, predicate) {
+  if (Array.isArray(fieldValue)) return fieldValue.some(predicate)
+  return predicate(fieldValue)
 }
 
-function compareCanRun(a, b) {
+/** Numbers with numbers, text with text (ISO dates compare as text); nothing else. */
+function comparable(a, b) {
   if (a == null || b == null) return false
-  // Numbers and ISO-date strings (which compare correctly with </>=) are fine.
-  // Mixed types (string vs number) are a mismatch — return false rather
-  // than coerce.
-  return typeof a === typeof b
+  return typeof a === typeof b && typeof a !== 'object'
 }
 
+/** Not missing, null, "" or []. `0` and `false` are values. */
+function hasValue(v) {
+  if (v === undefined || v === null || v === '') return false
+  if (Array.isArray(v) && v.length === 0) return false
+  return true
+}
+
+/**
+ * The value at a (possibly dotted) path. A path that meets a list before it ends
+ * descends into each item, and returns the values it reached as one list.
+ */
 function getPath(record, path) {
   if (typeof path !== 'string') return undefined
   if (path.indexOf('.') === -1) return record[path]
-  let cursor = record
+  let current = [record]
+  let throughList = false
   for (const segment of path.split('.')) {
-    if (cursor == null || typeof cursor !== 'object') return undefined
-    cursor = cursor[segment]
+    const next = []
+    for (const node of current) {
+      if (node == null || typeof node !== 'object') continue
+      if (Array.isArray(node)) {
+        throughList = true
+        for (const item of node) {
+          if (item != null && typeof item === 'object' && !Array.isArray(item)) next.push(item[segment])
+        }
+      } else {
+        next.push(node[segment])
+      }
+    }
+    current = next
   }
-  return cursor
-}
-
-/**
- * Shell-glob match: `*` matches any run of characters, `?` matches one char.
- * Anchored — the pattern must match the whole string.
- */
-function globMatch(pattern, value) {
-  // Translate to a RegExp with anchors. Escape regex metacharacters
-  // except for our wildcards.
-  const re = '^' + pattern
-    .replace(/[.+^${}()|[\]\\]/g, '\\$&')
-    .replace(/\*/g, '.*')
-    .replace(/\?/g, '.')
-    + '$'
-  return new RegExp(re).test(value)
+  if (!throughList) return current[0]
+  const reached = []
+  for (const v of current) {
+    if (v === undefined) continue
+    if (Array.isArray(v)) reached.push(...v)
+    else reached.push(v)
+  }
+  return reached
 }