@protobase/schema 0.0.0-stage → 0.1.1

package/dist/access/roles.js

@@ -0,0 +1,55 @@
+import { orResults, where } from "./combine.js";
+import { grantsOf, parseCapability } from "./capability.js";
+import { rule } from "./rule.js";
+//#region src/access/roles.ts
+const rolesOf = (user) => user.roles ?? [];
+/**
+* Defines roles as bundles of capability strings. Pass the resource and area names as the type
+* parameter to reject unknown names at compile time:
+* `defineRoles<'orders' | 'costs'>({ sales: ['orders.read.own'] })`.
+*/
+const defineRoles = (definitions, options = {}) => {
+	for (const [role, capabilities] of Object.entries(definitions)) for (const capability of capabilities) {
+		const { name } = parseCapability(capability);
+		if (options.names && name !== "*" && !options.names.includes(name)) throw new Error(`Role "${role}" grants "${capability}" but "${name}" is not a known resource or area`);
+	}
+	/** Scopes granted by the user's roles for a capability, without applying them. */
+	const grants = (user, capability) => {
+		const wanted = parseCapability(capability);
+		const held = rolesOf(user).flatMap((role) => definitions[role] ?? []);
+		return new Set(held.flatMap((capability) => grantsOf(capability, wanted)));
+	};
+	const scoped = async (ctx, scope, capability) => {
+		const owner = ctx.model?.owner;
+		if (!owner) throw new Error(`"${capability}" is scoped to ${scope} rows but ${ctx.model ? `resource "${ctx.model.name}" has no .owner(...)` : "the access context has no model"}`);
+		if (scope === "own") return ctx.user?.id === void 0 ? false : where.eq(owner, ctx.user.id);
+		if (!options.teamOf) throw new Error(`"${capability}" needs a teamOf resolver in defineRoles options`);
+		const ids = await options.teamOf(ctx.user ?? {});
+		return ids.length === 0 ? false : where.in(owner, [...ids]);
+	};
+	return {
+		definitions,
+		grants,
+		/** Whether the user holds the capability at all, in any scope. For areas and field rules. */
+		has: (user, capability) => grants(user, capability).size > 0,
+		/**
+		* A rule that allows when the user's roles grant the capability: `true` for an unscoped
+		* grant, a row filter for `.own` and `.team`, `false` otherwise.
+		*/
+		can: (capability) => {
+			parseCapability(capability);
+			return rule(async (ctx) => {
+				const held = grants(ctx.user ?? {}, capability);
+				if (held.has("all")) return true;
+				return (await Promise.all([...held].map((scope) => scoped(ctx, scope, capability)))).reduce((result, filter) => orResults(result, filter), false);
+			});
+		},
+		/** A rule that allows when the user has any of the roles. */
+		is: (...roles) => {
+			for (const role of roles) if (!Object.hasOwn(definitions, role)) throw new Error(`Unknown role "${role}"`);
+			return rule((ctx) => rolesOf(ctx.user ?? {}).some((role) => roles.includes(role)));
+		}
+	};
+};
+//#endregion
+export { defineRoles };

package/dist/access/rule.d.ts

@@ -0,0 +1,11 @@
+import { AccessFn } from "./types.js";
+//#region src/access/rule.d.ts
+/** An access function that can be combined with plain functions or other rules. */
+export type Rule<R = any> = AccessFn<R> & {
+  /** Both must allow; filters are ANDed. */
+  and: (other: AccessFn<R>) => Rule<R>;
+  /** Either may allow; filters are ORed. */
+  or: (other: AccessFn<R>) => Rule<R>;
+};
+export declare const rule: <R = any>(fn: AccessFn<R>) => Rule<R>;
+//#endregion

package/dist/access/rule.js

@@ -0,0 +1,9 @@
+import { andResults, orResults } from "./combine.js";
+//#region src/access/rule.ts
+const combine = (join, left, right) => async (ctx, record, input) => join(await left(ctx, record, input), await right(ctx, record, input));
+const rule = (fn) => Object.assign((ctx, record, input) => fn(ctx, record, input), {
+	and: (other) => rule(combine(andResults, fn, other)),
+	or: (other) => rule(combine(orResults, fn, other))
+});
+//#endregion
+export { rule };

