[data-reveal]{opacity:1!important;transform:none!important}
AntelopeJS DMS
DocumentationValue encodings

Value encodings

How the builder writes a configuration value to source: plain JSON as a literal, and the $dataType, $ref, $expr and $block sentinels for values that must reach the source as TypeScript.

Overview

Configuration values are plain JSON by default. The builder writes AddBlockInput.config, a ConfigureBlock patch and a page's permission to source exactly as you pass them, as literals.

The type of such a value is ConfigValue. It is a string, a number, a boolean, null, undefined, an array of ConfigValue items, or a ConfigObject, an object whose members are ConfigValue items. The compiler refuses a function or a class instance. undefined stands for an absent member. The builder skips it when it writes, and a ConfigureBlock patch reads it as "remove this key". The four encodings below are ConfigObject values.

Some options need TypeScript values instead of JSON literals. A form field needs a DataType instance, a relation needs a controller class, and a chart card needs a nested chart. The structured encodings below let the builder write those values and their imports. A raw $expr is the fallback for anything else, and page drafts and query parameters refuse it.

typescript
import type {
  BlockValue,
  DataTypeValue,
  ExprValue,
  RefValue,
} from "@antelopejs/interface-dms-builder";

Choose an encoding

You are writingEncoding
A string, number, boolean, array or objectThe value itself, as JSON.
A value the catalog marks x-dataTypeDataTypeValue
A reference to a class of a builder-generated resourceRefValue
A nested component in an option the catalog marks x-componentBlockValue
Anything else that must reach the source as codeExprValue

The catalog says which option needs which encoding. An option marked x-dataType in a block's ConfigSchema takes a DataTypeValue and nothing else. See Catalog.

Write a DataTypeValue

DataTypeValue emits new <DataType>(<config>) and adds the import.

FieldTypeDescription
$dataTypestringA DataTypeDescriptor.id from the catalog, such as "string" or "select".
configConfigObjectThe DataType's options. Omit it for new <DataType>() with no argument.
typescript
import { AddBlock } from "@antelopejs/interface-dms-builder";

await AddBlock({
  page: "/customers",
  name: "editor",
  type: "Form",
  config: {
    fields: [
      {
        id: "name",
        label: "Name",
        type: { $dataType: "string", config: { placeholder: "Name" } },
      },
    ],
  },
});
// emits:  type: new DefaultDataTypes.StringType({ placeholder: "Name" })

A resource field's dataType takes the same encoding, as Resources describes.

A $dataType id that the catalog does not list fails with invalid_config. The message names GetCatalog as the source of the valid ids.

Reference a generated class

RefValue emits the bare class name of a builder-generated resource and adds its import. It is the checked alternative to ExprValue for a class reference, such as the dataApiController of a RelationType.

FieldTypeDescription
$ref.resourcestringA ResourceRef, the resource's name, such as "product".
$ref.as"dataApi" | "table" | "model"Which of the resource's classes to reference. Defaults to "dataApi".
typescript
import { AddField } from "@antelopejs/interface-dms-builder";

await AddField("order-line", {
  name: "productId",
  label: "Product",
  dataType: {
    $dataType: "relation",
    config: { dataApiController: { $ref: { resource: "product" } } },
  },
});
// emits:  dataApiController: productDataAPI   (imported from the resource's data-api.ts)

as picks one of the three classes a resource generates. "dataApi" is the DataController, "table" is the Table and "model" is the BasicDataModel. An unknown resource fails with invalid_config, and the message names ListResources as the source of the valid refs.

AddBlockInput.controller holds the same reference in a field of its own. A block type that leads with a controller takes a ResourceRef there, not a RefValue in its config. See Page operations.

Write a raw expression

The builder emits an ExprValue as written. It is for a value the builder cannot model as structure.

FieldTypeDescription
$exprstringTypeScript source, inserted into the emitted file as written.
typescript
import { ConfigureBlock } from "@antelopejs/interface-dms-builder";

await ConfigureBlock("/revenue#total", {
  valueFormat: { $expr: "REVENUE_FORMAT" },
});

Two constraints apply:

  • The symbol the expression names must already be in scope in the target file. $expr adds no import.
  • A query's parameters refuse $expr, because a query's values are data and a raw expression would put code the builder cannot check inside a model body. See Queries.

A consumer that runs the builder in a restricted mode can refuse $expr entirely, because arbitrary code removes the checks that the structured encodings give. RefValue and BlockValue stay allowed in that mode, because the builder checks them. For a generated class, RefValue is the encoding to use.

Nest a block in a config value

A few options hold a component instead of data, such as the chart of a ChartCard, which the catalog marks x-component. BlockValue writes such a component. The builder emits the nested factory call and adds its import.

typescript
import type { BlockValue } from "@antelopejs/interface-dms-builder";

const chart: BlockValue = {
  $block: { type: "ChartArea", config: { xaxisType: "datetime" } },
};
// emits:  chart: ChartArea({ xaxisType: "datetime" })

type is a catalog key, like AddBlockInput.type. In a page draft, an unknown type fails with invalid_config. AddBlock and ConfigureBlock do not turn it into a result, and the call rejects with an unknown block type error. Read-back mirrors the write. A nested factory call whose callee is a known block type reads back as a $block sentinel, not as $expr, so the value stays editable.

Most nesting does not go through config. It goes through .child, which AddBlockInput.parent or BlockDraft.children express. $block is only for an option that the catalog marks x-component.

Next steps