@classytic/repo-core 0.1.0

package/dist/pagination/keyset.mjs

@@ -0,0 +1,61 @@
+//#region src/pagination/keyset.ts
+/**
+* Normalize a sort object so non-`_id` fields come first, `_id` last.
+* Stable ordering is required for cursor comparability across requests.
+*/
+function normalizeSort(sort) {
+	const normalized = {};
+	for (const key of Object.keys(sort)) if (key !== "_id") {
+		const direction = sort[key];
+		if (direction !== void 0) normalized[key] = direction;
+	}
+	const idDirection = sort["_id"];
+	if (idDirection !== void 0) normalized["_id"] = idDirection;
+	return normalized;
+}
+/**
+* Validate a sort spec for keyset pagination and return the normalized form.
+*
+* - Rejects empty sorts (keyset needs at least one field).
+* - Rejects non-`±1` directions.
+* - Rejects mixed directions across fields (keyset can't straddle directions).
+* - Auto-adds `_id` as tie-breaker (matching the primary direction) when absent.
+* - When `allowedPrimaryFields` is non-empty, rejects primary fields outside
+*   the allowlist (protects against lossy null-boundary keyset).
+*/
+function validateKeysetSort(sort, allowedPrimaryFields) {
+	const keys = Object.keys(sort);
+	if (keys.length === 0) throw new Error("Keyset pagination requires at least one sort field");
+	if (keys.length === 1 && keys[0] === "_id") return normalizeSort(sort);
+	for (const key of keys) {
+		const direction = sort[key];
+		if (direction !== 1 && direction !== -1) throw new Error(`Invalid sort direction for "${key}": must be 1 or -1, got ${String(direction)}`);
+	}
+	const nonIdKeys = keys.filter((k) => k !== "_id");
+	const firstNonId = nonIdKeys[0];
+	if (firstNonId === void 0) return normalizeSort(sort);
+	const primaryDirection = sort[firstNonId];
+	if (allowedPrimaryFields && allowedPrimaryFields.length > 0) {
+		for (const key of nonIdKeys) if (!allowedPrimaryFields.includes(key)) throw new Error(`Keyset sort field "${key}" is not in the strictKeysetSortFields allowlist. Allowed: ${allowedPrimaryFields.join(", ")}. (Protects against lossy null/non-null keyset boundaries.)`);
+	}
+	for (const key of nonIdKeys) if (sort[key] !== primaryDirection) throw new Error("All sort fields must share the same direction for keyset pagination");
+	if (keys.includes("_id") && sort["_id"] !== primaryDirection) throw new Error("_id direction must match primary field direction");
+	if (!keys.includes("_id")) return normalizeSort({
+		...sort,
+		_id: primaryDirection
+	});
+	return normalizeSort(sort);
+}
+/** Invert every direction in a sort (ascending ↔ descending). */
+function invertSort(sort) {
+	const inverted = {};
+	for (const key of Object.keys(sort)) inverted[key] = sort[key] === 1 ? -1 : 1;
+	return inverted;
+}
+/** Primary (first non-`_id`) sort field; falls back to `_id`. */
+function getPrimaryField(sort) {
+	for (const key of Object.keys(sort)) if (key !== "_id") return key;
+	return "_id";
+}
+//#endregion
+export { getPrimaryField, invertSort, normalizeSort, validateKeysetSort };

package/dist/pagination/offset.d.mts

