@e280/strata 0.0.0-0

package/LICENSE

@@ -0,0 +1,23 @@
+
+MIT License
+
+Copyright (c) 2025 Chase Moskal
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,73 @@
+
+# ⛏️ strata
+
+**my 10th state management library, probably**
+- 📦 `npm install @e280/strata`
+- single-source-of-truth state tree
+- immutable except for `mutate(fn)` calls
+- undo/redo history, cross-tab sync, localStorage persistence
+
+## good state management
+
+### establish a strata with some state
+- better stick to json-friendly serializable data
+  ```ts
+  import {Strata} from "@e280/strata"
+
+  const strata = new Strata({
+    count: 0,
+    stuff: {
+      peanuts: 8,
+      items: ["hello", "world"],
+    },
+  })
+
+  strata.state.count // 0
+  strata.state.stuff.peanuts // 8
+  ```
+
+### how mutations work
+- ⛔ informal mutations are denied
+  ```ts
+  strata.state.count++ // error is thrown
+  ```
+- ✅ formal mutation is allowed
+  ```ts
+  await strata.mutate(s => s.count++)
+  ```
+
+### substrata and selectors
+- a substrata is a view into a subset of the state tree
+  ```ts
+  const stuff = strata.substrata(s => s.stuff)
+  ```
+- run substrata mutations
+  ```ts
+  await stuff.mutate(s => s.peanuts++)
+  ```
+- array mutations are cool, actually
+  ```ts
+  await stuff.mutate(s => s.items.push("lol"))
+  ```
+
+### onMutation events
+- you can listen to global mutations on the strata
+  ```ts
+  strata.onMutation(s => console.log(s.count))
+  ```
+
+- substrata listeners don't care about outside changes
+  ```ts
+  stuff.onMutation(s => console.log(s.peanuts))
+  ```
+
+- onMutation returns a fn to stop listening
+  ```ts
+  const stop = strata.onMutation(s => console.log(s.count))
+  stop() // stop listening
+  ```
+
+## a buildercore e280 project
+free and open source by https://e280.org/  
+join us if you're cool and good at dev  
+

package/package.json

@@ -0,0 +1,46 @@
+{
+	"name": "@e280/strata",
+	"version": "0.0.0-0",
+	"description": "state management",
+	"license": "MIT",
+	"author": "Chase Moskal <chasemoskal@gmail.com>",
+	"type": "module",
+	"main": "x/index.js",
+	"files": [
+		"x",
+		"s"
+	],
+	"scripts": {
+		"build": "run-s _clean _links _tsc",
+		"test": "node x/tests.test.js",
+		"test-watch": "node --watch x/tests.test.js",
+		"test-inspect": "node inspect x/tests.test.js",
+		"count": "find s -path '*/_archive' -prune -o -name '*.ts' -exec wc -l {} +",
+		"watch": "run-p _tscw test-watch",
+		"_clean": "rm -rf x && mkdir x",
+		"_links": "ln -s \"$(realpath node_modules)\" x/node_modules",
+		"_tsc": "tsc",
+		"_tscw": "tsc -w"
+	},
+	"devDependencies": {
+		"@e280/science": "^0.0.5",
+		"@types/node": "^24.0.3",
+		"npm-run-all": "^4.1.5",
+		"typescript": "^5.8.3"
+	},
+	"keywords": [
+		"state",
+		"state management"
+	],
+	"homepage": "https://github.com/e280/strata#readme",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/e280/strata.git"
+	},
+	"bugs": {
+		"url": "https://github.com/e280/strata/issues"
+	},
+	"dependencies": {
+		"@e280/stz": "^0.0.0-24"
+	}
+}

package/s/index.ts

@@ -0,0 +1,5 @@
+
+export {Strata} from "./parts/strata.js"
+export {Substrata} from "./parts/substrata.js"
+export {Options, Mutator, Selector} from "./parts/types.js"
+

