@classytic/repo-core 0.1.0

package/dist/filter/builders.d.mts

@@ -0,0 +1,60 @@
+import { Filter, FilterEq, FilterExists, FilterFalse, FilterGt, FilterGte, FilterIn, FilterLike, FilterLt, FilterLte, FilterNe, FilterNin, FilterRaw, FilterRegex, FilterTrue } from "./types.mjs";
+
+//#region src/filter/builders.d.ts
+declare const eq: (field: string, value: unknown) => FilterEq;
+declare const ne: (field: string, value: unknown) => FilterNe;
+declare const gt: (field: string, value: unknown) => FilterGt;
+declare const gte: (field: string, value: unknown) => FilterGte;
+declare const lt: (field: string, value: unknown) => FilterLt;
+declare const lte: (field: string, value: unknown) => FilterLte;
+/** Membership (`$in` / `IN (...)`). Aliased as `anyOf` for readability. */
+declare const in_: (field: string, values: readonly unknown[]) => FilterIn;
+/** Non-membership (`$nin` / `NOT IN (...)`). Aliased as `noneOf`. */
+declare const nin: (field: string, values: readonly unknown[]) => FilterNin;
+declare const like: (field: string, pattern: string, caseSensitivity?: "sensitive" | "insensitive") => FilterLike;
+declare const regex: (field: string, pattern: string, flags?: string) => FilterRegex;
+declare const exists: (field: string, present?: boolean) => FilterExists;
+/**
+ * Conjunction. Normalizes trivially: an empty `and` returns `TRUE`, a
+ * single-child `and` is flattened to the child. Plugins that progressively
+ * build a filter (`let f = TRUE; if (...) f = and(f, eq(...))`) land in
+ * the expected shape without manual tree surgery.
+ */
+declare function and(...children: Filter[]): Filter;
+/** Disjunction. Boolean algebra duals of `and`: TRUE absorbs, FALSE is identity. */
+declare function or(...children: Filter[]): Filter;
+/** Negation. Double-negation is eliminated (`not(not(x)) === x`). */
+declare function not(child: Filter): Filter;
+/** Matches every document. Identity element for `and`. */
+declare const TRUE: FilterTrue;
+/** Matches no document. Identity element for `or`. */
+declare const FALSE: FilterFalse;
+/** Inclusive range: `lo <= field <= hi`. Desugars to `and(gte, lte)`. */
+declare function between(field: string, lo: unknown, hi: unknown): Filter;
+/** Case-insensitive by default. Escapes `%` and `_` in `prefix` so they match literally. */
+declare function startsWith(field: string, prefix: string, caseSensitivity?: 'sensitive' | 'insensitive'): FilterLike;
+declare function endsWith(field: string, suffix: string, caseSensitivity?: 'sensitive' | 'insensitive'): FilterLike;
+/** Substring match. Case-insensitive by default. */
+declare function contains(field: string, substring: string, caseSensitivity?: 'sensitive' | 'insensitive'): FilterLike;
+/**
+ * Case-insensitive equality. Desugars to a case-insensitive `like` with
+ * the value's SQL wildcards escaped — kits compile it the same as an
+ * equality check against `lower(field) = lower(?)`.
+ */
+declare function iEq(field: string, value: string): FilterLike;
+/** Shorthand for `exists(field, false)`. Reads better in plugin code. */
+declare function isNull(field: string): FilterExists;
+/** Shorthand for `exists(field, true)`. */
+declare function isNotNull(field: string): FilterExists;
+/**
+ * Embed a driver-native fragment verbatim. Use for features the IR
+ * doesn't express: pgvector similarity, SQLite JSON1 path access,
+ * Mongo `$geoWithin`, etc.
+ *
+ * `matchFilter` (the in-memory evaluator) returns `false` for raw nodes
+ * because evaluating arbitrary SQL in JS isn't possible — make sure
+ * predicates used in client-side filtering don't rely on `raw`.
+ */
+declare function raw(sql: string, params?: readonly unknown[]): FilterRaw;
+//#endregion
+export { FALSE, TRUE, and, between, contains, endsWith, eq, exists, gt, gte, iEq, in_, isNotNull, isNull, like, lt, lte, ne, nin, not, or, raw, regex, startsWith };

package/dist/filter/builders.mjs

