@uniweb/core 0.6.2 → 0.7.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/core",
-  "version": "0.6.2",
+  "version": "0.7.1",
   "description": "Core classes for the Uniweb platform - Uniweb, Website, Page, Block",
   "type": "module",
   "exports": {

package/src/entity-store.js

@@ -137,13 +137,61 @@ export default class EntityStore {
         if (!cfg.schema) continue
         if (configs.has(cfg.schema)) continue
         if (collectAll || requested.includes(cfg.schema)) {
-          configs.set(cfg.schema, this._localizeConfig(cfg, website))
+          const localized = this._localizeConfig(cfg, website)
+          const withDetail = this._applyDeferredDetail(localized, website)
+          configs.set(cfg.schema, withDetail)
         }
       }
     }
     return configs
   }
 
+  /**
+   * Auto-inject `detail:` on collection refs whose collection has
+   * `deferred:` declared. The detail pattern points at the per-record
+   * source so the existing dynamic-route singular flow fetches a record
+   * with all fields (including the deferred ones) instead of the
+   * matched-item-from-the-cascade-collection (without).
+   *
+   * Two patterns:
+   *
+   *   - Markdown-backed collections (the build emits per-record files
+   *     at `/data/<name>/<slug>.json`): the auto-injected pattern is
+   *     that path. `isLocalPath` resolution downstream gives the
+   *     fetch a `path:` shape.
+   *
+   *   - API-backed collections (the source is a remote URL; the build
+   *     emits no per-record files): the author declares a `detailUrl:`
+   *     on the collection — e.g., `/api/articles/{slug}` — and the
+   *     auto-injected pattern uses it. `isLocalPath` resolution
+   *     downstream gives the fetch a `url:` shape (because the
+   *     collection itself has `url:`, not `path:`).
+   *
+   * Conventions:
+   *   - Per-record sources are keyed by `item.slug`. The injected
+   *     pattern uses the `{slug}` placeholder; substitution works when
+   *     the dynamic route's paramName is 'slug' (the documented
+   *     convention). Routes with other param names need an explicit
+   *     author-written `detail:` value.
+   *   - Author-supplied `cfg.detail` always wins. This helper only fills
+   *     in the default for collections that have declared deferred fields.
+   *   - Per-record files are not currently localized; sites needing
+   *     localized deferred collections write their own `detail:` URL.
+   */
+  _applyDeferredDetail(cfg, website) {
+    if (cfg.detail !== undefined) return cfg
+    const schema = cfg.schema
+    if (!schema) return cfg
+    const collConfig = website?.config?.collections?.[schema]
+    if (!collConfig || typeof collConfig !== 'object') return cfg
+    const deferred = Array.isArray(collConfig.deferred) ? collConfig.deferred : null
+    if (!deferred || deferred.length === 0) return cfg
+    const pattern = typeof collConfig.detailUrl === 'string'
+      ? collConfig.detailUrl
+      : `/data/${schema}/{slug}.json`
+    return { ...cfg, detail: pattern }
+  }
+
   /**
    * Build a detail-URL fetch config from a collection config + dynamic context.
    *

package/src/index.js

@@ -21,6 +21,8 @@ export { default as ObservableState } from './observable-state.js'
 // Utilities
 export { default as singularize } from './singularize.js'
 export { substitutePlaceholders } from './substitute-placeholders.js'
+export { evaluate as evaluateWhere, match as matchWhere } from './where.js'
+export { resolveStyle as resolveRequestStyle, listStyleNames as listRequestStyleNames } from './request-styles/index.js'
 
 /**
  * The singleton Uniweb instance.

package/src/request-styles/flat-query.js

@@ -0,0 +1,146 @@
+/**
+ * flat-query — plain URL query-string style.
+ *
+ * GET-only. Operators become bare query params:
+ *
+ *   ?limit=10
+ *   ?sort=-date                  (single-key, "-" prefix for desc)
+ *   ?sort=-date,title            (multi-key, comma-separated)
+ *   ?dept=biology&tenured=true   (where, flat AND of equalities only)
+ *
+ * The `where:` operator is pushed **only** when the predicate is a flat
+ * AND of equalities on top-level fields. Nested operator objects
+ * (`{ age: { gte: 18 } }`), composition (`and` / `or` / `not`), and
+ * dotted field paths disqualify pushdown — the wire format can't
+ * express them. In those cases flat-query silently skips `where`, and
+ * the default fetcher applies it as a runtime fallback after the
+ * response arrives. This is the documented trade-off for the style's
+ * simplicity: flat-query fits simple REST APIs; richer queries either
+ * evaluate client-side or pick a different style.
+ *
+ * POST requests encode nothing — flat-query is a URL-params shape and
+ * has no meaningful POST representation.
+ *
+ * Use case: public REST APIs like `?dept=biology&limit=10&sort=-date`.
+ * For GraphQL or body-shaped backends, use json-body. For Strapi v4,
+ * use the strapi style.
+ */
+
+export const flatQuery = {
+  name: 'flat-query',
+  canPush: new Set(['where', 'limit', 'sort']),
+  defaultEnvelope: null,
+
+  encode(request, { method, pushCandidates, rename }) {
+    const pushed = new Set()
+    const queryParams = []
+
+    if (method !== 'GET') {
+      // POST has no flat-query representation; silent no-op.
+      return { queryParams, bodyMerge: null, pushed }
+    }
+
+    // where — only flat AND of equalities.
+    if (pushCandidates.has('where') && request.where !== undefined) {
+      const pairs = encodeFlatEqualities(request.where)
+      if (pairs !== null) {
+        for (const [k, v] of pairs) queryParams.push([applyRename(k, rename), v])
+        pushed.add('where')
+      }
+    }
+
+    if (pushCandidates.has('limit') && request.limit !== undefined) {
+      queryParams.push([wireName('limit', 'limit', rename), String(request.limit)])
+      pushed.add('limit')
+    }
+
+    if (pushCandidates.has('sort') && request.sort !== undefined) {
+      const encoded = encodeSort(request.sort)
+      if (encoded !== null) {
+        queryParams.push([wireName('sort', 'sort', rename), encoded])
+        pushed.add('sort')
+      }
+    }
+
+    return { queryParams, bodyMerge: null, pushed }
+  },
+}
+
+/**
+ * Encode a where-object as flat [field, value] pairs. Returns null when
+ * the predicate doesn't fit the flat-AND-equalities shape — caller
+ * falls back to runtime evaluation.
+ */
+function encodeFlatEqualities(where) {
+  if (!where || typeof where !== 'object' || Array.isArray(where)) return null
+  const out = []
+  for (const [key, raw] of Object.entries(where)) {
+    // Composition and operator shorthand disqualify the whole predicate.
+    if (key === 'and' || key === 'or' || key === 'not') return null
+    if (key.includes('.')) return null // dotted path — flat-query can't express nesting
+
+    // Bare primitive → implicit equality.
+    if (isPrimitive(raw)) {
+      out.push([key, stringifyPrimitive(raw)])
+      continue
+    }
+
+    // { eq: primitive } → equality. Anything else disqualifies.
+    if (raw && typeof raw === 'object' && !Array.isArray(raw)) {
+      const opKeys = Object.keys(raw)
+      if (opKeys.length === 1 && opKeys[0] === 'eq' && isPrimitive(raw.eq)) {
+        out.push([key, stringifyPrimitive(raw.eq)])
+        continue
+      }
+    }
+
+    return null
+  }
+  return out
+}
+
+/**
+ * Encode `sort: 'date desc'` → `-date`; `sort: 'date desc, title asc'` →
+ * `-date,title`. Returns null on malformed input (caller falls back).
+ */
+function encodeSort(sortExpr) {
+  if (typeof sortExpr !== 'string' || sortExpr.length === 0) return null
+  const parts = sortExpr.split(',').map((s) => s.trim()).filter(Boolean)
+  if (parts.length === 0) return null
+  const encoded = []
+  for (const part of parts) {
+    const [field, dirRaw] = part.split(/\s+/)
+    if (!field) return null
+    const desc = (dirRaw || 'asc').toLowerCase() === 'desc'
+    encoded.push(desc ? `-${field}` : field)
+  }
+  return encoded.join(',')
+}
+
+function isPrimitive(value) {
+  if (value === null) return true
+  const t = typeof value
+  return t === 'string' || t === 'number' || t === 'boolean'
+}
+
+function stringifyPrimitive(value) {
+  if (value === null) return ''
+  return String(value)
+}
+
+function wireName(operator, defaultWire, rename) {
+  if (rename && typeof rename[operator] === 'string' && rename[operator].length > 0) {
+    return rename[operator]
+  }
+  return defaultWire
+}
+
+// `rename` on flat-query's where pushdown doesn't apply to individual
+// field names — authors who need `dept → department` should write
+// their where-objects with the backend's field name directly. rename
+// remains available for `limit` and `sort` wire names.
+function applyRename(fieldName, _rename) {
+  return fieldName
+}
+
+export default flatQuery