package/s/parts/strata.ts

@@ -0,0 +1,48 @@
+
+import {debounce, deep, sub} from "@e280/stz"
+
+import {Substrata} from "./substrata.js"
+import {processOptions} from "./utils/process-options.js"
+import {Mutator, Options, Selector, State, Substate} from "./types.js"
+
+export class Strata<S extends State> {
+	onMutation = sub<[state: S]>()
+
+	#options: Options
+	#mutable: S
+	#immutable: S
+	#dispatchMutation = debounce(0, (state: S) => this.onMutation.pub(state))
+
+	constructor(state: S, options: Partial<Options> = {}) {
+		this.#options = processOptions(options)
+		this.#mutable = state
+		this.#immutable = deep.freeze(this.#options.clone(state))
+	}
+
+	#updateState(state: S) {
+		this.#mutable = state
+		this.#immutable = deep.freeze(this.#options.clone(state))
+	}
+
+	get state() {
+		return this.#immutable
+	}
+
+	substrata<Sub extends Substate>(selector: Selector<S, Sub>) {
+		return new Substrata(this, selector, this.#options)
+	}
+
+	async mutate(mutator: Mutator<S>) {
+		const oldState = this.#options.clone(this.#mutable)
+		mutator(this.#mutable)
+		const newState = this.#mutable
+		const isChanged = !deep.equal(newState, oldState)
+		if (isChanged) {
+			this.#updateState(newState)
+			const immutable = this.state
+			await this.#dispatchMutation(immutable)
+		}
+		return this.#immutable
+	}
+}
+

package/s/parts/substrata.ts

@@ -0,0 +1,55 @@
+
+import {debounce, deep, sub} from "@e280/stz"
+
+import {Strata} from "./strata.js"
+import {processOptions} from "./utils/process-options.js"
+import {Mutator, Options, Selector, State, Substate} from "./types.js"
+
+export class Substrata<ParentState extends State, S extends Substate> {
+	dispose: () => void
+	onMutation = sub<[state: S]>()
+
+	#options: Options
+	#immutable: S
+	#dispatchMutation = debounce(0, (state: S) => this.onMutation.pub(state))
+
+	constructor(
+			private strata: Strata<ParentState>,
+			private selector: Selector<ParentState, S>,
+			options: Partial<Options> = {},
+		) {
+
+		this.#options = processOptions(options)
+		const state = this.selector(this.strata.state)
+		this.#immutable = deep.freeze(this.#options.clone(state))
+
+		this.dispose = this.strata.onMutation(async parentState => {
+			const oldState = this.#immutable
+			const newState = this.selector(parentState)
+			const isChanged = !deep.equal(newState, oldState)
+			if (isChanged) {
+				this.#updateState(newState)
+				const immutable = this.state
+				await this.#dispatchMutation(immutable)
+			}
+		})
+	}
+
+	#updateState(state: S) {
+		this.#immutable = deep.freeze(this.#options.clone(state))
+	}
+
+	get state(): S {
+		return this.#immutable
+	}
+
+	async mutate(mutator: Mutator<S>) {
+		await this.strata.mutate(parentState => mutator(this.selector(parentState)))
+		return this.#immutable
+	}
+
+	substrata<Sub extends Substate>(selector: Selector<S, Sub>) {
+		return this.strata.substrata(parentState => selector(this.selector(parentState)))
+	}
+}
+

package/s/parts/types.ts

@@ -0,0 +1,11 @@
+
+export type Options = {
+	clone: <X>(x: X) => X
+}
+
+export type Selector<S, Sub> = (state: S) => Sub
+export type Mutator<S> = (state: S) => void
+
+export type State = {}
+export type Substate = {} | null | undefined
+

package/s/parts/utils/process-options.ts

@@ -0,0 +1,7 @@
+
+import {Options} from "../types.js"
+
+export const processOptions = (options: Partial<Options>): Options => ({
+	clone: options.clone ?? structuredClone,
+})
+

