@antelopejs/interface-dms-builder 0.3.1 → 0.4.1

package/docs/1.introduction.md

@@ -1,14 +1,18 @@
-# DMS Builder Documentation
+---
+title: "Introduction"
+description: "What the builder interface does, how an edit reaches your TypeScript files, and where each part of the contract is documented."
+mode: explanation
+---
 
-Use `@antelopejs/interface-dms-builder` to create and edit DMS pages from a backend module or a tool. The operations write ordinary TypeScript into your project; there is no separate database of page definitions.
+`@antelopejs/interface-dms-builder` creates and edits DMS pages from a backend module or a tool. The operations write ordinary TypeScript into your project. No separate database holds page definitions.
 
-If you want to edit a page with the mouse instead, start with the [visual builder guide](https://dms.antelopejs.com/docs/modules/builder/introduction).
+To edit a page with the mouse instead, start with the [visual builder guide](https://dms.antelopejs.com/docs/modules/builder/introduction).
 
-## Quick Start
+## Quick start
 
-This example creates a **Revenue** page with a **Total revenue** card. Run it once from a backend module after the builder is available, in a development project that loads both `@antelopejs/dms` and `@antelopejs/dms-builder`. Installing the interface package alone does not provide the implementation.
+This example creates a **Revenue** page with a **Total revenue** card. It runs once from a backend module after the builder is available, in a development project that loads both `@antelopejs/dms` and `@antelopejs/dms-builder`. The interface package alone does not provide the implementation.
 
-The project must already have a `pages` category. Use `ListCategories()` to find yours, or [create a category](./4.page-operations.md) first. Choose an unused page name: running a creation twice returns `duplicate_name`.
+The project must already have a `pages` category. `ListCategories()` lists yours, and [Create a category](./4.page-operations.md#create-a-category) adds one. The page name must be unused, because a second creation with the same name returns `duplicate_name`.
 
 ```typescript
 import {
@@ -45,33 +49,35 @@ for (const change of block.changes) {
 }
 ```
 
-After the backend reloads, open `/revenue` as a tenant owner. You should see the page and its card; the card has no revenue data yet. [Queries](./6.queries.md) connects a card to a resource when you are ready for real numbers.
+After the backend reloads, a tenant owner who opens `/revenue` sees the page and its card. The card has no revenue data yet. [Queries](./6.queries.md) connects a card to a resource for real numbers.
 
-Each call saves independently. If `CreatePage` succeeds but `AddBlock` fails, the empty page remains; fix the block configuration and retry that call, not the page creation.
+Each call saves on its own. If `CreatePage` succeeds and `AddBlock` fails, the empty page stays. Fix the block configuration and retry that call, not the page creation.
 
 ## How an edit reaches your files
 
-A *block* is one DMS component, such as a card or a table. Adding one writes a factory call into a `PageController` class, either as a static field or as a child of another block. The builder parses the source, stages the edit in memory and typechecks the project before writing it. A type error anywhere in the project can therefore block the edit.
+A *block* is one DMS component, such as a card or a table. Adding one writes a factory call into a `PageController` class, either as a static field or as a child of another block. The builder parses the source, stages the edit in memory and typechecks the whole project before it writes. A type error anywhere in the project outside `node_modules` can therefore block the edit.
 
-Operations are `InterfaceFunction` exports from `@antelopejs/interface-core`. Expected failures return values you can inspect:
+Operations are `InterfaceFunction` exports from `@antelopejs/interface-core`. An expected failure comes back as a value you can inspect:
 
 ```typescript
 // Success: { ok: true, data, changes, warnings? }
 // Failure: { ok: false, error }
 ```
 
-Listing operations such as `ListPages` return their value directly. See [Results and errors](./8.results-and-errors.md) for the full contract. When you read before writing, pass the structure's `version` as `expectedVersion` so another editor's work is not overwritten.
+Listing operations such as `ListPages` return their value directly. [Results and errors](./8.results-and-errors.md) holds the full contract. When you read before you write, pass the structure's `version` as `expectedVersion`, so that the write fails instead of overwriting another editor's work.
 
-Hand-written declarations remain editable when the builder recognizes their shape. Otherwise, it marks them *opaque*: you can inspect them without asking the builder to rewrite code it does not understand. Use [Drafts and preview](./9.drafts-and-preview.md) when an editor needs to save a whole block tree in one transaction.
+A caller that picks an operation by name, such as a route that forwards a request, reads `Operations`. It holds every operation under its exported name, with its own parameter and result types. `OperationName` is the union of those names.
 
-## Documentation Sections
+Hand-written declarations stay editable when the builder recognizes their shape. Otherwise the builder marks them *opaque*. You can inspect an opaque block, and the builder refuses to rewrite code it does not understand. [Drafts and preview](./9.drafts-and-preview.md) saves a whole block tree in one transaction.
 
-- [Addressing and Structure](./2.addressing-and-structure.md) - The refs that name a page, a block and a category, and the shapes the builder reads back
-- [Catalog](./3.catalog.md) - The block types, DataTypes and reserved names the builder can report
-- [Page Operations](./4.page-operations.md) - Create pages and categories, and edit a page's block tree
-- [Resources](./5.resources.md) - Generate tables, DataAPI controllers and their fields
-- [Queries](./6.queries.md) - Compile a measure, grouped or not, into a model method and a page route
-- [Value Encodings](./7.values.md) - Write configuration values that are not plain literals
-- [Results and Errors](./8.results-and-errors.md) - Branch on `OpResult`, read diagnostics, and make a write conditional
-- [Drafts and Preview](./9.drafts-and-preview.md) - Write a page's blocks and the data they read in one transaction, and preview either
-- [A Chart Without Code](./10.a-chart-without-code.md) - The whole journey, from picking a measure to reopening the page
+## Documentation sections
+
+- [Addressing and structure](./2.addressing-and-structure.md) covers the refs that name a page, a block and a category, and the shapes the builder reads back.
+- [Catalog](./3.catalog.md) lists the block types, DataTypes and reserved names the builder reports.
+- [Page operations](./4.page-operations.md) creates pages and categories, and edits the block tree of a page.
+- [Resources](./5.resources.md) generates tables, DataAPI controllers and their fields.
+- [Queries](./6.queries.md) compiles a measure, grouped or not, into a model method and a page route.
+- [Value encodings](./7.values.md) writes configuration values that are not plain literals.
+- [Results and errors](./8.results-and-errors.md) branches on `OpResult`, reads diagnostics, and makes a write conditional.
+- [Drafts and preview](./9.drafts-and-preview.md) writes the blocks of a page and the data they read in one transaction, and previews either.
+- [A chart without code](./10.a-chart-without-code.md) follows one chart from the choice of a measure to the reopened page.

package/docs/10.a-chart-without-code.md

@@ -1,23 +1,20 @@
-# A Chart Without Code
+---
+title: "A chart without code"
+description: "Preview a revenue chart against real rows, save the chart card and its data route in one write, and reopen the page with the chart's settings filled in, through the calls behind the visual builder."
+mode: tutorial
+---
 
-Build an editor that lets someone choose a table, a measure and a grouping, then
-save a chart without writing its data route by hand. This walkthrough follows the
-interface calls behind the visual builder; it is not a standalone script.
+In this tutorial we save a revenue chart grouped by month without writing its data route by hand. We follow the interface calls that the visual builder makes when someone picks a table, a measure and a grouping. The calls run inside a project, so this page is not a standalone script.
 
-![The visual builder with a chart selected and its settings open](./images/editor-selected.png)
+![The visual builder with a KPI card selected and its settings open](./images/captures/editor-selected.webp)
 
-You need an existing `/shop/board` page and an `order` resource with numeric
-`amount`, date `createdAt` and `status` fields. Run these calls inside a project
-that loads the builder. Use a disposable page for the save example: its draft
-replaces the page's existing blocks.
+Before we start, we need an existing `/shop/board` page and an `order` resource with a numeric `amount` field, a date `createdAt` field and a `status` field. Run the calls inside a project that loads the builder. Use a disposable page for the save step, because its draft replaces the page's existing blocks.
 
-The result is a revenue chart grouped by month. Start with all paid orders;
-add period controls and comparison only after this first chart works.
+We start with all paid orders. Period controls and a comparison come after the first chart works.
 
 ## Show the data before writing anything
 
-While the person is still choosing, `PreviewQuery` runs the calculation against
-the real table and answers what the route would:
+While the person is still choosing, `PreviewQuery` runs the calculation against the real table and answers what the route would:
 
 ```typescript
 import { PreviewQuery } from "@antelopejs/interface-dms-builder";
@@ -46,16 +43,11 @@ if (preview.ok) {
 }
 ```
 
-Nothing has been written yet. On success, `preview.data.body` has the response
-shape the chart card reads, including its headline figure. The saved route uses
-the same calculation, but its values can change as rows change. Check `truncated`
-before treating a limited preview as a complete result. For a per-tenant resource,
-also pass the tenant id in `PreviewQuery`'s `tenant` option.
+Nothing is written yet. On success, `preview.data.body` holds the response that the chart card reads, headline figure included. The saved route runs the same calculation, but its values change as the rows change. The preview stops at 500 points, so check `truncated` before you treat the preview as complete. For a per-tenant resource, also pass the tenant id in the `tenant` field of the `PreviewQuery` request.
 
 ## Save the block and its data together
 
-The query travels in the page draft, so one save writes the block, the model
-method and the route in a single transaction:
+The query travels in the page draft, so one save writes the block, the model method and the route in a single transaction:
 
 ```typescript
 import { GetPageStructure, SetPageBlocks } from "@antelopejs/interface-dms-builder";
@@ -97,33 +89,28 @@ const saved = await SetPageBlocks("/shop/board", {
 if (!saved.ok) throw new Error(saved.error.code);
 ```
 
-After the backend reloads, open `/shop/board` as a tenant owner. The card reads
-`/dms/pages/shop/board/stats/revenue-chart` and shows the saved calculation.
-Either the blocks and query save together or neither changes.
+After the backend reloads, open `/shop/board` as a tenant owner. The card reads `/dms/pages/shop/board/stats/revenue-chart` and shows the saved calculation. The blocks and the query save together, or neither changes.
 
-Two details the engine will hold you to. The block and the query cannot share a
-name: both become members of the page class, so a query named after the block it
-feeds comes back as `duplicate_name` in the `query` scope — name the block for
-what it is and the query for what it answers. And a `ChartCard` requires the
-chart it wraps, so a config without `chart` fails the save on `typecheck_failed`
-rather than on a validation message.
+The engine holds us to two details:
 
-## Reference: add a period and comparison
+- Give the block and the query different names. Name the block for what it is and the query for what it answers, so the page class reads clearly.
+- A `ChartCard` requires the chart it wraps. A config without `chart` fails the save with `typecheck_failed`, not with a validation issue.
 
-The first example intentionally has no period filter. To make the chart follow a
-page period, add `periodScope: "page"` to the card, bind `from` and `to` in the
-query's date filters, and supply the page's period selector. Set `compare: true`
-only when requests also supply `compareFrom` and `compareTo`. Pass the same filters
-and arguments to `PreviewQuery` to preview that period, rather than all paid orders.
-See [request-time bindings](./6.queries.md#bind-a-value-at-request-time).
+## Add a period and a comparison
 
-With those period filters added, the generated code has the following shape.
-These fragments illustrate the model method and route; they are not extra files
-you need to write for the walkthrough.
+The first chart has no period filter. To make the chart follow a page period, we make three changes:
+
+1. Add `periodScope` to the card, set to the id of the page's `PeriodSelector`, such as `"page"`.
+2. Bind `from` and `to` in the query's date filters. See [request-time bindings](./6.queries.md#bind-a-value-at-request-time).
+3. Add the `PeriodSelector` with that id to the page.
+
+To show a comparison, set `compare: true` on the query. The route then also reads `compareFrom` and `compareTo`, which the selector sends while a comparison is on. To preview that period instead of all paid orders, pass the same filters to `PreviewQuery`, with the period values in `args`.
+
+With those period filters added, the builder writes code of the following shape. We do not write these fragments ourselves. They show what the save produces.
 
 A method on the resource's model:
 
-```typescript
+```typescript fragment
 revenueChart(minCreatedAt: Date, maxCreatedAt: Date) {
   return this.table
     .filter((row) => row.key("status").eq("paid"))
@@ -138,9 +125,9 @@ revenueChart(minCreatedAt: Date, maxCreatedAt: Date) {
 }
 ```
 
-And a route on the page, guarded with the page's own permission:
+A route on the page, guarded with the page's own permission:
 
-```typescript
+```typescript fragment
 @Get("/stats/revenue-chart")
 async revenueChart(
   @AuthUserWithPermission(BoardPage) _user: User,
@@ -161,18 +148,13 @@ async revenueChart(
 }
 ```
 
-Ordinary code, in the application's own style, that a developer can read, edit
-and own.
+Both fragments are ordinary code in the application's own files. A developer can read, edit and own them.
 
-`label` is what a legend and a tooltip call the series. The builder takes it from
-the field being measured — the label the resource gives it — and from the resource
-itself for a count, which has no field to name: left out, the helper falls back to
-the measure's own word, and a reader who never asked for one would be shown "sum".
+`label` is what a legend and a tooltip call the series. For a measure over a field, the builder takes the field's label, or the field's name when the field has no label. For a count, which has no field, it takes the resource ref. Without a `label`, the helper falls back to the measure's own word, and the chart would show "sum".
 
-## Reopen it
+## Reopen the chart
 
-`GetPageStructure` reads the route and its chain back into the parameters that
-produced them, so the editor reopens filled in rather than empty:
+`GetPageStructure` reads the route and its chain back into the parameters that produced them, so the editor reopens with the chart's settings filled in:
 
 ```typescript
 import { GetPageStructure } from "@antelopejs/interface-dms-builder";
@@ -186,29 +168,24 @@ if (structure.ok) {
 }
 ```
 
-That read-back is what makes the journey repeatable rather than one-way. It is
-also what decides ownership: a chain edited past what the grammar accepts reads as
-`opaque`, and from then on the builder will list it and remove it but never
-rewrite it.
+The read-back makes the journey repeatable in both directions. It also decides ownership. When a developer edits a chain past what the grammar accepts, the query reads back as `opaque`. From then on, the builder lists the query and can remove it, but never rewrites it.
 
-## Where each guarantee lives
+## What we built
 
-| Guarantee | Where it comes from |
-| --- | --- |
-| Preview and saved queries use the same calculation | One `QueryPlan`, rendered by the emitter and run by the executor; rows and preview limits can differ |
-| The block and its data save together | `PageDraft.queries`, written in the page's transaction |
-| Reopening shows what was configured | The chain reads back into its parameters |
-| A developer's edit survives | An unreadable chain is opaque, and opaque is never rewritten |
-| The data is not public | The route carries the page's permission |
-| A tenant reads its own rows | The model provider is chosen from the resource's schema |
+We now have a chart that someone configured without code. Each step rests on one part of the builder:
 
-## Reference: what the block asks for
+- The preview and the saved query use the same calculation, because one `QueryPlan` feeds both the emitter that writes the model method and the executor that runs the preview. The rows and the preview limit can still differ.
+- The block and its data saved together, because `PageDraft.queries` is written in the page's transaction.
+- The page reopened with its settings, because the chain reads back into its parameters.
+- A developer's edit survives, because a chain the builder cannot read is opaque, and the builder never rewrites an opaque query.
+- The data is not public, because the route carries the page's permission.
+- A tenant reads its own rows, because the route's model provider follows the resource's schema.
 
-A block declares the response shape it can read beside its factory. The editor
-uses this catalog metadata to offer compatible calculations and find the option
-that controls the period:
+## See what the block asks for
 
-```typescript
+A block declares, beside its factory, the response shape it can read. The editor reads this catalog metadata to offer the calculations that fit and to find the option that controls the period. This is the `fetchUrl` option of `ChartCard`:
+
+```typescript fragment
 fetchUrl: ui(z.string().optional(), {
   label: "Data source",
   group: "data",
@@ -218,5 +195,4 @@ fetchUrl: ui(z.string().optional(), {
 });
 ```
 
-This is a schema fragment for a block author, not configuration to pass to
-`AddBlock`. An editor consumer reads it from [the catalog](./3.catalog.md).
+This fragment is part of a block's schema, for a block author. It is not configuration to pass to `AddBlock`. An editor reads it from [the catalog](./3.catalog.md).

package/docs/11.external-databases.md

@@ -1,29 +1,33 @@
-# External Databases
+---
+title: "External databases"
+description: "The operations that wire a database the project does not own into antelope.config.ts, analyse its catalog into a mapping proposal, and map its relations to table classes, controllers and TableView pages."
+mode: reference
+---
 
 ## Overview
 
-A DMS project can show pages over a database it does not own: a client's PostgreSQL, MongoDB or RethinkDB, read and written live through that engine's module (`@antelopejs/postgres`, `@antelopejs/mongodb`, `@antelopejs/rethinkdb`) in external mode. The builder takes such a database in four moves, each an operation:
+A DMS project can show pages over a database it does not own, such as a client's PostgreSQL, MongoDB or RethinkDB database. The engine's module (`@antelopejs/postgres`, `@antelopejs/mongodb` or `@antelopejs/rethinkdb`) reads and writes it live, in external mode. The builder takes such a database in four operations:
 
-1. **Wire it** into `antelope.config.ts` with `ConfigureProject`: the provider module, a local module for its tables, the builder's catalog connection, and the DMS module's pin to the project's own database.
-2. **Analyse it** with `AnalyseDatabase`, which reads the catalog and proposes a mapping by fixed rules. It writes nothing.
-3. **Decide** the proposal: a person in the builder's *Database* workspace, or an assistant through these operations.
-4. **Map it** with `MapResources`, which writes table classes, controllers and TableView pages into the module bound to the database.
+1. `ConfigureProject` wires the database into `antelope.config.ts`. It adds the provider module, a local module for the tables, the builder's catalog connection, and the DMS module's pin to the project's own database.
+2. `AnalyseDatabase` reads the catalog and proposes a mapping by fixed rules. It writes nothing.
+3. A person in the builder's **Database** workspace, or an assistant through these operations, settles the proposal.
+4. `MapResources` writes table classes, controllers and TableView pages into the module bound to the database.
 
-The builder reaches the database through `@antelopejs/interface-database-catalog`, a connection declared on its own module entry. It never connects with credentials of its own.
+The builder reaches the database through `@antelopejs/interface-database-catalog`, a connection declared on its own module entry. The builder never connects with credentials of its own.
 
-## Wire the Project
+## Wire the project
 
-`ConfigureProject(steps, opts?)` applies its steps to `antelope.config.ts` as one edit. Every step is validated before anything is written, and a refused step writes nothing. With `{ dryRun: true }` it answers the changes it would make, as `OpResult.changes`, so a caller can show the diff before writing.
+`ConfigureProject(steps, opts?)` applies its steps to `antelope.config.ts` in order, as one edit. It validates every step before it writes anything, and a refused step fails the call with `invalid_config` and writes nothing. With `{ dryRun: true }`, it answers the changes it would make as `OpResult.changes`, so a caller can show the diff before the write. The configuration must be a `defineConfig({ … })` or plain object literal with a literal `modules`.
 
 | Step | Writes |
 | --- | --- |
-| `AddModule` | a module entry, refusing an id that exists |
-| `ConfigureModule` | merges config, `importOverrides` (pins and connection ids), `exportPriority`, `disabledExports` and env variable names into an entry |
-| `CreateLocalModule` | scaffolds a local module and adds its entry; with `connection`, its record names that connection |
-| `RemoveModule` | removes an entry and the `envOverrides` entries supplying its config, refusing one another module still reads through; its files stay |
-| `RemoveConnection` | removes a named connection to an interface from every module's `importOverrides` |
+| `AddModule` | A module entry. Refuses an id that exists. |
+| `ConfigureModule` | Merges config, `importOverrides` (pins and connection ids), `exportPriority`, `disabledExports` and environment variable names into an existing entry. Refuses a pin that contradicts an existing one. |
+| `CreateLocalModule` | Scaffolds a local module at `path` and adds its entry. With `connection`, the module's `package.json` record names that connection. |
+| `RemoveModule` | Removes an entry and the `envOverrides` entries that supply its config. Refuses a module that another module's `importOverrides` names as a source. The module's files stay. |
+| `RemoveConnection` | Removes a named connection to an interface from every module's `importOverrides`. |
 
-`env` takes variable names, never values: each is added to `envOverrides`, and to `.env.example` when the project has one.
+`env` maps a config path to a variable name, never to a value. Each variable is added to `envOverrides`, and to `.env.example` when the project has one. A variable that already supplies another path is refused.
 
 The provider's entry depends on its engine:
 
@@ -31,9 +35,11 @@ The provider's entry depends on its engine:
 | --- | --- | --- | --- |
 | PostgreSQL | `@antelopejs/postgres` | `url` | none |
 | MongoDB | `@antelopejs/mongodb` | `url` and `database` | `@antelopejs/interface-mongodb` |
-| RethinkDB | `@antelopejs/rethinkdb` | `url`, the database as its path | `@antelopejs/interface-rethinkdb` |
+| RethinkDB | `@antelopejs/rethinkdb` | `url`, with the database as its path | `@antelopejs/interface-rethinkdb` |
 
-`disabledExports` keeps core from ever offering the external instance's raw client, so a module that needs the DMS's own MongoDB or RethinkDB client never gets the client's database instead.
+`disabledExports` stops core from offering the external instance's raw client. A module that needs the DMS's own MongoDB or RethinkDB client never gets the client's database instead.
+
+Replace `<version>` in the example with the range of the provider package to install. The **Database** workspace fills in a default range under **Advanced settings**, in the **Package version** field.
 
 ```typescript
 import { ConfigureProject } from "@antelopejs/interface-dms-builder";
@@ -45,7 +51,7 @@ const result = await ConfigureProject([
     op: "AddModule",
     id: "postgres-erp",
     entry: {
-      source: { type: "package", package: "@antelopejs/postgres", version: "^0.2.0" },
+      source: { type: "package", package: "@antelopejs/postgres", version: "<version>" },
       config: { mode: "external", statementTimeoutMs: 30000 },
       env: { url: "ERP_DATABASE_URL" },
       exportPriority: { "@antelopejs/interface-database": -1 },
@@ -71,26 +77,28 @@ const result = await ConfigureProject([
     entry: { importOverrides: [{ interface: catalog, source: "postgres-erp", id: "erp" }] },
   },
 ]);
+if (!result.ok) console.error(result.error);
 ```
 
 - The provider's `exportPriority` of `-1` keeps the project's own database the default for every module that does not pin `interface-database`.
-- The tables module pins `interface-database` to the provider, and uses the DMS. Core passes that pin on to the DMS, which every other module reaches with the default, so the DMS pins the project's own database to settle it. A DMS that already pins `interface-database` needs nothing more.
+- The tables module pins `interface-database` to the provider, and it uses the DMS. Core passes that pin on to the DMS, which every other module reaches with the default. The DMS therefore pins the project's own database to settle it. A DMS that already pins `interface-database` needs nothing more.
+- When the project loads `dms-ai`, the **Database** workspace gives it the same catalog connection as `dms-builder`.
 
 The connection exists once the project restarts with the variable set.
 
-### Remove a Connection
+### Remove a connection
 
-Removing a connection takes its catalog connections and its tables module out of the configuration, with `RemoveConnection` and `RemoveModule`. The tables module's folder is deleted with it. The database itself is untouched.
+In the **Database** workspace, the **Remove &lt;connection&gt;** button takes a connection out of the configuration with `RemoveConnection` for its catalog connections and `RemoveModule` for its tables module. The tables module's folder is deleted with it. The database itself is untouched.
 
-The tables module is the one whose `dmsBuilder.database` record names the connection, which `CreateLocalModule` writes with `connection` (the single-step `CreateLocalModule` takes it in its options). Another module that reads through the provider is never removed or deleted.
+The tables module is the one whose `dmsBuilder.database` record names the connection. `CreateLocalModule` writes that record from `connection`. The single-operation `CreateLocalModule` takes it in its options. A module that reads through the provider without such a record is never removed or deleted.
 
-The provider goes too, with the variables that supply its configuration in `envOverrides`, `.env` and `.env.example`, only when it was added for this connection alone: its `exportPriority` for `@antelopejs/interface-database` is below the project's own database, and no module or connection the removal leaves names it. Otherwise it stays, since it may be the project's own database.
+The provider is removed too, with the variables that supply its configuration in `envOverrides`, `.env` and `.env.example`, only when it was added for this connection alone. That holds when its `exportPriority` for `@antelopejs/interface-database` is below the project's own database, and no module or connection that the removal leaves names it. Otherwise the provider stays, since it may be the project's own database.
 
-A removal is all or nothing: the folders are moved aside and `.env` is edited first, and both are put back when the configuration cannot be written.
+A removal is all or nothing. The workspace moves the folders aside and edits `.env` first, and puts both back when the configuration cannot be written.
 
-## Analyse a Database
+## Analyse a database
 
-`AnalyseDatabase({ connection, module, schemas? })` starts a job and answers it at once: profiling a database takes a while. `GetAnalysis(id)` answers the job's `progress` while it runs, then its `proposal`, or its `error`.
+`AnalyseDatabase({ connection, module, schemas? })` starts a job and answers it at once, because profiling a database takes a while. `GetAnalysis(id)` answers the job's `progress` while it runs, then its `proposal` or its `error`.
 
 ```typescript
 import { AnalyseDatabase, GetAnalysis } from "@antelopejs/interface-dms-builder";
@@ -98,16 +106,19 @@ import { AnalyseDatabase, GetAnalysis } from "@antelopejs/interface-dms-builder"
 const started = await AnalyseDatabase({ connection: "erp", module: "erp-tables" });
 if (started.ok) {
   const state = await GetAnalysis(started.data.id);
-  // state.data.status: "running" | "done" | "failed"
+  if (state.ok) {
+    console.log(state.data.status); // "running", "done" or "failed"
+  }
 }
 ```
 
+- `connection` must be a catalog connection on the `dms-builder` entry, and `module` a local module other than the project's own. Otherwise the call fails with `invalid_config`.
 - One job runs per connection. Starting another while one runs answers the running one.
-- A finished job is kept until the next one on its connection, or a restart.
-- Relations the module has mapped, or recorded as excluded, are not proposed again.
-- Above 200 relations to profile, the proposal holds a single `schemas` question instead, and the analysis runs again with `schemas`.
+- A finished job is kept until the next one on its connection, or until a restart.
+- Relations that the module has mapped, or recorded as excluded, are not proposed again.
+- When more than 200 relations are left to profile and the call passed no `schemas`, the proposal holds a single `schemas` question instead. Run the analysis again with `schemas`.
 
-## Read a Proposal
+## Read a proposal
 
 A `MappingProposal` is a `MapResources` input in which every choice says where it came from:
 
@@ -119,45 +130,55 @@ interface Proposed<T> {
 }
 ```
 
-A **fact** follows from the catalog with no judgement. A **default** is a judgement to check.
+A `fact` follows from the catalog with no judgement. A `default` is a judgement to check.
+
+The relation rules apply in the order R1, R4, R3, R2, then R5 to R9. The first rule that applies decides.
 
 | Rule | When | Then |
 | --- | --- | --- |
-| R1 | the catalog says unmappable | excluded, with its reason |
-| R2 | no key | stats only: table class and model, no page |
-| R3 | no rows | excluded |
-| R4 | a framework's or a migration tool's table | excluded |
-| R5 | keyed by its two references | stats only |
-| R6 | keyed, with rows and a label | TableView |
-| R7 | keyed, no label, referenced | TableView labelled by its key, and a `label` question |
-| R8 | keyed, no label, not referenced, with a time axis | stats only |
-| R9 | anything else | a `purpose` question, nothing proposed |
-| L1, L2 | the label by name, then by order; titles from short comments, else from names | |
-| F1–F5 | columns no type reads and secrets left out; the first declaration; references the database declares, and references found whole, as relation columns | |
-| D1 | a `string` column the profile calls enum-like, of 2 to 10 categories that cover every non-null row | `display`: a badge, one toned item per value, by rows |
-| D2 | a `number` column whose name ends in `total`, `amount`, `price`, `cost`, `revenue` or `subtotal` | `display`: a price |
-| D3 | a relation column the database did not comment | `label`: the target's title in singular, "Customer" not "Customer id"; `MapResources` takes it too when a field leaves `label` out |
-| T1 | of the filterable badge columns of 2 to 6 values, the first named like `status`, `state`, `stage` or `type`, else the one with the fewest values | `tabs` on the resource |
-| W1 | every TableView | read-only |
-
-A badge's tones come from the value: `paid`, `active`, `done`, `completed`, `shipped`, `delivered` and `approved` are `success`; `pending`, `draft`, `processing`, `waiting` and `review` are `warning`; `failed`, `cancelled`, `canceled`, `refunded`, `rejected`, `error` and `blocked` are `error`; `new` and `open` are `info`. Other values take `primary`, `secondary`, `info` and `neutral` in turn. A price uses the DataType's default currency.
-
-Each field also carries the declarations its column `accepts`, and its profile's aggregates: traits, nulls, distinct values, range and categories. Never a row.
+| R1 | The catalog says unmappable | Excluded, with its reason |
+| R2 | No key | Stats only: table class and model, no page |
+| R3 | No rows | Excluded |
+| R4 | A framework's or a migration tool's table | Excluded |
+| R5 | Keyed by its two references, with at most one other column | Stats only |
+| R6 | Keyed, with rows and a label | TableView, and a `label` question when two candidates tie |
+| R7 | Keyed, no label, referenced | TableView labelled by its key, and a `label` question |
+| R8 | Keyed, no label, not referenced, with a time axis | Stats only |
+| R9 | Anything else | A `purpose` question, nothing proposed |
+| L1 | A label candidate | The label, by name, then by order |
+| L2 | A relation or a column | Its title, from a short comment, else from its name |
+| F1 | A column that no field type reads | Left out |
+| F2 | A column named like a secret | Left out |
+| F3 | A column | Its first declaration |
+| F4 | A single column with a foreign key that the database declares on a TableView's single-column key | A relation column |
+| F5 | A single column whose values are all found in a TableView's single-column key | A relation column |
+| FL | A field | Whether it is listable, filterable, sortable and searchable |
+| D1 | A `string` column that the profile calls enum-like, with 2 to 10 categories that cover every non-null row | `display`, a badge with one toned item per value, ordered by rows |
+| D2 | A `number` column whose name ends in `total`, `amount`, `price`, `cost`, `revenue` or `subtotal` | `display`, a price |
+| D3 | A relation column that the database did not comment | `label`, the target's title in the singular ("Customer", not "Customer id"). `MapResources` also applies it when a field leaves `label` out |
+| T1 | Among the filterable badge columns with 2 to 6 values, the first named like `status`, `state`, `stage` or `type`, else the one with the fewest values | `tabs` on the resource |
+| W1 | Every proposed relation | Read-only (`writable: false`) |
+
+A badge's tone comes from its value. `paid`, `active`, `done`, `completed`, `shipped`, `delivered` and `approved` are `success`. `pending`, `draft`, `processing`, `waiting` and `review` are `warning`. `failed`, `cancelled`, `canceled`, `refunded`, `rejected`, `error` and `blocked` are `error`. `new` and `open` are `info`. Other values take `primary`, `secondary`, `info` and `neutral` in turn. A price takes the currency the database states, from an ISO 4217 code in the column's comment, else from a sibling currency column that holds one code in every row. When the database states none, it uses the DataType's default currency.
+
+Each field also carries the declarations its column `accepts`, and its profile's aggregates: traits, nulls, distinct values, range and categories. A profile never holds a row.
 
 Each resource also carries its `rows`, counted by the profile or estimated, when either is known.
 
-What the rules could not decide is in `open`, each item with its options and what the proposal holds meanwhile:
+The `open` list holds what the rules could not decide. Each item holds its options and what the proposal holds meanwhile:
 
-- A `label` item offers every column a field reads, the key among them.
+- A `label` item offers every column that a field reads, the key among them, except columns named like a secret.
 - A `reference` item offers a plain column, the target its values were found in, and every TableView whose single-column key accepts the column.
-- A `purpose` item carries the `resource` it would map, should the answer be to map it, and in its own `open` the questions that resource leaves: they are asked only once the answer maps it.
+- A `purpose` item carries the `resource` it would map if the answer is to map it. Its own `open` holds the questions that resource leaves, which apply only once the answer maps it.
 - A `field-type` item asks which declaration reads a field of several native types.
 
-A document database declares no field types, so its catalog reads them from a sample. When no type covers enough of a field's values (`int 60% | string 40%`), the field is left out and a `field-type` item asks which declaration reads it: its options are a declaration per type seen, and leaving it out. The `_id` of a collection without a key is never declared, so it is left out and asks nothing. `MapResources` accepts the declaration it answers. MongoDB and RethinkDB declare no references either, so F5 finds them all.
+A document database declares no field types, so its catalog reads them from a sample. When no type covers enough of a field's values (`int 60% | string 40%`), the field is left out and a `field-type` item asks which declaration reads it. Its options are a declaration per type seen, and leaving the field out. The `_id` of a collection without a key is never declared, so it is left out and asks nothing. `MapResources` accepts the declaration the answer names. MongoDB and RethinkDB declare no references either, so F5 finds them all.
 
-## Map Relations
+`GetMapping(connection, module)` reads the relations a module maps back into the proposal's shape, with every choice citing the rule `mapped`, so a caller can change them and map again.
 
-`MapResources(input)` reads the descriptions of the relations through the builder's connection, checks every choice against them, and writes in one typechecked transaction. Then it creates the connection's category `pages.<connection>` and the TableView pages.
+## Map relations
+
+`MapResources(input)` reads the descriptions of the relations through the builder's connection, checks every choice against them, and writes in one typechecked transaction. It then creates the connection's category, `pages.<connection>`, and the TableView pages.
 
 ```typescript
 import { MapResources } from "@antelopejs/interface-dms-builder";
@@ -177,15 +198,16 @@ const result = await MapResources({
   ],
   excluded: [{ relation: "erp.schema_migrations", reason: "a framework's or a migration tool's table" }],
 });
+if (!result.ok) console.error(result.error);
 ```
 
-- **Names are the database's own.** `_id` is declared only where the relation has a key, and nothing creates or alters a table. A MongoDB collection's key is `_id` itself, which is declared once.
-- **Relation columns** point at a relation of the batch, or one the module mapped before, by its single-column key.
-- **A relation column's `label`** is written as sent. Left out, it keeps the label its controller holds if its relation was mapped before and held the column; otherwise it takes D3, the title of the relation it points at in singular ("Customer", not "Customer id"), as the target is titled by this call, by its page if it was mapped before, else by its name humanized. A column the database commented with a short first sentence takes that sentence instead (L2). A column that is not a relation column takes its name, humanized. A call that never sends a `label` therefore gets the analysis's labels on a first mapping and loses nothing on a remap.
-- **A column's `display`** is `{ kind: "badge", items: [{ value, label, tone }] }` on a `string` column, or `{ kind: "price" }` on a `number` one. A relation column takes none. Left out, the column keeps the display it has if its relation was mapped before, read back from its controller as `GetMapping` reads it; if the relation is new, it takes the display D1 or D2 proposes. `null` writes the column plain, over any display it had. A call that never sends a `display` therefore gets the proposal on a first mapping and loses nothing on a remap.
-- **Where a proposal comes from.** `MapResources` reads the profile of a new relation through the catalog connection at map time, since D1 needs it. When the profile cannot be read, it takes the proposal from the connection's last `AnalyseDatabase`; when there is none either, D2 still applies by the column's name, no column becomes a badge, and the result warns `display_not_proposed`. A display that does not suit the column's declaration, such as a badge on a column declared `number`, is dropped when it was kept or proposed, and refused only when sent.
-- **A TableView's `tabs`**: `tabs: { column }` writes "All" and a tab per value of that column's badge to the TableView, over the `tabs` it holds; the column must be filterable and drawn as a badge. Left out, a page already mapped keeps its tabs, and a new relation takes the tabs T1 proposes among its filterable badge columns: a column left unfilterable is not tabbed. `null` writes none: it adds no tabs to a new relation, and removes from a page already mapped the tabs a mapping wrote from a badge, as `display: null` removes the badge. Tabs edited by hand are kept.
-- **Mapping again** a relation already mapped rewrites it from the new choices. Its page is created, kept or removed as `tableView` says, and takes the new `title`. The module's relation columns pointing at it take its new `label`.
+- **Names are the database's own.** `_id` is declared only where the relation has a key, and nothing creates or alters a table. A MongoDB collection's key is `_id` itself, which is declared once. A relation without a key gets no TableView, whatever `tableView` says.
+- **Relation columns** point at a relation of the batch, or at one the module mapped before, by its single-column key.
+- **A relation column's `label`** is written as sent. When it is left out, the column keeps the label its controller holds, if its relation was mapped before and held the column. Otherwise it takes D3, the title of the relation it points at in the singular ("Customer", not "Customer id"). That title comes from this call, else from the target's page if it was mapped before, else from its humanized name. A relation column that the database commented with a short first sentence takes that sentence instead (L2). A column that is not a relation column takes its humanized name on every mapping, even when the database commented it, so it does not take the analysis's title. A call that never sends a `label` therefore gets D3 or L2 titles for its relation columns on a first mapping and keeps them on a remap, and gets humanized names for its other columns.
+- **A column's `display`** is `{ kind: "badge", items: [{ value, label, tone }] }` on a `string` column, or `{ kind: "price" }` on a `number` one. A relation column takes none. When `display` is left out, the column keeps the display it has if its relation was mapped before, read back from its controller as `GetMapping` reads it. A new relation takes the display that D1 or D2 proposes. `null` writes the column plain, over any display it had. A call that never sends a `display` therefore gets the proposal on a first mapping and loses nothing on a remap.
+- **Where a proposal comes from.** `MapResources` reads the profile of a new relation through the catalog connection at map time, because D1 needs it. When it cannot read the profile, it takes the proposal from the connection's last `AnalyseDatabase`. When there is none either, D2 still applies by the column's name, no column becomes a badge, and the result warns `display_not_proposed`. A display that does not suit the column's declaration, such as a badge on a column declared `number`, or one on the primary key, is dropped and the column is written plain. When the display was sent, the result warns `display_dropped`.
+- **A TableView's `tabs`.** `tabs: { column }` writes an "All" tab and one tab per value of that column's badge to the TableView, over the `tabs` it holds. The column must be drawn as a badge, or the tabs are left out with a `display_dropped` warning. When the column is not filterable, the builder marks it filterable and warns `field_flag_set`. When `tabs` is left out, a page already mapped keeps its tabs, and a new relation takes the tabs that T1 proposes among its filterable badge columns only. `null` writes none. It adds no tabs to a new relation, and it removes from a page already mapped the tabs that a mapping wrote from a badge, as `display: null` removes the badge. Tabs edited by hand are kept.
+- **Mapping a relation again** rewrites it from the new choices. Its page is created, kept or removed as `tableView` says, and takes the new `title`. The module's relation columns that point at it take its new `label`.
 - **Before a remap that removes a page**, `PreviewMapResources(input)` answers `pagesToRemove` for the same input and writes nothing, so a caller can ask a person first. It refuses what `MapResources` refuses.
 - **The module's `package.json`** records the connection and the `excluded` tables with their reasons, so the next analysis does not propose those tables. Mapping one later removes it from the record:
 
@@ -197,10 +219,11 @@ const result = await MapResources({
     }
   }
   ```
-- **In a mapped module**, `CreateResource` and `AddField` are refused, since its tables are the database's. `DeleteResource` keeps the client's rows and warns `data_kept`.
 
-## Next Steps
+- **In a mapped module**, `CreateResource`, `AddField` and a `ConfigureField` that changes `dbField` fail with `invalid_config`, since the module's tables belong to the database. `DeleteResource` keeps the client's rows and warns `data_kept`.
+
+## Next steps
 
-- [Resources](./5.resources.md): the resources a mapping writes are ordinary ones, read the same way.
-- [Queries](./6.queries.md): stats over a mapped relation name it by its ref.
-- [Results and Errors](./8.results-and-errors.md): branch on what every operation answers.
+- [Resources](./5.resources.md) describes the resources a mapping writes. They are ordinary resources, read the same way.
+- [Queries](./6.queries.md) shows how stats over a mapped relation name it by its ref.
+- [Results and errors](./8.results-and-errors.md) shows how to branch on what every operation answers.