@bodil/signal 0.3.5 → 0.4.0

package/src/map.test.ts

@@ -0,0 +1,62 @@
+import { None, Some } from "@bodil/opt";
+import { expect, test } from "vitest";
+
+import { Signal } from ".";
+
+test("SignalMap", () => {
+    const map = Signal.map<string, string>([
+        ["Joe", "Armstrong"],
+        ["Mike", "Williams"],
+        ["Robert", "Virding"],
+    ]);
+
+    expect(map.entries().toArray()).toEqual([
+        ["Joe", "Armstrong"],
+        ["Mike", "Williams"],
+        ["Robert", "Virding"],
+    ]);
+
+    const mike = map.signal("Mike");
+    expect(mike.get()).toEqual(Some("Williams"));
+
+    const bjarne = map.signal("Bjarne");
+    expect(bjarne.get()).toEqual(None);
+
+    const size = Signal.computed(() => map.size());
+    expect(map.size()).toBe(3);
+    expect(size.get()).toBe(3);
+    expect(mike.get()).toEqual(Some("Williams"));
+    expect(bjarne.get()).toEqual(None);
+
+    map.set("Bjarne", "Däcker");
+    expect(map.size()).toBe(4);
+    expect(size.get()).toBe(4);
+    expect(mike.get()).toEqual(Some("Williams"));
+    expect(bjarne.get()).toEqual(Some("Däcker"));
+
+    expect(map.entries().toArray()).toEqual([
+        ["Joe", "Armstrong"],
+        ["Mike", "Williams"],
+        ["Robert", "Virding"],
+        ["Bjarne", "Däcker"],
+    ]);
+
+    expect(map.remove("Mike")).toEqual(Some("Williams"));
+    expect(map.size()).toBe(3);
+    expect(size.get()).toBe(3);
+    expect(mike.get()).toEqual(None);
+    expect(bjarne.get()).toEqual(Some("Däcker"));
+
+    expect(map.entries().toArray()).toEqual([
+        ["Joe", "Armstrong"],
+        ["Robert", "Virding"],
+        ["Bjarne", "Däcker"],
+    ]);
+
+    map.clear();
+    expect(map.size()).toBe(0);
+    expect(size.get()).toBe(0);
+    expect(mike.get()).toEqual(None);
+    expect(bjarne.get()).toEqual(None);
+    expect(map.entries().toArray()).toEqual([]);
+});

package/src/map.ts

