@protobase/schema 0.0.0-stage → 0.1.0

package/dist/filter/order-by.d.ts

@@ -0,0 +1,23 @@
+import { FilterError, OrderByItem, ResourceModel, SortSpec } from "../model.js";
+//#region src/filter/order-by.d.ts
+export type OrderByParse = {
+  ok: true;
+  items: OrderByItem[];
+  errors: [];
+} | {
+  ok: false;
+  items: OrderByItem[];
+  errors: FilterError[];
+};
+export type OrderByCheck = {
+  ok: true;
+  sort: SortSpec;
+} | {
+  ok: false;
+  errors: FilterError[];
+};
+export declare const parseOrderBy: (source: string) => OrderByParse;
+export declare const printOrderBy: (items: OrderByItem[]) => string;
+/** Validates against sortable fields; traversal is not supported yet. */
+export declare const checkOrderBy: (model: ResourceModel, items: OrderByItem[]) => OrderByCheck;
+//#endregion

package/dist/filter/order-by.js

@@ -0,0 +1,51 @@
+import { filterError } from "./errors.js";
+import { schemaOf } from "./profile.js";
+import { checkOrderBy, parseOrderBy, printOrderBy } from "aip-parsers/order-by";
+//#region src/filter/order-by.ts
+const generic = (items) => items.map((item) => ({
+	path: item.path.path,
+	direction: item.direction,
+	span: item.span
+}));
+const lowercaseDirections = (source) => source.replace(/([^\s,])(\s+)(asc|desc)(?=\s|,|$)/gi, (_, before, space, word) => `${before}${space}${word.toLowerCase()}`);
+const parseOrderBy$1 = (source) => {
+	const parsed = parseOrderBy(lowercaseDirections(source));
+	const items = parsed.items.map((item) => ({
+		path: {
+			kind: "field",
+			path: item.path,
+			span: item.span
+		},
+		direction: item.direction,
+		span: item.span
+	}));
+	return parsed.ok ? {
+		ok: true,
+		items,
+		errors: []
+	} : {
+		ok: false,
+		items,
+		errors: parsed.errors
+	};
+};
+const printOrderBy$1 = (items) => printOrderBy(generic(items));
+/** Validates against sortable fields; traversal is not supported yet. */
+const checkOrderBy$1 = (model, items) => {
+	const traversal = items.filter((item) => item.path.path.length > 1).map((item) => filterError("unsupported-traversal", `Traversal into "${item.path.path.join(".")}" is not supported yet`, "Sort on fields of this resource only", item.path.span));
+	if (traversal.length > 0) return {
+		ok: false,
+		errors: traversal
+	};
+	const checked = checkOrderBy(generic(items), schemaOf(model));
+	if (!checked.ok) return {
+		ok: false,
+		errors: checked.errors
+	};
+	return {
+		ok: true,
+		sort: checked.items.map((item) => [item.path[0], item.direction])
+	};
+};
+//#endregion
+export { checkOrderBy$1 as checkOrderBy, parseOrderBy$1 as parseOrderBy, printOrderBy$1 as printOrderBy };

package/dist/filter/parse.d.ts

@@ -0,0 +1,20 @@
+import { FilterError, FilterExpr } from "../model.js";
+import { ParseOptions } from "aip-parsers/filter";
+//#region src/filter/parse.d.ts
+export type FilterParse = {
+  ok: true;
+  ast: FilterExpr | undefined;
+  errors: [];
+} | {
+  ok: false;
+  ast: FilterExpr | undefined;
+  errors: FilterError[];
+};
+export type FilterLimits = Pick<ParseOptions, 'maxLength' | 'maxDepth'>;
+/**
+ * Parses with the library, then lowers to Protobase's filter shape. Collects all errors.
+ * `maxLength` defaults to 10,000 characters and `maxDepth` to 64.
+ */
+declare const parseFilter$1: (source: string, limits?: FilterLimits) => FilterParse;
+//#endregion
+export { parseFilter$1 as parseFilter };

package/dist/filter/parse.js