package/src/request-styles/index.js

@@ -0,0 +1,61 @@
+/**
+ * Request-style registry.
+ *
+ * A "style" describes how the default fetcher reshapes a normalized
+ * request into wire format — which operators become URL params, which
+ * go into a body, what envelope the response carries. Sites pick a
+ * style on `site.yml fetcher.request.style`; when unset, the ambient
+ * default is `json-body`.
+ *
+ * Styles are shipped by the framework. There is no `registerStyle()`
+ * API for foundations or sites — custom wire shapes are expressed via
+ * foundation-level named transports. Styles are specifically for
+ * reshapings of the framework's own fetcher behavior.
+ *
+ * Internal to @uniweb/core. Consumed by @uniweb/runtime's default-fetcher.
+ */
+
+import { jsonBody } from './json-body.js'
+import { flatQuery } from './flat-query.js'
+import { strapi } from './strapi.js'
+
+const STYLES = new Map([
+  [jsonBody.name, jsonBody],
+  [flatQuery.name, flatQuery],
+  [strapi.name, strapi],
+])
+
+/**
+ * Resolve a style by name. Returns the requested style if registered,
+ * otherwise the ambient default (`json-body`). Unknown names trigger a
+ * one-time dev warning; production silently falls back.
+ *
+ * @param {string|undefined|null} name
+ * @param {{ dev?: boolean }} [options]
+ * @returns {Object} A style module.
+ */
+export function resolveStyle(name, { dev = false } = {}) {
+  if (!name) return jsonBody
+  const style = STYLES.get(name)
+  if (style) return style
+  if (dev && !warnedUnknownStyles.has(name)) {
+    warnedUnknownStyles.add(name)
+    console.warn(
+      `[default-fetcher] unknown request style "${name}"; falling back to "json-body". ` +
+        `Known styles: ${[...STYLES.keys()].join(', ')}.`,
+    )
+  }
+  return jsonBody
+}
+
+const warnedUnknownStyles = new Set()
+
+/**
+ * Sentinel list of names registered at the registry level. Used by tests
+ * and by dev-mode diagnostics; not part of the site-facing contract.
+ */
+export function listStyleNames() {
+  return [...STYLES.keys()]
+}
+
+export { jsonBody, flatQuery, strapi }

