envio 3.12.0 → 3.13.0-alpha.0

package/src/db/EntityFilter.res

@@ -1,111 +1,61 @@
-module FieldValue = {
-  @unboxed
-  type rec tNonOptional =
-    | String(string)
-    | BigInt(bigint)
-    | Int(int)
-    | BigDecimal(BigDecimal.t)
-    | Bool(bool)
-    | Array(array<tNonOptional>)
-
-  let rec toString = tNonOptional =>
-    switch tNonOptional {
-    | String(v) => v
-    | BigInt(v) => v->BigInt.toString
-    | Int(v) => v->Int.toString
-    | BigDecimal(v) => v->BigDecimal.toString
-    | Bool(v) => v ? "true" : "false"
-    | Array(v) => `[${v->Array.map(toString)->Array.join(",")}]`
-    }
-
-  //This needs to be a castable type from any type that we
-  //support in entities so that we can create evaluations
-  //and serialize the types without parsing/wrapping them
-  type t = option<tNonOptional>
-
-  // A Uint8Array is an object like a BigDecimal, so the unboxed variant can't
-  // tell them apart on its own.
-  let asBytes = (value: t) => value->(Utils.magic: t => unknown)->Utils.Bytes.asUint8Array
-
-  let toString = (value: t) =>
-    switch (value, value->asBytes) {
-    | (_, Some(bytes)) => bytes->Utils.Bytes.toHex
-    | (Some(v), None) => v->toString
-    | (None, None) => "undefined"
-    }
-
-  external castFrom: 'a => t = "%identity"
-
-  let compareWith = (a, b, ~bigDecimal, ~bytes, ~fallback) =>
-    switch (a, b, a->asBytes, b->asBytes) {
-    | (_, _, Some(bytesA), Some(bytesB)) => bytes(Utils.Bytes.compare(bytesA, bytesB))
-    //For big decimal use custom equals operator otherwise let Caml_obj.equal do its magic
-    | (Some(BigDecimal(bdA)), Some(BigDecimal(bdB)), _, _) => bigDecimal(bdA, bdB)
-    | (a, b, _, _) => fallback(a, b)
-    }
-
-  let eq = (a, b) =>
-    compareWith(
-      a,
-      b,
-      ~bigDecimal=BigDecimal.equals,
-      ~bytes=order => order === 0.,
-      ~fallback=(a, b) => a == b,
-    )
-
-  let gt = (a, b) =>
-    compareWith(
-      a,
-      b,
-      ~bigDecimal=BigDecimal.gt,
-      ~bytes=order => order > 0.,
-      ~fallback=(a, b) => a > b,
-    )
-
-  let lt = (a, b) =>
-    compareWith(
-      a,
-      b,
-      ~bigDecimal=BigDecimal.lt,
-      ~bytes=order => order < 0.,
-      ~fallback=(a, b) => a < b,
+@scope("JSON") @val external jsonStringify: unknown => string = "stringify"
+
+let nullish: unknown => bool = %raw(`v => v === undefined || v === null`)
+
+let asArray = (v: unknown) => v->(Utils.magic: unknown => array<unknown>)
+
+// Renders one already-projected value into a cache key: a type tag, then the
+// length, then the value. The tag keeps "5" apart from 5, and the length means
+// a delimiter inside a value can't imitate the delimiter, so no escaping pass
+// is needed. Both together make the encoding injective, which is the only
+// property a key needs.
+//
+// Every branch but the last is reached because the column's projection already
+// collapsed its values to a primitive — a Date to its epoch millis, a Bytea to
+// hex — so nothing here has to guess a value's type at runtime. JSON is the
+// last resort, for a column whose values are objects in the first place.
+let encodeValueKey: unknown => string = %raw(`v => {
+  if (v === null) return "z"
+  switch (typeof v) {
+    case "string": return "s" + v.length + ":" + v
+    case "number": { const s = "" + v; return "n" + s.length + ":" + s }
+    case "bigint": { const s = "" + v; return "g" + s.length + ":" + s }
+    case "boolean": return v ? "t" : "f"
+    case "undefined": return "u"
+    default: { const s = JSON.stringify(v); return "o" + s.length + ":" + s }
+  }
+}`)
+
+// JSON is the one step above that can fail, and only on an object: one holding
+// a bigint, or one that refers to itself. An array is walked rather than
+// stringified, because its key is built from its elements' keys.
+let isKeyable: unknown => bool = %raw(`function isKeyable(v) {
+  if (typeof v !== "object" || v === null) return true
+  if (Array.isArray(v)) return v.every(isKeyable)
+  try { JSON.stringify(v); return true } catch { return false }
+}`)
+
+// The filter as the handler wrote it: field -> operator -> value. Private, so
+// a value of this type is one parseOrThrow accepted or the indexer built
+// itself, and nothing downstream has to check the filter again.
+type t = private dict<dict<unknown>>
+
+external unsafeFromDict: dict<dict<unknown>> => t = "%identity"
+
+let entries = (filter: t) => (filter :> dict<dict<unknown>>)
+
+let valuesCount = (filter: t) => {
+  let count = ref(0)
+  filter
+  ->entries
+  ->Utils.Dict.forEachWithKey((operators, _) =>
+    operators->Utils.Dict.forEachWithKey((fieldValue, operator) =>
+      count := count.contents + (operator === "_in" ? fieldValue->asArray->Array.length : 1)
     )
+  )
+  count.contents
 }
 
-// The And case requires at least one nested filter (storage throws otherwise),
-// while In with an empty array matches nothing.
-@tag("operator")
-type rec t =
-  | @as("=") Eq({fieldName: string, fieldValue: unknown})
-  | @as(">") Gt({fieldName: string, fieldValue: unknown})
-  | @as("<") Lt({fieldName: string, fieldValue: unknown})
-  | @as("in") In({fieldName: string, fieldValue: array<unknown>})
-  | @as("and") And({filters: array<t>})
-
-// Used as a stable in-memory cache key, so it must be unambiguous
-// for any two different filters.
-let rec toString = (filter: t) =>
-  switch filter {
-  | Eq({fieldName, fieldValue}) =>
-    `${fieldName}:Eq:${fieldValue->FieldValue.castFrom->FieldValue.toString}`
-  | Gt({fieldName, fieldValue}) =>
-    `${fieldName}:Gt:${fieldValue->FieldValue.castFrom->FieldValue.toString}`
-  | Lt({fieldName, fieldValue}) =>
-    `${fieldName}:Lt:${fieldValue->FieldValue.castFrom->FieldValue.toString}`
-  | In({fieldName, fieldValue}) =>
-    `${fieldName}:In:[${fieldValue
-      ->Array.map(v => v->FieldValue.castFrom->FieldValue.toString)
-      ->Array.join(",")}]`
-  | And({filters}) => `And(${filters->Array.map(toString)->Array.join(",")})`
-  }
-
-let rec valuesCount = (filter: t) =>
-  switch filter {
-  | Eq(_) | Gt(_) | Lt(_) => 1
-  | In({fieldValue}) => fieldValue->Array.length
-  | And({filters}) => filters->Array.reduce(0, (acc, filter) => acc + filter->valuesCount)
-  }
-
 let codegenHelpMessage = `Rerun 'pnpm dev' to update generated code after schema.graphql changes.`
 
 let getUndefinedOrNullName = (value: 'a) =>
@@ -124,15 +74,42 @@ let throwUnsupportedGetWhereValue = (~valueName, ~entityName, ~filterDisplay, ~h
     `Invalid ${valueName} value passed to context.${entityName}.getWhere(${filterDisplay}). Filtering by null or undefined values is not supported in getWhere.${hint}`,
   )
 
-// Each returned filter should be loaded separately and the results flattened:
-// _in maps to one Eq per value so loads memoize on the per-value level,
-// and _gte/_lte are composed from Eq + Gt/Lt. Each field+operator pair
-// expands into a group of such alternatives, and multiple pairs combine
-// as a cross product of And filters — the groups stay disjoint, so the
-// flattened results contain no duplicates.
-let parseGetWhereOrThrow = (filter: dict<dict<unknown>>, ~entityName, ~table: Table.table): array<
-  t,
-> => {
+let isDate: unknown => bool = %raw(`v => v instanceof Date`)
+
+// Columns whose comparison needs a specific object shape. The rest compare
+// natively, so whatever they're handed is already safe.
+let expectedValueType = (field: Table.field) =>
+  switch field.fieldType {
+  | Date => Some(field.isArray ? "an array of Date" : "a Date")
+  | Bytea => Some(field.isArray ? "an array of Uint8Array" : "a Uint8Array")
+  | _ => None
+  }
+
+// Whether this column's values can reach JSON when a key is built. Date, Bytea
+// and BigDecimal collapse to a primitive first, and an array's elements follow
+// the same rule as the scalar they hold.
+let keyUsesSerializer = (field: Table.field) =>
+  switch field.fieldType {
+  | Date | Bytea | BigDecimal(_) => false
+  | _ => true
+  }
+
+let matchesFieldType = (value: unknown, ~field: Table.field) => {
+  let matchesScalar = value =>
+    switch field.fieldType {
+    | Date => value->isDate
+    | Bytea => value->Utils.Bytes.asUint8Array->Option.isSome
+    | _ => true
+    }
+  field.isArray
+    ? value->Array.isArray && value->asArray->Array.every(matchesScalar)
+    : value->matchesScalar
+}
+
+// The one way in for a handler's filter. A bad field, operator or value is
+// reported against the call the handler made rather than surfacing later as a
+// comparator or SQL failure.
+let parseOrThrow = (filter: dict<dict<unknown>>, ~entityName, ~table: Table.table): t => {
   let filterKeys = filter->Dict.keysToArray
 
   if filterKeys->Array.length === 0 {
@@ -141,7 +118,7 @@ let parseGetWhereOrThrow = (filter: dict<dict<unknown>>, ~entityName, ~table: Ta
     )
   }
 
-  let filterGroups = filterKeys->Array.flatMap(apiFieldName => {
+  filterKeys->Array.forEach(apiFieldName => {
     let operatorObj = filter->Dict.getUnsafe(apiFieldName)
 
     switch operatorObj->getUndefinedOrNullName {
@@ -186,7 +163,7 @@ let parseGetWhereOrThrow = (filter: dict<dict<unknown>>, ~entityName, ~table: Ta
       }
     )
 
-    switch table->Table.getFieldByApiName(apiFieldName) {
+    let field = switch table->Table.getFieldByApiName(apiFieldName) {
     | None =>
       JsError.throwWithMessage(
         `Invalid field "${apiFieldName}" in context.${entityName}.getWhere(). The field doesn't exist. ${codegenHelpMessage}`,
@@ -195,10 +172,16 @@ let parseGetWhereOrThrow = (filter: dict<dict<unknown>>, ~entityName, ~table: Ta
       JsError.throwWithMessage(
         `The field "${apiFieldName}" on entity "${entityName}" is a derived field and cannot be used in getWhere(). Use the source entity's indexed field instead.`,
       )
-    | Some(Field(_)) => ()
+    | Some(Field(field)) => field
     }
 
-    operatorKeys->Array.map(operatorKey => {
+    // Constant per field, and None for every column that accepts any runtime
+    // shape — so the per-value check below is a single comparison on the path
+    // that matters, an _in of many values that are all about to pass.
+    let expectedType = field->expectedValueType
+    let checkKeyable = field->keyUsesSerializer
+
+    operatorKeys->Array.forEach(operatorKey => {
       let fieldValue = operatorObj->Dict.getUnsafe(operatorKey)
       switch fieldValue->getUndefinedOrNullName {
       | Some(valueName) =>
@@ -209,6 +192,14 @@ let parseGetWhereOrThrow = (filter: dict<dict<unknown>>, ~entityName, ~table: Ta
         )
       | None => ()
       }
+      let throwUnexpectedType = (~typeName, ~hint) =>
+        JsError.throwWithMessage(
+          `Invalid value passed to context.${entityName}.getWhere({ ${apiFieldName}: { ${operatorKey}: ... } }). The field "${apiFieldName}" expects ${typeName}.${hint}`,
+        )
+      let throwUnkeyable = (~hint) =>
+        JsError.throwWithMessage(
+          `Invalid value passed to context.${entityName}.getWhere({ ${apiFieldName}: { ${operatorKey}: ... } }). The value can't be serialized, so it can't be used as a filter. An object holding a bigint, or a circular reference, is not supported.${hint}`,
+        )
 
       switch operatorKey {
       | "_in" => {
@@ -217,9 +208,9 @@ let parseGetWhereOrThrow = (filter: dict<dict<unknown>>, ~entityName, ~table: Ta
               `Invalid value passed to context.${entityName}.getWhere({ ${apiFieldName}: { _in: ... } }). The _in operator expects an array of values.`,
             )
           }
-          let fieldValues = fieldValue->(Utils.magic: unknown => array<unknown>)
+          let fieldValues = fieldValue->asArray
 
-          fieldValues->Array.mapWithIndex(
+          fieldValues->Array.forEachWithIndex(
             (fieldValue, index) => {
               switch fieldValue->getUndefinedOrNullName {
               | Some(valueName) =>
@@ -231,195 +222,416 @@ let parseGetWhereOrThrow = (filter: dict<dict<unknown>>, ~entityName, ~table: Ta
                 )
               | None => ()
               }
-              Eq({fieldName: apiFieldName, fieldValue})
+              switch expectedType {
+              | Some(typeName) if !(fieldValue->matchesFieldType(~field)) =>
+                throwUnexpectedType(
+                  ~typeName,
+                  ~hint=` The value is at index ${index->Int.toString} of the _in array.`,
+                )
+              | _ => ()
+              }
+              if checkKeyable && !(fieldValue->isKeyable) {
+                throwUnkeyable(
+                  ~hint=` The value is at index ${index->Int.toString} of the _in array.`,
+                )
+              }
             },
           )
         }
-      | "_gte" => [
-          Eq({fieldName: apiFieldName, fieldValue}),
-          Gt({fieldName: apiFieldName, fieldValue}),
-        ]
-      | "_lte" => [
-          Eq({fieldName: apiFieldName, fieldValue}),
-          Lt({fieldName: apiFieldName, fieldValue}),
-        ]
-      | "_eq" => [Eq({fieldName: apiFieldName, fieldValue})]
-      | "_gt" => [Gt({fieldName: apiFieldName, fieldValue})]
-      | "_lt" => [Lt({fieldName: apiFieldName, fieldValue})]
-      | _ => throwInvalidOperator(operatorKey)
+      | _ =>
+        switch expectedType {
+        | Some(typeName) if !(fieldValue->matchesFieldType(~field)) =>
+          throwUnexpectedType(~typeName, ~hint="")
+        | _ => ()
+        }
+        if checkKeyable && !(fieldValue->isKeyable) {
+          throwUnkeyable(~hint="")
+        }
       }
     })
   })
 
-  filterGroups
-  ->Array.reduce([[]], (combinations, group) =>
-    combinations->Array.flatMap(combination =>
-      group->Array.map(filter => combination->Array.concat([filter]))
-    )
-  )
-  ->Array.map(filters =>
-    switch filters {
-    | [filter] => filter
-    | _ => And({filters: filters})
-    }
-  )
+  filter->unsafeFromDict
 }
 
-let rec printOperationFilter = (filter: t, ~paramsCount: ref<int>) =>
-  switch filter {
-  | Eq({fieldName}) => {
-      paramsCount := paramsCount.contents + 1
-      `${fieldName}: $${paramsCount.contents->Int.toString}`
-    }
-  | Gt({fieldName}) => {
-      paramsCount := paramsCount.contents + 1
-      `${fieldName}: {_gt: $${paramsCount.contents->Int.toString}}`
-    }
-  | Lt({fieldName}) => {
-      paramsCount := paramsCount.contents + 1
-      `${fieldName}: {_lt: $${paramsCount.contents->Int.toString}}`
-    }
-  | In({fieldName}) => {
-      paramsCount := paramsCount.contents + 1
-      `${fieldName}: {_in: $${paramsCount.contents->Int.toString}}`
-    }
-  | And({filters}) => {
-      let acc = ref("")
-      for idx in 0 to filters->Array.length - 1 {
-        let part = filters->Array.getUnsafe(idx)->printOperationFilter(~paramsCount)
-        acc := (acc.contents === "" ? part : `${acc.contents}, ${part}`)
-      }
-      acc.contents
-    }
+let byIds = (ids: array<string>): t =>
+  Dict.fromArray([
+    (Table.idFieldName, dict{"_in": ids->(Utils.magic: array<string> => unknown)}),
+  ])->unsafeFromDict
+
+// Narrows a filter to the scope's chain. Cross-chain entities have no chain-id
+// column, so their filter is left untouched.
+let scoped = (filter: t, ~table: Table.table, ~scope: Internal.chainScope): t =>
+  switch (scope, table->Table.getChainIdField) {
+  | (Chain(chainId), Some(field)) =>
+    // Copied, because the filter the handler passed in must not gain a column
+    // it never asked for.
+    let scoped = filter->entries->Utils.Dict.shallowCopy
+    scoped->Dict.set(field.fieldName, dict{"_eq": chainId->(Utils.magic: ChainId.t => unknown)})
+    scoped->unsafeFromDict
+  | _ => filter
   }
 
-// Filters that may be batched into a single storage query must produce
-// the same key, so concrete values are replaced with $N placeholders.
-// The flat cases duplicate printOperationFilter to keep this hot path
-// allocation-free.
-let toOperationKey = (filter: t, ~entityName) =>
-  switch filter {
-  | Eq({fieldName}) => `${entityName}.getWhere({${fieldName}: $1})`
-  | Gt({fieldName}) => `${entityName}.getWhere({${fieldName}: {_gt: $1}})`
-  | Lt({fieldName}) => `${entityName}.getWhere({${fieldName}: {_lt: $1}})`
-  | In({fieldName}) => `${entityName}.getWhere({${fieldName}: {_in: $1}})`
-  | And(_) => `${entityName}.getWhere({${filter->printOperationFilter(~paramsCount=ref(0))}})`
-  }
+// Values bound to the query's $N placeholders, in the order it binds them.
+let getParams = (filter: t) => {
+  let params = []
+  filter
+  ->entries
+  ->Utils.Dict.forEachWithKey((operators, _) =>
+    operators->Utils.Dict.forEachWithKey((fieldValue, _) => params->Array.push(fieldValue)->ignore)
+  )
+  params
+}
 
-// Values bound to the operation key's $N placeholders, in placeholder
-// order. A top-level In is reported flat, since a merged query holds one
-// value per batched call there, while an In nested in And binds its whole
-// array to a single placeholder, mirroring the one paramsCount increment
-// per flat filter in printOperationFilter.
-let getParams = (filter: t) =>
-  switch filter {
-  | Eq({fieldValue}) => [fieldValue]
-  | Gt({fieldValue}) => [fieldValue]
-  | Lt({fieldValue}) => [fieldValue]
-  | In({fieldValue}) => fieldValue
-  | And(_) => {
-      let acc = []
-      let rec collect = (filter: t) =>
-        switch filter {
-        | Eq({fieldValue}) => acc->Array.push(fieldValue)->ignore
-        | Gt({fieldValue}) => acc->Array.push(fieldValue)->ignore
-        | Lt({fieldValue}) => acc->Array.push(fieldValue)->ignore
-        | In({fieldValue}) =>
-          acc->Array.push(fieldValue->(Utils.magic: array<unknown> => unknown))->ignore
-        | And({filters}) => filters->Array.forEach(collect)
-        }
-      collect(filter)
-      acc
+// The one shape a value can key an index or a merged query by: a single field
+// under a single operator.
+let asSingleOperator = (filter: t) =>
+  switch filter->entries->Dict.keysToArray {
+  | [fieldName] =>
+    let operators = filter->entries->Dict.getUnsafe(fieldName)
+    switch operators->Dict.keysToArray {
+    | [operator] => Some((fieldName, operator, operators->Dict.getUnsafe(operator)))
+    | _ => None
     }
+  | _ => None
   }
 
 // Collapses filters sharing an operation key into fewer storage queries:
-// Eq and In batches merge into a single In on the field. Gt/Lt/And have
-// no lossless single-query form without an Or operator, so they stay as is.
+// _eq and _in batches merge into a single _in on the field. The rest have no
+// lossless single-query form without an Or operator, so they stay as is.
 // Expects a homogeneous batch — filters with the same operation key.
 // A mismatched filter throws: dropping it would leave its already
 // registered index without the matching db rows, silently losing data.
 let throwUnmergeable = (filter: t) =>
   JsError.throwWithMessage(
-    `Unexpected filter ${filter->toString} in a merged batch. Filters batched into a single query must use the same operator and field.`,
+    `Unexpected ${switch filter->asSingleOperator {
+      | Some((_, operator, _)) => operator
+      | None => "composite"
+      }} filter in a merged batch. Filters batched into a single query must use the same operator and field.`,
   )
 
 let merge = (filters: array<t>) =>
   switch filters {
   | [] | [_] => filters
   | _ =>
-    switch filters->Array.getUnsafe(0) {
-    | Eq({fieldName}) => [
-        In({
-          fieldName,
-          fieldValue: filters->Array.map(filter =>
-            switch filter {
-            | Eq({fieldValue}) => fieldValue
-            | _ => throwUnmergeable(filter)
-            }
-          ),
-        }),
-      ]
-    | In({fieldName}) => [
-        In({
-          fieldName,
-          fieldValue: filters
-          ->Array.map(filter =>
-            switch filter {
-            | In({fieldValue}) => fieldValue
-            | _ => throwUnmergeable(filter)
-            }
-          )
-          ->Array.flat,
-        }),
+    switch filters->Array.getUnsafe(0)->asSingleOperator {
+    | Some((fieldName, ("_eq" | "_in") as operator, _)) =>
+      let values = []
+      filters->Array.forEach(filter =>
+        switch filter->asSingleOperator {
+        | Some((candidateField, candidateOperator, fieldValue))
+          if candidateField === fieldName && candidateOperator === operator =>
+          if operator === "_in" {
+            fieldValue->asArray->Array.forEach(value => values->Array.push(value)->ignore)
+          } else {
+            values->Array.push(fieldValue)->ignore
+          }
+        | _ => throwUnmergeable(filter)
+        }
+      )
+      [
+        Dict.fromArray([
+          (fieldName, dict{"_in": values->(Utils.magic: array<unknown> => unknown)}),
+        ])->unsafeFromDict,
       ]
-    | Gt(_) | Lt(_) | And(_) => filters
+    | _ => filters
     }
   }
 
-// A field missing on the entity reads as `undefined`, which matches the `None`
-// arm of `FieldValue.t` (`option<...>`), so nullable columns omitted on the
-// entity object are compared as null rather than crashing.
-let rec matches = (filter: t, ~entity: dict<FieldValue.t>) =>
-  switch filter {
-  | Eq({fieldName, fieldValue}) =>
-    entity->Dict.getUnsafe(fieldName)->FieldValue.eq(fieldValue->FieldValue.castFrom)
-  | Gt({fieldName, fieldValue}) =>
-    entity->Dict.getUnsafe(fieldName)->FieldValue.gt(fieldValue->FieldValue.castFrom)
-  | Lt({fieldName, fieldValue}) =>
-    entity->Dict.getUnsafe(fieldName)->FieldValue.lt(fieldValue->FieldValue.castFrom)
-  | In({fieldName, fieldValue}) => {
-      let entityFieldValue = entity->Dict.getUnsafe(fieldName)
-      fieldValue->Array.some(fieldValue =>
-        entityFieldValue->FieldValue.eq(fieldValue->FieldValue.castFrom)
+// A predicate specialized to a single filter. The field's comparison is
+// resolved once from the table config, so per-entity matching avoids both the
+// operator dispatch and the polymorphic compare.
+type matcher = Internal.entity => bool
+
+// Reads a field off an entity by its API name. Indexed/queryable fields hold
+// raw runtime values, so the result is compared directly.
+@get_index external getField: (Internal.entity, string) => unknown = ""
+
+// Compares (entityValue, filterValue) raw runtime values for one field. A
+// nullish entity value (a missing or null column) matches nothing, mirroring
+// SQL NULL semantics and the Postgres-side filter.
+type valueCompare = {
+  eq: (unknown, unknown) => bool,
+  gt: (unknown, unknown) => bool,
+  lt: (unknown, unknown) => bool,
+  // Projects a value onto something a Map can key by. Primitives key by
+  // themselves; the object-shaped types have to collapse to a primitive or
+  // equal values would miss each other on identity.
+  key: unknown => unknown,
+}
+
+// `>`/`<` on `unknown` would compile to the polymorphic Primitive_object path; the raw
+// operators give native JS comparison for primitive (string/number/bigint)
+// fields. `===` is already physical equality and false for a nullish column,
+// but `<` and `>` coerce a `null` column to 0 (a JS handler can write one for
+// a nullable field), so the ordering operators check for it first.
+let nativeEq = (a: unknown, b: unknown) => a === b
+let nativeGt: (unknown, unknown) => bool = %raw(`(a, b) => a != null && a > b`)
+let nativeLt: (unknown, unknown) => bool = %raw(`(a, b) => a != null && a < b`)
+let identityKey = (v: unknown) => v
+let native = {eq: nativeEq, gt: nativeGt, lt: nativeLt, key: identityKey}
+
+// A nullable column holds null where a row has no value, and a comparison that
+// calls a method on it would throw. Matching nothing is what SQL does, and
+// saying so once here keeps every comparison below a plain two-value compare.
+// The filter's own value needs no such guard — parseOrThrow rejects a nullish one.
+let nullSafe = (compare: valueCompare): valueCompare => {
+  eq: (a, b) => !(a->nullish) && compare.eq(a, b),
+  gt: (a, b) => !(a->nullish) && compare.gt(a, b),
+  lt: (a, b) => !(a->nullish) && compare.lt(a, b),
+  key: compare.key,
+}
+
+let asBigDecimal = (v: unknown) => v->(Utils.magic: unknown => BigDecimal.t)
+let bigDecimal = nullSafe({
+  eq: (a, b) => BigDecimal.equals(a->asBigDecimal, b->asBigDecimal),
+  gt: (a, b) => BigDecimal.gt(a->asBigDecimal, b->asBigDecimal),
+  lt: (a, b) => BigDecimal.lt(a->asBigDecimal, b->asBigDecimal),
+  key: v => v->asBigDecimal->BigDecimal.toString->(Utils.magic: string => unknown),
+})
+
+let getTime = (v: unknown) => v->(Utils.magic: unknown => Date.t)->Date.getTime
+let date = nullSafe({
+  eq: (a, b) => getTime(a) === getTime(b),
+  gt: (a, b) => getTime(a) > getTime(b),
+  lt: (a, b) => getTime(a) < getTime(b),
+  key: v => v->getTime->(Utils.magic: float => unknown),
+})
+
+// Json has no meaningful ordering, so reuse the structural compare for every
+// operator. Polymorphic `==` is intentional here.
+let json = nullSafe({
+  eq: (a: unknown, b: unknown) => a == b,
+  gt: (a, b) => a > b,
+  lt: (a, b) => a < b,
+  key: v => v->jsonStringify->(Utils.magic: string => unknown),
+})
+
+let asBytes = (v: unknown) => v->(Utils.magic: unknown => Uint8Array.t)
+let bytes = nullSafe({
+  eq: (a, b) => Utils.Bytes.compare(a->asBytes, b->asBytes) === 0.,
+  gt: (a, b) => Utils.Bytes.compare(a->asBytes, b->asBytes) > 0.,
+  lt: (a, b) => Utils.Bytes.compare(a->asBytes, b->asBytes) < 0.,
+  key: v => v->asBytes->Utils.Bytes.toHex->(Utils.magic: string => unknown),
+})
+
+// Postgres orders an enum by the position its members were declared in, not
+// by their names. Equality stays native so an _in keeps the Set fast path.
+let enum_ = (config: Table.enumConfig<Table.enum>): valueCompare => {
+  let ranks = Dict.make()
+  config.variants->Array.forEachWithIndex((variant, rank) =>
+    ranks->Dict.set(variant->(Utils.magic: Table.enum => string), rank)
+  )
+  let rank = (v: unknown) => ranks->Dict.getUnsafe(v->(Utils.magic: unknown => string))
+  {
+    eq: nativeEq,
+    gt: (a, b) => !(a->nullish) && rank(a) > rank(b),
+    lt: (a, b) => !(a->nullish) && rank(a) < rank(b),
+    key: identityKey,
+  }
+}
+
+let scalarCompare = (fieldType: Table.fieldType): valueCompare =>
+  switch fieldType {
+  | BigDecimal(_) => bigDecimal
+  | Date => date
+  | Json => json
+  | Bytea => bytes
+  | Enum({config}) => enum_(config)
+  | String
+  | Boolean
+  | Uint32
+  | UInt52
+  | SmallInt
+  | UInt64
+  | Int32
+  | ChainId
+  | Number
+  | BigInt(_)
+  | Serial
+  | BigSerial => native
+  }
+
+// Array-valued fields compare element-wise with the element type's comparator:
+// equality is length + pairwise eq, ordering is lexicographic where the first
+// differing element decides and a proper prefix is the smaller array. The key
+// follows the same rule, concatenating each element's own key, so a Date[]
+// keys by epoch millis and a Bytea[] by hex without inspecting a value.
+let arrayCompare = (element: valueCompare): valueCompare => {
+  let eq = (a, b) => {
+    let a = a->asArray
+    let b = b->asArray
+    let len = a->Array.length
+    len === b->Array.length && {
+        let rec go = i =>
+          i >= len || (element.eq(a->Array.getUnsafe(i), b->Array.getUnsafe(i)) && go(i + 1))
+        go(0)
+      }
+  }
+  let order = (~gt) =>
+    (a, b) => {
+      let a = a->asArray
+      let b = b->asArray
+      let la = a->Array.length
+      let lb = b->Array.length
+      let len = la < lb ? la : lb
+      let rec go = i =>
+        if i >= len {
+          gt ? la > lb : la < lb
+        } else {
+          let x = a->Array.getUnsafe(i)
+          let y = b->Array.getUnsafe(i)
+          if element.eq(x, y) {
+            go(i + 1)
+          } else if gt {
+            element.gt(x, y)
+          } else {
+            element.lt(x, y)
+          }
+        }
+      go(0)
+    }
+  nullSafe({
+    eq,
+    gt: order(~gt=true),
+    lt: order(~gt=false),
+    key: v => {
+      let key = ref("")
+      v->asArray->Array.forEach(item => key := key.contents ++ encodeValueKey(element.key(item)))
+      key.contents->(Utils.magic: string => unknown)
+    },
+  })
+}
+
+// Built once per table: an array field's comparator closes over its element's,
+// so resolving it per lookup would allocate that chain on every getWhere.
+let comparesByField: Table.table => dict<
+  valueCompare,
+> = Utils.WeakMap.memoize((table: Table.table) => {
+  let compares = Dict.make()
+  table.fields->Array.forEach(field =>
+    switch field {
+    | Field(field) =>
+      let element = scalarCompare(field.fieldType)
+      compares->Dict.set(
+        field->Table.getApiFieldName,
+        field.isArray ? arrayCompare(element) : element,
       )
+    | DerivedFrom(_) => ()
     }
-  | And({filters: []}) =>
-    JsError.throwWithMessage(`The "and" filter must contain at least one nested filter.`)
-  | And({filters}) => filters->Array.every(filter => filter->matches(~entity))
+  )
+  compares
+})
+
+let fieldCompare = (~table: Table.table, fieldName) =>
+  switch table->comparesByField->Utils.Dict.dangerouslyGetNonOption(fieldName) {
+  | Some(compare) => compare
+  | None =>
+    JsError.throwWithMessage(
+      `Internal error: no comparator for the field "${fieldName}" on the table "${table.tableName}". A filter is parsed against its table before it reaches the in-memory matcher.`,
+    )
   }
 
-// In values are mapped as one array (isArray=true), so they can be
-// converted with the table's cached array schema in a single pass.
-let rec mapValues = (
-  filter: t,
-  ~mapValue: (~fieldName: string, ~fieldValue: unknown, ~isArray: bool) => unknown,
-) =>
-  switch filter {
-  | Eq({fieldName, fieldValue}) =>
-    Eq({fieldName, fieldValue: mapValue(~fieldName, ~fieldValue, ~isArray=false)})
-  | Gt({fieldName, fieldValue}) =>
-    Gt({fieldName, fieldValue: mapValue(~fieldName, ~fieldValue, ~isArray=false)})
-  | Lt({fieldName, fieldValue}) =>
-    Lt({fieldName, fieldValue: mapValue(~fieldName, ~fieldValue, ~isArray=false)})
-  | In({fieldName, fieldValue}) =>
-    In({
-      fieldName,
-      fieldValue: mapValue(
-        ~fieldName,
-        ~fieldValue=fieldValue->(Utils.magic: array<unknown> => unknown),
-        ~isArray=true,
-      )->(Utils.magic: unknown => array<unknown>),
+// Projects a field's values onto Map keys, so an index can be found by value
+// instead of by a serialized filter.
+let makeValueKey = (~table: Table.table, ~fieldName) => (fieldName->fieldCompare(~table)).key
+
+// The cache key stands in for structural equality between filters. Values go
+// through the same per-field projection the equality buckets key by, so the
+// two agree on which values are distinct.
+//
+// Each field/operator entry ends with ";", which no field name or value key
+// starts with, so an _in's value list can't run into the next field name: a
+// one-letter key like "t" for true followed by field "b" would otherwise read
+// the same as an empty list followed by field "tb".
+let toString = (filter: t, ~table: Table.table) => {
+  let key = ref("")
+  filter
+  ->entries
+  ->Utils.Dict.forEachWithKey((operators, fieldName) => {
+    let keyOf = makeValueKey(~table, ~fieldName)
+    operators->Utils.Dict.forEachWithKey((fieldValue, operator) => {
+      key := key.contents ++ fieldName ++ operator
+      if operator === "_in" {
+        fieldValue
+        ->asArray
+        ->Array.forEach(value => key := key.contents ++ encodeValueKey(keyOf(value)))
+      } else {
+        key := key.contents ++ encodeValueKey(keyOf(fieldValue))
+      }
+      key := key.contents ++ ";"
+    })
+  })
+  key.contents
+}
+
+// Values are replaced by placeholders so calls that differ only in what they
+// filter for batch together.
+let toOperationKey = (filter: t, ~entityName) => {
+  let params = ref(0)
+  let printed = ref("")
+  filter
+  ->entries
+  ->Utils.Dict.forEachWithKey((operators, fieldName) => {
+    let ops = ref("")
+    // An _eq on its own is written without the operator, the way the user does.
+    let loneEq = ref(false)
+    operators->Utils.Dict.forEachWithKey((_, operator) => {
+      params := params.contents + 1
+      let part = `${operator}: $${params.contents->Int.toString}`
+      loneEq := ops.contents === "" && operator === "_eq"
+      ops := (ops.contents === "" ? part : ops.contents ++ ", " ++ part)
     })
-  | And({filters}) => And({filters: filters->Array.map(filter => filter->mapValues(~mapValue))})
+    let part = loneEq.contents
+      ? `${fieldName}: $${params.contents->Int.toString}`
+      : `${fieldName}: {${ops.contents}}`
+    printed := (printed.contents === "" ? part : printed.contents ++ ", " ++ part)
+  })
+  `${entityName}.getWhere({${printed.contents}})`
+}
+
+let makeMatcher = (filter: t, ~table: Table.table): matcher => {
+  let checks = []
+  filter
+  ->entries
+  ->Utils.Dict.forEachWithKey((operators, fieldName) => {
+    let compare = fieldName->fieldCompare(~table)
+    operators->Utils.Dict.forEachWithKey((fieldValue, operator) => {
+      let check = switch operator {
+      | "_eq" => entity => compare.eq(entity->getField(fieldName), fieldValue)
+      | "_gt" => entity => compare.gt(entity->getField(fieldName), fieldValue)
+      | "_lt" => entity => compare.lt(entity->getField(fieldName), fieldValue)
+      | "_gte" =>
+        entity => {
+          let entityFieldValue = entity->getField(fieldName)
+          compare.eq(entityFieldValue, fieldValue) || compare.gt(entityFieldValue, fieldValue)
+        }
+      | "_lte" =>
+        entity => {
+          let entityFieldValue = entity->getField(fieldName)
+          compare.eq(entityFieldValue, fieldValue) || compare.lt(entityFieldValue, fieldValue)
+        }
+      | "_in" =>
+        let fieldValues = fieldValue->asArray
+        if compare.eq === nativeEq {
+          let set = fieldValues->Utils.Set.fromArray
+          entity => set->Utils.Set.has(entity->getField(fieldName))
+        } else {
+          entity => {
+            let entityFieldValue = entity->getField(fieldName)
+            fieldValues->Array.some(candidate => compare.eq(entityFieldValue, candidate))
+          }
+        }
+      | _ =>
+        JsError.throwWithMessage(
+          `Invalid operator "${operator}" in a getWhere filter. Valid operators are _eq, _gt, _lt, _gte, _lte, _in.`,
+        )
+      }
+      checks->Array.push(check)->ignore
+    })
+  })
+  switch checks {
+  | [check] => check
+  | _ => entity => checks->Array.every(check => check(entity))
   }
+}