@protobase/schema 0.0.0-stage → 0.1.1

package/dist/filter/check-model.js

@@ -0,0 +1,123 @@
+import { filterError } from "./errors.js";
+import { checkValue } from "./check-value.js";
+import { resolveField } from "./check-field.js";
+import { compareOps, isOpaque } from "./operators.js";
+//#region src/filter/check-model.ts
+const value = (ctx, field, node) => {
+	const problem = checkValue(field, node);
+	if (problem) ctx.errors.push(filterError("invalid-value", problem.message, problem.hint, node.span));
+	return !problem;
+};
+const operatorError = (ctx, message, hint, span) => {
+	ctx.errors.push(filterError("operator-not-allowed", message, hint, span));
+};
+const isWildcard = (op, node) => (op === "=" || op === "!=") && node.kind === "string" && node.value.includes("*");
+const checkCompare = (ctx, node) => {
+	const field = resolveField(ctx, node.field, "filterable");
+	if (!field) return void 0;
+	const allowed = compareOps(field.type);
+	if (!allowed.includes(node.op)) {
+		operatorError(ctx, `Operator "${node.op}" is not supported for ${field.type} fields`, allowed.length ? `Supported: ${allowed.join(" ")}` : "Use field:value on json fields, or isNull(field)", node.span);
+		return;
+	}
+	if (isWildcard(node.op, node.value) && field.type !== "text") {
+		ctx.errors.push(filterError("wildcard-not-allowed", `Wildcards are only supported on text fields, not ${field.type}`, "Remove the \"*\" or filter a text field", node.value.span));
+		return;
+	}
+	if (!isWildcard(node.op, node.value) && !value(ctx, field, node.value)) return void 0;
+	return {
+		...node,
+		field
+	};
+};
+const checkHas = (ctx, node) => {
+	const field = resolveField(ctx, node.field, "filterable");
+	if (!field) return void 0;
+	if (field.type !== "json") {
+		operatorError(ctx, `":" is only supported on json fields, not ${field.type}`, `Use = on ${field.type} fields, or field:* to test for a value`, node.span);
+		return;
+	}
+	return {
+		...node,
+		field
+	};
+};
+const checkIn = (ctx, node) => {
+	const field = resolveField(ctx, node.field, "filterable");
+	if (!field) return void 0;
+	if (isOpaque(field.type)) {
+		operatorError(ctx, `in() is not supported for ${field.type} fields`, "Use field:value on json fields", node.span);
+		return;
+	}
+	return node.values.map((literal) => value(ctx, field, literal)).every(Boolean) ? {
+		...node,
+		field
+	} : void 0;
+};
+const checkText = (ctx, name, path) => {
+	const field = resolveField(ctx, path, "filterable");
+	if (field && field.type !== "text") {
+		operatorError(ctx, `${name}() only works on text fields, not ${field.type}`, `Field "${field.name}" is ${field.type}`, path.span);
+		return;
+	}
+	return field;
+};
+const checkNode = (ctx, node) => {
+	switch (node.kind) {
+		case "and":
+		case "or": {
+			const args = node.args.map((arg) => checkNode(ctx, arg));
+			return args.every((arg) => arg) ? {
+				...node,
+				args
+			} : void 0;
+		}
+		case "not": {
+			const arg = checkNode(ctx, node.arg);
+			return arg && {
+				...node,
+				arg
+			};
+		}
+		case "compare": return checkCompare(ctx, node);
+		case "has": return checkHas(ctx, node);
+		case "in": return checkIn(ctx, node);
+		case "search":
+			if (ctx.model.search?.length) return node;
+			ctx.errors.push(filterError("no-search-fields", "This resource has no search fields", "Declare them with .search((r) => [r.title]) in data.ts", node.span));
+			return;
+		case "present":
+		case "isNull": {
+			const field = resolveField(ctx, node.field, "filterable");
+			return field && {
+				...node,
+				field
+			};
+		}
+		case "similar":
+		case "regex": {
+			const field = checkText(ctx, node.kind, node.field);
+			return field && {
+				...node,
+				field
+			};
+		}
+	}
+};
+const checkAgainstModel = (model, ast) => {
+	const ctx = {
+		model,
+		errors: []
+	};
+	const filter = checkNode(ctx, ast);
+	if (!filter || ctx.errors.length > 0) return {
+		ok: false,
+		errors: [...ctx.errors].sort((a, b) => a.span.start - b.span.start)
+	};
+	return {
+		ok: true,
+		filter
+	};
+};
+//#endregion
+export { checkAgainstModel };