package/src/request-styles/json-body.js

@@ -0,0 +1,117 @@
+/**
+ * json-body — the framework's general-purpose request style.
+ *
+ * Ambient default when the site doesn't pick a style. Speaks the
+ * framework's own conventions:
+ *
+ *   GET   — operators travel as URL params prefixed with underscore:
+ *             ?_where=<JSON.stringify(predicate)>
+ *             ?_limit=N
+ *             ?_sort=field:dir       (comma-separated for multi-key)
+ *           The leading underscore avoids collision with backend-
+ *           specific query params the author may have included in `url:`.
+ *
+ *   POST  — operators merge as top-level keys into an object body,
+ *           alongside any author-supplied body. Content-Type defaults
+ *           to `application/json` unless the site set a different one.
+ *           String POST bodies (rare; typically GraphQL-only) don't
+ *           receive operator merge — the string is sent as-is.
+ *
+ * Operator name renames are applied from the `rename:` map passed in
+ * context. Shallow substitutions only — `rename: { limit: pageSize }`
+ * swaps the wire name `_limit` → `pageSize` on GET, or the body key
+ * `limit` → `pageSize` on POST. The operator identity (what `limit`
+ * means in the query) does not change.
+ *
+ * Internal module. Accessed by `default-fetcher.js` via the registry;
+ * never imported directly from outside `@uniweb/runtime`.
+ */
+
+export const jsonBody = {
+  name: 'json-body',
+
+  // Which operators this style knows how to push. The effective push set
+  // is the intersection of this and the site's `supports:` list.
+  canPush: new Set(['where', 'limit', 'sort']),
+
+  // Default response envelope. null = no wrapper (a plain JSON payload).
+  defaultEnvelope: null,
+
+  /**
+   * Encode a request against the json-body conventions.
+   *
+   * @param {Object} request - The normalized fetch request.
+   * @param {Object} ctx
+   * @param {'GET'|'POST'} ctx.method - The method the fetcher chose.
+   * @param {Set<string>} ctx.pushCandidates - Operators present on the
+   *   request AND listed in the site's `supports:`. Style may choose to
+   *   push all, some, or none of these based on what it knows how to
+   *   express on the wire.
+   * @param {Object|null} ctx.rename - Optional { operator → wireName } map.
+   * @returns {{
+   *   queryParams: Array<[string, string]>,
+   *   bodyMerge: Object|null,
+   *   pushed: Set<string>,
+   * }}
+   *   queryParams — pairs appended to the URL's query string.
+   *   bodyMerge   — object merged into the POST body, or null.
+   *   pushed      — the operators that actually rode on the wire.
+   *                 Feeds the fetcher's cache-key derivation and
+   *                 runtime-fallback skip.
+   */
+  encode(request, { method, pushCandidates, rename }) {
+    const pushed = new Set()
+    const queryParams = []
+    let bodyMerge = null
+
+    if (method === 'GET') {
+      if (pushCandidates.has('where') && request.where !== undefined) {
+        queryParams.push([
+          wireName('where', '_where', rename),
+          JSON.stringify(request.where),
+        ])
+        pushed.add('where')
+      }
+      if (pushCandidates.has('limit') && request.limit !== undefined) {
+        queryParams.push([
+          wireName('limit', '_limit', rename),
+          String(request.limit),
+        ])
+        pushed.add('limit')
+      }
+      if (pushCandidates.has('sort') && request.sort !== undefined) {
+        queryParams.push([
+          wireName('sort', '_sort', rename),
+          String(request.sort),
+        ])
+        pushed.add('sort')
+      }
+    } else if (method === 'POST') {
+      const merged = {}
+      if (pushCandidates.has('where') && request.where !== undefined) {
+        merged[wireName('where', 'where', rename)] = request.where
+        pushed.add('where')
+      }
+      if (pushCandidates.has('limit') && request.limit !== undefined) {
+        merged[wireName('limit', 'limit', rename)] = request.limit
+        pushed.add('limit')
+      }
+      if (pushCandidates.has('sort') && request.sort !== undefined) {
+        merged[wireName('sort', 'sort', rename)] = request.sort
+        pushed.add('sort')
+      }
+      if (Object.keys(merged).length > 0) bodyMerge = merged
+    }
+
+    return { queryParams, bodyMerge, pushed }
+  },
+}
+
+function wireName(operator, defaultWire, rename) {
+  if (rename && typeof rename[operator] === 'string' && rename[operator].length > 0) {
+    return rename[operator]
+  }
+  return defaultWire
+}
+
+export default jsonBody

