@elaraai/e3-types 1.0.83 → 1.0.85

package/src/structure.spec.ts

@@ -0,0 +1,65 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+
+/**
+ * Keypaths: `parseKeypath` reads back what `pathToString` writes, whatever a
+ * field is named, with no structure to check it against; `parsePath` reads the
+ * same syntax and checks each field against a structure as it reads it.
+ */
+
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { IntegerType, equalFor, printFor, toEastTypeValue, variant } from '@elaraai/east';
+import { TreePathType, parseKeypath, parsePath, pathToString, type Structure, type TreePath } from './structure.js';
+
+const equalPath = equalFor(TreePathType);
+const printPath = printFor(TreePathType);
+
+describe('parseKeypath', () => {
+  it('reads back what pathToString writes, whatever a field is named', () => {
+    const names = ['inputs', 'my field', 'a.b', 'a/b', 'back`tick', 'back\\slash', 'café', '1st', '', '`'];
+    for (const name of names) {
+      const path: TreePath = [variant('field', 'inputs'), variant('field', name)];
+      const printed = pathToString(path);
+      if (name === '') {
+        // An empty field name prints as nothing a keypath can read.
+        assert.throws(() => parseKeypath(printed));
+        continue;
+      }
+      const read = parseKeypath(printed);
+      assert.ok(equalPath(read, path), `${JSON.stringify(name)}: ${printed} read back as ${printPath(read)}`);
+    }
+  });
+
+  it('reads the empty string as the root', () => {
+    assert.ok(equalPath(parseKeypath(''), []));
+  });
+
+  it('refuses a string that is not a keypath, naming where', () => {
+    assert.throws(() => parseKeypath('inputs.x'), { message: "parseKeypath: unexpected character at position 0: 'i'" });
+    assert.throws(() => parseKeypath('.inputs.'), { message: "parseKeypath: expected identifier after '.' at position 8" });
+    assert.throws(() => parseKeypath('.inputs!'), { message: "parseKeypath: unexpected character at position 7: '!'" });
+  });
+});
+
+describe('parsePath', () => {
+  const structure: Structure = variant('struct', new Map([
+    ['inputs', variant('struct', new Map([
+      ['sales', variant('value', { type: toEastTypeValue(IntegerType), writable: true })],
+    ]))],
+  ]));
+
+  it('reads a keypath, and the structure at it', () => {
+    const { path, structure: at } = parsePath('.inputs.sales', structure);
+    assert.ok(equalPath(path, [variant('field', 'inputs'), variant('field', 'sales')]));
+    assert.equal(at.type, 'value');
+  });
+
+  it('refuses a field the structure lacks before a malformed one after it, and a path into a dataset', () => {
+    assert.throws(() => parsePath('.nope!', structure), { message: "parsePath: field 'nope' not found at ''. Available: inputs" });
+    assert.throws(() => parsePath('.inputs!', structure), { message: "parsePath: unexpected character at position 7: '!'" });
+    assert.throws(() => parsePath('.inputs.sales.more', structure), { message: "parsePath: cannot descend into dataset at '.inputs.sales'" });
+  });
+});

package/src/structure.ts