package/dist/filter/check-value.js

@@ -0,0 +1,64 @@
+import { isValidDate, isValidTimestamp } from "./datetime.js";
+//#region src/filter/check-value.ts
+const problem = (message, hint) => ({
+	message,
+	hint
+});
+const int64Min = -(2n ** 63n);
+const int64Max = 2n ** 63n - 1n;
+const uuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const numericText = (value) => value.kind === "number" ? value.raw : value.kind === "string" ? value.value : void 0;
+const expected = (what, hint = `Write ${what} values like the examples in the docs`) => problem(`Expected ${what}`, hint);
+const checkInteger = (value) => {
+	const text = numericText(value);
+	const number = text === void 0 ? NaN : Number(text);
+	if (text === void 0 || text.trim() === "" || !Number.isSafeInteger(number)) return expected("a whole number", "Use an integer such as 42, or a bigint field for larger values");
+};
+const checkBigint = (value) => {
+	const text = numericText(value);
+	if (text === void 0 || !/^-?\d+$/.test(text) || BigInt(text) < int64Min || BigInt(text) > int64Max) return expected("a 64-bit integer", "Use plain digits such as 9007199254740993 (no exponent or fraction)");
+};
+const checkDecimal = (value) => {
+	const text = numericText(value);
+	if (text === void 0 || !/^-?\d+(\.\d+)?$/.test(text)) return expected("a decimal number", "Use plain digits such as 100.50, or quote it: \"100.50\" (no exponent)");
+};
+const checkValue = (field, value) => {
+	if (value.kind === "now") {
+		if (field.type === "date" || field.type === "timestamp") return void 0;
+		return problem("now() only works with date and timestamp fields", `Field "${field.name}" is ${field.type}`);
+	}
+	switch (field.type) {
+		case "text":
+			if (value.kind !== "string") return expected("a quoted string", "Wrap the text in double quotes");
+			return;
+		case "integer": return checkInteger(value);
+		case "bigint": return checkBigint(value);
+		case "decimal": return checkDecimal(value);
+		case "boolean": return value.kind === "boolean" ? void 0 : expected("true or false");
+		case "date":
+			if (value.kind === "string" && isValidDate(value.value)) return void 0;
+			return expected("a date", "Quote a calendar date: \"2012-04-21\"");
+		case "timestamp":
+			if (value.kind === "timestamp" || value.kind === "string" && isValidTimestamp(value.value)) return void 0;
+			return expected("an RFC-3339 timestamp", "Use 2012-04-21T11:30:00Z, or now() - 7d");
+		case "uuid":
+			if (value.kind === "string" && uuid.test(value.value)) return void 0;
+			return expected("a uuid", "Quote a uuid like \"0b5a4f0e-6f2a-4a3c-9d4e-1f2a3b4c5d6e\"");
+		case "enum":
+			if (value.kind === "string" && field.enumValues?.includes(value.value)) return void 0;
+			return problem("Invalid enum value", `Allowed values: ${(field.enumValues ?? []).join(", ")}`);
+		case "currency":
+			if (value.kind === "string" && /^[A-Z]{3}$/.test(value.value)) return void 0;
+			return expected("an ISO 4217 currency code", "Use three capital letters, for example \"EUR\"");
+		case "country":
+			if (value.kind === "string" && /^[A-Z]{2}$/.test(value.value)) return void 0;
+			return expected("an ISO 3166-1 country code", "Use two capital letters, for example \"NL\"");
+		case "relation":
+			if (value.kind === "string" || value.kind === "number" && Number.isSafeInteger(value.value)) return void 0;
+			return expected("a record key", "Use the related record key: 42 or \"abc\"");
+		case "json":
+		case "file": return problem(`${field.type} fields cannot be compared`, "Use field:value on json fields, or isNull(field)");
+	}
+};
+//#endregion
+export { checkValue };