package/s/tests.test.ts

@@ -0,0 +1,119 @@
+
+import {expect, Science} from "@e280/science"
+import {Strata} from "./parts/strata.js"
+
+await Science.run({
+	"strata": Science.suite({
+		"get state": Science.test(async() => {
+			const strata = new Strata({count: 0})
+			expect(strata.state.count).is(0)
+		}),
+
+		"state is immutable": Science.test(async() => {
+			const strata = new Strata({count: 0})
+			expect(() => strata.state.count++).throws()
+		}),
+
+		"run a proper mutation": Science.test(async() => {
+			const strata = new Strata({count: 0})
+			expect(strata.state.count).is(0)
+			await strata.mutate(state => state.count++)
+			expect(strata.state.count).is(1)
+			await strata.mutate(state => state.count++)
+			expect(strata.state.count).is(2)
+		}),
+
+		"state after mutation is frozen": Science.test(async () => {
+			const strata = new Strata({x: 1})
+			await strata.mutate(s => { s.x = 2 })
+			expect(() => strata.state.x = 3).throws()
+		}),
+
+		"onMutation is published": Science.test(async() => {
+			const strata = new Strata({count: 0})
+			let mutationCount = 0
+			strata.onMutation.sub(() => {mutationCount++})
+			await strata.mutate(state => state.count++)
+			expect(mutationCount).is(1)
+		}),
+
+		"onMutation is debounced": Science.test(async() => {
+			const strata = new Strata({count: 0})
+			let mutationCount = 0
+			strata.onMutation.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() => {
+			const strata = new Strata({items: ["hello", "world"]})
+			let mutationCount = 0
+			strata.onMutation.sub(() => {mutationCount++})
+			await strata.mutate(state => state.items.push("lol"))
+			expect(mutationCount).is(1)
+			expect(strata.state.items.length).is(3)
+		}),
+	}),
+
+	"substrata": Science.suite({
+		"get state": Science.test(async() => {
+			const strata = new Strata({count: 0, sub: {rofls: 0}})
+			const substrata = strata.substrata(s => s.sub)
+			expect(substrata.state.rofls).is(0)
+		}),
+
+		"nullable selector": Science.test(async () => {
+			const strata = new Strata({
+				a: {b: 0}  as (null | {b: number}),
+			})
+			const a = strata.substrata(s => s.a)
+			expect(strata.state.a?.b).is(0)
+			expect(a.state?.b).is(0)
+			await a.mutate(a => { a!.b = 1 })
+			expect(strata.state.a?.b).is(1)
+			expect(a.state?.b).is(1)
+			await strata.mutate(s => s.a = null)
+			expect(strata.state.a?.b).is(undefined)
+			expect(a.state?.b).is(undefined)
+		}),
+
+		"composition": Science.test(async () => {
+			const strata = new Strata({a: {b: {c: 0}}})
+			const a = strata.substrata(s => s.a)
+			const b = a.substrata(s => s.b)
+			expect(strata.state.a.b.c).is(0)
+			expect(b.state.c).is(0)
+		}),
+
+		"deep mutations": Science.test(async () => {
+			const strata = new Strata({a: {b: {c: 0}}})
+			const a = strata.substrata(s => s.a)
+			const b = a.substrata(s => s.b)
+			await b.mutate(b => { b.c = 101 })
+			expect(strata.state.a.b.c).is(101)
+			expect(a.state.b.c).is(101)
+			expect(b.state.c).is(101)
+			await a.mutate(a => { a.b = {c: 102} })
+			expect(strata.state.a.b.c).is(102)
+			expect(a.state.b.c).is(102)
+			expect(b.state.c).is(102)
+			await strata.mutate(s => { s.a = {b: {c: 103}} })
+			expect(strata.state.a.b.c).is(103)
+			expect(a.state.b.c).is(103)
+			expect(b.state.c).is(103)
+		}),
+
+		"onMutation 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++})
+			await a.mutate(a => a.x = 1)
+			expect(counted).is(0)
+		}),
+	}),
+})
+