@@ -181,10 +181,69 @@ export interface ParsePathResult {
  * ```
  */
 export function parsePath(pathStr: string, structure: Structure): ParsePathResult {
-  if (pathStr === '') return { path: [], structure };
-
   const segments: TreePath = [];
   let currentStructure = structure;
+
+  // Each field is checked as it is read, so a field the structure lacks is
+  // refused before a malformed one after it.
+  for (const fieldName of keypathFields(pathStr, 'parsePath')) {
+    if (currentStructure.type === 'value') {
+      throw new Error(`parsePath: cannot descend into dataset at '${pathToString(segments)}'`);
+    }
+
+    // currentStructure.type === 'struct' (only other option after 'value' check)
+    const fields = currentStructure.value;
+    const childStructure = fields.get(fieldName);
+    if (childStructure === undefined) {
+      const available = [...fields.keys()].map(k => printIdentifier(k)).join(', ');
+      throw new Error(`parsePath: field '${fieldName}' not found at '${pathToString(segments)}'. Available: ${available}`);
+    }
+    segments.push(variant('field', fieldName));
+    currentStructure = childStructure;
+  }
+
+  return { path: segments, structure: currentStructure };
+}
+
+/**
+ * Parses an East keypath string into a path, with no structure to check it
+ * against: the inverse of {@link pathToString}.
+ *
+ * @remarks
+ * The syntax is {@link parsePath}'s: `.field` for a simple identifier, and
+ * `` .`field` `` for one that needs quoting, with `` \` `` for a literal
+ * backtick and `\\` for a backslash. Whether the path names anything is the
+ * caller's to judge, as a status asked for named datasets leaves out a path
+ * the workspace does not hold.
+ *
+ * @param pathStr - A keypath string (e.g., ".inputs.sales", or ".inputs.`my field`")
+ * @returns The path; the root's, `[]`, for the empty string
+ *
+ * @throws {Error} When the string is not a keypath, such as one that does not
+ *   start with `.`
+ *
+ * @example
+ * ```ts
+ * parseKeypath('.inputs.sales');
+ * // [field('inputs'), field('sales')]
+ *
+ * parseKeypath(pathToString([variant('field', 'inputs'), variant('field', 'my field')]));
+ * // [field('inputs'), field('my field')]
+ * ```
+ */
+export function parseKeypath(pathStr: string): TreePath {
+  return [...keypathFields(pathStr, 'parseKeypath')].map((fieldName) => variant('field', fieldName));
+}
+
+/**
+ * Reads a keypath string's field names in order, refusing a malformed one when
+ * it reaches it.
+ *
+ * @param pathStr - The keypath string
+ * @param caller - The function a refusal names
+ * @internal
+ */
+function* keypathFields(pathStr: string, caller: string): Generator<string> {
   let pos = 0;
 
   while (pos < pathStr.length) {
@@ -221,29 +280,13 @@ export function parsePath(pathStr: string, structure: Structure): ParsePathResul
       }
 
       if (fieldName.length === 0) {
-        throw new Error(`parsePath: expected identifier after '.' at position ${pos}`);
-      }
-
-      // Validate against structure
-      if (currentStructure.type === 'value') {
-        throw new Error(`parsePath: cannot descend into dataset at '${pathToString(segments)}'`);
+        throw new Error(`${caller}: expected identifier after '.' at position ${pos}`);
       }
-
-      // currentStructure.type === 'struct' (only other option after 'value' check)
-      const fields = currentStructure.value;
-      const childStructure = fields.get(fieldName);
-      if (childStructure === undefined) {
-        const available = [...fields.keys()].map(k => printIdentifier(k)).join(', ');
-        throw new Error(`parsePath: field '${fieldName}' not found at '${pathToString(segments)}'. Available: ${available}`);
-      }
-      segments.push(variant('field', fieldName));
-      currentStructure = childStructure;
+      yield fieldName;
     } else {
-      throw new Error(`parsePath: unexpected character at position ${pos}: '${pathStr[pos]}'`);
+      throw new Error(`${caller}: unexpected character at position ${pos}: '${pathStr[pos]}'`);
     }
   }
-
-  return { path: segments, structure: currentStructure };
 }
 
 /**

package/src/task.spec.ts

@@ -9,10 +9,14 @@
 
 import { describe, it } from 'node:test';
 import assert from 'node:assert/strict';
-import { ArrayType, BlobType, IntegerType, OptionType, StringType, StructType, encodeBeast2For, none, some, variant } from '@elaraai/east';
+import { ArrayType, BlobType, IntegerType, OptionType, StringType, StructType, VariantType, encodeBeast2For, none, some, variant } from '@elaraai/east';
 import {
   TASK_OBJECT_KIND,
+  TaskBodyType,
+  TaskInputType,
   TaskObjectType,
+  TaskOutputType,
+  TaskRoleType,
   decodeTaskObject,
   type TaskObject,
 } from './task.js';
@@ -26,7 +30,7 @@ describe('TaskObjectType', () => {
   const base: TaskObject = {
     kind: TASK_OBJECT_KIND,
     body: variant('east', { program: 'a'.repeat(64) }),
-    runner: variant('east_node', { platforms: ['@elaraai/east-node-std'] }),
+    runner: variant('east_node', { platforms: ['@elaraai/east-node-std'], decode: variant('lazy', null) }),
     inputs: [{ path: sales, partition: none }],
     output: { path: totals, kind: variant('value', null) },
     role: variant('data', null),
@@ -49,6 +53,7 @@ describe('TaskObjectType', () => {
       },
       { ...base, output: { path: totals, kind: variant('fold', { zero: 'e'.repeat(64), combine: 'f'.repeat(64) }) } },
       { ...base, output: { path: totals, kind: variant('set', null) } },
+      { ...base, runner: variant('east_py', { platforms: ['east-py-std'], decode: variant('whole', null) }) },
       { ...base, role: variant('ui', { paths: [sales], functions: ['forecast'], records: ['plans'], pages: [rates] }) },
     ];
     const encode = encodeBeast2For(TaskObjectType);
@@ -71,12 +76,33 @@ describe('TaskObjectType', () => {
       output: totals,
       kind: none,
       metadata: none,
-      runner: variant('east_node', { platforms: [] }),
+      runner: variant('east_node', { platforms: [], decode: variant('lazy', null) }),
       environment: none,
     });
     assert.throws(() => decodeTaskObject(older), /exported by an older e3 SDK — re-export it with the current one/);
   });
 
+  it('refuses a task object whose runner predates its decode, saying to re-export the package', () => {
+    // A stock runner as a package exported before runners said how they read
+    // a program's inputs: its platforms alone.
+    const PreDecodeRunnerType = VariantType({
+      east_node: StructType({ platforms: ArrayType(StringType) }),
+      east_py: StructType({ platforms: ArrayType(StringType) }),
+      east_c: StructType({ platforms: ArrayType(StringType) }),
+      custom: StructType({ command: ArrayType(StringType) }),
+    });
+    const older = encodeBeast2For(StructType({
+      kind: StringType,
+      body: TaskBodyType,
+      runner: PreDecodeRunnerType,
+      inputs: ArrayType(TaskInputType),
+      output: TaskOutputType,
+      role: TaskRoleType,
+      environment: OptionType(StringType),
+    }))({ ...base, runner: variant('east_node', { platforms: ['@elaraai/east-node-std'] }) });
+    assert.throws(() => decodeTaskObject(older), /exported by an older e3 SDK — re-export it with the current one/);
+  });
+
   it('refuses an object of the task shape that carries another kind tag', () => {
     assert.throws(() => decodeTaskObject(encodeBeast2For(TaskObjectType)({ ...base, kind: '$plan' })), /its kind is '\$plan', not '\$task'/);
   });

package/src/task.ts

@@ -132,7 +132,7 @@ export type TaskRole = ValueTypeOf<typeof TaskRoleType>;
  * const task: TaskObject = {
  *   kind: TASK_OBJECT_KIND,
  *   body: variant('east', { program: '5e7a3b...' }),
- *   runner: variant('east_node', { platforms: ['@elaraai/east-node-std'] }),
+ *   runner: variant('east_node', { platforms: ['@elaraai/east-node-std'], decode: variant('lazy', null) }),
  *   inputs: [{ path: [variant('field', 'inputs'), variant('field', 'sales')], partition: none }],
  *   output: { path: [variant('field', 'tasks'), variant('field', 'totals'), variant('field', 'output')], kind: variant('value', null) },
  *   role: variant('data', null),