package/dist/filter/check.d.ts

@@ -0,0 +1,16 @@
+import { CheckedFilter, FilterError, FilterExpr, ResourceModel } from "../model.js";
+//#region src/filter/check.d.ts
+export type CheckResult = {
+  ok: true;
+  filter: CheckedFilter;
+} | {
+  ok: false;
+  errors: FilterError[];
+};
+/**
+ * Validates against the resource: the library checks fields, aliases, filterability, enum
+ * values, operators and function signatures; the model pass then checks the value formats the
+ * library cannot know (decimal, bigint, uuid, date, ...), traversal and search fields.
+ */
+export declare const checkFilter: (model: ResourceModel, ast: FilterExpr) => CheckResult;
+//#endregion

package/dist/filter/check.js

@@ -0,0 +1,22 @@
+import { schemaOf } from "./profile.js";
+import { checkAgainstModel } from "./check-model.js";
+import { lift } from "./lift.js";
+import { checkFilter } from "aip-parsers/filter";
+//#region src/filter/check.ts
+/**
+* Validates against the resource: the library checks fields, aliases, filterability, enum
+* values, operators and function signatures; the model pass then checks the value formats the
+* library cannot know (decimal, bigint, uuid, date, ...), traversal and search fields.
+*/
+const checkFilter$1 = (model, ast) => {
+	const traversal = checkAgainstModel(model, ast);
+	if (!traversal.ok && traversal.errors.some((e) => e.code === "unsupported-traversal")) return traversal;
+	const generic = checkFilter(lift(ast), schemaOf(model));
+	if (!generic.ok) return {
+		ok: false,
+		errors: generic.errors
+	};
+	return checkAgainstModel(model, ast);
+};
+//#endregion
+export { checkFilter$1 as checkFilter };

package/dist/filter/datetime.js

@@ -0,0 +1,33 @@
+//#region src/filter/datetime.ts
+const daysIn = (year, month) => {
+	if (month === 2) return year % 4 === 0 && (year % 100 !== 0 || year % 400 === 0) ? 29 : 28;
+	return [
+		4,
+		6,
+		9,
+		11
+	].includes(month) ? 30 : 31;
+};
+const isValidDate = (text) => {
+	const match = /^(\d{4})-(\d{2})-(\d{2})$/.exec(text);
+	if (!match) return false;
+	const [year, month, day] = [
+		Number(match[1]),
+		Number(match[2]),
+		Number(match[3])
+	];
+	return month >= 1 && month <= 12 && day >= 1 && day <= daysIn(year, month);
+};
+const isValidTimestamp = (text) => {
+	const match = /^(\d{4}-\d{2}-\d{2})[Tt](\d{2}):(\d{2}):(\d{2})(?:\.\d+)?(?:[Zz]|[+-](\d{2}):(\d{2}))$/.exec(text);
+	if (!match) return false;
+	const [hour, minute, second] = [
+		Number(match[2]),
+		Number(match[3]),
+		Number(match[4])
+	];
+	const [offsetHour, offsetMinute] = [Number(match[5] ?? 0), Number(match[6] ?? 0)];
+	return isValidDate(match[1]) && hour <= 23 && minute <= 59 && second <= 59 && offsetHour <= 23 && offsetMinute <= 59;
+};
+//#endregion
+export { isValidDate, isValidTimestamp };

package/dist/filter/duration.js

@@ -0,0 +1,16 @@
+//#region src/filter/duration.ts
+const parseDurationText = (text) => {
+	const match = /^(\d+(?:\.\d+)?(?:[eE][+-]?\d+)?)([smhdw])$/.exec(text);
+	if (!match) throw new Error(`Invalid duration "${text}", expected for example 30d or 1.5h`);
+	return {
+		kind: "duration",
+		amount: Number(match[1]),
+		unit: match[2],
+		span: {
+			start: 0,
+			end: 0
+		}
+	};
+};
+//#endregion
+export { parseDurationText };

package/dist/filter/errors.js