@@ -0,0 +1,28 @@
+import { parseOptions } from "./profile.js";
+import { lower } from "./lower.js";
+import { parseFilter } from "aip-parsers/filter";
+//#region src/filter/parse.ts
+/**
+* Parses with the library, then lowers to Protobase's filter shape. Collects all errors.
+* `maxLength` defaults to 10,000 characters and `maxDepth` to 64.
+*/
+const parseFilter$1 = (source, limits = {}) => {
+	const parsed = parseFilter(source, {
+		...parseOptions,
+		...limits
+	});
+	const lowering = { errors: [] };
+	const ast = parsed.ast && lower(lowering, parsed.ast);
+	const errors = [...parsed.errors, ...lowering.errors].sort((a, b) => a.span.start - b.span.start);
+	return errors.length === 0 ? {
+		ok: true,
+		ast,
+		errors: []
+	} : {
+		ok: false,
+		ast,
+		errors
+	};
+};
+//#endregion
+export { parseFilter$1 as parseFilter };

package/dist/filter/print.d.ts

@@ -0,0 +1,5 @@
+import { FilterExpr } from "../model.js";
+//#region src/filter/print.d.ts
+/** Canonical text, readable by `parseFilter`; OR groups inside AND are always parenthesised. */
+export declare const printFilter: (ast: FilterExpr) => string;
+//#endregion

package/dist/filter/print.js

@@ -0,0 +1,7 @@
+import { lift } from "./lift.js";
+import { printFilter } from "aip-parsers/filter";
+//#region src/filter/print.ts
+/** Canonical text, readable by `parseFilter`; OR groups inside AND are always parenthesised. */
+const printFilter$1 = (ast) => printFilter(lift(ast));
+//#endregion
+export { printFilter$1 as printFilter };

package/dist/filter/profile.js

@@ -0,0 +1,69 @@
+//#region src/filter/profile.ts
+/** Protobase's filter functions, declared through the library's registry. */
+const functions = {
+	in: {
+		params: [{
+			name: "field",
+			type: "field"
+		}],
+		rest: {
+			name: "value",
+			type: "any"
+		}
+	},
+	search: { params: [{
+		name: "text",
+		type: "string"
+	}] },
+	similar: { params: [{
+		name: "field",
+		type: "field",
+		of: ["string"]
+	}, {
+		name: "text",
+		type: "string"
+	}] },
+	regex: { params: [{
+		name: "field",
+		type: "field",
+		of: ["string"]
+	}, {
+		name: "pattern",
+		type: "string"
+	}] },
+	isNull: { params: [{
+		name: "field",
+		type: "field"
+	}] },
+	now: {
+		params: [],
+		returns: "timestamp"
+	}
+};
+const parseOptions = { extensions: {
+	arithmetic: "now-offset",
+	durationUnits: true
+} };
+const libraryType = (field) => {
+	switch (field.type) {
+		case "text": return "string";
+		case "integer":
+		case "bigint": return "integer";
+		case "boolean":
+		case "timestamp":
+		case "enum": return field.type;
+		default: return "any";
+	}
+};
+const schemaOf = (model) => ({
+	fields: Object.fromEntries(Object.values(model.fields).map((field) => [field.name, {
+		type: libraryType(field),
+		filterable: field.filterable,
+		sortable: field.sortable,
+		aliases: field.aliases,
+		...field.enumValues && { values: field.enumValues }
+	}])),
+	functions
+});
+//#endregion
+export { functions, libraryType, parseOptions, schemaOf };

package/dist/filter/where.d.ts