package/src/request-styles/strapi.js

@@ -0,0 +1,232 @@
+/**
+ * strapi — Strapi v4 REST API query style.
+ *
+ * GET-only. Encodes a full where-object into Strapi's bracket-notation
+ * filters:
+ *
+ *   where: { dept: 'biology' }
+ *     → filters[dept][$eq]=biology
+ *
+ *   where: { age: { gte: 18 } }
+ *     → filters[age][$gte]=18
+ *
+ *   where: { 'tenure.start': { gte: 2015 } }
+ *     → filters[tenure][start][$gte]=2015
+ *
+ *   where: { or: [{ a: 1 }, { b: 2 }] }
+ *     → filters[$or][0][a][$eq]=1 & filters[$or][1][b][$eq]=2
+ *
+ *   where: { not: { dept: 'emeritus' } }
+ *     → filters[$not][dept][$eq]=emeritus
+ *
+ *   limit: 10
+ *     → pagination[limit]=10
+ *
+ *   sort: 'date desc'
+ *     → sort=date:desc
+ *
+ *   sort: 'date desc, title asc'
+ *     → sort[0]=date:desc & sort[1]=title:asc
+ *
+ * Response envelope defaults to `{ collection: 'data', item: 'data' }` —
+ * Strapi v4 wraps every response in `{ data, meta }`. Sites can override
+ * via `envelope:` at the site or per-fetch level.
+ *
+ * Operators mapped (where-object → Strapi `$op`):
+ *   eq, ne, gt, gte, lt, lte, in, nin → notIn, like → containsi,
+ *   exists → notNull, and → $and, or → $or, not → $not.
+ *
+ * For operators the where-object supports but Strapi doesn't have a
+ * clean equivalent for, the style leaves them untouched (the default
+ * fetcher applies them as a runtime fallback).
+ */
+
+export const strapi = {
+  name: 'strapi',
+  canPush: new Set(['where', 'limit', 'sort']),
+  defaultEnvelope: { collection: 'data', item: 'data' },
+
+  encode(request, { method, pushCandidates, rename }) {
+    const pushed = new Set()
+    const queryParams = []
+
+    if (method !== 'GET') {
+      // Strapi v4 REST is GET-only for reads.
+      return { queryParams, bodyMerge: null, pushed }
+    }
+
+    if (pushCandidates.has('where') && request.where !== undefined) {
+      const filterKey = wireName('where', 'filters', rename)
+      const pairs = encodeStrapiFilters(request.where, filterKey)
+      if (pairs !== null) {
+        for (const pair of pairs) queryParams.push(pair)
+        pushed.add('where')
+      }
+    }
+
+    if (pushCandidates.has('limit') && request.limit !== undefined) {
+      const limitKey = wireName('limit', 'pagination[limit]', rename)
+      queryParams.push([limitKey, String(request.limit)])
+      pushed.add('limit')
+    }
+
+    if (pushCandidates.has('sort') && request.sort !== undefined) {
+      const sortPairs = encodeStrapiSort(request.sort, wireName('sort', 'sort', rename))
+      if (sortPairs !== null) {
+        for (const pair of sortPairs) queryParams.push(pair)
+        pushed.add('sort')
+      }
+    }
+
+    return { queryParams, bodyMerge: null, pushed }
+  },
+}
+
+// ─── where encoding ────────────────────────────────────────────────────────
+
+// Values are the Strapi operator *with* bracket delimiters, so they
+// concatenate cleanly into a bracketed path like `filters[field][$eq]`.
+const OPERATOR_MAP = {
+  eq: '[$eq]',
+  ne: '[$ne]',
+  gt: '[$gt]',
+  gte: '[$gte]',
+  lt: '[$lt]',
+  lte: '[$lte]',
+  in: '[$in]',
+  nin: '[$notIn]',
+  like: '[$containsi]',    // case-insensitive substring — closest Strapi analog
+  exists: '[$notNull]',    // overridden below for exists:false → [$null]
+}
+
+/**
+ * Walk a where-object and emit [paramName, paramValue] pairs encoding
+ * Strapi's bracket syntax. Returns null if any branch is unencodable
+ * (caller falls back to runtime evaluation for the whole predicate).
+ */
+function encodeStrapiFilters(where, rootKey) {
+  const out = []
+  try {
+    walkPredicate(where, [rootKey], out)
+  } catch (err) {
+    if (err && err.unencodable) return null
+    throw err
+  }
+  return out.length > 0 ? out : null
+}
+
+function walkPredicate(node, path, out) {
+  if (!node || typeof node !== 'object' || Array.isArray(node)) {
+    throwUnencodable()
+  }
+
+  // Top-level each key is either composition ($and/$or/$not) or a field.
+  for (const [key, value] of Object.entries(node)) {
+    if (key === 'and' || key === 'or') {
+      if (!Array.isArray(value)) throwUnencodable()
+      value.forEach((sub, i) => {
+        walkPredicate(sub, [...path, `[$${key}]`, `[${i}]`], out)
+      })
+    } else if (key === 'not') {
+      walkPredicate(value, [...path, '[$not]'], out)
+    } else {
+      emitFieldPredicate(key, value, path, out)
+    }
+  }
+}
+
+function emitFieldPredicate(field, value, path, out) {
+  // Dotted paths become nested bracket segments: `tenure.start` →
+  // `[tenure][start]`.
+  const fieldSegments = field.split('.').map((seg) => `[${seg}]`)
+  const fieldPath = [...path, ...fieldSegments]
+
+  // Bare primitive → implicit eq.
+  if (isPrimitive(value)) {
+    out.push([joinPath(fieldPath) + '[$eq]', stringifyPrimitive(value)])
+    return
+  }
+
+  if (value && typeof value === 'object' && !Array.isArray(value)) {
+    for (const [opName, opValue] of Object.entries(value)) {
+      const strapiOp = OPERATOR_MAP[opName]
+      if (!strapiOp) throwUnencodable()
+
+      if (opName === 'in' || opName === 'nin') {
+        if (!Array.isArray(opValue)) throwUnencodable()
+        opValue.forEach((item, i) => {
+          if (!isPrimitive(item)) throwUnencodable()
+          out.push([joinPath(fieldPath) + strapiOp + `[${i}]`, stringifyPrimitive(item)])
+        })
+        continue
+      }
+
+      if (opName === 'exists') {
+        // { exists: true }  → field IS NOT NULL  → [field][$notNull]=true
+        // { exists: false } → field IS NULL      → [field][$null]=true
+        const wantsPresent = !!opValue
+        out.push([joinPath(fieldPath) + (wantsPresent ? '[$notNull]' : '[$null]'), 'true'])
+        continue
+      }
+
+      if (!isPrimitive(opValue)) throwUnencodable()
+      out.push([joinPath(fieldPath) + strapiOp, stringifyPrimitive(opValue)])
+    }
+    return
+  }
+
+  throwUnencodable()
+}
+
+function joinPath(segments) {
+  return segments.join('')
+}
+
+function throwUnencodable() {
+  const err = new Error('unencodable predicate')
+  err.unencodable = true
+  throw err
+}
+
+// ─── sort encoding ─────────────────────────────────────────────────────────
+
+function encodeStrapiSort(sortExpr, baseKey) {
+  if (typeof sortExpr !== 'string' || sortExpr.length === 0) return null
+  const parts = sortExpr.split(',').map((s) => s.trim()).filter(Boolean)
+  if (parts.length === 0) return null
+
+  const encoded = []
+  for (const part of parts) {
+    const [field, dirRaw] = part.split(/\s+/)
+    if (!field) return null
+    const dir = (dirRaw || 'asc').toLowerCase() === 'desc' ? 'desc' : 'asc'
+    encoded.push(`${field}:${dir}`)
+  }
+
+  if (encoded.length === 1) {
+    return [[baseKey, encoded[0]]]
+  }
+  return encoded.map((v, i) => [`${baseKey}[${i}]`, v])
+}
+
+// ─── helpers ───────────────────────────────────────────────────────────────
+
+function isPrimitive(value) {
+  if (value === null) return true
+  const t = typeof value
+  return t === 'string' || t === 'number' || t === 'boolean'
+}
+
+function stringifyPrimitive(value) {
+  if (value === null) return ''
+  return String(value)
+}
+
+function wireName(operator, defaultWire, rename) {
+  if (rename && typeof rename[operator] === 'string' && rename[operator].length > 0) {
+    return rename[operator]
+  }
+  return defaultWire
+}
+
+export default strapi

