@jarenjs/linq 0.67.0 → 0.72.2

package/docs/SCHEMA-PEN.md

@@ -31,11 +31,9 @@ import * as s from '@jarenjs/linq/schema';
 builds JSON Schema 2020-12 documents: the structural keywords, the
 constraints and the annotations, each with a method of its own; `$query`
 captured through the chain's proxy; `$defs`/`$ref` recursion; the
-normalizer's per-field predicates. Twenty-five further keywords that
-`@jarenjs/validate` also compiles have no method on this surface and are
-written through `.keyword()` or `from()` instead —
-[§6.2](#62-the-absences-twenty-five-keywords-with-no-method) lists them
-by family. The type reading is
+normalizer's per-field predicates. Every owned keyword has a dedicated spelling. Annotation-dependent,
+negating and dynamic-reference methods preserve the existing phantom;
+[§6.2](#62-annotation-and-legacy-boundaries) explains those boundaries. The type reading is
 emit's (EMIT-FORMAT §5–§7), because the agreement pins them equal; a
 constraint (`min`, `pattern`, `format`) never changes a type — the honest
 widening emit documents — with one addition: a string with
@@ -297,6 +295,42 @@ Three rules the tables imply, spelled out:
   so a promise that resolves one calls it with a function and is refused
   by name (`JL0101`); keep builders out of async return positions.
 
+### 2.11 Content, containment and resource identity
+
+Each method preserves the current phantom and replaces a prior value in place.
+The content methods describe encoded strings; `contentSchema` is annotation
+information, not a promise that the validator checks the decoded value.
+`contentValidation: true` enables encoding/media checks. Format bounds require
+a format compiler that supports ordering. Schema-valued methods take builders
+and share the root's definition-hoisting context.
+
+| Method | Emits | `Infer` / `Input` | Status |
+|---|---|---|---|
+| `.id(uri)` | `$id` | `this` | native; string required |
+| array `.minContains(n)`, `.maxContains(n)` | `minContains`, `maxContains` | `this` | native; non-negative integers |
+| string `.contentEncoding(text)` | `contentEncoding` | `this` | native |
+| string `.contentMediaType(text)` | `contentMediaType` | `this` | native |
+| string `.contentSchema(builder)` | `contentSchema` | `this` | native; named definitions hoist |
+| string `.formatMinimum(text)`, `.formatMaximum(text)` | `formatMinimum`, `formatMaximum` | `this` | native |
+| string `.formatExclusiveMinimum(text)`, `.formatExclusiveMaximum(text)` | `formatExclusiveMinimum`, `formatExclusiveMaximum` | `this` | native |
+
+### 2.12 Applicators, references and legacy keywords
+
+All methods below are immutable; repeated calls replace the previous value.
+Raw schemas enter through `from()`. Use `never()` for a false subschema.
+
+| Method | Emits | `Infer` / `Input` | Status |
+|---|---|---|---|
+| `.not(builder)` | `not` | `this` | native |
+| `.unevaluatedProperties(builder)`, `.unevaluatedItems(builder)` | `unevaluatedProperties`, `unevaluatedItems` | `this` | native |
+| `.dependentSchemas(map)`, `.dependencies(map)` | `dependentSchemas`, `dependencies` | `this` | native; legacy dependencies also accept arrays of distinct member names |
+| `.anchor(name)`, `.vocabulary(map)` | `$anchor`, `$vocabulary` | `this` | native |
+| `.dynamicRef(uri)`, `.dynamicAnchor(name)` | `$dynamicRef`, `$dynamicAnchor` | `this` | native; no inferred reference identity |
+| `.recursiveRef(uri)`, `.recursiveAnchor(boolean)` | `$recursiveRef`, `$recursiveAnchor` | `this` | native |
+| `.definitions(map)`, `.additionalItems(builder)` | `definitions`, `additionalItems` | `this` | native; legacy vocabulary |
+| `.dollarData(pointer)`, `.data(map)` | `$data`, `data` | `this` | native |
+| `.legacyNullable(boolean)` | `nullable` | `unknown` | native; distinct from `.nullable()` |
+
 ## 3. Worked examples
 
 One account service, built up. Every `js` fence below exports exactly one
@@ -830,25 +864,13 @@ JSON are still two, and still a collision.
 
 | The spelling that trips it | The message | The spelling that works |
 |---|---|---|
-| `s.string().meta({ type: 'x' })` | `meta() cannot write 'type' — the pen owns that keyword; spell it through the builder method that emits it, keyword('type', value) where no method does, or wrap a hand-written schema with from()` | the method that emits it — or, for a keyword §6.2 lists, `s.keyword(…)` or `s.from({ … })` |
+| `s.string().meta({ type: 'x' })` | `meta() cannot write 'type' — the pen owns that keyword; spell it through the builder method that emits it, keyword('type', value) where no method does, or wrap a hand-written schema with from()` | the method that emits it — or, for a raw value, `.keyword(…)` or `s.from({ … })` |
 | `.check((o, x) => x.foo.eq(1))` | `a check() rule cannot bind 'foo' — its query evaluates with exactly 2 externals, 'root' and 'path'; anything else has nothing to bind to` | `x.root` and `x.path`, and nothing else |
 
-The owned set is every keyword the pen writes itself plus every keyword
-that would change what a document asserts — the structural ones, the
-constraints, `$schema`/`$id`/`$ref`/`$defs` and the anchors, `$query`,
-`default`/`title`/`description`/`examples`/`errorMessage`, and
-`x-coerce`/`x-trim`. `meta()` is for everything else: a 2020-12
-annotation the pen has no method for (`deprecated`, `readOnly`,
-`writeOnly`), and any vendor extension. The type declaration carries the
-same set as `OwnedKeyword`, so a forbidden key does not compile either
-(§5). Twenty-five of the sixty-nine have no method to be spelled through,
-which is why the message names `keyword()` as well;
-[§6.2](#62-the-absences-twenty-five-keywords-with-no-method) lists them
-and the two doors that stay open for them.
-
-`check()`'s two externals are the two the validator binds on every
-`$query` evaluation. The refusal is raised at BUILD time, earlier than
-the validator's own compile error and with the same meaning.
+The owned set is the vocabulary written by the dedicated methods. `meta()`
+refuses those names so an annotation never changes the schema's assertions.
+`keyword()` remains available for raw values and `from()` for whole schemas;
+[§6.2](#62-annotation-and-legacy-boundaries) describes their type boundaries.
 
 ## 5. The types
 
@@ -1081,70 +1103,35 @@ having.
   `packages/json/docs/QUERY-FORMAT.md` §8; a rule outside it is
   application code, run beside validation rather than inside it.
 
-### 6.2 The absences: twenty-five keywords with no method
+### 6.2 Annotation and legacy boundaries
 
-The pen's own list of the keywords it owns
-(`packages/linq/src/schema/builders.js`) is sixty-nine names, and it holds
-two kinds — the keywords a method emits, and the ones that "would change
-what a document asserts" and are kept out of `meta()` for that reason
-alone (the comment above the list says so). The second kind has no
-spelling of its own on this surface:
+Every owned keyword has a dedicated route. The executable census in
+`test/linq/schema-keyword-corpus.js` checks the actual emitted spelling;
+a route that returns a different keyword cannot satisfy it.
 
-| Family | Keywords with no method |
-|---|---|
-| negation | `not` |
-| unevaluated | `unevaluatedProperties`, `unevaluatedItems` |
-| conditional members | `dependentSchemas`, `dependencies` |
-| `contains` bounds | `minContains`, `maxContains` |
-| content | `contentEncoding`, `contentMediaType`, `contentSchema` |
-| format bounds | `formatMinimum`, `formatMaximum`, `formatExclusiveMinimum`, `formatExclusiveMaximum` |
-| identification | `$id`, `$anchor`, `$vocabulary` |
-| dynamic references | `$dynamicRef`, `$dynamicAnchor`, `$recursiveRef`, `$recursiveAnchor` |
-| legacy and extension spellings | `definitions`, `additionalItems`, `$data`, `data` |
-
-`@jarenjs/validate` compiles every one of them — `not` in `combine.js`,
-the unevaluated pair in `unevaluated.js`, `dependentSchemas` in
-`object.js`, the `contains` bounds in `array.js`, the content family in
-`content.js`, the dynamic references in `dynamic-ref.js`, `$data` in
-`dollar-data.js` — so the gap is this pen's surface, not the format and
-not the engine. It is tracked in
-[docs/ROADMAP.md](../../../docs/ROADMAP.md) under the data pair, and
-`test/linq/schema-pen.test.js` holds this table equal to the pen's own
-owned set, so a method that lands for one of them fails the suite until
-its row goes.
-
-Two doors are open in the meantime, and both are rows of
-[§2.10](#210-the-document-and-the-builder-itself):
+`not`, unevaluated constraints, dependencies and dynamic references keep the
+existing phantom. They may reject more values, but TypeScript does not infer
+annotation tracking, negation or dynamic scope. `legacyNullable(boolean)`
+writes the OpenAPI `nullable` spelling exactly and deliberately broadens the
+phantom to `unknown`; `.nullable()` retains its inferred union and standard
+JSON Schema emission. These are separate operations.
 
-```js
-s.string().keyword('not', { type: 'number' })
-// { "type": "string", "not": { "type": "number" } }
+`contentSchema` remains annotation information in the current validator.
+Encoding and media checks require `contentValidation: true`; ordered format
+bounds require a registered format compiler with comparison support.
 
-s.object({ a: s.string() }).keyword('unevaluatedProperties', false)
-// { "type": "object", …, "unevaluatedProperties": false }
-```
+`definitions` and `additionalItems` author draft-07 vocabulary. Declare that
+dialect in a raw root when using them; `document({ draft: '2020-12' })` does
+not translate a legacy tuple. Schema-valued methods accept builders, including
+`from(json)` and `never()` for an exact raw or boolean subschema. They share
+named definition identity with every other branch, including recursive ones.
+Normalizer annotations in branches the normalizer never visits are refused.
 
-`.keyword(key, value)` writes one keyword onto the node the builder is
-assembling, in the order first set, exactly as a named method does;
-`from(json)` wraps a hand-written subschema whole. Neither changes the
-type reading — `.keyword()` answers `this` and `from<T>()` carries the
-type the caller asserts — which is the honest trade rather than a
-shortfall: a keyword with no method has no phantom to read either.
-
-`definitions` is the draft-07 spelling of `$defs`, and `named()` writes
-`$defs`: the pen emits one definitions block under one name, so the older
-keyword is owned to keep a document from carrying both and reached, like
-the rest of the table, through `keyword()` or `from()`.
-
-**`meta()` is not a third door.** Every name in the table is owned, so
-`meta()` refuses it with `JL0104`
-([§4.4](#44-jl0104--the-keyword-and-the-external)) — and the message
-names both doors that ARE open, `keyword()` and `from()`. One name is on
-the owned list for the opposite reason: `nullable` is refused because
-`.nullable()` already exists and emits a type union
-(`type: ['string', 'null']`) — `nullable` as a keyword is an OpenAPI
-spelling that 2020-12 does not carry, and refusing it is what keeps one
-document from claiming both.
+`dollarData(pointer)` builds a `$data` reference object; use its `.schema` as
+a raw constraint value. `data(map)` writes keyword-to-pointer bindings at the
+schema node. Both leave pointer resolution to the validator. `keyword()` and
+`from()` remain the escape hatches for future extensions, with no inferred
+narrowing. A boolean document cannot carry a keyword; widen it first.
 
 ### 6.3 When not to reach for this pen
 
@@ -1180,10 +1167,10 @@ hand, or generate it some other way, when:
 
 ## 7. Cost
 
-`@jarenjs/linq/schema` builds to **<!--fact:bundle.schema-->33,156<!--/fact--> bytes** as a minified,
+`@jarenjs/linq/schema` builds to **<!--fact:bundle.schema-->36,717<!--/fact--> bytes** as a minified,
 tree-shaken ESM bundle — the figure `scripts/check-tree-shaking.js`
 measures and `npm run test:tree-shaking` reports, published rounded
-(<!--fact:bundle.schema.kb-->33<!--/fact--> kB) beside the other nine subpath prices in
+(<!--fact:bundle.schema.kb-->37<!--/fact--> kB) beside the other nine subpath prices in
 [docs/CONSUMING.md](../../../docs/CONSUMING.md).
 
 The probe is a gate, not a report: building

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@jarenjs/linq",
   "private": false,
-  "version": "0.67.0",
+  "version": "0.72.2",
   "type": "module",
   "main": "./src/index.js",
   "types": "./types/index.d.ts",
@@ -47,7 +47,27 @@
       "types": "./types/db.d.ts",
       "default": "./src/db/index.js"
     },
-    "./package.json": "./package.json"
+    "./package.json": "./package.json",
+    "./charts": {
+      "types": "./types/charts.d.ts",
+      "default": "./src/charts/index.js"
+    },
+    "./project": {
+      "types": "./types/project.d.ts",
+      "default": "./src/project/index.js"
+    },
+    "./jtlt": {
+      "types": "./types/jtlt.d.ts",
+      "default": "./src/jtlt/index.js"
+    },
+    "./messages": {
+      "types": "./types/messages.d.ts",
+      "default": "./src/messages/index.js"
+    },
+    "./ai": {
+      "types": "./types/ai.d.ts",
+      "default": "./src/ai/index.js"
+    }
   },
   "files": [
     "types/",
@@ -84,13 +104,13 @@
     "prepack": "npm run build:types"
   },
   "dependencies": {
-    "@jarenjs/core": "^0.67.0",
-    "@jarenjs/json": "^0.67.0"
+    "@jarenjs/core": "^0.72.2",
+    "@jarenjs/json": "^0.72.2"
   },
   "peerDependencies": {
-    "@jarenjs/db": "^0.67.0",
-    "@jarenjs/formats": "^0.67.0",
-    "@jarenjs/validate": "^0.67.0"
+    "@jarenjs/db": "^0.72.2",
+    "@jarenjs/formats": "^0.72.2",
+    "@jarenjs/validate": "^0.72.2"
   },
   "peerDependenciesMeta": {
     "@jarenjs/db": {

package/src/ai/index.js

@@ -0,0 +1,76 @@
+//@ts-check
+/** The AI action document, authored without an AI client, environment or engine. */
+import { DocumentBuilder, optionsOf, snapshot } from '../authored.js';
+import { captureQuery } from '../capture-root.js';
+import { LinqBuildError } from '../errors.js';
+
+const FIELDS = {
+  chunk: ['strategy', 'size'], grep: ['pattern', 'flags', 'limit'], select: ['query'],
+  stat: [], peek: [], map: ['prompt'], reduce: ['query', 'outputSchema'], answer: ['chars'],
+};
+function make(op, from, as, options) {
+  if (typeof from !== 'string' || !from || (op !== 'answer' && (typeof as !== 'string' || !as)))
+    throw new LinqBuildError('JL0101', 'A step needs a source name and, except answer, a result name');
+  return snapshot({ op, from, ...(op === 'answer' ? {} : { as }), ...optionsOf(options, FIELDS[op], `${op}()`) });
+}
+function expression(value) {
+  // The program query receives only its input document: an undeclared external
+  // is the shared capture's JL0104 refusal, not an invented environment lookup.
+  return typeof value === 'function' ? captureQuery('program query', [], value, { fold: false }) : value;
+}
+/** Split a slot into a family of pieces. */
+export function chunk(from, as, options = {}) { return make('chunk', from, as, options); }
+/** Find matching slots with a bounded pattern and options. */
+export function grep(from, as, options) { return make('grep', from, as, options); }
+/** Query one JSON slot; a callback is captured as ordinary query JSON. */
+export function select(from, as, query) { return make('select', from, as, { query: expression(query) }); }
+/** Inspect counts and shape. */
+export function stat(from, as) { return make('stat', from, as, {}); }
+/** Inspect a slot's metadata and excerpt. */
+export function peek(from, as) { return make('peek', from, as, {}); }
+/** Ask one bounded prompt per member of a slot/family. */
+export function map(from, as, prompt) { return make('map', from, as, { prompt }); }
+/** Query the collected results of an earlier map. */
+export function reduce(from, as, query, options = {}) {
+  return make('reduce', from, as, { query: expression(query), ...optionsOf(options, ['outputSchema'], 'reduce()') });
+}
+/** Declare the final answer slot and optional excerpt bound. */
+export function answer(from, options = {}) { return make('answer', from, undefined, options); }
+
+/** An immutable ordered program; binding types are phantoms. */
+export class ProgramBuilder extends DocumentBuilder {
+  /** Append a public step. An answer closes this builder. @param {any} value */
+  step(value) {
+    if (this.schema.steps.at(-1)?.op === 'answer')
+      throw new LinqBuildError('JL0102', 'answer is terminal; start another program to append work');
+    if (value === null || typeof value !== 'object' || !Object.hasOwn(FIELDS, value.op))
+      throw new LinqBuildError('JL0101', 'step() needs a known program operation');
+    const step = optionsOf(value, ['op', 'from', ...(value.op === 'answer' ? [] : ['as']), ...FIELDS[value.op]], 'step()');
+    return this.with({ steps: [...this.schema.steps, step] });
+  }
+  /** Append a chunk step. */
+  chunk(from, as, options = {}) { return this.step(chunk(from, as, options)); }
+  /** Append a grep step. */
+  grep(from, as, options) { return this.step(grep(from, as, options)); }
+  /** Append a select step. */
+  select(from, as, query) { return this.step(select(from, as, query)); }
+  /** Append a stat step. */
+  stat(from, as) { return this.step(stat(from, as)); }
+  /** Append a peek step. */
+  peek(from, as) { return this.step(peek(from, as)); }
+  /** Append a map step. */
+  map(from, as, prompt) { return this.step(map(from, as, prompt)); }
+  /** Append a reduce step. */
+  reduce(from, as, query, options = {}) { return this.step(reduce(from, as, query, options)); }
+  /** Append the terminal answer. */
+  answer(from, options = {}) { return this.step(answer(from, options)); }
+}
+
+/** Declare input slot names for TypeScript; they never become document members. @param {readonly string[]} slots */
+export function program(slots = []) {
+  if (!Array.isArray(slots) || slots.some((name) => typeof name !== 'string' || !name))
+    throw new LinqBuildError('JL0101', 'program() takes input slot names');
+  return new ProgramBuilder({ steps: [] });
+}
+/** A raw public program. Compilation remains authoritative for names and semantics. @param {any} document */
+export function from(document) { return new ProgramBuilder(document); }

package/src/authored.js

@@ -0,0 +1,38 @@
+//@ts-check
+/** Immutable JSON document storage shared by the authored-format pens. */
+import { cloneJson, deepFreeze } from '@jarenjs/core/object';
+import { requireJson, requireNameMap } from './json-boundary.js';
+import { LinqBuildError } from './errors.js';
+
+/** A snapshot, never a view of a caller-owned document. @param {any} value */
+export function snapshot(value) {
+  return deepFreeze(cloneJson(requireJson(value, 'document')));
+}
+
+/** The closed option boundary; extensions enter through the raw document factory. */
+export function optionsOf(value, keys, what) {
+  if (value === null || typeof value !== 'object' || Array.isArray(value))
+    throw new LinqBuildError('JL0101', `${what} takes a plain object`);
+  requireNameMap(value, what);
+  for (const key of Object.keys(value)) {
+    if (!keys.includes(key))
+      throw new LinqBuildError('JL0101', `${what} does not take '${key}' — use from() for a raw document`);
+  }
+  return snapshot(value);
+}
+
+/** A standard document with fluent, immutable replacement. */
+export class DocumentBuilder {
+  #schema;
+  /** @param {any} document */
+  constructor(document) { this.#schema = snapshot(document); }
+  /** The public document, deeply frozen. */
+  get schema() { return this.#schema; }
+  /** JSON serialization is exactly the public document. */
+  toJSON() { return this.#schema; }
+  /** Replace members without changing the original builder. @param {object} patch */
+  with(patch) {
+    const Kind = /** @type {any} */ (this.constructor);
+    return new Kind({ ...this.#schema, ...patch });
+  }
+}

package/src/charts/index.js

@@ -0,0 +1,131 @@
+//@ts-check
+/** Chart-definition factories; the chart engine is injected by the consumer. */
+import { DocumentBuilder, optionsOf } from '../authored.js';
+import { LinqBuildError } from '../errors.js';
+import { CHART_FIELDS } from './vocabulary.js';
+
+/** Immutable chart definition; methods keep the original discriminator. */
+export class ChartBuilder extends DocumentBuilder {
+  /** @param {Record<string, any>} value */
+  options(value) {
+    const keys = CHART_FIELDS[this.schema.type];
+    if (keys === undefined) throw new LinqBuildError('JL0101', `unknown chart kind '${this.schema.type}'`);
+    return this.with(optionsOf(value, keys, `${this.schema.type}()`));
+  }
+  /** `title`. @param {any} value */
+  title(value) { return this.options({ title: value }); }
+  /** `stream`. @param {any} value */
+  stream(value) { return this.options({ stream: value }); }
+  /** `donut`. @param {any} value */
+  donut(value) { return this.options({ donut: value }); }
+  /** `slices`. @param {any} value */
+  slices(value) { return this.options({ slices: value }); }
+  /** `stacked`. @param {any} value */
+  stacked(value) { return this.options({ stacked: value }); }
+  /** `log`. @param {any} value */
+  log(value) { return this.options({ log: value }); }
+  /** `orient`. @param {any} value */
+  orient(value) { return this.options({ orient: value }); }
+  /** `catLabel`. @param {any} value */
+  catLabel(value) { return this.options({ catLabel: value }); }
+  /** `valLabel`. @param {any} value */
+  valLabel(value) { return this.options({ valLabel: value }); }
+  /** `categories`. @param {any} value */
+  categories(value) { return this.options({ categories: value }); }
+  /** `series`. @param {any} value */
+  series(value) { return this.options({ series: value }); }
+  /** `x`. @param {any} value */
+  x(value) { return this.options({ x: value }); }
+  /** `markers`. @param {any} value */
+  markers(value) { return this.options({ markers: value }); }
+  /** `xLabel`. @param {any} value */
+  xLabel(value) { return this.options({ xLabel: value }); }
+  /** `yLabel`. @param {any} value */
+  yLabel(value) { return this.options({ yLabel: value }); }
+  /** `domain`. @param {any} value */
+  domain(value) { return this.options({ domain: value }); }
+  /** `sampling`. @param {any} value */
+  sampling(value) { return this.options({ sampling: value }); }
+  /** `dateNames`. @param {any} value */
+  dateNames(value) { return this.options({ dateNames: value }); }
+  /** `timeFormats`. @param {any} value */
+  timeFormats(value) { return this.options({ timeFormats: value }); }
+  /** `candles`. @param {any} value */
+  candles(value) { return this.options({ candles: value }); }
+  /** `xLog`. @param {any} value */
+  xLog(value) { return this.options({ xLog: value }); }
+  /** `yLog`. @param {any} value */
+  yLog(value) { return this.options({ yLog: value }); }
+  /** `refY`. @param {any} value */
+  refY(value) { return this.options({ refY: value }); }
+  /** `refLabel`. @param {any} value */
+  refLabel(value) { return this.options({ refLabel: value }); }
+  /** `points`. @param {any} value */
+  points(value) { return this.options({ points: value }); }
+  /** `max`. @param {any} value */
+  max(value) { return this.options({ max: value }); }
+  /** `axes`. @param {any} value */
+  axes(value) { return this.options({ axes: value }); }
+  /** `value`. @param {any} value */
+  value(value) { return this.options({ value: value }); }
+  /** `min`. @param {any} value */
+  min(value) { return this.options({ min: value }); }
+  /** `unit`. @param {any} value */
+  unit(value) { return this.options({ unit: value }); }
+  /** `tone`. @param {any} value */
+  tone(value) { return this.options({ tone: value }); }
+  /** `boxes`. @param {any} value */
+  boxes(value) { return this.options({ boxes: value }); }
+  /** `xLabels`. @param {any} value */
+  xLabels(value) { return this.options({ xLabels: value }); }
+  /** `yLabels`. @param {any} value */
+  yLabels(value) { return this.options({ yLabels: value }); }
+  /** `values`. @param {any} value */
+  values(value) { return this.options({ values: value }); }
+  /** `aspect`. @param {any} value */
+  aspect(value) { return this.options({ aspect: value }); }
+  /** `items`. @param {any} value */
+  items(value) { return this.options({ items: value }); }
+  /** `xs`. @param {any} value */
+  xs(value) { return this.options({ xs: value }); }
+  /** `nodes`. @param {any} value */
+  nodes(value) { return this.options({ nodes: value }); }
+  /** `links`. @param {any} value */
+  links(value) { return this.options({ links: value }); }
+  /** `label`. @param {any} value */
+  label(value) { return this.options({ label: value }); }
+  /** `simplify`. @param {any} value */
+  simplify(value) { return this.options({ simplify: value }); }
+  /** `features`. @param {any} value */
+  features(value) { return this.options({ features: value }); }
+}
+
+/** A raw public chart definition, including JSON extensions. @param {any} document */
+export function from(document) { return new ChartBuilder(document); }
+
+/** A pie chart. @param {object} [options] */
+export function pie(options = {}) { return new ChartBuilder({ type: 'pie' }).options(options); }
+/** A bar chart. @param {object} [options] */
+export function bar(options = {}) { return new ChartBuilder({ type: 'bar' }).options(options); }
+/** A line chart. @param {object} [options] */
+export function line(options = {}) { return new ChartBuilder({ type: 'line' }).options(options); }
+/** A scatter chart. @param {object} [options] */
+export function scatter(options = {}) { return new ChartBuilder({ type: 'scatter' }).options(options); }
+/** A candlestick chart. @param {object} [options] */
+export function candlestick(options = {}) { return new ChartBuilder({ type: 'candlestick' }).options(options); }
+/** A radar chart. @param {object} [options] */
+export function radar(options = {}) { return new ChartBuilder({ type: 'radar' }).options(options); }
+/** A gauge chart. @param {object} [options] */
+export function gauge(options = {}) { return new ChartBuilder({ type: 'gauge' }).options(options); }
+/** A boxplot chart. @param {object} [options] */
+export function boxplot(options = {}) { return new ChartBuilder({ type: 'boxplot' }).options(options); }
+/** A heatmap chart. @param {object} [options] */
+export function heatmap(options = {}) { return new ChartBuilder({ type: 'heatmap' }).options(options); }
+/** A treemap chart. @param {object} [options] */
+export function treemap(options = {}) { return new ChartBuilder({ type: 'treemap' }).options(options); }
+/** A streamgraph chart. @param {object} [options] */
+export function streamgraph(options = {}) { return new ChartBuilder({ type: 'streamgraph' }).options(options); }
+/** A sankey chart. @param {object} [options] */
+export function sankey(options = {}) { return new ChartBuilder({ type: 'sankey' }).options(options); }
+/** A map chart. @param {object} [options] */
+export function map(options = {}) { return new ChartBuilder({ type: 'map' }).options(options); }

package/src/charts/vocabulary.js

@@ -0,0 +1,119 @@
+// Derived from chart-definition.schema.json by scripts/generate-chart-pen.js.
+/** The known member set for each public chart discriminator. */
+export const CHART_FIELDS = Object.freeze({
+  "pie": [
+    "title",
+    "stream",
+    "donut",
+    "slices"
+  ],
+  "bar": [
+    "title",
+    "stream",
+    "stacked",
+    "log",
+    "orient",
+    "catLabel",
+    "valLabel",
+    "categories",
+    "series"
+  ],
+  "line": [
+    "title",
+    "stream",
+    "x",
+    "log",
+    "markers",
+    "xLabel",
+    "yLabel",
+    "domain",
+    "sampling",
+    "dateNames",
+    "timeFormats",
+    "series"
+  ],
+  "scatter": [
+    "title",
+    "stream",
+    "xLog",
+    "yLog",
+    "refY",
+    "refLabel",
+    "xLabel",
+    "yLabel",
+    "points"
+  ],
+  "candlestick": [
+    "title",
+    "stream",
+    "xLabel",
+    "yLabel",
+    "domain",
+    "dateNames",
+    "timeFormats",
+    "candles"
+  ],
+  "radar": [
+    "title",
+    "stream",
+    "max",
+    "axes",
+    "series"
+  ],
+  "gauge": [
+    "title",
+    "stream",
+    "value",
+    "min",
+    "max",
+    "unit",
+    "tone"
+  ],
+  "boxplot": [
+    "title",
+    "stream",
+    "catLabel",
+    "valLabel",
+    "boxes"
+  ],
+  "heatmap": [
+    "title",
+    "stream",
+    "log",
+    "xLabel",
+    "yLabel",
+    "xLabels",
+    "yLabels",
+    "values"
+  ],
+  "treemap": [
+    "title",
+    "stream",
+    "aspect",
+    "items"
+  ],
+  "streamgraph": [
+    "title",
+    "stream",
+    "xLabel",
+    "xs",
+    "series"
+  ],
+  "sankey": [
+    "title",
+    "stream",
+    "nodes",
+    "links"
+  ],
+  "map": [
+    "title",
+    "stream",
+    "value",
+    "label",
+    "log",
+    "aspect",
+    "simplify",
+    "features",
+    "points"
+  ]
+});

package/src/expression.js

@@ -98,7 +98,7 @@ function bracketName(name) {
  * @param {string} name
  * @returns {string}
  */
-function memberSegment(name) {
+export function memberSegment(name) {
   return SHORTHAND_RE.test(name) ? `.${name}` : bracketName(name);
 }