@@ -0,0 +1,172 @@
+//#region src/filter/builders.ts
+const eq = (field, value) => Object.freeze({
+	op: "eq",
+	field,
+	value
+});
+const ne = (field, value) => Object.freeze({
+	op: "ne",
+	field,
+	value
+});
+const gt = (field, value) => Object.freeze({
+	op: "gt",
+	field,
+	value
+});
+const gte = (field, value) => Object.freeze({
+	op: "gte",
+	field,
+	value
+});
+const lt = (field, value) => Object.freeze({
+	op: "lt",
+	field,
+	value
+});
+const lte = (field, value) => Object.freeze({
+	op: "lte",
+	field,
+	value
+});
+/** Membership (`$in` / `IN (...)`). Aliased as `anyOf` for readability. */
+const in_ = (field, values) => Object.freeze({
+	op: "in",
+	field,
+	values: Object.freeze([...values])
+});
+/** Non-membership (`$nin` / `NOT IN (...)`). Aliased as `noneOf`. */
+const nin = (field, values) => Object.freeze({
+	op: "nin",
+	field,
+	values: Object.freeze([...values])
+});
+const like = (field, pattern, caseSensitivity = "insensitive") => Object.freeze({
+	op: "like",
+	field,
+	pattern,
+	caseSensitivity
+});
+const regex = (field, pattern, flags) => {
+	const node = {
+		op: "regex",
+		field,
+		pattern,
+		...flags !== void 0 && { flags }
+	};
+	return Object.freeze(node);
+};
+const exists = (field, present = true) => Object.freeze({
+	op: "exists",
+	field,
+	exists: present
+});
+/**
+* Conjunction. Normalizes trivially: an empty `and` returns `TRUE`, a
+* single-child `and` is flattened to the child. Plugins that progressively
+* build a filter (`let f = TRUE; if (...) f = and(f, eq(...))`) land in
+* the expected shape without manual tree surgery.
+*/
+function and(...children) {
+	const flat = [];
+	for (const c of children) if (c.op === "and") flat.push(...c.children);
+	else flat.push(c);
+	const filtered = [];
+	for (const c of flat) {
+		if (c.op === "false") return FALSE;
+		if (c.op === "true") continue;
+		filtered.push(c);
+	}
+	if (filtered.length === 0) return TRUE;
+	if (filtered.length === 1) return filtered[0];
+	const node = {
+		op: "and",
+		children: Object.freeze(filtered)
+	};
+	return Object.freeze(node);
+}
+/** Disjunction. Boolean algebra duals of `and`: TRUE absorbs, FALSE is identity. */
+function or(...children) {
+	const flat = [];
+	for (const c of children) if (c.op === "or") flat.push(...c.children);
+	else flat.push(c);
+	const filtered = [];
+	for (const c of flat) {
+		if (c.op === "true") return TRUE;
+		if (c.op === "false") continue;
+		filtered.push(c);
+	}
+	if (filtered.length === 0) return FALSE;
+	if (filtered.length === 1) return filtered[0];
+	const node = {
+		op: "or",
+		children: Object.freeze(filtered)
+	};
+	return Object.freeze(node);
+}
+/** Negation. Double-negation is eliminated (`not(not(x)) === x`). */
+function not(child) {
+	if (child.op === "not") return child.child;
+	if (child.op === "true") return FALSE;
+	if (child.op === "false") return TRUE;
+	return Object.freeze({
+		op: "not",
+		child
+	});
+}
+/** Matches every document. Identity element for `and`. */
+const TRUE = Object.freeze({ op: "true" });
+/** Matches no document. Identity element for `or`. */
+const FALSE = Object.freeze({ op: "false" });
+/** Inclusive range: `lo <= field <= hi`. Desugars to `and(gte, lte)`. */
+function between(field, lo, hi) {
+	return and(gte(field, lo), lte(field, hi));
+}
+/** Case-insensitive by default. Escapes `%` and `_` in `prefix` so they match literally. */
+function startsWith(field, prefix, caseSensitivity = "insensitive") {
+	return like(field, `${escapeLikePattern(prefix)}%`, caseSensitivity);
+}
+function endsWith(field, suffix, caseSensitivity = "insensitive") {
+	return like(field, `%${escapeLikePattern(suffix)}`, caseSensitivity);
+}
+/** Substring match. Case-insensitive by default. */
+function contains(field, substring, caseSensitivity = "insensitive") {
+	return like(field, `%${escapeLikePattern(substring)}%`, caseSensitivity);
+}
+/**
+* Case-insensitive equality. Desugars to a case-insensitive `like` with
+* the value's SQL wildcards escaped — kits compile it the same as an
+* equality check against `lower(field) = lower(?)`.
+*/
+function iEq(field, value) {
+	return like(field, escapeLikePattern(value), "insensitive");
+}
+/** Shorthand for `exists(field, false)`. Reads better in plugin code. */
+function isNull(field) {
+	return exists(field, false);
+}
+/** Shorthand for `exists(field, true)`. */
+function isNotNull(field) {
+	return exists(field, true);
+}
+/**
+* Embed a driver-native fragment verbatim. Use for features the IR
+* doesn't express: pgvector similarity, SQLite JSON1 path access,
+* Mongo `$geoWithin`, etc.
+*
+* `matchFilter` (the in-memory evaluator) returns `false` for raw nodes
+* because evaluating arbitrary SQL in JS isn't possible — make sure
+* predicates used in client-side filtering don't rely on `raw`.
+*/
+function raw(sql, params = []) {
+	return Object.freeze({
+		op: "raw",
+		sql,
+		params: Object.freeze([...params])
+	});
+}
+function escapeLikePattern(value) {
+	return value.replace(/[%_]/g, (c) => `\\${c}`);
+}
+//#endregion
+export { FALSE, TRUE, and, between, contains, endsWith, eq, exists, gt, gte, iEq, in_, isNotNull, isNull, like, lt, lte, ne, nin, not, or, raw, regex, startsWith };

