rename: onMutation to watch

Author: chase-moskal

README.md

@@ -57,18 +57,18 @@
   ```
 - you can make a substrata of another substrata
 
-### onMutation events
+### watch mutations
 - you can listen to global mutations on the strata
   ```ts
-  strata.onMutation(s => console.log(s.count))
+  strata.watch(s => console.log(s.count))
   ```
 - substrata listeners don't care about outside changes
   ```ts
-  snacks.onMutation(s => console.log(s.peanuts))
+  snacks.watch(s => console.log(s.peanuts))
   ```
-- onMutation returns a fn to stop listening
+- watch returns a fn to stop listening
   ```ts
-  const stop = strata.onMutation(s => console.log(s.count))
+  const stop = strata.watch(s => console.log(s.count))
   stop() // stop listening
   ```
 

s/parts/chronstrata.ts

@@ -26,8 +26,8 @@ export class Chronstrata<ParentState extends Substate, S extends Substate> imple
 		return this.#substrata.state.future.length
 	}
 
-	onMutation(fn: (state: S) => void) {
-		return this.#substrata.onMutation(chronicle => fn(chronicle.present))
+	watch(fn: (state: S) => void) {
+		return this.#substrata.watch(chronicle => fn(chronicle.present))
 	}
 
 	/** progress forwards in history */

s/parts/strata.ts

@@ -14,14 +14,14 @@ export class Strata<S extends State> implements Stratum<S> {
 	})
 
 	options: Options
-	onMutation = sub<[state: S]>()
+	watch = sub<[state: S]>()
 
 	#mutable: S
 	#immutable: S
 	#mutationLock = 0
 	#dispatchMutation = debounce(0, async(state: S) => {
 		this.#mutationLock++
-		try { await this.onMutation.pub(state) }
+		try { await this.watch.pub(state) }
 		finally { this.#mutationLock-- }
 	})
 

s/parts/substrata.ts

@@ -5,10 +5,10 @@ import {Chronicle, Mutator, Options, Selector, Stratum, Substate} from "./types.
 
 export class Substrata<ParentState extends Substate, S extends Substate> implements Stratum<S> {
 	dispose: () => void
-	onMutation = sub<[state: S]>()
+	watch = sub<[state: S]>()
 
 	#immutable: S
-	#dispatchMutation = debounce(0, (state: S) => this.onMutation.pub(state))
+	#dispatchMutation = debounce(0, (state: S) => this.watch.pub(state))
 
 	constructor(
 			private parent: Stratum<ParentState>,
@@ -19,7 +19,7 @@ export class Substrata<ParentState extends Substate, S extends Substate> impleme
 		const state = this.selector(this.parent.state)
 		this.#immutable = deep.freeze(this.options.clone(state))
 
-		this.dispose = this.parent.onMutation(async parentState => {
+		this.dispose = this.parent.watch(async parentState => {
 			const oldState = this.#immutable
 			const newState = this.selector(parentState)
 			const isChanged = !deep.equal(newState, oldState)

s/parts/types.ts

@@ -13,7 +13,7 @@ export type Substate = {} | null | undefined
 
 export type Stratum<S extends Substate> = {
 	readonly state: S
-	onMutation(fn: (s: S) => void): () => void
+	watch(fn: (s: S) => void): () => void
 	mutate(mutator: Mutator<S>): Promise<S>
 	substrata<Sub extends Substate>(selector: Selector<S, Sub>): Substrata<S, Sub>
 }

s/tests.test.ts

@@ -40,28 +40,28 @@ await Science.run({
 			expect(() => strata.state.x = 3).throws()
 		}),
 
-		"onMutation is published": Science.test(async() => {
+		"watch is published": Science.test(async() => {
 			const strata = new Strata({count: 0})
 			let mutationCount = 0
-			strata.onMutation.sub(() => {mutationCount++})
+			strata.watch.sub(() => {mutationCount++})
 			await strata.mutate(state => state.count++)
 			expect(mutationCount).is(1)
 		}),
 
-		"onMutation is debounced": Science.test(async() => {
+		"watch is debounced": Science.test(async() => {
 			const strata = new Strata({count: 0})
 			let mutationCount = 0
-			strata.onMutation.sub(() => {mutationCount++})
+			strata.watch.sub(() => {mutationCount++})
 			const promise = strata.mutate(state => state.count++)
 			expect(mutationCount).is(0)
 			await promise
 			expect(mutationCount).is(1)
 		}),
 
-		"onMutation is fired when array item is pushed": Science.test(async() => {
+		"watch is fired when array item is pushed": Science.test(async() => {
 			const strata = new Strata({items: ["hello", "world"]})
 			let mutationCount = 0
-			strata.onMutation.sub(() => {mutationCount++})
+			strata.watch.sub(() => {mutationCount++})
 			await strata.mutate(state => state.items.push("lol"))
 			expect(mutationCount).is(1)
 			expect(strata.state.items.length).is(3)
@@ -70,7 +70,7 @@ await Science.run({
 		"prevent mutation loops": Science.test(async() => {
 			const strata = new Strata({count: 0})
 			let mutationCount = 0
-			strata.onMutation.sub(async() => {
+			strata.watch.sub(async() => {
 				mutationCount++
 				if (mutationCount > 100)
 					return
@@ -131,12 +131,12 @@ await Science.run({
 			expect(b.state.c).is(103)
 		}),
 
-		"onMutation ignores outside mutations": Science.test(async() => {
+		"watch ignores outside mutations": Science.test(async() => {
 			const strata = new Strata({a: {x: 0}, b: {x: 0}})
 			const a = strata.substrata(s => s.a)
 			const b = strata.substrata(s => s.b)
 			let counted = 0
-			b.onMutation.sub(() => {counted++})
+			b.watch.sub(() => {counted++})
 			await a.mutate(a => a.x = 1)
 			expect(counted).is(0)
 		}),