@elaraai/e3 1.0.79 → 1.0.81

package/dist/src/record-index.spec.js

@@ -0,0 +1,160 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+/**
+ * `e3.recordIndex` — the declaration and the program built from it.
+ *
+ * Every guard here is a definition-time error: an index that is wrong is worse
+ * than no index, because the view it serves is quietly wrong rather than
+ * missing, so the refusals happen at the developer's desk.
+ *
+ * The build program is what actually runs, and its two load-bearing properties
+ * are asserted by running it: each row's entries come out as the row is read,
+ * keyed `{ik, k}` — index key first — for the runner's RunSorter to sort, and a
+ * multi-valued index emits one entry per element of the returned set, so an
+ * empty set is a row the index does not carry.
+ */
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { DictType, East, IntegerType, NullType, SetType, SortedMap, StringType, StructType, compareFor, printType, } from '@elaraai/east';
+import { record } from './record.js';
+import { recordIndex } from './record-index.js';
+import { indexBuildProgram } from './record-programs.js';
+import { package_ } from './package.js';
+const RowType = StructType({ status: StringType, due: IntegerType, title: StringType, tags: SetType(StringType) });
+const StatusKeyType = StructType({ status: StringType, due: IntegerType });
+const PlansType = DictType(StringType, RowType);
+/** The `by_status` declaration: one key per row, with a covering projection. */
+const statusKey = East.function([StringType, RowType], StatusKeyType, ($, _k, v) => ({ status: v.status, due: v.due }));
+const titleOf = East.function([StringType, RowType], StringType, ($, _k, v) => v.title);
+/** The `by_tag` declaration: many keys per row. */
+const tagKeys = East.function([StringType, RowType], SetType(StringType), ($, _k, v) => v.tags);
+const plans = () => record('plans', PlansType, new Map());
+/** The `[entry, projection]` pairs a build program emits for `rows`. */
+function emitted(recordType, def, rows) {
+    const out = [];
+    const run = indexBuildProgram(recordType, def).compile([]);
+    run(rows, (entry, value) => {
+        out.push([entry, value]);
+        return null;
+    });
+    return out;
+}
+const rows = new SortedMap([
+    ['p1', { status: 'late', due: 3n, title: 'One', tags: new Set(['a', 'b']) }],
+    ['p2', { status: 'ok', due: 1n, title: 'Two', tags: new Set(['b']) }],
+    ['p3', { status: 'late', due: 2n, title: 'Three', tags: new Set() }],
+], compareFor(StringType));
+describe('recordIndex — the declaration', () => {
+    // The typed bindings below are half of each test: they compile only when the
+    // declaration carries the exact key and projection types, which are what
+    // type a window read through the index — and so every component rendering
+    // one. An erased EastType is assignable to none of them.
+    it('reads the index key and the projection off the declared functions', () => {
+        const index = recordIndex('by_status', plans(), { key: statusKey, value: titleOf });
+        const keyType = index.keyType;
+        const valueType = index.valueType;
+        assert.equal(index.kind, 'recordIndex');
+        assert.equal(index.name, 'by_status');
+        assert.equal(index.multi, false);
+        assert.equal(printType(keyType), printType(StatusKeyType));
+        assert.equal(printType(valueType), printType(StringType));
+    });
+    it('unwraps the element type of a multi-valued index, and carries no value by default', () => {
+        const index = recordIndex('by_tag', plans(), { keys: tagKeys });
+        const keyType = index.keyType;
+        const valueType = index.valueType;
+        assert.equal(index.multi, true);
+        assert.equal(printType(keyType), printType(StringType), 'the SET is unwrapped to its element');
+        assert.equal(printType(valueType), printType(NullType));
+    });
+    it('is collected onto its record by the package', () => {
+        const rec = plans();
+        const pkg = package_('planning', '1.0.0', rec, recordIndex('by_status', rec, { key: statusKey }), recordIndex('by_tag', rec, { keys: tagKeys }));
+        assert.deepEqual(Object.keys(pkg.records.plans.indexes).sort(), ['by_status', 'by_tag']);
+    });
+    describe('refuses, at definition time', () => {
+        it('the reserved name, a non-identifier name, and an empty one', () => {
+            assert.throws(() => recordIndex('primary', plans(), { key: statusKey }), /cannot be named 'primary'/);
+            assert.throws(() => recordIndex('by status', plans(), { key: statusKey }), /must be an identifier/);
+            assert.throws(() => recordIndex('', plans(), { key: statusKey }), /non-empty name/);
+        });
+        it('a name declared twice on the record', () => {
+            const rec = plans();
+            const first = recordIndex('by_status', rec, { key: statusKey });
+            const second = recordIndex('by_status', rec, { key: statusKey, value: titleOf });
+            // A record keeps one index per name. With two it would keep whichever
+            // came last, and a page through `by_status` would read the other one.
+            assert.throws(() => package_('planning', '1.0.0', rec, first, second), /record 'plans' declares two indexes named 'by_status'/);
+            // One declaration passed twice is one index.
+            assert.deepEqual(Object.keys(package_('planning', '1.0.0', rec, first, first).records.plans.indexes), ['by_status']);
+            // An assembled record carries its indexes, so the name is refused at once.
+            const assembled = package_('planning', '1.0.0', rec, first).records.plans;
+            assert.throws(() => recordIndex('by_status', assembled, { key: statusKey }), /already declared/);
+        });
+        it('both or neither of key and keys', () => {
+            assert.throws(() => recordIndex('both', plans(), { key: statusKey, keys: tagKeys }), /exactly one of 'key'/);
+            assert.throws(() => recordIndex('neither', plans(), {}), /exactly one of 'key'/);
+        });
+        it('a keys function that does not return a Set', () => {
+            assert.throws(() => recordIndex('flat', plans(), { keys: statusKey }), /must return a Set of index keys/);
+        });
+        it('a function whose parameters are not the record\'s entry', () => {
+            assert.throws(() => recordIndex('wrong', plans(), { key: East.function([IntegerType], StringType, ($, _x) => 'only one parameter') }), /must take the record's entry/);
+            assert.throws(() => recordIndex('wrong_value', plans(), {
+                key: statusKey,
+                value: East.function([StringType], StringType, ($, k) => k),
+            }), /'value' projection must take the record's entry/);
+        });
+        it('a record that is not a Dict — there is no entry to index', () => {
+            const flags = record('flags', SetType(StringType), new Set());
+            assert.throws(() => recordIndex('on_set', flags, { key: statusKey }), /indexes a Dict record/);
+        });
+        it('an async function, and one that reaches a platform function', () => {
+            assert.throws(
+            // Only a dynamic or cast caller reaches this — the typed surface
+            // refuses an async function — but a wrong index is a quietly wrong
+            // view, so the guard is a runtime one too.
+            () => recordIndex('async', plans(), {
+                key: East.asyncFunction([StringType, RowType], StringType, ($, k, _v) => k),
+            }), /must be a synchronous East function/);
+            // A synchronous platform call is an ordinary function IR, so only the
+            // walk over the body finds it — in the key function and the projection
+            // alike.
+            assert.throws(() => recordIndex('clock', plans(), {
+                key: East.function([StringType, RowType], IntegerType, ($, _k, v) => v.due.add(East.platform('time_now', [], IntegerType)())),
+            }), /'key' function must not call platform functions \(found 'time_now'\)/);
+            assert.throws(() => recordIndex('clock_value', plans(), {
+                key: statusKey,
+                value: East.function([StringType, RowType], IntegerType, ($, _k, _v) => East.platform('time_now', [], IntegerType)()),
+            }), /'value' projection must not call platform functions \(found 'time_now'\)/);
+        });
+    });
+});
+describe('recordIndex — the build program', () => {
+    it('emits each row\'s entry as it reads the row, index key first', () => {
+        const out = emitted(PlansType, recordIndex('by_status', plans(), { key: statusKey, value: titleOf }), rows);
+        assert.deepEqual(out, [
+            [{ ik: { status: 'late', due: 3n }, k: 'p1' }, 'One'],
+            [{ ik: { status: 'ok', due: 1n }, k: 'p2' }, 'Two'],
+            [{ ik: { status: 'late', due: 2n }, k: 'p3' }, 'Three'],
+        ]);
+    });
+    it('emits one entry per element of a multi-valued key, and none for an empty set', () => {
+        const out = emitted(PlansType, recordIndex('by_tag', plans(), { keys: tagKeys }), rows);
+        assert.deepEqual(out, [
+            [{ ik: 'a', k: 'p1' }, null],
+            [{ ik: 'b', k: 'p1' }, null],
+            [{ ik: 'b', k: 'p2' }, null],
+        ]);
+    });
+    it('carries Null where an index declares no projection', () => {
+        const out = emitted(PlansType, recordIndex('by_status', plans(), { key: statusKey }), rows);
+        assert.deepEqual(out.map(([, value]) => value), [null, null, null]);
+    });
+    it('emits nothing for an empty record', () => {
+        assert.deepEqual(emitted(PlansType, recordIndex('by_status', plans(), { key: statusKey }), new Map()), []);
+    });
+});
+//# sourceMappingURL=record-index.spec.js.map

package/dist/src/record-index.spec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"record-index.spec.js","sourceRoot":"","sources":["../../src/record-index.spec.ts"],"names":[],"mappings":"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"}

package/dist/src/record-programs.d.ts

@@ -0,0 +1,128 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+/**
+ * The East programs a record's declarations generate.
+ *
+ * An author declares what an index keys on, how a mutation writes and how a
+ * migration changes a row; what actually runs is a program built from those
+ * declarations — an ordinary East function assembled at export time from the
+ * author's own expressions, as a stream task's output kind builds its merge
+ * function. It is linked and
+ * encoded like any other body, runs on the runner the author chose, and is
+ * what keeps e3 out of the business of evaluating user East: the engine runs a
+ * program and applies what it emits.
+ *
+ * @packageDocumentation
+ */
+import { type EastIR, type EastType } from '@elaraai/east';
+import { type DeltaTarget } from '@elaraai/e3-types';
+import type { MigrationDef, MutationDef, RecordDef, RecordIndexDef } from './types.js';
+/**
+ * The entry key an index collection sorts under: `{ik, k}`.
+ *
+ * @remarks
+ * `ik` first, so every entry with one index key is a contiguous run — ordered
+ * by primary key inside it — and a range of index keys is one contiguous run
+ * too. Struct keys compare field by field in declaration order, which is what
+ * makes that true rather than merely intended.
+ *
+ * @param keyType - the record's primary key type
+ * @param indexKeyType - the index key
+ * @returns the entry key type
+ */
+export declare function indexEntryKeyType(keyType: EastType, indexKeyType: EastType): EastType;
+/**
+ * The build program of an index: `(piece, emit) => Null`.
+ *
+ * @remarks
+ * Called with a piece of the primary — a whole small record, or one piece of a
+ * large one — it emits each row's index entries as it reads the row. Index
+ * order is not primary order, and need not be: the runner writes a `dict`
+ * output through its RunSorter, which sorts what it is given, so the program
+ * holds no more than the row in hand.
+ *
+ * The author's key and value functions are bound as function values and
+ * CALLED, never spliced into the loop: a spliced expression tree would be
+ * re-evaluated per reference and could capture the wrong bindings.
+ *
+ * @param recordType - the record's state type, `Dict<K, V>`
+ * @param def - the index declaration
+ * @returns the program's IR bundle
+ */
+export declare function indexBuildProgram(recordType: EastType, def: RecordIndexDef): EastIR<any, any>;
+/**
+ * The program a `rows` or `rekey` migration runs over each piece of a record's
+ * state: `(piece, emit) => Null`.
+ *
+ * @remarks
+ * It calls the author's function on each row, or element, as it reads it, and
+ * emits what the function returns: a `rows` step under the row's own key, or
+ * in order over an Array; a `rekey` step under the key the function returns,
+ * or, over a Set, as the element it returns. The runner writes a `dict` or
+ * `set` output through its RunSorter, which sorts what it is given, and an
+ * `array` output in the order emitted, so the program holds no more than the
+ * row in hand.
+ *
+ * The author's function is bound as a function value and CALLED, never
+ * spliced: a spliced expression tree would be re-evaluated per reference and
+ * could capture the wrong bindings.
+ *
+ * @param def - the migration, a `rows` or `rekey` step
+ * @returns the program's IR bundle
+ * @throws {Error} When the step is a `value` step, whose own function runs.
+ */
+export declare function migrationProgram(def: MigrationDef): EastIR<any, any>;
+/**
+ * The delta's targets for a record: its own collection, then each index.
+ *
+ * @remarks
+ * The names become the delta's variant cases, which is why `primary` is a
+ * reserved index name. Returned in the order the cases compare in — variant
+ * values order by case NAME — which is the order the delta holds their ops in.
+ *
+ * @param recordType - the record's state type, a Dict or a Set
+ * @param indexes - the record's index declarations
+ * @returns the targets, in canonical case order
+ */
+export declare function deltaTargets(recordType: EastType, indexes: readonly RecordIndexDef[]): DeltaTarget[];
+/** Whether a record's own collection has a delta at all: one addressed by key,
+ *  which is what lets a commit rebuild only the segments it touched. An Array
+ *  record's patch is positional, and a scalar's is a replace. */
+export declare function hasKeyedDelta(recordType: EastType): boolean;
+/**
+ * The program every write form runs: `(State, …Args | Patch, Emit) => Null`.
+ *
+ * @remarks
+ * One program, three forms, one output — the mutation delta, emitted entry by
+ * entry as it is computed, in any order: the runner writes a `dict` output
+ * through its RunSorter, which sorts it. e3 stores the delta as segments and
+ * applies it one target segment at a time; it never evaluates the author's
+ * East itself, which is what keeps one rule for where user code runs and gives
+ * the three runtimes something to agree on byte for byte.
+ *
+ * The three forms differ only in how the per-key ops are reached — a diff of
+ * the reducer's result, the folded writes of an `edit` body, or the client's
+ * own patch — after which the tail is shared: for each touched key, emit its
+ * op, then resolve the old and new row and ask each index what its entry was
+ * and what it becomes.
+ *
+ * A write the state moved under — a patch whose `before` the record no longer
+ * holds, an update of a row that no longer matches, a delete or update of a
+ * key the record does not hold — is emitted as a {@link DELTA_CONFLICT} entry
+ * naming it, which sorts first, rather than failing the program: a caller
+ * resubmits a conflict and gives up on a failure.
+ *
+ * The author's functions are bound as function values and CALLED, never
+ * spliced: a spliced tree would be re-evaluated per reference and could
+ * capture the wrong bindings.
+ *
+ * @param rec - the record, carrying its indexes
+ * @param mut - the mutation declaration
+ * @returns the program's IR bundle
+ * @throws {Error} When the record's collection has no keyed delta, or an
+ *   `edit` / `patch` mutation has no body where one is required.
+ */
+export declare function buildMutationProgram(rec: RecordDef, mut: MutationDef): EastIR<any, any>;
+//# sourceMappingURL=record-programs.d.ts.map

package/dist/src/record-programs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"record-programs.d.ts","sourceRoot":"","sources":["../../src/record-programs.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAaL,KAAK,MAAM,EACX,KAAK,QAAQ,EACd,MAAM,eAAe,CAAC;AACvB,OAAO,EAC6E,KAAK,WAAW,EACnG,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEvF;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,QAAQ,GAAG,QAAQ,CAErF;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,QAAQ,EAAE,GAAG,EAAE,cAAc,GAAG,MAAM,CAAC,GAAG,EAAE,GAAG,CAAC,CAoB7F;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,YAAY,GAAG,MAAM,CAAC,GAAG,EAAE,GAAG,CAAC,CA2BpE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAAC,UAAU,EAAE,QAAQ,EAAE,OAAO,EAAE,SAAS,cAAc,EAAE,GAAG,WAAW,EAAE,CAapG;AAUD;;iEAEiE;AACjE,wBAAgB,aAAa,CAAC,UAAU,EAAE,QAAQ,GAAG,OAAO,CAG3D;AAkED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,SAAS,EAAE,GAAG,EAAE,WAAW,GAAG,MAAM,CAAC,GAAG,EAAE,GAAG,CAAC,CAwEvF"}