@classytic/repo-core 0.28.0 → 0.30.0

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

@@ -0,0 +1,107 @@
+import { Filter } from "../filter/types.mjs";
+import { QueryFieldType, QueryScalar } from "./coerce.mjs";
+import { QueryGrammarError } from "./errors.mjs";
+import { BracketOperator, ParsedSelect, ParsedSort } from "./types.mjs";
+//#region src/query-parser/grammar.d.ts
+declare const DEFAULT_LIMIT = 20;
+declare const DEFAULT_MAX_LIMIT = 1000;
+declare const DEFAULT_MAX_TEXT_LENGTH = 500;
+declare const DEFAULT_MAX_SEARCH_LENGTH = 200;
+declare const CORE_OPERATORS: readonly ['eq', 'ne', 'gt', 'gte', 'lt', 'lte', 'in', 'nin', 'exists', 'contains', 'startsWith', 'endsWith', 'ieq', 'regex'];
+type CoreOperator = (typeof CORE_OPERATORS)[number];
+declare const URL_OPERATORS: readonly BracketOperator[];
+/** One line per URL operator — the single source for every parser's OpenAPI description. */
+declare const OPERATOR_DESCRIPTIONS: Readonly<Record<BracketOperator, string>>;
+type FilterClause = {
+  readonly field: string;
+  readonly op: 'eq' | 'ne' | 'gt' | 'gte' | 'lt' | 'lte';
+  readonly value: QueryScalar;
+} | {
+  readonly field: string;
+  readonly op: 'in' | 'nin';
+  readonly values: readonly QueryScalar[];
+} | {
+  readonly field: string;
+  readonly op: 'exists';
+  readonly value: boolean;
+} | {
+  readonly field: string;
+  readonly op: 'contains' | 'startsWith' | 'endsWith' | 'ieq';
+  readonly text: string;
+} | {
+  readonly field: string;
+  readonly op: 'regex';
+  readonly pattern: string;
+  readonly flags?: string;
+};
+/** A kit-declared operator (geo, `size`, …), handed back raw for the kit to emit natively. */
+interface ExtensionClause {
+  readonly field: string;
+  readonly op: string;
+  readonly raw: string;
+}
+interface QueryGrammarOptions {
+  /** Filterable fields; any other field is refused. */
+  allowedFilterFields?: readonly string[] | undefined;
+  /** URL operator names permitted (`options` follows `regex`); any other is refused. */
+  allowedOperators?: readonly string[] | undefined;
+  /** Declared field types — exact coercion, and a value that does not fit is refused. */
+  fieldTypes?: Readonly<Record<string, QueryFieldType>> | undefined;
+  /** Operators the kit emits itself; returned as {@link ExtensionClause}s. */
+  extensionOperators?: readonly string[] | undefined;
+  /** Kit-local control params (beyond `STANDARD_RESERVED_PARAMS`) that are not filters. */
+  reservedParams?: readonly string[] | undefined;
+  /** Longest text-operator value or regex pattern. Default {@link DEFAULT_MAX_TEXT_LENGTH}. */
+  maxTextLength?: number | undefined;
+  /**
+   * Drop mode: called with each refusal and the offending entry is skipped instead of thrown.
+   * Dropping a filter WIDENS the read — for trusted compatibility tooling only.
+   */
+  onInvalid?: ((error: QueryGrammarError) => void) | undefined;
+}
+interface FilterReadResult {
+  readonly clauses: FilterClause[];
+  readonly extensions: ExtensionClause[];
+}
+/** A list query as a parser receives it: URL params, qs-nested objects, or flat records. */
+type QueryInput = URLSearchParams | Iterable<readonly [string, string]> | Readonly<Record<string, unknown>>;
+/** Read every filter in `input` as canonical clauses. */
+declare function readFilterClauses(input: QueryInput | null | undefined, options?: QueryGrammarOptions): FilterReadResult;
+/** Canonical clauses → the portable Filter IR (repeated fields AND). */
+declare function clausesToFilter(clauses: readonly FilterClause[]): Filter;
+interface PageRequest {
+  readonly limit: number;
+  /** Offset page (1-based). Absent on a keyset request — `after` wins over `page`. */
+  readonly page?: number;
+  /** Keyset cursor (`after`, or its alias `cursor`). */
+  readonly after?: string;
+}
+interface PageOptions {
+  defaultLimit?: number | undefined;
+  maxLimit?: number | undefined;
+}
+/** `limit`/`page` must be positive integers; a `limit` above the cap is clamped to it. */
+declare function readPageRequest(input: {
+  page?: unknown;
+  limit?: unknown;
+  after?: unknown;
+  cursor?: unknown;
+}, options?: PageOptions): PageRequest;
+/** `sort=-createdAt,name` or qs `sort[createdAt]=desc`. An invalid or disallowed field is refused. */
+declare function readSort(raw: unknown, options?: {
+  allowedSortFields?: readonly string[] | undefined;
+  /** Drop mode: called for each refused token, which is skipped. */
+  onInvalid?: ((error: QueryGrammarError) => void) | undefined;
+}): ParsedSort | undefined;
+/** `select=name,-password`, or a `{ field: 0 | 1 }` projection. An invalid entry is refused. */
+declare function readSelect(raw: unknown, options?: {
+  onInvalid?: ((error: QueryGrammarError) => void) | undefined;
+}): ParsedSelect | undefined;
+/** Free-text search; longer than the cap is refused, never silently truncated. */
+declare function readSearch(raw: unknown, options?: {
+  maxSearchLength?: number | undefined;
+}): string | undefined;
+/** Every input shape → one record: repeated URL keys become arrays, qs objects stay nested. */
+declare function toRecord(input: QueryInput | null | undefined): Record<string, unknown>;
+//#endregion
+export { CORE_OPERATORS, CoreOperator, DEFAULT_LIMIT, DEFAULT_MAX_LIMIT, DEFAULT_MAX_SEARCH_LENGTH, DEFAULT_MAX_TEXT_LENGTH, ExtensionClause, FilterClause, FilterReadResult, OPERATOR_DESCRIPTIONS, PageOptions, PageRequest, QueryGrammarOptions, QueryInput, URL_OPERATORS, clausesToFilter, readFilterClauses, readPageRequest, readSearch, readSelect, readSort, toRecord };