@@ -0,0 +1,263 @@
+import { present } from "@bodil/core/assert";
+import type { Equals } from "@bodil/core/types";
+import { None, Some, type Option } from "@bodil/opt";
+
+import * as Signal from "./signal";
+
+const instance = Symbol("Signal.Map");
+
+type InstanceProps<K, V> = {
+    map: Map<K, V>;
+    signal: Signal.State<null>;
+    signals: Map<K, WeakRef<Signal.State<Option<V>>>>;
+    readonlySignals: WeakMap<Signal.State<Option<V>>, Signal.Computed<Option<V>>>;
+    registry: FinalizationRegistry<K>;
+};
+
+/**
+ * A read-only view of a {@link Signal.Map}.
+ *
+ * This acts just like the {@link Signal.Map} it was created from, mirroring
+ * the current contents of the source map, but without the ability to modify
+ * it.
+ */
+export class ReadonlySignalMap<K, V> implements Iterable<[K, V]>, Equals {
+    /** @ignore */
+    protected readonly [instance]: InstanceProps<K, V>;
+
+    /** @ignore */
+    protected constructor(instanceProps: InstanceProps<K, V>) {
+        this[instance] = instanceProps;
+    }
+
+    /**
+     * Test whether a value is a `Signal.ReadonlyMap`.
+     */
+    static is(value: unknown): value is ReadonlySignalMap<unknown, unknown> {
+        return value instanceof ReadonlySignalMap;
+    }
+
+    /**
+     * Obtain a {@link Signal.Computed} representing the current value of the
+     * given key in the map. The signal will update when the value changes, and
+     * will not respond to changes to any other elements of the map.
+     */
+    signal(key: K): Signal.Computed<Option<V>> {
+        const self = this[instance];
+        const active = self.signals.get(key)?.deref();
+        if (active !== undefined) {
+            return present(
+                self.readonlySignals.get(active),
+                "Signal.Map.signal(): unexpected absence of readonly signal for a signal which still exists",
+            );
+        }
+        const sig = new Signal.State(self.map.has(key) ? Some(self.map.get(key)!) : None);
+        self.registry.register(sig, key);
+        self.signals.set(key, new WeakRef(sig));
+        const roSig = sig.readOnly();
+        self.readonlySignals.set(sig, roSig);
+        return roSig;
+    }
+
+    /**
+     * Get the value associated with the given key in the map.
+     */
+    get(key: K): Option<V> {
+        return this.has(key) ? Some(this[instance].map.get(key)!) : None;
+    }
+
+    /**
+     * Test whether the given key is defined in the map.
+     */
+    has(key: K): boolean {
+        const self = this[instance];
+        self.signal.get();
+        return self.map.has(key);
+    }
+
+    /**
+     * Get the size of the map.
+     */
+    size(): number {
+        const self = this[instance];
+        self.signal.get();
+        return self.map.size;
+    }
+
+    /**
+     * Test whether the map is empty.
+     */
+    isEmpty(): boolean {
+        return this.size() === 0;
+    }
+
+    /**
+     * Iterate over the key/value pairs the map contains.
+     */
+    entries(): MapIterator<[K, V]> {
+        const self = this[instance];
+        self.signal.get();
+        return self.map.entries();
+    }
+
+    /**
+     * Iterate over the keys the map contains.
+     */
+    keys(): MapIterator<K> {
+        const self = this[instance];
+        self.signal.get();
+        return self.map.keys();
+    }
+
+    /**
+     * Iterate over the values associated with every key in the map.
+     */
+    values(): MapIterator<V> {
+        const self = this[instance];
+        self.signal.get();
+        return self.map.values();
+    }
+
+    /**
+     * Test whether a given value is a `Signal.Map` with identical contents to
+     * this map.
+     */
+    equals(other: unknown): other is ReadonlySignalMap<K, V> {
+        if (!ReadonlySignalMap.is(other) || this.size() !== other.size()) {
+            return false;
+        }
+        for (const [key, value] of this) {
+            const otherValue = other.get(key);
+            if (otherValue.isNone() || !Object.is(value, otherValue.value)) {
+                return false;
+            }
+        }
+        return true;
+    }
+
+    /**
+     * Iterate over the key/value pairs the map contains.
+     */
+    [Symbol.iterator](): MapIterator<[K, V]> {
+        const self = this[instance];
+        self.signal.get();
+        return self.map[Symbol.iterator]();
+    }
+}
+
+/**
+ * A map which behaves like a signal.
+ *
+ * Any read operation on the map, like {@link Signal.Map.get},
+ * {@link Signal.Map.size}, or iteration, acts like a
+ * {@link Signal.State.get}, registering the map as a dependency in any
+ * computed signals or effects it's used in. Correspondingly, any write
+ * operation to the map will cause all of these dependencies to update as
+ * with a {@link Signal.State.set}.
+ *
+ * Note that there's no granularity to this access by default: if you read only
+ * a single key from the map inside a computed signal, *any* write to the map,
+ * even to a different key, causes the signal to recompute. If you want
+ * granularity (and you normally do), use {@link Signal.Map.signal} instead of
+ * {@link Signal.Map.get}.
+ */
+export class SignalMap<K, V> extends ReadonlySignalMap<K, V> {
+    /**
+     * Test whether a value is a `Signal.Map`.
+     */
+    static is(value: unknown): value is SignalMap<unknown, unknown> {
+        return value instanceof SignalMap;
+    }
+
+    /**
+     * Construct a new map, optionally populating it with the provided key/value
+     * pairs.
+     */
+    constructor(entries: Iterable<readonly [K, V]> = []) {
+        const signals = new Map<K, WeakRef<Signal.State<Option<V>>>>();
+        super({
+            map: new Map(entries),
+            signal: new Signal.State(null, { equals: () => false }),
+            signals,
+            readonlySignals: new WeakMap(),
+            registry: new FinalizationRegistry((key) => signals.delete(key)),
+        });
+    }
+
+    /**
+     * Discard every key/value pair defined in the map, leaving an empty map.
+     */
+    clear(): void {
+        const self = this[instance];
+        self.map.clear();
+        self.signals.forEach((sig) => sig.deref()?.set(None));
+        self.signal.set(null);
+    }
+
+    /**
+     * Remove the given key from the map, returning its associated value. If the
+     * key isn't defined in the map, return {@link None}.
+     */
+    remove(key: K): Option<V> {
+        const self = this[instance];
+        if (!self.map.has(key)) {
+            return None;
+        }
+        const result = Some(self.map.get(key)!);
+        self.map.delete(key);
+        self.signals.get(key)?.deref()?.set(None);
+        self.signal.set(null);
+        return result;
+    }
+
+    /**
+     * Add the given key/value pair to the map, overwriting any previous
+     * definitions of the same key.
+     */
+    set(key: K, value: V): this {
+        const self = this[instance];
+        self.map.set(key, value);
+        self.signals.get(key)?.deref()?.set(Some(value));
+        self.signal.set(null);
+        return this;
+    }
+
+    /**
+     * Get the value associated with the given key, or, if the key doesn't
+     * already exist, call the provided function to create a new value and
+     * insert it into the map under the given key.
+     */
+    getOrSet(key: K, defaultFn: (this: SignalMap<K, V>) => V): V {
+        const self = this[instance];
+        self.signal.get();
+        if (self.map.has(key)) {
+            return self.map.get(key)!;
+        }
+        const value = defaultFn.call(this);
+        self.map.set(key, value);
+        self.signal.set(null);
+        return value;
+    }
+
+    /**
+     * Get a signal reflecting the value at the given key, as in
+     * {@link Signal.Map.signal}, except that if the key isn't defined,
+     * initialise it with the value produced by calling `defaultFn` first, as in
+     * {@link Signal.Map.getOrSet}.
+     */
+    signalOrSet(key: K, defaultFn: (this: SignalMap<K, V>) => V): Signal.Computed<Option<V>> {
+        const self = this[instance];
+        if (!self.map.has(key)) {
+            self.map.set(key, defaultFn.call(this));
+            self.signal.set(null);
+        }
+        return this.signal(key);
+    }
+
+    /**
+     * Return a read-only view of the map.
+     */
+    readOnly(): ReadonlySignalMap<K, V> {
+        return new ReadonlySignalMap(this[instance]);
+    }
+}