package/x/index.d.ts

@@ -0,0 +1,3 @@
+export { Strata } from "./parts/strata.js";
+export { Substrata } from "./parts/substrata.js";
+export { Options, Mutator, Selector } from "./parts/types.js";

package/x/index.js

@@ -0,0 +1,3 @@
+export { Strata } from "./parts/strata.js";
+export { Substrata } from "./parts/substrata.js";
+//# sourceMappingURL=index.js.map

package/x/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../s/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAC,MAAM,EAAC,MAAM,mBAAmB,CAAA;AACxC,OAAO,EAAC,SAAS,EAAC,MAAM,sBAAsB,CAAA"}

package/x/parts/strata.d.ts

@@ -0,0 +1,10 @@
+import { Substrata } from "./substrata.js";
+import { Mutator, Options, Selector, State, Substate } from "./types.js";
+export declare class Strata<S extends State> {
+    #private;
+    onMutation: import("@e280/stz").Sub<[state: S]>;
+    constructor(state: S, options?: Partial<Options>);
+    get state(): S;
+    substrata<Sub extends Substate>(selector: Selector<S, Sub>): Substrata<S, Sub>;
+    mutate(mutator: Mutator<S>): Promise<S>;
+}

package/x/parts/strata.js

@@ -0,0 +1,38 @@
+import { debounce, deep, sub } from "@e280/stz";
+import { Substrata } from "./substrata.js";
+import { processOptions } from "./utils/process-options.js";
+export class Strata {
+    onMutation = sub();
+    #options;
+    #mutable;
+    #immutable;
+    #dispatchMutation = debounce(0, (state) => this.onMutation.pub(state));
+    constructor(state, options = {}) {
+        this.#options = processOptions(options);
+        this.#mutable = state;
+        this.#immutable = deep.freeze(this.#options.clone(state));
+    }
+    #updateState(state) {
+        this.#mutable = state;
+        this.#immutable = deep.freeze(this.#options.clone(state));
+    }
+    get state() {
+        return this.#immutable;
+    }
+    substrata(selector) {
+        return new Substrata(this, selector, this.#options);
+    }
+    async mutate(mutator) {
+        const oldState = this.#options.clone(this.#mutable);
+        mutator(this.#mutable);
+        const newState = this.#mutable;
+        const isChanged = !deep.equal(newState, oldState);
+        if (isChanged) {
+            this.#updateState(newState);
+            const immutable = this.state;
+            await this.#dispatchMutation(immutable);
+        }
+        return this.#immutable;
+    }
+}
+//# sourceMappingURL=strata.js.map

package/x/parts/strata.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"strata.js","sourceRoot":"","sources":["../../s/parts/strata.ts"],"names":[],"mappings":"AACA,OAAO,EAAC,QAAQ,EAAE,IAAI,EAAE,GAAG,EAAC,MAAM,WAAW,CAAA;AAE7C,OAAO,EAAC,SAAS,EAAC,MAAM,gBAAgB,CAAA;AACxC,OAAO,EAAC,cAAc,EAAC,MAAM,4BAA4B,CAAA;AAGzD,MAAM,OAAO,MAAM;IAClB,UAAU,GAAG,GAAG,EAAc,CAAA;IAE9B,QAAQ,CAAS;IACjB,QAAQ,CAAG;IACX,UAAU,CAAG;IACb,iBAAiB,GAAG,QAAQ,CAAC,CAAC,EAAE,CAAC,KAAQ,EAAE,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAA;IAEzE,YAAY,KAAQ,EAAE,UAA4B,EAAE;QACnD,IAAI,CAAC,QAAQ,GAAG,cAAc,CAAC,OAAO,CAAC,CAAA;QACvC,IAAI,CAAC,QAAQ,GAAG,KAAK,CAAA;QACrB,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAA;IAC1D,CAAC;IAED,YAAY,CAAC,KAAQ;QACpB,IAAI,CAAC,QAAQ,GAAG,KAAK,CAAA;QACrB,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAA;IAC1D,CAAC;IAED,IAAI,KAAK;QACR,OAAO,IAAI,CAAC,UAAU,CAAA;IACvB,CAAC;IAED,SAAS,CAAuB,QAA0B;QACzD,OAAO,IAAI,SAAS,CAAC,IAAI,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAA;IACpD,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,OAAmB;QAC/B,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAA;QACnD,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAA;QACtB,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAA;QAC9B,MAAM,SAAS,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAA;QACjD,IAAI,SAAS,EAAE,CAAC;YACf,IAAI,CAAC,YAAY,CAAC,QAAQ,CAAC,CAAA;YAC3B,MAAM,SAAS,GAAG,IAAI,CAAC,KAAK,CAAA;YAC5B,MAAM,IAAI,CAAC,iBAAiB,CAAC,SAAS,CAAC,CAAA;QACxC,CAAC;QACD,OAAO,IAAI,CAAC,UAAU,CAAA;IACvB,CAAC;CACD"}