package/dist/query-parser/grammar.mjs

@@ -0,0 +1,462 @@
+import { TRUE, and, anyOf as in_, contains, endsWith, eq, exists, gt, gte, iEq, lt, lte, ne, nin, regex, startsWith } from "../filter/builders.mjs";
+import { QueryGrammarError } from "./errors.mjs";
+import { coerceQueryValue } from "./coerce.mjs";
+import { assessRegex } from "./regex-safety.mjs";
+import { STANDARD_RESERVED_PARAMS } from "./reserved.mjs";
+//#region src/query-parser/grammar.ts
+const DEFAULT_LIMIT = 20;
+const DEFAULT_MAX_LIMIT = 1e3;
+const DEFAULT_MAX_TEXT_LENGTH = 500;
+const DEFAULT_MAX_SEARCH_LENGTH = 200;
+const MAX_KEY_LENGTH = 256;
+/** Deepest qs nesting a filter can have: `filter[field][op]` plus a repeated value. */
+const MAX_NESTING = 4;
+const CORE_OPERATORS = [
+	"eq",
+	"ne",
+	"gt",
+	"gte",
+	"lt",
+	"lte",
+	"in",
+	"nin",
+	"exists",
+	"contains",
+	"startsWith",
+	"endsWith",
+	"ieq",
+	"regex"
+];
+/**
+* URL operator names the grammar accepts: the core set plus its sugar. Keyed by `BracketOperator`
+* so the public type and the runtime list cannot drift — a missing or extra name is a compile error.
+*/
+const URL_OPERATOR_SET = {
+	...Object.fromEntries(CORE_OPERATORS.map((op) => [op, true])),
+	like: true,
+	between: true,
+	options: true
+};
+const URL_OPERATORS = Object.keys(URL_OPERATOR_SET);
+/** One line per URL operator — the single source for every parser's OpenAPI description. */
+const OPERATOR_DESCRIPTIONS = {
+	eq: "Equal (the default for `field=value`; repeated keys mean `in`)",
+	ne: "Not equal — null and missing values never match",
+	gt: "Greater than",
+	gte: "Greater than or equal",
+	lt: "Less than",
+	lte: "Less than or equal",
+	in: "One of a comma-separated list",
+	nin: "None of a comma-separated list — null and missing values never match",
+	exists: "Has a non-null value (true) / is null or missing (false)",
+	contains: "Contains the text (literal, case-insensitive)",
+	like: "Alias of contains",
+	startsWith: "Starts with the text (literal, case-insensitive)",
+	endsWith: "Ends with the text (literal, case-insensitive)",
+	ieq: "Equals the text, ignoring case",
+	regex: "Regular expression (case-sensitive; checked for ReDoS)",
+	options: "Flags for the regex on the same field (i, m, s, x)",
+	between: "Inclusive range `from,to` (either side may be empty)"
+};
+const FIELD = "[A-Za-z_][A-Za-z0-9_-]*(?:\\.[A-Za-z0-9_-]+)*";
+const FIELD_RE = new RegExp(`^${FIELD}$`);
+const FILTER_KEY_RE = new RegExp(`^(${FIELD})(?:\\[([A-Za-z]+)\\])?$`);
+const SORT_TOKEN_RE = new RegExp(`^([+-]?)(${FIELD})$`);
+const SELECT_TOKEN_RE = new RegExp(`^(-?)(${FIELD})$`);
+const REGEX_FLAGS_RE = /^[imsx]+$/;
+/** Read every filter in `input` as canonical clauses. */
+function readFilterClauses(input, options = {}) {
+	const reserved = /* @__PURE__ */ new Set([...STANDARD_RESERVED_PARAMS, ...options.reservedParams ?? []]);
+	const extensions = new Set(options.extensionOperators ?? []);
+	const allowedOps = options.allowedOperators ? new Set(options.allowedOperators) : void 0;
+	const allowedFields = options.allowedFilterFields ? new Set(options.allowedFilterFields) : void 0;
+	const maxText = options.maxTextLength ?? 500;
+	const clauses = [];
+	const extensionClauses = [];
+	const regexFlags = /* @__PURE__ */ new Map();
+	const guard = (fn) => {
+		try {
+			fn();
+		} catch (error) {
+			if (!(error instanceof QueryGrammarError) || !options.onInvalid) throw error;
+			options.onInvalid(error);
+		}
+	};
+	for (const [key, value] of filterEntries(toRecord(input), reserved)) guard(() => {
+		const raw = toRaw(key, value);
+		if (raw === "") return;
+		const { field, op, explicit } = parseFilterKey(key, extensions);
+		if (allowedFields && !allowedFields.has(field)) throw new QueryGrammarError(key, `"${field}" is not a filterable field`, "policy");
+		const gate = op === "options" ? "regex" : op;
+		if (explicit && allowedOps && !allowedOps.has(gate)) throw new QueryGrammarError(key, `operator "${op}" is not allowed`, "policy");
+		if (extensions.has(op)) {
+			extensionClauses.push({
+				field,
+				op,
+				raw
+			});
+			return;
+		}
+		if (op === "options") {
+			if (!REGEX_FLAGS_RE.test(raw)) throw new QueryGrammarError(key, "flags must be from i, m, s, x");
+			regexFlags.set(field, raw);
+			return;
+		}
+		const fieldType = options.fieldTypes?.[field];
+		clauses.push(...toClauses(key, field, op, raw, fieldType, maxText));
+	});
+	for (const [field, flags] of regexFlags) guard(() => {
+		const index = clauses.findIndex((c) => c.field === field && c.op === "regex");
+		if (index < 0) throw new QueryGrammarError(`${field}[options]`, "needs a regex on the same field");
+		const clause = clauses[index];
+		clauses[index] = {
+			...clause,
+			flags
+		};
+	});
+	return {
+		clauses: collapseRepeats(clauses),
+		extensions: extensionClauses
+	};
+}
+/** Canonical clauses → the portable Filter IR (repeated fields AND). */
+function clausesToFilter(clauses) {
+	const nodes = clauses.map(clauseToFilter);
+	if (nodes.length === 0) return TRUE;
+	return nodes.length === 1 ? nodes[0] : and(...nodes);
+}
+function clauseToFilter(clause) {
+	switch (clause.op) {
+		case "eq": return eq(clause.field, clause.value);
+		case "ne": return ne(clause.field, clause.value);
+		case "gt": return gt(clause.field, clause.value);
+		case "gte": return gte(clause.field, clause.value);
+		case "lt": return lt(clause.field, clause.value);
+		case "lte": return lte(clause.field, clause.value);
+		case "in": return in_(clause.field, clause.values);
+		case "nin": return nin(clause.field, clause.values);
+		case "exists": return exists(clause.field, clause.value);
+		case "contains": return contains(clause.field, clause.text);
+		case "startsWith": return startsWith(clause.field, clause.text);
+		case "endsWith": return endsWith(clause.field, clause.text);
+		case "ieq": return iEq(clause.field, clause.text);
+		case "regex": return regex(clause.field, clause.pattern, clause.flags);
+	}
+}
+function parseFilterKey(key, extensions) {
+	if (key.length > MAX_KEY_LENGTH) throw new QueryGrammarError(key.slice(0, 64), `key longer than ${MAX_KEY_LENGTH} characters`, "syntax");
+	const match = FILTER_KEY_RE.exec(key);
+	if (!match) {
+		if (key.includes("$")) throw new QueryGrammarError(key, "`$` operators are not part of the query grammar", "syntax");
+		const nested = /^([^[\]]+)\[([^[\]]+)\]\[/.exec(key);
+		if (nested) throw new QueryGrammarError(key, `a nested field is a dot path: ${nested[1]}.${nested[2]}`, "syntax");
+		throw new QueryGrammarError(key, "not a valid filter key (`field` or `field[operator]`)", "syntax");
+	}
+	const field = match[1];
+	const op = match[2] ?? "eq";
+	if (!(op in URL_OPERATOR_SET) && !extensions.has(op)) throw new QueryGrammarError(key, `unknown operator "${op}" (supported: ${[...URL_OPERATORS, ...extensions].join(", ")}); a nested field is a dot path: ${field}.${op}`, "syntax");
+	return {
+		field,
+		op,
+		explicit: match[2] !== void 0
+	};
+}
+function toClauses(param, field, op, raw, fieldType, maxText) {
+	switch (op) {
+		case "eq":
+		case "ne": return [{
+			field,
+			op,
+			value: coerceQueryValue(raw, {
+				fieldType,
+				param
+			})
+		}];
+		case "gt":
+		case "gte":
+		case "lt":
+		case "lte": return [{
+			field,
+			op,
+			value: rangeValue(raw, fieldType, param)
+		}];
+		case "in":
+		case "nin": {
+			const values = splitList(raw).map((item) => coerceQueryValue(item, {
+				fieldType,
+				param
+			}));
+			return values.length > 0 ? [{
+				field,
+				op,
+				values
+			}] : [];
+		}
+		case "between": {
+			const parts = raw.split(",").map((part) => part.trim());
+			if (parts.length !== 2 || parts[0] === "" && parts[1] === "") throw new QueryGrammarError(param, "between takes `from,to` (one side may be empty)");
+			const [from, to] = parts;
+			const out = [];
+			if (from !== "") out.push({
+				field,
+				op: "gte",
+				value: rangeValue(from, fieldType, param)
+			});
+			if (to !== "") out.push({
+				field,
+				op: "lte",
+				value: rangeValue(to, fieldType, param)
+			});
+			return out;
+		}
+		case "exists": {
+			const lower = raw.toLowerCase();
+			if (lower === "true" || lower === "1") return [{
+				field,
+				op: "exists",
+				value: true
+			}];
+			if (lower === "false" || lower === "0") return [{
+				field,
+				op: "exists",
+				value: false
+			}];
+			throw new QueryGrammarError(param, "exists takes true or false");
+		}
+		case "like":
+		case "contains":
+		case "startsWith":
+		case "endsWith":
+		case "ieq":
+			if (raw.length > maxText) throw new QueryGrammarError(param, `text longer than ${maxText} characters`);
+			return [{
+				field,
+				op: op === "like" ? "contains" : op,
+				text: raw
+			}];
+		case "regex": {
+			const risk = assessRegex(raw, { maxLength: maxText });
+			if (!risk.safe) throw new QueryGrammarError(param, `regex refused (${risk.reason})`);
+			return [{
+				field,
+				op: "regex",
+				pattern: raw
+			}];
+		}
+	}
+	throw new QueryGrammarError(param, `unknown operator "${op}"`, "syntax");
+}
+function rangeValue(raw, fieldType, param) {
+	const value = coerceQueryValue(raw, {
+		fieldType,
+		range: true,
+		param
+	});
+	if (value === null) throw new QueryGrammarError(param, "a range bound cannot be null");
+	return value;
+}
+function splitList(raw) {
+	return raw.split(",").map((item) => item.trim()).filter((item) => item !== "");
+}
+/**
+* Membership on one field is a UNION, never an AND of alternatives: `status=a&status=b`,
+* `status[in]=a&status[in]=b` and `status=a&status[in]=b,c` are one `in`; the `ne`/`nin`
+* family likewise becomes one `nin`. Ranges and text clauses on a field still AND.
+*/
+function collapseRepeats(clauses) {
+	const family = (c) => c.op === "eq" || c.op === "in" ? "in" : c.op === "ne" || c.op === "nin" ? "nin" : void 0;
+	const valuesOf = (c) => c.op === "in" || c.op === "nin" ? c.values : [c.value];
+	const key = (c) => `${family(c)}:${c.field}`;
+	const groups = /* @__PURE__ */ new Map();
+	for (const clause of clauses) {
+		if (family(clause) === void 0) continue;
+		groups.set(key(clause), [...groups.get(key(clause)) ?? [], clause]);
+	}
+	const out = [];
+	const emitted = /* @__PURE__ */ new Set();
+	for (const clause of clauses) {
+		const group = family(clause) === void 0 ? void 0 : groups.get(key(clause));
+		if (group === void 0 || group.length === 1) out.push(clause);
+		else if (!emitted.has(key(clause))) {
+			emitted.add(key(clause));
+			const values = [...new Set(group.flatMap(valuesOf))];
+			out.push({
+				field: clause.field,
+				op: family(clause),
+				values
+			});
+		}
+	}
+	return out;
+}
+/** `limit`/`page` must be positive integers; a `limit` above the cap is clamped to it. */
+function readPageRequest(input, options = {}) {
+	const maxLimit = options.maxLimit ?? 1e3;
+	const requested = positiveInt(input.limit, "limit");
+	const limit = Math.min(requested ?? options.defaultLimit ?? 20, maxLimit);
+	const after = cursorValue(input.after ?? input.cursor);
+	if (after !== void 0) return {
+		limit,
+		after
+	};
+	const page = positiveInt(input.page, "page");
+	return page === void 0 ? { limit } : {
+		limit,
+		page
+	};
+}
+/** `sort=-createdAt,name` or qs `sort[createdAt]=desc`. An invalid or disallowed field is refused. */
+function readSort(raw, options = {}) {
+	if (raw === void 0 || raw === null || raw === "") return void 0;
+	const allowed = options.allowedSortFields ? new Set(options.allowedSortFields) : void 0;
+	const sort = {};
+	const refuse = (param, reason, kind = "syntax") => {
+		const error = new QueryGrammarError(param, reason, kind);
+		if (!options.onInvalid) throw error;
+		options.onInvalid(error);
+	};
+	const add = (field, direction) => {
+		if (allowed && !allowed.has(field)) refuse("sort", `"${field}" is not a sortable field`, "policy");
+		else sort[field] = direction;
+	};
+	if (isPlainObject(raw)) for (const [field, value] of Object.entries(raw)) {
+		const dir = String(value).toLowerCase();
+		if (!FIELD_RE.test(field)) refuse("sort", `"${field}" is not a field`);
+		else if (dir === "asc" || dir === "1") add(field, 1);
+		else if (dir === "desc" || dir === "-1") add(field, -1);
+		else refuse(`sort[${field}]`, "direction is asc or desc", "value");
+	}
+	else {
+		const tokens = (Array.isArray(raw) ? raw : [raw]).flatMap(splitTokens);
+		for (const token of tokens.map((t) => t.trim()).filter((t) => t !== "")) {
+			const match = SORT_TOKEN_RE.exec(token);
+			if (!match) refuse("sort", `"${token}" is not a field`);
+			else add(match[2], match[1] === "-" ? -1 : 1);
+		}
+	}
+	return Object.keys(sort).length > 0 ? sort : void 0;
+}
+/** `select=name,-password`, or a `{ field: 0 | 1 }` projection. An invalid entry is refused. */
+function readSelect(raw, options = {}) {
+	if (raw === void 0 || raw === null || raw === "") return void 0;
+	const select = {};
+	const refuse = (param, reason, kind) => {
+		const error = new QueryGrammarError(param, reason, kind);
+		if (!options.onInvalid) throw error;
+		options.onInvalid(error);
+	};
+	if (isPlainObject(raw)) for (const [field, flag] of Object.entries(raw)) {
+		const value = String(flag);
+		if (!FIELD_RE.test(field)) refuse("select", `"${field}" is not a field`, "syntax");
+		else if (value !== "0" && value !== "1") refuse(`select[${field}]`, "a projection flag is 0 or 1", "value");
+		else select[field] = value === "1" ? 1 : 0;
+	}
+	else {
+		const tokens = (Array.isArray(raw) ? raw : [raw]).flatMap(splitTokens);
+		for (const token of tokens.map((t) => t.trim()).filter((t) => t !== "")) {
+			const match = SELECT_TOKEN_RE.exec(token);
+			if (!match) refuse("select", `"${token}" is not a field`, "syntax");
+			else select[match[2]] = match[1] === "-" ? 0 : 1;
+		}
+	}
+	return Object.keys(select).length > 0 ? select : void 0;
+}
+/** Free-text search; longer than the cap is refused, never silently truncated. */
+function readSearch(raw, options = {}) {
+	if (raw === void 0 || raw === null) return void 0;
+	const search = String(raw).trim();
+	if (search === "") return void 0;
+	const max = options.maxSearchLength ?? 200;
+	if (search.length > max) throw new QueryGrammarError("search", `longer than ${max} characters`);
+	return search;
+}
+/** Every input shape → one record: repeated URL keys become arrays, qs objects stay nested. */
+function toRecord(input) {
+	if (input === null || input === void 0) return {};
+	if (input instanceof URLSearchParams || isEntryIterable(input)) {
+		const record = {};
+		const entries = input instanceof URLSearchParams ? input.entries() : input;
+		for (const [key, value] of entries) {
+			const prev = record[key];
+			record[key] = prev === void 0 ? value : Array.isArray(prev) ? [...prev, value] : [prev, value];
+		}
+		return record;
+	}
+	return input;
+}
+function isEntryIterable(input) {
+	return typeof input === "object" && input !== null && !(input instanceof URLSearchParams) && Symbol.iterator in input;
+}
+/** Flat `[bracketKey, scalar]` pairs for every non-reserved param, unwrapping the `filter` envelope. */
+function* filterEntries(record, reserved) {
+	for (const [key, value] of Object.entries(record)) {
+		const top = key.split("[", 1)[0];
+		if (top === "filter") {
+			if (key === "filter") {
+				if (!isPlainObject(value)) {
+					yield ["filter", new Refusal("the envelope is filter[field]=value")];
+					continue;
+				}
+				for (const [inner, innerValue] of Object.entries(value)) yield* flatten(inner, innerValue, 1);
+			} else yield* flatten(key.replace(/^filter\[([^\]]*)\]/, "$1"), value, 1);
+			continue;
+		}
+		if (reserved.has(top)) continue;
+		yield* flatten(key, value, 0);
+	}
+}
+/** Refuses input nested past {@link MAX_NESTING} BEFORE recursing into it. */
+function* flatten(path, value, depth) {
+	if (value === void 0) return;
+	if (depth > MAX_NESTING) {
+		yield [path.slice(0, 64), new Refusal("nested too deeply")];
+		return;
+	}
+	if (Array.isArray(value)) {
+		for (const item of value) yield* flatten(path, item, depth + 1);
+		return;
+	}
+	if (isPlainObject(value)) {
+		for (const [key, inner] of Object.entries(value)) yield* flatten(`${path}[${key}]`, inner, depth + 1);
+		return;
+	}
+	yield [path, value];
+}
+/**
+* A refusal found while flattening, yielded in place of a value so the caller's `onInvalid` policy
+* applies to it like any other entry — a generator that threw would end the whole read.
+*/
+var Refusal = class {
+	reason;
+	constructor(reason) {
+		this.reason = reason;
+	}
+};
+/** Sort/select tokens: comma- or whitespace-separated (`a,-b` or Mongoose's `a -b`). */
+function splitTokens(part) {
+	return String(part).split(/[\s,]+/);
+}
+function toRaw(key, value) {
+	if (value instanceof Refusal) throw new QueryGrammarError(key, value.reason, "syntax");
+	if (value === null) return "null";
+	if (value instanceof Date) return value.toISOString();
+	if (typeof value === "string") return value;
+	if (typeof value === "number" || typeof value === "boolean") return String(value);
+	throw new QueryGrammarError(key, "a filter value is a string", "syntax");
+}
+function isPlainObject(value) {
+	return typeof value === "object" && value !== null && Object.getPrototypeOf(value) === Object.prototype;
+}
+function positiveInt(raw, param) {
+	if (raw === void 0 || raw === null || raw === "") return void 0;
+	const value = typeof raw === "number" ? raw : /^\d+$/.test(String(raw).trim()) ? Number(String(raw).trim()) : NaN;
+	if (!Number.isSafeInteger(value) || value < 1) throw new QueryGrammarError(param, `"${String(raw)}" is not a positive integer`);
+	return value;
+}
+function cursorValue(raw) {
+	if (raw === void 0 || raw === null) return void 0;
+	const value = String(raw).trim();
+	return value === "" ? void 0 : value;
+}
+//#endregion
+export { CORE_OPERATORS, DEFAULT_LIMIT, DEFAULT_MAX_LIMIT, DEFAULT_MAX_SEARCH_LENGTH, DEFAULT_MAX_TEXT_LENGTH, OPERATOR_DESCRIPTIONS, URL_OPERATORS, clausesToFilter, readFilterClauses, readPageRequest, readSearch, readSelect, readSort, toRecord };

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

