aeon-test 0.1.0

package/README.md

@@ -0,0 +1,47 @@
+# aeon-test
+
+Marble testing utilities and helpers for [Aeon](https://github.com/joshburgess/aeon).
+
+This package provides:
+
+- **`marble`** — RxJS-style marble syntax for declaratively constructing test events
+- **`collect`** — synchronously collect all emitted values from an event into an array
+- **`testEvent`** — helpers for building events that fire at specific virtual times
+- **`assert`** — assertion helpers for comparing event sequences
+
+For the underlying virtual scheduler, see [`aeon-scheduler`](https://www.npmjs.com/package/aeon-scheduler) (`VirtualScheduler`).
+
+## Installation
+
+```bash
+pnpm add -D aeon-test aeon-scheduler
+```
+
+## Quick Start
+
+```typescript
+import { describe, it, expect } from "vitest";
+import { map } from "aeon-core";
+import { VirtualScheduler } from "aeon-scheduler";
+import { collect } from "aeon-test";
+
+describe("map", () => {
+  it("doubles each value", () => {
+    const scheduler = new VirtualScheduler();
+    const result = collect(
+      map((x: number) => x * 2, fromArray([1, 2, 3])),
+      scheduler,
+    );
+    expect(result).toEqual([2, 4, 6]);
+  });
+});
+```
+
+## Documentation
+
+- [Main README](https://github.com/joshburgess/aeon#readme)
+- [Getting Started](https://github.com/joshburgess/aeon/blob/main/docs/getting-started.md)
+
+## License
+
+MIT

package/dist/assert.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Assertion helpers for marble-based stream testing.
+ */
+import type { CollectedEntry } from "./collect.js";
+import type { MarbleEntry } from "./marble.js";
+/**
+ * Compare collected entries against expected marble entries.
+ *
+ * Returns `{ pass: true }` if they match, or `{ pass: false, message }`
+ * with a human-readable diff if they don't.
+ *
+ * This is framework-agnostic — use it with any assertion library:
+ * ```typescript
+ * const check = assertEvents(result.entries, expected);
+ * if (!check.pass) throw new Error(check.message);
+ * ```
+ */
+export declare const assertEvents: <A, E>(actual: readonly CollectedEntry<A, E>[], expected: readonly MarbleEntry<A, E>[]) => {
+    pass: true;
+} | {
+    pass: false;
+    message: string;
+};
+//# sourceMappingURL=assert.d.ts.map

package/dist/assert.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"assert.d.ts","sourceRoot":"","sources":["../src/assert.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AACnD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/C;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,YAAY,GAAI,CAAC,EAAE,CAAC,EAC/B,QAAQ,SAAS,cAAc,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EACvC,UAAU,SAAS,WAAW,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,KACrC;IAAE,IAAI,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAuDjD,CAAC"}

package/dist/collect.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Test collection helpers.
+ *
+ * Helpers for running a pulse Event and collecting its output
+ * as a structured list of timed entries for assertion.
+ */
+import type { Disposable, Event as PulseEvent, Scheduler, Time } from "aeon-types";
+/** A collected event entry (value, error, or end). */
+export type CollectedEntry<A, E = never> = {
+    readonly type: "event";
+    readonly time: Time;
+    readonly value: A;
+} | {
+    readonly type: "error";
+    readonly time: Time;
+    readonly error: E;
+} | {
+    readonly type: "end";
+    readonly time: Time;
+};
+/** Result of collecting events from a stream. */
+export interface CollectResult<A, E = never> {
+    /** All collected entries in order. */
+    readonly entries: CollectedEntry<A, E>[];
+    /** Just the values (convenience accessor). */
+    readonly values: A[];
+    /** Whether the stream ended. */
+    readonly ended: boolean;
+    /** Whether the stream errored. */
+    readonly errored: boolean;
+    /** The error value, if any. */
+    readonly error: E | undefined;
+    /** Disposable to stop collection. */
+    readonly disposable: Disposable;
+}
+/**
+ * Subscribe to a pulse Event and collect all emissions.
+ *
+ * Returns a CollectResult whose `entries`, `values`, `ended`, etc.
+ * update live as the scheduler advances. Use with VirtualScheduler:
+ *
+ * ```typescript
+ * const scheduler = new VirtualScheduler();
+ * const result = collectEvents(myEvent, scheduler);
+ * scheduler.advanceTo(toTime(100));
+ * expect(result.values).toEqual([1, 2, 3]);
+ * expect(result.ended).toBe(true);
+ * result.disposable.dispose();
+ * ```
+ */
+export declare const collectEvents: <A, E = never>(event: PulseEvent<A, E>, scheduler: Scheduler) => CollectResult<A, E>;
+/**
+ * Collect all values from a synchronous Event.
+ *
+ * For events backed by synchronous sources (fromArray, now, empty),
+ * all values are available immediately without advancing time.
+ */
+export declare const collectSync: <A>(event: PulseEvent<A, never>, scheduler: Scheduler) => A[];
+//# sourceMappingURL=collect.d.ts.map

package/dist/collect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"collect.d.ts","sourceRoot":"","sources":["../src/collect.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,KAAK,IAAI,UAAU,EAAE,SAAS,EAAgB,IAAI,EAAE,MAAM,YAAY,CAAC;AAEjG,sDAAsD;AACtD,MAAM,MAAM,cAAc,CAAC,CAAC,EAAE,CAAC,GAAG,KAAK,IACnC;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAA;CAAE,GAClE;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAA;CAAE,GAClE;IAAE,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAA;CAAE,CAAC;AAElD,iDAAiD;AACjD,MAAM,WAAW,aAAa,CAAC,CAAC,EAAE,CAAC,GAAG,KAAK;IACzC,sCAAsC;IACtC,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC;IACzC,8CAA8C;IAC9C,QAAQ,CAAC,MAAM,EAAE,CAAC,EAAE,CAAC;IACrB,gCAAgC;IAChC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,kCAAkC;IAClC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,+BAA+B;IAC/B,QAAQ,CAAC,KAAK,EAAE,CAAC,GAAG,SAAS,CAAC;IAC9B,qCAAqC;IACrC,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;CACjC;AAED;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,aAAa,GAAI,CAAC,EAAE,CAAC,GAAG,KAAK,EACxC,OAAO,UAAU,CAAC,CAAC,EAAE,CAAC,CAAC,EACvB,WAAW,SAAS,KACnB,aAAa,CAAC,CAAC,EAAE,CAAC,CAiCpB,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,WAAW,GAAI,CAAC,EAAE,OAAO,UAAU,CAAC,CAAC,EAAE,KAAK,CAAC,EAAE,WAAW,SAAS,KAAG,CAAC,EAInF,CAAC"}

package/dist/index.cjs

@@ -0,0 +1,521 @@
+'use strict';
+
+/**
+ * Branded types for temporal values.
+ *
+ * Branding prevents accidental mixing of Time, Duration, and Offset
+ * at the type level while remaining plain numbers at runtime.
+ */ // --- Constructors ---
+/** Wrap a raw millisecond value as a Time. */ const toTime$1 = (ms)=>ms;
+/** Advance a Time by a Duration. */ const timeAdd = (t, d)=>t + d;
+// --- Constants ---
+/** Time zero — the epoch. */ const TIME_ZERO = 0;
+/** Manually advanceable clock for deterministic testing. */ let VirtualClock = class VirtualClock {
+    constructor(initialTime = toTime$1(0)){
+        this.time = initialTime;
+    }
+    now() {
+        return this.time;
+    }
+    setTime(time) {
+        this.time = time;
+    }
+    advance(ms) {
+        this.time = toTime$1(this.time + ms);
+    }
+};
+/**
+ * Binary min-heap for the scheduler's timer queue.
+ *
+ * Keyed on a numeric priority (scheduled time). Uses a pre-allocated
+ * backing array to minimize per-node allocation.
+ */ let BinaryHeap = class BinaryHeap {
+    constructor(initialCapacity = 64){
+        this.items = [];
+        // Pre-allocate hint (V8 will grow as needed)
+        if (initialCapacity > 0) {
+            this.items.length = 0;
+        }
+    }
+    get size() {
+        return this.items.length;
+    }
+    peek() {
+        return this.items[0];
+    }
+    insert(value, priority) {
+        const entry = {
+            value,
+            priority,
+            index: this.items.length
+        };
+        this.items.push(entry);
+        this.siftUp(entry.index);
+        return entry;
+    }
+    extractMin() {
+        if (this.items.length === 0) return undefined;
+        const min = this.items[0];
+        this.removeAt(0);
+        return min;
+    }
+    remove(entry) {
+        if (entry.index < 0 || entry.index >= this.items.length) return false;
+        if (this.items[entry.index] !== entry) return false;
+        this.removeAt(entry.index);
+        return true;
+    }
+    removeAt(index) {
+        const last = this.items.length - 1;
+        if (index === last) {
+            this.items.pop();
+            return;
+        }
+        const moved = this.items[last];
+        this.items[index] = moved;
+        moved.index = index;
+        this.items.pop();
+        // Restore heap property
+        const parent = index - 1 >>> 1;
+        if (index > 0 && moved.priority < this.items[parent].priority) {
+            this.siftUp(index);
+        } else {
+            this.siftDown(index);
+        }
+    }
+    siftUp(index) {
+        const item = this.items[index];
+        while(index > 0){
+            const parentIndex = index - 1 >>> 1;
+            const parent = this.items[parentIndex];
+            if (item.priority >= parent.priority) break;
+            this.items[index] = parent;
+            parent.index = index;
+            index = parentIndex;
+        }
+        this.items[index] = item;
+        item.index = index;
+    }
+    siftDown(index) {
+        const item = this.items[index];
+        const halfLength = this.items.length >>> 1;
+        while(index < halfLength){
+            let childIndex = 2 * index + 1;
+            let child = this.items[childIndex];
+            const rightIndex = childIndex + 1;
+            if (rightIndex < this.items.length && this.items[rightIndex].priority < child.priority) {
+                childIndex = rightIndex;
+                child = this.items[rightIndex];
+            }
+            if (item.priority <= child.priority) break;
+            this.items[index] = child;
+            child.index = index;
+            index = childIndex;
+        }
+        this.items[index] = item;
+        item.index = index;
+    }
+};
+let VirtualScheduler = class VirtualScheduler {
+    constructor(initialTime = TIME_ZERO){
+        this.clock = new VirtualClock(initialTime);
+        this.heap = new BinaryHeap();
+    }
+    currentTime() {
+        return this.clock.now();
+    }
+    scheduleTask(delay, task) {
+        const time = timeAdd(this.clock.now(), delay);
+        const pending = {
+            task,
+            time,
+            cancelled: false,
+            heapEntry: undefined
+        };
+        pending.heapEntry = this.heap.insert(pending, time);
+        return {
+            task,
+            time,
+            dispose () {
+                if (!pending.cancelled) {
+                    pending.cancelled = true;
+                    if (pending.heapEntry) ;
+                }
+            }
+        };
+    }
+    relative(offset) {
+        return new VirtualRelativeScheduler(offset, this);
+    }
+    cancelTask(st) {
+        st.dispose();
+    }
+    /** Advance time by a duration, executing all tasks that fall within range. */ advance(duration) {
+        const target = timeAdd(this.clock.now(), duration);
+        this.advanceTo(target);
+    }
+    /** Advance to an exact time, executing all tasks up to and including that time. */ advanceTo(time) {
+        while(this.heap.size > 0){
+            const next = this.heap.peek();
+            if (next.priority > time) break;
+            this.heap.extractMin();
+            const pending = next.value;
+            if (!pending.cancelled) {
+                this.clock.setTime(pending.time);
+                try {
+                    pending.task.run(pending.time);
+                } catch (err) {
+                    pending.task.error(pending.time, err);
+                }
+            }
+        }
+        this.clock.setTime(time);
+    }
+    /** Execute all pending tasks regardless of time. */ flush() {
+        while(this.heap.size > 0){
+            const next = this.heap.extractMin();
+            const pending = next.value;
+            if (!pending.cancelled) {
+                this.clock.setTime(pending.time);
+                try {
+                    pending.task.run(pending.time);
+                } catch (err) {
+                    pending.task.error(pending.time, err);
+                }
+            }
+        }
+    }
+    /** Number of pending (non-cancelled) tasks. */ get pendingCount() {
+        return this.heap.size;
+    }
+};
+let VirtualRelativeScheduler = class VirtualRelativeScheduler {
+    constructor(offset, parent){
+        this.offset = offset;
+        this.parent = parent;
+    }
+    currentTime() {
+        return toTime$1(this.parent.currentTime() + this.offset);
+    }
+    scheduleTask(delay, task) {
+        return this.parent.scheduleTask(delay, task);
+    }
+    relative(offset) {
+        return new VirtualRelativeScheduler(toTime$1(this.offset + offset), this.parent);
+    }
+    cancelTask(st) {
+        this.parent.cancelTask(st);
+    }
+};
+
+/**
+ * Branded types for temporal values.
+ *
+ * Branding prevents accidental mixing of Time, Duration, and Offset
+ * at the type level while remaining plain numbers at runtime.
+ */ // --- Constructors ---
+/** Wrap a raw millisecond value as a Time. */ const toTime = (ms)=>ms;
+/** Wrap a raw millisecond value as a Duration. */ const toDuration = (ms)=>ms;
+
+/**
+ * Parse a marble string into a sequence of timed entries.
+ *
+ * @param marble - The marble notation string
+ * @param values - Map from single-character keys to values
+ * @param error - The error value for `#`
+ * @param timeUnit - Milliseconds per time unit (default: 1)
+ */ const parseMarble = (marble, values, error, timeUnit = 1)=>{
+    const entries = [];
+    let time = 0;
+    let inGroup = false;
+    for(let i = 0; i < marble.length; i++){
+        const ch = marble[i];
+        switch(ch){
+            case "-":
+                if (!inGroup) time += timeUnit;
+                break;
+            case "(":
+                inGroup = true;
+                break;
+            case ")":
+                inGroup = false;
+                if (!inGroup) time += timeUnit;
+                break;
+            case "|":
+                entries.push({
+                    type: "end",
+                    time: toTime(time)
+                });
+                if (!inGroup) time += timeUnit;
+                break;
+            case "#":
+                entries.push({
+                    type: "error",
+                    time: toTime(time),
+                    error: error
+                });
+                if (!inGroup) time += timeUnit;
+                break;
+            case " ":
+                break;
+            default:
+                {
+                    const value = values[ch];
+                    if (value === undefined) {
+                        throw new Error(`Marble character '${ch}' not found in values map`);
+                    }
+                    entries.push({
+                        type: "event",
+                        time: toTime(time),
+                        value
+                    });
+                    if (!inGroup) time += timeUnit;
+                    break;
+                }
+        }
+    }
+    return entries;
+};
+/**
+ * Compute the total duration of a marble string (in time units).
+ */ const marbleDuration = (marble, timeUnit = 1)=>{
+    let time = 0;
+    let inGroup = false;
+    for(let i = 0; i < marble.length; i++){
+        const ch = marble[i];
+        if (ch === "(") {
+            inGroup = true;
+            continue;
+        }
+        if (ch === ")") {
+            inGroup = false;
+            time += timeUnit;
+            continue;
+        }
+        if (ch === " ") continue;
+        if (!inGroup) time += timeUnit;
+    }
+    return time;
+};
+
+let MarbleSource = class MarbleSource {
+    constructor(entries){
+        this.entries = entries;
+    }
+    run(sink, scheduler) {
+        const disposables = [];
+        const currentTime = scheduler.currentTime();
+        for (const entry of this.entries){
+            const delay = toDuration(entry.time - currentTime);
+            switch(entry.type){
+                case "event":
+                    {
+                        const value = entry.value;
+                        disposables.push(scheduler.scheduleTask(delay, {
+                            run (t) {
+                                sink.event(t, value);
+                            },
+                            error (t, err) {
+                                sink.error(t, err);
+                            },
+                            dispose () {}
+                        }));
+                        break;
+                    }
+                case "error":
+                    {
+                        const error = entry.error;
+                        disposables.push(scheduler.scheduleTask(delay, {
+                            run (t) {
+                                sink.error(t, error);
+                            },
+                            error () {},
+                            dispose () {}
+                        }));
+                        break;
+                    }
+                case "end":
+                    {
+                        disposables.push(scheduler.scheduleTask(delay, {
+                            run (t) {
+                                sink.end(t);
+                            },
+                            error () {},
+                            dispose () {}
+                        }));
+                        break;
+                    }
+            }
+        }
+        return {
+            dispose () {
+                for (const d of disposables)d.dispose();
+            }
+        };
+    }
+};
+/**
+ * Create a pulse Event from a marble string.
+ *
+ * Events are scheduled on the provided scheduler. Use with VirtualScheduler
+ * and advance/flush to control time.
+ *
+ * @param marble - Marble notation string
+ * @param values - Map from single-character keys to values
+ * @param error - Error value for `#` in the marble string
+ * @param timeUnit - Milliseconds per time unit (default: 1)
+ */ const testEvent = (marble, values, error, timeUnit)=>{
+    const entries = parseMarble(marble, values, error, timeUnit);
+    return new MarbleSource(entries);
+};
+
+/**
+ * Test collection helpers.
+ *
+ * Helpers for running a pulse Event and collecting its output
+ * as a structured list of timed entries for assertion.
+ */ /**
+ * Subscribe to a pulse Event and collect all emissions.
+ *
+ * Returns a CollectResult whose `entries`, `values`, `ended`, etc.
+ * update live as the scheduler advances. Use with VirtualScheduler:
+ *
+ * ```typescript
+ * const scheduler = new VirtualScheduler();
+ * const result = collectEvents(myEvent, scheduler);
+ * scheduler.advanceTo(toTime(100));
+ * expect(result.values).toEqual([1, 2, 3]);
+ * expect(result.ended).toBe(true);
+ * result.disposable.dispose();
+ * ```
+ */ const collectEvents = (event, scheduler)=>{
+    const entries = [];
+    const values = [];
+    const result = {
+        entries,
+        values,
+        ended: false,
+        errored: false,
+        error: undefined,
+        disposable: {
+            dispose () {}
+        }
+    };
+    const sink = {
+        event (time, value) {
+            entries.push({
+                type: "event",
+                time,
+                value
+            });
+            values.push(value);
+        },
+        error (time, err) {
+            entries.push({
+                type: "error",
+                time,
+                error: err
+            });
+            result.errored = true;
+            result.error = err;
+        },
+        end (time) {
+            entries.push({
+                type: "end",
+                time
+            });
+            result.ended = true;
+        }
+    };
+    const source = event;
+    const disposable = source.run(sink, scheduler);
+    result.disposable = disposable;
+    return result;
+};
+/**
+ * Collect all values from a synchronous Event.
+ *
+ * For events backed by synchronous sources (fromArray, now, empty),
+ * all values are available immediately without advancing time.
+ */ const collectSync = (event, scheduler)=>{
+    const result = collectEvents(event, scheduler);
+    result.disposable.dispose();
+    return result.values;
+};
+
+/**
+ * Assertion helpers for marble-based stream testing.
+ */ /**
+ * Compare collected entries against expected marble entries.
+ *
+ * Returns `{ pass: true }` if they match, or `{ pass: false, message }`
+ * with a human-readable diff if they don't.
+ *
+ * This is framework-agnostic — use it with any assertion library:
+ * ```typescript
+ * const check = assertEvents(result.entries, expected);
+ * if (!check.pass) throw new Error(check.message);
+ * ```
+ */ const assertEvents = (actual, expected)=>{
+    if (actual.length !== expected.length) {
+        return {
+            pass: false,
+            message: `Expected ${expected.length} entries, got ${actual.length}.\n` + `  actual:   ${formatEntries(actual)}\n` + `  expected: ${formatEntries(expected)}`
+        };
+    }
+    for(let i = 0; i < actual.length; i++){
+        const a = actual[i];
+        const e = expected[i];
+        if (a.type !== e.type) {
+            return {
+                pass: false,
+                message: `Entry ${i}: expected type '${e.type}', got '${a.type}'.\n` + `  actual:   ${formatEntry(a)}\n` + `  expected: ${formatEntry(e)}`
+            };
+        }
+        if (a.time !== e.time) {
+            return {
+                pass: false,
+                message: `Entry ${i}: expected time ${e.time}, got ${a.time}.\n` + `  actual:   ${formatEntry(a)}\n` + `  expected: ${formatEntry(e)}`
+            };
+        }
+        if (a.type === "event" && e.type === "event") {
+            if (!Object.is(a.value, e.value)) {
+                return {
+                    pass: false,
+                    message: `Entry ${i}: expected value ${JSON.stringify(e.value)}, got ${JSON.stringify(a.value)}.`
+                };
+            }
+        }
+        if (a.type === "error" && e.type === "error") {
+            if (!Object.is(a.error, e.error)) {
+                return {
+                    pass: false,
+                    message: `Entry ${i}: expected error ${JSON.stringify(e.error)}, got ${JSON.stringify(a.error)}.`
+                };
+            }
+        }
+    }
+    return {
+        pass: true
+    };
+};
+const formatEntry = (e)=>{
+    switch(e.type){
+        case "event":
+            return `event(${e.time}, ${JSON.stringify(e.value)})`;
+        case "error":
+            return `error(${e.time}, ${JSON.stringify(e.error)})`;
+        case "end":
+            return `end(${e.time})`;
+    }
+};
+const formatEntries = (entries)=>`[${entries.map(formatEntry).join(", ")}]`;
+
+exports.VirtualScheduler = VirtualScheduler;
+exports.assertEvents = assertEvents;
+exports.collectEvents = collectEvents;
+exports.collectSync = collectSync;
+exports.marbleDuration = marbleDuration;
+exports.parseMarble = parseMarble;
+exports.testEvent = testEvent;
+//# sourceMappingURL=index.cjs.map