@jarenjs/linq 0.67.0 → 0.72.2

package/src/federate.js

@@ -45,6 +45,7 @@
 
 import { LinqBuildError, LinqRuntimeError } from './errors.js';
 import { compileDocument, isProviderSource, providerRoot } from './provider.js';
+import { memberSegment } from './expression.js';
 
 /** The strategies this boundary knows. One, for now, and it says so. */
 const STRATEGIES = new Set(['hash']);
@@ -123,18 +124,6 @@ function byteSize(row) {
   return encoder.encode(text).length;
 }
 
-/**
- * The root NAME a root expression carries: `'$.Post[*]'` → `'Post'`.
- * A federated source's root is always this shape, because the
- * federation names it.
- * @param {string} root
- * @returns {string}
- */
-function rootName(root) {
-  const match = /^\$\.([^.[\]]+)\[\*\]$/.exec(root);
-  return match === null ? '' : match[1];
-}
-
 /**
  * The FLWOR a terminal wrapped, and how to put a rewritten one back.
  *
@@ -412,7 +401,7 @@ export function federate(spec) {
     // the federated root, which is what the chain binds and what the
     // resident document ranges over; the source's OWN root is what its
     // child document uses, and `childDocument` rewrites between them
-    const root = `$.${name}[*]`;
+    const root = `$${memberSegment(name)}[*]`;
     members.set(root, { name, root, provider, estimatedRows });
   }
 
@@ -448,8 +437,8 @@ export function federate(spec) {
         }, open);
 
       const input = {
-        [rootName(plan.build.root)]: built.rows,
-        [rootName(plan.probe.root)]: probed.rows,
+        [plan.build.member.name]: built.rows,
+        [plan.probe.member.name]: probed.rows,
       };
       const compiled = compileDocument(plan.resident,
         { ...options, externals: options?.externalNames ?? [] });
@@ -462,7 +451,7 @@ export function federate(spec) {
     catch (error) {
       // the call's own failure is the one the caller gets: a cursor
       // that also fails to close must not replace the budget's refusal
-      await closeAll(open);
+      await closeAll(open).catch(() => {});
       throw error;
     }
   };
@@ -513,7 +502,7 @@ export function federate(spec) {
   const handleFor = (name) => {
     let handle = handles.get(name);
     if (handle === undefined) {
-      const root = `$.${name}[*]`;
+      const root = `$${memberSegment(name)}[*]`;
       if (!members.has(root)) {
         throw new LinqBuildError('JL0005',
           `'${name}' is not one of this federation's sources (${names.join(', ')})`);

package/src/jtlt/index.js

@@ -0,0 +1,97 @@
+//@ts-check
+/** JTLT's public rules and text segments, with query capture but no renderer. */
+import { DocumentBuilder, optionsOf, snapshot } from '../authored.js';
+import { captureQuery } from '../capture-root.js';
+import { LinqBuildError } from '../errors.js';
+
+const RULE_KEYS = ['match', 'mode', 'priority'];
+const OUTPUTS = ['text', 'xml'];
+
+function list(value, what) {
+  if (!Array.isArray(value)) throw new LinqBuildError('JL0101', `${what} takes an array`);
+  return value;
+}
+
+function rulesOf(values) {
+  return list(values, 'rules()').map((value) => value instanceof RuleBuilder ? value.schema : snapshot(value));
+}
+
+function queryDocument(value, options) {
+  const opts = optionsOf(options ?? {}, ['externals'], 'query options');
+  const names = opts.externals ?? [];
+  if (!Array.isArray(names) || names.some((n) => typeof n !== 'string' || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(n))
+    || new Set(names).size !== names.length || names.includes('root') || names.includes('path'))
+    throw new LinqBuildError('JL0101', 'externals must be unique parameter names; root and path are already bound');
+  // An undeclared callback external is the shared capture's JL0104 refusal.
+  return snapshot(typeof value === 'function'
+    ? captureQuery('JTLT expression', ['root', 'path', ...names], value, { fold: false })
+    : value);
+}
+
+/** A literal segment; escape a leading dollar so it cannot become a query. @param {string} value */
+export function text(value) {
+  if (typeof value !== 'string') throw new LinqBuildError('JL0101', 'text() takes a string');
+  return value.startsWith('$') ? '$' + value : value;
+}
+
+/** An interpolated query string/object, optionally captured from a callback. */
+export function query(value, options = {}) {
+  const doc = queryDocument(value, options);
+  if (typeof doc !== 'string' && (doc === null || Array.isArray(doc) || typeof doc !== 'object'
+    || !Object.keys(doc).some((key) => key.startsWith('$'))))
+    throw new LinqBuildError('JL0101', 'query() needs a string or query object segment; use json() for a literal JSON value');
+  return doc;
+}
+
+/** Interpolate a query without output-method escaping. */
+export function raw(value, options = {}) { return snapshot({ $raw: queryDocument(value, options) }); }
+/** Serialize query results as JSON text, with output-method escaping. */
+export function json(value, options = {}) { return snapshot({ $json: queryDocument(value, options) }); }
+/** Splice template dispatch, optionally selecting a literal mode. */
+export function apply(value, mode, options = {}) {
+  if (mode !== undefined && typeof mode !== 'string') throw new LinqBuildError('JL0101', 'apply() mode must be a string');
+  const doc = queryDocument(value, options);
+  return snapshot({ $apply: mode === undefined ? doc : [doc, mode] });
+}
+
+/** One immutable template rule. */
+export class RuleBuilder extends DocumentBuilder {
+  /** Replace the segment list. @param {readonly any[]} value */
+  body(value) { return this.with({ body: list(value, 'body()') }); }
+  /** Replace the JSLT match specification. @param {any} value */
+  match(value) { return this.with({ match: value }); }
+  /** Replace the mode. @param {string} value */
+  mode(value) { return this.with({ mode: value }); }
+  /** Replace priority; the compiler owns the reserved priority band. @param {number} value */
+  priority(value) { return this.with({ priority: value }); }
+}
+
+/** A public rule; omit match for a catch-all in its mode. */
+export function rule(body = [], options = {}) {
+  return new RuleBuilder({ ...optionsOf(options, RULE_KEYS, 'rule()'), body: list(body, 'rule() body') });
+}
+
+/** A bare rule list or versioned JTLT envelope. */
+export class TemplateBuilder extends DocumentBuilder {
+  /** Replace rules while preserving the bare/envelope distinction. @param {readonly any[]} values */
+  rules(values) {
+    const rules = rulesOf(values);
+    return Array.isArray(this.schema) ? new TemplateBuilder(rules) : this.with({ rules });
+  }
+  /** Append a rule without changing existing rules. @param {any} value */
+  rule(value) { return this.rules([...(Array.isArray(this.schema) ? this.schema : this.schema.rules), value]); }
+  /** Set output; a bare list becomes an envelope when an output is declared. @param {'text' | 'xml'} value */
+  output(value) {
+    if (!OUTPUTS.includes(value)) throw new LinqBuildError('JL0101', 'output() takes text or xml');
+    return Array.isArray(this.schema) ? stylesheet(this.schema, { output: value }) : this.with({ output: value });
+  }
+}
+
+/** The versioned public template envelope. */
+export function stylesheet(rules = [], options = {}) {
+  return new TemplateBuilder({ $jtlt: '0.1', ...optionsOf(options, ['output'], 'stylesheet()'), rules: rulesOf(rules) });
+}
+/** The public bare-rule-array shorthand, preserved on serialization. @param {readonly any[]} rules */
+export function bare(rules = []) { return new TemplateBuilder(rulesOf(rules)); }
+/** Preserve a raw public template exactly, including envelope member order. @param {any} document */
+export function from(document) { return new TemplateBuilder(document); }