@@ -1,5 +1,8 @@
+import { CoerceOptions, QueryFieldType, QueryScalar, coerceQueryValue } from "./coerce.mjs";
+import { INVALID_QUERY_INPUT, QueryErrorKind, QueryGrammarError, isQueryGrammarError } from "./errors.mjs";
 import { BracketOperator, ParsedPopulate, ParsedQuery, ParsedSelect, ParsedSort, ParsedSortDirection, QueryParserInput, QueryParserOptions } from "./types.mjs";
-import { coerceList, coerceValue } from "./coerce.mjs";
+import { CORE_OPERATORS, CoreOperator, DEFAULT_LIMIT, DEFAULT_MAX_LIMIT, DEFAULT_MAX_SEARCH_LENGTH, DEFAULT_MAX_TEXT_LENGTH, ExtensionClause, FilterClause, FilterReadResult, OPERATOR_DESCRIPTIONS, PageOptions, PageRequest, QueryGrammarOptions, QueryInput, URL_OPERATORS, clausesToFilter, readFilterClauses, readPageRequest, readSearch, readSelect, readSort, toRecord } from "./grammar.mjs";
 import { parseUrl } from "./parse-url.mjs";
+import { MAX_UNBOUNDED_QUANTIFIERS, RegexRisk, assessRegex, escapeRegex } from "./regex-safety.mjs";
 import { STANDARD_RESERVED_PARAMS, isControlParam } from "./reserved.mjs";
