@antelopejs/interface-dms-builder 0.0.1

package/docs/6.queries.md

@@ -0,0 +1,229 @@
+# Queries
+
+## Overview
+
+A query is derived data: a count, a sum, an average taken over a resource's rows and served from a page. `AddQuery` compiles a query template into a method on the resource's model and a route on the page's controller, so a block on that page can fetch a single number without you writing either half.
+
+A query is addressed by a `QueryRef`, lives on a page, and reads from a resource. Templates decide what a query can compute; you pick one by id, fill in its parameters, and the builder emits the chain.
+
+Queries read back structurally: `GetPageStructure` reports the queries it finds on a page in `PageStructure.queries`, whether the builder wrote them or a human did.
+
+## Address a Query
+
+`QueryRef` is `<pageRef>@<name>`, e.g. `/books@inStockCount`. The page part says where the route lives; the resource the query reads is recorded in the query itself, not in its ref.
+
+```typescript
+import type { QueryRef } from "@antelopejs/interface-dms-builder";
+
+const query: QueryRef = "/books@inStockCount";
+```
+
+## List the Templates
+
+`ListQueryTemplates(resourceType?)` returns the templates currently registered. It is a plain read, and the registry is live, so call it rather than hard-coding ids.
+
+```typescript
+import { ListQueryTemplates } from "@antelopejs/interface-dms-builder";
+
+const templates = await ListQueryTemplates("database-table");
+for (const template of templates) {
+  console.log(template.id, template.title, template.output);
+}
+```
+
+`QueryTemplateDescriptor`:
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `id` | `string` | The template id, e.g. `count` or `aggregate`. This is `AddQueryInput.template`. |
+| `resourceType` | `"database-table"` | The kind of resource the template reads. |
+| `title` | `string` | A human-readable title. |
+| `description` | `string` | What the template computes. |
+| `output` | `QueryOutputKind` | The shape the query's route responds with. |
+| `params` | `ConfigSchema` | The template's parameter schema, in the same vocabulary as the block catalog. |
+
+`QueryOutputKind` is `"scalar"`: the route responds with a `{ value }` object.
+
+Read `params` the way you read a block's `config` schema, described in [Catalog](./3.catalog.md) — it tells you which keys `AddQueryInput.params` accepts, and a key the template does not declare fails with `invalid_config`.
+
+## Add a Query
+
+```typescript
+import { AddQuery } from "@antelopejs/interface-dms-builder";
+
+const result = await AddQuery("/books", {
+  name: "inStockCount",
+  resource: "book",
+  template: "count",
+  params: {
+    where: [{ field: "stock", op: "gt", value: 0 }],
+  },
+});
+if (result.ok) {
+  console.log(result.data.query); // "/books@inStockCount"
+  console.log(result.data.route); // "/books/stats/in-stock-count"
+}
+```
+
+`AddQueryInput`:
+
+| Option | Type | Description |
+| --- | --- | --- |
+| `name` | `string` | The query name, a camelCase identifier. Required. It names the route method, and the model method too. |
+| `resource` | `ResourceRef` | The resource the query reads. Required, and it must exist. |
+| `template` | `string` | A `QueryTemplateDescriptor.id`. Required. |
+| `params` | `Record<string, QueryParamValue>` | The template's parameters. |
+| `endpoint` | `string` | The route path relative to the page's slug. Defaults to `/stats/<kebab-name>`. |
+
+The result carries both addresses: `query` is the `QueryRef` to configure or remove it by, `route` is the page slug joined with the endpoint — the URL a block fetches from.
+
+A few rules the operation enforces:
+
+- `name` must be a camelCase identifier, and must not collide with a member the page or the model already has. A collision fails with `duplicate_name` in the `query` scope.
+- `endpoint` must start with `/`, and must not collide with another route on the page. Any path is allowed otherwise, because read-back identifies a query by its shape rather than by its URL.
+- When a model method of that name already exists compiling a *different* chain, the model method is emitted under a free suffixed name, so the queries already sharing the original keep their behavior.
+
+## Filter the Rows
+
+`QueryFilter` is one conjunct of a template's `where`. Filters combine with AND.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `field` | `string` | A field of the resource. It must exist and must not be opaque. |
+| `op` | `FilterOp` | The comparison. |
+| `value` | `QueryParamValue` | A plain scalar baked into the chain, or a `QueryParamBinding`. |
+
+`FilterOp` is `"eq" | "ne" | "gt" | "ge" | "lt" | "le"`. The ordering operators (`gt`, `ge`, `lt`, `le`) are rejected on `boolean` and `select` fields.
+
+`QueryParamValue` is `unknown`, and a query's values are data: an `ExprValue` anywhere in a query's params is refused with `invalid_config`, since a raw expression would put uncheckable code inside a model body. The other sentinels are described in [Value Encodings](./7.values.md).
+
+```typescript
+import { AddQuery } from "@antelopejs/interface-dms-builder";
+
+await AddQuery("/books", {
+  name: "revenue",
+  resource: "book",
+  template: "aggregate",
+  params: {
+    op: "sum",
+    field: "price",
+    where: [{ field: "archived", op: "eq", value: false }],
+  },
+});
+```
+
+## Bind a Value at Request Time
+
+`QueryParamBinding` replaces a baked-in filter value with one supplied per request. It becomes a parameter of the model method and a declared parameter on the route.
+
+```typescript
+import { AddQuery } from "@antelopejs/interface-dms-builder";
+
+await AddQuery("/books", {
+  name: "cheaperThan",
+  resource: "book",
+  template: "count",
+  params: {
+    where: [
+      { field: "price", op: "lt", value: { $param: { name: "maxPrice" } } },
+    ],
+  },
+});
+// GET /books/stats/cheaper-than?maxPrice=20
+```
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `$param.name` | `string` | A camelCase identifier. The route exposes the value under this name. |
+| `$param.in` | `"query" \| "param"` | Where the route reads the value from. Defaults to `"query"`. |
+
+`name` and `in` describe the route, not the model: the route reads the value from that source, coerces it, and passes it positionally to the model method, whose own parameter is named from the template.
+
+Two rules to plan for:
+
+- `in: "param"` reads a path segment, so the endpoint must declare a matching `:name`. The default `/stats/…` endpoint has none, so a path-bound value forces you to supply an endpoint that does. A mismatch fails with `invalid_config` rather than emitting a route whose value never binds.
+- Two filters may bind the same parameter name, but only when they agree on its type and source.
+
+```typescript
+import { AddQuery } from "@antelopejs/interface-dms-builder";
+
+await AddQuery("/books", {
+  name: "countByAuthor",
+  resource: "book",
+  template: "count",
+  endpoint: "/stats/by-author/:authorId",
+  params: {
+    where: [
+      {
+        field: "authorId",
+        op: "eq",
+        value: { $param: { name: "authorId", in: "param" } },
+      },
+    ],
+  },
+});
+```
+
+## Configure a Query
+
+`ConfigureQuery(query, patch, opts?)` recompiles the query from the merged patch and replaces both emitted members. Fields you leave out keep their current value, read back off disk.
+
+```typescript
+import { ConfigureQuery } from "@antelopejs/interface-dms-builder";
+
+await ConfigureQuery("/books@inStockCount", {
+  params: { where: [{ field: "stock", op: "ge", value: 5 }] },
+});
+```
+
+The patch is a `Partial<AddQueryInput>`, so `resource`, `template`, `params` and `endpoint` are all patchable. The query keeps the name in its `QueryRef`: a `name` in the patch is not applied.
+
+A query that no longer reads back as an editable template fails with `opaque_target`. That is deliberate — an opaque chain means a human owns it now, and regenerating it from a template it no longer matches would revert their edit. Remove it and add a new one if you need to.
+
+## Remove a Query
+
+`RemoveQuery(query, opts?)` deletes the query's route from the page, and drops the model method it called once nothing else calls it — a method shared with another query stays. It works on an opaque query too.
+
+```typescript
+import { RemoveQuery } from "@antelopejs/interface-dms-builder";
+
+await RemoveQuery("/books@cheaperThan");
+```
+
+## Read a Query Back
+
+`QueryStructure` is a query as found on disk. Read-back is purely structural: a route reads as a query when its shape and the chain it calls both parse, so a hand-written route matching the grammar is as editable as a generated one, and any edit that keeps the chain in-grammar is simply re-read.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `name` | `string` | The query name. Always present. |
+| `endpoint` | `string` | The route path relative to the page's slug, as `AddQueryInput.endpoint` takes it. Always present. |
+| `resource` | `ResourceRef` | The resource the route's model parameter points at. |
+| `modelMethod` | `string` | The model method the route calls. Several queries may share one method, but only while they want the exact same chain. |
+| `output` | `QueryOutputKind` | The output shape, from the template descriptor. |
+| `template` | `string` | The template the chain was compiled from. |
+| `params` | `Record<string, unknown>` | The parameters that produced the chain. |
+| `routeParams` | `{ name: string; in: "query" \| "param" \| "header" }[]` | The route's declared parameters — the source of truth for a bound value's `name` and `in`. `header` appears only on hand-written routes. |
+| `opaque` | `boolean` | `true` when the query could not be reversed to an editable template. |
+| `opaqueReason` | `"unparseable_route" \| "unparseable_chain"` | Why it is opaque. Set when `opaque === true`. |
+
+The two opaque reasons say which half failed:
+
+- **`unparseable_route`** — the GET wrapper is not the recognized `return { value: await model.m(...) }` shape.
+- **`unparseable_chain`** — the model method it calls is not a chain any registered template accepts: hand-written, edited out of grammar, or emitted by a newer builder.
+
+A query that no longer parses still reports its `endpoint`, `resource` and `modelMethod`; only `template` and `params` go missing. The builder can therefore always see and remove what it cannot edit.
+
+```typescript
+import { GetPageStructure } from "@antelopejs/interface-dms-builder";
+
+const result = await GetPageStructure("/books");
+if (result.ok) {
+  const editable = result.data.queries.filter((query) => !query.opaque);
+  const urls = result.data.queries.map((query) => `/books${query.endpoint}`);
+}
+```
+
+## Next Steps
+
+- [Value Encodings](./7.values.md) - Write configuration values that are not plain literals