package/x/parts/substrata.d.ts

@@ -0,0 +1,13 @@
+import { Strata } from "./strata.js";
+import { Mutator, Options, Selector, State, Substate } from "./types.js";
+export declare class Substrata<ParentState extends State, S extends Substate> {
+    #private;
+    private strata;
+    private selector;
+    dispose: () => void;
+    onMutation: import("@e280/stz").Sub<[state: S]>;
+    constructor(strata: Strata<ParentState>, selector: Selector<ParentState, S>, options?: Partial<Options>);
+    get state(): S;
+    mutate(mutator: Mutator<S>): Promise<S>;
+    substrata<Sub extends Substate>(selector: Selector<S, Sub>): Substrata<ParentState, Sub>;
+}

package/x/parts/substrata.js

@@ -0,0 +1,42 @@
+import { debounce, deep, sub } from "@e280/stz";
+import { processOptions } from "./utils/process-options.js";
+export class Substrata {
+    strata;
+    selector;
+    dispose;
+    onMutation = sub();
+    #options;
+    #immutable;
+    #dispatchMutation = debounce(0, (state) => this.onMutation.pub(state));
+    constructor(strata, selector, options = {}) {
+        this.strata = strata;
+        this.selector = selector;
+        this.#options = processOptions(options);
+        const state = this.selector(this.strata.state);
+        this.#immutable = deep.freeze(this.#options.clone(state));
+        this.dispose = this.strata.onMutation(async (parentState) => {
+            const oldState = this.#immutable;
+            const newState = this.selector(parentState);
+            const isChanged = !deep.equal(newState, oldState);
+            if (isChanged) {
+                this.#updateState(newState);
+                const immutable = this.state;
+                await this.#dispatchMutation(immutable);
+            }
+        });
+    }
+    #updateState(state) {
+        this.#immutable = deep.freeze(this.#options.clone(state));
+    }
+    get state() {
+        return this.#immutable;
+    }
+    async mutate(mutator) {
+        await this.strata.mutate(parentState => mutator(this.selector(parentState)));
+        return this.#immutable;
+    }
+    substrata(selector) {
+        return this.strata.substrata(parentState => selector(this.selector(parentState)));
+    }
+}
+//# sourceMappingURL=substrata.js.map