@@ -0,0 +1,26 @@
+import { PaginationConfig } from "./types.mjs";
+
+//#region src/pagination/offset.d.ts
+/**
+ * Parse, clamp, and sanitize a `limit` value. Accepts string or number
+ * input (URL params arrive as strings). Returns the configured default
+ * when input is not a finite positive number.
+ *
+ * `config.maxLimit === 0` disables the upper cap (advanced usage only —
+ * unbounded page size is a footgun).
+ */
+declare function validateLimit(limit: number | string, config: PaginationConfig): number;
+/**
+ * Parse, clamp, and sanitize a 1-indexed `page` value.
+ * Throws when page exceeds `config.maxPage` — deep offset pagination is
+ * pathological and should be caught at the boundary.
+ */
+declare function validatePage(page: number | string, config: PaginationConfig): number;
+/** True when `page` is past the deep-pagination warning threshold. */
+declare function shouldWarnDeepPagination(page: number, threshold: number): boolean;
+/** Documents to skip for a given 1-indexed page + limit. */
+declare function calculateSkip(page: number, limit: number): number;
+/** Total page count from total rows + per-page limit. Zero-safe. */
+declare function calculateTotalPages(total: number, limit: number): number;
+//#endregion
+export { calculateSkip, calculateTotalPages, shouldWarnDeepPagination, validateLimit, validatePage };

package/dist/pagination/offset.mjs

@@ -0,0 +1,47 @@
+//#region src/pagination/offset.ts
+const DEFAULT_LIMIT = 10;
+const DEFAULT_MAX_LIMIT = 100;
+const DEFAULT_MAX_PAGE = 1e4;
+/**
+* Parse, clamp, and sanitize a `limit` value. Accepts string or number
+* input (URL params arrive as strings). Returns the configured default
+* when input is not a finite positive number.
+*
+* `config.maxLimit === 0` disables the upper cap (advanced usage only —
+* unbounded page size is a footgun).
+*/
+function validateLimit(limit, config) {
+	const parsed = Number(limit);
+	if (!Number.isFinite(parsed) || parsed < 1) return config.defaultLimit ?? DEFAULT_LIMIT;
+	const max = config.maxLimit ?? DEFAULT_MAX_LIMIT;
+	if (max === 0) return Math.floor(parsed);
+	return Math.min(Math.floor(parsed), max);
+}
+/**
+* Parse, clamp, and sanitize a 1-indexed `page` value.
+* Throws when page exceeds `config.maxPage` — deep offset pagination is
+* pathological and should be caught at the boundary.
+*/
+function validatePage(page, config) {
+	const parsed = Number(page);
+	if (!Number.isFinite(parsed) || parsed < 1) return 1;
+	const sanitized = Math.floor(parsed);
+	const maxPage = config.maxPage ?? DEFAULT_MAX_PAGE;
+	if (sanitized > maxPage) throw new Error(`Page ${String(sanitized)} exceeds maximum ${String(maxPage)}`);
+	return sanitized;
+}
+/** True when `page` is past the deep-pagination warning threshold. */
+function shouldWarnDeepPagination(page, threshold) {
+	return page > threshold;
+}
+/** Documents to skip for a given 1-indexed page + limit. */
+function calculateSkip(page, limit) {
+	return (page - 1) * limit;
+}
+/** Total page count from total rows + per-page limit. Zero-safe. */
+function calculateTotalPages(total, limit) {
+	if (limit <= 0) return 0;
+	return Math.ceil(total / limit);
+}
+//#endregion
+export { calculateSkip, calculateTotalPages, shouldWarnDeepPagination, validateLimit, validatePage };

package/dist/pagination/types.d.mts

