@protobase/schema 0.13.4 → 0.14.0

package/dist/access/capability.d.ts

@@ -1,10 +1,13 @@
 //#region src/access/capability.d.ts
+/** The operation a capability grants; `read` covers listing too. */
 export type CapabilityAction = 'read' | 'create' | 'update' | 'delete';
+/** The rows a scoped capability narrows to: the user's own (`.own`) or their team's (`.team`), by the resource's owner field. */
 export type CapabilityScope = 'own' | 'team';
 /**
  * `<resource|area>.<action>[.<scope>]` with `*` wildcards, or `*` alone. Pass the names as the
  * type parameter of `defineRoles` to make unknown names compile-time errors.
  */
 export type Capability<Name extends string = string> = '*' | `${Name | '*'}.${CapabilityAction | '*'}` | `${Name | '*'}.${CapabilityAction | '*'}.${CapabilityScope | '*'}`;
+/** The rows a held capability grants: all of them, or those of a scope. */
 export type Grant = 'all' | CapabilityScope;
 //#endregion

package/dist/access/index.d.ts

@@ -1,9 +1,9 @@
 import { AccessAction, AccessContext, AccessFn, AccessResult, AccessUser, FieldAccess, FieldRule } from "./types.js";
-import { Capability, CapabilityAction, CapabilityScope } from "./capability.js";
-import { CapabilityLimit, RoleEntry, anonymousRole } from "./role-entry.js";
+import { Capability, CapabilityAction, CapabilityScope, Grant } from "./capability.js";
+import { CapabilityLimit, HeldCapability, RoleEntry, anonymousRole } from "./role-entry.js";
 import { Rule, rule } from "./rule.js";
 import { RoleLimit, Roles, RolesOptions, defineRoles } from "./roles.js";
 import { pickView } from "./pick-view.js";
 import { AccessSource, ResolveOptions, ResolvedAccess, RowFilterOperation, accessWarnings, checkRecord, fieldsUsedBy, resolveAccess } from "./resolve.js";
 import { restrictModel } from "./restrict.js";
-export { type AccessAction, type AccessContext, type AccessFn, type AccessResult, type AccessSource, type AccessUser, type Capability, type CapabilityAction, type CapabilityLimit, type CapabilityScope, type FieldAccess, type FieldRule, type ResolveOptions, type ResolvedAccess, type RoleEntry, type RoleLimit, type Roles, type RolesOptions, type RowFilterOperation, type Rule, accessWarnings, anonymousRole, checkRecord, defineRoles, fieldsUsedBy, pickView, resolveAccess, restrictModel, rule };
+export { type AccessAction, type AccessContext, type AccessFn, type AccessResult, type AccessSource, type AccessUser, type Capability, type CapabilityAction, type CapabilityLimit, type CapabilityScope, type FieldAccess, type FieldRule, type Grant, type HeldCapability, type ResolveOptions, type ResolvedAccess, type RoleEntry, type RoleLimit, type Roles, type RolesOptions, type RowFilterOperation, type Rule, accessWarnings, anonymousRole, checkRecord, defineRoles, fieldsUsedBy, pickView, resolveAccess, restrictModel, rule };

package/dist/access/resolve.d.ts

@@ -6,10 +6,14 @@ import { Rule } from "./rule.js";
 //#region src/access/resolve.d.ts
 /** What the resolver needs from a resource; `ResourceBuilder` satisfies it. */
 export type AccessSource = {
+  /** The resource's model. */
   toModel: () => ResourceModel;
+  /** The resource's rules, by operation (`.access(...)`). */
   accessRules: Partial<Record<AccessAction, AccessFn>>;
+  /** The fields' own rules, by field name. */
   fieldAccess: () => Record<string, FieldAccess>;
 };