package/dist/access/types.d.ts

@@ -0,0 +1,37 @@
+import { FilterExpr, ResourceModel } from "../model.js";
+//#region src/access/types.d.ts
+export type AccessAction = 'list' | 'read' | 'create' | 'update' | 'delete';
+/** The signed-in user as access rules see it; roles come from the auth user record. */
+export type AccessUser = {
+  id?: string | number;
+  roles?: readonly string[];
+  [key: string]: unknown;
+};
+export type AccessContext = {
+  /** Always set by the server; optional in the type so rules stay callable with a bare context. */
+  user?: AccessUser;
+  operation?: AccessAction;
+  record?: unknown;
+  /** Set by the resolver; scoped capabilities (`.own`) need `model.owner`. */
+  model?: ResourceModel;
+  [key: string]: unknown;
+};
+/**
+ * What an access function may return: a verdict, or a filter that is ANDed into the query.
+ * The filter is AIP-160 text or a `FilterExpr` built with `where`.
+ */
+export type AccessResult = boolean | string | FilterExpr;
+/**
+ * A rule at the resource level. Without a record it decides the operation and may return a row
+ * filter; with `(ctx, record, input)` it is a record-level check. Rules that need the record
+ * may throw a `TypeError` when it is missing, which marks the operation as record-checked.
+ */
+export type AccessFn<R = any> = (ctx: AccessContext, record?: R, input?: Partial<R>) => AccessResult | Promise<AccessResult>;
+/** A field rule is role-based: it never sees a record, so readable columns are fixed per request. */
+export type FieldRule = (ctx: AccessContext) => AccessResult | Promise<AccessResult>;
+export type FieldAccess = {
+  read?: FieldRule;
+  create?: FieldRule;
+  update?: FieldRule;
+};
+//#endregion

package/dist/enum-label.d.ts

@@ -0,0 +1,4 @@
+//#region src/enum-label.d.ts
+/** How an enum value reads: its label from the view's `valueLabels`, else the stored value unchanged (`co_signer`). */
+export declare const enumLabel: (value: string, labels?: Record<string, string>) => string;
+//#endregion

package/dist/enum-label.js

@@ -0,0 +1,5 @@
+//#region src/enum-label.ts
+/** How an enum value reads: its label from the view's `valueLabels`, else the stored value unchanged (`co_signer`). */
+const enumLabel = (value, labels) => labels?.[value] ?? value;
+//#endregion
+export { enumLabel };

package/dist/field.d.ts

@@ -0,0 +1,69 @@
+import { FieldType } from "./model.js";
+import { FieldAccess } from "./access/types.js";
+import { z } from "zod";
+//#region src/field.d.ts
+export type Constraint = 'min' | 'max' | 'regex';
+export type FieldMeta = {
+  type: FieldType;
+  column?: string;
+  nullable: boolean;
+  readOnly: boolean;
+  filterable: boolean;
+  sortable: boolean;
+  aliases: string[];
+  hasDefault: boolean;
+  defaultValue?: unknown;
+  dbDefault?: boolean;
+  access?: FieldAccess;
+  sensitive?: boolean;
+  enumValues?: string[];
+  relation?: {
+    resource: string;
+    columns?: string[];
+  };
+  precision?: number;
+  scale?: number;
+  min?: number;
+  max?: number;
+  regex?: {
+    re: RegExp;
+    message: string;
+  };
+};
+export type FieldTypeDef = {
+  type: FieldType;
+  constraints: readonly Constraint[];
+  build: (meta: FieldMeta) => z.ZodType;
+};
+export declare class Field<V> {
+  readonly def: FieldTypeDef;
+  readonly meta: FieldMeta;
+  readonly schema: z.ZodType<V>;
+  constructor(def: FieldTypeDef, meta: FieldMeta);
+  column(name: string): Field<V>;
+  readOnly(): Field<V>;
+  optional(): Field<V | null>;
+  default(value: V): Field<V>;
+  /**
+   * Role-based rules for reading and writing this column. They never see a record, so the set of
+   * readable columns is fixed per request. A field without a rule follows its resource.
+   */
+  access(rules: FieldAccess): Field<V>;
+  /**
+   * Hidden like a password: never part of a list, record, search or write response. A caller who may read it fetches the
+   * value of one record on its own (`POST /{resource}/{key}:reveal`), and every reveal is published as an audit event.
+   */
+  sensitive(): Field<V>;
+  /** The database supplies a value when none is given (identity, now(), ...). */
+  dbDefault(): Field<V>;
+  alias(...names: string[]): Field<V>;
+  filterable(): Field<V>;
+  sortable(): Field<V>;
+  regex(re: RegExp, message: string): Field<V>;
+  min(value: number): Field<V>;
+  max(value: number): Field<V>;
+  protected with(patch: Partial<FieldMeta>): Field<V>;
+  private constrain;
+}
+export type AnyField = Field<any>;
+//#endregion