package/docs/7.values.md

@@ -0,0 +1,130 @@
+# Value Encodings
+
+## Overview
+
+Configuration values are plain JSON by default. `AddBlockInput.config`, a `ConfigureBlock` patch, a page's `permission` — all of it is written to source exactly as you pass it, as a literal.
+
+Some values are not literals. A Form field's `type` is a `new DefaultDataTypes.StringType(...)` instance; a `TableView`'s controller is a class identifier with an import behind it. Three sentinel object shapes cover those cases: `DataTypeValue` for a DataType instance, `RefValue` for a builder-generated class, and `ExprValue` for a raw expression the builder cannot model. Each is recognized wherever a config value is read, at any depth — inside an array, inside a nested object.
+
+```typescript
+import type {
+  DataTypeValue,
+  ExprValue,
+  RefValue,
+} from "@antelopejs/interface-dms-builder";
+```
+
+## Choose an Encoding
+
+| You are writing | Encoding |
+| --- | --- |
+| A string, number, boolean, array or object | The value itself, as JSON. |
+| A value the catalog marks `x-dataType` | `DataTypeValue` |
+| A reference to a builder-generated resource class | `RefValue` |
+| Anything else that must reach the source as code | `ExprValue` |
+
+The catalog is what tells you which option needs which: an option marked `x-dataType` in a block's `ConfigSchema` takes a `DataTypeValue`, and nothing else. See [Catalog](./3.catalog.md).
+
+## Write a DataType
+
+`DataTypeValue` emits `new <DataType>(<config>)` and adds the import for you.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `$dataType` | `string` | A `DataTypeDescriptor.id` from the catalog, e.g. `"string"` or `"select"`. |
+| `config` | `Record<string, unknown>` | The DataType's options. Omit for a no-arg `new <DataType>()`. |
+
+```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" })
+```
+
+The same encoding is what a resource field's `dataType` takes, described in [Resources](./5.resources.md).
+
+A `$dataType` id the catalog does not list fails with `invalid_config`, and the message points you at `GetCatalog` for the valid ids.
+
+## Reference a Generated Class
+
+`RefValue` emits the bare class identifier of a builder-generated resource, with its import added. It is the structured, validated alternative to `ExprValue` for a class reference — a `RelationType`'s `dataApiController`, for instance.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `$ref.resource` | `string` | A `ResourceRef` — the resource's name, e.g. `"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` selects among the three classes a resource generates: `"dataApi"` for the `DataController`, `"table"` for the `Table`, `"model"` for the `BasicDataModel`. An unknown resource fails with `invalid_config`, and the message points you at `ListResources`.
+
+`AddBlockInput.controller` is the same reference in a dedicated field: a controller-leading block type takes a `ResourceRef` there rather than a `RefValue` in its config. See [Page Operations](./4.page-operations.md).
+
+## Write a Raw Expression
+
+`ExprValue` is emitted verbatim. Reach for it only when the builder cannot model the value structurally.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `$expr` | `string` | TypeScript source, spliced into the emitted file as written. |
+
+```typescript
+import { ConfigureBlock } from "@antelopejs/interface-dms-builder";
+
+await ConfigureBlock("/revenue#total", {
+  valueFormat: { $expr: "REVENUE_FORMAT" },
+});
+```
+
+Two constraints come with it:
+
+- The referenced symbol must already be importable in the target file. Unlike the other two sentinels, `$expr` adds no import.
+- `$expr` is refused inside a query's parameters — a query's values are data, and a raw expression would put uncheckable code inside a model body. See [Queries](./6.queries.md).
+
+Consumers that run the builder in a restricted mode may refuse `$expr` outright, since arbitrary code defeats the structured guarantees the rest of the surface provides. `RefValue` is allowed in that mode precisely because it is validated; prefer it whenever the value you need is a generated class.
+
+## Next Steps
+
+- [Results and Errors](./8.results-and-errors.md) - Branch on an operation's result and read its diagnostics
+
+## Nest a Block in a Config Value
+
+A few options hold a component rather than data — a `ChartCard`'s `chart`, marked `x-component` in the catalog. `BlockValue` is how you write one: 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" } },
+};
+// → chart: ChartArea({ xaxisType: "datetime" })
+```
+
+`type` is a catalog key, like `AddBlockInput.type`; an unknown one is rejected with `invalid_config`. Read-back is symmetrical: a nested factory call whose callee is a known block type comes back as a `$block` sentinel rather than as `$expr`, so the value stays editable.
+
+Most nesting does *not* go through config — it goes through `.child`, which you express with `AddBlockInput.parent` or with `BlockDraft.children`. Reach for `$block` only where the catalog marks an option `x-component`.

package/docs/8.results-and-errors.md

@@ -0,0 +1,201 @@
+# Results and Errors
+
+## 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, `ok: false` carries a single `BuilderError`. Nothing throws for an expected failure — an unknown ref, a duplicate name, a config the engine cannot validate all come back as values.
+
+Mutations are transactional. The engine applies the edit in memory, typechecks the project, and only writes 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>` is:
+
+| Variant | Fields |
+| --- | --- |
+| success | `ok: true`, `data: T`, `changes: FileChange[]`, `warnings?: OpWarning[]` |
+| failure | `ok: false`, `error: BuilderError` |
+
+`OpResult` defaults to `OpResult<void>`, which is what the operations that return nothing but a status use — `ConfigurePage`, `RemoveBlock`, `RemoveField` and the rest.
+
+Reads that use the envelope — `GetPageStructure`, `GetResourceStructure` — return an empty `changes` array on success. The listing operations (`ListPages`, `ListCategories`, `ListResources`, `ListQueryTemplates`, `GetCatalog`) do not use the envelope at all: they return their value directly, and `RefreshSourceIndex` returns `void`.
+
+## Read the Staged Changes
+
+`changes` is 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` | A textual diff of the change. Empty for a deletion. |
+
+A single operation usually touches 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 an otherwise successful operation has something non-fatal to report. It is optional: check for it rather than assuming an array.
+
+| Code | Raised when |
+| --- | --- |
+| `index_clamped` | An `AddBlock` or `MoveBlock` index fell outside the sibling range and was clamped into it. |
+| `datatype_fallback` | A field's DataType is not one the builder maps, so it is handled as a string. |
+| `data_not_dropped` | `DeleteResource` removed the source but could not clear the resource's table data. |
+
+```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 exactly what you need 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. |
+| `unsupported` | `detail: string` | The operation is valid but out of scope for the engine, 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 was rolled 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:
+
+| 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 already served by the page, or a member of the resource's model. |
+
+### Validation Issues
+
+`ValidationIssue` addresses a failure by JSON pointer into the request:
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `pointer` | `string` | A JSON pointer into the offending input, e.g. `/where/0/op`. Empty when the failure is not tied to one key. |
+| `message` | `string` | What is wrong, and often what to call to find the valid values. |
+
+### Typecheck Errors
+
+`TypecheckError` is one TypeScript diagnostic from the in-memory typecheck gate:
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `file` | `string` | The file the diagnostic points at. |
+| `line` | `number` | The line number. |
+| `message` | `string` | The diagnostic message. |
+
+Diagnostics are collected across the project, not just the file the operation edited, so a change that breaks a consumer elsewhere is caught before anything is written.
+
+## Make a Write Conditional
+
+`MutationOpts` is the trailing options argument a mutating operation takes.
+
+| Option | Type | Description |
+| --- | --- | --- |
+| `expectedVersion` | `string` | The version the consumer last read. A mismatch fails with `stale`. |
+
+The operations that edit something that already exists take it: `ConfigurePage`, `DeletePage`, `AddBlock`, `ConfigureBlock`, `MoveBlock`, `RemoveBlock`, `DeleteResource`, `AddField`, `ConfigureField`, `RemoveField`, `AddQuery`, `ConfigureQuery` and `RemoveQuery`. The three creations — `CreatePage`, `CreateCategory` and `CreateResource` — take no options argument, and neither do `ConfigureCategory` and `DeleteCategory`.
+
+The version comes from the structure you read: `PageStructure.version` for a page operation, `ResourceStructure.version` for a resource one. Both are content hashes — of the page file, and of a 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 what the file hashes to now:
+  // re-read the structure, re-decide, and retry.
+}
+```
+
+Omitting `expectedVersion` writes unconditionally. Pass it whenever a human or another process may have touched the file between your read and your write.
+
+Two operations extend `MutationOpts` with a field of their own: `ConfigureBlockOpts` adds `replace`, described in [Page Operations](./4.page-operations.md), and `DeleteResourceOpts` adds `keepData`, described in [Resources](./5.resources.md).