-export { type BracketOperator, type ParsedPopulate, type ParsedQuery, type ParsedSelect, type ParsedSort, type ParsedSortDirection, type QueryParserInput, type QueryParserOptions, STANDARD_RESERVED_PARAMS, coerceList, coerceValue, isControlParam, parseUrl };
+export { type BracketOperator, CORE_OPERATORS, type CoerceOptions, type CoreOperator, DEFAULT_LIMIT, DEFAULT_MAX_LIMIT, DEFAULT_MAX_SEARCH_LENGTH, DEFAULT_MAX_TEXT_LENGTH, type ExtensionClause, type FilterClause, type FilterReadResult, INVALID_QUERY_INPUT, MAX_UNBOUNDED_QUANTIFIERS, OPERATOR_DESCRIPTIONS, type PageOptions, type PageRequest, type ParsedPopulate, type ParsedQuery, type ParsedSelect, type ParsedSort, type ParsedSortDirection, type QueryErrorKind, type QueryFieldType, QueryGrammarError, type QueryGrammarOptions, type QueryInput, type QueryParserInput, type QueryParserOptions, type QueryScalar, type RegexRisk, STANDARD_RESERVED_PARAMS, URL_OPERATORS, assessRegex, clausesToFilter, coerceQueryValue, escapeRegex, isControlParam, isQueryGrammarError, parseUrl, readFilterClauses, readPageRequest, readSearch, readSelect, readSort, toRecord };