@@ -0,0 +1,136 @@
+//#region src/pagination/types.d.ts
+/**
+ * Pagination primitives — driver-agnostic type surface.
+ *
+ * These types are the vocabulary shared between arc, the driver kits,
+ * and any consumer that talks to a repository. Kits extend with their
+ * own option types (e.g. mongokit adds `populate`, `collation`); those
+ * extensions never change the shape of the result envelope.
+ */
+/** Ascending (1) or descending (-1). */
+type SortDirection = 1 | -1;
+/** Sort specification keyed by field path. */
+type SortSpec = Record<string, SortDirection>;
+/** Global pagination configuration, configured once per repository. */
+interface PaginationConfig {
+  /** Default documents per page when caller omits `limit`. Default: 10. */
+  defaultLimit?: number;
+  /** Hard ceiling for `limit`. `0` means unlimited. Default: 100. */
+  maxLimit?: number;
+  /** Hard ceiling for `page`. Throws above this. Default: 10_000. */
+  maxPage?: number;
+  /** Page index that triggers a deep-pagination warning. Default: 100. */
+  deepPageThreshold?: number;
+  /** Cursor version — bump when the payload format changes. Default: 1. */
+  cursorVersion?: number;
+  /**
+   * Minimum cursor version accepted. Bump alongside `cursorVersion` when a
+   * breaking format change ships so stale client cursors are rejected with
+   * a clear error rather than silently resuming from the wrong position.
+   */
+  minCursorVersion?: number;
+  /**
+   * Allowlist of primary sort fields for keyset pagination. When set, any
+   * keyset request whose primary (non-`_id`) sort field isn't listed throws
+   * at validation time. Use this to lock keyset sorts to fields your schema
+   * guarantees non-null — keyset across null/non-null boundaries is lossy.
+   *
+   * `_id` is always allowed regardless of this list.
+   */
+  strictKeysetSortFields?: string[];
+}
+/**
+ * Known value types that round-trip through a cursor.
+ *
+ * `objectid` / `uuid` are NOT in this core union — repo-core is driver-free,
+ * so it treats any non-primitive string id as a plain `string`. Kits that
+ * need typed id rehydration (mongokit wants real `ObjectId` instances) can
+ * tag their own type in the payload and post-process on decode. Unknown
+ * tags round-trip unchanged as strings.
+ */
+type ValueType = 'date' | 'boolean' | 'number' | 'string' | 'null' | 'unknown';
+/** Raw cursor payload — the base64url JSON blob behind a cursor token. */
+interface CursorPayload {
+  /** Primary sort field value (legacy single-field compatibility). */
+  v: string | number | boolean | null;
+  /** Primary sort field value type tag. Open string so kits can extend. */
+  t: string;
+  /** Document id, serialized as string. */
+  id: string;
+  /** Document id type tag. Open string so kits can extend (e.g. `objectid`). */
+  idType: string;
+  /** Sort specification this cursor was built against. */
+  sort: SortSpec;
+  /** Cursor format version. */
+  ver: number;
+  /** Compound sort field values (multi-field keyset). */
+  vals?: Record<string, string | number | boolean | null>;
+  /** Compound sort value type tags. */
+  types?: Record<string, string>;
+}
+/** Decoded cursor with values rehydrated to their declared types. */
+interface DecodedCursor {
+  /** Primary sort field value (rehydrated). */
+  value: unknown;
+  /** Document id (rehydrated — string for unknown id types). */
+  id: unknown;
+  /** Sort specification. */
+  sort: SortSpec;
+  /** Cursor format version. */
+  version: number;
+  /** Compound sort field values (rehydrated). Present when the cursor was built from a multi-field sort. */
+  values?: Record<string, unknown>;
+}
+/**
+ * Core fields of an offset-paginated result. Don't consume this directly —
+ * use `OffsetPaginationResult<TDoc>` or `OffsetPaginationResult<TDoc, TExtra>`.
+ */
+interface OffsetPaginationResultCore<TDoc> {
+  method: 'offset';
+  docs: TDoc[];
+  page: number;
+  limit: number;
+  total: number;
+  pages: number;
+  hasNext: boolean;
+  hasPrev: boolean;
+}
+/**
+ * Offset-paginated result envelope.
+ *
+ * `TExtra` lets kits surface typed extras alongside the core envelope —
+ * mongokit emits `warning?: string` on deep-page reads, pgkit could surface
+ * `queryPlan`, sqlitekit could surface vacuum hints. Defaults to `{}` so
+ * consumers that don't care see zero change (`OffsetPaginationResult<User>`
+ * behaves exactly as before).
+ *
+ * The `method: 'offset'` discriminant carries through the intersection so
+ * `if (result.method === 'offset')` narrowing keeps working.
+ *
+ * @example Kit extends with typed extras
+ * ```ts
+ * type MongokitPage<T> = OffsetPaginationResult<T, { warning?: string }>;
+ * ```
+ */
+type OffsetPaginationResult<TDoc, TExtra extends Record<string, unknown> = {}> = OffsetPaginationResultCore<TDoc> & TExtra;
+/**
+ * Core fields of a keyset-paginated result. Don't consume this directly —
+ * use `KeysetPaginationResult<TDoc>` or `KeysetPaginationResult<TDoc, TExtra>`.
+ */
+interface KeysetPaginationResultCore<TDoc> {
+  method: 'keyset';
+  docs: TDoc[];
+  limit: number;
+  hasMore: boolean;
+  /** Cursor token for the next page, or `null` when there is none. */
+  next: string | null;
+}
+/**
+ * Keyset-paginated result envelope.
+ *
+ * `TExtra` parallels `OffsetPaginationResult` — see that type's docstring
+ * for the rationale. Defaults to `{}`.
+ */
+type KeysetPaginationResult<TDoc, TExtra extends Record<string, unknown> = {}> = KeysetPaginationResultCore<TDoc> & TExtra;
+//#endregion
+export { CursorPayload, DecodedCursor, KeysetPaginationResult, KeysetPaginationResultCore, OffsetPaginationResult, OffsetPaginationResultCore, PaginationConfig, SortDirection, SortSpec, ValueType };