package/dist/filter/guard.d.mts

@@ -0,0 +1,13 @@
+import { Filter } from "./types.mjs";
+
+//#region src/filter/guard.d.ts
+/**
+ * True when `value` is a Filter IR node.
+ *
+ * Structural check: requires `op` to be a known filter operator string.
+ * Deeper validation (children are themselves filters, field is a string,
+ * values is an array) is left to the compiler — this is the fast-path gate.
+ */
+declare function isFilter(value: unknown): value is Filter;
+//#endregion
+export { isFilter };

package/dist/filter/guard.mjs

@@ -0,0 +1,34 @@
+//#region src/filter/guard.ts
+const FILTER_OPS = new Set([
+	"eq",
+	"ne",
+	"gt",
+	"gte",
+	"lt",
+	"lte",
+	"in",
+	"nin",
+	"like",
+	"regex",
+	"exists",
+	"and",
+	"or",
+	"not",
+	"true",
+	"false",
+	"raw"
+]);
+/**
+* True when `value` is a Filter IR node.
+*
+* Structural check: requires `op` to be a known filter operator string.
+* Deeper validation (children are themselves filters, field is a string,
+* values is an array) is left to the compiler — this is the fast-path gate.
+*/
+function isFilter(value) {
+	if (!value || typeof value !== "object") return false;
+	const op = value.op;
+	return typeof op === "string" && FILTER_OPS.has(op);
+}
+//#endregion
+export { isFilter };

package/dist/filter/index.d.mts

@@ -0,0 +1,7 @@
+import { Filter, FilterAnd, FilterEq, FilterExists, FilterFalse, FilterGt, FilterGte, FilterIn, FilterLike, FilterLt, FilterLte, FilterNe, FilterNin, FilterNot, FilterOp, FilterOr, FilterRaw, FilterRegex, FilterTrue } from "./types.mjs";
+import { FALSE, TRUE, and, between, contains, endsWith, eq, exists, gt, gte, iEq, in_, isNotNull, isNull, like, lt, lte, ne, nin, not, or, raw, regex, startsWith } from "./builders.mjs";
+import { isFilter } from "./guard.mjs";
+import { asPredicate, matchFilter } from "./match.mjs";
+import { SCOPE_ANY, buildTenantScope, mergeScope } from "./scope.mjs";
+import { collectFields, mapFilter, walkFilter } from "./walk.mjs";
+export { FALSE, type Filter, type FilterAnd, type FilterEq, type FilterExists, type FilterFalse, type FilterGt, type FilterGte, type FilterIn, type FilterLike, type FilterLt, type FilterLte, type FilterNe, type FilterNin, type FilterNot, type FilterOp, type FilterOr, type FilterRaw, type FilterRegex, type FilterTrue, SCOPE_ANY, TRUE, and, in_ as anyOf, asPredicate, between, buildTenantScope, collectFields, contains, endsWith, eq, exists, gt, gte, iEq, in_, not as invert, isFilter, isNotNull, isNull, like, lt, lte, mapFilter, matchFilter, mergeScope, ne, nin, nin as noneOf, not, or, raw, regex, startsWith, walkFilter };