package/src/messages/index.js

@@ -0,0 +1,96 @@
+//@ts-check
+/** JSON catalogs and existing MessageSpec values, checked against English vocabulary. */
+import { compileMessageTemplate } from '@jarenjs/core/message';
+import { snapshot, optionsOf } from '../authored.js';
+import { requireNameMap } from '../json-boundary.js';
+import { LinqBuildError } from '../errors.js';
+import { CATALOGS } from './vocabulary.js';
+export { CATALOGS } from './vocabulary.js';
+
+const ALL = Object.freeze(Object.assign({}, ...Object.values(CATALOGS)));
+function sourceOf(source) {
+  if (source === 'all') return ALL;
+  if (!Object.hasOwn(CATALOGS, source)) throw new LinqBuildError('JL0101', `Unknown message catalog '${source}'`);
+  return CATALOGS[source];
+}
+function mapOf(value) {
+  if (value === null || typeof value !== 'object' || Array.isArray(value))
+    throw new LinqBuildError('JL0101', 'A catalog takes a plain message-id map');
+  return requireNameMap(value, 'catalog entries');
+}
+function checkTemplate(id, text, reference, locale, exact = true) {
+  if (!Object.hasOwn(reference, id)) throw new LinqBuildError('JL0101', `${locale}/${id}: unknown message id`);
+  if (typeof text !== 'string') throw new LinqBuildError('JL0101', `${locale}/${id}: JSON catalog entries are template strings`);
+  const names = compileMessageTemplate(text).parameters;
+  const missing = exact ? reference[id].filter((name) => !names.includes(name)) : [];
+  const extra = names.filter((name) => !reference[id].includes(name));
+  if (missing.length || extra.length)
+    throw new LinqBuildError('JL0101', `${locale}/${id}: placeholder mismatch; missing [${missing.join(', ')}], extra [${extra.join(', ')}]`);
+}
+
+/** An immutable catalog draft. Serialize only after complete() or explicit partial(). */
+export class CatalogBuilder {
+  #document;
+  #source;
+  #locale;
+  /** @param {object} document @param {string} source @param {string} locale */
+  constructor(document, source, locale) {
+    sourceOf(source);
+    if (typeof locale !== 'string' || !locale) throw new LinqBuildError('JL0101', 'A catalog needs a nonempty locale name');
+    this.#document = snapshot(mapOf(document));
+    this.#source = source;
+    this.#locale = locale;
+  }
+  /** Add or replace a template, checking its placeholders immediately. */
+  entry(id, value) {
+    checkTemplate(id, value, sourceOf(this.#source), this.#locale);
+    return new CatalogBuilder({ ...this.#document, [id]: value }, this.#source, this.#locale);
+  }
+  /** Add several templates atomically; the prior draft is unchanged on refusal. @param {object} values */
+  entries(values) {
+    const reference = sourceOf(this.#source);
+    for (const [id, value] of Object.entries(mapOf(values))) checkTemplate(id, value, reference, this.#locale);
+    return new CatalogBuilder({ ...this.#document, ...values }, this.#source, this.#locale);
+  }
+  /** Emit an explicitly partial catalog; all present entries still need valid names/placeholders. */
+  partial() {
+    const reference = sourceOf(this.#source);
+    for (const [id, value] of Object.entries(this.#document)) checkTemplate(id, value, reference, this.#locale);
+    return this.#document;
+  }
+  /** Emit a complete catalog, refusing missing or extra ids before publication. */
+  complete() {
+    const document = this.partial();
+    const missing = Object.keys(sourceOf(this.#source)).filter((id) => !Object.hasOwn(document, id));
+    if (missing.length) throw new LinqBuildError('JL0101', `${this.#locale}: incomplete ${this.#source} catalog; missing [${missing.join(', ')}]`);
+    return document;
+  }
+  /** Serializing an unfinished draft is a completeness check, never an implicit partial. */
+  toJSON() { return this.complete(); }
+}
+
+/** Start a catalog for an English-owned key space and a diagnostic locale name. */
+export function catalog(source = 'all', locale = 'en') { return new CatalogBuilder({}, source, locale); }
+/** A raw JSON catalog draft; both exits validate its keys and placeholders. */
+export function from(document, options = {}) {
+  const opts = optionsOf(options, ['source', 'locale'], 'from()');
+  return new CatalogBuilder(document, opts.source ?? 'all', opts.locale ?? 'en');
+}
+/** An inline MessageSpec string, parsed by the same compiler as a catalog entry. @param {string} value */
+export function inline(value) {
+  if (typeof value !== 'string') throw new LinqBuildError('JL0101', 'inline() takes a template string');
+  compileMessageTemplate(value);
+  return value;
+}
+/** The existing structured MessageSpec; it is a message reference, not a catalog entry. */
+export function message(id, options = {}) {
+  if (!Object.hasOwn(ALL, id)) throw new LinqBuildError('JL0101', `Unknown message id '${id}'`);
+  const opts = optionsOf(options, ['params', 'message'], 'message()');
+  if (Object.hasOwn(opts, 'params')) {
+    for (const name of Object.keys(mapOf(opts.params))) {
+      if (!ALL[id].includes(name)) throw new LinqBuildError('JL0101', `${id}: unknown parameter '${name}'`);
+    }
+  }
+  if (Object.hasOwn(opts, 'message')) checkTemplate(id, opts.message, ALL, 'fallback', false);
+  return snapshot({ $msgid: id, ...opts });
+}

package/src/messages/vocabulary.js

@@ -0,0 +1,259 @@
+// Derived from the English catalogs by scripts/generate-message-pen.js.
+import { deepFreeze } from '@jarenjs/core/object';
+/** Canonical parameter names, grouped by their owning English catalog. */
+export const CATALOGS = deepFreeze({
+  "validate": {
+    "type": [
+      "type",
+      "types"
+    ],
+    "required": [
+      "missingProperty"
+    ],
+    "minimum": [
+      "comparison",
+      "limit"
+    ],
+    "maximum": [
+      "comparison",
+      "limit"
+    ],
+    "exclusiveMinimum": [
+      "comparison",
+      "limit"
+    ],
+    "exclusiveMaximum": [
+      "comparison",
+      "limit"
+    ],
+    "multipleOf": [
+      "multipleOf"
+    ],
+    "minLength": [
+      "limit"
+    ],
+    "maxLength": [
+      "limit"
+    ],
+    "pattern": [
+      "pattern"
+    ],
+    "additionalProperties": [
+      "additionalProperty"
+    ],
+    "minProperties": [
+      "limit"
+    ],
+    "maxProperties": [
+      "limit"
+    ],
+    "minItems": [
+      "limit"
+    ],
+    "maxItems": [
+      "limit"
+    ],
+    "uniqueItems": [],
+    "contains": [],
+    "items": [],
+    "allOf": [],
+    "anyOf": [],
+    "oneOf": [],
+    "not": [],
+    "format": [
+      "format"
+    ],
+    "if": [],
+    "then": [],
+    "else": [],
+    "false schema": [],
+    "$query": [
+      "code",
+      "docPath"
+    ],
+    "JQ2001": [
+      "code",
+      "docPath"
+    ],
+    "JQ2003": [
+      "code",
+      "docPath"
+    ]
+  },
+  "forms": {
+    "form/required": [],
+    "form/type": [
+      "type"
+    ],
+    "form/const": [
+      "constValue"
+    ],
+    "form/enum": [
+      "enumValues"
+    ],
+    "form/minLength": [
+      "len",
+      "limit"
+    ],
+    "form/maxLength": [
+      "len",
+      "limit"
+    ],
+    "form/pattern": [
+      "pattern"
+    ],
+    "form/format": [
+      "format"
+    ],
+    "form/minimum": [
+      "limit"
+    ],
+    "form/maximum": [
+      "limit"
+    ],
+    "form/exclusiveMinimum": [
+      "limit"
+    ],
+    "form/exclusiveMaximum": [
+      "limit"
+    ],
+    "form/multipleOf": [
+      "multipleOf"
+    ],
+    "form/minItems": [
+      "limit"
+    ],
+    "form/maxItems": [
+      "limit"
+    ],
+    "form/uniqueItems": [],
+    "form/minProperties": [
+      "limit"
+    ],
+    "form/maxProperties": [
+      "limit"
+    ],
+    "x-form/assert": [],
+    "form/addItem": [],
+    "form/removeItem": []
+  },
+  "contract": {
+    "contract/not-found": [],
+    "contract/method-not-allowed": [
+      "allow"
+    ],
+    "contract/body-too-large": [
+      "limit",
+      "op"
+    ],
+    "contract/unsupported-media": [
+      "media",
+      "op"
+    ],
+    "contract/malformed-json": [
+      "op"
+    ],
+    "contract/invalid-input": [
+      "op"
+    ],
+    "contract/idempotency-key-required": [
+      "op"
+    ],
+    "contract/handler-failed": [
+      "op"
+    ],
+    "contract/idempotency-conflict": [
+      "kind",
+      "op"
+    ],
+    "contract/invalid-output": [
+      "op"
+    ],
+    "contract/malformed-path": [],
+    "contract/malformed-query": [],
+    "contract/not-implemented": [
+      "op"
+    ],
+    "contract/precondition-failed": [
+      "op"
+    ],
+    "contract/invalid-header": [
+      "header",
+      "op"
+    ],
+    "contract/handler-error": [
+      "code",
+      "op"
+    ],
+    "contract/client-invalid-input": [
+      "op"
+    ],
+    "contract/network": [
+      "name",
+      "op"
+    ],
+    "contract/cancelled": [
+      "op"
+    ],
+    "contract/invalid-response": [
+      "op"
+    ],
+    "contract/key-storage-failed": [
+      "op"
+    ],
+    "contract/undeclared-response": [
+      "op",
+      "status"
+    ],
+    "contract/not-a-contract": [
+      "id"
+    ],
+    "contract/incompatible": [
+      "client",
+      "id",
+      "server"
+    ],
+    "contract/host-failed": [
+      "op"
+    ],
+    "contract/local-handler-failed": [
+      "op"
+    ],
+    "contract/unknown-operation": [],
+    "contract/port-timeout": [
+      "ms",
+      "op"
+    ],
+    "contract/malformed-frame": [
+      "op"
+    ],
+    "contract/channel-closed": [
+      "op"
+    ],
+    "contract/not-a-stream": [
+      "op"
+    ],
+    "contract/invalid-snapshot": [
+      "op"
+    ],
+    "contract/seq-regression": [
+      "op"
+    ],
+    "contract/stream-error": [
+      "code",
+      "op"
+    ],
+    "contract/heartbeat-missed": [
+      "ms",
+      "op"
+    ],
+    "contract/slow-consumer": [
+      "op"
+    ],
+    "contract/reconnect-exhausted": [
+      "attempts",
+      "lastCode",
+      "op"
+    ]
+  }
+});

package/src/project/index.js

@@ -0,0 +1,54 @@
+//@ts-check
+/** Typed files and project envelopes; Studio owns parsing and normalization. */
+import { DocumentBuilder, optionsOf, snapshot } from '../authored.js';
+import { LinqBuildError } from '../errors.js';
+
+/** The public project file vocabulary, held equal to Studio's schema by tests. */
+export const FILE_KINDS = Object.freeze(['app', 'jslt', 'query', 'state', 'data', 'schema', 'fsm', 'dag', 'model', 'contract']);
+const LAYOUT_KEYS = ['mode', 'ratio', 'autorun'];
+
+/** One file, preserving the caller's text byte-for-byte. */
+export function file(name, kind, text) {
+  if (typeof name !== 'string' || name.length === 0 || !FILE_KINDS.includes(kind) || typeof text !== 'string')
+    throw new LinqBuildError('JL0101', 'file() requires a nonempty name, a declared kind and text');
+  return snapshot({ name, kind, text });
+}
+
+/** One file holding a public JSON value; pass another pen's `.schema` explicitly. */
+export function jsonFile(name, kind, document) { return file(name, kind, JSON.stringify(snapshot(document))); }
+
+/** Validate the authoring shape, preserving duplicate names for Studio to judge. */
+function filesOf(files) {
+  if (!Array.isArray(files)) throw new LinqBuildError('JL0101', 'files() takes an array of project files');
+  return files.map((value) => {
+    const f = optionsOf(value, ['name', 'kind', 'text'], 'file');
+    return file(f.name, f.kind, f.text);
+  });
+}
+
+/** Immutable public project document. */
+export class ProjectBuilder extends DocumentBuilder {
+  /** Replace the whole file list. @param {readonly object[]} values */
+  files(values) { return this.with({ files: filesOf(values) }); }
+  /** Append one file, without inventing a duplicate-name policy. @param {object} value */
+  file(value) { return this.files([...this.schema.files, value]); }
+  /** The requested active file; Studio falls back if it cannot resolve it. @param {string} name */
+  active(name) {
+    if (typeof name !== 'string') throw new LinqBuildError('JL0101', 'active() takes a file name');
+    return this.with({ active: name });
+  }
+  /** Replace layout metadata; Studio supplies defaults. @param {object} value */
+  layout(value) { return this.with({ layout: optionsOf(value, LAYOUT_KEYS, 'layout()') }); }
+}
+
+/** Start a project with files and optional active/layout metadata. */
+export function defineProject(files = [], options = {}) {
+  const opts = optionsOf(options, ['active', 'layout'], 'defineProject()');
+  let built = new ProjectBuilder({ project: '0.1', files: filesOf(files) });
+  if (Object.hasOwn(opts, 'active')) built = built.active(opts.active);
+  if (Object.hasOwn(opts, 'layout')) built = built.layout(opts.layout);
+  return built;
+}
+
+/** A public envelope supplied verbatim; the Studio parser remains authoritative. @param {any} document */
+export function from(document) { return new ProjectBuilder(document); }