+/** How `resolveAccess` decides what the resource's rules leave open. */
 export type ResolveOptions = {
   /**
    * The project's roles. When given, an operation without a rule is denied unless the user's
@@ -18,8 +22,11 @@ export type ResolveOptions = {
    * holding only that role needs its capability even where a rule or `defaultAccess` would allow.
    */
   roles?: {
+    /** The rule allowing a capability, as `defineRoles` makes it. */
     can: (capability: any) => Rule;
+    /** The fields the user's roles list for a capability, or `undefined` for every field. */
     fields?: (user: AccessUser, capability: string) => readonly string[] | undefined;
+    /** The roles by name, to tell whether the project has an `anonymous` role. */
     definitions?: Record<string, unknown>;
   };
   /**
@@ -31,15 +38,21 @@ export type ResolveOptions = {
 };
 /** Startup warnings for risky option combinations; the caller decides how to report them. */
 export declare const accessWarnings: (options: ResolveOptions) => string[];
+/** An operation a row filter applies to. */
 export type RowFilterOperation = 'read' | 'create' | 'update' | 'delete';
+/** What one request may do with one resource, as `resolveAccess` works it out. */
 export type ResolvedAccess = {
+  /** Whether each operation is allowed at all; one in `recordChecks` or `rowFilter` only for some records. */
   operations: Record<AccessAction, boolean>;
   /** Operations whose rule needs the record (or input); check them with `checkRecord`. */
   recordChecks: AccessAction[];
   /** Columns the caller may see; everything else must be left out of results, filters, sorts and search. */
   readableFields: string[];
+  /** Columns the caller may write. */
   writableFields: {
+    /** Those a create may set. */
     create: string[];
+    /** Those an update may change. */
     update: string[];
   };
   /** ANDed into queries (`read` covers list and read) or checked against records (`create`). */

package/dist/access/role-entry.d.ts

@@ -6,15 +6,20 @@ import { Capability } from "./capability.js";
  * text that is ANDed into its rows (`{ filter: 'published = true' }`), or both (`{ fields: [...], filter: '...' }`).
  */
 export type CapabilityLimit = readonly string[] | {
+  /** The only fields the capability reads or writes. */
   readonly fields?: readonly string[];
+  /** AIP-160 text the capability's rows must match. */
   readonly filter?: string;
 };
 /** One entry of a role: a capability, or capabilities each with its limit, `{ 'products.read': ['sku', 'price'] }`. */
 export type RoleEntry<Name extends string = string> = Capability<Name> | { readonly [C in Capability<Name>]?: CapabilityLimit; };
 /** A capability a role holds, with the fields and rows it is limited to when it has a limit. */
 export type HeldCapability = {
+  /** The capability, such as `products.read`. */
   capability: string;
+  /** The only fields it reads or writes; every field when omitted. */
   fields?: readonly string[];
+  /** The filter its rows must match, parsed. */
   filter?: FilterExpr;
 };
 /** Requests without a token act as this role, when the project defines it. */

package/dist/access/roles.d.ts

@@ -3,6 +3,7 @@ import { Capability, Grant } from "./capability.js";
 import { HeldCapability, RoleEntry } from "./role-entry.js";
 import { Rule } from "./rule.js";
 //#region src/access/roles.d.ts
+/** The second argument of `defineRoles`. */
 export type RolesOptions = {
   /** Ids of the users in `user`'s team; `.team` scopes become `owner IN teamOf(user)`. */
   teamOf?: (user: AccessUser) => readonly (string | number)[] | Promise<readonly (string | number)[]>;
@@ -11,6 +12,7 @@ export type RolesOptions = {
 };
 /** A capability of a role that is limited to fields or rows; the server checks them against the resources at startup. */
 export type RoleLimit = HeldCapability & {
+  /** The role holding it. */
   role: string;
 };
 /**
@@ -21,8 +23,19 @@ export type RoleLimit = HeldCapability & {
  * An entry may limit capabilities to fields (an allowlist) and rows (an AIP-160 filter):
  * `{ 'products.read': ['sku', 'price'] }`, `{ 'products.read': { fields: ['name'], filter: 'published = true' } }`.
  * The role `anonymous`, when defined, is what requests without a token act as; it may only read listed fields.
+ * See [Access](website/src/content/docs/reference/access.mdx#capabilities).
+ *
+ * @example
+ * ```ts
+ * const roles = defineRoles<'orders' | 'products'>({
+ *   admin: ['*'],
+ *   sales: ['orders.read.own', 'orders.create', 'products.read'],
+ *   reseller: [{ 'products.read': { fields: ['sku', 'name', 'price'], filter: 'published = true' } }],
+ * })
+ * ```
  */
 export declare const defineRoles: <Name extends string = string>(definitions: Record<string, readonly RoleEntry<Name>[]>, options?: RolesOptions) => {
+  /** The roles as defined, by name. */
   definitions: Record<string, readonly RoleEntry<Name>[]>;
   grants: (user: AccessUser, capability: string) => Set<Grant>;
   /** The capabilities limited to fields or rows, by role. */
@@ -42,5 +55,6 @@ export declare const defineRoles: <Name extends string = string>(definitions: Re
   /** A rule that allows when the user has any of the roles. */
   is: (...roles: string[]) => Rule;
 };
+/** The roles `defineRoles` returns, as the server's `options.roles` takes them. */
 export type Roles = ReturnType<typeof defineRoles>;
 //#endregion

package/dist/access/roles.js

@@ -12,6 +12,16 @@ const rolesOf = (user) => user.roles ?? [];
 * An entry may limit capabilities to fields (an allowlist) and rows (an AIP-160 filter):
 * `{ 'products.read': ['sku', 'price'] }`, `{ 'products.read': { fields: ['name'], filter: 'published = true' } }`.
 * The role `anonymous`, when defined, is what requests without a token act as; it may only read listed fields.
+* See [Access](website/src/content/docs/reference/access.mdx#capabilities).
+*
+* @example
+* ```ts
+* const roles = defineRoles<'orders' | 'products'>({
+*   admin: ['*'],
+*   sales: ['orders.read.own', 'orders.create', 'products.read'],
+*   reseller: [{ 'products.read': { fields: ['sku', 'name', 'price'], filter: 'published = true' } }],
+* })
+* ```
 */
 const defineRoles = (definitions, options = {}) => {
 	const held = new Map(Object.entries(definitions).map(([role, entries]) => [role, heldCapabilities(role, entries)]));
@@ -34,6 +44,7 @@ const defineRoles = (definitions, options = {}) => {
 		return ids.length === 0 ? false : where.in(owner, [...ids]);
 	};
 	return {
+		/** The roles as defined, by name. */
 		definitions,
 		grants,
 		/** The capabilities limited to fields or rows, by role. */

package/dist/access/rule.d.ts

@@ -7,5 +7,15 @@ export type Rule<R = any> = AccessFn<R> & {
   /** Either may allow; filters are ORed. */
   or: (other: AccessFn<R>) => Rule<R>;
 };
+/**
+ * Wraps an access function so it combines with others through `.and()` and `.or()`; `roles.can()` and `roles.is()`
+ * return such rules already.
+ *
+ * @example
+ * ```ts
+ * const notShipped = rule((ctx, order) => order?.status !== 'shipped')
+ * resource('orders').access({ update: notShipped.and(roles.can('orders.update')) })
+ * ```
+ */
 export declare const rule: <R = any>(fn: AccessFn<R>) => Rule<R>;
 //#endregion

package/dist/access/rule.js

@@ -1,6 +1,16 @@
 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));
+/**
+* Wraps an access function so it combines with others through `.and()` and `.or()`; `roles.can()` and `roles.is()`
+* return such rules already.
+*
+* @example
+* ```ts
+* const notShipped = rule((ctx, order) => order?.status !== 'shipped')
+* resource('orders').access({ update: notShipped.and(roles.can('orders.update')) })
+* ```
+*/
 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))

package/dist/access/types.d.ts

@@ -1,19 +1,26 @@
 import { FilterExpr, ResourceModel } from "../model.js";
 //#region src/access/types.d.ts
+/** An operation on a resource that access rules decide; `list` falls back to the `read` rule. */
 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 = {
+  /** The user's id, which `.own` compares with the resource's `.owner(...)` field. */
   id?: string | number;
+  /** The user's roles, with organizations those of the membership too. */
   roles?: readonly string[];
   [key: string]: unknown;
 };
+/** What an access rule is given: who asks, for which operation, and where. */
 export type AccessContext = {
   /** Always set by the server; optional in the type so rules stay callable with a bare context. */
   user?: AccessUser;
+  /** The operation being decided. */
   operation?: AccessAction;
+  /** The record the operation is on, when there is one. */
   record?: unknown;
   /** With organizations, the one the request works in; `.tenant` resources are scoped to it already. */
   organization?: {
+    /** The organization's id. */
     id: string | number;
   };
   /** Set by the resolver; scoped capabilities (`.own`) need `model.owner`. */
@@ -33,9 +40,13 @@ export type AccessResult = boolean | string | FilterExpr;
 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>;
+/** A field's own rules, `.access({ read, create, update })` on the field; an operation without one follows the resource. */
 export type FieldAccess = {
+  /** Whether the caller may see the field. */
   read?: FieldRule;
+  /** Whether the caller may set the field when creating a record. */
   create?: FieldRule;
+  /** Whether the caller may change the field when updating a record. */
   update?: FieldRule;
 };
 //#endregion

package/dist/assistant/protocol.d.ts

@@ -1,58 +1,96 @@
 //#region src/assistant/protocol.d.ts
+/** The colour of a card, by what it reports. */
 export type AssistantTone = 'neutral' | 'info' | 'success' | 'warning' | 'danger';
 /** A button on a card. Clicking it posts `{ partId, actionId }`; with `confirm`, only after the user confirms that text. */
 export type AssistantAction = {
+  /** What the click posts as `actionId`, unique on its card. */
   id: string;
+  /** The button's text. */
   label: string;
+  /** How the button looks; `secondary` when omitted. */
   style?: 'primary' | 'secondary' | 'ghost' | 'danger';
+  /** Shown but not clickable. */
   disabled?: boolean;
   /** A line under the buttons, such as why one is disabled. */
   hint?: string;
+  /** A question the user confirms before the click is posted, such as `Run this update?`. */
   confirm?: string;
 };
+/** Where a step of a card's work stands. */
 export type AssistantStepState = 'pending' | 'running' | 'done' | 'failed';
+/** One step of a card's work, listed with its state. */
 export type AssistantStep = {
+  /** What the step does. */
   label: string;
+  /** Where it stands. */
   state: AssistantStepState;
 };
 /** Changed lines: `+` added, `-` removed, anything else context; `start` is the first line's number. */
 export type AssistantDiff = {
+  /** What changed, such as a file's path, shown above the lines. */
   path?: string;
+  /** The lines, one per line of text, each starting with `+`, `-` or anything else. */
   source: string;
+  /** The number of the first line; 1 when omitted. */
   start?: number;
 };
+/** A paragraph of plain text. */
 export type AssistantTextPart = {
+  /** Marks a text part. */
   type: 'text';
+  /** The part's id, unique in its message; a part with the same id replaces it. */
   id: string;
+  /** The text. */
   text: string;
 };
 /** Rows of values; `null` stays visible, objects show as JSON. `truncated` says the rows stop at a limit. */
 export type AssistantTablePart = {
+  /** Marks a table part. */
   type: 'table';
+  /** The part's id, unique in its message; a part with the same id replaces it. */
   id: string;
+  /** The column headings. */
   columns: string[];
+  /** One array per row, a value per column. */
   rows: unknown[][];
+  /** A line under the table, such as the query it came from. */
   caption?: string;
+  /** The rows stop at a limit, so there are more than shown. */
   truncated?: boolean;
 };
+/**
+ * A card with a title, and in this order whichever of `body`, `code`, `fields`, `steps` and `diffs` it has, then its
+ * `note` and `actions`: what a backend proposes or reports, such as a query waiting for approval.
+ */
 export type AssistantCardPart = {
+  /** Marks a card part. */
   type: 'card';
+  /** The part's id, unique in its message; a part with the same id replaces it, and button clicks post it as `partId`. */
   id: string;
+  /** The card's title. */
   title: string;
+  /** The card's colour; `neutral` when omitted. */
   tone?: AssistantTone;
   /** Short text at the end of the title row. */
   badge?: string;
+  /** A paragraph of text. */
   body?: string;
   /** Monospace text, such as a query. */
   code?: string;
+  /** Labelled values, one per line. */
   fields?: Array<{
+    /** The value's label. */
     label: string;
+    /** The value, as text. */
     value: string;
   }>;
+  /** The steps of the card's work, each with its state. */
   steps?: AssistantStep[];
+  /** Changed lines, such as of a file or a record. */
   diffs?: AssistantDiff[];
   /** A muted line under the content, such as what happened to the card. */
   note?: string;
+  /** Buttons at the card's bottom. */
   actions?: AssistantAction[];
 };
 /**
@@ -60,7 +98,9 @@ export type AssistantCardPart = {
  * component's name and props such as `{ taskId }`, so the part shows the record as it is now.
  */
 export type AssistantWidgetPart = {
+  /** Marks a widget part. */
   type: 'widget';
+  /** The part's id, unique in its message; a part with the same id replaces it. */
   id: string;
   /** A component in the app's `components` (its protobase.ui.tsx and the UI configs it extends), PascalCase. */
   name: string;
@@ -68,17 +108,26 @@ export type AssistantWidgetPart = {
   props: Record<string, unknown>;
   /** Drawn, as a plain card, when the app has no component by that name: what the part was about when it was made. */
   fallback?: {
+    /** The card's title. */
     title: string;
+    /** The card's text. */
     body?: string;
   };
 };
+/** A piece of a message, drawn by its `type`; code that switches over it handles every type. */
 export type AssistantPart = AssistantTextPart | AssistantTablePart | AssistantCardPart | AssistantWidgetPart;
+/** A message of the chat: what the user wrote, or the backend's answer in parts. */
 export type AssistantMessage = {
+  /** The message's id; a message with the same id replaces it. */
   id: string;
+  /** Who wrote it. */
   from: 'user' | 'assistant';
+  /** What it shows, in order. */
   parts: AssistantPart[];
 };
+/** Everything the dock shows: the chat and its header, as the event stream builds it up. */
 export type AssistantState = {
+  /** The chat, oldest first. */
   messages: AssistantMessage[];
   /** The backend is answering: the user can write but not send. */
   replying: boolean;
@@ -90,32 +139,48 @@ export type AssistantState = {
 /**
  * What the event stream sends. `state` replaces everything and always comes first on a connection; `message` adds a
  * message or replaces the one with its id; `part` adds a part to a message or replaces the one with its id; `patch`
- * changes the top-level fields, `null` clearing one.
+ * changes the top-level fields, `null` clearing one. A backend in place of the built-in one sends these; see
+ * [Another backend](website/src/content/docs/reference/assistant.md#another-backend).
  */
 export type AssistantEvent = {
+  /** Replaces the whole state. */
   type: 'state';
+  /** The new state. */
   state: AssistantState;
 } | {
+  /** Adds or replaces a message. */
   type: 'message';
+  /** The message. */
   message: AssistantMessage;
 } | {
+  /** Adds or replaces a part of a message. */
   type: 'part';
+  /** The id of the message the part belongs to. */
   messageId: string;
+  /** The part. */
   part: AssistantPart;
 } | {
+  /** Changes the state's top-level fields. */
   type: 'patch';
+  /** The new `replying`, when it changes. */
   replying?: boolean;
+  /** The new `status`, or `null` to clear it. */
   status?: string | null;
+  /** The new `placeholder`, or `null` to clear it. */
   placeholder?: string | null;
 };
 /** `POST <url>/messages`; `page` is where the user is in the app, below its base path, such as `/orders/42?status=open`. */
 export type AssistantMessageRequest = {
+  /** What the user wrote. */
   text: string;
+  /** Where the user is in the app when they send it. */
   page?: string;
 };
-/** `POST <url>/actions` */
+/** `POST <url>/actions`: the user clicked a button of a card. */
 export type AssistantActionRequest = {
+  /** The card's `id`. */
   partId: string;
+  /** The button's `id`. */
   actionId: string;
 };
 //#endregion

package/dist/bottom-bar-errors.d.ts

@@ -2,8 +2,11 @@ import { BottomBarModel } from "./model.js";
 //#region src/bottom-bar-errors.d.ts
 /** What the bottom bars may name. Without `roles` (an app whose roles are not declared) any role is accepted. */
 export type BottomBarNames = {
+  /** The app's resources. */
   resources: readonly string[];
+  /** The app's composed pages. */
   pages: readonly string[];
+  /** The app's roles, when it declares them. */
   roles?: readonly string[];
 };
 /**

package/dist/bottom-bar.d.ts

@@ -20,11 +20,13 @@ declare const items: {
 };
 /** What the server needs from a `bottomBar(...)` export of the config module. */
 export type BottomBarSource = {
+  /** The bar's model, a copy each time. */
   toBottomBarModel(): BottomBarModel;
 };
 /**
  * Tabs at the bottom of the screen on phones, for the users holding one of `roles`. Export one per group of roles; a
- * role belongs to one bottom bar. `label` names the bar where someone with several switches between them.
+ * role belongs to one bottom bar. `label` names the bar where someone with several switches between them. Its tabs
+ * are `m.resource`, `m.page` and `m.link`, at most four. See [Bottom bar](website/src/content/docs/reference/bottom-bar.md).
  */
 export declare const bottomBar: (options: {
   label: string;

package/dist/bottom-bar.js

@@ -28,7 +28,8 @@ const items = {
 };
 /**
 * Tabs at the bottom of the screen on phones, for the users holding one of `roles`. Export one per group of roles; a
-* role belongs to one bottom bar. `label` names the bar where someone with several switches between them.
+* role belongs to one bottom bar. `label` names the bar where someone with several switches between them. Its tabs
+* are `m.resource`, `m.page` and `m.link`, at most four. See [Bottom bar](website/src/content/docs/reference/bottom-bar.md).
 */
 const bottomBar = (options, build) => {
 	const model = {

package/dist/events/event-helpers.d.ts

@@ -3,7 +3,9 @@ import { Ref } from "../refs.js";
 //#region src/events/event-helpers.d.ts
 /** Who made a write through the API; writes from anywhere else have none. */
 export type EventActor = {
+  /** The user's id. */
   id: string | number;
+  /** The user's roles. */
   roles: string[];
 };
 /**
@@ -11,60 +13,91 @@ export type EventActor = {
  * sensitive fields, whose names `changed` still lists.
  */
 export type EventContext<R = Record<string, unknown>> = {
+  /** What happened to the record. */
   operation: EventOperation;
+  /** The record before the change, as it was at the start of the transaction; none for a create. */
   before?: Partial<R>;
+  /** The record after the change, as it is at commit; none for a delete. */
   after?: Partial<R>;
+  /** The names of the fields that changed, sensitive ones included. */
   changed: string[];
   /** `null` for a write made outside the API (psql, another service, a database trigger). */
   actor: EventActor | null;
+  /** `api` for a write through the API, `database` for any other. */
   source: 'api' | 'database';
+  /** The record's tenant, when the resource has one. */
   tenant?: string | number;
   /** The writing transaction's id. */
   transaction: string;
 };
+/** An event's code predicate: whether a change raises the event, for what a filter cannot say. */
 export type EventMatch<R> = (context: EventContext<R>) => boolean;
 /** `when` and `from` are filters in the language of access rules and views, on the record after and before the change. */
 export type CreatedOptions<R> = {
+  /** A filter the created record meets. */
   when?: string;
+  /** A code predicate the change meets. */
   match?: EventMatch<R>;
 };
+/** The conditions of `e.updated()`, which combine with AND. */
 export type UpdatedOptions<R> = {
+  /** A filter the record meets after the change. */
   when?: string;
+  /** A filter the record met before the change. */
   from?: string;
+  /** Fields of which one changed; it works on sensitive fields too. */
   changed?: Ref[];
+  /** A code predicate the change meets. */
   match?: EventMatch<R>;
 };
+/** The conditions of `e.deleted()`, which combine with AND. */
 export type DeletedOptions<R> = {
+  /** A filter the record met before it was deleted. */
   from?: string;
+  /** A code predicate the change meets. */
   match?: EventMatch<R>;
 };
+/** The conditions of `e.undeleted()`, which combine with AND. */
 export type UndeletedOptions<R> = {
+  /** A filter the record meets once restored. */
   when?: string;
+  /** A filter the record met while deleted. */
   from?: string;
+  /** A code predicate the change meets. */
   match?: EventMatch<R>;
 };
 /** An event as declared; `buildEventModels` checks it against the resource. */
 export type EventSpec = {
+  /** The event's name within the resource, such as `created`; the event is `<resource>.<name>`. */
   name: string;
+  /** The operations that may raise it. */
   operations: EventOperation[];
+  /** A filter on the record after the change. */
   when?: string;
+  /** A filter on the record before the change. */
   from?: string;
+  /** A filter that turns true with the change. */
   becomes?: string;
+  /** The fields of which one must change, by name. */
   changed?: string[];
+  /** A code predicate the change must meet. */
   match?: EventMatch<any>;
   /** Kept only when the resource soft deletes: the `undeleted` of `e.crud()`. */
   softDeleteOnly?: true;
 };
 /** The `e` of `.events((e, r) => [...])`. Options combine with AND. */
-export declare const eventHelpers: <R>() => {
-  created: (name?: string, options?: CreatedOptions<R>) => EventSpec;
-  updated: (name?: string, options?: UpdatedOptions<R>) => EventSpec;
-  deleted: (name?: string, options?: DeletedOptions<R>) => EventSpec;
-  undeleted: (name?: string, options?: UndeletedOptions<R>) => EventSpec;
+export type EventHelpers<R> = {
+  /** Fires when a record is created; named `created` unless `name` says otherwise. */
+  created(name?: string, options?: CreatedOptions<R>): EventSpec;
+  /** Fires when a record is updated; named `updated` unless `name` says otherwise. */
+  updated(name?: string, options?: UpdatedOptions<R>): EventSpec;
+  /** Fires when a record is deleted, soft deletes included; named `deleted` unless `name` says otherwise. */
+  deleted(name?: string, options?: DeletedOptions<R>): EventSpec;
+  /** Fires when a soft deleted record is restored; named `undeleted` unless `name` says otherwise. */
+  undeleted(name?: string, options?: UndeletedOptions<R>): EventSpec;
   /** Fires when `condition` turns true: on a create that meets it, or an update after which it holds and before which it did not. */
-  becomes: (name: string, condition: string) => EventSpec;
+  becomes(name: string, condition: string): EventSpec;
   /** created, updated and deleted, plus undeleted when the resource soft deletes. */
-  crud: () => EventSpec[];
+  crud(): EventSpec[];
 };
-export type EventHelpers<R> = ReturnType<typeof eventHelpers<R>>;
 //#endregion

package/dist/events/event-helpers.js

@@ -5,7 +5,7 @@ const spec = (name, operation, { changed, ...options }) => ({
 	...options,
 	...changed && { changed: changed.map((ref) => ref.name) }
 });
-/** The `e` of `.events((e, r) => [...])`. Options combine with AND. */
+/** The helpers handed to `.events()`, typed against the resource's record `R`. */
 const eventHelpers = () => {
 	const created = (name = "created", options = {}) => spec(name, "create", options);
 	const updated = (name = "updated", options = {}) => spec(name, "update", options);
@@ -16,13 +16,11 @@ const eventHelpers = () => {
 		updated,
 		deleted,
 		undeleted,
-		/** Fires when `condition` turns true: on a create that meets it, or an update after which it holds and before which it did not. */
 		becomes: (name, condition) => ({
 			name,
 			operations: ["create", "update"],
 			becomes: condition
 		}),
-		/** created, updated and deleted, plus undeleted when the resource soft deletes. */
 		crud: () => [
 			created(),
 			updated(),

package/dist/field-ref.d.ts

@@ -5,6 +5,7 @@ import { JsonValue } from "./model.js";
  * relations (`plan.name`) on a page. Marked, so that the walker leaving out hidden fields finds it wherever it is.
  */
 export type FieldRefValue = {
+  /** The field's name, or a path through relations. */
   readonly $field: string;
 };
 /** A field reference for a layout's custom component props, such as `<UsageChart field={fieldRef('total')} />`. */