package/dist/query-parser/coerce.d.mts

@@ -0,0 +1,16 @@
+import { QueryParserOptions } from "./types.mjs";
+
+//#region src/query-parser/coerce.d.ts
+/**
+ * Coerce a single URL value to its field-declared type, or to a best-guess
+ * scalar when no hint exists. Always returns `string`, `number`, `boolean`,
+ * `Date`, or `null` — never `undefined`.
+ */
+declare function coerceValue(rawValue: string, fieldType: QueryParserOptions['fieldTypes'] extends infer T ? T extends Record<string, infer V> ? V | undefined : undefined : undefined): unknown;
+/**
+ * Split a comma-separated URL value into an array of coerced scalars.
+ * Used by `in`/`nin`/`between` which accept `field[in]=a,b,c`.
+ */
+declare function coerceList(rawValue: string, fieldType: Parameters<typeof coerceValue>[1]): unknown[];
+//#endregion
+export { coerceList, coerceValue };

package/dist/query-parser/coerce.mjs

@@ -0,0 +1,73 @@
+//#region src/query-parser/coerce.ts
+const BOOLEAN_STRINGS = new Set([
+	"true",
+	"1",
+	"yes",
+	"on"
+]);
+const FALSEY_STRINGS = new Set([
+	"false",
+	"0",
+	"no",
+	"off"
+]);
+const ISO_DATE_RE = /^\d{4}-\d{2}-\d{2}(?:T\d{2}:\d{2}(?::\d{2}(?:\.\d{1,3})?)?(?:Z|[+-]\d{2}:?\d{2})?)?$/;
+/**
+* Coerce a single URL value to its field-declared type, or to a best-guess
+* scalar when no hint exists. Always returns `string`, `number`, `boolean`,
+* `Date`, or `null` — never `undefined`.
+*/
+function coerceValue(rawValue, fieldType) {
+	if (rawValue === "null") return null;
+	switch (fieldType) {
+		case "number": {
+			const n = Number(rawValue);
+			return Number.isFinite(n) ? n : rawValue;
+		}
+		case "boolean": return BOOLEAN_STRINGS.has(rawValue.toLowerCase());
+		case "date": {
+			const d = new Date(rawValue);
+			return Number.isNaN(d.getTime()) ? rawValue : d;
+		}
+		case "string": return rawValue;
+		default: return heuristicCoerce(rawValue);
+	}
+}
+/**
+* Heuristic used when no field-type hint applies. Deliberately conservative:
+*
+* - Pure boolean strings ("true", "false") → boolean.
+* - Unambiguous ISO-8601 dates → Date.
+* - Integers that don't start with 0 (unless literal "0") → number.
+* - Floats → number.
+* - Anything else stays a string.
+*
+* We do NOT coerce arbitrary-looking numeric strings ("12345") because
+* they're routinely SKUs, order IDs, or phone numbers. Callers needing
+* reliable numeric coercion pass `fieldTypes: { age: 'number' }`.
+*/
+function heuristicCoerce(value) {
+	if (BOOLEAN_STRINGS.has(value) && value.length <= 5) {
+		if (value === "true" || value === "false") return value === "true";
+	}
+	if (FALSEY_STRINGS.has(value) && (value === "false" || value === "true")) return value === "true";
+	if (ISO_DATE_RE.test(value)) {
+		const d = new Date(value);
+		if (!Number.isNaN(d.getTime())) return d;
+	}
+	if (/^-?\d+\.\d+$/.test(value)) {
+		const n = Number(value);
+		if (Number.isFinite(n)) return n;
+	}
+	return value;
+}
+/**
+* Split a comma-separated URL value into an array of coerced scalars.
+* Used by `in`/`nin`/`between` which accept `field[in]=a,b,c`.
+*/
+function coerceList(rawValue, fieldType) {
+	if (rawValue.length === 0) return [];
+	return rawValue.split(",").map((v) => coerceValue(v.trim(), fieldType));
+}
+//#endregion
+export { coerceList, coerceValue };

