Introduction
What the builder interface does, how an edit reaches your TypeScript files, and where each part of the contract is documented.
@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.
Quick start
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 @antelopejs/dms, which implements the builder in development. The interface package alone does not provide the implementation.
The project must already have a pages category. ListCategories() lists yours, and Create a category adds one. The page name must be unused, because a second creation with the same name returns duplicate_name.
import {
AddBlock,
CreatePage,
} from "@antelopejs/interface-dms-builder";
const page = await CreatePage({
name: "revenue",
displayName: "Revenue",
category: "pages",
icon: "i-ph-chart-line",
});
if (!page.ok) {
throw new Error(`could not create the page: ${page.error.code}`);
}
const block = await AddBlock({
page: page.data.ref, // "/revenue"
name: "total",
type: "KpiCard",
config: {
title: "Total revenue",
icon: "i-ph-currency-eur",
},
});
if (!block.ok) {
throw new Error(`could not add the block: ${block.error.code}`);
}
console.log(block.data.path); // "/revenue#total"
for (const change of block.changes) {
console.log(change.kind, change.path);
}
After the backend reloads, a tenant owner who opens /revenue sees the page and its card. The card has no revenue data yet. Queries connects a card to a resource for real numbers.
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 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. An expected failure comes back as a value you can inspect:
// Success: { ok: true, data, changes, warnings? }
// Failure: { ok: false, error }
Listing operations such as ListPages return their value directly. Results and errors 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.
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.
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 saves a whole block tree in one transaction.
Documentation sections
- Addressing and structure covers the refs that name a page, a block and a category, and the shapes the builder reads back.
- Catalog lists the block types, DataTypes and reserved names the builder reports.
- Page operations creates pages and categories, and edits the block tree of a page.
- Resources generates tables, DataAPI controllers and their fields.
- Queries compiles a measure, grouped or not, into a model method and a page route.
- Value encodings writes configuration values that are not plain literals.
- Results and errors branches on
OpResult, reads diagnostics, and makes a write conditional. - Drafts and preview writes the blocks of a page and the data they read in one transaction, and previews either.
- A chart without code follows one chart from the choice of a measure to the reopened page.
- Theme and branding reads and writes a project's colors, corners, font and logos, and gives it the layer they live in.
- External databases wires a database the project does not own, analyses its catalog and maps its relations.
- Connect a database checks a database live, reads the project's database state, and edits, repairs or removes a connection.