package/dist/filter/index.mjs

@@ -0,0 +1,6 @@
+import { FALSE, TRUE, and, between, contains, endsWith, eq, exists, gt, gte, iEq, in_, isNotNull, isNull, like, lt, lte, ne, nin, not, or, raw, regex, startsWith } from "./builders.mjs";
+import { isFilter } from "./guard.mjs";
+import { asPredicate, matchFilter } from "./match.mjs";
+import { SCOPE_ANY, buildTenantScope, mergeScope } from "./scope.mjs";
+import { collectFields, mapFilter, walkFilter } from "./walk.mjs";
+export { FALSE, SCOPE_ANY, TRUE, and, in_ as anyOf, asPredicate, between, buildTenantScope, collectFields, contains, endsWith, eq, exists, gt, gte, iEq, in_, not as invert, isFilter, isNotNull, isNull, like, lt, lte, mapFilter, matchFilter, mergeScope, ne, nin, nin as noneOf, not, or, raw, regex, startsWith, walkFilter };

package/dist/filter/match.d.mts

@@ -0,0 +1,12 @@
+import { Filter } from "./types.mjs";
+
+//#region src/filter/match.d.ts
+/** Evaluate a filter against a single document. Returns true iff the doc matches. */
+declare function matchFilter(doc: unknown, filter: Filter): boolean;
+/**
+ * Lift a Filter into a standalone predicate closure. Handy for
+ * `array.filter(asPredicate(myFilter))`.
+ */
+declare function asPredicate<T>(filter: Filter): (doc: T) => boolean;
+//#endregion
+export { asPredicate, matchFilter };

package/dist/filter/match.mjs

@@ -0,0 +1,91 @@
+//#region src/filter/match.ts
+/** Evaluate a filter against a single document. Returns true iff the doc matches. */
+function matchFilter(doc, filter) {
+	switch (filter.op) {
+		case "true": return true;
+		case "false": return false;
+		case "and": return filter.children.every((child) => matchFilter(doc, child));
+		case "or": return filter.children.some((child) => matchFilter(doc, child));
+		case "not": return !matchFilter(doc, filter.child);
+		case "eq": return equals(getField(doc, filter.field), filter.value);
+		case "ne": return !equals(getField(doc, filter.field), filter.value);
+		case "gt": return compare(getField(doc, filter.field), filter.value) > 0;
+		case "gte": return compare(getField(doc, filter.field), filter.value) >= 0;
+		case "lt": return compare(getField(doc, filter.field), filter.value) < 0;
+		case "lte": return compare(getField(doc, filter.field), filter.value) <= 0;
+		case "in": {
+			const v = getField(doc, filter.field);
+			return filter.values.some((candidate) => equals(v, candidate));
+		}
+		case "nin": {
+			const v = getField(doc, filter.field);
+			return !filter.values.some((candidate) => equals(v, candidate));
+		}
+		case "exists": {
+			const v = getField(doc, filter.field);
+			const present = v !== void 0 && v !== null;
+			return filter.exists ? present : !present;
+		}
+		case "like": {
+			const v = getField(doc, filter.field);
+			if (typeof v !== "string") return false;
+			const flags = filter.caseSensitivity === "sensitive" ? "" : "i";
+			return new RegExp(`^${likeToRegex(filter.pattern)}$`, flags).test(v);
+		}
+		case "regex": {
+			const v = getField(doc, filter.field);
+			if (typeof v !== "string") return false;
+			return new RegExp(filter.pattern, filter.flags).test(v);
+		}
+		case "raw": return false;
+	}
+}
+/**
+* Lift a Filter into a standalone predicate closure. Handy for
+* `array.filter(asPredicate(myFilter))`.
+*/
+function asPredicate(filter) {
+	return (doc) => matchFilter(doc, filter);
+}
+function getField(doc, path) {
+	if (!doc || typeof doc !== "object") return void 0;
+	const segments = path.split(".");
+	let cursor = doc;
+	for (const segment of segments) {
+		if (cursor === null || cursor === void 0) return void 0;
+		if (typeof cursor !== "object") return void 0;
+		cursor = cursor[segment];
+	}
+	return cursor;
+}
+function equals(a, b) {
+	if (a instanceof Date && b instanceof Date) return a.getTime() === b.getTime();
+	if (a instanceof Date && typeof b === "string") return a.toISOString() === b;
+	if (b instanceof Date && typeof a === "string") return b.toISOString() === a;
+	return a === b;
+}
+function compare(a, b) {
+	const aNum = toComparable(a);
+	const bNum = toComparable(b);
+	if (aNum === void 0 || bNum === void 0) return NaN;
+	if (aNum < bNum) return -1;
+	if (aNum > bNum) return 1;
+	return 0;
+}
+function toComparable(value) {
+	if (value === null || value === void 0) return void 0;
+	if (value instanceof Date) return value.getTime();
+	if (typeof value === "number" || typeof value === "string") return value;
+	if (typeof value === "boolean") return value ? 1 : 0;
+}
+/** SQL `LIKE` pattern → JS regex body. Escapes regex metachars; `%` → `.*`, `_` → `.`. */
+function likeToRegex(pattern) {
+	let out = "";
+	for (const ch of pattern) if (ch === "%") out += ".*";
+	else if (ch === "_") out += ".";
+	else if (/[.*+?^${}()|[\]\\]/.test(ch)) out += `\\${ch}`;
+	else out += ch;
+	return out;
+}
+//#endregion
+export { asPredicate, matchFilter };

