@protobase/query 0.0.0-stage → 0.1.0

package/dist/facet-counts.js

@@ -0,0 +1,27 @@
+import { QueryError } from "./fields/query-error.js";
+import { columnRef, requireField } from "./columns.js";
+import { baseQuery } from "./base-query.js";
+import { assertFilterRequirements } from "./filter-requirements.js";
+import { toNumber } from "./numbers.js";
+import { withoutField } from "./prune-filter.js";
+import { withStatementTimeout } from "./with-statement-timeout.js";
+import { sql } from "kysely";
+//#region src/facet-counts.ts
+const defaultLimit = 100;
+const maxLimit = 1e3;
+/** Counts per value of `field`, with every filter applied except the ones on `field` itself. */
+const facetCounts = async (db, model, field, filter, options) => {
+	const column = columnRef(requireField(model, field, "filterable"));
+	const limit = options.limit ?? defaultLimit;
+	if (!Number.isInteger(limit) || limit < 1 || limit > maxLimit) throw new QueryError("invalid_option", `limit must be between 1 and ${maxLimit}`);
+	const others = withoutField(filter, field);
+	await assertFilterRequirements(db, others, options.scope);
+	return withStatementTimeout(db, options.statementTimeoutMs, async (trx) => {
+		return (await baseQuery(trx, model, others, options.scope).select([sql`${column}`.as("value"), sql`count(*)::text`.as("n")]).groupBy(column).orderBy(sql`count(*)`, "desc").orderBy(column, "asc").limit(limit).execute()).map((row) => ({
+			value: row.value,
+			count: toNumber(row.n)
+		}));
+	});
+};
+//#endregion
+export { facetCounts };

package/dist/field-values.js

@@ -0,0 +1,36 @@
+import { QueryError } from "./fields/query-error.js";
+import { toParam } from "./fields/text.js";
+import { toParam as toParam$1 } from "./fields/bigint.js";
+import { toParam as toParam$2 } from "./fields/boolean.js";
+import { toParam as toParam$3 } from "./fields/country.js";
+import { toParam as toParam$4 } from "./fields/currency.js";
+import { toParam as toParam$5 } from "./fields/date.js";
+import { toParam as toParam$6 } from "./fields/decimal.js";
+import { toParam as toParam$7 } from "./fields/enum.js";
+import { toParam as toParam$8 } from "./fields/integer.js";
+import { toParam as toParam$9 } from "./fields/relation.js";
+import { toParam as toParam$10 } from "./fields/timestamp.js";
+import { toParam as toParam$11 } from "./fields/uuid.js";
+//#region src/field-values.ts
+const byType = {
+	text: toParam,
+	integer: toParam$8,
+	bigint: toParam$1,
+	decimal: toParam$6,
+	boolean: toParam$2,
+	date: toParam$5,
+	timestamp: toParam$10,
+	uuid: toParam$11,
+	currency: toParam$4,
+	country: toParam$3,
+	relation: toParam$9,
+	enum: toParam$7
+};
+/** json and file fields have no scalar comparison; the checker rejects them before they reach here. */
+const paramFor = (value, field) => {
+	const convert = byType[field.type];
+	if (!convert) throw new QueryError("unsupported_field_type", `Field "${field.name}" (${field.type}) cannot be compared`);
+	return convert(value, field);
+};
+//#endregion
+export { paramFor };

package/dist/fields/bigint.js

@@ -0,0 +1,13 @@
+import { invalidValue, numericText } from "./sql-common.js";
+//#region src/fields/bigint.ts
+const int64Max = 2n ** 63n - 1n;
+/** Sent as text so no precision is lost. */
+const toParam = (value, field) => {
+	const text = numericText(value, field, "a 64-bit integer");
+	if (!/^-?\d{1,19}$/.test(text)) throw invalidValue(field, "a 64-bit integer");
+	const parsed = BigInt(text);
+	if (parsed > int64Max || parsed < -int64Max - 1n) throw invalidValue(field, "a 64-bit integer");
+	return text;
+};
+//#endregion
+export { toParam };

package/dist/fields/boolean.js

@@ -0,0 +1,8 @@
+import { invalidValue } from "./sql-common.js";
+//#region src/fields/boolean.ts
+const toParam = (value, field) => {
+	if (value.kind !== "boolean") throw invalidValue(field, "a boolean");
+	return value.value;
+};
+//#endregion
+export { toParam };