@@ -0,0 +1,29 @@
+//#region src/filter/errors.ts
+const filterError = (code, message, hint, span) => ({
+	code,
+	message,
+	hint,
+	span
+});
+const distance = (a, b) => {
+	let row = Array.from({ length: b.length + 1 }, (_, i) => i);
+	for (let i = 1; i <= a.length; i++) {
+		const next = [i];
+		for (let j = 1; j <= b.length; j++) {
+			const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+			next[j] = Math.min(row[j] + 1, next[j - 1] + 1, row[j - 1] + cost);
+		}
+		row = next;
+	}
+	return row[b.length];
+};
+const suggest = (name, candidates) => {
+	const lower = name.toLowerCase();
+	const scored = candidates.map((candidate) => ({
+		candidate,
+		score: distance(lower, candidate.toLowerCase())
+	})).sort((a, b) => a.score - b.score)[0];
+	return scored && scored.score <= Math.max(2, Math.floor(name.length / 3)) ? scored.candidate : void 0;
+};
+//#endregion
+export { filterError, suggest };

package/dist/filter/evaluate.d.ts

@@ -0,0 +1,12 @@
+import { CheckedFilter } from "../model.js";
+//#region src/filter/evaluate.d.ts
+export type EvaluateOptions = {
+  /** Clock for `now()`; defaults to the current time. */
+  now?: () => Date;
+};
+/**
+ * Evaluates a checked filter against a plain record keyed by field name, for rules such as
+ * access filters on create. Throws `Not implemented` for `search` and `similar`.
+ */
+export declare const evaluateFilter: (checked: CheckedFilter, record: unknown, options?: EvaluateOptions) => boolean;
+//#endregion

package/dist/filter/evaluate.js

@@ -0,0 +1,33 @@
+import { functions } from "./profile.js";
+import { lift } from "./lift.js";
+import { evaluateFilter } from "aip-parsers/filter";
+//#region src/filter/evaluate.ts
+const needsDatabase = (name) => () => {
+	throw new Error(`Not implemented: ${name}() needs the database (the resource's search fields, trigram matching), so it cannot be evaluated against a record`);
+};
+const implementations = (now) => ({
+	...functions,
+	search: {
+		...functions.search,
+		evaluate: needsDatabase("search")
+	},
+	similar: {
+		...functions.similar,
+		evaluate: needsDatabase("similar")
+	},
+	regex: {
+		...functions.regex,
+		evaluate: (values, pattern) => values.some((value) => typeof value === "string" && new RegExp(pattern).test(value))
+	},
+	now: {
+		...functions.now,
+		evaluate: now
+	}
+});
+/**
+* Evaluates a checked filter against a plain record keyed by field name, for rules such as
+* access filters on create. Throws `Not implemented` for `search` and `similar`.
+*/
+const evaluateFilter$1 = (checked, record, options = {}) => evaluateFilter(lift(checked, { expand: true }), record, { functions: implementations(options.now ?? (() => /* @__PURE__ */ new Date())) });
+//#endregion
+export { evaluateFilter$1 as evaluateFilter };

package/dist/filter/index.d.ts

@@ -0,0 +1,7 @@
+import { FilterLimits, FilterParse, parseFilter } from "./parse.js";
+import { CheckResult, checkFilter } from "./check.js";
+import { EvaluateOptions, evaluateFilter } from "./evaluate.js";
+import { printFilter } from "./print.js";
+import { OrderByCheck, OrderByParse, checkOrderBy, parseOrderBy, printOrderBy } from "./order-by.js";
+import { createWhere, where } from "./where.js";
+export { type CheckResult, type EvaluateOptions, type FilterLimits, type FilterParse, type OrderByCheck, type OrderByParse, checkFilter, checkOrderBy, createWhere, evaluateFilter, parseFilter, parseOrderBy, printFilter, printOrderBy, where };

package/dist/filter/lift.js