package/src/where.js

@@ -0,0 +1,223 @@
+/**
+ * Where-object evaluator.
+ *
+ * A where-object is a structured JSON predicate. The format is small,
+ * additive, and YAML/JSON-native — there is no DSL or parser. The same
+ * predicate travels from author YAML, through transports, to backends
+ * (which translate to their native query language) or to this evaluator
+ * (which walks the object against a record).
+ *
+ * Architecture: see kb/framework/architecture/data-fetching.md.
+ *
+ * Shape:
+ *
+ *   {
+ *     // Top-level keys are field names; values are the values to match.
+ *     // Implicit AND across keys.
+ *     department: 'biology',
+ *     tenured: true,
+ *
+ *     // For non-equality, the value is an operator object.
+ *     start_year: { gte: 2010 },
+ *     rank: { in: ['associate', 'full'] },
+ *     title: { like: 'Origin*' },
+ *
+ *     // Explicit composition keys at any nesting level.
+ *     and: [{ tenured: true }, { rank: 'full' }],
+ *     or:  [{ rank: 'full' }, { years_in_role: { gte: 10 } }],
+ *     not: { department: 'emeritus' },
+ *   }
+ *
+ * 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).
+ *
+ * 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.
+ *
+ * Dotted paths descend into nested objects: `tenure.start: { gte: 2015 }`.
+ *
+ * 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.
+ */
+
+const COMPOSITION_KEYS = new Set(['and', 'or', 'not'])
+const OPERATORS = new Set([
+  'eq', 'ne', 'gt', 'gte', 'lt', 'lte', 'in', 'nin', 'like', 'exists',
+])
+
+/**
+ * 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.
+ */
+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
+}
+
+/**
+ * Filter an array of records by a where-object predicate.
+ *
+ * @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.
+ */
+export function match(where, records) {
+  if (!Array.isArray(records)) return []
+  if (where == null) return records.slice()
+  return records.filter((r) => evaluate(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))
+  }
+  if (key === 'not') {
+    return !evaluate(value, record)
+  }
+
+  // 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
+  }
+
+  if (typeof value === 'object' && !Array.isArray(value) && isOperatorObject(value)) {
+    return evaluateOperatorObject(value, fieldValue)
+  }
+
+  // Bare value (string, number, boolean, array): implicit equality.
+  return matchEqual(fieldValue, value)
+}
+
+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 evaluateOperatorObject(opObject, fieldValue) {
+  for (const op of Object.keys(opObject)) {
+    if (!evaluateOperator(op, opObject[op], fieldValue)) return false
+  }
+  return true
+}
+
+function evaluateOperator(op, opValue, fieldValue) {
+  switch (op) {
+    case 'eq':
+      return matchEqual(fieldValue, opValue)
+    case 'ne':
+      return !matchEqual(fieldValue, opValue)
+    case 'gt':
+      return compareCanRun(fieldValue, opValue) && fieldValue > opValue
+    case 'gte':
+      return compareCanRun(fieldValue, opValue) && fieldValue >= opValue
+    case 'lt':
+      return compareCanRun(fieldValue, opValue) && fieldValue < opValue
+    case 'lte':
+      return compareCanRun(fieldValue, opValue) && fieldValue <= opValue
+    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)
+    case 'exists':
+      return Boolean(fieldValue) === Boolean(opValue)
+    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
+}
+
+function compareCanRun(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
+}
+
+function getPath(record, path) {
+  if (typeof path !== 'string') return undefined
+  if (path.indexOf('.') === -1) return record[path]
+  let cursor = record
+  for (const segment of path.split('.')) {
+    if (cursor == null || typeof cursor !== 'object') return undefined
+    cursor = cursor[segment]
+  }
+  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)
+}