package/dist/fields/country.js

@@ -0,0 +1,5 @@
+import { stringValue } from "./sql-common.js";
+//#region src/fields/country.ts
+const toParam = (value, field) => stringValue(value, field, "an ISO 3166-1 country code");
+//#endregion
+export { toParam };

package/dist/fields/currency.js

@@ -0,0 +1,5 @@
+import { stringValue } from "./sql-common.js";
+//#region src/fields/currency.ts
+const toParam = (value, field) => stringValue(value, field, "an ISO 4217 currency code");
+//#endregion
+export { toParam };

package/dist/fields/date.js

@@ -0,0 +1,11 @@
+import { invalidValue, nowExpression, stringValue } from "./sql-common.js";
+import { sql } from "kysely";
+//#region src/fields/date.ts
+const toParam = (value, field) => {
+	if (value.kind === "now") return sql`(${nowExpression(value)})::date`;
+	const text = stringValue(value, field, "a date (YYYY-MM-DD)");
+	if (!/^\d{4}-\d{2}-\d{2}$/.test(text) || Number.isNaN(Date.parse(text))) throw invalidValue(field, "a date (YYYY-MM-DD)");
+	return text;
+};
+//#endregion
+export { toParam };

package/dist/fields/decimal.js

@@ -0,0 +1,9 @@
+import { invalidValue, numericText } from "./sql-common.js";
+//#region src/fields/decimal.ts
+const toParam = (value, field) => {
+	const text = numericText(value, field, "a decimal number");
+	if (!/^-?\d+(\.\d+)?$/.test(text)) throw invalidValue(field, "a decimal number");
+	return text;
+};
+//#endregion
+export { toParam };

package/dist/fields/enum.js

@@ -0,0 +1,9 @@
+import { invalidValue, stringValue } from "./sql-common.js";
+//#region src/fields/enum.ts
+const toParam = (value, field) => {
+	const text = stringValue(value, field, "a string");
+	if (field.enumValues && !field.enumValues.includes(text)) throw invalidValue(field, "one of its enum values");
+	return text;
+};
+//#endregion
+export { toParam };

package/dist/fields/integer.js

@@ -0,0 +1,9 @@
+import { invalidValue, numericText } from "./sql-common.js";
+//#region src/fields/integer.ts
+const toParam = (value, field) => {
+	const number = Number(numericText(value, field, "a 32-bit integer"));
+	if (!Number.isSafeInteger(number) || Math.abs(number) > 2 ** 31 - 1) throw invalidValue(field, "a 32-bit integer");
+	return number;
+};
+//#endregion
+export { toParam };

package/dist/fields/json.js

@@ -0,0 +1,15 @@
+import { sql } from "kysely";
+//#region src/fields/json.ts
+/** `field:value`: the json contains the scalar, as an array element, an equal value or (for text) an object key. */
+const jsonHas = (col, value) => {
+	switch (value.kind) {
+		case "string": return sql`(jsonb_exists(${col}::jsonb, ${value.value}) or ${col}::jsonb @> to_jsonb(${value.value}::text))`;
+		case "number": return sql`${col}::jsonb @> to_jsonb(${value.raw}::numeric)`;
+		case "boolean": return sql`${col}::jsonb @> to_jsonb(${value.value}::boolean)`;
+		default: throw new Error(`Not implemented: json containment for ${value.kind} literals, the parser only produces strings, numbers and booleans`);
+	}
+};
+/** `field:*`: a json value other than SQL NULL and JSON null. */
+const jsonPresent = (col) => sql`(${col} is not null and ${col}::jsonb <> 'null'::jsonb)`;
+//#endregion
+export { jsonHas, jsonPresent };

package/dist/fields/query-error.d.ts

@@ -0,0 +1,8 @@
+//#region src/fields/query-error.d.ts
+export type QueryErrorCode = 'unknown_field' | 'not_filterable' | 'not_sortable' | 'unsupported_operator' | 'unsupported_field_type' | 'missing_tenant' | 'invalid_filter' | 'invalid_value' | 'invalid_sort' | 'invalid_cursor' | 'invalid_limit' | 'invalid_option' | 'no_statistics' | 'no_search_fields' | 'missing_extension';
+/** Thrown for any request the query layer refuses; `code` is the stable part, `message` is for humans. */
+export declare class QueryError extends Error {
+  readonly code: QueryErrorCode;
+  constructor(code: QueryErrorCode, message: string);
+}
+//#endregion

