@bodil/signal 0.3.5 → 0.4.0

package/src/signal.ts

@@ -0,0 +1,361 @@
+import { AbortablePromise } from "@bodil/core/async";
+import { toDisposable, type Disposifiable } from "@bodil/core/disposable";
+import { Err, Ok, type Result } from "@bodil/opt";
+import { Signal as SignalPolyfill } from "signal-polyfill";
+
+import { ReadonlySignalArray, SignalArray } from "./array";
+import { ReadonlySignalMap, SignalMap } from "./map";
+
+const SystemSignal = ((globalThis as any).Signal as typeof SignalPolyfill) ?? SignalPolyfill;
+
+/** @namespace */
+export const subtle = SystemSignal.subtle;
+// eslint-disable-next-line @typescript-eslint/no-namespace
+export namespace subtle {
+    /** @hidden */
+    export type Watcher = SignalPolyfill.subtle.Watcher;
+}
+
+export type Options<A> = {
+    /** @internal */
+    [subtle.unwatched]?: () => void;
+    /** @internal */
+    [subtle.watched]?: () => void;
+    /**
+     * A function used to compare the new value of a signal with the previous
+     * value when the signal's value updates. If the function returns false,
+     * this will cause the signal's dependencies to update themselves with the
+     * new value, because the value is considered to have changed. If the
+     * function returns true, dependencies will not be updated, because no
+     * change is considered to have occurred.
+     *
+     * This option defaults to using {@link Object.is}.
+     */
+    equals?: (a: A, b: A) => boolean;
+};
+
+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): Computed<B>;
+    /**
+     * Subscribe to changes to the value of this signal.
+     */
+    on(callback: (value: A) => void): Disposable;
+    /**
+     * Get the current value of the signal.
+     *
+     * When this is called inside a computation function or an effect function,
+     * this signal is automatically added to the effect or computed signal as a
+     * dependency.
+     */
+    get(): A;
+}
+
+/**
+ * A signal which contains a writable value.
+ */
+export class State<A> extends SystemSignal.State<A> implements ISignal<A> {
+    get value(): A {
+        return this.get();
+    }
+
+    set value(value: A) {
+        this.set(value);
+    }
+
+    get(): A {
+        return super.get();
+    }
+
+    /**
+     * Set the current value of the signal.
+     *
+     * This triggers an update of every dependency of the signal. Computed
+     * signals will recompute the next time they're read, and effects will be
+     * scheduled to run as soon as possible.
+     */
+    set(value: A): void {
+        super.set(value);
+    }
+
+    /**
+     *  @internal
+     * @hidden
+     */
+    // eslint-disable-next-line @typescript-eslint/no-useless-constructor
+    constructor(value: A, options?: Options<A>) {
+        super(value, options);
+    }
+    /**
+     * Update the current value of this signal using a function.
+     */
+    update(fn: (value: A) => A): void {
+        this.set(SystemSignal.subtle.untrack(() => fn(this.get())));
+    }
+
+    /**
+     * Get a read only version of this signal.
+     */
+    readOnly(): Computed<A> {
+        return computed(() => this.get());
+    }
+
+    map<B>(fn: (value: A) => B): Computed<B> {
+        return computed(() => fn(this.get()));
+    }
+
+    on(callback: (value: A) => void): Disposable {
+        return subscribe(this, callback);
+    }
+
+    /**
+     * Test whether a value is a {@link Signal.State} signal.
+     */
+    static is(v: unknown): v is State<unknown> {
+        return v instanceof State;
+    }
+}
+
+/**
+ * A signal which contains a reactive computation.
+ *
+ * @property get
+ * Get the current value of the signal.
+ *
+ * When this is called inside a computation function or an effect function,
+ * this signal is automatically added to the effect or computed signal as a
+ * dependency.
+ */
+export class Computed<A> extends SystemSignal.Computed<A> implements ISignal<A> {
+    get value(): A {
+        return this.get();
+    }
+
+    get(): A {
+        return super.get();
+    }
+
+    /**
+     * @internal
+     * @hidden
+     */
+    // eslint-disable-next-line @typescript-eslint/no-useless-constructor
+    constructor(computeFn: () => A, options?: Options<A>) {
+        super(computeFn, options);
+    }
+
+    map<B>(fn: (value: A) => B): Computed<B> {
+        return computed(() => fn(this.get()));
+    }
+
+    on(callback: (value: A) => void): Disposable {
+        return subscribe(this, callback);
+    }
+
+    /**
+     * Test whether a value is a {@link Signal.Computed} signal.
+     */
+    static is(v: unknown): v is Computed<unknown> {
+        return v instanceof Computed;
+    }
+}
+
+/**
+ * A type representing any kind of signal, either a {@link Signal.State} or a
+ * {@link Signal.Computed}.
+ */
+export type Any<A> = State<A> | Computed<A>;
+
+let effectNeedsEnqueue = true;
+const effectWatcher = new SystemSignal.subtle.Watcher(() => {
+    if (effectNeedsEnqueue) {
+        effectNeedsEnqueue = false;
+        queueMicrotask(effectProcess);
+    }
+});
+
+function effectProcess(): void {
+    effectNeedsEnqueue = true;
+    for (const sig of effectWatcher.getPending()) {
+        sig.get();
+    }
+    effectWatcher.watch();
+}
+
+/**
+ * Test whether the given value is a signal.
+ *
+ * @see {@link Signal.State.is}, {@link Signal.Computed.is}
+ */
+export function is(v: unknown): v is Any<unknown> {
+    return State.is(v) || Computed.is(v);
+}
+
+/**
+ * Construct a new {@link Signal.State} signal containing the provided value.
+ *
+ * @example
+ * const sig = Signal.state("Hello Joe!");
+ */
+export function from<A>(value: A, options?: Options<A>): State<A> {
+    return new State(value, options);
+}
+
+/**
+ * {@inheritDoc from}
+ * @function
+ */
+export const state = from;
+
+/**
+ * Construct a new {@link Signal.Computed} signal using the provided
+ * computation function.
+ *
+ * @example
+ * const sig1 = Signal.from(2);
+ * const sig2 = Signal.from(3);
+ * const sum = Signal.computed(() => sig1.get() + sig2.get());
+ * assert(sum.get() === 5);
+ * sig1.set(4);
+ * assert(sum.get() === 7);
+ */
+export function computed<A>(fn: (this: Computed<A>) => A, options?: Options<A>): Computed<A> {
+    return new Computed(fn, options);
+}
+
+/**
+ * Suscribe to a signal.
+ *
+ * The provided callback will be called every time the value of the
+ * signal changes.
+ */
+export function subscribe<A>(signal: Any<A>, callback: (value: A) => void): Disposable {
+    return 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.from("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!"
+ */
+export function effect(fn: () => Disposifiable | void): Disposable {
+    let cleanup: Disposable | undefined;
+    const computed = new 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.
+ *
+ * @experimental
+ */
+export function asyncComputed<A>(
+    fn: (abort: AbortSignal) => Promise<A>,
+    options?: Options<A>,
+): Promise<Computed<A>> {
+    const result = Promise.withResolvers<Computed<A>>();
+    const stream = computed(() =>
+        AbortablePromise.run<A>((resolve, reject, abort) => {
+            try {
+                fn(abort).then(resolve, reject);
+            } catch (e) {
+                reject(e as Error);
+            }
+        }),
+    );
+    const sig = new State<Result<A, Error>>(Err(new Error()));
+    let job: AbortablePromise<A> | undefined = undefined;
+    let resolved = false;
+    const resolve = () => {
+        if (!resolved) {
+            resolved = true;
+            result.resolve(computed(() => sig.get().unwrapExact(), options));
+        }
+    };
+    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;
+}
+
+/**
+ * Create a new {@link Signal.Array} and optionally populate it from the
+ * provided {@link Iterable}.
+ */
+export function array<A>(values?: Iterable<A>): SignalArray<A> {
+    return values === undefined ? new SignalArray() : SignalArray.from(values);
+}
+
+/**
+ * Create a new {@link Signal.Map} and optionally populate it from the
+ * provided {@link Iterable}.
+ */
+export function map<K, V>(entries?: Iterable<[K, V]>): SignalMap<K, V> {
+    return new SignalMap(entries);
+}
+
+export {
+    SignalArray as Array,
+    ReadonlySignalArray as ReadonlyArray,
+    SignalMap as Map,
+    ReadonlySignalMap as ReadonlyMap,
+};