more docs tweaking (#34)

* clock terminology

* more docs tweaks

Author: ds300

README.md

@@ -5,25 +5,8 @@
 	</picture>
 </div>
 
-**Signia** is a small, fast, and scaleable signals library for JavaScript and TypeScript.
+**Signia** is a minimal, fast, and [scalable](https://signia.tldraw.dev/docs/scalability) signals library for TypeScript.
 
-It uses an epochal pull-based (i.e. lazy) reactivity model that provides a lot of leverage to keep performance high and spaghetti low as the size and complexity of an application grows.
+It uses a new clock-based lazy reactivity system that allows signals to scale with complex data-intensive applications.
 
-Check the [docs](https://tldraw.github.io/signia)
-
-## What are signals?
-
-## How is Signia different?
-
-The key difference is scalability. Signia uses a unique reactivity model which allows signals to emit both ordinary values, and 'deltas' between successive values over time.
-
-Imagine something like the following:
-
-```ts
-const todos = atom([{ title: 'buy milk', completed: false}, ...])
-const incompleteTodos = computed(() => todos.value.filter(t => !t.completed))
-```
-
-Every time you add a new todo item, `incompleteTodos` will be recomputed from scratch, running the filter predicate on all todo items regardless of whether they have changed.
-
-With Signia, you can get only the changes since last time, and do with them what you like.
+Check the [docs](https://signia.tldraw.dev)

docs/docs/_intro.mdx

@@ -9,8 +9,8 @@ import useBaseUrl from '@docusaurus/useBaseUrl'
 	}}
 />
 
-**Signia** is a minimal, fast, and scalable signals library for TypeScript. It is framework-agnostic, and has official React bindings.
+**Signia** is a minimal, fast, and [scalable](/docs/scalability) signals library for TypeScript. It is framework-agnostic, and has official React bindings.
 
-It uses a new epochal pull-based reactivity system that allows signals to scale with complex data-intensive applications.
+It uses a new clock-based lazy reactivity system that allows signals to scale with complex data-intensive applications.
 
 Signia was originally created for [tldraw](https://beta.tldraw.com), to meet performance demands that other reactive signals libraries could not.

docs/docs/getting-started.mdx

@@ -4,24 +4,44 @@ sidebar_position: 2
 
 # Incrementally computed signals
 
-One of the things that sets Signia apart is that it supports incremental recomputation of derived values.
-This means that working with large derived collections can be extremely efficient, while still benefitting from the lazy evaluation and always-on-caching that Signia provides.
+One of Signia's superpowers is its support for incremental recomputation of derived values.
+This makes it possible to work with large derived collections extremely efficiently, while still benefitting from the lazy evaluation and always-on caching that Signia provides.
 
-This is achieved using an epochal reactivity system.
+This is achieved using a clock-based reactivity system.
 
-## Epochs
+## Clocks and Epochs
 
-Signia has a global 'epoch' value which is an integer that gets incremented every time any atom is updated.
+Signia has a global logical **clock**. This is an integer that gets incremented every time any atom is updated.
 
-When a derived value is computed, its computing function is passed two arguments: the previous value, and the global epoch when the previous value was computed.
+An **epoch** is one specific value of the global clock. It is a virtual point in time.
 
-This 'last computed' epoch can be used in conjunction with the `Signal.getDiffSince(epoch)` method to retrieve a list of changes, or 'diffs', since the last time the computed value was derived.
+You can access the epoch upon which a signal's value last changed using the `lastChangedEpoch` property:
+
+```ts
+const firstName = atom('firstName', 'Brian')
+const startEpoch = firstName.lastChangedEpoch
+firstName.set('Steve')
+const endEpoch = firstName.lastChangedEpoch
+console.log(endEpoch - startEpoch) // 1
+```
+
+When a derived value is computed, its computing function is passed two arguments:
+
+- `previousValue` the last value returned by the computing function
+- `lastComputedEpoch` the value of the global clock when the previous value was last _computed_.
+
+  :::note
+  Beware that 'last computed' is not the same as 'last changed', since a value can be recomputed and end up the same as it was before.
+  :::
+
+`lastComputedEpoch` can be used in conjunction with the `Signal.getDiffSince` method to retrieve a list of changes, or **diffs**, since the last time the computing function was invoked.
 
 ## Diffs don't come free
 
-JavaScript's data types don't have built-in support for diffs, so it necessary to implement this functionality manually.
+JavaScript's datatypes don't have built-in support for diffs, so you need to implement this functionality manually.
 
-For this tutorial, let's use [`immer`](https://immerjs.github.io/immer/), which is a library for working with immutable data. It also has the ability to extract diffs while making changes
+For this tutorial, let's use [`immer`](https://immerjs.github.io/immer/), which is a library for working with immutable data.
+It has the ability to extract diffs while making changes using its `produceWithPatches` function.
 
 Here is an example of an Atom wrapper which uses `immer` to capture diffs:
 
@@ -36,7 +56,7 @@ class ImmerAtom<T> {
 	readonly atom: Atom<T, Patch[]>
 	constructor(name: string, initialValue: T) {
 		this.atom = atom(name, initialValue, {
-			// In order to save diffs, we need to provide a historyLength argument
+			// In order to store diffs, we need to provide the `historyLength` argument
 			// to the atom constructor. Otherwise it will not allocate a history buffer.
 			historyLength: 10,
 		})
@@ -51,7 +71,7 @@ class ImmerAtom<T> {
 
 ## Using diffs in `computed`
 
-Now that we have a way to capture diffs, we can use them in our `computed` functions.
+We can use the diffs emitted by our ImmerAtom in our `computed` functions.
 
 Let's define an incremental version of Array.map:
 
@@ -118,7 +138,7 @@ function map<T, U>(source: ImmerAtom<T[]>, fn: (value: T) => U): Computed<U[], P
 
 You're probably thinking: "that's a whole lot of code just to map over an array!"
 
-Alas, such is the nature of the beast. Incremental logic is _much_ trickier to write than non-incremental logic, but the payoff is worth it.
+Alas, incremental logic is _much_ trickier to write than non-incremental logic. But often the payoff is worth it.
 
 ## The payoff
 
@@ -170,18 +190,6 @@ console.log(reversedNames.value) // [ 'linuS', 'xelA', 'uL', 'eimaJ', 'ajtiM' ]
 console.log(numReverseCalls) // 7
 ```
 
-:::note A small caveat
-
-In this example, if the mapping function reads any other external signals, then those dependencies will not necessarily be captured on incremental runs. e.g. if popping an item off the list.
-This will prevent updates to external signals from propagating correctly through the mapped list.
-There are a couple of ways around this:
-
-- Maintaining an array of computed signals, one for each item in the root list.
-- Adding an explicit dependencies array to the `map` function.
-
-These are left as an exercise for the reader :) Feel free to reach out in our [Discord](https://discord.gg/3GJTuqay) if you need help.
-:::
-
 ## The `historyLength` option
 
 The `historyLength` option is used to tell Signia how many diffs to store. Each time a value changes, a new diff is stored.
@@ -213,10 +221,70 @@ names.set(['Bob', 'Abhiti'])
 console.log(names.getDiffSince(startEpoch)) // [[ { op: 'replace', path: [1], value: 'Abhiti' } ]]
 ```
 
+## Testing
+
+Applying incremental diffs correctly takes a lot of care and can be difficult in unexpected ways.
+
+We suggest using generative testing to make sure your incremental logic matches your non-incremental logic.
+
+An easy way to get started is by creating a seeded random number generator and using it to generate random 'update ops' for atoms.
+You can then run the same updates through both the incremental and non-incremental logic and compare the results.
+
+```ts
+const seed = Math.random()
+test(`using seed ${seed}`, () => {
+	const rng = new RandomNumberGenerator(seed)
+	const names = new ImmerAtom('names', [], { historyLength: 10 })
+	// if you set historyLength to 0 it will force your `map` incremental logic down the RESET_VALUE path
+	const names_no_diff = new ImmerAtom('names_no_diff', [], { historyLength: 0 })
+
+	const updateBoth = (fn: (draft: string[]) => void) => {
+		names.update(fn)
+		names_no_diff.update(fn)
+	}
+
+	const reversedNames = map(names, (name) => name.split('').reverse().join(''))
+	const reversedNames_no_diff = map(names_no_diff, (name) => name.split('').reverse().join(''))
+
+	for (let i = 0; i < 1000; i++) {
+		// getRandomNamesOp implementation left as an exercise for the reader
+		const op = getRandomNamesOp(names.state.value, rng)
+		if (op.type === 'add_name') {
+			updateBoth((draft) => {
+				draft.splice(op.index, 0, op.name)
+			})
+		} else if (op.type === 'remove_name') {
+			updateBoth((draft) => {
+				draft.splice(op.index, 1)
+			})
+		} else if (op.type === 'update_name') {
+			updateBoth((draft) => {
+				draft[op.index] = op.name
+			})
+		}
+
+		// don't check every time, to allow for some history buffer buildup and overflow
+		if (rng.random() < 0.1) {
+			expect(reversedNames.value).toEqual(reversedNames_no_diff.value)
+		}
+	}
+
+	expect(reversedNames.value).toEqual(reversedNames_no_diff.value)
+})
+```
+
 ## Conclusion
 
 Most complex software systems do _something_ along these lines by necessity, usually ad-hoc. The nice thing about integrating it into Signia is that it's now a first-class citizen and it works seamlessly with other signals. There's no need to worry about cache invalidation or update ordering, everything just works.
 
 At [tldraw](https://tldraw.com) we use incrementally computed signals for a handful of our core data structures, and it's been a huge win for performance. We're able to keep our canvas snappy and responsive even when we have thousands of shapes.
 
 We also have a rudimentary reactive database based on `signia` which makes heavy use of incrementally computed signals for building reactive queries and indexes.
+
+:::info Get involved!
+
+This is an extremely new kind of tool with lots of sharp edges! There are probably lots of ways to improve it and address common problems.
+
+We'd be happy to hear your feedback and suggestions on [GitHub](https://github.com/tldraw/signia/discussions) or in the [Discord channel](https://discord.gg/3GJTuqay).
+
+:::

docs/docs/incremental.mdx

@@ -1,15 +1,48 @@
 ---
 sidebar_position: -1
-title: Introducing Signia
+title: Getting Started
 hide_title: true
 ---
 
-import Intro from './_intro.mdx'
+import ThemedImage from '@theme/ThemedImage'
+import useBaseUrl from '@docusaurus/useBaseUrl'
 
-<Intro />
+<ThemedImage
+	alt="Push signals"
+	sources={{
+		light: useBaseUrl('/img/[email protected]'),
+		dark: useBaseUrl('/img/[email protected]'),
+	}}
+/>
 
-## Quick links
+# Getting started
 
-- [Getting started](getting-started)
-- [What are signals](what-are-signals)?
-- [How is Signia special](scalability)?
+## Installation
+
+import Tabs from '@theme/Tabs'
+import TabItem from '@theme/TabItem'
+
+### Core library
+
+<Tabs>
+	<TabItem value="npm" label="npm">
+		<pre>npm add signia</pre>
+	</TabItem>
+	<TabItem value="yarn" label="yarn">
+		<pre>yarn add signia</pre>
+	</TabItem>
+	<TabItem value="pnpm" label="pnpm">
+		<pre>pnpm add signia</pre>
+	</TabItem>
+</Tabs>
+
+### React bindings
+
+`signia` has no dependencies, and is useful outside of react applications.
+However if you wish to use it in a react app, we have officially-supported bindings available.
+
+Read the [installation instructions](react-bindings) to find out more.
+
+## Next: Read the tutorial
+
+The [Using Signals Tutorial](using-signals) will walk you through the basics of using `signia` in an application.

docs/docs/intro.mdx

@@ -4,6 +4,6 @@ import Intro from '@site/docs/_intro.mdx'
 
 import Link from '@docusaurus/Link'
 
-<Link className="button button--primary button--lg" to="/docs/getting-started">
+<Link className="button button--primary button--lg" to="/docs/intro">
 	Getting Started
 </Link>