package/dist/fields/query-error.js

@@ -0,0 +1,12 @@
+//#region src/fields/query-error.ts
+/** Thrown for any request the query layer refuses; `code` is the stable part, `message` is for humans. */
+var QueryError = class extends Error {
+	code;
+	constructor(code, message) {
+		super(message);
+		this.code = code;
+		this.name = "QueryError";
+	}
+};
+//#endregion
+export { QueryError };

package/dist/fields/relation.js

@@ -0,0 +1,10 @@
+import { invalidValue } from "./sql-common.js";
+//#region src/fields/relation.ts
+/** A related record's key: text, or a safe integer. */
+const toParam = (value, field) => {
+	if (value.kind === "string") return value.value;
+	if (value.kind === "number" && Number.isSafeInteger(value.value)) return value.raw;
+	throw invalidValue(field, "a record key");
+};
+//#endregion
+export { toParam };

package/dist/fields/sql-common.js

@@ -0,0 +1,30 @@
+import { QueryError } from "./query-error.js";
+import { sql } from "kysely";
+//#region src/fields/sql-common.ts
+const invalidValue = (field, expected) => new QueryError("invalid_value", `Field "${field.name}" expects ${expected}`);
+/** Numbers keep their written text so bigint and decimal precision is never lost to a JS double. */
+const numericText = (value, field, expected) => {
+	if (value.kind === "number") return value.raw;
+	if (value.kind === "string") return value.value;
+	throw invalidValue(field, expected);
+};
+const stringValue = (value, field, expected) => {
+	if (value.kind !== "string") throw invalidValue(field, expected);
+	return value.value;
+};
+const secondsPerUnit = {
+	s: 1,
+	m: 60,
+	h: 3600,
+	d: 86400,
+	w: 604800
+};
+/** `now()` with its optional +/- duration offset, as a timestamptz expression. */
+const nowExpression = (value) => {
+	if (!value.offset) return sql`now()`;
+	const { sign, duration } = value.offset;
+	const seconds = duration.amount * secondsPerUnit[duration.unit];
+	return sql`now() ${sql.raw(sign === "-" ? "-" : "+")} ${seconds}::float8 * interval '1 second'`;
+};
+//#endregion
+export { invalidValue, nowExpression, numericText, stringValue };

package/dist/fields/text.js

@@ -0,0 +1,10 @@
+import { stringValue } from "./sql-common.js";
+//#region src/fields/text.ts
+const toParam = (value, field) => stringValue(value, field, "a string");
+const escapeLike = (text) => text.replace(/[\\%_]/g, "\\$&");
+/** Escapes LIKE wildcards (backslash is LIKE's default escape), then turns the filter wildcard `*` into `%`. */
+const wildcardPattern = (text) => escapeLike(text).replaceAll("*", "%");
+/** A LIKE pattern for values that contain the text anywhere, taken literally. */
+const containsPattern = (text) => `%${escapeLike(text)}%`;
+//#endregion
+export { containsPattern, toParam, wildcardPattern };

package/dist/fields/timestamp.js

@@ -0,0 +1,10 @@
+import { invalidValue, nowExpression } from "./sql-common.js";
+//#region src/fields/timestamp.ts
+/** Parsed RFC 3339 timestamps are sent as written, which keeps microseconds. */
+const toParam = (value, field) => {
+	if (value.kind === "now") return nowExpression(value);
+	if (value.kind !== "timestamp" && value.kind !== "string" || Number.isNaN(Date.parse(value.value))) throw invalidValue(field, "an RFC 3339 timestamp");
+	return value.value;
+};
+//#endregion
+export { toParam };

package/dist/fields/uuid.js

@@ -0,0 +1,10 @@
+import { invalidValue, stringValue } from "./sql-common.js";
+//#region src/fields/uuid.ts
+const uuidPattern = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const toParam = (value, field) => {
+	const text = stringValue(value, field, "a UUID");
+	if (!uuidPattern.test(text)) throw invalidValue(field, "a UUID");
+	return text;
+};
+//#endregion
+export { toParam };

package/dist/filter-requirements.js