package/dist/filter/scope.d.mts

@@ -0,0 +1,31 @@
+import { Filter } from "./types.mjs";
+
+//#region src/filter/scope.d.ts
+/**
+ * Inject a tenant-scope predicate into an existing filter.
+ *
+ * Returns a new filter representing `existing AND tenantField = tenantId`.
+ * Handles three existing-filter shapes:
+ *   - `undefined` → returns the bare scope predicate
+ *   - Filter IR → ANDed onto the tree
+ *   - flat record `{ field: value }` → merged field-wise (each existing
+ *     key becomes an `eq` node, ANDed with the scope)
+ *
+ * Used by each kit's `multiTenantPlugin.apply()` to stay consistent
+ * without duplicating the merge logic.
+ */
+declare function buildTenantScope(existing: Filter | Record<string, unknown> | undefined, tenantField: string, tenantId: string | number): Filter | Record<string, unknown>;
+/**
+ * Merge an arbitrary scope predicate into an existing filter.
+ *
+ * Generalization of `buildTenantScope` — callers pass any Filter IR node
+ * (e.g. `isNull('deletedAt')` for soft-delete, `eq('status', 'active')`
+ * for policy guards) and this function handles the existing-filter shape
+ * matrix. Flat-record existing filters become Filter IR on the way out so
+ * the result is always `Filter`-compatible.
+ */
+declare function mergeScope(existing: Filter | Record<string, unknown> | undefined, scope: Filter): Filter;
+/** Convenience: scope that matches everything — the identity under AND. */
+declare const SCOPE_ANY: Filter;
+//#endregion
+export { SCOPE_ANY, buildTenantScope, mergeScope };

package/dist/filter/scope.mjs