package/dist/field.js

@@ -0,0 +1,85 @@
+import { z } from "zod";
+//#region src/field.ts
+const fieldRegistry = z.registry();
+var Field = class Field {
+	def;
+	meta;
+	schema;
+	constructor(def, meta) {
+		this.def = def;
+		this.meta = meta;
+		let schema = def.build(meta);
+		if (meta.nullable) schema = schema.nullable();
+		if (meta.hasDefault) schema = schema.default(meta.defaultValue);
+		this.schema = schema.register(fieldRegistry, meta);
+	}
+	column(name) {
+		return this.with({ column: name });
+	}
+	readOnly() {
+		return this.with({ readOnly: true });
+	}
+	optional() {
+		return this.with({ nullable: true });
+	}
+	default(value) {
+		return this.with({
+			hasDefault: true,
+			defaultValue: value
+		});
+	}
+	/**
+	* Role-based rules for reading and writing this column. They never see a record, so the set of
+	* readable columns is fixed per request. A field without a rule follows its resource.
+	*/
+	access(rules) {
+		return this.with({ access: {
+			...this.meta.access,
+			...rules
+		} });
+	}
+	/**
+	* Hidden like a password: never part of a list, record, search or write response. A caller who may read it fetches the
+	* value of one record on its own (`POST /{resource}/{key}:reveal`), and every reveal is published as an audit event.
+	*/
+	sensitive() {
+		return this.with({ sensitive: true });
+	}
+	/** The database supplies a value when none is given (identity, now(), ...). */
+	dbDefault() {
+		return this.with({ dbDefault: true });
+	}
+	alias(...names) {
+		return this.with({ aliases: [...this.meta.aliases, ...names] });
+	}
+	filterable() {
+		return this.with({ filterable: true });
+	}
+	sortable() {
+		return this.with({ sortable: true });
+	}
+	regex(re, message) {
+		return this.constrain("regex", { regex: {
+			re,
+			message
+		} });
+	}
+	min(value) {
+		return this.constrain("min", { min: value });
+	}
+	max(value) {
+		return this.constrain("max", { max: value });
+	}
+	with(patch) {
+		return new Field(this.def, {
+			...this.meta,
+			...patch
+		});
+	}
+	constrain(constraint, patch) {
+		if (!this.def.constraints.includes(constraint)) throw new Error(`f.${this.def.type} does not support .${constraint}()`);
+		return this.with(patch);
+	}
+};
+//#endregion
+export { Field, fieldRegistry };

package/dist/fields/bigint.js

@@ -0,0 +1,12 @@
+import { z } from "zod";
+//#region src/fields/bigint.ts
+const digits = /^-?\d+$/;
+const min = -(2n ** 63n);
+const max = 2n ** 63n - 1n;
+const bigint = {
+	type: "bigint",
+	constraints: [],
+	build: () => z.string().refine((v) => digits.test(v) && BigInt(v) >= min && BigInt(v) <= max, { message: "Expected a 64-bit integer as a string" })
+};
+//#endregion
+export { bigint };

package/dist/fields/boolean.js

@@ -0,0 +1,9 @@
+import { z } from "zod";
+//#region src/fields/boolean.ts
+const boolean = {
+	type: "boolean",
+	constraints: [],
+	build: () => z.boolean()
+};
+//#endregion
+export { boolean };

package/dist/fields/country.js

@@ -0,0 +1,9 @@
+import { z } from "zod";
+//#region src/fields/country.ts
+const country = {
+	type: "country",
+	constraints: [],
+	build: () => z.string().regex(/^[A-Z]{2}$/, "Expected an ISO 3166-1 alpha-2 country code")
+};
+//#endregion
+export { country };