@@ -0,0 +1,15 @@
+import { QueryError } from "./fields/query-error.js";
+import { sql } from "kysely";
+//#region src/filter-requirements.ts
+const usesSimilar = (node) => {
+	if (node.kind === "similar") return true;
+	if (node.kind === "and" || node.kind === "or") return node.args.some(usesSimilar);
+	return node.kind === "not" && usesSimilar(node.arg);
+};
+/** Fails with a clear error, before any query runs, when the filter needs an extension the database lacks. */
+const assertFilterRequirements = async (db, filter, scope) => {
+	if (!(filter && usesSimilar(filter)) && !(scope?.rowFilter && usesSimilar(scope.rowFilter))) return;
+	if ((await sql`select count(*)::text as n from pg_extension where extname = 'pg_trgm'`.execute(db)).rows[0]?.n === "0") throw new QueryError("missing_extension", "similar() needs the pg_trgm extension: run \"create extension pg_trgm\"");
+};
+//#endregion
+export { assertFilterRequirements };

package/dist/histogram.d.ts

@@ -0,0 +1,17 @@
+import { Db } from "./db.js";
+import { Scope } from "./scope.js";
+import { CheckedFilter, ResourceModel } from "@protobase/schema";
+//#region src/histogram.d.ts
+export type HistogramBucket = {
+  from: number;
+  to: number;
+  count: number;
+};
+export type Histogram = {
+  min: number | null;
+  max: number | null;
+  buckets: HistogramBucket[];
+};
+/** Equal-width buckets between the filtered min and max, empty buckets included. */
+export declare const histogram: (db: Db, model: ResourceModel, field: string, filter: CheckedFilter | undefined, buckets: number, scope?: Scope) => Promise<Histogram>;
+//#endregion

package/dist/histogram.js

@@ -0,0 +1,57 @@
+import { QueryError } from "./fields/query-error.js";
+import { columnRef, requireField } from "./columns.js";
+import { baseQuery } from "./base-query.js";
+import { assertFilterRequirements } from "./filter-requirements.js";
+import { toNumber } from "./numbers.js";
+import { sql } from "kysely";
+//#region src/histogram.ts
+const maxBuckets = 200;
+const numericTypes = [
+	"integer",
+	"bigint",
+	"decimal",
+	"currency"
+];
+/** Equal-width buckets between the filtered min and max, empty buckets included. */
+const histogram = async (db, model, field, filter, buckets, scope) => {
+	const target = requireField(model, field, "filterable");
+	if (!numericTypes.includes(target.type)) throw new QueryError("unsupported_field_type", `Histogram needs a numeric field, "${field}" is ${target.type}`);
+	if (!Number.isInteger(buckets) || buckets < 1 || buckets > maxBuckets) throw new QueryError("invalid_option", `buckets must be between 1 and ${maxBuckets}`);
+	await assertFilterRequirements(db, filter, scope);
+	const col = columnRef(target);
+	const present = baseQuery(db, model, filter, scope).where(sql`${col} is not null`);
+	const bounds = await present.select([sql`min(${col})::float8::text`.as("lo"), sql`max(${col})::float8::text`.as("hi")]).executeTakeFirstOrThrow();
+	if (bounds.lo === null || bounds.hi === null) return {
+		min: null,
+		max: null,
+		buckets: []
+	};
+	const min = Number(bounds.lo);
+	const max = Number(bounds.hi);
+	if (min === max) {
+		const total = await present.select(sql`count(*)::text`.as("n")).executeTakeFirstOrThrow();
+		return {
+			min,
+			max,
+			buckets: [{
+				from: min,
+				to: max,
+				count: toNumber(total.n)
+			}]
+		};
+	}
+	const counted = await present.select([sql`least(width_bucket(${col}::float8, ${min}::float8, ${max}::float8, ${buckets}::int), ${buckets}::int)`.as("bucket"), sql`count(*)::text`.as("n")]).groupBy(sql`1`).execute();
+	const counts = new Map(counted.map((row) => [toNumber(row.bucket), toNumber(row.n)]));
+	const width = (max - min) / buckets;
+	return {
+		min,
+		max,
+		buckets: Array.from({ length: buckets }, (_, i) => ({
+			from: min + i * width,
+			to: i === buckets - 1 ? max : min + (i + 1) * width,
+			count: counts.get(i + 1) ?? 0
+		}))
+	};
+};
+//#endregion
+export { histogram };

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+import { CompileOptions, compileFilter } from "./compile-filter.js";
+import { Db } from "./db.js";
+import { Scope } from "./scope.js";
+import { ExtraColumn, ListOptions, ListPlan, ListResult, buildListQuery, listQuery, maxLimit } from "./list-query.js";
+import { estimateCount } from "./estimate-count.js";
+import { exactCount } from "./exact-count.js";
+import { FacetCount, FacetOptions, facetCounts } from "./facet-counts.js";
+import { Granularity, SeriesOptions, SeriesPoint, series } from "./series.js";
+import { Histogram, HistogramBucket, histogram } from "./histogram.js";
+import { ScrollMode, scrollMode } from "./scroll-mode.js";
+import { GuardFinding, GuardOptions, GuardReport, explainGuard } from "./explain-guard.js";
+import { QueryError, QueryErrorCode } from "./fields/query-error.js";
+import { SeekRequest, seekToPosition } from "./seek-to-position.js";
+export { type CompileOptions, type Db, type ExtraColumn, type FacetCount, type FacetOptions, type Granularity, type GuardFinding, type GuardOptions, type GuardReport, type Histogram, type HistogramBucket, type ListOptions, type ListPlan, type ListResult, QueryError, type QueryErrorCode, type Scope, type ScrollMode, type SeekRequest, type SeriesOptions, type SeriesPoint, buildListQuery, compileFilter, estimateCount, exactCount, explainGuard, facetCounts, histogram, listQuery, maxLimit, scrollMode, seekToPosition, series };