@@ -0,0 +1,107 @@
+import { libraryType } from "./profile.js";
+//#region src/filter/lift.ts
+const member = (field, span) => "path" in field ? {
+	kind: "member",
+	path: field.path,
+	span: field.span
+} : {
+	kind: "member",
+	path: [field.name],
+	field: {
+		name: field.name,
+		spec: { type: libraryType(field) }
+	},
+	span
+};
+const call = (name, args, span) => ({
+	kind: "call",
+	name,
+	args,
+	span
+});
+const text = (value, span) => ({
+	kind: "string",
+	value,
+	span
+});
+const value = (node) => {
+	if (node.kind !== "now") return node;
+	const now = {
+		kind: "call",
+		name: "now",
+		args: [],
+		span: node.span
+	};
+	if (!node.offset) return now;
+	return {
+		kind: "binary",
+		op: node.offset.sign,
+		left: now,
+		right: node.offset.duration,
+		span: node.span
+	};
+};
+/** Protobase's filter shape as a generic AIP-160 expression, for checking, printing and evaluating. */
+const lift = (node, options = {}) => {
+	const next = (child) => lift(child, options);
+	switch (node.kind) {
+		case "and":
+		case "or": return {
+			kind: node.kind,
+			args: node.args.map(next),
+			span: node.span
+		};
+		case "not": return {
+			kind: "not",
+			arg: next(node.arg),
+			span: node.span
+		};
+		case "compare": return {
+			kind: "compare",
+			op: node.op,
+			left: member(node.field, node.span),
+			right: value(node.value),
+			span: node.span
+		};
+		case "has": return {
+			kind: "has",
+			left: member(node.field, node.span),
+			right: node.value,
+			span: node.span
+		};
+		case "present": return {
+			kind: "present",
+			left: member(node.field, node.span),
+			span: node.span
+		};
+		case "in":
+			if (options.expand) return {
+				kind: "or",
+				args: node.values.map((literal) => ({
+					kind: "compare",
+					op: "=",
+					left: member(node.field, node.span),
+					right: literal,
+					span: node.span
+				})),
+				span: node.span
+			};
+			return call("in", [member(node.field, node.span), ...node.values], node.span);
+		case "search": return call("search", [text(node.text, node.span)], node.span);
+		case "similar": return call("similar", [member(node.field, node.span), text(node.text, node.span)], node.span);
+		case "regex": return call("regex", [member(node.field, node.span), text(node.pattern, node.span)], node.span);
+		case "isNull":
+			if (options.expand) return {
+				kind: "not",
+				arg: {
+					kind: "present",
+					left: member(node.field, node.span),
+					span: node.span
+				},
+				span: node.span
+			};
+			return call("isNull", [member(node.field, node.span)], node.span);
+	}
+};
+//#endregion
+export { lift };

package/dist/filter/lower.js

