Add a simple readme for signals. (#974)

Author: kixelated

js/signals/README.md

@@ -1,13 +1,139 @@
-# Signals
-Reactive and safe signals.
+# @moq/signals
 
-TODO More docs.
+Reactive signals with explicit tracking.
+No magic or footguns.
 
-## Why?
-Solid signals are nice, but there's too much magic.
-It's very easy to shoot yourself in the foot by calling Accessors from outside of an effect.
-The current execution context is difficult to track and there's many unintuitive edge cases.
+## Usage
+```sh
+bun add @moq/signals
+```
 
-React signals require explicit dependencies.
-I don't want to list all of the signals that *might* be used in an effect.
-I would much rather just run the function and record what signals were used, re-running it on change.
+### Signal
+A `Signal` holds a reactive value.
+
+```ts
+import { Signal } from "@moq/signals";
+
+const count = new Signal(0);
+
+count.peek();      // 0
+count.set(1);     // notifies subscribers
+count.update(n => n + 1); // update via function
+
+const dispose = count.subscribe(n => console.log(n)); // subscribe to changes manually
+```
+
+Updates are batched, coalescing multiple updates into a single microtask.
+The old and new values are then compared with deep equality ([dequal](https://github.com/lukeed/dequal)) to avoid unnecessary wakeups.
+It's possible to skip this check, but please benchmark it first...
+
+### Effect
+An `Effect` is a reactive scope.
+It re-runs whenever a tracked signal changes.
+
+```ts
+import { Signal, Effect } from "@moq/signals";
+
+const name = new Signal("world");
+
+const effect = new Effect((effect) => {
+  const value = effect.get(name); // read AND track
+  console.log(`Hello, ${value}!`);
+});
+
+name.set("signals"); // effect reruns: "Hello, signals!"
+
+effect.close(); // cleanup
+```
+
+The key difference from other libraries: **`effect.get(signal)` is what subscribes**.
+If you just want to read without tracking, use `signal.peek()` directly.
+
+### effect.cleanup
+Run a cleanup function when the effect reruns or closes.
+
+```ts
+const name = new Signal("world");
+
+const effect = new Effect((effect) => {
+  const value = effect.get(name);
+  console.log(`Hello, ${value}!`);
+
+  effect.cleanup(() => console.log(`Goodbye, ${value}!`));
+});
+```
+
+### effect.run
+Create a nested effect that can be rerun independently.
+It will be closed when the parent effect reruns or closes.
+
+```ts
+const name = new Signal("world");
+const age = new Signal(20);
+
+const effect = new Effect((effect) => {
+  const n = effect.get(name);
+  console.log(`Hello, ${n}!`);
+
+  // NOTE: use the nested effect's argument, not the parent's
+  effect.run((nested) => {
+    const a = nested.get(age);
+    console.log(`You are ${a} years old!`);
+  });
+});
+
+age.set(21); // only the nested effect reruns: "You are 21 years old!"
+```
+
+### effect.spawn
+Run async work that blocks the effect from re-running until it completes.
+The promise should monitor the `effect.cancel` Promise to detect when the effect wants to rerun.
+
+```ts
+const url = new Signal("/api/data");
+
+const effect = new Effect((effect) => {
+  const endpoint = effect.get(url);
+
+  effect.spawn(async () => {
+    const request = fetch(endpoint);
+    const res = await Promise.race([request, effect.cancel]);
+    if (!res) return; // effect cancelled, stop the request
+
+    // ...
+  });
+});
+```
+
+### Helpers
+
+Effects also provide lifecycle helpers that auto-cleanup:
+
+- **`effect.set(signal, value, cleanup)`** - temporarily set the value of a signal for the duration of the effect
+- **`effect.timer(fn, ms)`** - `setTimeout` that cancels on cleanup
+- **`effect.interval(fn, ms)`** - `setInterval` that cancels on cleanup
+- **`effect.animate(fn)`** - `requestAnimationFrame` that cancels on cleanup
+- **`effect.event(target, type, fn)`** - `addEventListener` that removes on cleanup
+- **`effect.subscribe(signal, fn)`** - shorthand: run `fn` each time `signal` changes
+- **`effect.getAll(signals)`** - get the values of multiple signals, only if they are all truthy
+
+## Framework Integrations
+
+### Solid.js
+
+```ts
+import solid from "@moq/signals/solid";
+
+const count = new Signal(0);
+const value = solid(count); // returns a Solid Accessor
+```
+
+### React
+
+```ts
+import react from "@moq/signals/react";
+
+function Component() {
+  const value = react(count); // uses useSyncExternalStore under the hood
+}
+```

js/signals/src/index.ts

@@ -278,6 +278,10 @@ export class Effect {
 
 		if (this.#fn) {
 			this.#fn(this);
+
+			if (DEV && this.#unwatch.length === 0) {
+				console.warn("Effect did not subscribe to any signals; it will never rerun.", this.#stack);
+			}
 		}
 	}
 
@@ -414,7 +418,7 @@ export class Effect {
 	}
 
 	// Create a nested effect that can be rerun independently.
-	effect(fn: (effect: Effect) => void) {
+	run(fn: (effect: Effect) => void) {
 		if (this.#dispose === undefined) {
 			if (DEV) {
 				console.warn("Effect.nested called when closed, ignoring");
@@ -426,6 +430,11 @@ export class Effect {
 		this.#dispose.push(() => effect.close());
 	}
 
+	// Backwards compatibility with the old name.
+	effect(fn: (effect: Effect) => void) {
+		return this.run(fn);
+	}
+
 	// Get the values of multiple signals, returning undefined if any are falsy.
 	getAll<S extends readonly Getter<unknown>[]>(
 		signals: [...S],