();
-input.sink((event) => {
+inputEvents.sink((event) => {
const target = event.target as HTMLInputElement | null;
- const value = target?.value ?? null;
- if (value !== null) {
- text.send(value);
+ const value = target?.value;
+ if (value != null) {
+ inputState.send({ text: value });
}
});
@@ -32,11 +32,11 @@ const timeView = view(`{{time}}
`, { time });
const titleGroup = view(
`
-
{{text}}
-
+ {{input.text}}
+
`,
- { text, input },
+ { input: inputState, oninput: inputEvents },
);
const container = html`
diff --git a/typescript/packages/common-html/src/util.ts b/typescript/packages/common-html/src/contract.ts
similarity index 100%
rename from typescript/packages/common-html/src/util.ts
rename to typescript/packages/common-html/src/contract.ts
diff --git a/typescript/packages/common-html/src/path.ts b/typescript/packages/common-html/src/path.ts
index 04e039a28..36cf973be 100644
--- a/typescript/packages/common-html/src/path.ts
+++ b/typescript/packages/common-html/src/path.ts
@@ -1,10 +1,12 @@
-import { isObject } from "./util.js";
+import { isObject } from "./contract.js";
+import * as logger from "./logger.js";
/** A keypath is an array of property keys */
export type KeyPath = Array;
+export type NonEmptyKeyPath = [PropertyKey, ...PropertyKey[]];
export type Pathable = {
- path(keyPath: KeyPath): unknown;
+ path(keyPath: NonEmptyKeyPath): unknown;
};
/** Does value have a path method? */
@@ -20,31 +22,28 @@ export const getProp = (value: unknown, key: PropertyKey): unknown => {
return value[key as keyof typeof value] ?? undefined;
};
-/**
- * Get deep value using a key path.
- * Follows property path. Returns undefined if any key is not found.
- */
-export const get = (value: T, keyPath: KeyPath): unknown => {
- let subject = value as unknown;
- for (const key of keyPath) {
- subject = getProp(subject, key);
- if (subject == null) {
- return undefined;
- }
- }
- return subject;
-};
-
/**
* Get path on value using a keypath.
* If value is pathable, uses path method.
* Otherwise, gets properties along path.
*/
-export const path = (value: T, keyPath: KeyPath): unknown => {
+export const path = (value: unknown, keyPath: Array): unknown => {
+ if (value == null) {
+ return undefined;
+ }
+ if (keyPath.length === 0) {
+ return value;
+ }
if (isPathable(value)) {
- return value.path(keyPath);
+ const part = value.path(keyPath as NonEmptyKeyPath);
+ logger.debug("path: call path()", value, keyPath, part);
+ return part;
}
- return get(value, keyPath);
+ const [key, ...restPath] = keyPath;
+ // We checked the length, so we know this is not undefined.
+ const part = getProp(value, key);
+ logger.debug("path: get prop", value, key, part);
+ return path(part, restPath);
};
export default path;
diff --git a/typescript/packages/common-html/src/reactive.ts b/typescript/packages/common-html/src/reactive.ts
index c2ca9e6ba..9ae369431 100644
--- a/typescript/packages/common-html/src/reactive.ts
+++ b/typescript/packages/common-html/src/reactive.ts
@@ -11,6 +11,10 @@ export type Reactive = {
sink: (callback: (value: T) => void) => Cancel;
};
+export type ReactiveValue = Reactive & {
+ get(): T;
+};
+
export const isReactive = (value: unknown): value is Reactive => {
return typeof (value as Reactive)?.sink === "function";
};
diff --git a/typescript/packages/common-html/src/render.ts b/typescript/packages/common-html/src/render.ts
index 7711fed84..a651ee247 100644
--- a/typescript/packages/common-html/src/render.ts
+++ b/typescript/packages/common-html/src/render.ts
@@ -8,6 +8,7 @@ import {
Props,
Child,
isSection,
+ getContext,
} from "./view.js";
import { effect } from "./reactive.js";
import { isSendable } from "./sendable.js";
@@ -71,7 +72,7 @@ const bindChildren = (
}
} else if (isBinding(child)) {
// Bind dynamic content
- const replacement = context[child.name];
+ const replacement = getContext(context, child.path);
// Anchor for reactive replacement
let anchor: ChildNode = document.createTextNode("");
element.append(anchor);
@@ -108,17 +109,17 @@ const bindProps = (
context: Context,
): Cancel => {
const [cancel, addCancel] = useCancelGroup();
- for (const [name, value] of Object.entries(props)) {
- if (isBinding(value)) {
- const replacement = context[value.name];
+ for (const [propKey, propValue] of Object.entries(props)) {
+ if (isBinding(propValue)) {
+ const replacement = getContext(context, propValue.path);
// If prop is an event, we need to add an event listener
- if (isEventProp(name)) {
+ if (isEventProp(propKey)) {
if (!isSendable(replacement)) {
throw new TypeError(
- `Event prop "${name}" does not have a send method`,
+ `Event prop "${propKey}" does not have a send method`,
);
}
- const key = cleanEventProp(name);
+ const key = cleanEventProp(propKey);
if (key != null) {
const cancel = listen(element, key, (event) => {
const sanitizedEvent = sanitizeEvent(event);
@@ -126,18 +127,18 @@ const bindProps = (
});
addCancel(cancel);
} else {
- logger.warn("Could not bind event", name, value);
+ logger.warn("Could not bind event", propKey, propValue);
}
} else {
const cancel = effect(replacement, (replacement) => {
// Replacements are set as properties not attributes to avoid
// string serialization of complex datatypes.
- setProp(element, name, replacement);
+ setProp(element, propKey, replacement);
});
addCancel(cancel);
}
} else {
- element.setAttribute(name, value);
+ element.setAttribute(propKey, propValue);
}
}
return cancel;
diff --git a/typescript/packages/common-html/src/state.ts b/typescript/packages/common-html/src/state.ts
index 7426a5597..c0abb0dc6 100644
--- a/typescript/packages/common-html/src/state.ts
+++ b/typescript/packages/common-html/src/state.ts
@@ -1,53 +1,96 @@
-/** A simple reactive state cell without any scheduling */
-export const state = (value: T) => {
- let state = value;
- const listeners = new Set<(value: T) => void>();
+import { NonEmptyKeyPath, path } from "./path.js";
+import { ReactiveValue } from "./reactive.js";
+
+/** A one-to-many typed event publisher */
+export class Publisher {
+ #listeners = new Set<(value: T) => void>();
- const get = () => state;
+ send(value: T) {
+ for (const listener of this.#listeners) {
+ listener(value);
+ }
+ }
- const sink = (callback: (value: T) => void) => {
+ sink(callback: (value: T) => void) {
+ const listeners = this.#listeners;
listeners.add(callback);
- callback(state);
return () => {
listeners.delete(callback);
};
- };
+ }
+}
- const send = (value: T) => {
- state = value;
- for (const listener of listeners) {
- listener(state);
- }
- };
+class State {
+ #publisher = new Publisher();
+ #state: T;
- return {
- get,
- sink,
- send,
- };
-};
+ constructor(value: T) {
+ this.#state = value;
+ }
-/** A simple reactive event stream without any scheduling */
-export const stream = () => {
- const listeners = new Set<(value: T) => void>();
+ get() {
+ return this.#state;
+ }
- const sink = (callback: (value: T) => void) => {
- listeners.add(callback);
- return () => {
- listeners.delete(callback);
- };
- };
+ send(value: T) {
+ this.#state = value;
+ this.#publisher.send(value);
+ }
- const send = (value: T) => {
- for (const listener of listeners) {
- listener(value);
- }
- };
+ sink(callback: (value: T) => void) {
+ callback(this.#state);
+ return this.#publisher.sink(callback);
+ }
+
+ path(keyPath: NonEmptyKeyPath) {
+ return scope(this, (value) => path(value, keyPath));
+ }
+}
+
+/** A simple reactive state cell without any scheduling */
+export const state = (value: T) => new State(value);
+
+/**
+ * A scoped cell that represents some transformation of a state.
+ * ScopedState is a "cold" reactive value. It only does work when you subscribe
+ * to it with sink. Each sink performs computed transformation of the source
+ * state and returns a cancel function to unsubscribe.
+ */
+export class ScopedState {
+ #source: ReactiveValue;
+ #transform: (value: T) => U;
+
+ constructor(source: ReactiveValue, transform: (value: T) => U) {
+ this.#transform = transform;
+ this.#source = source;
+ }
- return {
- sink,
- send,
- };
-};
+ get() {
+ return this.#transform(this.#source.get());
+ }
+
+ sink(callback: (value: U) => void) {
+ let state: U | null = null;
+ return this.#source.sink((value) => {
+ const next = this.#transform(value);
+ if (state !== next) {
+ state = next;
+ callback(next);
+ }
+ });
+ }
+
+ path(keyPath: NonEmptyKeyPath) {
+ return scope(this, (value) => path(value, keyPath));
+ }
+}
+
+export const scope = (
+ source: ReactiveValue,
+ transform: (value: T) => U,
+) => new ScopedState(source, transform);
+
+/** A simple reactive event stream without any scheduling */
+export const stream = () => new Publisher();
export default state;
diff --git a/typescript/packages/common-html/src/view.ts b/typescript/packages/common-html/src/view.ts
index 1feecf182..3d0980e5b 100644
--- a/typescript/packages/common-html/src/view.ts
+++ b/typescript/packages/common-html/src/view.ts
@@ -1,6 +1,6 @@
import { Parser } from "htmlparser2";
import * as logger from "./logger.js";
-import { path, KeyPath } from "./path.js";
+import { path } from "./path.js";
/** Parse a markup string and context into a view */
export const view = (markup: string, context: Context): View => {
@@ -55,9 +55,7 @@ export const get = (value: unknown): unknown => {
};
/** Get context item by key */
-export const getContext = (context: Context, keyPath: KeyPath): unknown => {
- return path(context, keyPath);
-};
+export const getContext = path;
/**
* Dynamic properties. Can either be string type (static) or a Mustache
From 2049630fbf1036aab922d74283874ca154d0d0db Mon Sep 17 00:00:00 2001
From: Gordon Brander
Date: Fri, 19 Jul 2024 21:33:04 -0400
Subject: [PATCH 18/32] Scope on source and compose transform fns
---
typescript/packages/common-html/src/state.ts | 11 +++++++----
1 file changed, 7 insertions(+), 4 deletions(-)
diff --git a/typescript/packages/common-html/src/state.ts b/typescript/packages/common-html/src/state.ts
index c0abb0dc6..5e5f5dac1 100644
--- a/typescript/packages/common-html/src/state.ts
+++ b/typescript/packages/common-html/src/state.ts
@@ -50,11 +50,14 @@ class State {
/** A simple reactive state cell without any scheduling */
export const state = (value: T) => new State(value);
+export default state;
+
/**
* A scoped cell that represents some transformation of a state.
* ScopedState is a "cold" reactive value. It only does work when you subscribe
* to it with sink. Each sink performs computed transformation of the source
- * state and returns a cancel function to unsubscribe.
+ * state separately, and returns a cancel function to unsubscribe that
+ * particular sink. There are no intermediate subscriptions to cancel.
*/
export class ScopedState {
#source: ReactiveValue;
@@ -81,7 +84,9 @@ export class ScopedState {
}
path(keyPath: NonEmptyKeyPath) {
- return scope(this, (value) => path(value, keyPath));
+ return scope(this.#source, (value) =>
+ path(this.#transform(value), keyPath),
+ );
}
}
@@ -92,5 +97,3 @@ export const scope = (
/** A simple reactive event stream without any scheduling */
export const stream = () => new Publisher();
-
-export default state;
From f8f4d7484c948cb71b8cc511543c387d5d79ad65 Mon Sep 17 00:00:00 2001
From: Gordon Brander
Date: Tue, 23 Jul 2024 21:39:50 -0400
Subject: [PATCH 19/32] Base path on .key()
---
typescript/packages/common-html/src/path.ts | 31 +++++++++----------
typescript/packages/common-html/src/state.ts | 29 +++++++----------
.../common-html/src/test/path.test.ts | 10 +++---
3 files changed, 31 insertions(+), 39 deletions(-)
diff --git a/typescript/packages/common-html/src/path.ts b/typescript/packages/common-html/src/path.ts
index 36cf973be..f7b7a8d45 100644
--- a/typescript/packages/common-html/src/path.ts
+++ b/typescript/packages/common-html/src/path.ts
@@ -5,13 +5,12 @@ import * as logger from "./logger.js";
export type KeyPath = Array;
export type NonEmptyKeyPath = [PropertyKey, ...PropertyKey[]];
-export type Pathable = {
- path(keyPath: NonEmptyKeyPath): unknown;
+export type Keyable = {
+ key(key: K): T[K];
};
-/** Does value have a path method? */
-export const isPathable = (value: unknown): value is Pathable => {
- return isObject(value) && "path" in value && typeof value.path === "function";
+export const isKeyable = (value: unknown): value is Keyable => {
+ return isObject(value) && "key" in value && typeof value.key === "function";
};
/** Get value at prop. Returns undefined if key is not accessible. */
@@ -27,23 +26,23 @@ export const getProp = (value: unknown, key: PropertyKey): unknown => {
* If value is pathable, uses path method.
* Otherwise, gets properties along path.
*/
-export const path = (value: unknown, keyPath: Array): unknown => {
- if (value == null) {
+export const path = (parent: T, keyPath: Array): unknown => {
+ if (parent == null) {
return undefined;
}
if (keyPath.length === 0) {
- return value;
+ return parent;
}
- if (isPathable(value)) {
- const part = value.path(keyPath as NonEmptyKeyPath);
- logger.debug("path: call path()", value, keyPath, part);
- return part;
+ const key = keyPath.shift()!;
+ if (isKeyable(parent)) {
+ const child = parent.key(key);
+ logger.debug("path: call .key()", parent, key, child);
+ return path(child, keyPath);
}
- const [key, ...restPath] = keyPath;
// We checked the length, so we know this is not undefined.
- const part = getProp(value, key);
- logger.debug("path: get prop", value, key, part);
- return path(part, restPath);
+ const child = getProp(parent, key);
+ logger.debug("path: get prop", parent, key, child);
+ return path(child, keyPath);
};
export default path;
diff --git a/typescript/packages/common-html/src/state.ts b/typescript/packages/common-html/src/state.ts
index 5e5f5dac1..ddd9c9310 100644
--- a/typescript/packages/common-html/src/state.ts
+++ b/typescript/packages/common-html/src/state.ts
@@ -1,6 +1,3 @@
-import { NonEmptyKeyPath, path } from "./path.js";
-import { ReactiveValue } from "./reactive.js";
-
/** A one-to-many typed event publisher */
export class Publisher {
#listeners = new Set<(value: T) => void>();
@@ -20,7 +17,7 @@ export class Publisher {
}
}
-class State {
+export class State {
#publisher = new Publisher();
#state: T;
@@ -42,8 +39,8 @@ class State {
return this.#publisher.sink(callback);
}
- path(keyPath: NonEmptyKeyPath) {
- return scope(this, (value) => path(value, keyPath));
+ key(key: K) {
+ return new ScopedState(this, (value) => value[key]);
}
}
@@ -60,15 +57,15 @@ export default state;
* particular sink. There are no intermediate subscriptions to cancel.
*/
export class ScopedState {
- #source: ReactiveValue;
+ #source: State;
#transform: (value: T) => U;
- constructor(source: ReactiveValue, transform: (value: T) => U) {
+ constructor(source: State, transform: (value: T) => U) {
this.#transform = transform;
this.#source = source;
}
- get() {
+ get(): U {
return this.#transform(this.#source.get());
}
@@ -83,17 +80,13 @@ export class ScopedState {
});
}
- path(keyPath: NonEmptyKeyPath) {
- return scope(this.#source, (value) =>
- path(this.#transform(value), keyPath),
- );
+ key(key: K) {
+ return new ScopedState(this.#source, (value) => {
+ const scoped = this.#transform(value);
+ return scoped[key];
+ });
}
}
-export const scope = (
- source: ReactiveValue,
- transform: (value: T) => U,
-) => new ScopedState(source, transform);
-
/** A simple reactive event stream without any scheduling */
export const stream = () => new Publisher();
diff --git a/typescript/packages/common-html/src/test/path.test.ts b/typescript/packages/common-html/src/test/path.test.ts
index c886d8734..d59d42722 100644
--- a/typescript/packages/common-html/src/test/path.test.ts
+++ b/typescript/packages/common-html/src/test/path.test.ts
@@ -1,5 +1,5 @@
import { equal as assertEqual } from "node:assert/strict";
-import { path, KeyPath, Pathable } from "../path.js";
+import { path } from "../path.js";
describe("path", () => {
it("gets a deep path from any object", () => {
@@ -15,16 +15,16 @@ describe("path", () => {
assertEqual(path({}, ["a", "b", 0, "c"]), undefined);
});
- it("defers to `path()` implementation for Pathable types", () => {
- class Wrapper implements Pathable {
+ it("defers to `key()` implementation for Keyable types", () => {
+ class Wrapper {
#subject: T;
constructor(subject: T) {
this.#subject = subject;
}
- path(keyPath: KeyPath): unknown {
- return path(this.#subject, keyPath);
+ key(key: K): T[K] {
+ return this.#subject[key];
}
}
From 9ba28c121078bbaa26c0116e98e4cdb94b8111d0 Mon Sep 17 00:00:00 2001
From: Gordon Brander
Date: Tue, 23 Jul 2024 21:40:22 -0400
Subject: [PATCH 20/32] Add cell / propagator
---
.../packages/common-html/src/propagator.ts | 190 ++++++++++++++++++
.../common-html/src/test/propagator.test.ts | 83 ++++++++
2 files changed, 273 insertions(+)
create mode 100644 typescript/packages/common-html/src/propagator.ts
create mode 100644 typescript/packages/common-html/src/test/propagator.test.ts
diff --git a/typescript/packages/common-html/src/propagator.ts b/typescript/packages/common-html/src/propagator.ts
new file mode 100644
index 000000000..c0bad9b0a
--- /dev/null
+++ b/typescript/packages/common-html/src/propagator.ts
@@ -0,0 +1,190 @@
+import cid from "./cid.js";
+import { Cancel, Cancellable, useCancelGroup } from "./cancel.js";
+import * as logger from "./logger.js";
+
+const advanceClock = (a: number, b: number) => Math.max(a, b) + 1;
+
+export const lww = (_state: T, next: T) => next;
+
+export type LamportTime = number;
+
+export class Cell {
+ #id = cid();
+ #neighbors = new Set<(value: Value, time: LamportTime) => void>();
+ #time: LamportTime = 0;
+ #update: (state: Value, next: Value) => Value;
+ #value: Value;
+
+ constructor({
+ value,
+ update = lww,
+ }: {
+ value: Value;
+ update?: (state: Value, next: Value) => Value;
+ }) {
+ this.#update = update;
+ this.#value = value;
+ }
+
+ get id() {
+ return this.#id;
+ }
+
+ get() {
+ return this.#value;
+ }
+
+ send(value: Value, time: LamportTime = this.#time + 1): number {
+ logger.debug(`cell#${this.id}`, "Message", value, time);
+
+ // We ignore old news
+ if (this.#time >= time) {
+ logger.debug(
+ `cell#${this.id}`,
+ "Message out of date. Ignoring.",
+ value,
+ time,
+ );
+ return this.#time;
+ }
+
+ this.#time = advanceClock(this.#time, time);
+ logger.debug(`cell#${this.id}`, "Advanced clock", this.#time);
+
+ const next = this.#update(this.#value, value);
+
+ // We only advance clock if msg changed state
+ if (this.#value === next) {
+ logger.debug(`cell#${this.id}`, "Value unchanged.", this.#value);
+ return this.#time;
+ }
+
+ const prev = this.#value;
+ this.#value = next;
+ logger.debug(`cell#${this.id}`, "Value updated", prev, next);
+
+ // Notify neighbors
+ for (const neighbor of this.#neighbors) {
+ neighbor(next, this.#time);
+ }
+ logger.debug(`cell#${this.id}`, "Notified neighbors", this.#neighbors.size);
+
+ return this.#time;
+ }
+
+ /** Disconnect all neighbors */
+ disconnect() {
+ this.#neighbors.clear();
+ logger.debug(
+ `cell#${this.id}`,
+ "Disconnected all neighbors",
+ this.#neighbors.size,
+ );
+ }
+
+ sink(callback: (value: Value, time: LamportTime) => void) {
+ callback(this.#value, this.#time);
+ this.#neighbors.add(callback);
+ return () => {
+ this.#neighbors.delete(callback);
+ };
+ }
+
+ key(valueKey: K) {
+ return key(this, valueKey);
+ }
+}
+
+/** A simple reactive state cell without any scheduling */
+export const cell = ({
+ value,
+ update = lww,
+}: {
+ value: Value;
+ update?: (state: Value, next: Value) => Value;
+}) => new Cell({ value, update });
+
+export default cell;
+
+export type CancellableCell = Cell & Cancellable;
+
+export const lens = ({
+ cell: big,
+ get,
+ update,
+}: {
+ cell: Cell;
+ get: (big: B) => S;
+ update: (big: B, small: S) => B;
+}): CancellableCell => {
+ const bigValue = big.get();
+
+ const small = cell({ value: get(bigValue) });
+
+ const [cancel, addCancel] = useCancelGroup();
+
+ // Propagate writes from parent to child
+ const cancelBigToSmall = big.sink((parentValue, time) => {
+ small.send(get(parentValue), time);
+ });
+ addCancel(cancelBigToSmall);
+
+ // Propagate writes from child to parent
+ const cancelSmallToBig = small.sink((value, time) => {
+ big.send(update(big.get(), value), time);
+ });
+ addCancel(cancelSmallToBig);
+
+ const cancellableSmall = small as CancellableCell;
+ cancellableSmall.cancel = cancel;
+
+ return cancellableSmall;
+};
+
+export const key = (
+ big: Cell,
+ key: K,
+): CancellableCell =>
+ lens({
+ cell: big,
+ get: (big) => big[key],
+ update: (big, small) => ({ ...big, [key]: small }),
+ });
+
+/** Wrap an effect function so that it batches on microtask */
+const batcher = (queue = queueMicrotask) => {
+ let isScheduled = false;
+ let scheduledJob = () => {};
+
+ const perform = () => {
+ isScheduled = false;
+ scheduledJob();
+ };
+
+ return (job: () => void) => {
+ if (isScheduled) return;
+ scheduledJob = job;
+ isScheduled = true;
+ queue(perform);
+ };
+};
+
+/** Batch updates on animatinoframe */
+export const render = (
+ cell: Cell,
+ callback: (state: State) => Cancel | null,
+) => {
+ const [cancel, addCancel] = useCancelGroup();
+
+ const batch = batcher(requestAnimationFrame);
+
+ const cancelSink = cell.sink((state) => {
+ batch(() => {
+ const cancel = callback(state);
+ addCancel(cancel);
+ });
+ });
+
+ addCancel(cancelSink);
+ return cancel;
+};
diff --git a/typescript/packages/common-html/src/test/propagator.test.ts b/typescript/packages/common-html/src/test/propagator.test.ts
new file mode 100644
index 000000000..4ae705cd2
--- /dev/null
+++ b/typescript/packages/common-html/src/test/propagator.test.ts
@@ -0,0 +1,83 @@
+import {
+ equal as assertEqual,
+ deepEqual as assertDeepEqual,
+} from "node:assert/strict";
+import cell, { lens } from "../propagator.js";
+
+describe("cell()", () => {
+ it("synchronously sets the value", () => {
+ const a = cell({ value: 1 });
+ a.send(2);
+ assertEqual(a.get(), 2);
+ });
+
+ it("reacts synchronously when sent a new value", () => {
+ const a = cell({ value: 1 });
+
+ let state = 0;
+ a.sink((value) => {
+ state = value;
+ });
+ a.send(2);
+
+ assertEqual(state, 2);
+ });
+});
+
+describe("lens()", () => {
+ it("lenses over a cell", () => {
+ const x = cell({ value: { a: { b: { c: 10 } } } });
+
+ const c = lens({
+ cell: x,
+ get: (state) => state.a.b.c,
+ update: (state, next) => ({ ...state, a: { b: { c: next } } }),
+ });
+
+ c.send(20);
+
+ assertDeepEqual(x.get(), { a: { b: { c: 20 } } });
+ assertEqual(c.get(), 20);
+ });
+});
+
+describe("cell.key()", () => {
+ it("returns a typesafe cell that reflects the state of the parent", () => {
+ const x = cell({ value: { a: 10 } });
+ const a = x.key("a");
+
+ assertEqual(a.get(), 10);
+ });
+
+ it("reflects updates from parent to child", () => {
+ const x = cell({ value: { a: 10 } });
+ const a = x.key("a");
+
+ x.send({ a: 20 });
+
+ assertEqual(a.get(), 20);
+ });
+
+ it("reflects updates from child to parent", () => {
+ const x = cell({ value: { a: 10 } });
+ const a = x.key("a");
+
+ a.send(20);
+
+ assertDeepEqual(x.get(), { a: 20 });
+ });
+
+ it("it works for deep derived keys", () => {
+ const x = cell({ value: { a: { b: { c: 10 } } } });
+ const a = x.key("a");
+ const b = a.key("b");
+ const c = b.key("c");
+
+ c.send(20);
+
+ assertDeepEqual(x.get(), { a: { b: { c: 20 } } });
+ assertDeepEqual(a.get(), { b: { c: 20 } });
+ assertDeepEqual(b.get(), { c: 20 });
+ assertDeepEqual(c.get(), 20);
+ });
+});
From 9de216293ca8ffeb14bc299d09ff3a9d09442bd7 Mon Sep 17 00:00:00 2001
From: Gordon Brander
Date: Wed, 24 Jul 2024 10:54:32 -0400
Subject: [PATCH 21/32] Move render into reactive
- Add tests
- Batch on microtask instead of animationframe
- Add name to cell
- Remove ID from cell
---
.../packages/common-html/src/propagator.ts | 81 +++++++------------
.../packages/common-html/src/reactive.ts | 48 +++++++++++
.../common-html/src/test/propagator.test.ts | 7 +-
.../common-html/src/test/reactive.test.ts | 65 ++++++++++++++-
4 files changed, 144 insertions(+), 57 deletions(-)
diff --git a/typescript/packages/common-html/src/propagator.ts b/typescript/packages/common-html/src/propagator.ts
index c0bad9b0a..e417bd856 100644
--- a/typescript/packages/common-html/src/propagator.ts
+++ b/typescript/packages/common-html/src/propagator.ts
@@ -1,5 +1,4 @@
-import cid from "./cid.js";
-import { Cancel, Cancellable, useCancelGroup } from "./cancel.js";
+import { Cancellable, useCancelGroup } from "./cancel.js";
import * as logger from "./logger.js";
const advanceClock = (a: number, b: number) => Math.max(a, b) + 1;
@@ -8,8 +7,11 @@ export const lww = (_state: T, next: T) => next;
export type LamportTime = number;
+/**
+ * A cell is a reactive value that can be updated and subscribed to.
+ */
export class Cell {
- #id = cid();
+ #name: string = "";
#neighbors = new Set<(value: Value, time: LamportTime) => void>();
#time: LamportTime = 0;
#update: (state: Value, next: Value) => Value;
@@ -17,17 +19,20 @@ export class Cell {
constructor({
value,
+ name = "",
update = lww,
}: {
value: Value;
+ name?: string;
update?: (state: Value, next: Value) => Value;
}) {
+ this.#name = name;
this.#update = update;
this.#value = value;
}
- get id() {
- return this.#id;
+ get name() {
+ return this.#name;
}
get() {
@@ -35,12 +40,12 @@ export class Cell {
}
send(value: Value, time: LamportTime = this.#time + 1): number {
- logger.debug(`cell#${this.id}`, "Message", value, time);
+ logger.debug(`cell#${this.name}`, "Message", value, time);
// We ignore old news
if (this.#time >= time) {
logger.debug(
- `cell#${this.id}`,
+ `cell#${this.name}`,
"Message out of date. Ignoring.",
value,
time,
@@ -49,25 +54,29 @@ export class Cell {
}
this.#time = advanceClock(this.#time, time);
- logger.debug(`cell#${this.id}`, "Advanced clock", this.#time);
+ logger.debug(`cell#${this.name}`, "Advanced clock", this.#time);
const next = this.#update(this.#value, value);
// We only advance clock if msg changed state
if (this.#value === next) {
- logger.debug(`cell#${this.id}`, "Value unchanged.", this.#value);
+ logger.debug(`cell#${this.name}`, "Value unchanged.", this.#value);
return this.#time;
}
const prev = this.#value;
this.#value = next;
- logger.debug(`cell#${this.id}`, "Value updated", prev, next);
+ logger.debug(`cell#${this.name}`, "Value updated", prev, next);
// Notify neighbors
for (const neighbor of this.#neighbors) {
neighbor(next, this.#time);
}
- logger.debug(`cell#${this.id}`, "Notified neighbors", this.#neighbors.size);
+ logger.debug(
+ `cell#${this.name}`,
+ "Notified neighbors",
+ this.#neighbors.size,
+ );
return this.#time;
}
@@ -76,7 +85,7 @@ export class Cell {
disconnect() {
this.#neighbors.clear();
logger.debug(
- `cell#${this.id}`,
+ `cell#${this.name}`,
"Disconnected all neighbors",
this.#neighbors.size,
);
@@ -95,16 +104,18 @@ export class Cell {
}
}
-/** A simple reactive state cell without any scheduling */
+/**
+ * Create a reactive cell for a value
+ */
export const cell = ({
value,
+ name = "",
update = lww,
}: {
value: Value;
+ name?: string;
update?: (state: Value, next: Value) => Value;
-}) => new Cell({ value, update });
-
-export default cell;
+}) => new Cell({ value, name, update });
export type CancellableCell = Cell & Cancellable;
@@ -150,41 +161,3 @@ export const key = (
get: (big) => big[key],
update: (big, small) => ({ ...big, [key]: small }),
});
-
-/** Wrap an effect function so that it batches on microtask */
-const batcher = (queue = queueMicrotask) => {
- let isScheduled = false;
- let scheduledJob = () => {};
-
- const perform = () => {
- isScheduled = false;
- scheduledJob();
- };
-
- return (job: () => void) => {
- if (isScheduled) return;
- scheduledJob = job;
- isScheduled = true;
- queue(perform);
- };
-};
-
-/** Batch updates on animatinoframe */
-export const render = (
- cell: Cell,
- callback: (state: State) => Cancel | null,
-) => {
- const [cancel, addCancel] = useCancelGroup();
-
- const batch = batcher(requestAnimationFrame);
-
- const cancelSink = cell.sink((state) => {
- batch(() => {
- const cancel = callback(state);
- addCancel(cancel);
- });
- });
-
- addCancel(cancelSink);
- return cancel;
-};
diff --git a/typescript/packages/common-html/src/reactive.ts b/typescript/packages/common-html/src/reactive.ts
index 9ae369431..51c1856c0 100644
--- a/typescript/packages/common-html/src/reactive.ts
+++ b/typescript/packages/common-html/src/reactive.ts
@@ -45,3 +45,51 @@ export const effect = (
};
const noOp = () => {};
+
+/** Wrap an effect function so that it batches on microtask */
+const batcher = (queue = queueMicrotask) => {
+ let isScheduled = false;
+ let scheduledJob = () => {};
+
+ const perform = () => {
+ isScheduled = false;
+ scheduledJob();
+ };
+
+ return (job: () => void) => {
+ scheduledJob = job;
+ if (!isScheduled) {
+ isScheduled = true;
+ queue(perform);
+ }
+ };
+};
+
+/** Batch effects on microtask */
+export const render = (
+ value: unknown,
+ callback: (value: unknown) => Cancel | void,
+) => {
+ if (value == null) {
+ return noOp;
+ }
+
+ const queueRender = batcher();
+
+ let cleanup: Cancel = noOp;
+ if (isReactive(value)) {
+ const cancelSink = value.sink((value: unknown) => {
+ queueRender(() => {
+ cleanup();
+ const next = callback(value);
+ cleanup = isCancel(next) ? next : noOp;
+ });
+ });
+ return () => {
+ cancelSink();
+ cleanup();
+ };
+ }
+ const maybeCleanup = callback(value);
+ return isCancel(maybeCleanup) ? maybeCleanup : noOp;
+};
diff --git a/typescript/packages/common-html/src/test/propagator.test.ts b/typescript/packages/common-html/src/test/propagator.test.ts
index 4ae705cd2..29f767be7 100644
--- a/typescript/packages/common-html/src/test/propagator.test.ts
+++ b/typescript/packages/common-html/src/test/propagator.test.ts
@@ -2,7 +2,7 @@ import {
equal as assertEqual,
deepEqual as assertDeepEqual,
} from "node:assert/strict";
-import cell, { lens } from "../propagator.js";
+import { cell, lens } from "../propagator.js";
describe("cell()", () => {
it("synchronously sets the value", () => {
@@ -22,6 +22,11 @@ describe("cell()", () => {
assertEqual(state, 2);
});
+
+ it("has an optional name", () => {
+ const a = cell({ value: 1, name: "a" });
+ assertEqual(a.name, "a");
+ });
});
describe("lens()", () => {
diff --git a/typescript/packages/common-html/src/test/reactive.test.ts b/typescript/packages/common-html/src/test/reactive.test.ts
index 9edc07ec5..acca0d00c 100644
--- a/typescript/packages/common-html/src/test/reactive.test.ts
+++ b/typescript/packages/common-html/src/test/reactive.test.ts
@@ -1,6 +1,8 @@
import { equal as assertEqual } from "node:assert/strict";
import state from "../state.js";
-import { effect, isReactive } from "../reactive.js";
+import { effect, render, isReactive } from "../reactive.js";
+
+const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
describe("isReactive", () => {
it("returns true for any object with a sink method", () => {
@@ -19,7 +21,7 @@ describe("isReactive", () => {
});
});
-describe("effect", () => {
+describe("effect()", () => {
it("runs callback for nonreactive values", () => {
let calls = 0;
effect(10, (_value: number) => {
@@ -72,3 +74,62 @@ describe("effect", () => {
assertEqual(calls, 1);
});
});
+
+describe("render()", () => {
+ it("runs callback for nonreactive values", async () => {
+ let calls = 0;
+ render(10, (_value: number) => {
+ calls++;
+ });
+ await sleep(1);
+ assertEqual(calls, 1);
+ });
+
+ it("subscribes callback to `sink` for reactive value", async () => {
+ const value = state(10);
+
+ let valueMut = 0;
+ render(value, (value: number) => {
+ valueMut = value;
+ });
+
+ value.send(11);
+ value.send(12);
+
+ await sleep(1);
+
+ assertEqual(valueMut, 12);
+ });
+
+ it("ends subscription to reactive value when cancel is called", async () => {
+ const value = state(10);
+
+ let valueMut = 0;
+ const cancel = render(value, (value: number) => {
+ valueMut = value;
+ });
+
+ value.send(11);
+ cancel();
+ value.send(12);
+
+ await sleep(1);
+ assertEqual(valueMut, 11);
+ });
+
+ it("returns a cancel function", () => {
+ const cancel = render(10, (_value: number) => {});
+ assertEqual(typeof cancel, "function");
+ });
+
+ it("runs any returned cleanup function when cancel is run", async () => {
+ let calls = 0;
+ const cancel = render(10, (_value: number) => {
+ const cleanup = () => calls++;
+ return cleanup;
+ });
+ cancel();
+ await sleep(1);
+ assertEqual(calls, 1);
+ });
+});
From f5567ac127682220c83c8fbe2342e24f47ad2c8a Mon Sep 17 00:00:00 2001
From: Gordon Brander
Date: Wed, 24 Jul 2024 10:59:38 -0400
Subject: [PATCH 22/32] Update HTML to use propagator cell
...instead of bespoke State class.
---
.../packages/common-html/src/propagator.ts | 9 +-
typescript/packages/common-html/src/state.ts | 92 -------------------
.../common-html/src/test/html.test.ts | 4 +-
.../common-html/src/test/reactive.test.ts | 2 +-
4 files changed, 9 insertions(+), 98 deletions(-)
delete mode 100644 typescript/packages/common-html/src/state.ts
diff --git a/typescript/packages/common-html/src/propagator.ts b/typescript/packages/common-html/src/propagator.ts
index e417bd856..20761220a 100644
--- a/typescript/packages/common-html/src/propagator.ts
+++ b/typescript/packages/common-html/src/propagator.ts
@@ -104,9 +104,7 @@ export class Cell {
}
}
-/**
- * Create a reactive cell for a value
- */
+/** Create a reactive cell for a value */
export const cell = ({
value,
name = "",
@@ -117,6 +115,11 @@ export const cell = ({
update?: (state: Value, next: Value) => Value;
}) => new Cell({ value, name, update });
+export default cell;
+
+/** Create a cell with last-write-wins update semantics */
+export const state = (value: T, name = "") => cell({ value, name });
+
export type CancellableCell = Cell & Cancellable;
export const lens = ({
diff --git a/typescript/packages/common-html/src/state.ts b/typescript/packages/common-html/src/state.ts
deleted file mode 100644
index ddd9c9310..000000000
--- a/typescript/packages/common-html/src/state.ts
+++ /dev/null
@@ -1,92 +0,0 @@
-/** A one-to-many typed event publisher */
-export class Publisher {
- #listeners = new Set<(value: T) => void>();
-
- send(value: T) {
- for (const listener of this.#listeners) {
- listener(value);
- }
- }
-
- sink(callback: (value: T) => void) {
- const listeners = this.#listeners;
- listeners.add(callback);
- return () => {
- listeners.delete(callback);
- };
- }
-}
-
-export class State {
- #publisher = new Publisher();
- #state: T;
-
- constructor(value: T) {
- this.#state = value;
- }
-
- get() {
- return this.#state;
- }
-
- send(value: T) {
- this.#state = value;
- this.#publisher.send(value);
- }
-
- sink(callback: (value: T) => void) {
- callback(this.#state);
- return this.#publisher.sink(callback);
- }
-
- key(key: K) {
- return new ScopedState(this, (value) => value[key]);
- }
-}
-
-/** A simple reactive state cell without any scheduling */
-export const state = (value: T) => new State(value);
-
-export default state;
-
-/**
- * A scoped cell that represents some transformation of a state.
- * ScopedState is a "cold" reactive value. It only does work when you subscribe
- * to it with sink. Each sink performs computed transformation of the source
- * state separately, and returns a cancel function to unsubscribe that
- * particular sink. There are no intermediate subscriptions to cancel.
- */
-export class ScopedState {
- #source: State;
- #transform: (value: T) => U;
-
- constructor(source: State, transform: (value: T) => U) {
- this.#transform = transform;
- this.#source = source;
- }
-
- get(): U {
- return this.#transform(this.#source.get());
- }
-
- sink(callback: (value: U) => void) {
- let state: U | null = null;
- return this.#source.sink((value) => {
- const next = this.#transform(value);
- if (state !== next) {
- state = next;
- callback(next);
- }
- });
- }
-
- key(key: K) {
- return new ScopedState(this.#source, (value) => {
- const scoped = this.#transform(value);
- return scoped[key];
- });
- }
-}
-
-/** A simple reactive event stream without any scheduling */
-export const stream = () => new Publisher();
diff --git a/typescript/packages/common-html/src/test/html.test.ts b/typescript/packages/common-html/src/test/html.test.ts
index 4be209fea..d16583b1f 100644
--- a/typescript/packages/common-html/src/test/html.test.ts
+++ b/typescript/packages/common-html/src/test/html.test.ts
@@ -1,11 +1,11 @@
import * as assert from "node:assert";
import html from "../html.js";
import { isBinding } from "../view.js";
-import { state, stream } from "../state.js";
+import { state } from "../propagator.js";
describe("html", () => {
it("parses tagged template string into a Renderable", () => {
- const clicks = stream();
+ const clicks = state(null);
const text = state("Hello world!");
const view = html`
diff --git a/typescript/packages/common-html/src/test/reactive.test.ts b/typescript/packages/common-html/src/test/reactive.test.ts
index acca0d00c..9efc29507 100644
--- a/typescript/packages/common-html/src/test/reactive.test.ts
+++ b/typescript/packages/common-html/src/test/reactive.test.ts
@@ -1,5 +1,5 @@
import { equal as assertEqual } from "node:assert/strict";
-import state from "../state.js";
+import { state } from "../propagator.js";
import { effect, render, isReactive } from "../reactive.js";
const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
From 40fd992e90beda213534492d0329314e7ed36e98 Mon Sep 17 00:00:00 2001
From: Gordon Brander
Date: Wed, 24 Jul 2024 11:10:40 -0400
Subject: [PATCH 23/32] Add lens type
- Define propagator lens in terms of lens type.
---
typescript/packages/common-html/src/lens.ts | 12 ++++++++++
.../packages/common-html/src/propagator.ts | 24 +++++++++----------
2 files changed, 23 insertions(+), 13 deletions(-)
create mode 100644 typescript/packages/common-html/src/lens.ts
diff --git a/typescript/packages/common-html/src/lens.ts b/typescript/packages/common-html/src/lens.ts
new file mode 100644
index 000000000..1c39b350b
--- /dev/null
+++ b/typescript/packages/common-html/src/lens.ts
@@ -0,0 +1,12 @@
+export type Lens = {
+ get: (big: Big) => Small;
+ update: (big: Big, small: Small) => Big;
+};
+
+export const lens = ({ get, update }: Lens) =>
+ Object.freeze({
+ get,
+ update,
+ });
+
+export default lens;
diff --git a/typescript/packages/common-html/src/propagator.ts b/typescript/packages/common-html/src/propagator.ts
index 20761220a..8ab6bd6c4 100644
--- a/typescript/packages/common-html/src/propagator.ts
+++ b/typescript/packages/common-html/src/propagator.ts
@@ -1,5 +1,6 @@
import { Cancellable, useCancelGroup } from "./cancel.js";
import * as logger from "./logger.js";
+import { Lens } from "./lens.js";
const advanceClock = (a: number, b: number) => Math.max(a, b) + 1;
@@ -122,18 +123,16 @@ export const state = (value: T, name = "") => cell({ value, name });
export type CancellableCell = Cell & Cancellable;
-export const lens = ({
- cell: big,
- get,
- update,
-}: {
- cell: Cell;
- get: (big: B) => S;
- update: (big: B, small: S) => B;
-}): CancellableCell => {
+/**
+ * Derive a cell who's contents is transformed by a lens
+ */
+export const lens = (
+ big: Cell,
+ lens: Lens,
+): CancellableCell => {
const bigValue = big.get();
- const small = cell({ value: get(bigValue) });
+ const small = cell({ value: lens.get(bigValue) });
const [cancel, addCancel] = useCancelGroup();
@@ -145,7 +144,7 @@ export const lens = ({
// Propagate writes from child to parent
const cancelSmallToBig = small.sink((value, time) => {
- big.send(update(big.get(), value), time);
+ big.send(lens.update(big.get(), value), time);
});
addCancel(cancelSmallToBig);
@@ -159,8 +158,7 @@ export const key = (
big: Cell,
key: K,
): CancellableCell =>
- lens({
- cell: big,
+ lens(big, {
get: (big) => big[key],
update: (big, small) => ({ ...big, [key]: small }),
});
From 48c9cdc28a6dfc7f65cf4f831f71d8a117f5bc60 Mon Sep 17 00:00:00 2001
From: Gordon Brander
Date: Wed, 24 Jul 2024 11:14:19 -0400
Subject: [PATCH 24/32] Fix lens accessor
---
typescript/packages/common-html/src/propagator.ts | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/typescript/packages/common-html/src/propagator.ts b/typescript/packages/common-html/src/propagator.ts
index 8ab6bd6c4..3f7148ee9 100644
--- a/typescript/packages/common-html/src/propagator.ts
+++ b/typescript/packages/common-html/src/propagator.ts
@@ -138,7 +138,7 @@ export const lens = (
// Propagate writes from parent to child
const cancelBigToSmall = big.sink((parentValue, time) => {
- small.send(get(parentValue), time);
+ small.send(lens.get(parentValue), time);
});
addCancel(cancelBigToSmall);
From 511adcd8625a12ee3edd71f907eca7f3d6dc3df4 Mon Sep 17 00:00:00 2001
From: Gordon Brander
Date: Wed, 24 Jul 2024 14:40:52 -0400
Subject: [PATCH 25/32] Add lift function that solves diamond problem
Uses vector clock to solve diamond problem.
---
.../packages/common-html/src/propagator.ts | 213 +++++++++++++++---
.../common-html/src/test/propagator.test.ts | 91 +++++++-
2 files changed, 266 insertions(+), 38 deletions(-)
diff --git a/typescript/packages/common-html/src/propagator.ts b/typescript/packages/common-html/src/propagator.ts
index 3f7148ee9..6bee20256 100644
--- a/typescript/packages/common-html/src/propagator.ts
+++ b/typescript/packages/common-html/src/propagator.ts
@@ -1,18 +1,28 @@
-import { Cancellable, useCancelGroup } from "./cancel.js";
+import { Cancel, Cancellable, useCancelGroup } from "./cancel.js";
import * as logger from "./logger.js";
import { Lens } from "./lens.js";
+import cid from "./cid.js";
-const advanceClock = (a: number, b: number) => Math.max(a, b) + 1;
+export type LamportTime = number;
-export const lww = (_state: T, next: T) => next;
+const advanceClock = (...times: LamportTime[]) => Math.max(...times) + 1;
-export type LamportTime = number;
+export const lww = (_state: T, next: T) => next;
/**
* A cell is a reactive value that can be updated and subscribed to.
*/
export class Cell {
- #name: string = "";
+ static get(cell: Cell) {
+ return cell.get();
+ }
+
+ static time(cell: Cell) {
+ return cell.time;
+ }
+
+ #id = cid();
+ #name = "";
#neighbors = new Set<(value: Value, time: LamportTime) => void>();
#time: LamportTime = 0;
#update: (state: Value, next: Value) => Value;
@@ -30,66 +40,99 @@ export class Cell {
this.#name = name;
this.#update = update;
this.#value = value;
+ logger.debug({
+ msg: "Cell created",
+ cell: this.id,
+ name: this.name,
+ value: this.#value,
+ time: this.#time,
+ });
+ }
+
+ get id() {
+ return this.#id;
}
get name() {
return this.#name;
}
+ get time() {
+ return this.#time;
+ }
+
get() {
return this.#value;
}
send(value: Value, time: LamportTime = this.#time + 1): number {
- logger.debug(`cell#${this.name}`, "Message", value, time);
+ logger.debug({
+ msg: "Sent value",
+ cell: this.id,
+ value,
+ time,
+ });
- // We ignore old news
+ // We ignore old news.
+ // If times are equal, we ignore incoming value.
if (this.#time >= time) {
- logger.debug(
- `cell#${this.name}`,
- "Message out of date. Ignoring.",
+ logger.debug({
+ msg: "Value out of date. Ignoring.",
+ cell: this.id,
value,
time,
- );
+ });
return this.#time;
}
- this.#time = advanceClock(this.#time, time);
- logger.debug(`cell#${this.name}`, "Advanced clock", this.#time);
-
- const next = this.#update(this.#value, value);
-
- // We only advance clock if msg changed state
- if (this.#value === next) {
- logger.debug(`cell#${this.name}`, "Value unchanged.", this.#value);
+ // We only advance clock if value changes state
+ if (this.#value === value) {
+ logger.debug({
+ msg: "Value unchanged. Ignoring.",
+ cell: this.id,
+ value,
+ time,
+ });
return this.#time;
}
+ this.#time = advanceClock(this.#time, time);
+
+ const next = this.#update(this.#value, value);
const prev = this.#value;
this.#value = next;
- logger.debug(`cell#${this.name}`, "Value updated", prev, next);
+
+ logger.debug({
+ msg: "Value updated",
+ cell: this.id,
+ prev,
+ value,
+ time: this.#time,
+ });
// Notify neighbors
for (const neighbor of this.#neighbors) {
neighbor(next, this.#time);
}
- logger.debug(
- `cell#${this.name}`,
- "Notified neighbors",
- this.#neighbors.size,
- );
+
+ logger.debug({
+ msg: "Notified neighbors",
+ cell: this.id,
+ neighbors: this.#neighbors.size,
+ });
return this.#time;
}
/** Disconnect all neighbors */
disconnect() {
+ const size = this.#neighbors.size;
this.#neighbors.clear();
- logger.debug(
- `cell#${this.name}`,
- "Disconnected all neighbors",
- this.#neighbors.size,
- );
+ logger.debug({
+ msg: "Disconnected all neighbors",
+ cell: this.id,
+ neighbors: size,
+ });
}
sink(callback: (value: Value, time: LamportTime) => void) {
@@ -137,14 +180,18 @@ export const lens =