@bodil/signal 0.3.5 → 0.4.0

package/src/array.ts

@@ -1,164 +1,330 @@
+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);
-    }
+/**
+ * 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();
+        return (
+            this.size() === other.size() &&
+            self.array.every((a, index) => Object.is(a, other.get(index).value))
+        );
+    }
+
+    /**
+     * 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;
     }
 }

package/src/index.ts

@@ -4,268 +4,4 @@
  * @module
  */
 
-import { AbortablePromise } from "@bodil/core/async";
-import { toDisposable, type Disposifiable } from "@bodil/core/disposable";
-import { Err, Ok, type Result } from "@bodil/opt";
-import { Signal } from "signal-polyfill";
-
-import { SignalArray } from "./array";
-
-interface ISignal<A> {
-    /**
-     * The current value of the signal.
-     *
-     * When this is read inside a computation function or an effect function,
-     * this signal is automatically added to the effect or computed signal as a
-     * dependency.
-     */
-    readonly value: A;
-    /**
-     * Construct a {@link Signal.Computed} signal using a mapping function over
-     * the current value of this signal.
-     */
-    map<B>(fn: (value: A) => B): SignalGlobal.Computed<B>;
-    /**
-     * Subscribe to changes to the value of this signal.
-     */
-    on(callback: (value: A) => void): Disposable;
-}
-
-/**
- * A writable state signal.
- */
-class StateSignal<A> extends Signal.State<A> implements ISignal<A> {
-    get value(): A {
-        return this.get();
-    }
-
-    set value(value: A) {
-        this.set(value);
-    }
-
-    /**
-     * Update the current value of this signal using a function.
-     */
-    update(fn: (value: A) => A): void {
-        this.set(Signal.subtle.untrack(() => fn(this.get())));
-    }
-
-    /**
-     * Get a read only version of this signal.
-     */
-    readOnly(): SignalGlobal.Computed<A> {
-        return SignalGlobal.computed(() => this.get());
-    }
-
-    map<B>(fn: (value: A) => B): SignalGlobal.Computed<B> {
-        return SignalGlobal.computed(() => fn(this.get()));
-    }
-
-    on(callback: (value: A) => void): Disposable {
-        return SignalGlobal.subscribe(this, callback);
-    }
-
-    static is(v: unknown): v is SignalGlobal.State<unknown> {
-        return v instanceof StateSignal;
-    }
-}
-
-/**
- * A read only signal computed from the values of other signals.
- */
-class ComputedSignal<A> extends Signal.Computed<A> implements ISignal<A> {
-    get value(): A {
-        return this.get();
-    }
-
-    map<B>(fn: (value: A) => B): SignalGlobal.Computed<B> {
-        return SignalGlobal.computed(() => fn(this.get()));
-    }
-
-    on(callback: (value: A) => void): Disposable {
-        return SignalGlobal.subscribe(this, callback);
-    }
-
-    static is(v: unknown): v is SignalGlobal.Computed<unknown> {
-        return v instanceof ComputedSignal;
-    }
-}
-
-let effectNeedsEnqueue = true;
-const effectWatcher = new Signal.subtle.Watcher(() => {
-    if (effectNeedsEnqueue) {
-        effectNeedsEnqueue = false;
-        queueMicrotask(effectProcess);
-    }
-});
-
-function effectProcess(): void {
-    effectNeedsEnqueue = true;
-    for (const sig of effectWatcher.getPending()) {
-        sig.get();
-    }
-    effectWatcher.watch();
-}
-
-type SignalGlobal<A> = SignalGlobal.State<A> | SignalGlobal.Computed<A>;
-
-const SignalGlobal = Object.assign(
-    /**
-     * Construct a new {@link Signal.State} signal containing the provided value.
-     *
-     * @example
-     * const sig = Signal("Hello Joe!");
-     */
-    function <A>(value: A, options?: Signal.Options<A>): SignalGlobal.State<A> {
-        return new SignalGlobal.State(value, options);
-    },
-    {
-        /**
-         * Test whether the given value is a signal.
-         */
-        is(v: unknown): v is SignalGlobal<unknown> {
-            return SignalGlobal.State.is(v) || SignalGlobal.Computed.is(v);
-        },
-
-        /**
-         * Construct a new {@link Signal.Computed} signal using the provided
-         * computation function.
-         *
-         * @example
-         * const sig1 = Signal(2);
-         * const sig2 = Signal(3);
-         * const sum = Signal.computed(() => sig1.get() + sig2.get());
-         * assert(sum.get() === 5);
-         */
-        computed<A>(
-            fn: (this: SignalGlobal.Computed<A>) => A,
-            options?: Signal.Options<A>,
-        ): SignalGlobal.Computed<A> {
-            return new SignalGlobal.Computed(fn, options);
-        },
-
-        /**
-         * Suscribe to a signal.
-         *
-         * The provided callback will be called every time the value of the
-         * signal changes.
-         */
-        subscribe<A>(signal: SignalGlobal<A>, callback: (value: A) => void): Disposable {
-            return SignalGlobal.effect(() => callback(signal.value));
-        },
-
-        /**
-         * Create an effect responding to signal changes.
-         *
-         * The provided function will be called immediately, and again every
-         * time a signal that was read by the function changes.
-         *
-         * @example
-         * const sig = Signal("Hello Joe!");
-         * effect(() => console.log("Signal value is:", sig.get()));
-         * // prints "Signal value is: Hello Joe!"
-         * sig.set("Hello Mike!");
-         * // prints "Signal value is: Hello Mike!"
-         */
-        effect(fn: () => Disposifiable | void): Disposable {
-            let cleanup: Disposable | undefined;
-            const computed = new SignalGlobal.Computed(() => {
-                if (cleanup !== undefined) {
-                    cleanup[Symbol.dispose]();
-                }
-                const result = fn();
-                cleanup = result !== undefined ? toDisposable(result) : undefined;
-            });
-            effectWatcher.watch(computed);
-            computed.get();
-            return toDisposable(() => {
-                effectWatcher.unwatch(computed);
-                if (cleanup !== undefined) {
-                    cleanup[Symbol.dispose]();
-                }
-            });
-        },
-
-        /**
-         * Construct a new {@link Signal.Computed} signal using an async
-         * computation function.
-         *
-         * This returns a promise which will resolve to a
-         * {@link Signal.Computed} signal once the promise returned by the
-         * computation function resolves, and will update itself whenever
-         * subsequent calls to the computation function resolve.
-         *
-         * The function is provided with an {@link AbortSignal} which any async
-         * jobs started from it should abide by. If a signal dependency changes
-         * while the job is running, the {@link AbortSignal} will be triggered
-         * and the job restarted.
-         */
-        asyncComputed<A>(
-            fn: (abort: AbortSignal) => Promise<A>,
-            options?: Signal.Options<A>,
-        ): Promise<SignalGlobal.Computed<A>> {
-            const result = Promise.withResolvers<SignalGlobal.Computed<A>>();
-            const stream = SignalGlobal.computed(() =>
-                AbortablePromise.run<A>((resolve, reject, abort) => {
-                    try {
-                        fn(abort).then(resolve, reject);
-                    } catch (e) {
-                        reject(e as Error);
-                    }
-                }),
-            );
-            const sig: SignalGlobal.State<Result<A, Error>> = SignalGlobal(Err(new Error()));
-            let job: AbortablePromise<A> | undefined = undefined;
-            let resolved = false;
-            const resolve = () => {
-                if (!resolved) {
-                    resolved = true;
-                    result.resolve(SignalGlobal.computed(() => sig.get().unwrapExact(), options));
-                }
-            };
-            SignalGlobal.effect(() => {
-                if (job !== undefined) {
-                    job.abort();
-                }
-                job = stream.get();
-                job.then(
-                    (next) => {
-                        sig.set(Ok(next));
-                        resolve();
-                    },
-                    (error) => {
-                        if (job?.signal.aborted === true) {
-                            return;
-                        }
-                        sig.set(Err(error));
-                        resolve();
-                    },
-                );
-            });
-            return result.promise;
-        },
-
-        array<A>(values: Iterable<A>) {
-            return SignalArray.from(values);
-        },
-
-        State: StateSignal,
-        Computed: ComputedSignal,
-        Array: SignalArray,
-        subtle: Signal.subtle,
-    },
-);
-
-declare namespace SignalGlobal {
-    /** @interface */
-    export type State<A> = StateSignal<A>;
-    /** @interface */
-    export type Computed<A> = ComputedSignal<A>;
-    export type Array<A> = SignalArray<A>;
-    export type Options<A> = Signal.Options<A>;
-    export namespace subtle {
-        export type Watcher = Signal.subtle.Watcher;
-    }
-}
-
-export { SignalGlobal as Signal };
+export * as Signal from "./signal";