@manyducks.co/dolla 0.78.1 → 1.0.0

package/lib/view.d.ts

@@ -1,19 +1,19 @@
 import { type AppContext, type ElementContext } from "./app.js";
 import { type DebugChannel } from "./classes/DebugHub.js";
 import { type DOMHandle, type Markup } from "./markup.js";
-import { type Readable, type ReadableValues, type MaybeReadable } from "./state.js";
+import { type MaybeSignal, Signal, type SignalValues, type StopFunction } from "./signals.js";
 import { type Store } from "./store.js";
 import type { BuiltInStores } from "./types.js";
 /**
  * Any valid value that a View can return.
  */
-export type ViewResult = Node | Readable<any> | Markup | Markup[] | null;
+export type ViewResult = Node | Signal<any> | Markup | Markup[] | null;
 export type View<P> = (props: P, context: ViewContext) => ViewResult;
 export interface ViewContext extends DebugChannel {
     /**
      * A string ID unique to this view.
      */
-    readonly uniqueId: string;
+    readonly uid: string;
     /**
      * Returns the shared instance of `store`.
      */
@@ -24,20 +24,32 @@ export interface ViewContext extends DebugChannel {
     getStore<N extends keyof BuiltInStores>(name: N): BuiltInStores[N];
     /**
      * Runs `callback` just before this view is connected. DOM nodes are not yet attached to the page.
+     * @deprecated
      */
     beforeConnect(callback: () => void): void;
     /**
      * Runs `callback` after this view is connected. DOM nodes are now attached to the page.
+     * @deprecated use onMount
      */
     onConnected(callback: () => void): void;
     /**
      * Runs `callback` just before this view is disconnected. DOM nodes are still attached to the page.
+     * @deprecated
      */
     beforeDisconnect(callback: () => void): void;
     /**
      * Runs `callback` after this view is disconnected. DOM nodes are no longer attached to the page.
+     * @deprecated use onUnmount
      */
     onDisconnected(callback: () => void): void;
+    /**
+     * Registers a callback to run just after this view is mounted.
+     */
+    onMount(callback: () => void): void;
+    /**
+     * Registers a callback to run just after this view is unmounted.
+     */
+    onUnmount(callback: () => void): void;
     /**
      * The name of this view for logging and debugging purposes.
      */
@@ -47,23 +59,10 @@ export interface ViewContext extends DebugChannel {
      */
     crash(error: Error): void;
     /**
-     * Observes a readable value while this view is connected. Calls `callback` each time the value changes.
-     */
-    observe<T>(state: MaybeReadable<T>, callback: (currentValue: T) => void): void;
-    /**
-     * Observes a set of readable values while this view is connected.
-     * Calls `callback` with each value in the same order as `readables` each time any of their values change.
+     * Watch a set of signals. The callback is called when any of the signals receive a new value.
+     * Watchers will be stopped when this view is unmounted. Returns a function to stop watching early.
      */
-    observe<T extends MaybeReadable<any>[]>(states: [...T], callback: (...currentValues: ReadableValues<T>) => void): void;
-    observe<I1, I2>(state1: MaybeReadable<I1>, state2: MaybeReadable<I2>, callback: (value1: I1, value2: I2) => void): void;
-    observe<I1, I2, I3>(state1: MaybeReadable<I1>, state2: MaybeReadable<I2>, state3: MaybeReadable<I3>, callback: (value1: I1, value2: I2, value3: I3) => void): void;
-    observe<I1, I2, I3, I4>(state1: MaybeReadable<I1>, state2: MaybeReadable<I2>, state3: MaybeReadable<I3>, state4: MaybeReadable<I4>, callback: (value1: I1, value2: I2, value3: I3, value4: I4) => void): void;
-    observe<I1, I2, I3, I4, I5>(state1: MaybeReadable<I1>, state2: MaybeReadable<I2>, state3: MaybeReadable<I3>, state4: MaybeReadable<I4>, state5: MaybeReadable<I5>, callback: (value1: I1, value2: I2, value3: I3, value4: I4, value5: I5) => void): void;
-    observe<I1, I2, I3, I4, I5, I6>(state1: MaybeReadable<I1>, state2: MaybeReadable<I2>, state3: MaybeReadable<I3>, state4: MaybeReadable<I4>, state5: MaybeReadable<I5>, state6: MaybeReadable<I6>, callback: (value1: I1, value2: I2, value3: I3, value4: I4, value5: I5, value6: I6) => void): void;
-    observe<I1, I2, I3, I4, I5, I6, I7>(state1: MaybeReadable<I1>, state2: MaybeReadable<I2>, state3: MaybeReadable<I3>, state4: MaybeReadable<I4>, state5: MaybeReadable<I5>, state6: MaybeReadable<I6>, state7: MaybeReadable<I7>, callback: (value1: I1, value2: I2, value3: I3, value4: I4, value5: I5, value6: I6, value7: I7) => void): void;
-    observe<I1, I2, I3, I4, I5, I6, I7, I8>(state1: MaybeReadable<I1>, state2: MaybeReadable<I2>, state3: MaybeReadable<I3>, state4: MaybeReadable<I4>, state5: MaybeReadable<I5>, state6: MaybeReadable<I6>, state7: MaybeReadable<I7>, state8: MaybeReadable<I8>, callback: (value1: I1, value2: I2, value3: I3, value4: I4, value5: I5, value6: I6, value7: I7, value8: I8) => void): void;
-    observe<I1, I2, I3, I4, I5, I6, I7, I8, I9>(state1: MaybeReadable<I1>, state2: MaybeReadable<I2>, state3: MaybeReadable<I3>, state4: MaybeReadable<I4>, state5: MaybeReadable<I5>, state6: MaybeReadable<I6>, state7: MaybeReadable<I7>, state8: MaybeReadable<I8>, state9: MaybeReadable<I9>, callback: (value1: I1, value2: I2, value3: I3, value4: I4, value5: I5, value6: I6, value7: I7, value8: I8, value9: I9) => void): void;
-    observe<I1, I2, I3, I4, I5, I6, I7, I8, I9, I10>(state1: MaybeReadable<I1>, state2: MaybeReadable<I2>, state3: MaybeReadable<I3>, state4: MaybeReadable<I4>, state5: MaybeReadable<I5>, state6: MaybeReadable<I6>, state7: MaybeReadable<I7>, state8: MaybeReadable<I8>, state9: MaybeReadable<I9>, state10: MaybeReadable<I10>, callback: (value1: I1, value2: I2, value3: I3, value4: I4, value5: I5, value6: I6, value7: I7, value8: I8, value9: I9, value10: I10) => void): void;
+    watch<T extends MaybeSignal<any>[]>(signals: [...T], callback: (...values: SignalValues<T>) => void): StopFunction;
     /**
      * Returns a Markup element that displays this view's children.
      */

package/notes/scratch.md

@@ -0,0 +1,76 @@
+# Scratch Note
+
+```tsx
+// import { signal, computed } from "@manyducks.co/dolla";
+
+function signal(initialValue, options = {}) {}
+
+function computed();
+
+function WhateverView(props, c) {
+  // IDEA: Have state, computed and effect be methods on the view context.
+  // PROBLEM: Then what are the types when passing as props? State? ComputedState? or just a generic Dynamic<T> for readable/writable?
+
+  // Context variables (replacement for stores)
+  c.set("name", {
+    value: 5,
+  });
+
+  // Can get in the same context scope or on a child.
+  // Throws an error if value is not set.
+  c.get("name");
+
+  // If we use this $readable and set function pattern then we only have a single type of signal which is read-only.
+  // Take props as Signal<T> and deal with setting in callbacks. Simple and predictable.
+  const [$count, setCount] = signal(5);
+
+  const $doubled = derived($count, (value) => value * 2);
+
+  // const watcher = new SignalWatcher($count, (value) => {
+  //   c.debug.log("watcher received value: " + value);
+  // });
+
+  // watcher.start();
+  // watcher.stop();
+
+  $count.get(); // returns the current value
+  setCount(10); // updates the value
+
+  // Observe and trigger side effects.
+  c.watch($count, (count) => {
+    c.debug.log(`The value of count is: ${count}`);
+  });
+
+  // Exposes language and translation tools.
+  c.i18n.translate$("");
+  c.i18n.$language;
+  c.i18n.setLanguage();
+
+  // Exposes internal HTTP client.
+  c.http.get(); // put, post, patch, delete, etc.
+
+  // Exposes router helpers and variables.
+  c.route.go("/");
+  c.route.$params;
+  c.route.$path;
+  c.route.$query;
+  c.route.setQuery({
+    value: 1,
+  });
+
+  return html`
+    <h1>This is the template</h1>
+
+    ${render($count, (count) => {
+      // Render rebuilds the markup within when any of the dependencies change.
+      return html`<p>The count is ${count}</p>`;
+
+      // Other view helpers are also provided as exports
+      repeat();
+      cond();
+      outlet();
+      portal();
+    })}
+  `;
+}
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@manyducks.co/dolla",
-  "version": "0.78.1",
+  "version": "1.0.0",
   "description": "Front-end components, routing and state management.",
   "main": "lib/index.js",
   "types": "./index.d.ts",

package/tests/signals.test.js

@@ -0,0 +1,135 @@
+import test from "node:test";
+import assert from "node:assert";
+
+import { signal, derive } from "../lib/index.js";
+
+test("signal", (t) => {
+  const [$count, setCount] = signal(5);
+
+  const defaultWatcher = t.mock.fn();
+  const stopDefault = $count.watch(defaultWatcher);
+
+  const lazyWatcher = t.mock.fn();
+  const stopLazy = $count.watch(lazyWatcher, { lazy: true });
+
+  assert.equal(defaultWatcher.mock.callCount(), 1, "watcher is called immediately by default");
+  assert.equal(lazyWatcher.mock.callCount(), 0, "lazy watcher is not called immediately");
+
+  assert.equal($count.get(), 5, "get returns the initial value");
+
+  setCount(12);
+
+  assert.equal($count.get(), 12, "setter updates the signal value");
+
+  assert.equal(defaultWatcher.mock.callCount(), 2, "default watcher is called");
+  assert.equal(lazyWatcher.mock.callCount(), 1, "lazy watcher is called");
+
+  assert.deepStrictEqual(defaultWatcher.mock.calls[1].arguments, [12], "default watcher is called with new value");
+  assert.deepStrictEqual(lazyWatcher.mock.calls[0].arguments, [12], "lazy watcher is called with new value");
+
+  setCount(12);
+
+  assert.equal(defaultWatcher.mock.callCount(), 2, "default watcher was not called with same value");
+  assert.equal(lazyWatcher.mock.callCount(), 1, "lazy watcher was not called with same value");
+
+  stopDefault();
+  stopLazy();
+
+  setCount(51);
+
+  assert.equal(defaultWatcher.mock.callCount(), 2, "default watcher has not been called again");
+  assert.equal(lazyWatcher.mock.callCount(), 1, "lazy watcher has not been called again");
+});
+
+test("derive", (t) => {
+  const [$one, setOne] = signal(5);
+  const [$two, setTwo] = signal(20);
+
+  const deriveSum = t.mock.fn((one, two) => one + two);
+  const deriveProduct = t.mock.fn((one, two) => one * two);
+
+  const $sum = derive([$one, $two], deriveSum);
+  const $product = derive([$one, $two], deriveProduct);
+
+  assert.equal($sum.get(), 25, "sum is calculated correctly");
+  assert.equal($product.get(), 100, "product is calculated correctly");
+
+  assert.equal(deriveSum.mock.callCount(), 1, "derive function has only been called once");
+
+  $sum.get();
+  $sum.get();
+  $sum.get();
+
+  assert.equal(deriveSum.mock.callCount(), 1, "derive function still only called once as dependencies haven't changed");
+
+  const defaultWatcher = t.mock.fn();
+  const stopDefault = $sum.watch(defaultWatcher);
+
+  const lazyWatcher = t.mock.fn();
+  const stopLazy = $product.watch(lazyWatcher, { lazy: true });
+
+  assert.equal(defaultWatcher.mock.callCount(), 1, "default watcher has been called");
+  assert.equal(lazyWatcher.mock.callCount(), 0, "lazy watcher has not been called yet");
+
+  assert.deepStrictEqual(defaultWatcher.mock.calls[0].arguments, [25], "default watcher was called with initial value");
+
+  setOne(6);
+
+  assert.equal(defaultWatcher.mock.callCount(), 2, "default watcher has been called");
+  assert.equal(lazyWatcher.mock.callCount(), 1, "lazy watcher has been called");
+
+  assert.deepStrictEqual(defaultWatcher.mock.calls[1].arguments, [26], "default watcher was called with new value");
+  assert.deepStrictEqual(lazyWatcher.mock.calls[0].arguments, [120], "lazy watcher was called with new value");
+
+  setTwo(20);
+
+  assert.equal(defaultWatcher.mock.callCount(), 2, "default watcher was not called with same value");
+  assert.equal(lazyWatcher.mock.callCount(), 1, "lazy watcher was not called with same value");
+
+  stopDefault();
+  stopLazy();
+
+  setOne(4);
+
+  assert.equal(defaultWatcher.mock.callCount(), 2, "default watcher was not called after stop");
+  assert.equal(lazyWatcher.mock.callCount(), 1, "lazy watcher was not called after stop");
+
+  assert.equal($sum.get(), 24, "sum is derived correctly");
+  assert.equal($product.get(), 80, "product is derived correctly");
+
+  assert.equal(deriveSum.mock.callCount(), 3, "sum has only been derived three times");
+});
+
+test("derive nested signals", (t) => {
+  const [$value, setValue] = signal(5);
+
+  const [$object, setObject] = signal({
+    href: derive([$value], (value) => `/projects/${value}/test`),
+  });
+
+  // o.href here is itself a derived value
+  const $href = derive([$object], (o) => o.href);
+
+  const watcher = t.mock.fn();
+  const stop = $href.watch(watcher);
+
+  assert.equal(watcher.mock.callCount(), 1);
+  assert.deepStrictEqual(watcher.mock.calls[0].arguments, ["/projects/5/test"]);
+
+  // Update value which href depends on.
+  setValue(12);
+
+  assert.equal(watcher.mock.callCount(), 2);
+  assert.deepStrictEqual(watcher.mock.calls[1].arguments, ["/projects/12/test"]);
+
+  // Now set the original object and replace the derived href.
+  // See that watcher still receives the latest value.
+  setObject({
+    href: derive([$value], (value) => `/projects/${value}/changed`),
+  });
+
+  assert.equal(watcher.mock.callCount(), 3);
+  assert.deepStrictEqual(watcher.mock.calls[2].arguments, ["/projects/12/changed"]);
+
+  stop();
+});

package/tests/state.test.js

@@ -1,290 +0,0 @@
-import test from "node:test";
-import assert from "node:assert";
-import { $, $$, observe, unwrap, isReadable, isWritable } from "../lib/index.js";
-
-test("isReadable, isWritable: returns correct results", (t) => {
-  const $$writable = $$(5);
-  const $readable = $($$writable);
-  const $computed = $($readable, (x) => x * 2);
-
-  assert.strictEqual(isWritable($$writable), true);
-  assert.strictEqual(isReadable($$writable), true);
-
-  assert.strictEqual(isWritable($readable), false);
-  assert.strictEqual(isReadable($readable), true);
-
-  assert.strictEqual(isWritable($computed), false);
-  assert.strictEqual(isReadable($computed), true);
-});
-
-test("readable, writable, computed: basic functionality", (t) => {
-  const $$writable = $$("writable");
-  const $readable = $("test");
-  const $x = $($readable, (v) => v.toUpperCase());
-  const $y = $($$writable);
-
-  const compute = t.mock.fn((x, y) => {
-    return x + y;
-  });
-
-  const $computed = $([$x, $y], compute);
-
-  assert.strictEqual($computed.get(), "TESTwritable");
-
-  const observer = t.mock.fn();
-  const stop = observe($$writable, observer); // Observer is called immediately with the current value.
-
-  $$writable.set("new value"); // First observed change (second call)
-  $$writable.set("new value 2"); // Second observed change (third call)
-
-  assert.strictEqual($$writable.get(), "new value 2");
-  assert.strictEqual($computed.get(), "TESTnew value 2");
-
-  assert.strictEqual(unwrap($$writable), "new value 2");
-  assert.strictEqual(unwrap("value"), "value");
-
-  stop();
-
-  $$writable.set("can you hear me now?"); // Sets value but is not observed.
-
-  assert.strictEqual($$writable.get(), "can you hear me now?");
-  assert.strictEqual($computed.get(), "TESTcan you hear me now?");
-
-  assert.strictEqual(observer.mock.calls.length, 3);
-  assert.deepEqual(observer.mock.calls[0].arguments, ["writable"]);
-  assert.deepEqual(observer.mock.calls[1].arguments, ["new value"]);
-  assert.deepEqual(observer.mock.calls[2].arguments, ["new value 2"]);
-});
-
-test("writable -> readable -> readable: chained transforms", (t) => {
-  const $$number = $$(5);
-  const $doubled = $($$number, (x) => x * 2);
-  const $quadrupled = $($doubled, (x) => x * 2);
-  const observer = t.mock.fn();
-
-  assert.strictEqual($doubled.get(), 10);
-  assert.strictEqual($quadrupled.get(), 20);
-
-  const stop = observe($quadrupled, observer);
-
-  assert.strictEqual(observer.mock.calls.length, 1);
-  assert.deepEqual(observer.mock.calls[0].arguments, [20]);
-
-  $$number.set(50);
-
-  assert.strictEqual(observer.mock.calls.length, 2);
-  assert.deepEqual(observer.mock.calls[1].arguments, [200]);
-
-  stop();
-
-  $$number.set(100);
-
-  assert.strictEqual($quadrupled.get(), 400);
-
-  // Not called again after stop().
-  assert.strictEqual(observer.mock.calls.length, 2);
-});
-
-test("writable: update", (t) => {
-  const $$numbers = $$(["one", "two", "three"]);
-
-  const original = $$numbers.get();
-
-  $$numbers.update((list) => [...list, "four"]);
-
-  const updated = $$numbers.get();
-
-  assert.notDeepEqual(original, updated);
-  assert.strictEqual(updated.length, 4);
-});
-
-test("readable, writable, computed: observer called with initial value when registered", (t) => {
-  const $$value = $$(1);
-  const $value = $(5);
-  const $doubled = $($value, (x) => x * 2);
-  const $multi = $([$value, $doubled], (x, y) => x + y);
-
-  // Writable
-  const wObserver = t.mock.fn();
-  const wStop = observe($$value, wObserver);
-  assert.strictEqual(wObserver.mock.calls.length, 1);
-  assert.deepEqual(wObserver.mock.calls[0].arguments, [1]);
-  wStop();
-
-  // Readable
-  const rObserver = t.mock.fn();
-  const rStop = observe($value, rObserver);
-  assert.strictEqual(rObserver.mock.calls.length, 1);
-  assert.deepEqual(rObserver.mock.calls[0].arguments, [5]);
-  rStop();
-
-  // Computed (single source)
-  const cObserver1 = t.mock.fn();
-  const cStop1 = observe($doubled, cObserver1);
-  assert.strictEqual(cObserver1.mock.calls.length, 1);
-  assert.deepEqual(cObserver1.mock.calls[0].arguments, [10]);
-  cStop1();
-
-  // Computed (multi source)
-  const cObserver2 = t.mock.fn();
-  const cStop2 = observe($multi, cObserver2);
-  assert.strictEqual(cObserver2.mock.calls.length, 1);
-  assert.deepEqual(cObserver2.mock.calls[0].arguments, [15]);
-  cStop2();
-});
-
-test("computed: basic functionality", (t) => {
-  const $$one = $$(2);
-  const $$two = $$(4);
-  const $$three = $$(8);
-
-  const joinFirst = t.mock.fn((one, two) => {
-    return one + two;
-  });
-  const $first = $([$$one, $$two], joinFirst);
-
-  const joinSecond = t.mock.fn((one, two, three) => {
-    return one + two + three;
-  });
-  const $second = $([$$one, $$two, $$three], joinSecond);
-
-  assert.strictEqual($first.get(), 6);
-  assert.strictEqual($second.get(), 14);
-
-  assert.strictEqual(joinFirst.mock.callCount(), 1);
-  assert.strictEqual(joinSecond.mock.callCount(), 1);
-
-  const observer = t.mock.fn();
-  const stop = observe($second, observer);
-
-  assert.strictEqual(observer.mock.callCount(), 1);
-  assert.deepEqual(observer.mock.calls[0].arguments, [14]); // Observer receives initial value.
-  assert.strictEqual(joinSecond.mock.callCount(), 2);
-
-  $$two.set(16);
-
-  assert.strictEqual(joinFirst.mock.callCount(), 1);
-  assert.strictEqual(joinSecond.mock.callCount(), 3);
-
-  assert.strictEqual($first.get(), 18);
-  assert.strictEqual($second.get(), 26);
-
-  assert.strictEqual(joinFirst.mock.callCount(), 2);
-  assert.strictEqual(joinSecond.mock.callCount(), 3);
-
-  assert.strictEqual(observer.mock.callCount(), 2); // Observer received value.
-  assert.deepEqual(observer.mock.calls[1].arguments, [26]);
-
-  stop();
-
-  $$one.set(32);
-
-  assert.strictEqual($first.get(), 48);
-  assert.strictEqual($second.get(), 56);
-
-  assert.strictEqual(joinFirst.mock.callCount(), 3);
-  assert.strictEqual(joinSecond.mock.callCount(), 4);
-
-  assert.strictEqual(observer.mock.callCount(), 2); // Not called after stop()
-});
-
-test("computed: observers received value when undefined", (t) => {
-  const $$one = $$(true);
-  const $$two = $$(false);
-
-  const $joined = $([$$one, $$two], (one, two) => {
-    if (one && two) {
-      return true;
-    }
-    if (!one && !two) {
-      return false;
-    }
-  });
-
-  assert.strictEqual($joined.get(), undefined);
-
-  const observer = t.mock.fn();
-  const stop = observe($joined, observer);
-
-  assert.strictEqual(observer.mock.calls.length, 1);
-  assert.deepEqual(observer.mock.calls[0].arguments, [undefined]);
-
-  $$two.set(true);
-
-  assert.strictEqual($joined.get(), true);
-  assert.strictEqual(observer.mock.calls.length, 2);
-  assert.deepEqual(observer.mock.calls[1].arguments, [true]);
-
-  $$one.set(false);
-
-  assert.strictEqual($joined.get(), undefined);
-  assert.strictEqual(observer.mock.calls.length, 3);
-  assert.deepEqual(observer.mock.calls[2].arguments, [undefined]);
-
-  stop();
-
-  $$two.set(false);
-
-  assert.strictEqual($joined.get(), false);
-
-  assert.strictEqual(observer.mock.calls.length, 3); // Not called again after stop()
-});
-
-test("computed: observer only gets new values when they are different", (t) => {
-  const $$source = $$({ name: "Jimbo Jones", age: 346 });
-  const $age = $($$source, (x) => x.age);
-
-  const ageObserver = t.mock.fn();
-  const stop = observe($age, ageObserver);
-
-  assert.strictEqual(ageObserver.mock.calls.length, 1);
-  assert.deepEqual(ageObserver.mock.calls[0].arguments, [346]);
-
-  $$source.update((current) => {
-    return { ...current, name: "Not Jimbo Jones" };
-  });
-
-  assert.strictEqual(ageObserver.mock.calls.length, 1); // Age has not changed, so shouldn't be observed again.
-
-  $$source.update((current) => {
-    return { ...current, age: 347 };
-  });
-
-  assert.strictEqual(ageObserver.mock.calls.length, 2); // Age change should have been observed.
-  assert.deepEqual(ageObserver.mock.calls[1].arguments, [347]);
-
-  stop();
-});
-
-test("proxy", (t) => {
-  const $$numbers = $$([1, 2, 3]);
-  const $$hasTwo = $$($$numbers, {
-    get() {
-      return $$numbers.get().includes(2);
-    },
-    set(value) {
-      $$numbers.update((numbers) => {
-        if (value && !numbers.includes(2)) {
-          return [...numbers, 2].sort();
-        }
-        if (!value && numbers.includes(2)) {
-          return numbers.filter((n) => n !== 2);
-        }
-        return numbers;
-      });
-    },
-  });
-
-  assert.deepEqual($$numbers.get(), [1, 2, 3]);
-  assert.strictEqual($$hasTwo.get(), true, "numbers should contain 2");
-
-  $$hasTwo.set(false);
-
-  assert.deepEqual($$numbers.get(), [1, 3]);
-  assert.strictEqual($$hasTwo.get(), false, "numbers should not contain 2");
-
-  $$hasTwo.set(true);
-
-  assert.deepEqual($$numbers.get(), [1, 2, 3]);
-  assert.strictEqual($$hasTwo.get(), true, "numbers should again contain 2");
-});