package/x/parts/substrata.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"substrata.js","sourceRoot":"","sources":["../../s/parts/substrata.ts"],"names":[],"mappings":"AACA,OAAO,EAAC,QAAQ,EAAE,IAAI,EAAE,GAAG,EAAC,MAAM,WAAW,CAAA;AAG7C,OAAO,EAAC,cAAc,EAAC,MAAM,4BAA4B,CAAA;AAGzD,MAAM,OAAO,SAAS;IASX;IACA;IATV,OAAO,CAAY;IACnB,UAAU,GAAG,GAAG,EAAc,CAAA;IAE9B,QAAQ,CAAS;IACjB,UAAU,CAAG;IACb,iBAAiB,GAAG,QAAQ,CAAC,CAAC,EAAE,CAAC,KAAQ,EAAE,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAA;IAEzE,YACU,MAA2B,EAC3B,QAAkC,EAC1C,UAA4B,EAAE;QAFtB,WAAM,GAAN,MAAM,CAAqB;QAC3B,aAAQ,GAAR,QAAQ,CAA0B;QAI3C,IAAI,CAAC,QAAQ,GAAG,cAAc,CAAC,OAAO,CAAC,CAAA;QACvC,MAAM,KAAK,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;QAC9C,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAA;QAEzD,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,KAAK,EAAC,WAAW,EAAC,EAAE;YACzD,MAAM,QAAQ,GAAG,IAAI,CAAC,UAAU,CAAA;YAChC,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAA;YAC3C,MAAM,SAAS,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAA;YACjD,IAAI,SAAS,EAAE,CAAC;gBACf,IAAI,CAAC,YAAY,CAAC,QAAQ,CAAC,CAAA;gBAC3B,MAAM,SAAS,GAAG,IAAI,CAAC,KAAK,CAAA;gBAC5B,MAAM,IAAI,CAAC,iBAAiB,CAAC,SAAS,CAAC,CAAA;YACxC,CAAC;QACF,CAAC,CAAC,CAAA;IACH,CAAC;IAED,YAAY,CAAC,KAAQ;QACpB,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAA;IAC1D,CAAC;IAED,IAAI,KAAK;QACR,OAAO,IAAI,CAAC,UAAU,CAAA;IACvB,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,OAAmB;QAC/B,MAAM,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,WAAW,CAAC,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC,CAAC,CAAA;QAC5E,OAAO,IAAI,CAAC,UAAU,CAAA;IACvB,CAAC;IAED,SAAS,CAAuB,QAA0B;QACzD,OAAO,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,WAAW,CAAC,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC,CAAC,CAAA;IAClF,CAAC;CACD"}

package/x/parts/types.d.ts

@@ -0,0 +1,7 @@
+export type Options = {
+    clone: <X>(x: X) => X;
+};
+export type Selector<S, Sub> = (state: S) => Sub;
+export type Mutator<S> = (state: S) => void;
+export type State = {};
+export type Substate = {} | null | undefined;

package/x/parts/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/x/parts/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../s/parts/types.ts"],"names":[],"mappings":""}

package/x/parts/utils/process-options.d.ts

@@ -0,0 +1,2 @@
+import { Options } from "../types.js";
+export declare const processOptions: (options: Partial<Options>) => Options;

package/x/parts/utils/process-options.js

@@ -0,0 +1,4 @@
+export const processOptions = (options) => ({
+    clone: options.clone ?? structuredClone,
+});
+//# sourceMappingURL=process-options.js.map

package/x/parts/utils/process-options.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"process-options.js","sourceRoot":"","sources":["../../../s/parts/utils/process-options.ts"],"names":[],"mappings":"AAGA,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,OAAyB,EAAW,EAAE,CAAC,CAAC;IACtE,KAAK,EAAE,OAAO,CAAC,KAAK,IAAI,eAAe;CACvC,CAAC,CAAA"}

package/x/tests.test.d.ts

@@ -0,0 +1 @@
+export {};

package/x/tests.test.js

