Results and errors
The OpResult envelope every builder operation returns: the staged file changes, the warnings, the BuilderError codes with their payloads, and the expectedVersion check.
Overview
Every operation that can fail returns an OpResult. It is a discriminated union. ok: true carries the operation's data and the file changes it staged, and ok: false carries a single BuilderError. An expected failure comes back as a value and does not throw. An unknown ref, a duplicate name and a configuration the engine cannot validate are examples. The one known exception is an unknown block type inside a $block value passed to AddBlock or ConfigureBlock, which rejects the call, as Value encodings describes.
Mutations of source files are transactional. The engine applies the edit in memory, typechecks the project, and writes only when the typecheck passes. A failure rolls the transaction back and returns typecheck_failed, so a rejected operation leaves no partial edit on disk.
Branch on a result
import { GetPageStructure } from "@antelopejs/interface-dms-builder";
const result = await GetPageStructure("/dashboard");
if (!result.ok) {
console.error(result.error.code);
return;
}
const { blocks, version } = result.data;
OpResult<T> has two variants:
| Variant | Fields |
|---|---|
| Success | ok: true, data: T, changes: FileChange[], warnings?: OpWarning[] |
| Failure | ok: false, error: BuilderError |
OpResult defaults to OpResult<void>. The operations that return only a status use it, such as ConfigureCategory, RemoveBlock and RemoveField.
The reads that use the envelope, such as GetPageStructure and GetResourceStructure, return an empty changes array on success. The listing operations (ListPages, ListCategories, ListResources, ListQueryTemplates, ListDataSources and GetCatalog) do not use the envelope. They return their value directly, and RefreshSourceIndex returns void.
Read the staged changes
changes lists what the operation wrote, one entry per file.
| Field | Type | Description |
|---|---|---|
path | string | The file's absolute path. |
kind | "create" | "modify" | "delete" | What happened to the file. |
diff | string | The change as unified diff hunks (@@ -a,b +c,d @@, then lines that start with a space, - or +), with no file headers. Empty for a deleted file or folder. |
One operation often changes more than one file. Creating a page writes the page file and rewrites the barrel that exports it. Creating a resource writes three files and rewrites a barrel.
import { CreateResource } from "@antelopejs/interface-dms-builder";
const result = await CreateResource({
name: "product",
fields: [{ name: "title", dataType: { $dataType: "string" } }],
});
if (result.ok) {
for (const change of result.changes) {
console.log(change.kind, change.path);
}
}
Handle warnings
warnings is present only when a successful operation has something non-fatal to report. The field is optional, so it can be absent instead of an empty array.
| Code | Raised when |
|---|---|
index_clamped | An AddBlock or MoveBlock index fell outside the sibling range, and the engine moved it to the nearest end. |
datatype_fallback | A field's DataType is not one the builder maps, so a resource stores it as a string, or a query filter compares it as a string. |
data_not_dropped | DeleteResource removed the source files but could not delete the rows of the resource's table. |
data_kept | DeleteResource deleted a resource that mirrors an external database. Its rows belong to that database and stay in place. |
route_changed | ConfigurePage moved a page to another category, so its route changed and links to the old route break. |
query_opaque | SetPageBlocks left alone a query on the page that a person took over by hand. |
query_kept | SetPageBlocks kept a query that the draft dropped, because a block still reads it. |
page_not_written | MapResources wrote a mapped relation's tables, but not its table view page. |
relation_missing | GetMapping found a relation that the module maps but the database no longer has, or that the role can no longer see. |
module_not_loaded | MapResources wrote the mapping, but the module it wrote into did not load again. The module was unloaded and did not start within the wait, or the runtime does not report it active. The message names the module, and the backend log holds the error. |
setting_dropped | ConfigureTableView or MapResources dropped a TableView setting that no longer holds, such as a default display the table no longer offers. |
relation_skipped | MapResources left out a relation of the batch because one of its choices was refused, and wrote the others. |
display_dropped | MapResources wrote a column plain because the display sent for it, or the tabs sent from it, do not suit the column. |
field_flag_set | MapResources or ConfigureTableView marked a column filterable or sortable, because a view, footer figure, tab or grouping needs it. |
label_changed | MapResources changed a relation's label to one the generated code can read, or dropped it when no column offers it. |
display_not_proposed | MapResources mapped a relation whose columns left display out, and no profile or analysis could propose a badge, so its text columns were written plain. |
import { AddBlock } from "@antelopejs/interface-dms-builder";
const result = await AddBlock({
page: "/revenue",
name: "total",
type: "KpiCard",
config: { title: "Total" },
index: 99,
});
if (result.ok) {
for (const warning of result.warnings ?? []) {
console.warn(warning.code, warning.message);
}
}
Handle errors
BuilderError is a union discriminated by code. Each variant carries the data needed to act on it.
| Code | Payload | Meaning |
|---|---|---|
not_found | ref: string | The page, category, block, resource, field or query does not exist. |
duplicate_name | name: string, scope: DuplicateScope | The name is already taken within that scope. |
invalid_config | issues: ValidationIssue[] | The request's configuration did not validate. |
opaque_target | path: BlockPath | The target exists, but the builder cannot rewrite it. For a field or a query, path holds the FieldPath or the QueryRef. |
unsupported | detail: string | The engine does not handle the request, and detail says why. |
referential_integrity | blockedBy: string[] | Something still depends on what you asked to delete. |
stale | ref: string, currentVersion: string | The file changed since the version you passed as expectedVersion. |
typecheck_failed | diagnostics: TypecheckError[] | The edit would not compile, and the engine rolled it back. |
import { AddBlock } from "@antelopejs/interface-dms-builder";
const result = await AddBlock({
page: "/revenue",
name: "total",
type: "KpiCard",
config: { title: "Total" },
});
if (!result.ok) {
switch (result.error.code) {
case "duplicate_name":
console.error(`"${result.error.name}" is taken in ${result.error.scope}`);
break;
case "invalid_config":
for (const issue of result.error.issues) {
console.error(issue.pointer, issue.message);
}
break;
case "typecheck_failed":
for (const diagnostic of result.error.diagnostics) {
console.error(`${diagnostic.file}:${diagnostic.line}`, diagnostic.message);
}
break;
default:
console.error(result.error.code);
}
}
Duplicate scopes
DuplicateScope names the namespace the collision happened in, which tells you what to rename.
| Scope | The name collided with |
|---|---|
page | A top-level block on the same page, or another page's route. |
siblings | Another child of the same container block. |
category | Another category. |
resource | Another resource, or another field on the same resource. |
query | A member of the page controller, a route path the page already serves, or a member of the resource's model. For a route path, name holds the endpoint. |
module | A module. The type declares this scope, and no operation returns it now. |
Validation issues
ValidationIssue addresses a failure by a JSON pointer into the request.
| Field | Type | Description |
|---|---|---|
pointer | string | A JSON pointer into the input that failed, such as /where/0/op. Empty when the failure is not tied to one key. |
message | string | What is wrong. It often names the operation that lists the valid values. |
Typecheck errors
TypecheckError is one TypeScript diagnostic from the in-memory typecheck.
| Field | Type | Description |
|---|---|---|
file | string | The file the diagnostic points at. |
line | number | The line number. |
message | string | The diagnostic message. |
The engine collects diagnostics across the whole project, outside node_modules, and not only in the file the operation edited. A change that breaks code elsewhere fails before anything is written.
Make a write conditional
MutationOpts is the trailing options argument of the mutations that check a version. Not every mutation takes it.
| Option | Type | Description |
|---|---|---|
expectedVersion | string | The version the caller last read. A mismatch fails with stale. |
The operations that edit something that already exists take it: ConfigurePage, DeletePage, AddBlock, ConfigureBlock, MoveBlock, RemoveBlock, SetPageBlocks, ConfigureResource, DeleteResource, AddField, ConfigureField, RemoveField, AddQuery, ConfigureQuery, RemoveQuery, ConfigureTableView and ComposePage. The three creations, CreatePage, CreateCategory and CreateResource, take no options argument. Neither do ConfigureCategory and DeleteCategory.
The version comes from the structure you read. A page operation takes PageStructure.version, and a resource operation takes ResourceStructure.version. Both are content hashes, of the page file and of the resource's two generated files.
import {
ConfigureBlock,
GetPageStructure,
} from "@antelopejs/interface-dms-builder";
const read = await GetPageStructure("/revenue");
if (!read.ok) {
return;
}
const write = await ConfigureBlock(
"/revenue#total",
{ title: "Revenue" },
{ expectedVersion: read.data.version },
);
if (!write.ok && write.error.code === "stale") {
// `write.error.currentVersion` is the file's hash now.
// Read the structure again, decide again, and retry.
}
Without expectedVersion, the write is unconditional. Pass it when a person or another process can change the file between your read and your write.
Two operations extend MutationOpts with options of their own. ConfigureBlockOpts adds replace and meta, described in Page operations. DeleteResourceOpts adds keepData, described in Resources.