package/dist/fields/currency.js

@@ -0,0 +1,9 @@
+import { z } from "zod";
+//#region src/fields/currency.ts
+const currency = {
+	type: "currency",
+	constraints: [],
+	build: () => z.string().regex(/^[A-Z]{3}$/, "Expected an ISO 4217 currency code")
+};
+//#endregion
+export { currency };

package/dist/fields/date.js

@@ -0,0 +1,9 @@
+import { z } from "zod";
+//#region src/fields/date.ts
+const date = {
+	type: "date",
+	constraints: [],
+	build: () => z.iso.date()
+};
+//#endregion
+export { date };

package/dist/fields/decimal.js

@@ -0,0 +1,22 @@
+import { z } from "zod";
+//#region src/fields/decimal.ts
+const shape = /^-?(\d*)(?:\.(\d+))?$/;
+const decimal = {
+	type: "decimal",
+	constraints: [],
+	build: (o) => {
+		if (o.precision === void 0 || o.scale === void 0) throw new Error("f.decimal requires precision and scale");
+		const maxInteger = o.precision - o.scale;
+		const maxFraction = o.scale;
+		return z.string().refine((v) => {
+			const match = shape.exec(v);
+			if (!match) return false;
+			const integer = (match[1] ?? "").replace(/^0+/, "");
+			const fraction = match[2] ?? "";
+			if (!(match[1] || fraction)) return false;
+			return integer.length <= maxInteger && fraction.length <= maxFraction;
+		}, { message: `Expected a decimal string with at most ${o.precision} digits, ${o.scale} after the point` });
+	}
+};
+//#endregion
+export { decimal };

package/dist/fields/enum.js

@@ -0,0 +1,12 @@
+import { z } from "zod";
+//#region src/fields/enum.ts
+const enumeration = {
+	type: "enum",
+	constraints: [],
+	build: (o) => {
+		if (!o.enumValues?.length) throw new Error("f.enum requires at least one value");
+		return z.enum(o.enumValues);
+	}
+};
+//#endregion
+export { enumeration };

package/dist/fields/integer.js

@@ -0,0 +1,14 @@
+import { z } from "zod";
+//#region src/fields/integer.ts
+const integer = {
+	type: "integer",
+	constraints: ["min", "max"],
+	build: (o) => {
+		let schema = z.int();
+		if (o.min !== void 0) schema = schema.min(o.min);
+		if (o.max !== void 0) schema = schema.max(o.max);
+		return schema;
+	}
+};
+//#endregion
+export { integer };

package/dist/fields/json.js

@@ -0,0 +1,9 @@
+import { z } from "zod";
+//#region src/fields/json.ts
+const json = {
+	type: "json",
+	constraints: [],
+	build: () => z.json()
+};
+//#endregion
+export { json };

package/dist/fields/relation.js

@@ -0,0 +1,9 @@
+import { z } from "zod";
+//#region src/fields/relation.ts
+const relation = {
+	type: "relation",
+	constraints: [],
+	build: () => z.union([z.string(), z.int()])
+};
+//#endregion
+export { relation };

package/dist/fields/text.js

@@ -0,0 +1,19 @@
+import { z } from "zod";
+//#region src/fields/text.ts
+const text = {
+	type: "text",
+	constraints: [
+		"min",
+		"max",
+		"regex"
+	],
+	build: (o) => {
+		let schema = z.string();
+		if (o.min !== void 0) schema = schema.min(o.min);
+		if (o.max !== void 0) schema = schema.max(o.max);
+		if (o.regex) schema = schema.regex(o.regex.re, o.regex.message);
+		return schema;
+	}
+};
+//#endregion
+export { text };

package/dist/fields/timestamp.js

@@ -0,0 +1,9 @@
+import { z } from "zod";
+//#region src/fields/timestamp.ts
+const timestamp = {
+	type: "timestamp",
+	constraints: [],
+	build: () => z.iso.datetime({ offset: true })
+};
+//#endregion
+export { timestamp };

package/dist/fields/uuid.js