package/dist/index.js

@@ -0,0 +1,12 @@
+import { QueryError } from "./fields/query-error.js";
+import { compileFilter } from "./compile-filter.js";
+import { buildListQuery, listQuery, maxLimit } from "./list-query.js";
+import { estimateCount } from "./estimate-count.js";
+import { exactCount } from "./exact-count.js";
+import { facetCounts } from "./facet-counts.js";
+import { series } from "./series.js";
+import { histogram } from "./histogram.js";
+import { scrollMode } from "./scroll-mode.js";
+import { explainGuard } from "./explain-guard.js";
+import { seekToPosition } from "./seek-to-position.js";
+export { QueryError, buildListQuery, compileFilter, estimateCount, exactCount, explainGuard, facetCounts, histogram, listQuery, maxLimit, scrollMode, seekToPosition, series };

package/dist/list-query.d.ts

@@ -0,0 +1,40 @@
+import { Db } from "./db.js";
+import { Scope } from "./scope.js";
+import { SortKey } from "./sort.js";
+import { ListQuery, ResourceModel } from "@protobase/schema";
+//#region src/list-query.d.ts
+export declare const maxLimit = 500;
+export type ListResult = {
+  rows: Array<Record<string, unknown>>;
+  nextCursor: string | null;
+  prevCursor: string | null;
+};
+/** An extra output column, mapped from a model field and never from raw SQL. */
+export type ExtraColumn = {
+  field: string;
+  as: 'text';
+  alias: string;
+};
+export type ListOptions = {
+  /** `as: 'text'` selects `column::text`, so timestamps and numerics keep full database precision. */
+  extraColumns?: ExtraColumn[];
+};
+export type ListPlan = {
+  /** The exact query listQuery runs (fetches limit + 1 rows); explain it, or execute it yourself. */
+  query: ReturnType<typeof selectPage>;
+  limit: number;
+  keys: SortKey[];
+  reverse: boolean;
+  hasCursor: boolean;
+};
+declare const selectPage: (db: Db, model: ResourceModel, query: ListQuery, scope: Scope | undefined, keys: SortKey[], cursorValues: Array<string | null> | undefined, options: ListOptions) => import("kysely").SelectQueryBuilder<{
+  [x: string]: any;
+  [x: number]: any;
+  [x: symbol]: any;
+}, "t", {
+  [x: string]: unknown;
+}>;
+/** Validates the request and builds, without executing, the query listQuery would run. */
+export declare const buildListQuery: (db: Db, model: ResourceModel, query: ListQuery, scope?: Scope, options?: ListOptions) => Promise<ListPlan>;
+export declare const listQuery: (db: Db, model: ResourceModel, query: ListQuery, scope?: Scope, options?: ListOptions) => Promise<ListResult>;
+//#endregion

package/dist/list-query.js