package/dist/query-parser/index.d.mts

@@ -0,0 +1,4 @@
+import { BracketOperator, ParsedPopulate, ParsedQuery, ParsedSelect, ParsedSort, ParsedSortDirection, QueryParserInput, QueryParserOptions } from "./types.mjs";
+import { coerceList, coerceValue } from "./coerce.mjs";
+import { parseUrl } from "./parse-url.mjs";
+export { type BracketOperator, type ParsedPopulate, type ParsedQuery, type ParsedSelect, type ParsedSort, type ParsedSortDirection, type QueryParserInput, type QueryParserOptions, coerceList, coerceValue, parseUrl };

package/dist/query-parser/index.mjs

@@ -0,0 +1,3 @@
+import { coerceList, coerceValue } from "./coerce.mjs";
+import { parseUrl } from "./parse-url.mjs";
+export { coerceList, coerceValue, parseUrl };

package/dist/query-parser/parse-url.d.mts

@@ -0,0 +1,7 @@
+import { ParsedQuery, QueryParserInput, QueryParserOptions } from "./types.mjs";
+
+//#region src/query-parser/parse-url.d.ts
+/** Parse URL search params into a driver-agnostic ParsedQuery. */
+declare function parseUrl(input: QueryParserInput, options?: QueryParserOptions): ParsedQuery;
+//#endregion
+export { parseUrl };

package/dist/query-parser/parse-url.mjs

