[data-reveal]{opacity:1!important;transform:none!important}
AntelopeJS DMS
DocumentationResults and errors

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

typescript
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:

VariantFields
Successok: true, data: T, changes: FileChange[], warnings?: OpWarning[]
Failureok: 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.

FieldTypeDescription
pathstringThe file's absolute path.
kind"create" | "modify" | "delete"What happened to the file.
diffstringThe 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.

typescript
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.

CodeRaised when
index_clampedAn AddBlock or MoveBlock index fell outside the sibling range, and the engine moved it to the nearest end.
datatype_fallbackA 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_droppedDeleteResource removed the source files but could not delete the rows of the resource's table.
data_keptDeleteResource deleted a resource that mirrors an external database. Its rows belong to that database and stay in place.
route_changedConfigurePage moved a page to another category, so its route changed and links to the old route break.
query_opaqueSetPageBlocks left alone a query on the page that a person took over by hand.
query_keptSetPageBlocks kept a query that the draft dropped, because a block still reads it.
page_not_writtenMapResources wrote a mapped relation's tables, but not its table view page.
relation_missingGetMapping found a relation that the module maps but the database no longer has, or that the role can no longer see.
module_not_loadedMapResources 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_droppedConfigureTableView or MapResources dropped a TableView setting that no longer holds, such as a default display the table no longer offers.
relation_skippedMapResources left out a relation of the batch because one of its choices was refused, and wrote the others.
display_droppedMapResources wrote a column plain because the display sent for it, or the tabs sent from it, do not suit the column.
field_flag_setMapResources or ConfigureTableView marked a column filterable or sortable, because a view, footer figure, tab or grouping needs it.
label_changedMapResources changed a relation's label to one the generated code can read, or dropped it when no column offers it.
display_not_proposedMapResources mapped a relation whose columns left display out, and no profile or analysis could propose a badge, so its text columns were written plain.
typescript
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.

CodePayloadMeaning
not_foundref: stringThe page, category, block, resource, field or query does not exist.
duplicate_namename: string, scope: DuplicateScopeThe name is already taken within that scope.
invalid_configissues: ValidationIssue[]The request's configuration did not validate.
opaque_targetpath: BlockPathThe target exists, but the builder cannot rewrite it. For a field or a query, path holds the FieldPath or the QueryRef.
unsupporteddetail: stringThe engine does not handle the request, and detail says why.
referential_integrityblockedBy: string[]Something still depends on what you asked to delete.
staleref: string, currentVersion: stringThe file changed since the version you passed as expectedVersion.
typecheck_faileddiagnostics: TypecheckError[]The edit would not compile, and the engine rolled it back.
typescript
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.

ScopeThe name collided with
pageA top-level block on the same page, or another page's route.
siblingsAnother child of the same container block.
categoryAnother category.
resourceAnother resource, or another field on the same resource.
queryA 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.
moduleA 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.

FieldTypeDescription
pointerstringA JSON pointer into the input that failed, such as /where/0/op. Empty when the failure is not tied to one key.
messagestringWhat is wrong. It often names the operation that lists the valid values.

Typecheck errors

TypecheckError is one TypeScript diagnostic from the in-memory typecheck.

FieldTypeDescription
filestringThe file the diagnostic points at.
linenumberThe line number.
messagestringThe 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.

OptionTypeDescription
expectedVersionstringThe 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.

typescript
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.