@@ -0,0 +1,106 @@
+import { expect, Science } from "@e280/science";
+import { Strata } from "./parts/strata.js";
+await Science.run({
+    "strata": Science.suite({
+        "get state": Science.test(async () => {
+            const strata = new Strata({ count: 0 });
+            expect(strata.state.count).is(0);
+        }),
+        "state is immutable": Science.test(async () => {
+            const strata = new Strata({ count: 0 });
+            expect(() => strata.state.count++).throws();
+        }),
+        "run a proper mutation": Science.test(async () => {
+            const strata = new Strata({ count: 0 });
+            expect(strata.state.count).is(0);
+            await strata.mutate(state => state.count++);
+            expect(strata.state.count).is(1);
+            await strata.mutate(state => state.count++);
+            expect(strata.state.count).is(2);
+        }),
+        "state after mutation is frozen": Science.test(async () => {
+            const strata = new Strata({ x: 1 });
+            await strata.mutate(s => { s.x = 2; });
+            expect(() => strata.state.x = 3).throws();
+        }),
+        "onMutation is published": Science.test(async () => {
+            const strata = new Strata({ count: 0 });
+            let mutationCount = 0;
+            strata.onMutation.sub(() => { mutationCount++; });
+            await strata.mutate(state => state.count++);
+            expect(mutationCount).is(1);
+        }),
+        "onMutation is debounced": Science.test(async () => {
+            const strata = new Strata({ count: 0 });
+            let mutationCount = 0;
+            strata.onMutation.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 () => {
+            const strata = new Strata({ items: ["hello", "world"] });
+            let mutationCount = 0;
+            strata.onMutation.sub(() => { mutationCount++; });
+            await strata.mutate(state => state.items.push("lol"));
+            expect(mutationCount).is(1);
+            expect(strata.state.items.length).is(3);
+        }),
+    }),
+    "substrata": Science.suite({
+        "get state": Science.test(async () => {
+            const strata = new Strata({ count: 0, sub: { rofls: 0 } });
+            const substrata = strata.substrata(s => s.sub);
+            expect(substrata.state.rofls).is(0);
+        }),
+        "nullable selector": Science.test(async () => {
+            const strata = new Strata({
+                a: { b: 0 },
+            });
+            const a = strata.substrata(s => s.a);
+            expect(strata.state.a?.b).is(0);
+            expect(a.state?.b).is(0);
+            await a.mutate(a => { a.b = 1; });
+            expect(strata.state.a?.b).is(1);
+            expect(a.state?.b).is(1);
+            await strata.mutate(s => s.a = null);
+            expect(strata.state.a?.b).is(undefined);
+            expect(a.state?.b).is(undefined);
+        }),
+        "composition": Science.test(async () => {
+            const strata = new Strata({ a: { b: { c: 0 } } });
+            const a = strata.substrata(s => s.a);
+            const b = a.substrata(s => s.b);
+            expect(strata.state.a.b.c).is(0);
+            expect(b.state.c).is(0);
+        }),
+        "deep mutations": Science.test(async () => {
+            const strata = new Strata({ a: { b: { c: 0 } } });
+            const a = strata.substrata(s => s.a);
+            const b = a.substrata(s => s.b);
+            await b.mutate(b => { b.c = 101; });
+            expect(strata.state.a.b.c).is(101);
+            expect(a.state.b.c).is(101);
+            expect(b.state.c).is(101);
+            await a.mutate(a => { a.b = { c: 102 }; });
+            expect(strata.state.a.b.c).is(102);
+            expect(a.state.b.c).is(102);
+            expect(b.state.c).is(102);
+            await strata.mutate(s => { s.a = { b: { c: 103 } }; });
+            expect(strata.state.a.b.c).is(103);
+            expect(a.state.b.c).is(103);
+            expect(b.state.c).is(103);
+        }),
+        "onMutation 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++; });
+            await a.mutate(a => a.x = 1);
+            expect(counted).is(0);
+        }),
+    }),
+});
+//# sourceMappingURL=tests.test.js.map

package/x/tests.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tests.test.js","sourceRoot":"","sources":["../s/tests.test.ts"],"names":[],"mappings":"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"}