@protobase/schema 0.27.0 → 0.28.1

package/dist/access/restrict.d.ts

@@ -4,7 +4,7 @@ import { ResolvedAccess } from "./resolve.js";
 /**
  * The resource as one user may see it: only readable fields remain, and a field is `readOnly`
  * unless it is writable on create or update. `search` (and `searchMatch`) shrinks to readable fields, and `tenant`,
- * `softDelete` and `owner` are dropped when their field is hidden, `position` when its field or its `within` is. The event catalogue, whose conditions may use any
+ * `softDelete` and `owner` are dropped when their field is hidden, `position` when its field or its `within` is, and each of `parents` whose field is. The event catalogue, whose conditions may use any
  * field, is dropped. Key columns always stay,
  * because records are addressed by them.
  *

package/dist/access/restrict.js

@@ -2,7 +2,7 @@
 /**
 * The resource as one user may see it: only readable fields remain, and a field is `readOnly`
 * unless it is writable on create or update. `search` (and `searchMatch`) shrinks to readable fields, and `tenant`,
-* `softDelete` and `owner` are dropped when their field is hidden, `position` when its field or its `within` is. The event catalogue, whose conditions may use any
+* `softDelete` and `owner` are dropped when their field is hidden, `position` when its field or its `within` is, and each of `parents` whose field is. The event catalogue, whose conditions may use any
 * field, is dropped. Key columns always stay,
 * because records are addressed by them.
 *
@@ -17,11 +17,12 @@ const restrictModel = (model, access) => {
 	const keep = (name) => name !== void 0 && visible.has(name) ? name : void 0;
 	const search = model.search?.filter((name) => visible.has(name));
 	const searchMatch = model.searchMatch && Object.entries(model.searchMatch).filter(([name]) => visible.has(name));
-	const { search: _search, searchMatch: _searchMatch, tenant: _tenant, softDelete: _softDelete, owner: _owner, position: _position, events: _events, ...rest } = model;
+	const { search: _search, searchMatch: _searchMatch, tenant: _tenant, softDelete: _softDelete, owner: _owner, position: _position, parents: _parents, events: _events, ...rest } = model;
 	const tenant = keep(model.tenant);
 	const softDelete = keep(model.softDelete);
 	const owner = keep(model.owner);
 	const position = model.position && keep(model.position.field) && (model.position.within === void 0 || keep(model.position.within)) ? model.position : void 0;
+	const parents = model.parents?.filter((parent) => visible.has(parent.field));
 	return {
 		...rest,
 		fields: Object.fromEntries(Object.entries(model.fields).filter(([name]) => visible.has(name)).map(([name, field]) => [name, {
@@ -33,7 +34,8 @@ const restrictModel = (model, access) => {
 		...tenant && { tenant },
 		...softDelete && { softDelete },
 		...owner && { owner },
-		...position && { position: { ...position } }
+		...position && { position: { ...position } },
+		...parents?.length && { parents: parents.map((parent) => ({ ...parent })) }
 	};
 };
 //#endregion

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { Rollup, RollupCount, RollupFn, RollupSource, RollupValue } from "./computed/rollup.js";
 import { FileOptions, FileProcessor, FileProcessorInput, ImageFormat, ImageVariant, ImageVariantOptions, imageFormats } from "./files/file-options.js";
-import { ActionInputKind, ActionInputModel, ActionModel, ActionRun, AppAddress, BadgeShape, BottomBarItemModel, BottomBarModel, CalendarView, CardFavoriteModel, CardPhotosModel, ChartGranularity, ChartModel, ChartRange, CheckedFilter, CommentsSectionModel, CompareOp, CreateModel, CustomSectionModel, DatePreset, DurationLiteral, DurationUnit, EventModel, EventOperation, ExportModel, FieldFormat, FieldModel, FieldPath, FieldType, FieldViewModel, FieldWidgetModel, FileFieldModel, FilterError, FilterErrorCode, FilterExpr, FilterLayout, FilterOf, FilterValue, FilterWidgetModel, FormModel, GalleryModel, GroupChartModel, GroupItemModel, GroupModel, HelpWhen, HistorySectionModel, JsonValue, KeyValue, LayoutItemModel, ListDisplayModel, ListDragModel, ListModel, ListQuery, Literal, MapSectionModel, MapView, NamedListModel, NavModel, NavRecentModel, NowValue, OrderByItem, PeriodChartModel, PositionAfterModel, RecordMode, RecordWhen, RelatedColumnModel, RelatedModel, RelatedPresentation, ResourceModel, SaveFeedback, SaveSearchModel, SearchMatch, SearchResultModel, SearchesOfModel, SectionModel, SectionPresentation, ShowWhen, SignInPromptModel, SignInViewModel, SortSpec, Span, StatusTone, TabItemModel, TabModel, TimelineView, UserMenuItemModel, UserMenuModel, ViewModel } from "./model.js";
+import { ActionInputKind, ActionInputModel, ActionModel, ActionRun, AppAddress, BadgeShape, BottomBarItemModel, BottomBarModel, CalendarView, CardFavoriteModel, CardPhotosModel, ChartGranularity, ChartModel, ChartRange, CheckedFilter, CommentsSectionModel, CompareOp, CreateModel, CustomSectionModel, DatePreset, DurationLiteral, DurationUnit, EventModel, EventOperation, ExportModel, FieldFormat, FieldModel, FieldPath, FieldType, FieldViewModel, FieldWidgetModel, FileFieldModel, FilterError, FilterErrorCode, FilterExpr, FilterLayout, FilterOf, FilterValue, FilterWidgetModel, FormModel, GalleryModel, GroupChartModel, GroupItemModel, GroupModel, HelpWhen, HistorySectionModel, JsonValue, KeyValue, LayoutItemModel, ListDisplayModel, ListDragModel, ListModel, ListQuery, Literal, MapSectionModel, MapView, NamedListModel, NavModel, NavRecentModel, NowValue, OrderByItem, ParentAccess, ParentModel, PeriodChartModel, PositionAfterModel, RecordMode, RecordWhen, RelatedColumnModel, RelatedModel, RelatedPresentation, ResourceModel, SaveFeedback, SaveSearchModel, SearchMatch, SearchResultModel, SearchesOfModel, SectionModel, SectionPresentation, ShowWhen, SignInPromptModel, SignInViewModel, SortSpec, Span, StatusTone, TabItemModel, TabModel, TimelineView, UserMenuItemModel, UserMenuModel, ViewModel } from "./model.js";
 import { AccessAction, AccessContext, AccessFn, AccessResult, AccessUser, FieldAccess, FieldRule } from "./access/types.js";
 import { AnyField, Constraint, Field, FieldMeta, FieldTypeDef } from "./field.js";
 import { RelationField } from "./relation-field.js";
@@ -43,4 +43,4 @@ import { AccessSource, ResolveOptions, ResolvedAccess, RowFilterOperation, acces
 import { restrictModel } from "./access/restrict.js";
 import "./access/index.js";
 import { AssistantAction, AssistantActionRequest, AssistantCardPart, AssistantDiff, AssistantEvent, AssistantMessage, AssistantMessageRequest, AssistantPart, AssistantState, AssistantStep, AssistantStepState, AssistantTablePart, AssistantTextPart, AssistantTone, AssistantWidgetPart } from "./assistant/protocol.js";
-export { type Access, type AccessAction, type AccessContext, type AccessFn, type AccessResult, type AccessSource, type AccessUser, type ActionInputKind, type ActionInputModel, type ActionModel, type ActionRun, type AnyField, type AppAddress, type AssistantAction, type AssistantActionRequest, type AssistantCardPart, type AssistantDiff, type AssistantEvent, type AssistantMessage, type AssistantMessageRequest, type AssistantPart, type AssistantState, type AssistantStep, type AssistantStepState, type AssistantTablePart, type AssistantTextPart, type AssistantTone, type AssistantWidgetPart, type BadgeShape, type BottomBarItemModel, type BottomBarModel, type BottomBarNames, type BottomBarSource, type CalendarView, type Capability, type CapabilityAction, type CapabilityLimit, type CapabilityScope, type CardFavoriteModel, type CardPhotosModel, type ChartGranularity, type ChartInput, type ChartModel, type ChartRange, type CheckResult, type CheckedFilter, type CommentsSectionModel, type CompareOp, type ComponentRef, type Constraint, type CreateModel, type CreatedOptions, type CustomSectionModel, type DatePreset, type DeletedOptions, type DurationLiteral, type DurationUnit, type EvaluateOptions, type EventActor, type EventContext, type EventHelpers, type EventMatch, type EventModel, type EventOperation, type EventSpec, type ExportModel, type Field, type FieldAccess, type FieldFormat, type FieldMeta, type FieldModel, type FieldPath, type FieldRefValue, type FieldRefs, type FieldRule, type FieldType, type FieldTypeDef, type FieldView, type FieldViewModel, type FieldViews, type FieldWidgetModel, type FieldsInput, type FileField, type FileFieldModel, type FileOptions, type FileProcessor, type FileProcessorInput, type FilterError, type FilterErrorCode, type FilterExpr, type FilterLayout, type FilterLimits, type FilterOf, type FilterParse, type FilterValue, type FilterWidgetModel, type FormAddress, type FormInput, type FormModel, type GalleryModel, type Grant, type GroupChartInput, type GroupChartModel, type GroupItemModel, type GroupModel, type HeldCapability, type HelpWhen, type HistorySectionModel, type ImageFormat, type ImageVariant, type ImageVariantOptions, type InferRecord, type Issue, type JsonValue, type KeyOf, type KeyRefs, type KeyType, type KeyValue, type LayoutItemModel, type ListColumn, type ListDisplayModel, type ListDragModel, type ListModel, type ListQuery, type Literal, type MapSectionModel, type MapView, type NamedListModel, type NavModel, type NavRecentModel, type NowValue, type OrderByCheck, type OrderByItem, type OrderByParse, type PeriodChartInput, type PeriodChartModel, type PositionAfterModel, type RecordKey, type RecordMode, type RecordOf, type RecordWhen, type Ref, type Refs, type RelatedColumnModel, type RelatedModel, type RelatedPresentation, type RelationField, type ResolveOptions, type ResolvedAccess, type ResourceBuilder, type ResourceModel, type RoleEntry, type RoleLimit, type Roles, type RolesOptions, type Rollup, type RollupCount, type RollupFn, type RollupSource, type RollupValue, type RowFilterOperation, type Rule, type SaveFeedback, type SaveSearchModel, type SearchMatch, type SearchRef, type SearchRefs, type SearchResultModel, type SearchesOfModel, type SectionModel, type SectionPresentation, type ShowWhen, type SignInAddress, type SignInPromptModel, type SignInStep, type SignInViewModel, type SortSpec, type Span, type StatusTone, type TabItemModel, type TabModel, type TimelineView, type UndeletedOptions, type UpdatedOptions, type UserMenuItemModel, type UserMenuModel, type UserMenuSource, type Validator, type ViewBuilder, type ViewModel, type ViewProps, accessWarnings, addressWords, anonymousRole, appPath, bottomBar, bottomBarErrors, checkFilter, checkOrderBy, checkRecord, createWhere, defineRoles, enumLabel, evaluateFilter, f, fieldRef, fieldsUsedBy, fitsKeyType, formPath, formRoute, imageFormats, isRecordCondition, keyTypes, layout as l, maxBottomBarItems, parseFilter, parseOrderBy, pickView, printFilter, printOrderBy, readAppPath, readFormAddress, readSignInAddress, resolveAccess, resource, restrictModel, rule, signInParams, signInPath, signInRoute, signInSteps, userMenu, view, where };
+export { type Access, type AccessAction, type AccessContext, type AccessFn, type AccessResult, type AccessSource, type AccessUser, type ActionInputKind, type ActionInputModel, type ActionModel, type ActionRun, type AnyField, type AppAddress, type AssistantAction, type AssistantActionRequest, type AssistantCardPart, type AssistantDiff, type AssistantEvent, type AssistantMessage, type AssistantMessageRequest, type AssistantPart, type AssistantState, type AssistantStep, type AssistantStepState, type AssistantTablePart, type AssistantTextPart, type AssistantTone, type AssistantWidgetPart, type BadgeShape, type BottomBarItemModel, type BottomBarModel, type BottomBarNames, type BottomBarSource, type CalendarView, type Capability, type CapabilityAction, type CapabilityLimit, type CapabilityScope, type CardFavoriteModel, type CardPhotosModel, type ChartGranularity, type ChartInput, type ChartModel, type ChartRange, type CheckResult, type CheckedFilter, type CommentsSectionModel, type CompareOp, type ComponentRef, type Constraint, type CreateModel, type CreatedOptions, type CustomSectionModel, type DatePreset, type DeletedOptions, type DurationLiteral, type DurationUnit, type EvaluateOptions, type EventActor, type EventContext, type EventHelpers, type EventMatch, type EventModel, type EventOperation, type EventSpec, type ExportModel, type Field, type FieldAccess, type FieldFormat, type FieldMeta, type FieldModel, type FieldPath, type FieldRefValue, type FieldRefs, type FieldRule, type FieldType, type FieldTypeDef, type FieldView, type FieldViewModel, type FieldViews, type FieldWidgetModel, type FieldsInput, type FileField, type FileFieldModel, type FileOptions, type FileProcessor, type FileProcessorInput, type FilterError, type FilterErrorCode, type FilterExpr, type FilterLayout, type FilterLimits, type FilterOf, type FilterParse, type FilterValue, type FilterWidgetModel, type FormAddress, type FormInput, type FormModel, type GalleryModel, type Grant, type GroupChartInput, type GroupChartModel, type GroupItemModel, type GroupModel, type HeldCapability, type HelpWhen, type HistorySectionModel, type ImageFormat, type ImageVariant, type ImageVariantOptions, type InferRecord, type Issue, type JsonValue, type KeyOf, type KeyRefs, type KeyType, type KeyValue, type LayoutItemModel, type ListColumn, type ListDisplayModel, type ListDragModel, type ListModel, type ListQuery, type Literal, type MapSectionModel, type MapView, type NamedListModel, type NavModel, type NavRecentModel, type NowValue, type OrderByCheck, type OrderByItem, type OrderByParse, type ParentAccess, type ParentModel, type PeriodChartInput, type PeriodChartModel, type PositionAfterModel, type RecordKey, type RecordMode, type RecordOf, type RecordWhen, type Ref, type Refs, type RelatedColumnModel, type RelatedModel, type RelatedPresentation, type RelationField, type ResolveOptions, type ResolvedAccess, type ResourceBuilder, type ResourceModel, type RoleEntry, type RoleLimit, type Roles, type RolesOptions, type Rollup, type RollupCount, type RollupFn, type RollupSource, type RollupValue, type RowFilterOperation, type Rule, type SaveFeedback, type SaveSearchModel, type SearchMatch, type SearchRef, type SearchRefs, type SearchResultModel, type SearchesOfModel, type SectionModel, type SectionPresentation, type ShowWhen, type SignInAddress, type SignInPromptModel, type SignInStep, type SignInViewModel, type SortSpec, type Span, type StatusTone, type TabItemModel, type TabModel, type TimelineView, type UndeletedOptions, type UpdatedOptions, type UserMenuItemModel, type UserMenuModel, type UserMenuSource, type Validator, type ViewBuilder, type ViewModel, type ViewProps, accessWarnings, addressWords, anonymousRole, appPath, bottomBar, bottomBarErrors, checkFilter, checkOrderBy, checkRecord, createWhere, defineRoles, enumLabel, evaluateFilter, f, fieldRef, fieldsUsedBy, fitsKeyType, formPath, formRoute, imageFormats, isRecordCondition, keyTypes, layout as l, maxBottomBarItems, parseFilter, parseOrderBy, pickView, printFilter, printOrderBy, readAppPath, readFormAddress, readSignInAddress, resolveAccess, resource, restrictModel, rule, signInParams, signInPath, signInRoute, signInSteps, userMenu, view, where };

package/dist/model.d.ts

@@ -120,6 +120,8 @@ export type ResourceModel = {
     /** The records each record ranks after while they are pending, such as the tasks it waits for (`.position(..., { after })`). */
     after?: PositionAfterModel;
   };