@@ -0,0 +1,170 @@
+import { filterError } from "./errors.js";
+import { functions } from "./profile.js";
+//#region src/filter/lower.ts
+const unsupported = (l, message, hint, span) => {
+	l.errors.push(filterError("unsupported", message, hint, span));
+};
+const fieldOf = (l, node) => node.kind === "member" ? {
+	kind: "field",
+	path: node.path,
+	span: node.span
+} : unsupported(l, "Only fields can be compared", "Put a field name on the left, for example total > 100", node.span);
+const valueOf = (l, node) => {
+	switch (node.kind) {
+		case "member": return {
+			kind: "string",
+			value: node.path.join("."),
+			span: node.span
+		};
+		case "call":
+			if (node.name === "now" && node.args.length === 0) return {
+				kind: "now",
+				span: node.span
+			};
+			return unsupported(l, `${node.name}() cannot be used as a value`, "Only now() is a value function", node.span);
+		case "binary": {
+			const left = node.left;
+			if (left.kind === "call" && left.name === "now" && left.args.length === 0 && node.right.kind === "duration") return {
+				kind: "now",
+				offset: {
+					sign: node.op,
+					duration: node.right
+				},
+				span: node.span
+			};
+			return unsupported(l, "Arithmetic is only supported as now() +/- duration", "Write now() - 30d", node.span);
+		}
+		default: return node;
+	}
+};
+const literalOf = (l, node) => {
+	const value = "kind" in node && [
+		"member",
+		"call",
+		"binary"
+	].includes(node.kind) ? void 0 : node;
+	if (value) return value;
+	if (node.kind === "member") return {
+		kind: "string",
+		value: node.path.join("."),
+		span: node.span
+	};
+	return unsupported(l, "Expected a literal value", "Use strings, numbers, true/false, durations or timestamps", node.span);
+};
+const wordOf = (node) => {
+	switch (node.kind) {
+		case "member": return node.path.join(".");
+		case "string":
+		case "timestamp": return node.kind === "string" ? node.value : node.value;
+		case "number": return node.raw;
+		case "boolean": return String(node.value);
+		case "duration": return `${node.amount}${node.unit}`;
+		default: return "";
+	}
+};
+const lowerCall = (l, node) => {
+	const [first, second, ...rest] = node.args;
+	const field = first?.kind === "member" ? fieldOf(l, first) : void 0;
+	const string = (arg) => arg?.kind === "string" ? arg.value : void 0;
+	const bad = (usage) => {
+		l.errors.push(filterError("invalid-arguments", `Invalid arguments to ${node.name}()`, `Usage: ${usage}`, node.span));
+	};
+	switch (node.name) {
+		case "in": {
+			const values = node.args.slice(1).map((arg) => literalOf(l, arg));
+			if (!field || values.length === 0) return bad("in(field, value1, value2, ...)");
+			return values.every((v) => v) ? {
+				kind: "in",
+				field,
+				values,
+				span: node.span
+			} : void 0;
+		}
+		case "search": return string(first) !== void 0 && !second ? {
+			kind: "search",
+			text: string(first),
+			span: node.span
+		} : bad("search(\"text\")");
+		case "similar": return field && string(second) !== void 0 && rest.length === 0 ? {
+			kind: "similar",
+			field,
+			text: string(second),
+			span: node.span
+		} : bad("similar(field, \"text\")");
+		case "regex": return field && string(second) !== void 0 && rest.length === 0 ? {
+			kind: "regex",
+			field,
+			pattern: string(second),
+			span: node.span
+		} : bad("regex(field, \"pattern\")");
+		case "isNull": return field && !second ? {
+			kind: "isNull",
+			field,
+			span: node.span
+		} : bad("isNull(field)");
+		default:
+			l.errors.push(filterError("unknown-function", `Unknown function "${node.name}"`, `Available functions: ${Object.keys(functions).join(", ")}`, node.span));
+			return;
+	}
+};
+const all = (items) => items.every((item) => item) ? items : void 0;
+/** Lowers a generic AIP-160 expression to Protobase's filter shape; unsupported constructs become errors. */
+const lower = (l, node) => {
+	switch (node.kind) {
+		case "sequence":
+		case "and":
+		case "or": {
+			const args = all(node.args.map((arg) => lower(l, arg)));
+			return args && {
+				kind: node.kind === "or" ? "or" : "and",
+				args,
+				span: node.span
+			};
+		}
+		case "not": {
+			const arg = lower(l, node.arg);
+			return arg && {
+				kind: "not",
+				arg,
+				span: node.span
+			};
+		}
+		case "compare": {
+			const field = fieldOf(l, node.left);
+			const value = valueOf(l, node.right);
+			return field && value && {
+				kind: "compare",
+				op: node.op,
+				field,
+				value,
+				span: node.span
+			};
+		}
+		case "has": {
+			const field = fieldOf(l, node.left);
+			const value = literalOf(l, node.right);
+			return field && value && {
+				kind: "has",
+				field,
+				value,
+				span: node.span
+			};
+		}
+		case "present": {
+			const field = fieldOf(l, node.left);
+			return field && {
+				kind: "present",
+				field,
+				span: node.span
+			};
+		}
+		case "global": return {
+			kind: "search",
+			text: wordOf(node.value),
+			span: node.span
+		};
+		case "call": return lowerCall(l, node);
+	}
+};
+//#endregion
+export { lower };

package/dist/filter/operators.js

@@ -0,0 +1,26 @@
+//#region src/filter/operators.ts
+const equality = ["=", "!="];
+const ordered = [
+	"=",
+	"!=",
+	"<",
+	"<=",
+	">",
+	">="
+];
+const compareOps = (type) => {
+	switch (type) {
+		case "text":
+		case "integer":
+		case "bigint":
+		case "decimal":
+		case "date":
+		case "timestamp": return ordered;
+		case "json":
+		case "file": return [];
+		default: return equality;
+	}
+};
+const isOpaque = (type) => type === "json" || type === "file";
+//#endregion
+export { compareOps, isOpaque };