@manyducks.co/dolla 0.67.0

package/lib/utils.d.ts

@@ -0,0 +1,14 @@
+export declare function deepEqual(one: any, two: any): boolean;
+/**
+ * Takes an old value and a new value.  Returns a merged copy if both are objects, otherwise returns the new value.
+ */
+export declare function merge(one: unknown, two: unknown): any;
+/**
+ * Returns a new object without the specified keys.
+ * If called without object, returns a function that takes an object
+ * and returns a version with the original keys omitted.
+ *
+ * @param keys - An array of keys to omit.
+ * @param object - An object to clone without the omitted keys.
+ */
+export declare function omit<O extends Record<any, any>>(keys: (keyof O)[], object: O): Record<any, any>;

package/lib/view.d.ts

@@ -0,0 +1,80 @@
+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 } from "./state.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 View<P> = (props: P, context: ViewContext) => ViewResult;
+export interface ViewContext extends DebugChannel {
+    /**
+     * A string ID unique to this view.
+     */
+    readonly uniqueId: string;
+    /**
+     * Returns the shared instance of `store`.
+     */
+    getStore<T extends Store<any, any>>(store: T): ReturnType<T>;
+    /**
+     * Returns the shared instance of a built-in store.
+     */
+    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.
+     */
+    beforeConnect(callback: () => void): void;
+    /**
+     * Runs `callback` after this view is connected. DOM nodes are now attached to the page.
+     */
+    onConnected(callback: () => void): void;
+    /**
+     * Runs `callback` just before this view is disconnected. DOM nodes are still attached to the page.
+     */
+    beforeDisconnect(callback: () => void): void;
+    /**
+     * Runs `callback` after this view is disconnected. DOM nodes are no longer attached to the page.
+     */
+    onDisconnected(callback: () => void): void;
+    /**
+     * The name of this view for logging and debugging purposes.
+     */
+    name: string;
+    /**
+     * Takes an Error object, unmounts the app and displays its crash page.
+     */
+    crash(error: Error): void;
+    /**
+     * Observes a readable value while this view is connected. Calls `callback` each time the value changes.
+     */
+    observe<T>(readable: Readable<T>, callback: (currentValue: T, previousValue: 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.
+     */
+    observe<T extends Readable<any>[]>(readables: [...T], callback: (currentValues: ReadableValues<T>, previousValues: ReadableValues<T>) => void): void;
+    /**
+     * Returns a Markup element that displays this view's children.
+     */
+    outlet(): Markup;
+}
+export interface ViewContextSecrets {
+    appContext: AppContext;
+    elementContext: ElementContext;
+}
+export declare function getViewSecrets(ctx: ViewContext): ViewContextSecrets;
+export declare function view<P>(callback: View<P>): View<P>;
+/**
+ * Parameters passed to the makeView function.
+ */
+interface ViewConfig<P> {
+    view: View<P>;
+    appContext: AppContext;
+    elementContext: ElementContext;
+    props: P;
+    children?: Markup[];
+}
+export declare function initView<P>(config: ViewConfig<P>): DOMHandle;
+export {};

package/lib/views/fragment.d.ts

@@ -0,0 +1,2 @@
+import { type ViewContext } from "../view.js";
+export declare function Fragment(_: {}, ctx: ViewContext): import("../markup.js").Markup;

package/lib/views/store-scope.d.ts

@@ -0,0 +1,10 @@
+import { Store } from "../store.js";
+import { ViewContext } from "../view.js";
+export interface StoreScopeProps<O, E> {
+    store: Store<O, E>;
+    options?: O;
+}
+/**
+ * Creates an instance of a store available only to children of this StoreScope.
+ */
+export declare function StoreScope<O, E>(props: StoreScopeProps<O, E>, ctx: ViewContext): import("../markup.js").Markup;

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@manyducks.co/dolla",
+  "version": "0.67.0",
+  "description": "Front-end components, routing and state management.",
+  "main": "lib/index.js",
+  "types": "./index.d.ts",
+  "type": "module",
+  "sideEffects": false,
+  "repository": "https://github.com/manyducksco/dolla",
+  "scripts": {
+    "test": "tsc && node --test",
+    "build": "tsc && node build.js",
+    "start": "tsc --watch",
+    "prepublishOnly": "NODE_ENV=production npm run build"
+  },
+  "keywords": [
+    "web app",
+    "front end framework",
+    "functional",
+    "reactive state"
+  ],
+  "author": "tony@manyducks.co",
+  "license": "MIT",
+  "exports": {
+    ".": {
+      "import": "./lib/index.js",
+      "types": "./index.d.ts"
+    },
+    "./testing": {
+      "import": "./lib/testing/index.js"
+    },
+    "./jsx-runtime": {
+      "import": "./lib/jsx/jsx-runtime.js",
+      "types": "./jsx-runtime.d.ts"
+    },
+    "./jsx-dev-runtime": {
+      "import": "./lib/jsx/jsx-dev-runtime.js",
+      "types": "./jsx-dev-runtime.d.ts"
+    }
+  },
+  "dependencies": {
+    "@borf/bedrock": "^3.1.0",
+    "fetch-ponyfill": "^7.1.0",
+    "history": "^5.3.0",
+    "nanoid": "^4.0.2",
+    "simple-color-hash": "^1.0.2"
+  },
+  "devDependencies": {
+    "@types/node": "^18.17.6",
+    "csstype": "^3.1.2",
+    "esbuild": "^0.19.2",
+    "prettier": "^2.8.8",
+    "typescript": "^5.2.2",
+    "zod": "^3.22.2"
+  }
+}

package/tests/state.test.js

@@ -0,0 +1,290 @@
+import test from "node:test";
+import assert from "node:assert";
+import { proxy, observe, readable, writable, computed, unwrap, isReadable, isWritable } from "../lib/index.js";
+
+test("isReadable, isWritable: returns correct results", (t) => {
+  const $$writable = writable(5);
+  const $readable = readable($$writable);
+  const $computed = 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("writable");
+  const $readable = readable("test");
+  const $x = computed($readable, (v) => v.toUpperCase());
+  const $y = readable($$writable);
+
+  const compute = t.mock.fn(([x, y]) => {
+    return x + y;
+  });
+
+  const $computed = 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", undefined]);
+  assert.deepEqual(observer.mock.calls[1].arguments, ["new value", "writable"]);
+  assert.deepEqual(observer.mock.calls[2].arguments, ["new value 2", "new value"]);
+});
+
+test("writable -> readable -> readable: chained transforms", (t) => {
+  const $$number = writable(5);
+  const $doubled = computed($$number, (x) => x * 2);
+  const $quadrupled = computed($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, undefined]);
+
+  $$number.set(50);
+
+  assert.strictEqual(observer.mock.calls.length, 2);
+  assert.deepEqual(observer.mock.calls[1].arguments, [200, 20]);
+
+  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 = writable(["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 = writable(1);
+  const $value = readable(5);
+  const $doubled = computed($value, (x) => x * 2);
+  const $multi = computed([$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, undefined]);
+  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, undefined]);
+  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, undefined]);
+  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, undefined]);
+  cStop2();
+});
+
+test("computed: basic functionality", (t) => {
+  const $$one = writable(2);
+  const $$two = writable(4);
+  const $$three = writable(8);
+
+  const joinFirst = t.mock.fn(([one, two]) => {
+    return one + two;
+  });
+  const $first = computed([$$one, $$two], joinFirst);
+
+  const joinSecond = t.mock.fn(([one, two, three]) => {
+    return one + two + three;
+  });
+  const $second = computed([$$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, undefined]); // 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, 14]);
+
+  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 = writable(true);
+  const $$two = writable(false);
+
+  const $joined = computed([$$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, undefined]);
+
+  $$two.set(true);
+
+  assert.strictEqual($joined.get(), true);
+  assert.strictEqual(observer.mock.calls.length, 2);
+  assert.deepEqual(observer.mock.calls[1].arguments, [true, undefined]);
+
+  $$one.set(false);
+
+  assert.strictEqual($joined.get(), undefined);
+  assert.strictEqual(observer.mock.calls.length, 3);
+  assert.deepEqual(observer.mock.calls[2].arguments, [undefined, true]);
+
+  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 = writable({ name: "Jimbo Jones", age: 346 });
+  const $age = computed($$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, undefined]);
+
+  $$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, 346]);
+
+  stop();
+});
+
+test("proxy", (t) => {
+  const $$numbers = writable([1, 2, 3]);
+  const $$hasTwo = proxy($$numbers, {
+    get(source) {
+      return source.get().includes(2);
+    },
+    set(source, value) {
+      source.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");
+});