@@ -0,0 +1,58 @@
+import { FilterExpr, FilterValue } from "../model.js";
+import { Field } from "../field.js";
+import { RecordOf } from "../resource-types.js";
+//#region src/filter/where.d.ts
+type Scalar = string | number | boolean;
+type Source = {
+  readonly $fields: unknown;
+};
+type Fields<R extends Source> = keyof RecordOf<R['$fields']> & string;
+type Value<R extends Source, K extends Fields<R>> = Extract<NonNullable<RecordOf<R['$fields']>[K]>, Scalar> | FilterValue;
+type Anything = {
+  readonly $fields: Record<string, Field<any>>;
+};
+export declare const createWhere: <R extends Source = Anything>() => {
+  eq: <K extends Fields<R>>(name: K, value: Value<R, K>) => FilterExpr;
+  ne: <K extends Fields<R>>(name: K, value: Value<R, K>) => FilterExpr;
+  lt: <K extends Fields<R>>(name: K, value: Value<R, K>) => FilterExpr;
+  lte: <K extends Fields<R>>(name: K, value: Value<R, K>) => FilterExpr;
+  gt: <K extends Fields<R>>(name: K, value: Value<R, K>) => FilterExpr;
+  gte: <K extends Fields<R>>(name: K, value: Value<R, K>) => FilterExpr;
+  between: <K extends Fields<R>>(name: K, low: Value<R, K>, high: Value<R, K>) => FilterExpr;
+  has: <K extends Fields<R>>(name: K, value: Scalar) => FilterExpr;
+  present: <K extends Fields<R>>(name: K) => FilterExpr;
+  in: <K extends Fields<R>>(name: K, values: Extract<NonNullable<RecordOf<R["$fields"]>[K]>, Scalar>[]) => FilterExpr;
+  isNull: <K extends Fields<R>>(name: K) => FilterExpr;
+  search: (text: string) => FilterExpr;
+  similar: <K extends Fields<R>>(name: K, text: string) => FilterExpr;
+  regex: <K extends Fields<R>>(name: K, pattern: string) => FilterExpr;
+  and: (...args: FilterExpr[]) => FilterExpr;
+  or: (...args: FilterExpr[]) => FilterExpr;
+  not: (arg: FilterExpr) => FilterExpr;
+  now: () => FilterValue;
+  ago: (duration: string) => FilterValue;
+  fromNow: (duration: string) => FilterValue;
+};
+export declare const where: {
+  eq: <K extends string>(name: K, value: any) => FilterExpr;
+  ne: <K extends string>(name: K, value: any) => FilterExpr;
+  lt: <K extends string>(name: K, value: any) => FilterExpr;
+  lte: <K extends string>(name: K, value: any) => FilterExpr;
+  gt: <K extends string>(name: K, value: any) => FilterExpr;
+  gte: <K extends string>(name: K, value: any) => FilterExpr;
+  between: <K extends string>(name: K, low: any, high: any) => FilterExpr;
+  has: <K extends string>(name: K, value: Scalar) => FilterExpr;
+  present: <K extends string>(name: K) => FilterExpr;
+  in: <K extends string>(name: K, values: any[]) => FilterExpr;
+  isNull: <K extends string>(name: K) => FilterExpr;
+  search: (text: string) => FilterExpr;
+  similar: <K extends string>(name: K, text: string) => FilterExpr;
+  regex: <K extends string>(name: K, pattern: string) => FilterExpr;
+  and: (...args: FilterExpr[]) => FilterExpr;
+  or: (...args: FilterExpr[]) => FilterExpr;
+  not: (arg: FilterExpr) => FilterExpr;
+  now: () => FilterValue;
+  ago: (duration: string) => FilterValue;
+  fromNow: (duration: string) => FilterValue;
+};
+//#endregion

package/dist/filter/where.js

