@rebasepro/common 0.23.0 → 0.24.1-canary.g56af4a4

package/dist/data/filter-dialect.es.js

@@ -0,0 +1,786 @@
+import { normalizeToEntityRelation } from "../util/entities.es.js";
+import { ALL_WHERE_FILTER_OPS, CANONICAL_TO_REST, LIST_OPS, NULL_OPS, REST_TO_CANONICAL, toCanonicalOp } from "@rebasepro/types";
+//#region src/data/filter-dialect.ts
+/**
+* REST wire-format adapter for the unified filter system.
+*
+* This module is the ONLY code in the entire codebase that knows about
+* PostgREST-style dot-syntax strings (`eq.active`, `gt.18`, `in.(a,b)`).
+* Everything else speaks `FilterValues` exclusively.
+*
+* Wire-format values are always strings — the wire format carries no type
+* metadata, so type coercion is the responsibility of the server-side data
+* driver which has access to the collection schema.
+*
+* Structural characters inside a value are backslash-escaped: `,` → `\,`,
+* `(` → `\(`, `)` → `\)`, and a literal backslash as `\\`. Decoding is
+* deliberately conservative — only those four sequences are decoded, so a
+* backslash that arrives unescaped from an older client survives intact.
+*
+* @module
+*/
+/**
+* Serialize a JS value to its querystring representation.
+* `null` is serialized as the literal string `"null"`.
+* Relation values (`EntityRelation` instances or `{ __type: "relation", id, path }`
+* objects) are serialized as their raw id — the wire format only carries the
+* value to compare against the FK column.
+*
+* A `Date` is its ISO 8601 instant — what JSON makes of it on the socket and
+* in-process, so one filter names one instant through every door. `String()`
+* gave the viewer's local zone, no milliseconds and a parenthesised zone name
+* Postgres cannot parse. An invalid date keeps its "Invalid Date" spelling for
+* the server to refuse, rather than throwing a `RangeError` from here.
+*/
+function stringifyValue(value) {
+	if (value === null) return "null";
+	if (value instanceof Date && !Number.isNaN(value.getTime())) return value.toISOString();
+	const relation = normalizeToEntityRelation(value);
+	if (relation) return String(relation.id);
+	return String(value);
+}
+/**
+* Characters that carry structure in the wire format and must therefore be
+* escaped inside a value: the separator, the group delimiters, and the escape
+* character itself.
+*
+* Parentheses are here because `and(...)`/`or(...)` groups are parsed by
+* tracking paren depth. A value containing one is not merely ambiguous, it
+* moves where the parser thinks the group ends.
+*/
+var WIRE_SPECIALS = /[\\,()]/g;
+/**
+* Escape a value for the wire format: `\` → `\\`, `,` → `\,`, `(` → `\(`,
+* `)` → `\)`.
+*/
+/**
+* The wire spelling of an empty list.
+*
+* A lone backslash: unproducible by {@link escapeWireValue}, which doubles
+* every backslash it emits, so it cannot collide with any real item.
+*/
+var EMPTY_LIST_TOKEN = "\\";
+function escapeWireValue(value) {
+	return value.replace(WIRE_SPECIALS, (ch) => `\\${ch}`);
+}
+/**
+* Unescape a wire-format value.
+*
+* **Conservative**, and deliberately so: only the four sequences
+* {@link escapeWireValue} actually produces are decoded. A backslash followed
+* by anything else is left exactly as it is.
+*
+* This used to consume the backslash before *any* character, which is
+* indistinguishable for anything this codec emitted — it only ever emits those
+* four — but not for input arriving from elsewhere. A client on an older
+* release sends a Windows path or a LIKE pattern with a literal `C:\x`
+* unescaped, and greedy unescaping silently turned it into `C:x`, changing
+* which rows matched. Decoding only what the encoder can produce makes the two
+* directions agree across versions.
+*/
+function unescapeWireValue(value) {
+	let result = "";
+	for (let i = 0; i < value.length; i++) {
+		const next = value[i + 1];
+		if (value[i] === "\\" && (next === "\\" || next === "," || next === "(" || next === ")")) {
+			result += next;
+			i++;
+			continue;
+		}
+		result += value[i];
+	}
+	return result;
+}
+/**
+* Whether a scalar, sent raw as a query parameter's operand, would be read
+* back as something other than itself.
+*
+* A query parameter owns its whole value, so its scalar goes out unescaped —
+* `eq.a,b`, `eq.C:\x` — and the decoder returns it verbatim. Two shapes break
+* that. A parenthesised operand is a list for every operator (so that
+* `["==", ["a","b"]]` on an array column stays a list), so raw, the scalar
+* `"(deleted)"` would arrive as `["deleted"]`: an `==` matching nothing, a
+* `!=` returning the very rows it excludes. Such a scalar is sent escaped,
+* `eq.\(deleted\)`. And that spelling has to be told apart from a raw value
+* that looks the same, so a scalar of *that* shape is escaped in turn.
+*
+* Everything else stays raw, so a value an older client sends decodes as it
+* always has — unless it is exactly the escaped spelling of such a scalar,
+* which decodes to the scalar it spells.
+*/
+function scalarNeedsEscape(value) {
+	if (value.startsWith("(") && value.endsWith(")")) return true;
+	return decodeEscapedScalar(value) !== void 0;
+}
+/**
+* The scalar an operand is the escaped spelling of, when it is one.
+*
+* Exact on purpose: only an operand that {@link escapeWireValue} produces from
+* a scalar that {@link scalarNeedsEscape} is decoded. Any other operand —
+* including a raw backslash an older client sent, like `\\server\share` — is
+* left verbatim. Terminates because an operand that matches contains an
+* escape pair, so the value is strictly shorter than it.
+*/
+function decodeEscapedScalar(operand) {
+	if (!operand.startsWith("\\")) return void 0;
+	const value = unescapeWireValue(operand);
+	return escapeWireValue(value) === operand && scalarNeedsEscape(value) ? value : void 0;
+}
+/**
+* Split a parenthesized list string on unescaped commas.
+* Input is the content between `(` and `)`.
+*
+* @example
+* splitListItems("admin,editor")          // ["admin", "editor"]
+* splitListItems("hello\\, world,foo")    // ["hello, world", "foo"]
+*/
+function splitListItems(inner) {
+	const items = [];
+	let current = "";
+	for (let i = 0; i < inner.length; i++) if (inner[i] === "\\" && i + 1 < inner.length) {
+		current += inner[i] + inner[i + 1];
+		i++;
+	} else if (inner[i] === ",") {
+		items.push(unescapeWireValue(current));
+		current = "";
+	} else current += inner[i];
+	items.push(unescapeWireValue(current));
+	return items;
+}
+/**
+* Split a group body on commas at paren depth 0, honouring escapes.
+*
+* The escape-awareness is the point. The splitter used to track only paren
+* depth, so a comma inside a scalar value ended a condition:
+* `or(name.eq.Doe, John,age.gte.18)` parsed as *three* conditions, the middle
+* one a fabricated `" John" == true`. On an `or` that widens the result set,
+* and nothing anywhere reports an error — the query simply stops meaning what
+* the caller wrote.
+*/
+function splitGroupItems(inner) {
+	const parts = [];
+	let depth = 0;
+	let start = 0;
+	for (let i = 0; i < inner.length; i++) {
+		const ch = inner[i];
+		if (ch === "\\" && i + 1 < inner.length) {
+			i++;
+			continue;
+		}
+		if (ch === "(") depth++;
+		else if (ch === ")") depth--;
+		else if (ch === "," && depth === 0) {
+			parts.push(inner.slice(start, i));
+			start = i + 1;
+		}
+	}
+	parts.push(inner.slice(start));
+	return parts;
+}
+/**
+* Operator tables as `Map`s, because the key comes off the wire.
+*
+* Indexed as plain objects, every `Object.prototype` member answered: a query
+* string of `?f=valueOf.x` found a truthy "operator" — the inherited function —
+* and `deserializeTuple` returned it *as the operator*, so a function object
+* travelled on into the compilers in place of a `WhereFilterOp`. The guard one
+* line below (`if (!canonicalOp)`) reads as though it rejects anything unknown,
+* and does not: `Object.prototype` is not unknown to a plain object.
+*
+* Same shape as the prototype-key defects swept out of `setIn`, `getIn`,
+* `mergeDeep`, `unflattenObject` and `FOREIGN_CONVENTION_UIDS`.
+*/
+var REST_OP_LOOKUP = new Map(Object.entries(REST_TO_CANONICAL));
+var CANONICAL_OP_LOOKUP = new Map(Object.entries(CANONICAL_TO_REST));
+/** The operator spellings a rejection lists back to the caller. */
+var VALID_OPERATOR_LIST = ALL_WHERE_FILTER_OPS.join(", ");
+/**
+* A filter condition named an operator this dialect does not have.
+*
+* ## Why this throws, rather than returning a typed rejection
+*
+* `deserializeFilter` is the *shared* codec: the REST ingress
+* (`packages/server/src/api/rest/query-parser.ts`), the browser SDK and the
+* admin panel (`buildRebaseData.ts`) all decode through it. Two constraints
+* follow.
+*
+* - It cannot throw the server's `ApiError`. `@rebasepro/common` does not
+*   depend on `@rebasepro/server` (the dependency runs the other way), and a
+*   browser client has no error handler to render an `ApiError` with. So the
+*   rejection is this plain `Error` subclass, whose `message` reads correctly
+*   wherever it surfaces — a rejected promise in an app, a 400 body over HTTP.
+* - It cannot be a returned rejection *value*. Every caller assigns the result
+*   straight into a query it is about to run; a sentinel that none of them
+*   check would be ignored, which is exactly the silently-wrong-filter failure
+*   this exists to stop. Throwing is also what this file already does for the
+*   sibling cases — `serializeTuple` on an unknown canonical operator,
+*   `deserializeLogicalCondition` past the nesting bound — and the REST parser
+*   already converts the latter into a 400.
+*
+* `statusCode`, `code` and `details` are carried as fields because the server's
+* Hono error handler duck-types those off any thrown error: a decode path that
+* forgets to convert still answers 400 with the canonical envelope instead of a
+* 500 that says "An unexpected error occurred". `query-parser.ts` converts
+* explicitly all the same — that is the path the contract is stated on, and an
+* incidental 400 is not a contract.
+*/
+var UnknownFilterOperatorError = class extends Error {
+	/** The field the condition was written against. */
+	field;
+	/** The operator string as it arrived, verbatim. */
+	operator;
+	/** Every operator this dialect accepts, in canonical spelling. */
+	validOperators = ALL_WHERE_FILTER_OPS;
+	/** See the class docblock: read by the server's error handler. */
+	statusCode = 400;
+	code = "UNKNOWN_FILTER_OPERATOR";
+	details;
+	constructor(field, operator) {
+		super(`Unknown filter operator '${operator}' on field '${field}'. Valid operators: ${VALID_OPERATOR_LIST}`);
+		this.name = "UnknownFilterOperatorError";
+		this.field = field;
+		this.operator = operator;
+		this.details = {
+			field,
+			operator,
+			validOperators: ALL_WHERE_FILTER_OPS
+		};
+	}
+};
+/**
+* Two to three characters of ASCII punctuation and nothing else — the shape
+* every symbolic operator has (`==`, `>=`, `<>`, `~~`, `!!`, `>>`, `===`), and
+* one a column value effectively never has.
+*
+* Two characters minimum on purpose. A *single* punctuation character is a
+* perfectly ordinary value — `{ grade: ["-", "+"] }` is a two-item list, not a
+* condition — and the only single-character operator anyone actually mistypes
+* is `=`, which is named separately below. `<` and `>` need no special case:
+* they are real operators and resolve.
+*/
+var SYMBOLIC_OPERATOR = /^[^\p{L}\p{N}\s]{2,3}$/u;
+/** Lowercase, strip everything that is not a letter or digit. */
+function normalizeOperatorName(op) {
+	return op.toLowerCase().replace(/[^a-z0-9]/g, "");
+}
+/**
+* Every real operator name with its case and separators removed, so a
+* respelling of one — `arrayContains`, `not_in`, `NOT-LIKE`, `isNull` — is
+* recognised as an attempt at an operator rather than read as a value.
+*
+* These are rejected rather than accepted: admitting a second spelling of an
+* operator would leave two wire spellings of one thing, and the rejection
+* message names the one that works.
+*/
+var RESPELLED_OPERATORS = new Set([...ALL_WHERE_FILTER_OPS, ...Object.keys(REST_TO_CANONICAL)].map(normalizeOperatorName));
+/**
+* Operator names *other* query dialects use, which this one does not have.
+*
+* This list is curated, and deliberately so. For a word-shaped string there is
+* no rule that separates "an operator the caller guessed" from "a value that
+* happens to be a word": `{ tags: ["a", "b"] }` has to keep meaning a two-item
+* `in` list, so the codec cannot simply refuse every unrecognised word in
+* position 0. The line is therefore drawn by name, and only around names whose
+* use as an operator is far more likely than their use as one of two sibling
+* values. `contains` is the motivating case — the first thing a developer
+* reaches for, and until now it compiled to `title IN ('contains', 'Hell')`.
+*
+* Genuinely ambiguous single words (`any`, `all`, `exists`, `search`, `not`)
+* are left off: as operators they are rare, and as enum values they are common.
+* Everywhere else the tie goes to *rejecting*, because a 400 naming the
+* supported set costs the caller one round trip, and the alternative — which is
+* what every name on this list used to produce — is a query that runs, returns
+* rows, and is wrong.
+*/
+var NEAR_MISS_OPERATORS = /* @__PURE__ */ new Set([
+	"contains",
+	"notcontains",
+	"doesnotcontain",
+	"doesnotcontains",
+	"includes",
+	"notincludes",
+	"startswith",
+	"notstartswith",
+	"beginswith",
+	"startingwith",
+	"endswith",
+	"notendswith",
+	"matches",
+	"notmatches",
+	"regex",
+	"regexp",
+	"between",
+	"notbetween",
+	"equals",
+	"notequals",
+	"equalto",
+	"isequalto",
+	"isnotequalto",
+	"greaterthan",
+	"greaterthanorequal",
+	"greaterthanorequalto",
+	"lessthan",
+	"lessthanorequal",
+	"lessthanorequalto",
+	"isempty",
+	"isnotempty",
+	"oneof",
+	"noneof",
+	"anyof",
+	"allof",
+	"null",
+	"isnullorempty"
+]);
+/**
+* Was this string *meant* as an operator?
+*
+* Only consulted after {@link toCanonicalOp} has already failed to resolve it,
+* so a `true` here is always a rejection.
+*/
+function isOperatorShaped(op) {
+	if (op === "=") return true;
+	if (SYMBOLIC_OPERATOR.test(op)) return true;
+	const normalized = normalizeOperatorName(op);
+	if (!normalized) return false;
+	return RESPELLED_OPERATORS.has(normalized) || NEAR_MISS_OPERATORS.has(normalized);
+}
+/**
+* Read a `[op, value]` tuple, if that is what this is.
+*
+* Three outcomes, and the middle one is the defect this function exists for:
+*
+* - the operator resolves (canonical *or* REST spelling) → the canonical tuple;
+* - the operator does not resolve but was plainly meant as one → throw;
+* - it does not look like an operator at all → `undefined`, and the caller
+*   falls back to reading the array as a list of values.
+*
+* The old test was `toCanonicalOp(raw[0]) === raw[0]`, i.e. canonical spelling
+* only, with *everything else* — including every REST short-code — dropping
+* through to `["in", raw]`. So the operator string itself became a value in a
+* membership test: `["!!", "Hello"]` compiled to `title IN ('!!','Hello')`,
+* which matches, and the caller got back rows their filter was written to
+* exclude. `["eq", "active"]` had the same shape of failure.
+*/
+function readTuple(field, raw) {
+	if (!Array.isArray(raw) || raw.length !== 2) return void 0;
+	const [op, value] = raw;
+	if (typeof op !== "string") return void 0;
+	const canonical = toCanonicalOp(op);
+	if (canonical) return [canonical, value];
+	if (op.includes(".")) return void 0;
+	if (isOperatorShaped(op)) throw new UnknownFilterOperatorError(field, op);
+}
+/**
+* The query-parameter names a REST listing reads as something other than a
+* field filter: pagination and whether to count, sorting, includes,
+* projection, search, the logical groups, the JSON `where` dialect, an
+* aggregate's `select`/`groupBy`, and the soft-delete switches.
+*
+* One list for both ends. The server skips these names when it collects
+* `?<field>=<op>.<value>` filters, and the SDK sends a filter on a column with
+* one of these names inside `?where=` instead — a collection is free to have a
+* `page`, `select` or `hard` column, and a filter on it sent as its own
+* parameter was read as the parameter and never applied.
+*/
+var RESERVED_QUERY_KEYS = /* @__PURE__ */ new Set([
+	"limit",
+	"offset",
+	"page",
+	"after",
+	"orderBy",
+	"include",
+	"fields",
+	"distinct",
+	"count",
+	"searchString",
+	"searchExplain",
+	"vector_search",
+	"vector",
+	"vector_distance",
+	"vector_threshold",
+	"or",
+	"and",
+	"not",
+	"where",
+	"select",
+	"groupBy",
+	"deleted",
+	"hard"
+]);
+/**
+* Encode the `<op>.<value>` half of a wire condition.
+*
+* This is the single leaf encoder. Both wire positions that carry a condition
+* — a top-level query parameter (`?status=eq.active`) and a leaf inside an
+* `and(...)`/`or(...)` group (`or(status.eq.active,…)`) — go through it, so a
+* rule expressed here holds in both. The group serializer used to carry its
+* own copy, and the copy had drifted on every rule that matters: `null` went
+* out as the four-character string, the empty list as `()`, and an operator
+* this dialect does not have was silently rewritten to `eq` — a filter that
+* ran, returned rows, and answered a different question than the one asked.
+*
+* `escapeScalar` is the one thing the two positions legitimately disagree
+* about. A scalar in a query parameter owns the whole value and needs no
+* escaping; a scalar inside a group sits between the same commas a list item
+* does, so a comma in it would end the condition early.
+*/
+function serializeOperatorAndValue(op, value, { escapeScalar, where }) {
+	if (typeof op !== "string") throw new TypeError(`${where}: operator must be a string, got ${typeof op}`);
+	const restOp = CANONICAL_OP_LOOKUP.get(op);
+	if (!restOp) throw new TypeError(`${where}: unknown operator "${op}". Valid operators: ${Object.keys(CANONICAL_TO_REST).join(", ")}`);
+	if (value === null && (op === "==" || op === "!=")) return op === "==" ? "isnull.null" : "notnull.null";
+	if (NULL_OPS.has(op)) return `${restOp}.null`;
+	if (Array.isArray(value)) {
+		if (value.length === 0) return `${restOp}.(${EMPTY_LIST_TOKEN})`;
+		return `${restOp}.(${value.map((v) => escapeWireValue(stringifyValue(v))).join(",")})`;
+	}
+	const scalar = stringifyValue(value);
+	return `${restOp}.${escapeScalar || !LIST_OPS.has(op) && scalarNeedsEscape(scalar) ? escapeWireValue(scalar) : scalar}`;
+}
+/**
+* Serialize a single canonical condition tuple to a PostgREST dot-string.
+*
+* Throws `TypeError` if the input is not a valid `[WhereFilterOp, unknown]` tuple.
+*
+* @example
+* serializeTuple(["==", "active"])           // "eq.active"
+* serializeTuple(["in", ["admin","editor"]]) // "in.(admin,editor)"
+* serializeTuple([">=", 18])                 // "gte.18"
+*/
+function serializeTuple(tuple) {
+	if (!Array.isArray(tuple) || tuple.length !== 2) throw new TypeError(`serializeTuple: expected a [WhereFilterOp, value] tuple, got ${JSON.stringify(tuple)}`);
+	const [op, value] = tuple;
+	return serializeOperatorAndValue(op, value, {
+		escapeScalar: false,
+		where: "serializeTuple"
+	});
+}
+/**
+* Convert `FilterValues` (or `WireFilterValues`) to a PostgREST-style
+* querystring record.
+*
+* - Canonical `[WhereFilterOp, value]` tuples are serialized strictly.
+* - Pre-serialized PostgREST strings (e.g. `"eq.published"`) are passed through.
+* - Single conditions produce a string value.
+* - Multiple conditions on the same field produce a string array (repeated params).
+*
+* @example
+* serializeFilter({ status: ["==", "active"] })
+* // → { status: "eq.active" }
+*
+* serializeFilter({ age: [[">=", 18], ["<", 65]] })
+* // → { age: ["gte.18", "lt.65"] }
+*
+* // Pre-serialized strings pass through unchanged:
+* serializeFilter({ status: "eq.published" })
+* // → { status: "eq.published" }
+*/
+function serializeFilter(filter) {
+	const result = {};
+	for (const [field, condition] of Object.entries(filter)) {
+		if (condition === void 0) continue;
+		if (typeof condition === "string") {
+			result[field] = condition;
+			continue;
+		}
+		if (Array.isArray(condition) && condition.length > 0 && Array.isArray(condition[0])) result[field] = condition.map(serializeTuple);
+		else result[field] = serializeTuple(condition);
+	}
+	return result;
+}
+/**
+* The spellings a null-testing operator's operand may take.
+*
+* The serializer writes `isnull.null`; a hand-written `isnull.true` means the
+* same thing and has always been accepted. Anything else after the operator is
+* not an operand it has — `notnull.reason` is a *value* — see
+* {@link deserializeSingle}.
+*/
+var NULL_OPERANDS = /* @__PURE__ */ new Set([
+	"null",
+	"true",
+	"false",
+	""
+]);
+/**
+* Parse a single PostgREST dot-string into a `[WhereFilterOp, unknown]` tuple.
+*
+* All values are returned as strings — the wire format carries no type
+* metadata, so coercion is the data driver's responsibility.
+*
+* ## When a leading segment is an operator, and when it is part of the value
+*
+* `?status=in.progress` and `?status=in.(a,b)` differ by one character and mean
+* entirely different things, and the reading here decides which. The rule, in
+* full:
+*
+* > A dot-string is read as `operator.operand` **only** when its first segment
+* > names a known REST operator **and** what follows is a well-formed operand
+* > *for that operator's arity*. Otherwise the whole string is the value.
+*
+* Arity, per operator family:
+*
+* - **List** operators (`in`, `nin`, `csa` — `LIST_OPS`) take a parenthesised
+*   list and nothing else. `in.(draft,review)` is the operator; `in.progress`
+*   is the *value* `"in.progress"`, because there is no list there and so no
+*   `in` filter that could have been written. That case used to compile to
+*   `status IN ('progress')` — a filter the caller never wrote, quietly
+*   matching the wrong rows and, on a status field, hiding every row they were
+*   looking for.
+* - **Null** operators (`isnull`, `notnull` — {@link NULL_OPS}) take no
+*   operand: only {@link NULL_OPERANDS}. `notnull.reason` is the value
+*   `"notnull.reason"`, not "reason is not null".
+* - **Everything else** takes one scalar, and any remainder is one — including
+*   the empty string, so `eq.` really is "equals the empty string". A
+*   parenthesised remainder is a list for these too (`eq.(a,b)` is array
+*   equality); a scalar that is itself parenthesised arrives escaped,
+*   `eq.\(none\)`, and is decoded here — see {@link scalarNeedsEscape}.
+*
+* ### The one ambiguity that remains, and how to write past it
+*
+* A scalar operator's operand is unconstrained, so `?status=like.that` is a
+* `LIKE 'that'` and no rule at this layer can tell it from the literal value
+* `"like.that"` — both are well-formed encodings, and picking either by guess
+* would break the other. Two spellings say "value" unambiguously, and both
+* round-trip:
+*
+* - `?status=eq.like.that` — name the operator. The *first* segment is consumed
+*   as the operator and everything after it is the value, dots and all. This is
+*   what `serializeFilter` emits, which is why the SDK never meets the
+*   ambiguity at all.
+* - `?where={"status":["==","like.that"]}` — the JSON dialect's tuple form.
+*
+* Values that merely *contain* dots (`user@host.com`, `1.2.3`) were never
+* ambiguous: their first segment names no operator to begin with.
+*/
+function deserializeSingle(raw) {
+	const dotIndex = raw.indexOf(".");
+	if (dotIndex === -1) return ["==", raw];
+	const prefix = raw.substring(0, dotIndex);
+	const rest = raw.substring(dotIndex + 1);
+	const canonicalOp = REST_OP_LOOKUP.get(prefix);
+	if (!canonicalOp) return ["==", raw];
+	if (NULL_OPS.has(canonicalOp)) {
+		if (!NULL_OPERANDS.has(rest)) return ["==", raw];
+		return [canonicalOp, null];
+	}
+	if (rest.startsWith("(") && rest.endsWith(")")) {
+		const inner = rest.slice(1, -1);
+		return [canonicalOp, inner === EMPTY_LIST_TOKEN ? [] : splitListItems(inner)];
+	}
+	if (LIST_OPS.has(canonicalOp)) return ["==", raw];
+	return [canonicalOp, decodeEscapedScalar(rest) ?? rest];
+}
+/**
+* Convert a PostgREST-style querystring record to `FilterValues`.
+*
+* - String values are parsed as single conditions.
+* - String arrays (repeated query params) become multiple conditions on the same field.
+*
+* @example
+* deserializeFilter({ status: "eq.active" })
+* // → { status: ["==", "active"] }
+*
+* deserializeFilter({ age: ["gte.18", "lt.65"] })
+* // → { age: [[">=", "18"], ["<", "65"]] }
+*
+* @throws {UnknownFilterOperatorError} when a condition names an operator this
+* dialect does not have. See that class for why a rejection here is a throw.
+*/
+function deserializeFilter(query) {
+	const result = {};
+	for (const [field, raw] of Object.entries(query)) {
+		if (raw === void 0) continue;
+		const tuple = readTuple(field, raw);
+		if (tuple) {
+			result[field] = tuple;
+			continue;
+		}
+		if (Array.isArray(raw)) {
+			if (raw.length === 0) continue;
+			if (Array.isArray(raw[0])) {
+				const tuples = raw.map((item) => readTuple(field, item));
+				if (tuples.every((t) => t !== void 0)) {
+					result[field] = tuples;
+					continue;
+				}
+			}
+			if (raw.length === 1) result[field] = typeof raw[0] === "string" ? deserializeSingle(raw[0]) : ["==", raw[0]];
+			else if (typeof raw[0] === "string" && raw[0].includes(".")) result[field] = raw.map((r) => typeof r === "string" ? deserializeSingle(r) : ["==", r]);
+			else result[field] = ["in", raw];
+		} else if (typeof raw === "string") result[field] = deserializeSingle(raw);
+		else result[field] = ["==", raw];
+	}
+	return result;
+}
+/**
+* Serialize a `LogicalCondition` or `FilterCondition` to its wire-format string.
+*
+* Leaf encoding is {@link serializeOperatorAndValue}, the same function
+* `serializeTuple` uses, so `null`, the empty list and an unknown operator
+* behave identically inside a group and in a query parameter.
+*
+* @throws {TypeError} when a leaf names an operator this dialect does not have.
+* It used to fall back to `eq`, which turned `age >= 18` into `age = 18` with
+* no diagnostic anywhere.
+*
+* @example
+* serializeLogicalCondition({ column: "status", operator: "==", value: "active" })
+* // → "status.eq.active"
+*
+* serializeLogicalCondition({ column: "deleted_at", operator: "==", value: null })
+* // → "deleted_at.isnull.null"
+*
+* serializeLogicalCondition({ type: "or", conditions: [...] })
+* // → "or(status.eq.active,status.eq.pending)"
+*/
+function serializeLogicalCondition(cond) {
+	if ("type" in cond) {
+		const inner = (cond.conditions ?? []).map(serializeLogicalCondition).join(",");
+		return `${cond.type}(${inner})`;
+	}
+	return `${escapeWireValue(cond.column)}.${serializeOperatorAndValue(cond.operator, cond.value, {
+		escapeScalar: true,
+		where: "serializeLogicalCondition"
+	})}`;
+}
+/**
+* The positions of the dots that can separate a leaf's segments.
+*
+* Dots inside a list value (`in.(1.5,2.5)`) are not separators. The value
+* always follows the operator, so the search only needs the region before the
+* first unescaped paren.
+*/
+function leafSeparators(str) {
+	let limit = str.length;
+	for (let i = 0; i < str.length; i++) {
+		if (str[i] === "\\") {
+			i++;
+			continue;
+		}
+		if (str[i] === "(") {
+			limit = i;
+			break;
+		}
+	}
+	const dots = [];
+	for (let i = 0; i < limit; i++) {
+		if (str[i] === "\\") {
+			i++;
+			continue;
+		}
+		if (str[i] === ".") dots.push(i);
+	}
+	return dots;
+}
+/**
+* Split a leaf condition into `column`, operator token and value.
+*
+* The naive reading — column is everything before the first dot, operator is
+* everything up to the second — cannot express a relation path. A filter on
+* `author.name` serializes to `author.name.eq.bob` and came back as the column
+* `author` with the operator `name`, which resolves to nothing, so the
+* fallback made it `author == "eq.bob"`: a condition that runs and matches
+* nothing, on a column the caller never named.
+*
+* So the operator is found rather than assumed: it is the first dot-separated
+* segment after the column that resolves to a real operator. Everything before
+* it is the column, everything after is the value. `version.eq.1.2.3` reads as
+* `version == "1.2.3"` because the scan stops at the first match — the `eq` at
+* offset 1, not a later segment — and `metadata->>x.eq.5` never had dots in the
+* column to begin with.
+*
+* Returns `undefined` when no segment resolves — `status.active`, an equality
+* written without an operator, which the caller handles.
+*/
+function splitLeafCondition(str) {
+	const dots = leafSeparators(str);
+	for (let i = 1; i < dots.length; i++) {
+		const operator = toCanonicalOp(str.substring(dots[i - 1] + 1, dots[i]));
+		if (!operator) continue;
+		return {
+			column: unescapeWireValue(str.substring(0, dots[i - 1])),
+			operator,
+			value: str.substring(dots[i] + 1)
+		};
+	}
+}
+/**
+* Parse a logical condition wire-format string back into a
+* `LogicalCondition` or `FilterCondition`.
+*
+* @example
+* deserializeLogicalCondition("status.eq.active")
+* // → { column: "status", operator: "==", value: "active" }
+*
+* deserializeLogicalCondition("or(status.eq.active,age.gte.18)")
+* // → { type: "or", conditions: [...] }
+*/
+/**
+* How deeply `or(...)`/`and(...)` groups may nest.
+*
+* This parser recurses once per level, on a value that arrives in a query
+* string. Unbounded, twenty thousand levels reached `RangeError: Maximum call
+* stack size exceeded`, which a caller sees as a 500 about the call stack
+* rather than a 400 about their filter. Node's 16 KB header cap keeps a GET
+* below that in practice, but "the HTTP layer happens to stop it" is not a
+* bound this parser should rely on.
+*
+* Thirty-two is far past anything a real filter expresses; the deepest in this
+* repository's own tests is three.
+*/
+var MAX_LOGICAL_NESTING_DEPTH = 32;
+function deserializeLogicalCondition(str, nesting = 0) {
+	if (nesting > MAX_LOGICAL_NESTING_DEPTH) throw new Error(`Filter groups nest more than ${MAX_LOGICAL_NESTING_DEPTH} levels deep. Flatten the condition — \`or(a,or(b,c))\` is \`or(a,b,c)\`.`);
+	const logicalMatch = str.match(/^(and|or|not)\((.+)\)$/);
+	if (logicalMatch) {
+		const type = logicalMatch[1];
+		const innerStr = logicalMatch[2];
+		return {
+			type,
+			conditions: splitGroupItems(innerStr).map((part) => deserializeLogicalCondition(part, nesting + 1))
+		};
+	}
+	const leaf = splitLeafCondition(str);
+	if (!leaf) {
+		const firstDot = str.indexOf(".");
+		if (firstDot === -1) return {
+			column: unescapeWireValue(str),
+			operator: "==",
+			value: true
+		};
+		const dots = leafSeparators(str);
+		for (let i = 1; i < dots.length; i++) {
+			const segment = str.substring(dots[i - 1] + 1, dots[i]);
+			if (isOperatorShaped(segment)) throw new UnknownFilterOperatorError(unescapeWireValue(str.substring(0, dots[i - 1])), segment);
+		}
+		return {
+			column: unescapeWireValue(str.substring(0, firstDot)),
+			operator: "==",
+			value: unescapeWireValue(str.substring(firstDot + 1))
+		};
+	}
+	const { column, operator, value: valueStr } = leaf;
+	if (NULL_OPS.has(operator)) return {
+		column,
+		operator,
+		value: null
+	};
+	if (valueStr.startsWith("(") && valueStr.endsWith(")")) {
+		const inner = valueStr.slice(1, -1);
+		return {
+			column,
+			operator,
+			value: inner === EMPTY_LIST_TOKEN ? [] : splitListItems(inner)
+		};
+	}
+	return {
+		column,
+		operator,
+		value: unescapeWireValue(valueStr)
+	};
+}
+//#endregion
+export { MAX_LOGICAL_NESTING_DEPTH, RESERVED_QUERY_KEYS, UnknownFilterOperatorError, deserializeFilter, deserializeLogicalCondition, serializeFilter, serializeLogicalCondition };
+
+//# sourceMappingURL=filter-dialect.es.js.map