@@ -0,0 +1,9 @@
+import { z } from "zod";
+//#region src/fields/uuid.ts
+const uuid = {
+	type: "uuid",
+	constraints: [],
+	build: () => z.uuid()
+};
+//#endregion
+export { uuid };

package/dist/fields.d.ts

@@ -0,0 +1,23 @@
+import { Field } from "./field.js";
+import { RelationField } from "./relation-field.js";
+import { z } from "zod";
+//#region src/fields.d.ts
+export declare const f: {
+  text: () => Field<string>;
+  integer: () => Field<number>;
+  bigint: () => Field<string>;
+  decimal: (o: {
+    precision: number;
+    scale: number;
+  }) => Field<string>;
+  boolean: () => Field<boolean>;
+  date: () => Field<string>;
+  timestamp: () => Field<string>;
+  uuid: () => Field<string>;
+  enum: <const T extends readonly string[]>(values: T) => Field<T[number]>;
+  json: () => Field<z.core.util.JSONType>;
+  relation: (resource: string) => RelationField<string | number>;
+  currency: () => Field<string>;
+  country: () => Field<string>;
+};
+//#endregion

package/dist/fields.js

@@ -0,0 +1,49 @@
+import { bigint } from "./fields/bigint.js";
+import { boolean } from "./fields/boolean.js";
+import { country } from "./fields/country.js";
+import { currency } from "./fields/currency.js";
+import { date } from "./fields/date.js";
+import { decimal } from "./fields/decimal.js";
+import { enumeration } from "./fields/enum.js";
+import { integer } from "./fields/integer.js";
+import { json } from "./fields/json.js";
+import { relation } from "./fields/relation.js";
+import { text } from "./fields/text.js";
+import { timestamp } from "./fields/timestamp.js";
+import { uuid } from "./fields/uuid.js";
+import { Field } from "./field.js";
+import { RelationField } from "./relation-field.js";
+//#region src/fields.ts
+const baseMeta = (def) => ({
+	type: def.type,
+	nullable: false,
+	readOnly: false,
+	filterable: false,
+	sortable: false,
+	aliases: [],
+	hasDefault: false
+});
+const make = (def, extra = {}) => new Field(def, {
+	...baseMeta(def),
+	...extra
+});
+const f = {
+	text: () => make(text),
+	integer: () => make(integer),
+	bigint: () => make(bigint),
+	decimal: (o) => make(decimal, o),
+	boolean: () => make(boolean),
+	date: () => make(date),
+	timestamp: () => make(timestamp),
+	uuid: () => make(uuid),
+	enum: (values) => make(enumeration, { enumValues: [...values] }),
+	json: () => make(json),
+	relation: (resource) => new RelationField(relation, {
+		...baseMeta(relation),
+		relation: { resource }
+	}),
+	currency: () => make(currency),
+	country: () => make(country)
+};
+//#endregion
+export { f };

package/dist/filter/check-field.js

@@ -0,0 +1,25 @@
+import { filterError, suggest } from "./errors.js";
+//#region src/filter/check-field.ts
+const findField = (model, name) => Object.hasOwn(model.fields, name) ? model.fields[name] : Object.values(model.fields).find((field) => field.aliases.includes(name));
+const resolveField = (ctx, path, capability) => {
+	if (path.path.length > 1) {
+		ctx.errors.push(filterError("unsupported-traversal", `Traversal into "${path.path.join(".")}" is not supported yet`, "Filter on fields of this resource only", path.span));
+		return;
+	}
+	const name = path.path[0];
+	const field = findField(ctx.model, name);
+	if (!field) {
+		const usable = Object.values(ctx.model.fields).filter((f) => f[capability]).map((f) => f.name);
+		const close = suggest(name, usable);
+		ctx.errors.push(filterError("unknown-field", `Unknown field "${name}"`, close ? `Did you mean "${close}"?` : `Available fields: ${usable.join(", ")}`, path.span));
+		return;
+	}
+	if (!field[capability]) {
+		const method = capability === "filterable" ? "filterable" : "sortable";
+		ctx.errors.push(filterError(capability === "filterable" ? "not-filterable" : "not-sortable", `Field "${field.name}" is not ${method}`, `Mark it with .${method}() in data.ts`, path.span));
+		return;
+	}
+	return field;
+};
+//#endregion
+export { findField, resolveField };