@esportsplus/reactivity 0.39.1 → 0.40.0

package/README.md

@@ -222,7 +222,8 @@ let user = new ReactiveObject_1();
 | `reactive({...})` | Creates a reactive object with signals and computeds |
 | `reactive([...])` | Creates a reactive array |
 | `effect(fn, apply?)` | Runs a function that re-executes when dependencies change. Returns a dispose function. Optional `apply(value, prev)` runs untracked after each run with `fn`'s return value |
-| `root(fn)` | Creates an untracked scope. If `fn` accepts an argument, a dispose function is provided |
+| `root(fn, owner?)` | Creates an untracked scope. If `fn` accepts an argument, a dispose function is provided. With `owner`, the scope belongs to that node instead of whatever is running: `root(() => …, owner)` runs `fn` owned by `owner` (to re-enter it after an `await`), `root((dispose) => …, owner)` creates a child root of `owner`. Reads stay untracked. Throws on a disposed owner |
+| `owner()` | The node that owns what is created now: the running effect/computed, else the running root's scope, else `null`. Its `.owner` chain reaches every enclosing owner |
 | `onCleanup(fn)` | Registers a cleanup function for the current effect/computed |
 
 ### Low-Level Functions
@@ -301,6 +302,7 @@ All standard array methods (`push`, `pop`, `shift`, `unshift`, `splice`, `sort`,
 
 | Event | Payload | Description |
 |-------|---------|-------------|
+| `batch` | `ArrayOp<T>[]` | Every mutation of a task, in order, each as `{ op, ...payload }` of its event; delivered once inside the reactivity pass that follows (`flush()` settles it), outside any owner. A `clear` drops the mutations before it |
 | `clear` | `undefined` | Array was cleared |
 | `concat` | `{ items: T[] }` | Items were concatenated |
 | `pop` | `{ item: T }` | Item was popped |

package/build/constants.d.ts

@@ -15,5 +15,6 @@ declare const STATE_IN_HEAP: number;
 declare const STATE_COMPUTED: number;
 declare const STATE_ERROR: number;
 declare const STATE_EFFECT: number;
+declare const STATE_DISPOSED: number;
 declare const STATE_NOTIFY_MASK: number;
-export { COMPUTED, PACKAGE_NAME, REACTIVE_ARRAY, REACTIVE_OBJECT, SIGNAL, STABILIZER_DEFERRED, STABILIZER_IDLE, STABILIZER_RESCHEDULE, STABILIZER_RUNNING, STABILIZER_SCHEDULED, STATE_CHECK, STATE_COMPUTED, STATE_DIRTY, STATE_EFFECT, STATE_ERROR, STATE_IN_HEAP, STATE_NOTIFY_MASK, STATE_RECOMPUTING };
+export { COMPUTED, PACKAGE_NAME, REACTIVE_ARRAY, REACTIVE_OBJECT, SIGNAL, STABILIZER_DEFERRED, STABILIZER_IDLE, STABILIZER_RESCHEDULE, STABILIZER_RUNNING, STABILIZER_SCHEDULED, STATE_CHECK, STATE_COMPUTED, STATE_DIRTY, STATE_DISPOSED, STATE_EFFECT, STATE_ERROR, STATE_IN_HEAP, STATE_NOTIFY_MASK, STATE_RECOMPUTING };

package/build/constants.js

@@ -15,5 +15,6 @@ const STATE_IN_HEAP = 1 << 3;
 const STATE_COMPUTED = 1 << 4;
 const STATE_ERROR = 1 << 5;
 const STATE_EFFECT = 1 << 6;
+const STATE_DISPOSED = 1 << 7;
 const STATE_NOTIFY_MASK = (STATE_CHECK | STATE_DIRTY);
-export { COMPUTED, PACKAGE_NAME, REACTIVE_ARRAY, REACTIVE_OBJECT, SIGNAL, STABILIZER_DEFERRED, STABILIZER_IDLE, STABILIZER_RESCHEDULE, STABILIZER_RUNNING, STABILIZER_SCHEDULED, STATE_CHECK, STATE_COMPUTED, STATE_DIRTY, STATE_EFFECT, STATE_ERROR, STATE_IN_HEAP, STATE_NOTIFY_MASK, STATE_RECOMPUTING };
+export { COMPUTED, PACKAGE_NAME, REACTIVE_ARRAY, REACTIVE_OBJECT, SIGNAL, STABILIZER_DEFERRED, STABILIZER_IDLE, STABILIZER_RESCHEDULE, STABILIZER_RUNNING, STABILIZER_SCHEDULED, STATE_CHECK, STATE_COMPUTED, STATE_DIRTY, STATE_DISPOSED, STATE_EFFECT, STATE_ERROR, STATE_IN_HEAP, STATE_NOTIFY_MASK, STATE_RECOMPUTING };

package/build/index.d.ts

@@ -1,5 +1,6 @@
 export { isPromise } from '@esportsplus/utilities';
 export { COMPUTED, REACTIVE_ARRAY, REACTIVE_OBJECT, SIGNAL } from './constants.js';
 export { default as reactive, ReactiveArray, ReactiveObject } from './reactive/index.js';
+export type { ArrayOp } from './reactive/array.js';
 export * from './system.js';
 export * from './types.js';

package/build/reactive/array.d.ts

@@ -1,4 +1,37 @@
+type ArrayOp<T> = {
+    items: T[];
+    op: 'concat';
+} | {
+    deleteCount: number;
+    items: T[];
+    op: 'splice';
+    start: number;
+} | {
+    items: T[];
+    op: 'push';
+} | {
+    index: number;
+    item: T;
+    op: 'set';
+} | {
+    items: T[];
+    op: 'unshift';
+} | {
+    op: 'clear';
+} | {
+    item: T;
+    op: 'pop';
+} | {
+    op: 'reverse';
+} | {
+    item: T;
+    op: 'shift';
+} | {
+    op: 'sort';
+    order: number[];
+};
 type Events<T> = {
+    batch: ArrayOp<T>[];
     clear: undefined;
     concat: {
         items: T[];
@@ -39,12 +72,18 @@ type Listeners<T> = {
 };
 declare class ReactiveArray<T> extends Array<T> {
     private _length;
+    private batched;
+    private delivering;
     listeners: Listeners<T>;
     constructor(items?: readonly T[]);
     static get [Symbol.species](): ArrayConstructor;
     get $length(): number;
     set $length(value: number);
     $set(i: number, value: T): void;
+    private batch;
+    private prune;
+    private record;
+    private unbatch;
     clear(): void;
     concat(...items: ConcatArray<T>[]): ReactiveArray<T>;
     concat(...items: (T | ConcatArray<T>)[]): ReactiveArray<T>;
@@ -52,7 +91,6 @@ declare class ReactiveArray<T> extends Array<T> {
     dispose(): void;
     on<K extends keyof Events<T>>(event: K, listener: Listener<Events<T>[K]>): VoidFunction;
     once<K extends keyof Events<T>>(event: K, listener: Listener<Events<T>[K]>): VoidFunction;
-    private prune;
     pop(): T | undefined;
     push(...items: T[]): number;
     reverse(): this;
@@ -62,3 +100,4 @@ declare class ReactiveArray<T> extends Array<T> {
     unshift(...items: T[]): number;
 }
 export { ReactiveArray };
+export type { ArrayOp };

package/build/reactive/array.js

@@ -1,6 +1,6 @@
 import { isArray } from '@esportsplus/utilities';
 import { PACKAGE_NAME, REACTIVE_ARRAY } from '../constants.js';
-import { read, signal, write } from '../system.js';
+import { effect, read, root, signal, write } from '../system.js';
 import { isReactiveObject } from './object.js';
 function dispose(value) {
     if (isReactiveObject(value)) {
@@ -9,6 +9,8 @@ function dispose(value) {
 }
 class ReactiveArray extends Array {
     _length;
+    batched = null;
+    delivering = false;
     listeners = {};
     constructor(items) {
         super();
@@ -41,12 +43,71 @@ class ReactiveArray extends Array {
             write(this._length, i + 1);
         }
         this.dispatch('set', { index: i, item: value });
+        this.record({ index: i, item: value, op: 'set' });
         dispose(prev);
     }
+    batch() {
+        let tick = signal(0);
+        this.batched = {
+            ops: null,
+            stop: root(() => effect(() => {
+                read(tick);
+                let batched = this.batched, ops = batched?.ops;
+                if (!ops) {
+                    return;
+                }
+                batched.ops = null;
+                this.delivering = true;
+                try {
+                    root(() => this.dispatch('batch', ops));
+                }
+                finally {
+                    this.delivering = false;
+                }
+                if (this.listeners.batch === undefined) {
+                    queueMicrotask(() => {
+                        if (this.listeners.batch === undefined) {
+                            this.unbatch();
+                        }
+                    });
+                }
+            })),
+            tick
+        };
+    }
+    prune(event, listeners) {
+        while (listeners.length && listeners[listeners.length - 1] === null) {
+            listeners.pop();
+        }
+        if (listeners.length === 0 && this.listeners[event] === listeners) {
+            delete this.listeners[event];
+        }
+    }
+    record(op) {
+        let batched = this.batched;
+        if (batched === null) {
+            return;
+        }
+        if (op.op === 'clear' || batched.ops === null) {
+            batched.ops = [op];
+        }
+        else {
+            batched.ops.push(op);
+        }
+        write(batched.tick, batched.tick.value + 1);
+    }
+    unbatch() {
+        let batched = this.batched;
+        if (batched !== null) {
+            this.batched = null;
+            batched.stop();
+        }
+    }
     clear() {
         this.dispose();
         write(this._length, 0);
         this.dispatch('clear');
+        this.record({ op: 'clear' });
     }
     concat(...items) {
         let added = [];
@@ -66,6 +127,7 @@ class ReactiveArray extends Array {
         if (added.length) {
             write(this._length, this.length);
             this.dispatch('concat', { items: added });
+            this.record({ items: added, op: 'concat' });
         }
         return this;
     }
@@ -96,6 +158,9 @@ class ReactiveArray extends Array {
         if (dirty) {
             this.prune(event, listeners);
         }
+        if (event === 'batch' && !this.delivering && this.listeners.batch === undefined) {
+            this.unbatch();
+        }
         if (errors !== null) {
             let error = errors.length === 1
                 ? errors[0]
@@ -113,6 +178,9 @@ class ReactiveArray extends Array {
     }
     on(event, listener) {
         let entry = listener, listeners = this.listeners[event];
+        if (event === 'batch' && this.batched === null) {
+            this.batch();
+        }
         if (listeners === undefined) {
             this.listeners[event] = [entry];
         }
@@ -143,20 +211,15 @@ class ReactiveArray extends Array {
                 current[i] = null;
                 this.prune(event, current);
             }
+            if (event === 'batch' && !this.delivering && this.listeners.batch === undefined) {
+                this.unbatch();
+            }
         };
     }
     once(event, listener) {
         listener.once = true;
         return this.on(event, listener);
     }
-    prune(event, listeners) {
-        while (listeners.length && listeners[listeners.length - 1] === null) {
-            listeners.pop();
-        }
-        if (listeners.length === 0 && this.listeners[event] === listeners) {
-            delete this.listeners[event];
-        }
-    }
     pop() {
         if (this.length === 0) {
             return undefined;
@@ -165,6 +228,7 @@ class ReactiveArray extends Array {
         dispose(item);
         write(this._length, this.length);
         this.dispatch('pop', { item });
+        this.record({ item, op: 'pop' });
         return item;
     }
     push(...items) {
@@ -174,11 +238,13 @@ class ReactiveArray extends Array {
         let length = super.push(...items);
         write(this._length, length);
         this.dispatch('push', { items });
+        this.record({ items, op: 'push' });
         return length;
     }
     reverse() {
         super.reverse();
         this.dispatch('reverse');
+        this.record({ op: 'reverse' });
         return this;
     }
     shift() {
@@ -189,10 +255,11 @@ class ReactiveArray extends Array {
         dispose(item);
         write(this._length, this.length);
         this.dispatch('shift', { item });
+        this.record({ item, op: 'shift' });
         return item;
     }
     sort(fn) {
-        if (this.listeners.sort === undefined) {
+        if (this.listeners.sort === undefined && this.batched === null) {
             super.sort(fn);
         }
         else {
@@ -216,6 +283,7 @@ class ReactiveArray extends Array {
                 order[i] = bucket.indices[bucket.next++];
             }
             this.dispatch('sort', { order });
+            this.record({ op: 'sort', order });
         }
         return this;
     }
@@ -226,12 +294,9 @@ class ReactiveArray extends Array {
             for (let i = 0, n = removed.length; i < n; i++) {
                 dispose(removed[i]);
             }
-            let index = Math.trunc(start) || 0;
-            this.dispatch('splice', {
-                deleteCount: removed.length,
-                items,
-                start: index < 0 ? Math.max(length + index, 0) : Math.min(index, length)
-            });
+            let index = Math.trunc(start) || 0, resolved = index < 0 ? Math.max(length + index, 0) : Math.min(index, length);
+            this.dispatch('splice', { deleteCount: removed.length, items, start: resolved });
+            this.record({ deleteCount: removed.length, items, op: 'splice', start: resolved });
         }
         return removed;
     }
@@ -242,6 +307,7 @@ class ReactiveArray extends Array {
         let length = super.unshift(...items);
         write(this._length, length);
         this.dispatch('unshift', { items });
+        this.record({ items, op: 'unshift' });
         return length;
     }
 }

package/build/system.d.ts

@@ -13,12 +13,13 @@ declare const isSignal: (value: unknown) => value is Signal<unknown>;
 declare const onCleanup: (fn: VoidFunction) => typeof fn;
 declare const peek: <T>(node: Signal<T> | Computed<T>) => T;
 declare const read: <T>(node: Signal<T> | Computed<T>) => T;
-declare const root: <T>(fn: ((dispose: VoidFunction) => T) | (() => T)) => T;
+declare const owner: () => Computed<unknown> | null;
+declare const root: <T>(fn: ((dispose: VoidFunction) => T) | (() => T), parent?: Computed<unknown> | null) => T;
 declare function signal<T>(value: T, equals?: ((a: T, b: T) => boolean) | null): Signal<T>;
 declare namespace signal {
     var selector: <T>(node: Signal<T>, key: T) => boolean;
 }
 declare const untrack: <T>(fn: () => T) => T;
 declare const write: <T>(signal: Signal<T>, value: T) => void;
-export { batch, computed, dispose, effect, flush, hasOwner, isComputed, isSignal, onCleanup, peek, read, root, signal, untrack, write };
+export { batch, computed, dispose, effect, flush, hasOwner, isComputed, isSignal, onCleanup, owner, peek, read, root, signal, untrack, write };
 export type { Computed, Signal };

package/build/system.js

@@ -1,4 +1,4 @@
-import { PACKAGE_NAME, SIGNAL, STABILIZER_DEFERRED, STABILIZER_IDLE, STABILIZER_RESCHEDULE, STABILIZER_RUNNING, STABILIZER_SCHEDULED, STATE_CHECK, STATE_COMPUTED, STATE_DIRTY, STATE_EFFECT, STATE_ERROR, STATE_IN_HEAP, STATE_NOTIFY_MASK, STATE_RECOMPUTING } from './constants.js';
+import { PACKAGE_NAME, SIGNAL, STABILIZER_DEFERRED, STABILIZER_IDLE, STABILIZER_RESCHEDULE, STABILIZER_RUNNING, STABILIZER_SCHEDULED, STATE_CHECK, STATE_COMPUTED, STATE_DIRTY, STATE_DISPOSED, STATE_EFFECT, STATE_ERROR, STATE_IN_HEAP, STATE_NOTIFY_MASK, STATE_RECOMPUTING } from './constants.js';
 import { isObject, isPromise } from '@esportsplus/utilities';
 let asyncFactory = new WeakMap(), depth = 0, disposeHead = null, draining = false, heap = new Array(64), heap_i = 0, heap_n = 0, linkPoolHead = null, microtask = queueMicrotask, notified = false, observer = null, pendingHead = null, pulled = null, puller = null, scope = null, stabilizer = STABILIZER_IDLE, version = 0, walkPoolHead = null, writes = 0;
 function noop() {
@@ -623,6 +623,7 @@ const dispose = (computed) => {
     try {
         for (;;) {
             deleteFromHeap(node);
+            node.state |= STATE_DISPOSED;
             let dep = node.deps;
             while (dep) {
                 dep = unlink(dep);
@@ -751,12 +752,16 @@ const read = (node) => {
     }
     return node.value;
 };
-const root = (fn) => {
+const owner = () => observer || scope;
+const root = (fn, parent) => {
+    if (parent && parent.state & STATE_DISPOSED) {
+        throw new Error(`${PACKAGE_NAME}: root() was given a disposed owner`);
+    }
     let o = observer, s = scope, tracking = fn.length, value;
     observer = null;
     try {
         if (tracking) {
-            let self = makeNode(noop), owner = o || s;
+            let self = makeNode(noop), owner = parent === undefined ? o || s : parent;
             if (owner !== null) {
                 own(owner, self);
             }
@@ -764,7 +769,7 @@ const root = (fn) => {
             value = fn(() => dispose(self));
         }
         else {
-            scope = null;
+            scope = parent ?? null;
             value = fn();
         }
     }
@@ -854,4 +859,4 @@ const write = (signal, value) => {
     }
     schedule();
 };
-export { batch, computed, dispose, effect, flush, hasOwner, isComputed, isSignal, onCleanup, peek, read, root, signal, untrack, write };
+export { batch, computed, dispose, effect, flush, hasOwner, isComputed, isSignal, onCleanup, owner, peek, read, root, signal, untrack, write };

package/package.json

@@ -4,7 +4,7 @@
     "@esportsplus/utilities": "^0.28.6"
   },
   "devDependencies": {
-    "@esportsplus/typescript": "^0.37.0",
+    "@esportsplus/typescript": "^0.38.0",
     "@types/node": "^26.4.1",
     "vite": "^8.2.2",
     "vitest": "^5.0.0"
@@ -36,7 +36,7 @@
   },
   "type": "module",
   "types": "build/index.d.ts",
-  "version": "0.39.1",
+  "version": "0.40.0",
   "scripts": {
     "agent:bench": "vitest bench --run",
     "agent:test": "tsc --noEmit && vitest run",

package/pnpm-workspace.yaml

@@ -2,7 +2,7 @@ allowBuilds:
   esbuild: true
 minimumReleaseAgeExclude:
   - '@esportsplus/utilities@0.28.1 || 0.28.3 || 0.28.4 || 0.28.6'
-  - '@esportsplus/typescript@0.31.0 || 0.32.0 || 0.33.0 || 0.33.2 || 0.33.4 || 0.34.1 || 0.34.3 || 0.34.4 || 0.36.0 || 0.36.1 || 0.37.0'
+  - '@esportsplus/typescript@0.31.0 || 0.32.0 || 0.33.0 || 0.33.2 || 0.33.4 || 0.34.1 || 0.34.3 || 0.34.4 || 0.36.0 || 0.36.1 || 0.37.0 || 0.38.0'
   - tsc-alias@1.9.4
   - '@vitest/mocker@5.0.0'
   - '@vitest/spy@5.0.0'

package/src/constants.ts

@@ -32,6 +32,9 @@ const STATE_ERROR = 1 << 5;
 
 const STATE_EFFECT = 1 << 6;
 
+// Set by dispose(): a node that can never run or own anything again
+const STATE_DISPOSED = 1 << 7;
+
 const STATE_NOTIFY_MASK = (STATE_CHECK | STATE_DIRTY);
 
 
@@ -41,5 +44,5 @@ export {
     REACTIVE_ARRAY, REACTIVE_OBJECT,
     SIGNAL,
     STABILIZER_DEFERRED, STABILIZER_IDLE, STABILIZER_RESCHEDULE, STABILIZER_RUNNING, STABILIZER_SCHEDULED,
-    STATE_CHECK, STATE_COMPUTED, STATE_DIRTY, STATE_EFFECT, STATE_ERROR, STATE_IN_HEAP, STATE_NOTIFY_MASK, STATE_RECOMPUTING
+    STATE_CHECK, STATE_COMPUTED, STATE_DIRTY, STATE_DISPOSED, STATE_EFFECT, STATE_ERROR, STATE_IN_HEAP, STATE_NOTIFY_MASK, STATE_RECOMPUTING
 };

package/src/index.ts

@@ -1,5 +1,6 @@
 export { isPromise } from '@esportsplus/utilities';
 export { COMPUTED, REACTIVE_ARRAY, REACTIVE_OBJECT, SIGNAL } from './constants';
 export { default as reactive, ReactiveArray, ReactiveObject } from './reactive';
+export type { ArrayOp } from './reactive/array';
 export * from './system';
 export * from './types';

package/src/reactive/array.ts

@@ -1,11 +1,27 @@
 import { isArray } from '@esportsplus/utilities';
 import { PACKAGE_NAME, REACTIVE_ARRAY } from '~/constants';
-import { read, signal, write } from '~/system';
+import { effect, read, root, signal, write } from '~/system';
 import type { Signal } from '~/types';
 import { isReactiveObject } from './object';
 
 
+// One mutation as the batch event reports it: the matching event's payload, named by 'op'
+type ArrayOp<T> =
+    | { items: T[]; op: 'concat' }
+    | { deleteCount: number; items: T[]; op: 'splice'; start: number }
+    | { items: T[]; op: 'push' }
+    | { index: number; item: T; op: 'set' }
+    | { items: T[]; op: 'unshift' }
+    | { op: 'clear' }
+    | { item: T; op: 'pop' }
+    | { op: 'reverse' }
+    | { item: T; op: 'shift' }
+    | { op: 'sort'; order: number[] };
+
 type Events<T> = {
+    // Every mutation of a task, in order, delivered once inside the reactivity pass that follows it (flush() settles
+    // it); a clear drops the mutations before it
+    batch: ArrayOp<T>[];
     clear: undefined,
     concat: {
         items: T[];
@@ -60,6 +76,11 @@ class ReactiveArray<T> extends Array<T> {
 
     private _length: Signal<number>;
 
+    // The batch listeners' delivery: the mutations not yet delivered, and the effect that delivers them
+    private batched: { ops: ArrayOp<T>[] | null; stop: VoidFunction; tick: Signal<number> } | null = null;
+
+    private delivering = false;
+
     listeners: Listeners<T> = {};
 
 
@@ -110,14 +131,95 @@ class ReactiveArray<T> extends Array<T> {
         }
 
         this.dispatch('set', { index: i, item: value });
+        this.record({ index: i, item: value, op: 'set' });
         dispose(prev);
     }
 
 
+    // Starts delivering batches: an effect of its own, outside any owner, since the array outlives whoever listens
+    private batch() {
+        let tick = signal(0);
+
+        this.batched = {
+            ops: null,
+            stop: root(() => effect(() => {
+                read(tick);
+
+                let batched = this.batched,
+                    ops = batched?.ops;
+
+                if (!ops) {
+                    return;
+                }
+
+                batched!.ops = null;
+                this.delivering = true;
+
+                try {
+                    // What listeners build belongs to them, not to this effect
+                    root(() => this.dispatch('batch', ops));
+                }
+                finally {
+                    this.delivering = false;
+                }
+
+                // Disposing this effect inside its own run corrupts its dependency links, so the stop waits for the
+                // run to end; a listener that joins meanwhile keeps it
+                if (this.listeners.batch === undefined) {
+                    queueMicrotask(() => {
+                        if (this.listeners.batch === undefined) {
+                            this.unbatch();
+                        }
+                    });
+                }
+            })),
+            tick
+        };
+    }
+
+    // Trims trailing empty slots; an event left with no listeners is deleted, so e.g. sort() skips computing its order
+    private prune<K extends keyof Events<T>>(event: K, listeners: (AnyListener<T> | null)[]) {
+        while (listeners.length && listeners[listeners.length - 1] === null) {
+            listeners.pop();
+        }
+
+        if (listeners.length === 0 && this.listeners[event] === listeners) {
+            delete this.listeners[event];
+        }
+    }
+
+    private record(op: ArrayOp<T>) {
+        let batched = this.batched;
+
+        if (batched === null) {
+            return;
+        }
+
+        if (op.op === 'clear' || batched.ops === null) {
+            batched.ops = [op];
+        }
+        else {
+            batched.ops.push(op);
+        }
+
+        write(batched.tick, batched.tick.value + 1);
+    }
+
+    private unbatch() {
+        let batched = this.batched;
+
+        if (batched !== null) {
+            this.batched = null;
+            batched.stop();
+        }
+    }
+
+
     clear() {
         this.dispose();
         write(this._length, 0);
         this.dispatch('clear');
+        this.record({ op: 'clear' });
     }
 
     concat(...items: ConcatArray<T>[]): ReactiveArray<T>;
@@ -143,6 +245,7 @@ class ReactiveArray<T> extends Array<T> {
         if (added.length) {
             write(this._length, this.length);
             this.dispatch('concat', { items: added });
+            this.record({ items: added, op: 'concat' });
         }
 
         return this;
@@ -185,6 +288,10 @@ class ReactiveArray<T> extends Array<T> {
             this.prune(event, listeners);
         }
 
+        if (event === 'batch' && !this.delivering && this.listeners.batch === undefined) {
+            this.unbatch();
+        }
+
         if (errors !== null) {
             let error = errors.length === 1
                 ? errors[0]
@@ -210,6 +317,10 @@ class ReactiveArray<T> extends Array<T> {
         let entry = listener as AnyListener<T>,
             listeners = this.listeners[event];
 
+        if (event === 'batch' && this.batched === null) {
+            this.batch();
+        }
+
         if (listeners === undefined) {
             this.listeners[event] = [entry];
         }
@@ -248,6 +359,10 @@ class ReactiveArray<T> extends Array<T> {
                 current[i] = null;
                 this.prune(event, current);
             }
+
+            if (event === 'batch' && !this.delivering && this.listeners.batch === undefined) {
+                this.unbatch();
+            }
         };
     }
 
@@ -257,17 +372,6 @@ class ReactiveArray<T> extends Array<T> {
         return this.on(event, listener);
     }
 
-    // Trims trailing empty slots; an event left with no listeners is deleted, so e.g. sort() skips computing its order
-    private prune<K extends keyof Events<T>>(event: K, listeners: (AnyListener<T> | null)[]) {
-        while (listeners.length && listeners[listeners.length - 1] === null) {
-            listeners.pop();
-        }
-
-        if (listeners.length === 0 && this.listeners[event] === listeners) {
-            delete this.listeners[event];
-        }
-    }
-
     pop() {
         if (this.length === 0) {
             return undefined;
@@ -278,6 +382,7 @@ class ReactiveArray<T> extends Array<T> {
         dispose(item);
         write(this._length, this.length);
         this.dispatch('pop', { item });
+        this.record({ item, op: 'pop' });
 
         return item;
     }
@@ -292,6 +397,7 @@ class ReactiveArray<T> extends Array<T> {
         write(this._length, length);
 
         this.dispatch('push', { items });
+        this.record({ items, op: 'push' });
 
         return length;
     }
@@ -299,6 +405,7 @@ class ReactiveArray<T> extends Array<T> {
     reverse() {
         super.reverse();
         this.dispatch('reverse');
+        this.record({ op: 'reverse' });
 
         return this;
     }
@@ -313,12 +420,13 @@ class ReactiveArray<T> extends Array<T> {
         dispose(item);
         write(this._length, this.length);
         this.dispatch('shift', { item });
+        this.record({ item, op: 'shift' });
 
         return item;
     }
 
     sort(fn?: (a: T, b: T) => number) {
-        if (this.listeners.sort === undefined) {
+        if (this.listeners.sort === undefined && this.batched === null) {
             super.sort(fn);
         }
         else {
@@ -353,6 +461,7 @@ class ReactiveArray<T> extends Array<T> {
             }
 
             this.dispatch('sort', { order });
+            this.record({ op: 'sort', order });
         }
 
         return this;
@@ -371,13 +480,11 @@ class ReactiveArray<T> extends Array<T> {
 
             // Listeners receive the position and count Array.prototype.splice actually applied
             // (negative, fractional and out-of-range arguments resolved), never the raw arguments
-            let index = Math.trunc(start) || 0;
+            let index = Math.trunc(start) || 0,
+                resolved = index < 0 ? Math.max(length + index, 0) : Math.min(index, length);
 
-            this.dispatch('splice', {
-                deleteCount: removed.length,
-                items,
-                start: index < 0 ? Math.max(length + index, 0) : Math.min(index, length)
-            });
+            this.dispatch('splice', { deleteCount: removed.length, items, start: resolved });
+            this.record({ deleteCount: removed.length, items, op: 'splice', start: resolved });
         }
 
         return removed;
@@ -392,6 +499,7 @@ class ReactiveArray<T> extends Array<T> {
 
         write(this._length, length);
         this.dispatch('unshift', { items });
+        this.record({ items, op: 'unshift' });
 
         return length;
     }
@@ -401,3 +509,4 @@ Object.defineProperty(ReactiveArray.prototype, REACTIVE_ARRAY, { value: true });
 
 
 export { ReactiveArray };
+export type { ArrayOp };

package/src/system.ts

@@ -2,7 +2,7 @@ import {
     PACKAGE_NAME,
     SIGNAL,
     STABILIZER_DEFERRED, STABILIZER_IDLE, STABILIZER_RESCHEDULE, STABILIZER_RUNNING, STABILIZER_SCHEDULED,
-    STATE_CHECK, STATE_COMPUTED, STATE_DIRTY, STATE_EFFECT, STATE_ERROR, STATE_IN_HEAP, STATE_NOTIFY_MASK, STATE_RECOMPUTING
+    STATE_CHECK, STATE_COMPUTED, STATE_DIRTY, STATE_DISPOSED, STATE_EFFECT, STATE_ERROR, STATE_IN_HEAP, STATE_NOTIFY_MASK, STATE_RECOMPUTING
 } from './constants';
 import { Computed, ComputedResult, Link, SelectorSignal, Settled, Signal } from './types';
 import { isObject, isPromise } from '@esportsplus/utilities';
@@ -941,6 +941,7 @@ const dispose = <T>(computed: Computed<T>): void => {
     try {
         for (;;) {
             deleteFromHeap(node);
+            node.state |= STATE_DISPOSED;
 
             let dep = node.deps;
 
@@ -1116,9 +1117,21 @@ const read = <T>(node: Signal<T> | Computed<T>): T => {
     return node.value;
 };
 
+// The node that owns what is created now: the running computed or effect, else the running root's scope. Walking its
+// .owner chain finds every enclosing owner.
+const owner = (): Computed<unknown> | null => observer || scope;
+
 // Owned before fn runs (nothing can register on the owner meanwhile, so ownerSlot is unchanged): a
 // root disposed inside its own fn then unlinks instead of being parked on the owner as a dead child.
-const root = <T>(fn: ((dispose: VoidFunction) => T) | (() => T)) => {
+//
+// 'parent' replaces whatever is running as the owner, for ownership only: reads in fn stay untracked. With it,
+// root(() => ...) runs fn owned by 'parent' (re-entering it after an await) and root(dispose => ...) creates a
+// child root of 'parent'. A disposed node cannot own anything: nothing would dispose what it took.
+const root = <T>(fn: ((dispose: VoidFunction) => T) | (() => T), parent?: Computed<unknown> | null) => {
+    if (parent && parent.state & STATE_DISPOSED) {
+        throw new Error(`${PACKAGE_NAME}: root() was given a disposed owner`);
+    }
+
     let o = observer,
         s = scope,
         tracking = fn.length,
@@ -1129,7 +1142,7 @@ const root = <T>(fn: ((dispose: VoidFunction) => T) | (() => T)) => {
     try {
         if (tracking) {
             let self = makeNode(noop),
-                owner = o || s;
+                owner = parent === undefined ? o || s : parent;
 
             if (owner !== null) {
                 own(owner, self);
@@ -1139,7 +1152,7 @@ const root = <T>(fn: ((dispose: VoidFunction) => T) | (() => T)) => {
             value = (fn as (dispose: VoidFunction) => T)(() => dispose(self));
         }
         else {
-            scope = null;
+            scope = parent ?? null;
             value = (fn as () => T)();
         }
     }
@@ -1269,7 +1282,7 @@ export {
     flush,
     hasOwner,
     isComputed, isSignal,
-    onCleanup,
+    onCleanup, owner,
     peek,
     read, root,
     signal,

package/test/ownership.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest';
-import { computed, dispose, effect, flush, hasOwner, onCleanup, read, root, signal, untrack, write } from '~/system';
+import { computed, dispose, effect, flush, hasOwner, onCleanup, owner as current, read, root, signal, untrack, write } from '~/system';
 import type { Computed } from '~/system';
 import { captureUncaught } from './lib/uncaught';
 
@@ -584,3 +584,102 @@ describe('hasOwner', () => {
     });
 });
 
+describe('owner', () => {
+    it('is the running computation, else the running root scope, else null', () => {
+        let running: Computed<unknown> | null = null,
+            scope: Computed<unknown> | null = null,
+            seen: unknown[] = [];
+
+        seen.push(current());
+
+        let stop = root((dispose) => {
+            scope = current();
+
+            effect(() => {
+                running = current();
+                seen.push(untrack(() => current()) === running);
+            });
+
+            return dispose;
+        });
+
+        seen.push(current());
+
+        expect(scope).not.toBeNull();
+        expect(running).not.toBe(scope);
+        // An effect is owned once its first run returns
+        expect(running!.owner).toBe(scope);
+
+        stop();
+
+        expect(seen).toEqual([null, true, null]);
+    });
+});
+
+describe('root with an owner', () => {
+    it('runs fn owned by the given node, its reads untracked', async () => {
+        let cleaned = 0,
+            s = signal(0),
+            node: Computed<unknown> | null = null,
+            runs = 0,
+            stop = root((dispose) => {
+                node = current();
+
+                return dispose;
+            });
+
+        root(() => {
+            runs++;
+            read(s);
+            onCleanup(() => cleaned++);
+            effect(() => { read(s); });
+        }, node);
+
+        expect(hasOwner()).toBe(false);
+        expect(registrations(node!)).toBe(2);
+
+        write(s, 1);
+        await Promise.resolve();
+
+        expect(runs).toBe(1);
+
+        stop();
+
+        expect(cleaned).toBe(1);
+        expect(registrations(node!)).toBe(0);
+    });
+
+    it('creates a child root of the given node instead of whatever is running', () => {
+        let a: Computed<unknown> | null = null,
+            b: Computed<unknown> | null = null,
+            child: Computed<unknown> | null = null,
+            stopA = root((dispose) => { a = current(); return dispose; }),
+            stopB = root((dispose) => { b = current(); return dispose; });
+
+        root(() => {
+            root((dispose) => {
+                child = current();
+
+                return dispose;
+            }, a);
+        }, b);
+
+        expect(child!.owner).toBe(a);
+        expect(registrations(b!)).toBe(0);
+
+        stopA();
+
+        expect(child!.owner).toBe(null);
+
+        stopB();
+    });
+
+    it('throws on a disposed owner', () => {
+        let node: Computed<unknown> | null = null,
+            stop = root((dispose) => { node = current(); return dispose; });
+
+        stop();
+
+        expect(() => root(() => {}, node)).toThrow('@esportsplus/reactivity: root() was given a disposed owner');
+    });
+});

package/test/reactive/array.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it, vi } from 'vitest';
-import { effect, read, signal, write } from '~/system';
+import { effect, flush, owner, read, root, signal, write } from '~/system';
 import { ReactiveArray } from '~/reactive/array';
 import { ReactiveObject } from '~/reactive/object';
 import reactive from '~/reactive/index';
@@ -1226,3 +1226,183 @@ describe('ReactiveArray', () => {
         });
     });
 });
+
+describe('ReactiveArray batch', () => {
+    // Disposed links go back to a shared pool; a node disposed mid-run then walks pooled links
+    let pool = () => {
+        let a = signal(0),
+            b = signal(0),
+            c = signal(0);
+
+        root(() => effect(() => read(a) + read(b) + read(c)))();
+    };
+
+    it('delivers every mutation of a task once, in order, in the pass that follows', async () => {
+        let arr = new ReactiveArray([1, 2, 3]),
+            batches: unknown[][] = [];
+
+        arr.on('batch', (ops) => batches.push(ops));
+        arr.push(4);
+        arr.$set(0, 9);
+        arr.splice(1, 1, 7, 8);
+        arr.pop();
+
+        expect(batches).toEqual([]);
+
+        await Promise.resolve();
+
+        expect(batches).toEqual([[
+            { items: [4], op: 'push' },
+            { index: 0, item: 9, op: 'set' },
+            { deleteCount: 1, items: [7, 8], op: 'splice', start: 1 },
+            { item: 4, op: 'pop' }
+        ]]);
+    });
+
+    it('settles through flush()', () => {
+        let arr = new ReactiveArray<number>(),
+            batches: unknown[][] = [];
+
+        arr.on('batch', (ops) => batches.push(ops));
+        arr.push(1, 2);
+        flush();
+
+        expect(batches).toEqual([[{ items: [1, 2], op: 'push' }]]);
+    });
+
+    it('drops the mutations before a clear', () => {
+        let arr = new ReactiveArray([1]),
+            batches: unknown[][] = [];
+
+        arr.on('batch', (ops) => batches.push(ops));
+        arr.push(2);
+        arr.clear();
+        arr.unshift(5);
+        flush();
+
+        expect(batches).toEqual([[{ op: 'clear' }, { items: [5], op: 'unshift' }]]);
+    });
+
+    it('reports the order of a sort, and reverse, shift and concat', () => {
+        let arr = new ReactiveArray([3, 1, 2]),
+            batches: unknown[][] = [];
+
+        arr.on('batch', (ops) => batches.push(ops));
+        arr.sort((a, b) => a - b);
+        arr.reverse();
+        arr.shift();
+        arr.concat([9]);
+        flush();
+
+        expect(batches).toEqual([[
+            { op: 'sort', order: [1, 2, 0] },
+            { op: 'reverse' },
+            { item: 3, op: 'shift' },
+            { items: [9], op: 'concat' }
+        ]]);
+    });
+
+    it('runs listeners outside any owner, and stops delivering once the last one leaves', () => {
+        let arr = new ReactiveArray<number>(),
+            seen: unknown[] = [],
+            stop = arr.on('batch', () => seen.push(owner()));
+
+        arr.push(1);
+        flush();
+        stop();
+        arr.push(2);
+        flush();
+
+        expect(seen).toEqual([null]);
+    });
+
+    it('delivers mutations made inside an effect within the same pass', () => {
+        let arr = new ReactiveArray<number>(),
+            batches: unknown[][] = [],
+            s = signal(0);
+
+        arr.on('batch', (ops) => batches.push(ops));
+
+        let stop = root(() => effect(() => {
+            if (read(s)) {
+                arr.push(read(s));
+            }
+        }));
+
+        write(s, 5);
+        flush();
+        stop();
+
+        expect(batches).toEqual([[{ items: [5], op: 'push' }]]);
+    });
+
+    it('keeps delivering to later listeners after the last one throws and is dropped', async () => {
+        pool();
+
+        let arr = new ReactiveArray<number>(),
+            batches: unknown[][] = [],
+            lengths: number[] = [],
+            stop = root(() => effect(() => { lengths.push(arr.$length); }));
+
+        let captured = await captureUncaught(() => {
+            arr.on('batch', () => { throw new Error('reactivity: batch'); });
+            arr.push(1);
+            flush();
+        });
+
+        arr.on('batch', (ops) => batches.push(ops));
+        arr.push(2);
+        flush();
+        stop();
+
+        expect(captured.map((e) => (e as Error).message)).toEqual(['reactivity: batch']);
+        expect(batches).toEqual([[{ items: [2], op: 'push' }]]);
+        expect(lengths).toEqual([0, 1, 2]);
+    });
+
+    it('keeps delivering to later listeners after the last one unsubscribes itself during dispatch', async () => {
+        pool();
+
+        let arr = new ReactiveArray<number>(),
+            batches: unknown[][] = [],
+            first: unknown[][] = [],
+            lengths: number[] = [],
+            stop = root(() => effect(() => { lengths.push(arr.$length); })),
+            unsubscribe = arr.on('batch', (ops) => {
+                first.push(ops);
+                unsubscribe();
+            });
+
+        arr.push(1);
+        flush();
+        await Promise.resolve();
+
+        arr.push(2);
+        flush();
+
+        arr.on('batch', (ops) => batches.push(ops));
+        arr.push(3);
+        flush();
+        stop();
+
+        expect(first).toEqual([[{ items: [1], op: 'push' }]]);
+        expect(batches).toEqual([[{ items: [3], op: 'push' }]]);
+        expect(lengths).toEqual([0, 1, 2, 3]);
+    });
+
+    it('keeps the delivering effect when a listener joins before the stop runs', () => {
+        let arr = new ReactiveArray<number>(),
+            batches: unknown[][] = [],
+            unsubscribe = arr.on('batch', () => {
+                unsubscribe();
+                arr.on('batch', (ops) => batches.push(ops));
+            });
+
+        arr.push(1);
+        flush();
+        arr.push(2);
+        flush();
+
+        expect(batches).toEqual([[{ items: [2], op: 'push' }]]);
+    });
+});