@@ -0,0 +1,224 @@
+import { TRUE, and, between, contains, endsWith, eq, gt, gte, iEq, in_, isNotNull, isNull, like, lt, lte, ne, nin, regex, startsWith } from "../filter/builders.mjs";
+import { coerceList, coerceValue } from "./coerce.mjs";
+//#region src/query-parser/parse-url.ts
+const DEFAULT_LIMIT = 20;
+const DEFAULT_MAX_LIMIT = 200;
+const DEFAULT_MAX_DEPTH = 10;
+const DEFAULT_MAX_REGEX = 500;
+const DEFAULT_MAX_SEARCH = 200;
+/** Reserved top-level URL keys the parser handles specially. */
+const RESERVED_KEYS = new Set([
+	"page",
+	"limit",
+	"after",
+	"sort",
+	"select",
+	"populate",
+	"search"
+]);
+const ALL_OPERATORS = new Set([
+	"eq",
+	"ne",
+	"gt",
+	"gte",
+	"lt",
+	"lte",
+	"in",
+	"nin",
+	"like",
+	"contains",
+	"startsWith",
+	"endsWith",
+	"ieq",
+	"regex",
+	"between",
+	"exists"
+]);
+/** Parse URL search params into a driver-agnostic ParsedQuery. */
+function parseUrl(input, options = {}) {
+	const params = normalize(input);
+	const maxLimit = options.maxLimit ?? DEFAULT_MAX_LIMIT;
+	const allowedOps = options.allowedOperators ? new Set(options.allowedOperators) : ALL_OPERATORS;
+	const rawPage = params.get("page");
+	const rawLimit = params.get("limit");
+	const after = params.get("after") ?? void 0;
+	const limit = clampLimit(rawLimit, options.defaultLimit ?? DEFAULT_LIMIT, maxLimit);
+	const page = rawPage !== null && rawPage !== void 0 ? toPositiveInt(rawPage) : void 0;
+	const sort = parseSort(params.get("sort"), options.allowedSortFields);
+	const select = parseSelect(params.get("select"));
+	const populate = parsePopulate(params);
+	const rawSearch = params.get("search");
+	const searchCap = options.maxSearchLength ?? DEFAULT_MAX_SEARCH;
+	const search = rawSearch !== null && rawSearch !== void 0 && rawSearch.length > 0 ? rawSearch.slice(0, searchCap) : void 0;
+	const result = {
+		filter: parseFilters(params, {
+			allowedFields: options.allowedFilterFields,
+			allowedOps,
+			fieldTypes: options.fieldTypes,
+			maxDepth: options.maxFilterDepth ?? DEFAULT_MAX_DEPTH,
+			maxRegex: options.maxRegexLength ?? DEFAULT_MAX_REGEX
+		}),
+		limit
+	};
+	if (sort) result.sort = sort;
+	if (select) result.select = select;
+	if (populate.length > 0) result.populate = populate;
+	if (page !== void 0) result.page = page;
+	if (after !== void 0) result.after = after;
+	if (search !== void 0) result.search = search;
+	return result;
+}
+function normalize(input) {
+	if (input instanceof URLSearchParams) return {
+		get: (k) => input.get(k),
+		entries: () => input.entries(),
+		has: (k) => input.has(k)
+	};
+	if (Symbol.iterator in input) {
+		const usp = new URLSearchParams();
+		for (const [k, v] of input) usp.append(k, v);
+		return {
+			get: (k) => usp.get(k),
+			entries: () => usp.entries(),
+			has: (k) => usp.has(k)
+		};
+	}
+	const record = input;
+	const usp = new URLSearchParams();
+	for (const [k, v] of Object.entries(record)) {
+		if (v === void 0) continue;
+		if (Array.isArray(v)) for (const item of v) usp.append(k, item);
+		else usp.append(k, v);
+	}
+	return {
+		get: (k) => usp.get(k),
+		entries: () => usp.entries(),
+		has: (k) => usp.has(k)
+	};
+}
+function clampLimit(raw, fallback, max) {
+	if (raw === null || raw === void 0) return fallback;
+	const n = Number(raw);
+	if (!Number.isFinite(n) || n < 1) return fallback;
+	return Math.min(Math.floor(n), max);
+}
+function toPositiveInt(raw) {
+	const n = Number(raw);
+	if (!Number.isFinite(n) || n < 1) return void 0;
+	return Math.floor(n);
+}
+function parseSort(raw, allowed) {
+	if (!raw) return void 0;
+	const spec = {};
+	for (const piece of raw.split(",").map((s) => s.trim()).filter(Boolean)) {
+		const desc = piece.startsWith("-");
+		const field = desc ? piece.slice(1) : piece.startsWith("+") ? piece.slice(1) : piece;
+		if (allowed && !allowed.includes(field)) continue;
+		spec[field] = desc ? -1 : 1;
+	}
+	return Object.keys(spec).length > 0 ? spec : void 0;
+}
+function parseSelect(raw) {
+	if (!raw) return void 0;
+	const spec = {};
+	for (const piece of raw.split(",").map((s) => s.trim()).filter(Boolean)) if (piece.startsWith("-")) spec[piece.slice(1)] = 0;
+	else spec[piece] = 1;
+	return Object.keys(spec).length > 0 ? spec : void 0;
+}
+/**
+* Parse `populate[field][select]=...&populate[field][match][other]=...` into
+* an array of ParsedPopulate specs. Flat iteration keeps the parser simple;
+* nested populate (`populate[author][populate][org][select]=...`) is supported
+* one level deep.
+*/
+function parsePopulate(params) {
+	const byField = /* @__PURE__ */ new Map();
+	for (const [key, value] of params.entries()) {
+		if (!key.startsWith("populate[")) continue;
+		const match = /^populate\[([^\]]+)\](?:\[([^\]]+)\](?:\[([^\]]+)\])?)?$/.exec(key);
+		if (!match) continue;
+		const [, field, sub, subKey] = match;
+		if (!field) continue;
+		const existing = byField.get(field) ?? {};
+		if (!sub) byField.set(field, existing);
+		else if (sub === "select") {
+			existing.select = value;
+			byField.set(field, existing);
+		} else if (sub === "match" && subKey) {
+			existing.match = existing.match ?? {};
+			existing.match[subKey] = value;
+			byField.set(field, existing);
+		}
+	}
+	const out = [];
+	for (const [path, spec] of byField) {
+		const entry = { path };
+		if (spec.select !== void 0) entry.select = spec.select;
+		if (spec.match) entry.match = spec.match;
+		out.push(entry);
+	}
+	return out;
+}
+function parseFilters(params, ctx) {
+	const leaves = [];
+	const fieldGroups = /* @__PURE__ */ new Map();
+	for (const [key, rawValue] of params.entries()) {
+		if (RESERVED_KEYS.has(key) || key.startsWith("populate[")) continue;
+		const bracket = /^([^[\]]+)\[([^\]]+)\]$/.exec(key);
+		let field;
+		let op;
+		if (bracket) {
+			const [, f, o] = bracket;
+			if (!f || !o) continue;
+			field = f;
+			op = o;
+		} else {
+			field = key;
+			op = "eq";
+		}
+		if (ctx.allowedFields && !ctx.allowedFields.includes(field)) continue;
+		if (!ctx.allowedOps.has(op)) continue;
+		const fieldType = ctx.fieldTypes?.[field];
+		const leaf = buildLeaf(field, op, rawValue, fieldType, ctx);
+		if (!leaf) continue;
+		const bucket = fieldGroups.get(field) ?? [];
+		bucket.push(leaf);
+		fieldGroups.set(field, bucket);
+	}
+	for (const [, nodes] of fieldGroups) if (nodes.length === 1) leaves.push(nodes[0]);
+	else leaves.push(and(...nodes));
+	if (leaves.length === 0) return TRUE;
+	if (leaves.length === 1) return leaves[0];
+	return and(...leaves);
+}
+function buildLeaf(field, op, rawValue, fieldType, ctx) {
+	switch (op) {
+		case "eq": return eq(field, coerceValue(rawValue, fieldType));
+		case "ne": return ne(field, coerceValue(rawValue, fieldType));
+		case "gt": return gt(field, coerceValue(rawValue, fieldType));
+		case "gte": return gte(field, coerceValue(rawValue, fieldType));
+		case "lt": return lt(field, coerceValue(rawValue, fieldType));
+		case "lte": return lte(field, coerceValue(rawValue, fieldType));
+		case "in": return in_(field, coerceList(rawValue, fieldType));
+		case "nin": return nin(field, coerceList(rawValue, fieldType));
+		case "like": return like(field, rawValue);
+		case "contains": return contains(field, rawValue);
+		case "startsWith": return startsWith(field, rawValue);
+		case "endsWith": return endsWith(field, rawValue);
+		case "ieq": return iEq(field, rawValue);
+		case "regex":
+			if (rawValue.length > ctx.maxRegex) return void 0;
+			return regex(field, rawValue);
+		case "between": {
+			const parts = coerceList(rawValue, fieldType);
+			if (parts.length < 2) return void 0;
+			return between(field, parts[0], parts[1]);
+		}
+		case "exists": {
+			const val = rawValue.toLowerCase();
+			return val === "true" || val === "1" ? isNotNull(field) : isNull(field);
+		}
+	}
+}
+//#endregion
+export { parseUrl };