package/src/signal.test.ts

@@ -4,7 +4,7 @@ import { expect, test } from "vitest";
 import { Signal } from ".";
 
 test("Signal", async () => {
-    const sig = Signal(0);
+    const sig = Signal.state(0);
     const result: Array<number> = [];
     Signal.effect(() => void result.push(sig.value));
     expect(result).toEqual([0]);
@@ -26,7 +26,7 @@ test("Signal", async () => {
 
 test("signal equality", async () => {
     const result: Array<number> = [];
-    const sig = Signal(0);
+    const sig = Signal.state(0);
     Signal.effect(() => void result.push(sig.value));
     expect(result).toEqual([0]);
     sig.value = 1;
@@ -53,7 +53,7 @@ test("signal equality", async () => {
 });
 
 test("asyncComputed", async () => {
-    const s = Signal(1);
+    const s = Signal.state(1);
     const c = await Signal.asyncComputed(() => Promise.resolve(s.value + 1));
     expect(c.value).toEqual(2);
 
@@ -78,7 +78,7 @@ test("asyncComputed", async () => {
 });
 
 test("isSignal", () => {
-    const s1: Signal.State<number> = Signal(1);
+    const s1: Signal.State<number> = Signal.state(1);
     expect(Signal.is(s1)).toBeTruthy();
     expect(Signal.State.is(s1)).toBeTruthy();
     expect(Signal.Computed.is(s1)).toBeFalsy();
@@ -92,11 +92,11 @@ test("isSignal", () => {
 });
 
 test("Signal types", () => {
-    const s1: Signal.State<number> = Signal(1);
+    const s1: Signal.State<number> = Signal.state(1);
     const s2: Signal.Computed<number> = Signal.computed(() => s1.get());
 
-    function foo(_signal: Signal<unknown>) {
-        // ensure Signal<A> is an accessible type
+    function foo(_signal: Signal.Any<unknown>) {
+        // ensure Signal.Any<A> is an accessible type
         // and that it accepts both concrete signal types.
     }
     foo(s1);