@@ -0,0 +1,54 @@
+import { TRUE, and, eq } from "./builders.mjs";
+import { isFilter } from "./guard.mjs";
+//#region src/filter/scope.ts
+/**
+* Scope-injection helpers.
+*
+* Every policy plugin (multi-tenant, soft-delete, org-boundary) follows the
+* same pattern: AND a predicate into an existing filter while tolerating
+* Filter IR, flat `{ field: value }` records, and `undefined`. These
+* helpers lift that pattern out so every kit's local policy plugins compose
+* the same way.
+*/
+/**
+* Inject a tenant-scope predicate into an existing filter.
+*
+* Returns a new filter representing `existing AND tenantField = tenantId`.
+* Handles three existing-filter shapes:
+*   - `undefined` → returns the bare scope predicate
+*   - Filter IR → ANDed onto the tree
+*   - flat record `{ field: value }` → merged field-wise (each existing
+*     key becomes an `eq` node, ANDed with the scope)
+*
+* Used by each kit's `multiTenantPlugin.apply()` to stay consistent
+* without duplicating the merge logic.
+*/
+function buildTenantScope(existing, tenantField, tenantId) {
+	const scope = eq(tenantField, tenantId);
+	if (existing === void 0) return scope;
+	if (isFilter(existing)) return existing.op === "true" ? scope : and(existing, scope);
+	return {
+		...existing,
+		[tenantField]: tenantId
+	};
+}
+/**
+* Merge an arbitrary scope predicate into an existing filter.
+*
+* Generalization of `buildTenantScope` — callers pass any Filter IR node
+* (e.g. `isNull('deletedAt')` for soft-delete, `eq('status', 'active')`
+* for policy guards) and this function handles the existing-filter shape
+* matrix. Flat-record existing filters become Filter IR on the way out so
+* the result is always `Filter`-compatible.
+*/
+function mergeScope(existing, scope) {
+	if (existing === void 0) return scope;
+	if (isFilter(existing)) return existing.op === "true" ? scope : and(existing, scope);
+	const eqs = Object.entries(existing).map(([f, v]) => eq(f, v));
+	if (eqs.length === 0) return scope;
+	return and(...eqs, scope);
+}
+/** Convenience: scope that matches everything — the identity under AND. */
+const SCOPE_ANY = TRUE;
+//#endregion
+export { SCOPE_ANY, buildTenantScope, mergeScope };

package/dist/filter/types.d.mts

