@bodil/signal 0.3.5 → 0.4.1

package/src/array.test.ts

@@ -1,8 +1,9 @@
+import { sleep } from "@bodil/core/async";
 import { expect, test } from "vitest";
 
 import { Signal } from ".";
 
-test("SignalArray", () => {
+test("Signal.Array", () => {
     const t = Signal.array([1, 2, 3]);
     const length = Signal.computed(() => t.size());
     const three = Signal.computed(() => t.indexOf(3));
@@ -32,3 +33,37 @@ test("SignalArray", () => {
     expect(t.toArray()).toEqual([0, 1, 2, 3, 4]);
     expect(inc.get()).toEqual([1, 2, 3, 4, 5]);
 });
+
+test("Signal.Array.equals", () => {
+    const a = Signal.array([1, 2, 3, 4, 5]);
+    const b = Signal.array([1, 2, 3, 4, 5]);
+    expect(a.equals(b)).toBeTruthy();
+    const c = Signal.array([1, 2, 3, 5, 4]);
+    expect(a.equals(c)).toBeFalsy();
+    const d = Signal.array([1, 2, 3, 4]);
+    expect(a.equals(d)).toBeFalsy();
+    const e = [1, 2, 3, 4, 5];
+    expect(a.equals(e)).toBeFalsy();
+});
+
+test("Signal.Array.replace", async () => {
+    const a = Signal.array([1, 2, 3, 4, 5]);
+    let updates = 0;
+    Signal.effect(() => {
+        a.size();
+        updates++;
+    });
+    expect(updates).toBe(1);
+    a.set(2, 0);
+    await sleep(1);
+    expect(updates).toBe(2);
+    expect(a.toArray()).toEqual([1, 2, 0, 4, 5]);
+    a.replace([1, 2, 0, 4, 5]);
+    await sleep(1);
+    expect(updates).toBe(2);
+    expect(a.toArray()).toEqual([1, 2, 0, 4, 5]);
+    a.replace([1, 2, 3, 5, 4]);
+    await sleep(1);
+    expect(a.toArray()).toEqual([1, 2, 3, 5, 4]);
+    expect(updates).toBe(3);
+});

package/src/array.ts

@@ -1,164 +1,347 @@
+import type { Equals } from "@bodil/core/types";
 import { None, Some, type Option } from "@bodil/opt";
 
-import { Signal } from ".";
+import * as Signal from "./signal";
 
-export interface SignalReadonlyArray<A> extends Iterable<A> {
-    isEmpty(): boolean;
-    size(): number;
-    indexOf(value: A, fromIndex?: number): number;
-    findIndex(
-        predicate: (value: A, index: number, obj: Array<A>) => boolean,
-        thisArg?: any,
-    ): number;
-    toArray(): Array<A>;
-    get(index: number): Option<A>;
-}
+const instance = Symbol("Signal.Array");
 
-export class SignalArray<A> implements Iterable<A>, SignalReadonlyArray<A> {
-    #array: Array<A>;
-    readonly #signal = Signal<null>(null, { equals: () => false });
+type InstanceProps<A> = {
+    array: Array<A>;
+    signal: Signal.State<null>;
+    equals?: (a: A, b: A) => boolean;
+};
 
-    static from<T>(iterable: Iterable<T>): SignalArray<T> {
-        return new SignalArray(iterable);
-    }
+function arraysEqual<A>(a: Array<A>, b: Array<A>, equals: (a: A, b: A) => boolean): boolean {
+    return a.length === b.length && a.every((value, index) => equals(value, b[index]));
+}
+
+/**
+ * A read-only view of a {@link Signal.Array}.
+ *
+ * This acts just like the {@link Signal.Array} it was created from, mirroring
+ * the current contents of the source array, but without the ability to modify
+ * it.
+ */
+export class ReadonlySignalArray<A> implements Iterable<A>, Equals {
+    /** @ignore */
+    protected readonly [instance]: InstanceProps<A>;
 
-    constructor(iterable: Iterable<A>) {
-        this.#array = [...iterable];
+    /** @ignore */
+    protected constructor(instanceProps: InstanceProps<A>) {
+        this[instance] = instanceProps;
     }
 
-    [Symbol.iterator](): IteratorObject<A> {
-        this.#signal.get();
-        return Iterator.from(this.#array);
+    /**
+     * Test whether a value is a `Signal.ReadonlyArray`.
+     */
+    static is(value: unknown): value is Signal.ReadonlyArray<unknown> {
+        return value instanceof ReadonlySignalArray;
     }
 
+    /**
+     * Test whether the array is empty.
+     */
     isEmpty(): boolean {
-        this.#signal.get();
-        return this.#array.length === 0;
+        const self = this[instance];
+        self.signal.get();
+        return self.array.length === 0;
     }
 
+    /**
+     * Get the size of the array.
+     */
     size(): number {
-        this.#signal.get();
-        return this.#array.length;
+        const self = this[instance];
+        self.signal.get();
+        return self.array.length;
     }
 
+    /**
+     * Find the index at which the given value first occurs in the array,
+     * optionally starting at `fromIndex`. If the value doesn't occur in the
+     * array, return `-1`.
+     */
     indexOf(value: A, fromIndex?: number): number {
-        this.#signal.get();
-        return this.#array.indexOf(value, fromIndex);
+        const self = this[instance];
+        self.signal.get();
+        return self.array.indexOf(value, fromIndex);
     }
 
+    /**
+     * Find the first index in the array for which the `predicate` function
+     * returns true for the value at that index, or `-1` if it never does.
+     */
     findIndex(
         predicate: (value: A, index: number, obj: Array<A>) => boolean,
         thisArg?: any,
     ): number {
-        this.#signal.get();
-        return this.#array.findIndex(predicate, thisArg);
+        const self = this[instance];
+        self.signal.get();
+        return self.array.findIndex(predicate, thisArg);
+    }
+
+    /**
+     * Test whether a value is an array with identical contents to this array.
+     */
+    equals(other: unknown): other is Signal.ReadonlyArray<A> {
+        if (!ReadonlySignalArray.is(other)) {
+            return false;
+        }
+        const self = this[instance];
+        self.signal.get();
+        other[instance].signal.get();
+        return arraysEqual(self.array, other[instance].array as Array<A>, self.equals ?? Object.is);
     }
 
+    /**
+     * Copy the contents of this array into a normal {@link Array}.
+     */
     toArray(): Array<A> {
-        this.#signal.get();
-        return this.#array.slice();
+        const self = this[instance];
+        self.signal.get();
+        return self.array.slice();
     }
 
+    /**
+     * Get the value at the given index, or {@link None} if the index is out of
+     * bounds.
+     *
+     * @throws {@link TypeError} of `index` is not an integer
+     */
     get(index: number): Option<A> {
         if (!Number.isInteger(index)) {
             throw new TypeError(`Signal.Array.get: index ${index} is not an integer`);
         }
-        this.#signal.get();
-        return index >= 0 && this.#array.length > index ? Some(this.#array[index]) : None;
+        const self = this[instance];
+        self.signal.get();
+        return Object.hasOwn(this, index) ? Some(self.array[index]) : None;
     }
 
-    readOnly(): SignalReadonlyArray<A> {
-        return this;
+    /**
+     * Iterate over the contents of the array.
+     */
+    [Symbol.iterator](): IteratorObject<A> {
+        const self = this[instance];
+        self.signal.get();
+        return Iterator.from(self.array);
     }
+}
 
-    set(index: number, value: A) {
+/**
+ * An array which behaves like a signal.
+ *
+ * Any read operation on the array, like {@link Signal.Array.get},
+ * {@link Signal.Array.size}, or iteration, acts like a
+ * {@link Signal.State.get}, registering the array as a dependency in any
+ * computed signals or effects it's used in. Correspondingly, any write
+ * operation to the array will cause all of these dependencies to update as
+ * with a {@link Signal.State.set}.
+ *
+ * Note that the API of this array is different from the built-in
+ * {@link Array}. This is intentional. Additionally, many operations you'd
+ * expect to find on an array, like {@link Array.map} or predicates like
+ * {@link Array.every}, are missing from the array itself. It's recommended
+ * that you access these through {@link Iterator}s instead.
+ *
+ * Note also that array access doesn't come with any granularity: if you read
+ * only a single index from the array inside a computed signal, *any* change to
+ * the array causes the signal to recompute, regardless of whether the value at
+ * the index you read changed.
+ */
+export class SignalArray<A> extends ReadonlySignalArray<A> {
+    /**
+     * Construct a new array with the contents of the provided iterable.
+     */
+    static from<T>(iterable: Iterable<T>): Signal.Array<T> {
+        return new SignalArray(iterable);
+    }
+
+    /**
+     * Test whether a value is a `Signal.Array`.
+     */
+    static is(value: unknown): value is Signal.Array<unknown> {
+        return value instanceof SignalArray;
+    }
+
+    /**
+     * Construct a new array, optionally filling it with the contents of the
+     * provided iterable.
+     */
+    constructor(iterable: Iterable<A> = [], options?: Signal.Options<A>) {
+        super({
+            array: Array.from(iterable),
+            signal: new Signal.State<null>(null, { equals: () => false }),
+            equals: options?.equals,
+        });
+    }
+
+    /**
+     * Return a read-only view of the array.
+     */
+    readOnly(): Signal.ReadonlyArray<A> {
+        return new ReadonlySignalArray(this[instance]);
+    }
+
+    /**
+     * Write the given value to the given index of the array, overwriting
+     * anything that may have been there before.
+     *
+     * @throws {@link TypeError} if `index` is negative or not an integer
+     */
+    set(index: number, value: A): this {
         if (!Number.isInteger(index)) {
             throw new TypeError(`Signal.Array.set: index ${index} is not an integer`);
         }
-        if (index > this.#array.length || index < 0) {
+        if (index < 0) {
             throw new RangeError(`Signal.Array.set: index ${index} out of bounds`);
         }
-        this.#array[index] = value;
-        this.#signal.set(null);
+        const self = this[instance];
+        if (!(self.equals ?? Object.is)(self.array[index], value)) {
+            self.array[index] = value;
+            self.signal.set(null);
+        }
+        return this;
     }
 
+    /**
+     * Append the provided values to the end of the array.
+     *
+     * @returns the number of values that were inserted.
+     */
     push(...values: Array<A>): number {
-        const result = this.#array.push(...values);
-        this.#signal.set(null);
+        const self = this[instance];
+        const result = self.array.push(...values);
+        self.signal.set(null);
         return result;
     }
 
+    /**
+     * Prepend the provided values to the start of the array.
+     *
+     * @returns the number of values that were inserted.
+     */
     unshift(...values: Array<A>): number {
-        const result = this.#array.unshift(...values);
-        this.#signal.set(null);
+        const self = this[instance];
+        const result = self.array.unshift(...values);
+        self.signal.set(null);
         return result;
     }
 
+    /**
+     * Remove the item at the front of the array and return it.
+     */
     pop(): Option<A> {
         if (this.isEmpty()) {
             return None;
         }
-        const result = this.#array.pop()!;
-        this.#signal.set(null);
+        const self = this[instance];
+        const result = self.array.pop()!;
+        self.signal.set(null);
         return Some(result);
     }
 
+    /**
+     * Remove the item at the end of the array and return it.
+     */
     shift(): Option<A> {
         if (this.isEmpty()) {
             return None;
         }
-        const result = this.#array.shift()!;
-        this.#signal.set(null);
+        const self = this[instance];
+        const result = self.array.shift()!;
+        self.signal.set(null);
         return Some(result);
     }
 
-    splice(start: number, deleteCount: number, ...values: Array<A>): Array<A> {
+    /** @see {@link Array.splice} */
+    splice(start: number, deleteCount?: number, ...values: Array<A>): Array<A> {
         if (!Number.isInteger(start)) {
-            throw new TypeError(`Signal.Array.splice: index ${start} is not an integer`);
+            throw new TypeError(`Signal.Array.splice: start ${start} is not an integer`);
         }
-        if (start > this.#array.length || start < 0) {
-            throw new RangeError(`Signal.Array.splice: index ${start} out of bounds`);
+        if (deleteCount !== undefined && !Number.isInteger(deleteCount)) {
+            throw new TypeError(
+                `Signal.Array.splice: deleteCount ${deleteCount} is not an integer`,
+            );
         }
-        const result = this.#array.splice(start, deleteCount, ...values);
-        this.#signal.set(null);
+        const self = this[instance];
+        const result = self.array.splice(start, deleteCount as any, ...values);
+        self.signal.set(null);
         return result;
     }
 
+    /**
+     * Insert the given values starting at the given index, shifting the
+     * remainder of the array to higher indices accordingly.
+     *
+     * @throws {@link TypeError} if `index` is not an integer
+     */
     insert(index: number, ...values: Array<A>): this {
         if (!Number.isInteger(index)) {
             throw new TypeError(`Signal.Array.insert: index ${index} is not an integer`);
         }
-        if (index > this.#array.length || index < 0) {
-            throw new RangeError(`Signal.Array.insert: index ${index} out of bounds`);
-        }
-        this.#array.splice(index, 0, ...values);
-        this.#signal.set(null);
+        this.splice(index, 0, ...values);
         return this;
     }
 
+    /**
+     * Remove the value at the given index and return it. If there's no value at
+     * the given index, return {@link None}.
+     *
+     * @throws {@link TypeError} if `index` is not an integer
+     */
     removeIndex(index: number): Option<A> {
         if (!Number.isInteger(index)) {
             throw new TypeError(`Signal.Array.removeIndex: index ${index} is not an integer`);
         }
-        if (index < 0 || index >= this.#array.length) {
+        if (!Object.hasOwn(this, index)) {
             return None;
         }
-        const removed = this.#array.splice(index, 1).pop()!;
-        this.#signal.set(null);
+        const self = this[instance];
+        const removed = self.array.splice(index, 1).pop()!;
+        self.signal.set(null);
         return Some(removed);
     }
 
+    /**
+     * Remove the first occurrence of the given value from the array, if it
+     * exists in the array.
+     */
     remove(value: A): Option<A> {
-        return this.removeIndex(this.indexOf(value));
+        const index = this.indexOf(value);
+        return index < 0 ? None : this.removeIndex(index);
     }
 
+    /**
+     * Remove the first value from the array that matches the given predicate
+     * function, if any.
+     */
     removeFn(predicate: (value: A, index: number, obj: Array<A>) => boolean): Option<A> {
-        return this.removeIndex(this.findIndex(predicate as () => boolean));
+        const index = this.findIndex(predicate as () => boolean);
+        return index < 0 ? None : this.removeIndex(index);
     }
 
+    /**
+     * Discard all values in the array, leaving an empty array.
+     */
     clear(): this {
-        this.#array = [];
-        this.#signal.set(null);
+        const self = this[instance];
+        self.array = [];
+        self.signal.set(null);
+        return this;
+    }
+
+    /**
+     * Replace the contents of this array with the values contained in
+     * `iterable`.
+     */
+    replace(iterable: Iterable<A>): this {
+        const self = this[instance];
+        const oldArray = self.array;
+        const newArray = Array.from(iterable);
+        if (!arraysEqual(oldArray, newArray, self.equals ?? Object.is)) {
+            self.array = newArray;
+            self.signal.set(null);
+        }
         return this;
     }
 }