@jarenjs/linq 0.49.2 → 0.56.0

package/src/migration/steps.js

@@ -0,0 +1,248 @@
+//@ts-check
+/**
+ * @file The step spellings of a `$migration` 0.1 document
+ * (MIGRATION-FORMAT §2): each function writes one step as plain JSON in
+ * the member order the format's examples use, and refuses only what it
+ * cannot spell (`JL0101`) or what the runner's own structural check would
+ * refuse later and the pen can see now (`JL0101`, mirrored from the
+ * runner's `JD0023` rules: a `sql` step without text, a `derive` without
+ * columns, a `rebuild` without its rendered parts, an unknown kind). A
+ * transform's callback is captured through the JSLT pen's `body()` — the
+ * capture the format's `jslt` step runs — as one root rule; an
+ * assertion's predicate through the chain's recording proxy, rooted at
+ * `$it` inside the `$for` the format's own example writes.
+ */
+
+import { captureExpression } from '../expression.js';
+import { body } from '../jslt/body.js';
+import { describeValue, requireJson } from '../json-boundary.js';
+import { LinqBuildError } from '../errors.js';
+
+/** The kinds the runner accepts, in the artifact's order. */
+const STEP_KINDS = ['ddl', 'jslt', 'query', 'derive', 'sql', 'rebuild'];
+const EXPECTS = ['empty', 'ebv'];
+const NAME_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/** An assertion evaluates with no externals: `p.x` cannot appear. */
+const NO_PARAMS = new Set();
+
+/** A JSON value, copied: the document is a value of its own. @param {any} v */
+const copy = (v) => JSON.parse(JSON.stringify(v));
+
+/** @param {any} value */
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+/**
+ * A table name: an identifier, as the artifact's pattern admits.
+ * @param {any} name
+ * @param {string} what
+ * @returns {string}
+ */
+export function requireName(name, what) {
+  if (typeof name !== 'string' || !NAME_RE.test(name)) {
+    throw new LinqBuildError('JL0101',
+      `${what} names an entity or collection by identifier ('users'), got ${describeValue(name)}`);
+  }
+  return name;
+}
+
+/** @param {any} sql @param {string} what */
+function requireSql(sql, what) {
+  if (typeof sql !== 'string' || sql.trim() === '') {
+    throw new LinqBuildError('JL0101',
+      `${what} takes one rendered SQL statement as a non-empty string, got ${describeValue(sql)}`);
+  }
+  return sql;
+}
+
+/** @param {any} note @param {string} what */
+function readNote(note, what) {
+  if (note === undefined) return undefined;
+  if (typeof note !== 'string') {
+    throw new LinqBuildError('JL0101', `${what} note is a string, got ${describeValue(note)}`);
+  }
+  return note;
+}
+
+/** The externals proxy an assertion's predicate sees: nothing. */
+const NO_EXTERNALS = new Proxy(Object.freeze({}), {
+  get(_target, prop) {
+    if (typeof prop === 'symbol') return undefined;
+    throw new LinqBuildError('JL0104',
+      `an assert() predicate cannot bind '${String(prop)}' — a query assertion runs over the `
+      + "table's rows with no externals (MIGRATION-FORMAT §2)");
+  },
+});
+
+/**
+ * `{ kind: 'ddl', sql, note? }` — one rendered DDL statement.
+ * @param {string} sql @param {string} [note]
+ */
+export function ddlStep(sql, note = undefined) {
+  const out = { kind: 'ddl', sql: requireSql(sql, 'ddl()') };
+  const n = readNote(note, 'ddl()');
+  if (n !== undefined) out.note = n;
+  return out;
+}
+
+/**
+ * `{ kind: 'sql', sql, note? }` — one DATA statement spelled directly
+ * (§9.4); a dry run always prints it with its note.
+ * @param {string} sql @param {string} [note]
+ */
+export function sqlStep(sql, note = undefined) {
+  const out = { kind: 'sql', sql: requireSql(sql, 'sql()') };
+  const n = readNote(note, 'sql()');
+  if (n !== undefined) out.note = n;
+  return out;
+}
+
+/**
+ * `{ kind: 'jslt', collection, stylesheet }` — the transform of one
+ * table's rows. The spelling is a callback (one root rule, `match: '$'`,
+ * its body captured over the whole row with `root`/`path` as the
+ * externals the engine binds), a `stylesheet(…)` envelope (its rules —
+ * the step carries the rules array, so a disposition or a mode table
+ * has no place in it, `JL0102`), or a rules array verbatim.
+ * @param {string} name
+ * @param {any} spelling
+ */
+export function transformStep(name, spelling) {
+  requireName(name, 'transform()');
+  let stylesheet;
+  if (typeof spelling === 'function') {
+    stylesheet = [{ match: '$', body: body(spelling) }];
+  }
+  else if (Array.isArray(spelling)) {
+    stylesheet = copy(requireJson(spelling, 'transform() rules'));
+  }
+  else if (isPlainObject(spelling) && spelling.$jslt === '0.1') {
+    for (const key of Object.keys(spelling)) {
+      if (key !== '$jslt' && key !== 'rules') {
+        throw new LinqBuildError('JL0102',
+          `transform() takes a stylesheet's rules — a jslt step carries the rules array `
+          + `(MIGRATION-FORMAT §2), so '${key}' has no place in it; write the rules without it`,
+          `/${key}`);
+      }
+    }
+    stylesheet = copy(requireJson(spelling.rules, 'transform() stylesheet rules'));
+    if (!Array.isArray(stylesheet)) {
+      throw new LinqBuildError('JL0101',
+        `transform() stylesheet rules are an array, got ${describeValue(spelling.rules)}`, '/rules');
+    }
+  }
+  else {
+    throw new LinqBuildError('JL0101',
+      'transform() takes a callback (row, x) => …, a stylesheet(…) document or a rules array, '
+      + `got ${describeValue(spelling)}`);
+  }
+  return { kind: 'jslt', collection: name, stylesheet };
+}
+
+/**
+ * `{ kind: 'query', collection, assert, expect? }` — an assertion over
+ * the table's rows. A callback names a predicate over one row, spelled
+ * as the format's own `$for` over the rows: with `expect: 'empty'` (the
+ * default, absent from the document) no row may satisfy it — the
+ * predicate names the VIOLATION; with `expect: 'ebv'` the matching rows
+ * are the witness. A document is taken verbatim.
+ * @param {string} name
+ * @param {any} spelling
+ * @param {{ expect?: 'empty' | 'ebv' }} [options]
+ */
+export function assertStep(name, spelling, options = undefined) {
+  requireName(name, 'assert()');
+  let expect;
+  if (options !== undefined) {
+    if (!isPlainObject(options)) {
+      throw new LinqBuildError('JL0101', `assert() options are { expect? }, got ${describeValue(options)}`);
+    }
+    for (const key of Object.keys(options)) {
+      if (key !== 'expect') throw new LinqBuildError('JL0101', `assert() does not take '${key}'`);
+    }
+    if (options.expect !== undefined) {
+      if (!EXPECTS.includes(options.expect)) {
+        throw new LinqBuildError('JL0101',
+          `assert() expect is 'empty' or 'ebv' (MIGRATION-FORMAT §2), got ${describeValue(options.expect)}`,
+          '/expect');
+      }
+      expect = options.expect;
+    }
+  }
+  let query;
+  if (typeof spelling === 'function') {
+    const predicate = captureExpression((it) => spelling(it, NO_EXTERNALS), ['it'], NO_PARAMS);
+    query = { $for: { it: '$[*]' }, $where: predicate, $return: '$it' };
+  }
+  else if (spelling !== undefined) {
+    query = copy(requireJson(spelling, 'assert() query'));
+  }
+  else {
+    throw new LinqBuildError('JL0101',
+      'assert() takes a predicate (row) => … or a query document over the rows');
+  }
+  const out = { kind: 'query', collection: name, assert: query };
+  if (expect === 'ebv') out.expect = 'ebv';
+  return out;
+}
+
+/**
+ * `{ kind: 'derive', collection, columns }` — recompute stored derived
+ * columns (§2.1); the columns ride verbatim, a non-empty array.
+ * @param {string} name
+ * @param {any} columns
+ */
+export function deriveStep(name, columns) {
+  requireName(name, 'derive()');
+  if (!Array.isArray(columns) || columns.length === 0) {
+    throw new LinqBuildError('JL0101',
+      `derive() takes a non-empty array of derived-column records ({ name, derive, segments }), got ${describeValue(columns)}`);
+  }
+  return { kind: 'derive', collection: name, columns: copy(requireJson(columns, 'derive() columns')) };
+}
+
+/**
+ * Any planner-emitted step, verbatim — the escape that keeps `rebuild`
+ * authorable without the pen re-implementing §10. The structural rules
+ * are the runner's own (`JD0023`), seen here: a recognised kind and the
+ * members that kind requires. A `draft` flag rides untouched.
+ * @param {any} step
+ */
+export function rawStep(step) {
+  const raw = copy(requireJson(step, 'step()'));
+  if (!isPlainObject(raw) || !STEP_KINDS.includes(raw.kind)) {
+    throw new LinqBuildError('JL0101',
+      `step() takes a migration step with a recognised kind (${STEP_KINDS.join(', ')}), got `
+      + `${isPlainObject(raw) ? `kind ${describeValue(raw.kind)}` : describeValue(step)}`);
+  }
+  const need = (member, ok) => {
+    if (!ok) {
+      throw new LinqBuildError('JL0101',
+        `step() '${raw.kind}' needs '${member}' (MIGRATION-FORMAT §2)`, `/${member}`);
+    }
+  };
+  switch (raw.kind) {
+    case 'ddl': case 'sql':
+      need('sql', typeof raw.sql === 'string' && raw.sql !== '');
+      break;
+    case 'jslt':
+      need('collection', typeof raw.collection === 'string');
+      need('stylesheet', Array.isArray(raw.stylesheet));
+      break;
+    case 'query':
+      need('collection', typeof raw.collection === 'string');
+      need('assert', raw.assert !== undefined);
+      break;
+    case 'derive':
+      need('collection', typeof raw.collection === 'string');
+      need('columns', Array.isArray(raw.columns) && raw.columns.length > 0);
+      break;
+    default: // rebuild
+      need('table', typeof raw.table === 'string');
+      need('create', Array.isArray(raw.create) && raw.create.length > 0);
+      need('copy', typeof raw.copy === 'string');
+      need('indexes', Array.isArray(raw.indexes));
+  }
+  return raw;
+}