package/dist/query-parser/index.mjs

@@ -1,4 +1,7 @@
-import { coerceList, coerceValue } from "./coerce.mjs";
+import { INVALID_QUERY_INPUT, QueryGrammarError, isQueryGrammarError } from "./errors.mjs";
+import { coerceQueryValue } from "./coerce.mjs";
+import { MAX_UNBOUNDED_QUANTIFIERS, assessRegex, escapeRegex } from "./regex-safety.mjs";
 import { STANDARD_RESERVED_PARAMS, isControlParam } from "./reserved.mjs";
+import { CORE_OPERATORS, DEFAULT_LIMIT, DEFAULT_MAX_LIMIT, DEFAULT_MAX_SEARCH_LENGTH, DEFAULT_MAX_TEXT_LENGTH, OPERATOR_DESCRIPTIONS, URL_OPERATORS, clausesToFilter, readFilterClauses, readPageRequest, readSearch, readSelect, readSort, toRecord } from "./grammar.mjs";
 import { parseUrl } from "./parse-url.mjs";
-export { STANDARD_RESERVED_PARAMS, coerceList, coerceValue, isControlParam, parseUrl };
+export { CORE_OPERATORS, DEFAULT_LIMIT, DEFAULT_MAX_LIMIT, DEFAULT_MAX_SEARCH_LENGTH, DEFAULT_MAX_TEXT_LENGTH, INVALID_QUERY_INPUT, MAX_UNBOUNDED_QUANTIFIERS, OPERATOR_DESCRIPTIONS, QueryGrammarError, STANDARD_RESERVED_PARAMS, URL_OPERATORS, assessRegex, clausesToFilter, coerceQueryValue, escapeRegex, isControlParam, isQueryGrammarError, parseUrl, readFilterClauses, readPageRequest, readSearch, readSelect, readSort, toRecord };

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

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