@@ -0,0 +1,61 @@
+import { QueryError } from "./fields/query-error.js";
+import { columnRef, findField } from "./columns.js";
+import { baseQuery } from "./base-query.js";
+import { effectiveSort, flip } from "./sort.js";
+import { decodeCursor, encodeCursor } from "./cursor.js";
+import { assertFilterRequirements } from "./filter-requirements.js";
+import { orderTerm } from "./order.js";
+import { seekCondition } from "./seek.js";
+import { sql } from "kysely";
+//#region src/list-query.ts
+const maxLimit = 500;
+const keyAlias = (index) => `__pb_key${index}`;
+const clampLimit = (limit) => {
+	if (!Number.isInteger(limit) || limit < 1) throw new QueryError("invalid_limit", "limit must be a positive integer");
+	return Math.min(limit, 500);
+};
+const requestedFields = (model, columns) => (columns ?? Object.keys(model.fields)).map((name) => findField(model, name));
+const extraSelections = (model, extras = []) => extras.map(({ field, as, alias }) => {
+	if (as !== "text") throw new QueryError("invalid_option", "extraColumns only supports as: \"text\"");
+	if (Object.hasOwn(model.fields, alias) || alias.startsWith("__pb_key")) throw new QueryError("invalid_option", `extra column alias "${alias}" collides with a field or internal column`);
+	return sql`${columnRef(findField(model, field))}::text`.as(alias);
+});
+const selectPage = (db, model, query, scope, keys, cursorValues, options) => {
+	const reading = query.direction ?? "after";
+	const reverse = reading === "before";
+	let select = baseQuery(db, model, query.filter, scope).select(requestedFields(model, query.columns).map((field) => sql`${columnRef(field)}`.as(field.name))).select(extraSelections(model, options.extraColumns)).select(keys.map((key, i) => sql`${columnRef(key.field)}::text`.as(keyAlias(i))));
+	if (cursorValues) select = select.where(seekCondition(keys, cursorValues, reading));
+	for (const key of keys) select = select.orderBy(orderTerm(key, reverse ? flip(key.direction) : key.direction));
+	return select.limit(clampLimit(query.limit) + 1);
+};
+/** Validates the request and builds, without executing, the query listQuery would run. */
+const buildListQuery = async (db, model, query, scope, options = {}) => {
+	const limit = clampLimit(query.limit);
+	await assertFilterRequirements(db, query.filter, scope);
+	const keys = effectiveSort(model, query.sort);
+	const cursorValues = query.cursor === void 0 ? void 0 : decodeCursor(query.cursor, keys);
+	return {
+		query: selectPage(db, model, query, scope, keys, cursorValues, options),
+		limit,
+		keys,
+		reverse: query.direction === "before",
+		hasCursor: cursorValues !== void 0
+	};
+};
+const listQuery = async (db, model, query, scope, options = {}) => {
+	const { query: select, limit, keys, reverse, hasCursor } = await buildListQuery(db, model, query, scope, options);
+	const fetched = await select.execute();
+	const more = fetched.length > limit;
+	const page = more ? fetched.slice(0, limit) : fetched;
+	if (reverse) page.reverse();
+	const cursorOf = (row) => encodeCursor(keys, keys.map((_, i) => row[keyAlias(i)] === null ? null : String(row[keyAlias(i)])));
+	const first = page[0];
+	const last = page.at(-1);
+	return {
+		rows: page.map((row) => Object.fromEntries(Object.entries(row).filter(([name]) => !name.startsWith("__pb_key")))),
+		nextCursor: last && (reverse ? hasCursor : more) ? cursorOf(last) : null,
+		prevCursor: first && (reverse ? more : hasCursor) ? cursorOf(first) : null
+	};
+};
+//#endregion
+export { buildListQuery, listQuery, maxLimit };

package/dist/numbers.js

@@ -0,0 +1,5 @@
+//#region src/numbers.ts
+/** Driver values for bigint/numeric columns arrive as number, bigint or string. */
+const toNumber = (value) => Number(value);
+//#endregion
+export { toNumber };

package/dist/order.js

@@ -0,0 +1,14 @@
+import { columnRef } from "./columns.js";
+import { sql } from "kysely";
+//#region src/order.ts
+/**
+* ORDER BY term for a sort key. Nulls follow Postgres defaults (last for asc, first for desc), written out for
+* nullable columns so the seek predicates in seek.ts and the ordering can never drift apart.
+*/
+const orderTerm = (key, direction = key.direction) => {
+	const column = columnRef(key.field);
+	if (!key.field.nullable) return sql`${column} ${sql.raw(direction)}`;
+	return sql`${column} ${sql.raw(direction)} nulls ${sql.raw(direction === "asc" ? "last" : "first")}`;
+};
+//#endregion
+export { orderTerm };