+  /** The records its records belong to, and the access on them writing its records needs (`.parent()`). */
+  parents?: ParentModel[];
   /** The events its changes raise (`.events()`), the catalogue subscriptions pick from. */
   events?: EventModel[];
   /** Whether every change of its records is kept, with who made it (`.history()`). */
@@ -581,6 +583,20 @@ export type PositionAfterModel = {
   /** An AIP-160 filter on the records depended on, which they keep the order only while they match, such as `status != "done"`. */
   while?: string;
 };
+/** The access on a parent record that writing a record under it needs: reading it, or updating it. */
+export type ParentAccess = 'read' | 'update';
+/**
+ * A record that a resource's records belong to through a relation field, such as an operation's VM: creating, changing,
+ * deleting or undeleting a record needs `access` on the record `field` points at, checked with the caller's own access
+ * rules on that resource. See
+ * [Records that belong to another](website/src/content/docs/reference/access.mdx#records-that-belong-to-another).
+ */
+export type ParentModel = {
+  /** The relation field that points at the parent record. */
+  field: string;
+  /** The access on the parent record that writing needs. */
+  access: ParentAccess;
+};
 /** A view's list page (`.list(...)`). */
 export type ListModel = {
   /** The table's columns, in order. */

package/dist/resource-model.d.ts

@@ -1,4 +1,4 @@
-import { PositionAfterModel, SearchMatch } from "./model.js";
+import { ParentModel, PositionAfterModel, SearchMatch } from "./model.js";
 import { FieldsInput } from "./refs.js";
 import { EventSpec } from "./events/event-helpers.js";
 //#region src/resource-model.d.ts
@@ -17,6 +17,7 @@ export type ResourceState = {
     within?: string;
     after?: PositionAfterModel;
   };
+  parents?: ParentModel[];
   events?: EventSpec[];
   history?: boolean;
   comments?: boolean;

package/dist/resource-model.js

@@ -70,7 +70,8 @@ const assembleModel = (state) => {
 		...state.history && { history: true },
 		...state.comments && { comments: true },
 		...state.live && { live: true },
-		...state.position && { position: { ...state.position } }
+		...state.position && { position: { ...state.position } },
+		...state.parents && { parents: state.parents.map((parent) => ({ ...parent })) }
 	};
 };
 const sensitiveProblems = (model) => Object.values(model.fields).filter((field) => field.sensitive).flatMap((field) => [
@@ -130,6 +131,15 @@ const positionProblems = (model) => {
 		...model.position.after && model.primaryKey.length !== 1 ? [`position "${name}" ranks after other records, which needs a key of one field`] : []
 	];
 };
+const parentProblems = (model) => (model.parents ?? []).flatMap(({ field: name, access }, index, parents) => {
+	const field = Object.hasOwn(model.fields, name) ? model.fields[name] : void 0;
+	return [
+		...!field ? ["is not a field"] : field.type !== "relation" ? [`is ${field.type}, not a relation`] : [],
+		...field?.relation && field.relation.columns.length !== 1 ? ["is a relation of several columns (not implemented)"] : [],
+		...access === "read" || access === "update" ? [] : [`needs "${String(access)}", not "read" or "update"`],
+		...parents.findIndex((parent) => parent.field === name) !== index ? ["is given twice"] : []
+	].map((problem) => `parent "${name}" ${problem}`);
+});
 const aiProblems = (model) => Object.values(model.fields).filter((field) => field.ai).flatMap((field) => [
 	...field.type === "text" || field.type === "enum" ? [] : [`is ${field.type}, not text or an enum`],
 	...field.nullable ? [] : ["must be optional(), empty until the job fills it"],
@@ -150,6 +160,7 @@ const buildResourceModel = (state) => {
 		...sensitiveProblems(model),
 		...fileProblems(model),
 		...positionProblems(model),
+		...parentProblems(model),
 		...aiProblems(model),
 		...computedProblems(model),
 		...events?.problems ?? []

package/dist/resource.d.ts

@@ -1,4 +1,4 @@
-import { PositionAfterModel, ResourceModel, SearchMatch } from "./model.js";
+import { ParentAccess, PositionAfterModel, ResourceModel, SearchMatch } from "./model.js";
 import { FieldAccess } from "./access/types.js";
 import { FieldRefs, FieldsInput, Ref } from "./refs.js";
 import { EventHelpers, EventMatch, EventSpec } from "./events/event-helpers.js";
@@ -86,6 +86,19 @@ export declare class ResourceBuilder<F extends FieldsInput = {}, K = never> {
     within?: (r: FieldRefs<F>) => Ref;
     after?: PositionAfterModel;
   }): ResourceBuilder<F, K>;
+  /**
+   * A relation whose record each record belongs to, and the access on it writing them needs: creating a record, changing
+   * it (the parent it leaves and the one it moves to), deleting and undeleting it all need `access` on the parent,
+   * checked with the caller's own access rules on its resource and locked until the write commits. A null relation
+   * checks nothing; each call adds a check. See
+   * [Records that belong to another](website/src/content/docs/reference/access.mdx#records-that-belong-to-another).
+   *
+   * @example
+   * ```ts
+   * .parent((r) => r.vm_id, 'update')
+   * ```
+   */
+  parent(pick: (r: FieldRefs<F>) => Ref, access: ParentAccess): ResourceBuilder<F, K>;
   /**
    * The events changes to its records raise, captured in the database for every write, from the API or elsewhere. See
    * [Declaring events](website/src/content/docs/reference/events.mdx#declaring-events).

package/dist/resource.js

@@ -100,6 +100,24 @@ var ResourceBuilder = class ResourceBuilder {
 		} });
 	}
 	/**
+	* A relation whose record each record belongs to, and the access on it writing them needs: creating a record, changing
+	* it (the parent it leaves and the one it moves to), deleting and undeleting it all need `access` on the parent,
+	* checked with the caller's own access rules on its resource and locked until the write commits. A null relation
+	* checks nothing; each call adds a check. See
+	* [Records that belong to another](website/src/content/docs/reference/access.mdx#records-that-belong-to-another).
+	*
+	* @example
+	* ```ts
+	* .parent((r) => r.vm_id, 'update')
+	* ```
+	*/
+	parent(pick, access) {
+		return this.next({ parents: [...this.state.parents ?? [], {
+			field: pick(this.refs()).name,
+			access
+		}] });
+	}
+	/**
 	* The events changes to its records raise, captured in the database for every write, from the API or elsewhere. See
 	* [Declaring events](website/src/content/docs/reference/events.mdx#declaring-events).
 	*

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@protobase/schema",
-  "version": "0.27.0",
+  "version": "0.28.1",
   "description": "Resource, field, view and access definitions for Protobase configs.",
   "license": "Apache-2.0",
   "repository": {