@@ -0,0 +1,121 @@
+import { parseDurationText } from "./duration.js";
+//#region src/filter/where.ts
+const span = {
+	start: 0,
+	end: 0
+};
+const field = (name) => ({
+	kind: "field",
+	path: name.split("."),
+	span
+});
+const literal = (value) => {
+	if (typeof value === "string") return {
+		kind: "string",
+		value,
+		span
+	};
+	if (typeof value === "boolean") return {
+		kind: "boolean",
+		value,
+		span
+	};
+	if (!Number.isFinite(value)) throw new Error("Filter numbers must be finite");
+	return {
+		kind: "number",
+		value,
+		raw: String(value),
+		span
+	};
+};
+const filterValue = (value) => typeof value === "object" ? value : literal(value);
+const group = (kind, args) => {
+	if (args.length === 0) throw new Error(`where.${kind} needs at least one filter`);
+	if (args.length === 1) return args[0];
+	return {
+		kind,
+		args,
+		span
+	};
+};
+const createWhere = () => {
+	const compare = (op) => (name, value) => ({
+		kind: "compare",
+		op,
+		field: field(name),
+		value: filterValue(value),
+		span
+	});
+	const offset = (sign) => (duration) => ({
+		kind: "now",
+		offset: {
+			sign,
+			duration: parseDurationText(duration)
+		},
+		span
+	});
+	return {
+		eq: compare("="),
+		ne: compare("!="),
+		lt: compare("<"),
+		lte: compare("<="),
+		gt: compare(">"),
+		gte: compare(">="),
+		between: (name, low, high) => group("and", [compare(">=")(name, low), compare("<=")(name, high)]),
+		has: (name, value) => ({
+			kind: "has",
+			field: field(name),
+			value: literal(value),
+			span
+		}),
+		present: (name) => ({
+			kind: "present",
+			field: field(name),
+			span
+		}),
+		in: (name, values) => ({
+			kind: "in",
+			field: field(name),
+			values: values.map(literal),
+			span
+		}),
+		isNull: (name) => ({
+			kind: "isNull",
+			field: field(name),
+			span
+		}),
+		search: (text) => ({
+			kind: "search",
+			text,
+			span
+		}),
+		similar: (name, text) => ({
+			kind: "similar",
+			field: field(name),
+			text,
+			span
+		}),
+		regex: (name, pattern) => ({
+			kind: "regex",
+			field: field(name),
+			pattern,
+			span
+		}),
+		and: (...args) => group("and", args),
+		or: (...args) => group("or", args),
+		not: (arg) => ({
+			kind: "not",
+			arg,
+			span
+		}),
+		now: () => ({
+			kind: "now",
+			span
+		}),
+		ago: offset("-"),
+		fromNow: offset("+")
+	};
+};
+const where = createWhere();
+//#endregion
+export { createWhere, where };

package/dist/index.d.ts

@@ -0,0 +1,28 @@
+import { ActionModel, ActionRun, ChartGranularity, ChartModel, ChartRange, CheckedFilter, CompareOp, DatePreset, DurationLiteral, DurationUnit, FieldFormat, FieldModel, FieldPath, FieldType, FieldViewModel, FilterError, FilterErrorCode, FilterExpr, FilterOf, FilterValue, FilterWidgetModel, KeyValue, LayoutItemModel, ListModel, ListQuery, Literal, NavModel, NavRecentModel, NowValue, OrderByItem, RelatedModel, ResourceModel, SaveFeedback, SearchMatch, SearchResultModel, SortSpec, Span, StatusTone, UserMenuItemModel, UserMenuModel, ViewModel } from "./model.js";
+import { AccessAction, AccessContext, AccessFn, AccessResult, AccessUser, FieldAccess, FieldRule } from "./access/types.js";
+import { Field } from "./field.js";
+import { f } from "./fields.js";
+import { InferRecord, RecordKey } from "./resource-types.js";
+import { resource } from "./resource.js";
+import { view } from "./view.js";
+import { enumLabel } from "./enum-label.js";
+import { SearchTerm, matchedSearchField, matchesSearch, searchTerms, termMatches } from "./search-match.js";
+import { defaultRecentLimit, navRecentErrors, statusTones } from "./nav-recent.js";
+import { UserMenuSource, userMenu } from "./user-menu.js";
+import { layout } from "./layout.js";
+import { KeyType, decodeKey, encodeKey, keyTypes } from "./keys.js";
+import { FilterLimits, FilterParse, parseFilter } from "./filter/parse.js";
+import { CheckResult, checkFilter } from "./filter/check.js";
+import { EvaluateOptions, evaluateFilter } from "./filter/evaluate.js";
+import { printFilter } from "./filter/print.js";
+import { OrderByCheck, OrderByParse, checkOrderBy, parseOrderBy, printOrderBy } from "./filter/order-by.js";
+import { createWhere, where } from "./filter/where.js";
+import "./filter/index.js";
+import { Capability, CapabilityAction, CapabilityScope } from "./access/capability.js";
+import { Rule, rule } from "./access/rule.js";
+import { Roles, RolesOptions, defineRoles } from "./access/roles.js";
+import { pickView } from "./access/pick-view.js";
+import { AccessSource, ResolveOptions, ResolvedAccess, RowFilterOperation, accessWarnings, checkRecord, fieldsUsedBy, resolveAccess } from "./access/resolve.js";
+import { restrictModel } from "./access/restrict.js";
+import "./access/index.js";
+export { type AccessAction, type AccessContext, type AccessFn, type AccessResult, type AccessSource, type AccessUser, type ActionModel, type ActionRun, type Capability, type CapabilityAction, type CapabilityScope, type ChartGranularity, type ChartModel, type ChartRange, type CheckResult, type CheckedFilter, type CompareOp, type DatePreset, type DurationLiteral, type DurationUnit, type EvaluateOptions, type Field, type FieldAccess, type FieldFormat, type FieldModel, type FieldPath, type FieldRule, type FieldType, type FieldViewModel, type FilterError, type FilterErrorCode, type FilterExpr, type FilterLimits, type FilterOf, type FilterParse, type FilterValue, type FilterWidgetModel, type InferRecord, type KeyType, type KeyValue, type LayoutItemModel, type ListModel, type ListQuery, type Literal, type NavModel, type NavRecentModel, type NowValue, type OrderByCheck, type OrderByItem, type OrderByParse, type RecordKey, type RelatedModel, type ResolveOptions, type ResolvedAccess, type ResourceModel, type Roles, type RolesOptions, type RowFilterOperation, type Rule, type SaveFeedback, type SearchMatch, type SearchResultModel, type SearchTerm, type SortSpec, type Span, type StatusTone, type UserMenuItemModel, type UserMenuModel, type UserMenuSource, type ViewModel, accessWarnings, checkFilter, checkOrderBy, checkRecord, createWhere, decodeKey, defaultRecentLimit, defineRoles, encodeKey, enumLabel, evaluateFilter, f, fieldsUsedBy, keyTypes, layout as l, matchedSearchField, matchesSearch, navRecentErrors, parseFilter, parseOrderBy, pickView, printFilter, printOrderBy, resolveAccess, resource, restrictModel, rule, searchTerms, statusTones, termMatches, userMenu, view, where };