package/src/model/collection.js

@@ -0,0 +1,171 @@
+//@ts-check
+/**
+ * @file Collections and their indexes: `collection(builder, { key,
+ * indexes })` and `index(path, options)`. A key is an RFC 6901 pointer
+ * or a captured member path (`(d) => d.id` → `/id`); an index path is a
+ * captured lambda (`(p) => p.embedding` → `$.embedding`), a composite
+ * array of them, or a JSONPath string; the options ride verbatim, the
+ * store's model walk being the judge of `derive`/`precision`/`dims`/
+ * `physical`. The default index name is `by_<segments>`.
+ */
+
+import { LinqBuildError } from '../errors.js';
+import { isSchemaBuilder } from '../schema/brand.js';
+import { requireJson, requireName } from '../schema/builders.js';
+import { captureQuery } from '../schema/check.js';
+import { DOCUMENT_SCOPE, refuseStrandedRename } from './entity.js';
+
+/** The index options the grammar names beside `name` and `path`. */
+const INDEX_OPTIONS = new Set(['name', 'unique', 'derive', 'precision', 'dims', 'physical']);
+
+/** The marker a collection spec carries so `defineModel` can tell it apart. */
+export const COLLECTION = Symbol.for('@jarenjs/linq/model-collection');
+
+/** A shorthand member path (`$.a.b`), as the capture spells one. */
+const MEMBER_PATH = /^\$(\.[A-Za-z_][A-Za-z0-9_]*)+$/;
+
+/**
+ * Capture one path lambda into a JSONPath string.
+ * @param {(doc: any) => any} lambda
+ * @param {string} what
+ * @returns {string}
+ */
+function capturePath(lambda, what) {
+  let captured;
+  try {
+    captured = captureQuery(what, [], lambda, { advice: () => DOCUMENT_SCOPE });
+  }
+  catch (error) {
+    // a member named like a surface method (`at`, `get`, …) reads as the
+    // method, so the lambda answers a function; name the escape
+    if (error instanceof LinqBuildError && error.code === 'JL0005' && /function/.test(error.message)) {
+      throw new LinqBuildError('JL0102',
+        `${what} answered a function, not a path — a member named like a surface method `
+        + "(`at`, `get`, `all`, …) is read with get('name'): (d) => d.get('at')", undefined, error);
+    }
+    throw error;
+  }
+  if (typeof captured !== 'string' || captured.charCodeAt(0) !== 0x24) {
+    throw new LinqBuildError('JL0102',
+      `${what} takes a member path ((d) => d.member); an operator result is not a path`);
+  }
+  return captured;
+}
+
+/**
+ * A path argument: a captured lambda, a JSONPath string, or an array of
+ * either (a composite).
+ * @param {any} path
+ * @param {string} what
+ * @returns {string | string[]}
+ */
+function indexPath(path, what) {
+  if (typeof path === 'function') return capturePath(path, what);
+  if (typeof path === 'string' && path.length > 0) return path;
+  if (Array.isArray(path) && path.length > 0) {
+    return path.map((one, i) => {
+      if (typeof one === 'function') return capturePath(one, `${what}[${i}]`);
+      if (typeof one === 'string' && one.length > 0) return one;
+      throw new LinqBuildError('JL0101', `${what}[${i}] is neither a path lambda nor a JSONPath string`);
+    });
+  }
+  throw new LinqBuildError('JL0101',
+    `${what} takes a path lambda, a JSONPath string, or a non-empty array of them`);
+}
+
+/** The default name: `by_` + the member segments, identifier-safe. @param {string | string[]} path */
+function defaultName(path) {
+  const segments = (Array.isArray(path) ? path : [path]).flatMap((one) =>
+    one.replace(/^\$\.?/, '').split(/[.[\]'"]+/).filter((s) => s !== '' && s !== '*'));
+  return 'by_' + segments.map((s) => s.replace(/[^A-Za-z0-9_]/g, '_')).join('_');
+}
+
+/**
+ * One index declaration.
+ * @param {((doc: any) => any) | string | readonly (((doc: any) => any) | string)[]} path
+ * @param {{ name?: string, unique?: boolean, derive?: 'geohash' | 'bbox' | 'vector',
+ *   precision?: number, dims?: number, physical?: 'columns' | 'rtree' }} [options]
+ * @returns {any} the frozen index document
+ */
+export function index(path, options = {}) {
+  if (options === null || typeof options !== 'object' || Array.isArray(options)) {
+    throw new LinqBuildError('JL0101', 'index() takes an options object');
+  }
+  for (const key of Object.keys(options)) {
+    if (!INDEX_OPTIONS.has(key)) {
+      throw new LinqBuildError('JL0101',
+        `index() does not take '${key}' — the options are name, unique, derive, precision, dims, physical`);
+    }
+  }
+  const resolved = indexPath(path, 'index()');
+  const out = {
+    name: options.name === undefined ? defaultName(resolved) : requireName(options.name, 'index() name'),
+    path: resolved,
+  };
+  for (const key of ['unique', 'derive', 'precision', 'dims', 'physical']) {
+    if (options[key] !== undefined) out[key] = requireJson(options[key], `index() ${key}`);
+  }
+  return Object.freeze(out);
+}
+
+/**
+ * The key declaration: a pointer string, a captured member path, or
+ * `null` (the store allocates; `identity` says how).
+ * @param {any} key
+ * @returns {string | null}
+ */
+function keyPointer(key) {
+  if (key === null) return null;
+  if (typeof key === 'function') {
+    const path = capturePath(key, 'collection() key');
+    if (!MEMBER_PATH.test(path)) {
+      throw new LinqBuildError('JL0102',
+        `collection() key must select members by name ((d) => d.id), got the path ${path}`);
+    }
+    return '/' + path.slice(2).split('.').map((s) => s.replaceAll('~', '~0').replaceAll('/', '~1')).join('/');
+  }
+  if (typeof key === 'string' && key.startsWith('/')) return key;
+  throw new LinqBuildError('JL0101',
+    'collection() key is an RFC 6901 pointer, a member path lambda, or null');
+}
+
+/**
+ * One collection declaration for `defineModel`.
+ * @param {any} builder - the document schema
+ * @param {{ key?: string | ((doc: any) => any) | null, identity?: 'caller' | 'uuid' | 'integer',
+ *   indexes?: readonly any[], renamedFrom?: string }} [options]
+ * @returns {any} the frozen collection document
+ */
+export function collection(builder, options = {}) {
+  if (!isSchemaBuilder(builder)) {
+    throw new LinqBuildError('JL0101', 'collection() takes a schema builder as its document schema');
+  }
+  refuseStrandedRename(builder, 'collection()');
+  if (options === null || typeof options !== 'object' || Array.isArray(options)) {
+    throw new LinqBuildError('JL0101', 'collection() takes an options object');
+  }
+  for (const key of Object.keys(options)) {
+    if (!['key', 'identity', 'indexes', 'renamedFrom'].includes(key)) {
+      throw new LinqBuildError('JL0101',
+        `collection() does not take '${key}' — the options are key, identity, indexes, renamedFrom`);
+    }
+  }
+  const out = { schema: builder.schema };
+  if (options.key !== undefined) out.key = keyPointer(options.key);
+  if (options.identity !== undefined) out.identity = requireJson(options.identity, 'collection() identity');
+  if (options.indexes !== undefined) {
+    if (!Array.isArray(options.indexes)) {
+      throw new LinqBuildError('JL0101', 'collection() indexes is an array of index() entries');
+    }
+    out.indexes = options.indexes.map((one, i) => {
+      if (one === null || typeof one !== 'object' || typeof one.name !== 'string') {
+        throw new LinqBuildError('JL0101', `collection() indexes[${i}] is not an index() entry`);
+      }
+      return requireJson(one, `collection() indexes[${i}]`);
+    });
+  }
+  const renamed = options.renamedFrom ?? builder.state.renamedFrom;
+  if (renamed !== undefined) out['x-rename'] = requireName(renamed, 'collection() renamedFrom');
+  Object.defineProperty(out, COLLECTION, { value: true, enumerable: false });
+  return Object.freeze(out);
+}

package/src/model/define.js

@@ -0,0 +1,125 @@
+//@ts-check
+/**
+ * @file `defineModel({ entities, collections })` — one `$model` 0.1
+ * document, deep-frozen, that `openStore` accepts unchanged. The pen
+ * refuses here only what it can see and the store's model walk would
+ * refuse anyway: a relation whose target is not a declared entity, a
+ * store-allocated default on a composite key, a collection spec where
+ * an entity was expected, and a `renamedFrom()` hint on a member, which
+ * the document has no place for. Inverse agreement, foreign-key types
+ * and the rest stay the engine's (`JD00xx`), never re-implemented.
+ */
+
+import { deepFreeze, setObjectMember } from '@jarenjs/core/object';
+
+import { LinqBuildError } from '../errors.js';
+import { requireNameMap } from '../json-boundary.js';
+import { isSchemaBuilder } from '../schema/brand.js';
+import { COLLECTION } from './collection.js';
+import { refuseStrandedRename } from './entity.js';
+
+const NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+/** @param {any} value @param {string} what @returns {Record<string, any>} */
+function requireMap(value, what) {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+    throw new LinqBuildError('JL0101', `defineModel() ${what} is a plain object of declarations`);
+  }
+  requireNameMap(value, `defineModel() ${what}`, `/${what}`);
+  for (const name of Object.keys(value)) {
+    if (!NAME.test(name)) {
+      throw new LinqBuildError('JL0101',
+        `defineModel() ${what} names are identifiers, got '${name}'`, `/${what}`);
+    }
+  }
+  return value;
+}
+
+/**
+ * The `x-entity` blocks an entity declares, by member, read from the
+ * builder before its document is assembled.
+ * @param {any} builder
+ * @returns {[string, any][]}
+ */
+function entityBlocks(builder) {
+  const st = builder.state;
+  if (st.kind !== 'object') return [];
+  return st.props.map(([name, member]) => [name, member.annotation('x-entity') ?? {}]);
+}
+
+/**
+ * Build the model document.
+ * @param {{ entities?: Record<string, any>, collections?: Record<string, any> }} spec
+ * @returns {any} the deep-frozen `$model` 0.1 document
+ */
+export function defineModel(spec) {
+  if (spec === null || typeof spec !== 'object' || Array.isArray(spec)) {
+    throw new LinqBuildError('JL0101', 'defineModel() takes { entities?, collections? }');
+  }
+  for (const key of Object.keys(spec)) {
+    if (key !== 'entities' && key !== 'collections') {
+      throw new LinqBuildError('JL0101', `defineModel() does not take '${key}'`);
+    }
+  }
+  if (spec.entities === undefined && spec.collections === undefined) {
+    throw new LinqBuildError('JL0101', 'defineModel() needs entities, collections, or both');
+  }
+  const out = { $model: '0.1' };
+
+  if (spec.collections !== undefined) {
+    const collections = requireMap(spec.collections, 'collections');
+    const emitted = {};
+    for (const name of Object.keys(collections)) {
+      const declared = collections[name];
+      if (declared === null || typeof declared !== 'object' || declared[COLLECTION] !== true) {
+        throw new LinqBuildError('JL0101',
+          `collections.${name} is not a collection() declaration`, `/collections/${name}`);
+      }
+      setObjectMember(emitted, name, declared);
+    }
+    out.collections = emitted;
+  }
+
+  if (spec.entities !== undefined) {
+    const entities = requireMap(spec.entities, 'entities');
+    const names = Object.keys(entities);
+    const emitted = {};
+    for (const name of names) {
+      const at = `/entities/${name}`;
+      const builder = entities[name];
+      if (builder !== null && typeof builder === 'object' && builder[COLLECTION] === true) {
+        throw new LinqBuildError('JL0102',
+          `entities.${name} is a collection() declaration — an entity has no key pointer and no `
+          + 'indexes option: its key is key() on a member and its indexes are unique()/index() '
+          + 'per member (the vocabulary has no composite or derived entity index)', at);
+      }
+      if (!isSchemaBuilder(builder)) {
+        throw new LinqBuildError('JL0101', `entities.${name} is not a schema builder`, at);
+      }
+      refuseStrandedRename(builder, `entities.${name}`, at);
+      const blocks = entityBlocks(builder);
+      const keys = blocks.filter(([, block]) => block.key === true);
+      for (const [member, block] of blocks) {
+        const memberAt = `${at}/schema/properties/${member}/x-entity`;
+        const relation = block.relation;
+        if (relation !== undefined && !names.includes(relation.to)) {
+          throw new LinqBuildError('JL0102',
+            `relation target '${relation.to}' on ${name}.${member} is not a declared entity — `
+            + `the model declares ${names.map((n) => `'${n}'`).join(', ')}`,
+            `${memberAt}/relation/to`);
+        }
+        if ((block.default === 'auto' || block.default === 'uuid') && keys.length > 1) {
+          throw new LinqBuildError('JL0102',
+            `identity('${block.default}') on ${name}.${member}: a store-allocated key is a SINGLE `
+            + `key, and ${name} declares a composite one (${keys.map(([k]) => k).join(', ')})`,
+            `${memberAt}/default`);
+        }
+      }
+      const entity = { schema: builder.schema };
+      if (builder.state.renamedFrom !== undefined) entity['x-rename'] = builder.state.renamedFrom;
+      setObjectMember(emitted, name, entity);
+    }
+    out.entities = emitted;
+  }
+  return deepFreeze(out);
+}