@@ -0,0 +1,143 @@
+//#region src/filter/types.d.ts
+/**
+ * Filter IR — driver-agnostic query AST.
+ *
+ * A `Filter` is a tagged-union tree that every kit knows how to compile
+ * to its native syntax. Plugins compose `Filter` nodes via the combinators
+ * in `builders.ts` rather than writing `$`-operator objects directly, so
+ * policy hooks (multi-tenant scope, soft-delete) work identically against
+ * MongoDB, SQLite, Postgres, and Prisma.
+ *
+ * The IR is intentionally small — it covers the operator surface every
+ * SQL and document store supports. Backend-specific operators (Mongo
+ * `$geoWithin`, pgvector `<=>`, Postgres JSONB `@>`) stay kit-native and
+ * are composed alongside the IR via each kit's escape hatch, not embedded
+ * in this type.
+ *
+ * **Compat invariant:** mongokit's Mongo-shaped filter objects (`$`-keyed
+ * records) are NOT `Filter` values. Kits accept both via a passthrough in
+ * their compiler — a raw record is treated as pre-compiled and handed to
+ * the driver unchanged. See `isFilter` for the runtime guard.
+ */
+/** Leaf operator on a single field with a scalar-ish value. */
+interface FilterEq {
+  readonly op: 'eq';
+  readonly field: string;
+  readonly value: unknown;
+}
+interface FilterNe {
+  readonly op: 'ne';
+  readonly field: string;
+  readonly value: unknown;
+}
+interface FilterGt {
+  readonly op: 'gt';
+  readonly field: string;
+  readonly value: unknown;
+}
+interface FilterGte {
+  readonly op: 'gte';
+  readonly field: string;
+  readonly value: unknown;
+}
+interface FilterLt {
+  readonly op: 'lt';
+  readonly field: string;
+  readonly value: unknown;
+}
+interface FilterLte {
+  readonly op: 'lte';
+  readonly field: string;
+  readonly value: unknown;
+}
+/** Leaf operator on a single field with a set value. */
+interface FilterIn {
+  readonly op: 'in';
+  readonly field: string;
+  readonly values: readonly unknown[];
+}
+interface FilterNin {
+  readonly op: 'nin';
+  readonly field: string;
+  readonly values: readonly unknown[];
+}
+/**
+ * Substring / prefix / suffix match with SQL-style `%` wildcards.
+ * Kits compile to MongoDB `$regex`, SQL `LIKE`, Prisma `contains`/`startsWith`/`endsWith`.
+ * Use `regex` for anchored/character-class patterns when your schema allows.
+ */
+interface FilterLike {
+  readonly op: 'like';
+  readonly field: string;
+  readonly pattern: string;
+  /** Case sensitivity. Default `'insensitive'` — matches how most UIs expect search. */
+  readonly caseSensitivity?: 'sensitive' | 'insensitive';
+}
+/**
+ * Regex match — the most powerful leaf. Not every driver exposes the same
+ * regex dialect (Mongo ICU, Postgres POSIX, SQLite PCRE via extension),
+ * so kits MAY reject patterns their backend can't compile. Prefer `like`
+ * when a substring match suffices.
+ */
+interface FilterRegex {
+  readonly op: 'regex';
+  readonly field: string;
+  readonly pattern: string;
+  readonly flags?: string;
+}
+/** Field presence / absence (NULL vs NOT NULL in SQL; `$exists` in Mongo). */
+interface FilterExists {
+  readonly op: 'exists';
+  readonly field: string;
+  readonly exists: boolean;
+}
+/** Boolean composition nodes — recursive. */
+interface FilterAnd {
+  readonly op: 'and';
+  readonly children: readonly Filter[];
+}
+interface FilterOr {
+  readonly op: 'or';
+  readonly children: readonly Filter[];
+}
+interface FilterNot {
+  readonly op: 'not';
+  readonly child: Filter;
+}
+/** Tautology — matches every document. Useful as an identity for `and` reductions. */
+interface FilterTrue {
+  readonly op: 'true';
+}
+/** Contradiction — matches no document. */
+interface FilterFalse {
+  readonly op: 'false';
+}
+/**
+ * Driver-native escape hatch. Carries opaque SQL / query fragment + params
+ * through to the compiler untouched. Kits compile by inlining the fragment
+ * verbatim (and appending the params in order). Use sparingly — the IR
+ * advantage is lost inside a `raw` node.
+ *
+ * Arc's `matchFilter` (in-memory) always returns `false` for `raw` nodes:
+ * evaluating arbitrary SQL in JS isn't possible, so a caller who uses raw
+ * must either (a) not rely on in-memory matching for that predicate, or
+ * (b) provide their own evaluator via the match options surface.
+ *
+ * @example pgvector cosine similarity
+ * ```ts
+ * and(eq('userId', ctx.userId), raw('embedding <=> ? < 0.3', [queryEmbedding]))
+ * ```
+ */
+interface FilterRaw {
+  readonly op: 'raw';
+  /** Kit-native query fragment. Embedded verbatim by each kit's compiler. */
+  readonly sql: string;
+  /** Positional params bound at the position of this fragment in the final query. */
+  readonly params?: readonly unknown[];
+}
+/** Root discriminated-union node. Every kit's compiler pattern-matches on `op`. */
+type Filter = FilterEq | FilterNe | FilterGt | FilterGte | FilterLt | FilterLte | FilterIn | FilterNin | FilterLike | FilterRegex | FilterExists | FilterAnd | FilterOr | FilterNot | FilterTrue | FilterFalse | FilterRaw;
+/** Narrow set of ops for pattern-matching exhaustiveness checks. */
+type FilterOp = Filter['op'];
+//#endregion
+export { Filter, FilterAnd, FilterEq, FilterExists, FilterFalse, FilterGt, FilterGte, FilterIn, FilterLike, FilterLt, FilterLte, FilterNe, FilterNin, FilterNot, FilterOp, FilterOr, FilterRaw, FilterRegex, FilterTrue };

package/dist/filter/walk.d.mts

@@ -0,0 +1,24 @@
+import { Filter } from "./types.mjs";
+
+//#region src/filter/walk.d.ts
+/**
+ * Depth-first visit of every node. Visitor returns `false` to stop descent
+ * into the current subtree (e.g. optimization prunes). Otherwise visits
+ * children.
+ */
+declare function walkFilter(filter: Filter, visit: (node: Filter) => boolean | undefined): void;
+/**
+ * Post-order transform. `transform` sees every node after its children have
+ * been rewritten, so leaf rewrites cascade up. Return the same node
+ * reference to opt-out of a rewrite at that level.
+ *
+ * Guarantees:
+ * - Immutable — never mutates input.
+ * - Identity-preserving — when no child changes, the parent node is
+ *   returned unchanged (useful for structural sharing in caches).
+ */
+declare function mapFilter(filter: Filter, transform: (node: Filter) => Filter): Filter;
+/** Collect every field name referenced in the tree. Useful for index hints, policy checks. */
+declare function collectFields(filter: Filter): string[];
+//#endregion
+export { collectFields, mapFilter, walkFilter };