package/dist/index.js

@@ -0,0 +1,21 @@
+import { f } from "./fields.js";
+import { resource } from "./resource.js";
+import { parseFilter } from "./filter/parse.js";
+import { checkFilter } from "./filter/check.js";
+import { evaluateFilter } from "./filter/evaluate.js";
+import { printFilter } from "./filter/print.js";
+import { checkOrderBy, parseOrderBy, printOrderBy } from "./filter/order-by.js";
+import { createWhere, where } from "./filter/where.js";
+import { defaultRecentLimit, navRecentErrors, statusTones } from "./nav-recent.js";
+import { view } from "./view.js";
+import { enumLabel } from "./enum-label.js";
+import { matchedSearchField, matchesSearch, searchTerms, termMatches } from "./search-match.js";
+import { userMenu } from "./user-menu.js";
+import { layout } from "./layout.js";
+import { decodeKey, encodeKey, keyTypes } from "./keys.js";
+import { rule } from "./access/rule.js";
+import { defineRoles } from "./access/roles.js";
+import { pickView } from "./access/pick-view.js";
+import { restrictModel } from "./access/restrict.js";
+import { accessWarnings, checkRecord, fieldsUsedBy, resolveAccess } from "./access/resolve.js";
+export { accessWarnings, checkFilter, checkOrderBy, checkRecord, createWhere, decodeKey, defaultRecentLimit, defineRoles, encodeKey, enumLabel, evaluateFilter, f, fieldsUsedBy, keyTypes, layout as l, matchedSearchField, matchesSearch, navRecentErrors, parseFilter, parseOrderBy, pickView, printFilter, printOrderBy, resolveAccess, resource, restrictModel, rule, searchTerms, statusTones, termMatches, userMenu, view, where };

package/dist/keys.d.ts

@@ -0,0 +1,12 @@
+import { FieldType, KeyValue, ResourceModel } from "./model.js";
+//#region src/keys.d.ts
+export type KeyType = Extract<FieldType, 'integer' | 'bigint' | 'uuid' | 'text'>;
+export declare const encodeKey: (key: KeyValue | readonly KeyValue[]) => string;
+export declare const decodeKey: (encoded: string, types: readonly KeyType[]) => string | number | (string | number)[];
+/**
+ * Key part types of a resource's primary key. A relation part takes the key types of the
+ * target resource (a composite target contributes one part per key column), so `resolve`
+ * is required whenever a relation is part of the key.
+ */
+export declare const keyTypes: (model: ResourceModel, resolve?: (resource: string) => ResourceModel | undefined, seen?: string[]) => KeyType[];
+//#endregion