package/dist/prune-filter.js

@@ -0,0 +1,26 @@
+//#region src/prune-filter.ts
+/** Removes every condition on `field`, dropping groups that end up empty (disjunctive faceting). Text search stays. */
+const withoutField = (node, field) => {
+	if (!node) return void 0;
+	switch (node.kind) {
+		case "and":
+		case "or": {
+			const args = node.args.map((arg) => withoutField(arg, field)).filter((arg) => arg !== void 0);
+			return args.length === 0 ? void 0 : {
+				...node,
+				args
+			};
+		}
+		case "not": {
+			const arg = withoutField(node.arg, field);
+			return arg && {
+				...node,
+				arg
+			};
+		}
+		case "search": return node;
+		default: return node.field.name === field ? void 0 : node;
+	}
+};
+//#endregion
+export { withoutField };

package/dist/range-bound.js

@@ -0,0 +1,15 @@
+import { QueryError } from "./fields/query-error.js";
+//#region src/range-bound.ts
+const datePattern = /^\d{4}-\d{2}-\d{2}$/;
+const timestampPattern = /^\d{4}-\d{2}-\d{2}([T ]\d{2}:\d{2}(:\d{2}(\.\d{1,6})?)?)?(Z|[+-]\d{2}(:?\d{2})?)?$/;
+/** Validates a series range bound: a Date or ISO text (dates only for `date` fields). Returns text to bind. */
+const rangeBound = (value, field) => {
+	const wantsDate = field.type === "date";
+	const text = value instanceof Date ? value.toISOString() : value;
+	const pattern = wantsDate ? datePattern : timestampPattern;
+	const date = wantsDate && value instanceof Date ? text.slice(0, 10) : text;
+	if (!pattern.test(date) || Number.isNaN(Date.parse(date))) throw new QueryError("invalid_option", `Range bounds for "${field.name}" must be ${wantsDate ? "YYYY-MM-DD dates" : "ISO 8601 timestamps"}`);
+	return date;
+};
+//#endregion
+export { rangeBound };

package/dist/scope.d.ts

@@ -0,0 +1,17 @@
+import { Expression, SqlBool } from "kysely";
+import { CheckedFilter, ResourceModel } from "@protobase/schema";
+//#region src/scope.d.ts
+/**
+ * Who is asking, and which rows they may see.
+ * - `tenantValue`: models with a `tenant` column only ever see rows of this value.
+ * - `rowFilter`: a filter from access rules, ANDed in before the user's filter. It is checked against the FULL model,
+ *   so it may use hidden or non-filterable columns the user's own (restricted) model does not expose.
+ * - `fullModel`: that full model. Soft delete, tenant and `rowFilter` resolve against it; everything the user
+ *   supplies (filter, sort, columns, fields) resolves against the model argument. Defaults to the model argument.
+ */
+export type Scope = {
+  tenantValue?: string | number;
+  rowFilter?: CheckedFilter;
+  fullModel?: ResourceModel;
+};
+//#endregion

package/dist/scope.js

@@ -0,0 +1,17 @@
+import { QueryError } from "./fields/query-error.js";
+import { columnRef } from "./columns.js";
+import { sql } from "kysely";
+//#region src/scope.ts
+const fullModelOf = (model, scope) => scope?.fullModel ?? model;
+/** `tenant = value` for tenant models; throws when the scope is missing, so a forgotten scope never leaks rows. */
+const tenantCondition = (model, scope) => {
+	const full = fullModelOf(model, scope);
+	const tenant = full.tenant ?? model.tenant;
+	if (!tenant) return void 0;
+	if (scope?.tenantValue === void 0) throw new QueryError("missing_tenant", `Resource "${model.name}" is tenant-scoped; pass scope.tenantValue`);
+	const field = Object.hasOwn(full.fields, tenant) ? full.fields[tenant] : void 0;
+	const column = field ? columnRef(field) : sql`${sql.id("t", tenant)}`;
+	return sql`${column} = ${scope.tenantValue}`;
+};
+//#endregion
+export { fullModelOf, tenantCondition };