@antelopejs/interface-dms-builder 0.4.0 → 0.5.0

package/README.md

@@ -19,7 +19,7 @@ The AntelopeJS interface that edits the pages, blocks, resources and queries of
 - Reports every block type and DataType the builder can write, with a schema for its options (`GetCatalog`).
 - Returns every mutation as an `OpResult`. It holds the files changed on success, and a typed error otherwise.
 
-Every operation is an `InterfaceFunction` routed to [`@antelopejs/dms-builder`](https://www.npmjs.com/package/@antelopejs/dms-builder). That module parses the project, applies the edit as an AST rewrite, and writes only if the project still typechecks.
+Every operation is an `InterfaceFunction` that [`@antelopejs/dms`](https://www.npmjs.com/package/@antelopejs/dms) implements in development. The DMS parses the project, applies the edit as an AST rewrite, and writes only if the project still typechecks.
 
 ## Install
 
@@ -65,11 +65,11 @@ The interface declares this peer dependency:
 
 | Package                      | Supported        | Tested with |
 | ---------------------------- | ---------------- | ----------- |
-| `@antelopejs/interface-core` | `>=0.2.4 <1.0.0` | `0.4.0`     |
+| `@antelopejs/interface-core` | `>=0.5.1 <1.0.0` | `0.5.1`     |
 
 <!-- antelopejs-docs-compat:end -->
 
-The `@antelopejs/dms-builder` module implements this interface. The `@antelopejs/interface-dms-builder` row in the compatibility block of the [module README](../dms-builder/README.md#compatibility) gives the interface range each module release implements. The implementation is not a peer dependency of the interface package. It runs in development only, unless its [`api.enabled`](https://dms.antelopejs.com/docs/modules/builder/configuration) option turns it on.
+The `@antelopejs/dms` module implements this interface, and so does the `@antelopejs/dms-builder` module. The `@antelopejs/interface-dms-builder` entry in the `dependencies` of `@antelopejs/dms` gives the interface range each `@antelopejs/dms` release implements. The implementation is not a peer dependency of the interface package. It runs in development only, unless the [`builder.enabled`](https://dms.antelopejs.com/docs/building/configuration) option of `@antelopejs/dms` turns it on.
 
 ## Documentation
 
@@ -79,7 +79,7 @@ The `@antelopejs/dms-builder` module implements this interface. The `@antelopejs
 
 ## Contributing
 
-This package lives in the [`AntelopeJS/dms-builder`](https://github.com/AntelopeJS/dms-builder) pnpm workspace, next to the module that implements it. Read [CONTRIBUTING.md](https://github.com/AntelopeJS/dms-builder/blob/main/CONTRIBUTING.md) and the [repository README](https://github.com/AntelopeJS/dms-builder#contributing) for the development commands. Release this package before the module that implements it.
+This package lives in the [`AntelopeJS/dms`](https://github.com/AntelopeJS/dms) pnpm workspace, next to the module that implements it. Read [CONTRIBUTING.md](https://github.com/AntelopeJS/dms/blob/main/CONTRIBUTING.md) and the [repository README](https://github.com/AntelopeJS/dms#contributing) for the development commands. Release this package before the module that implements it.
 
 ## License
 

package/dist/addressing.d.ts

@@ -1,3 +1,9 @@
+/** A page's unique route string, e.g. `/settings/profile`. */
 export type PageRef = string;
+/**
+ * A block's address within a page: `<pageRef>#<name>[/<childId>...]`,
+ * e.g. `/dashboard#kpis/row/revenue`.
+ */
 export type BlockPath = string;
+/** A category's stable id/slug. */
 export type CategoryRef = string;

package/dist/analysis.d.ts

@@ -1,26 +1,34 @@
 import type { ColumnDisplay, TabsChoice } from "./mapping";
 import type { ResourceRef } from "./resources";
 import type { OpResult } from "./results";
+/** Whether a proposed choice follows from the catalog alone, or is a judgement to check. */
 export type ProposedKind = "fact" | "default";
+/** A choice the analysis made, with the rule that made it. */
 export interface Proposed<T> {
     value: T;
+    /** The rule's id, e.g. `R6`, `L1`, `F5`. */
     rule: string;
     kind: ProposedKind;
 }
+/** A declaration the analysis chose, and why it does not round-trip when it does not. */
 export interface ProposedDeclaration extends Proposed<string> {
     lossy?: string;
 }
+/** A relation column the analysis chose; `implied` when the database declares no foreign key. */
 export interface ProposedRelationColumn extends Proposed<string> {
     implied: boolean;
 }
+/** The ends of a number, date or enum column. */
 export interface ProposedRange {
     min: number | string;
     max: number | string;
 }
+/** A category of a column with few distinct values, with its rows. */
 export interface ProposedCategory {
     value: string | number | boolean;
     rows: number;
 }
+/** What the column's profile measured, for the person deciding: aggregates, never a row. */
 export interface ProposedColumnProfile {
     traits: string[];
     nulls?: number;
@@ -28,9 +36,12 @@ export interface ProposedColumnProfile {
     range?: ProposedRange;
     categories?: ProposedCategory[];
 }
+/** One column of a proposed relation, each aspect with its rule. */
 export interface ProposedField {
     column: string;
+    /** The column's native type. */
     native: string;
+    /** Every declaration the column accepts, the proposed one among them. */
     accepts: string[];
     declared: ProposedDeclaration;
     label: Proposed<string>;
@@ -38,59 +49,93 @@ export interface ProposedField {
     filterable: Proposed<boolean>;
     sortable: Proposed<boolean>;
     searchable: Proposed<boolean>;
+    /** How the column is drawn (D1, D2); absent when it is plain. */
     display?: Proposed<ColumnDisplay>;
+    /** `"schema.name"` of the relation this column refers to, when it becomes a relation column. */
     relation?: ProposedRelationColumn;
     profile?: ProposedColumnProfile;
 }
+/** A column the analysis leaves out, and why. */
 export interface ProposedLeftOut {
     column: string;
     reason: string;
     rule: string;
 }
+/** What the analysis's connection may write to a relation. */
 export interface ProposedWrites {
     insert: boolean;
     update: boolean;
     delete: boolean;
 }
+/** One relation the analysis proposes to map, in the shape `MapResources` takes. */
 export interface ProposedResource {
+    /** `"schema.name"`. */
     relation: string;
     tableView: Proposed<boolean>;
     writable: Proposed<boolean>;
+    /** The column relation columns pointing here show; null when no column is one. */
     label: Proposed<string | null>;
     title: Proposed<string>;
+    /** The tabs of its TableView (T1); absent when no column suits them. */
     tabs?: Proposed<TabsChoice>;
     fields: ProposedField[];
     leftOut: ProposedLeftOut[];
     writes: ProposedWrites;
+    /** Its rows, counted by the profile or estimated; absent when neither is known. */
     rows?: number;
+    /**
+     * The rows its column profiles were measured on: the sample's, when the profile sampled the
+     * relation, else its rows. A column's `nulls` is out of these.
+     */
     profiledRows?: number;
 }
+/** A relation the analysis does not propose, and why. */
 export interface ProposedExclusion {
     relation: string;
     reason: string;
     rule: string;
 }
+/**
+ * The kinds of question the rules leave open. A `field-type` item asks which declaration reads a
+ * column whose values have several native types, none covering enough of them: unanswered, the
+ * column is left out.
+ */
 export type OpenItemKind = "schemas" | "purpose" | "label" | "reference" | "field-type";
+/** One answer an open item offers. */
 export interface OpenItemOption {
     value: unknown;
     title: string;
 }
+/** A question the rules could not decide, with its options. */
 export interface OpenItem {
+    /** Stable across runs, e.g. `label:erp.customers`. */
     id: string;
     kind: OpenItemKind;
     relation?: string;
     column?: string;
     question: string;
     options: OpenItemOption[];
+    /** What the proposal holds meanwhile, if anything. */
     proposed: unknown;
+    /** For a `purpose` item, the relation as it would be mapped should the answer be to map it. */
     resource?: ProposedResource;
+    /**
+     * For a `purpose` item, the questions its `resource` leaves open, to answer should the answer be
+     * to map it. Absent when it leaves none.
+     */
     open?: OpenItem[];
 }
+/** The connected database, as the analysis's connection sees it. */
 export interface ProposalDatabase {
     engine: string;
     role: string;
     writes: "none" | "some" | "all";
 }
+/**
+ * A mapping of a connection's relations into a module, proposed from the catalog by fixed rules.
+ * Every choice names its rule. It writes nothing: settling it and sending it to `MapResources` is
+ * the caller's.
+ */
 export interface MappingProposal {
     connection: string;
     module: string;
@@ -99,19 +144,25 @@ export interface MappingProposal {
     excluded: ProposedExclusion[];
     open: OpenItem[];
 }
+/** Which connection to analyse, for which module, optionally limited to some schemas. */
 export interface AnalyseDatabaseInput {
+    /** The id of the builder's catalog connection. */
     connection: string;
+    /** The module the mapping is for; relations mapped or excluded there are not proposed again. */
     module: string;
     schemas?: string[];
 }
+/** How far an analysis has come. */
 export interface AnalysisProgress {
     relations: number;
     described: number;
     toProfile: number;
     profiled: number;
+    /** Measures that did not finish in their time. */
     timeouts: number;
 }
 export type AnalysisStatus = "running" | "done" | "failed";
+/** An analysis job: its progress, then its proposal or its failure. */
 export interface AnalysisState {
     id: string;
     connection: string;
@@ -120,11 +171,33 @@ export interface AnalysisState {
     proposal?: MappingProposal;
     error?: string;
 }
+/**
+ * Starts an analysis of a connection's database, and answers its job at once. Profiling is
+ * slow, so the proposal comes later through `GetAnalysis`. One job runs per connection; starting
+ * another while one runs answers the running one.
+ */
 export declare const AnalyseDatabase: (input: AnalyseDatabaseInput) => Promise<OpResult<AnalysisState>>;
+/**
+ * An analysis job's progress, then its proposal. A finished job is kept until the next one on
+ * its connection, or a restart.
+ */
 export declare const GetAnalysis: (id: string) => Promise<OpResult<AnalysisState>>;
+/**
+ * The latest analysis of a connection: the running one, or else the last to finish. `not_found`
+ * when none ran since the start.
+ *
+ * Owner path only: no MCP tool exposes it, so only an owner-authenticated entry calls it.
+ */
+export declare const GetLatestAnalysis: (connection: string) => Promise<OpResult<AnalysisState>>;
+/**
+ * A relation a module maps, read back from its code as its current choices, in a proposal's shape:
+ * every choice cites the rule `mapped`.
+ */
 export interface MappedRelation {
     ref: ResourceRef;
     resource: ProposedResource;
+    /** The columns the module declares; the rest of `resource.fields` are the catalog's others. */
     included: string[];
 }
+/** The relations a module maps for a connection, as their current choices, to change and map again. */
 export declare const GetMapping: (connection: string, module: string) => Promise<OpResult<MappedRelation[]>>;

package/dist/analysis.js

@@ -1,8 +1,25 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.GetMapping = exports.GetAnalysis = exports.AnalyseDatabase = void 0;
+exports.GetMapping = exports.GetLatestAnalysis = exports.GetAnalysis = exports.AnalyseDatabase = void 0;
 const interface_core_1 = require("@antelopejs/interface-core");
+/**
+ * Starts an analysis of a connection's database, and answers its job at once. Profiling is
+ * slow, so the proposal comes later through `GetAnalysis`. One job runs per connection; starting
+ * another while one runs answers the running one.
+ */
 exports.AnalyseDatabase = (0, interface_core_1.InterfaceFunction)();
+/**
+ * An analysis job's progress, then its proposal. A finished job is kept until the next one on
+ * its connection, or a restart.
+ */
 exports.GetAnalysis = (0, interface_core_1.InterfaceFunction)();
+/**
+ * The latest analysis of a connection: the running one, or else the last to finish. `not_found`
+ * when none ran since the start.
+ *
+ * Owner path only: no MCP tool exposes it, so only an owner-authenticated entry calls it.
+ */
+exports.GetLatestAnalysis = (0, interface_core_1.InterfaceFunction)();
+/** The relations a module maps for a connection, as their current choices, to change and map again. */
 exports.GetMapping = (0, interface_core_1.InterfaceFunction)();
 //# sourceMappingURL=analysis.js.map

package/dist/analysis.js.map

@@ -1 +1 @@
-{"version":3,"file":"analysis.js","sourceRoot":"","sources":["../src/analysis.ts"],"names":[],"mappings":";;;AAAA,+DAA+D;AA8MlD,QAAA,eAAe,GAC1B,IAAA,kCAAiB,GAEd,CAAC;AAMO,QAAA,WAAW,GACtB,IAAA,kCAAiB,GAAoD,CAAC;AAc3D,QAAA,UAAU,GACrB,IAAA,kCAAiB,GAEd,CAAC"}
+{"version":3,"file":"analysis.js","sourceRoot":"","sources":["../src/analysis.ts"],"names":[],"mappings":";;;AAAA,+DAA+D;AAyM/D;;;;GAIG;AACU,QAAA,eAAe,GAC1B,IAAA,kCAAiB,GAEd,CAAC;AAEN;;;GAGG;AACU,QAAA,WAAW,GACtB,IAAA,kCAAiB,GAAoD,CAAC;AAExE;;;;;GAKG;AACU,QAAA,iBAAiB,GAC5B,IAAA,kCAAiB,GAA4D,CAAC;AAahF,uGAAuG;AAC1F,QAAA,UAAU,GACrB,IAAA,kCAAiB,GAEd,CAAC"}

package/dist/catalog.d.ts

@@ -1,44 +1,103 @@
 import type { ConfigObject } from "./values";
+/**
+ * An import the emitter must add: `import { <name> } from "<module>"`. Either a
+ * package `module` specifier (fixed, file-independent) or a `targetFile` absolute
+ * path resolved to a relative specifier against the emitting file (e.g. a `$ref`
+ * to a local resource class).
+ */
 export interface ImportRef {
     name: string;
     module?: string;
     targetFile?: string;
 }
+/** A named region of a container block (e.g. a Tab's slots). */
 export interface SlotDescriptor {
     id: string;
     label?: string;
     description?: string;
 }
+/**
+ * A container whose slots come from its own options rather than being fixed —
+ * `Tab`, whose `items[].slot` names each region. Read the option at `optionPath`
+ * of the block's config to enumerate them.
+ */
 export interface DynamicSlots {
     optionPath: string;
     idKey: string;
     labelKey?: string;
 }
+/** The editor control an option is best edited with. */
 export type OptionWidget = "text" | "textarea" | "number" | "range" | "switch" | "select" | "segmented" | "icon" | "color" | "url" | "resource" | "field" | "dataType" | "dataSource" | "permission" | "json" | "block";
+/** How a builder UI should present one option. */
+/** A resource aspect a field must carry for an option naming it to work. */
 export type FieldAspect = "listable" | "searchable" | "sortable" | "filterable";
 export interface OptionUi {
     label?: string;
     widget?: OptionWidget;
+    /** Section the option belongs to: `content` | `data` | `appearance` | … */
     group?: string;
     order?: number;
+    /** Not editable from a config panel — transport-only or code-only. */
     hidden?: boolean;
     placeholder?: string;
     min?: number;
     max?: number;
     step?: number;
+    /** Dotted path to the option whose value scopes this one. */
     scope?: string;
+    /** Block types a `block` widget accepts. */
     blockTypes?: string[];
+    /**
+     * The options of the block a `block` widget holds that the block holding it
+     * supplies itself: a card fetches and heads the chart it wraps.
+     */
     supplies?: string[];
+    /**
+     * The aspect, or aspects, a `field` widget's value must carry on the
+     * resource. Naming a field that lacks one is written and then ignored at
+     * runtime, so it is refused instead.
+     */
     fieldAspect?: FieldAspect | FieldAspect[];
+    /**
+     * Render an object option's own properties in its group rather than nested
+     * under its label — a set of switches that reads as one list of features.
+     */
     flatten?: boolean;
+    /**
+     * What to call each value of an enum, keyed by the value: `Last 30 days`
+     * rather than `last-30-days`.
+     */
     valueLabels?: Record<string, string>;
+    /**
+     * The sibling option this one's value can be derived from — a field's key
+     * from its label. The builder writes it itself in its simple mode.
+     */
     derivedFrom?: string;
+    /**
+     * The switch this option sits behind, by its label: offered once an author
+     * turns it on, left out while it is off.
+     */
     optIn?: string;
+    /**
+     * The sibling option holding the data type this value is one of: a field's
+     * default takes the input its type calls for.
+     */
     typedBy?: string;
+    /** Offered in the builder's advanced view only. */
     advanced?: boolean;
+    /** What the builder places a new block with, when not the option's default. */
     initial?: unknown;
 }
-export type OptionType = "string" | "number" | "boolean" | "object" | "array" | "record" | "union" | "unknown";
+/** The primitive kinds a described option reduces to. */
+export type OptionType = "string" | "number" | "boolean" | "object" | "array" | "record"
+/** Branches of differing kinds; read `oneOf` rather than `type`. */
+ | "union" | "unknown";
+/**
+ * A JSON-Schema-ish description of one option. Two DMS extensions carry over
+ * from the inferred path: `x-dataType` marks a value that is a
+ * `new <DataType>(...)` instance (a Form field's `type`), and `x-component`
+ * marks one that holds a nested component.
+ */
 export interface OptionSchema {
     type: OptionType;
     optional?: boolean;
@@ -46,68 +105,147 @@ export interface OptionSchema {
     description?: string;
     default?: unknown;
     enum?: Array<string | number | boolean>;
+    /** Object shape, keyed by property name. */
     properties?: Record<string, OptionSchema>;
+    /** Array element shape. */
     items?: OptionSchema;
+    /** Record value shape. */
     values?: OptionSchema;
+    /**
+     * Record key shape. A key drawn from a closed set carries it as `enum`, so
+     * an editor can offer one entry per key.
+     */
     keys?: OptionSchema;
+    /** Union branches, in declaration order. */
     oneOf?: OptionSchema[];
+    /** Property carrying the branch tag of a discriminated union. */
     discriminator?: string;
+    /** Positional element shapes of a tuple, in order. */
     prefixItems?: OptionSchema[];
+    /** Shapes a value must satisfy at once, for an intersection. */
     allOf?: OptionSchema[];
+    /**
+     * The shape is deeper than the catalog describes. What is reported is
+     * accurate as far as it goes; the value has more structure below it.
+     */
     truncated?: boolean;
     ui?: OptionUi;
     "x-dataType"?: boolean;
     "x-component"?: boolean;
+    /**
+     * The option is handed a table's DataAPI class — a relation's
+     * `dataApiController`. Its value is a `$ref` to a resource.
+     */
     "x-controller"?: boolean;
 }
+/**
+ * A block's or DataType's options, keyed by option name. Declared schemas
+ * (`configOrigin: "annotated"`) carry labels, defaults and widgets; inferred ones
+ * carry only what the TypeScript signature revealed.
+ */
 export type ConfigSchema = Record<string, OptionSchema>;
+/** How a block type's emit shape was determined. */
 export type ConfigOrigin = "inferred" | "annotated";
+/**
+ * The palette section a block type belongs to. The four the DMS ships are
+ * spelled out; a newer DMS declaring another one passes through rather than
+ * being dropped, so its blocks stay listable.
+ */
 export type BlockGroup = "layout" | "content" | "data" | "visualization" | (string & {});
+/** A block factory the builder can emit and configure. Keyed on `type`. */
 export interface BlockTypeDescriptor {
+    /** Factory export name, e.g. `KpiCard` — the catalog key. */
     type: string;
     import: ImportRef;
+    /** Frontend component name the factory emits, e.g. `dms-kpi-card`. */
     componentName?: string;
+    /** Human label for the palette; falls back to `type`. */
     label?: string;
     icon?: string;
     group?: BlockGroup;
+    /** Whether the block accepts `.child(...)`. */
     container: boolean;
+    /** Block types accepted as children; any type when absent. */
     allowedChildren?: string[];
     slots?: SlotDescriptor[];
     dynamicSlots?: DynamicSlots;
     config: ConfigSchema;
+    /** Option values the factory applies when the caller omits them. */
     defaults?: ConfigObject;
+    /** Schema of the metadata a child carries, e.g. `{ colSpan }`. */
     childMeta?: ConfigSchema;
+    /**
+     * Options the factory sets itself whatever the caller passes — a chart's
+     * `type`, which is what tells `dms-chart-block` which chart to draw. Emitting them
+     * is unnecessary; a consumer rendering from the descriptor alone merges them
+     * in.
+     */
     fixedOptions?: ConfigObject;
     configOrigin: ConfigOrigin;
     description?: string;
+    /**
+     * True when the factory takes a leading controller-class argument before its
+     * options object (e.g. `TableView(controller, options)`). Such blocks require
+     * `AddBlockInput.controller`; `config` describes the options (second) argument.
+     */
     controllerArg?: boolean;
+    /**
+     * The children an editor places in a new block of this type, as the DMS's
+     * own helper places them in code: a `PageToolbar`'s `LiveToggle` and
+     * `PeriodSelector` with the defaults of `pageToolbar()`.
+     */
     initialChildren?: BlockInitialChild[];
 }
+/** One child a new block starts with (see `BlockTypeDescriptor.initialChildren`). */
 export interface BlockInitialChild {
+    /** The child id under its parent, the one roles name it by. */
     id: string;
+    /** The child's block type, a key of the catalog (`LiveToggle`). */
     type: string;
+    /** The child's options. */
     options: ConfigObject;
 }
+/** A DataType usable as a Form field's `type`. */
 export interface DataTypeDescriptor {
+    /** Registered id, e.g. `string` | `number` | `select`. */
     id: string;
     import: ImportRef;
     config: ConfigSchema;
     description?: string;
 }
+/** The full set of block types and DataTypes the builder can emit. */
 export interface BlockCatalog {
     blocks: BlockTypeDescriptor[];
     dataTypes: DataTypeDescriptor[];
+    /**
+     * Names a resource field may not take: they collide with a generated
+     * DataController route or a Model member, and are rejected with
+     * `invalid_config`. Reported here so a caller can pick a valid name up front
+     * rather than carrying its own copy of the list.
+     */
     reservedFieldNames: string[];
+    /** Cache key; invalidated on module-source change. */
     generatedAt: string;
 }
+/**
+ * A route a developer declared as something a block may read.
+ *
+ * Listed beside the calculations the builder generates, so a source editor
+ * offers both in one place. The builder never reads or rewrites the code behind
+ * one: it knows only what the declaration says.
+ */
 export interface DataSourceDescriptor {
     id: string;
     title: string;
     description?: string;
+    /** The shape it answers with, matched against what a block can read. */
     responseKind: string;
+    /** The path a block fetches, as declared. */
     path: string;
     method?: string;
+    /** Parameters it takes, in the same vocabulary as a block's options. */
     params?: ConfigSchema;
+    /** The query parameters it reads a period from, when it takes one. */
     period?: {
         from: string;
         to: string;

package/dist/compose.d.ts

@@ -4,52 +4,96 @@ import type { AddQueryInput, QueryPreview, QueryRef } from "./queries";
 import type { AddBlockInput, CreatePageInput } from "./operations";
 import type { ResourceRef } from "./resources";
 import type { MutationOpts, OpResult } from "./results";
+/**
+ * The query a data block reads, in {@link AddQueryInput}'s shape. The route it
+ * compiles to is written into the block's config, under `into`.
+ */
 export interface ComposeQuery extends Omit<AddQueryInput, "name"> {
+    /** The query's name; defaults to the block's name. */
     name?: string;
+    /** The block config key that receives the route. Defaults to `fetchUrl`. */
     into?: string;
+    /** Values for this query's preview, overriding {@link ComposePageInput.args}. */
     args?: QueryPreviewRequest["args"];
 }
+/** One block of a composed page; a container carries its blocks in `children`. */
 export interface ComposeBlock {
+    /** Unique among its siblings. */
     name: string;
+    /** A block type from the catalog, e.g. `GridRow`, `KpiCard`, `ChartCard`. */
     type: string;
     config?: AddBlockInput["config"];
+    /** The resource whose DataAPI leads a controller-leading block such as `TableView`. */
     controller?: ResourceRef;
+    /** The slot this block fills in its container. */
     slot?: string;
+    /** Child metadata such as `{ colSpan: 2 }` in a grid. */
     meta?: AddBlockInput["meta"];
+    /** The query this block reads; added to the page with the block. */
     query?: ComposeQuery;
+    /** Blocks nested in this one, in order. */
     children?: ComposeBlock[];
 }
+/** Where the new blocks go among the siblings already there: next to the block named. */
 export interface ComposePlacement {
     before?: string;
     after?: string;
 }
+/**
+ * Input for `ComposePage`: builds a whole page, or extends one, in one call.
+ * Name the page with `page`, or give the fields of one to create with `create`.
+ */
 export interface ComposePageInput {
     page?: PageRef;
     create?: CreatePageInput;
+    /** An existing container to add the blocks under; omit for the page itself. */
     parent?: BlockPath;
+    /** Position among the siblings already under `parent`; omit to append. */
     placement?: ComposePlacement;
+    /** The blocks to add, in order. */
     blocks: ComposeBlock[];
+    /**
+     * Run every query against the database and answer each block's result without
+     * writing anything. A second call without it writes.
+     */
     preview?: boolean;
+    /** The values every query's route would receive, e.g. `{ from, to }`; used by `preview`. */
     args?: QueryPreviewRequest["args"];
+    /** The tenant whose rows a preview reads. */
     tenant?: string;
 }
+/** A block the call added. */
 export interface ComposedBlock {
+    /** Where the block sits in the input, e.g. `/blocks/1/children/0`. */
     pointer: string;
     path: BlockPath;
     query?: QueryRef;
+    /** The route the block reads, as written into its config. */
     route?: string;
 }
+/** What one block's query answered in a preview. */
 export interface ComposePreviewBlock {
     pointer: string;
     block: string;
+    /** `empty`: no rows. `zero`: rows, but every figure is zero or missing. `error`: the query was refused. */
     status: "ok" | "empty" | "zero" | "error";
     preview?: QueryPreview;
+    /** Why the query was refused, when `status` is `error`. */
     error?: string;
 }
 export interface ComposePageData {
     page: PageRef;
+    /** False for a preview. */
     written: boolean;
     blocks: ComposedBlock[];
+    /** One entry per block that reads a query; filled by a preview. */
     previews: ComposePreviewBlock[];
 }
+/**
+ * Builds a page, or adds to one, in one operation: one rewrite of the page, one of
+ * the models, one typecheck, and nothing written when any block is refused. A
+ * refusal is `invalid_config` whose issues carry a JSON pointer into the input
+ * (`/blocks/2/children/0/query/params/...`) per refused block, or
+ * `typecheck_failed` when the whole would not compile.
+ */
 export declare const ComposePage: (input: ComposePageInput, opts?: MutationOpts | undefined) => Promise<OpResult<ComposePageData>>;

package/dist/compose.js

@@ -2,5 +2,12 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ComposePage = void 0;
 const interface_core_1 = require("@antelopejs/interface-core");
+/**
+ * Builds a page, or adds to one, in one operation: one rewrite of the page, one of
+ * the models, one typecheck, and nothing written when any block is refused. A
+ * refusal is `invalid_config` whose issues carry a JSON pointer into the input
+ * (`/blocks/2/children/0/query/params/...`) per refused block, or
+ * `typecheck_failed` when the whole would not compile.
+ */
 exports.ComposePage = (0, interface_core_1.InterfaceFunction)();
 //# sourceMappingURL=compose.js.map

package/dist/compose.js.map

@@ -1 +1 @@
-{"version":3,"file":"compose.js","sourceRoot":"","sources":["../src/compose.ts"],"names":[],"mappings":";;;AAAA,+DAA+D;AA2GlD,QAAA,WAAW,GACtB,IAAA,kCAAiB,GAKd,CAAC"}
+{"version":3,"file":"compose.js","sourceRoot":"","sources":["../src/compose.ts"],"names":[],"mappings":";;;AAAA,+DAA+D;AAoG/D;;;;;;GAMG;AACU,QAAA,WAAW,GACtB,IAAA,kCAAiB,GAKd,CAAC"}