package/dist/keys.js

@@ -0,0 +1,57 @@
+//#region src/keys.ts
+const integerPattern = /^-?\d+$/;
+const uuidPattern = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const decodePart = (part, type) => {
+	if (type === "text") return part;
+	if (type === "uuid") {
+		if (!uuidPattern.test(part)) throw new Error("Invalid uuid key part");
+		return part;
+	}
+	if (!integerPattern.test(part)) throw new Error(`Invalid ${type} key part`);
+	if (type === "bigint") return part;
+	const value = Number(part);
+	if (!Number.isSafeInteger(value)) throw new Error("Invalid integer key part");
+	return value;
+};
+const decodeComponent = (part) => {
+	try {
+		return decodeURIComponent(part);
+	} catch (error) {
+		if (error instanceof URIError) throw new Error("Malformed key encoding");
+		throw error;
+	}
+};
+const encodeKey = (key) => {
+	if (!Array.isArray(key)) return String(key);
+	const parts = key;
+	if (parts.length === 1) return String(parts[0]);
+	return parts.map((part) => encodeURIComponent(String(part))).join(",");
+};
+const decodeKey = (encoded, types) => {
+	if (types.length === 0) throw new Error("A key needs at least one part");
+	if (types.length === 1) return decodePart(encoded, types[0]);
+	const parts = encoded.split(",");
+	if (parts.length !== types.length) throw new Error(`Expected ${types.length} key parts, got ${parts.length}`);
+	return parts.map((part, i) => decodePart(decodeComponent(part), types[i]));
+};
+const scalarKey = (type) => type === "text" || type === "integer" || type === "bigint" || type === "uuid";
+/**
+* Key part types of a resource's primary key. A relation part takes the key types of the
+* target resource (a composite target contributes one part per key column), so `resolve`
+* is required whenever a relation is part of the key.
+*/
+const keyTypes = (model, resolve, seen = []) => model.primaryKey.flatMap((name) => {
+	const field = model.fields[name];
+	if (scalarKey(field?.type)) return [field.type];
+	if (field?.type !== "relation" || !field.relation) throw new Error(`Unsupported primary key type for "${name}"`);
+	const { resource, columns } = field.relation;
+	if (!resolve) throw new Error(`keyTypes needs a resolver for relation "${name}" to "${resource}"`);
+	const target = resolve(resource);
+	if (!target) throw new Error(`Unknown resource "${resource}" for relation "${name}"`);
+	if (seen.includes(target.name)) throw new Error(`Circular primary key through "${resource}"`);
+	const types = keyTypes(target, resolve, [...seen, model.name]);
+	if (types.length !== columns.length) throw new Error(`Relation "${name}" has ${columns.length} column(s) but "${resource}" has a ${types.length}-part key`);
+	return types;
+});
+//#endregion
+export { decodeKey, encodeKey, keyTypes };

package/dist/layout.d.ts

@@ -0,0 +1,12 @@
+import { LayoutItemModel, RelatedModel } from "./model.js";
+import { Ref } from "./refs.js";
+//#region src/layout.d.ts
+export declare const layout: {
+  section: (title: string, fields: Ref[], o?: {
+    help?: string;
+  }) => LayoutItemModel;
+  sidebar: (fields: Ref[]) => LayoutItemModel;
+  /** A table of the records of another resource that point at this one, directly or through a join table. */
+  related: (title: string, o: Omit<RelatedModel, "kind" | "title">) => LayoutItemModel;
+};
+//#endregion

package/dist/layout.js

@@ -0,0 +1,21 @@
+//#region src/layout.ts
+const layout = {
+	section: (title, fields, o = {}) => ({
+		kind: "section",
+		title,
+		fields: fields.map((ref) => ref.name),
+		...o.help !== void 0 && { help: o.help }
+	}),
+	sidebar: (fields) => ({
+		kind: "sidebar",
+		fields: fields.map((ref) => ref.name)
+	}),
+	/** A table of the records of another resource that point at this one, directly or through a join table. */
+	related: (title, o) => ({
+		kind: "related",
+		title,
+		...structuredClone(o)
+	})
+};
+//#endregion
+export { layout };