totally-tubular 0.3.3 → 0.4.1

package/README.md

@@ -18,7 +18,7 @@ npm i totally-tubular --save
 
 ## Core concepts
 
-A `Tubular` instance wraps an object and gives you four things:
+A `Tubular` instance wraps an object and gives you five things:
 
 | Method | What it does |
 |---|---|
@@ -26,6 +26,7 @@ A `Tubular` instance wraps an object and gives you four things:
 | `update(path, fn)` | Calls `fn` with the current value, stores the return value, then notifies all observers |
 | `observe(path, fn)` | Registers a callback that fires whenever `path` is updated |
 | `unobserve(path, fn)` | Removes a previously registered callback |
+| `reset()` | Restores every key to its initial value and notifies all observers of each change |
 
 Paths are fully type-checked. TypeScript knows every valid dot-path into your state shape, so you get autocomplete and a compile error if you mistype a key.
 
@@ -63,6 +64,30 @@ store.update("meta.title", (prev) => `Supreme ${prev}`);
 console.info(store.read("meta.title")); // "Supreme Director"
 ```
 
+## Resetting state
+
+Call `reset()` to restore your entire state back to the value you passed to the constructor. Every updated key is restored and every registered observer fires with the new (initial) value.
+
+```typescript
+const store = new Tubular({
+  name: "Alice",
+  count: 0,
+  settings: { theme: "light" },
+});
+
+store.update("name", () => "Bob");
+store.update("count", (prev) => prev + 1);
+store.update("settings.theme", () => "dark");
+
+store.observe("name", (newVal, oldVal) => {
+  console.log(`name: ${oldVal} -> ${newVal}`);
+});
+
+store.reset();
+// Logs: name: Bob -> Alice
+// Reads back: "Alice", 0, { theme: "light" }
+```
+
 ## React
 
 Import `useTubular` from `totally-tubular/react`. It works exactly like React's
@@ -115,6 +140,24 @@ setCount((prev) => (prev ?? 0) + 1);
 `useTubular` automatically unsubscribes when the component unmounts, so you
 don't need to manage cleanup yourself.
 
+### Resetting from React
+
+Import `useTubularReset` from `totally-tubular/react`. It returns a stable
+callback that restores the store to its initial state. Every `useTubular` hook
+watching the store re-renders with the restored value.
+
+```tsx
+import { useTubularReset } from "totally-tubular/react";
+
+function ResetButton() {
+  const handleReset = useTubularReset(store);
+  return <button onClick={handleReset}>Reset</button>;
+}
+```
+
+The callback identity never changes, so it's safe to pass directly as an event
+handler or as a dependency to `useEffect`.
+
 ## Things you should know
 
 - **Arrays and nested objects are observed at their path, not their contents.**
@@ -125,53 +168,55 @@ don't need to manage cleanup yourself.
 
 ## Performance benchmarks
 
+All benchmarks were run with Node.js 26.5.0 using the `tsx` TypeScript interpreter.
+
 ### Apple M3 Max · 36 GB RAM · macOS Sequoia 15.5
 
 ```
 -----shallow state object-----
 
-1,000 updates to "name" string val with 10 observers: 0.0036749580000000038s
-1,000 updates to "name" string val with 100 observers: 0.0004760830000000027s
-1,000 updates to "name" string val with 1000 observers: 0.002774291000000005s
-10,000 updates to "name" string val with 10 observers: 0.0014766249999999986s
-10,000 updates to "name" string val with 100 observers: 0.0023700000000000045s
-10,000 updates to "name" string val with 1000 observers: 0.010886792s
-100,000 updates to "name" string val with 10 observers: 0.012480834000000001s
-100,000 updates to "name" string val with 100 observers: 0.022641292000000007s
-100,000 updates to "name" string val with 1000 observers: 0.102325125s
-1,000,000 updates to "name" string val with 10 observers: 0.16086666700000002s
-1,000,000 updates to "name" string val with 100 observers: 0.26716437499999995s
-1,000,000 updates to "name" string val with 1000 observers: 1.0726739170000001s
+1,000 updates to "name" string val with 10 observers: 0.0005343750000000114s
+1,000 updates to "name" string val with 100 observers: 0.0006880840000000035s
+1,000 updates to "name" string val with 1000 observers: 0.002814292000000023s
+10,000 updates to "name" string val with 10 observers: 0.0007928750000000377s
+10,000 updates to "name" string val with 100 observers: 0.0017347500000000195s
+10,000 updates to "name" string val with 1000 observers: 0.007635916000000009s
+100,000 updates to "name" string val with 10 observers: 0.01587337500000001s
+100,000 updates to "name" string val with 100 observers: 0.020373334s
+100,000 updates to "name" string val with 1000 observers: 0.12892133400000005s
+1,000,000 updates to "name" string val with 10 observers: 0.14660462499999993s
+1,000,000 updates to "name" string val with 100 observers: 0.20982341600000007s
+1,000,000 updates to "name" string val with 1000 observers: 0.8595329590000002s
 
 -----medium state object-----
 
-1,000 updates to "user.settings.theme" string val with 10 observers: 0.000344333000000006s
-1,000 updates to "user.settings.theme" string val with 100 observers: 0.00034458300000005695s
-1,000 updates to "user.settings.theme" string val with 1000 observers: 0.0011382089999999608s
-10,000 updates to "user.settings.theme" string val with 10 observers: 0.0012657919999999195s
-10,000 updates to "user.settings.theme" string val with 100 observers: 0.002091625000000022s
-10,000 updates to "user.settings.theme" string val with 1000 observers: 0.010777082999999948s
-100,000 updates to "user.settings.theme" string val with 10 observers: 0.009487583000000086s
-100,000 updates to "user.settings.theme" string val with 100 observers: 0.01902945799999998s
-100,000 updates to "user.settings.theme" string val with 1000 observers: 0.11656079100000011s
-1,000,000 updates to "user.settings.theme" string val with 10 observers: 0.14811841699999992s
-1,000,000 updates to "user.settings.theme" string val with 100 observers: 0.27773633299999984s
-1,000,000 updates to "user.settings.theme" string val with 1000 observers: 1.0240415829999998s
+1,000 updates to "user.settings.theme" string val with 10 observers: 0.0011529580000001261s
+1,000 updates to "user.settings.theme" string val with 100 observers: 0.002206040999999914s
+1,000 updates to "user.settings.theme" string val with 1000 observers: 0.006846457999999984s
+10,000 updates to "user.settings.theme" string val with 10 observers: 0.01919616700000006s
+10,000 updates to "user.settings.theme" string val with 100 observers: 0.007707957999999963s
+10,000 updates to "user.settings.theme" string val with 1000 observers: 0.014114458000000014s
+100,000 updates to "user.settings.theme" string val with 10 observers: 0.012900958000000174s
+100,000 updates to "user.settings.theme" string val with 100 observers: 0.018197167000000035s
+100,000 updates to "user.settings.theme" string val with 1000 observers: 0.09116387499999973s
+1,000,000 updates to "user.settings.theme" string val with 10 observers: 0.18448416599999973s
+1,000,000 updates to "user.settings.theme" string val with 100 observers: 0.24980879200000028s
+1,000,000 updates to "user.settings.theme" string val with 1000 observers: 0.8701055419999998s
 
 -----deep state object-----
 
-1,000 updates to "zdeepSettings.level1.level2.level3.level4.level5.level6.currentValue" string val with 10 observers: 0.0012417919999998049s
-1,000 updates to "zdeepSettings.level1.level2.level3.level4.level5.level6.currentValue" string val with 100 observers: 0.0003201250000001892s
-1,000 updates to "zdeepSettings.level1.level2.level3.level4.level5.level6.currentValue" string val with 1000 observers: 0.0011683750000001964s
-10,000 updates to "zdeepSettings.level1.level2.level3.level4.level5.level6.currentValue" string val with 10 observers: 0.0014113330000000133s
-10,000 updates to "zdeepSettings.level1.level2.level3.level4.level5.level6.currentValue" string val with 100 observers: 0.002289249999999811s
-10,000 updates to "zdeepSettings.level1.level2.level3.level4.level5.level6.currentValue" string val with 1000 observers: 0.01099350000000004s
-100,000 updates to "zdeepSettings.level1.level2.level3.level4.level5.level6.currentValue" string val with 10 observers: 0.014709209000000101s
-100,000 updates to "zdeepSettings.level1.level2.level3.level4.level5.level6.currentValue" string val with 100 observers: 0.024220374999999877s
-100,000 updates to "zdeepSettings.level1.level2.level3.level4.level5.level6.currentValue" string val with 1000 observers: 0.10777845800000023s
-1,000,000 updates to "zdeepSettings.level1.level2.level3.level4.level5.level6.currentValue" string val with 10 observers: 0.22398191699999961s
-1,000,000 updates to "zdeepSettings.level1.level2.level3.level4.level5.level6.currentValue" string val with 100 observers: 0.2829787500000002s
-1,000,000 updates to "zdeepSettings.level1.level2.level3.level4.level5.level6.currentValue" string val with 1000 observers: 1.1015419579999999s
+1,000 updates to "zdeepSettings.level1.level2.level3.level4.level5.level6.currentValue" string val with 10 observers: 0.0002052080000003116s
+1,000 updates to "zdeepSettings.level1.level2.level3.level4.level5.level6.currentValue" string val with 100 observers: 0.0002497920000000704s
+1,000 updates to "zdeepSettings.level1.level2.level3.level4.level5.level6.currentValue" string val with 1000 observers: 0.001332209000000148s
+10,000 updates to "zdeepSettings.level1.level2.level3.level4.level5.level6.currentValue" string val with 10 observers: 0.0018820000000000618s
+10,000 updates to "zdeepSettings.level1.level2.level3.level4.level5.level6.currentValue" string val with 100 observers: 0.0024639170000000377s
+10,000 updates to "zdeepSettings.level1.level2.level3.level4.level5.level6.currentValue" string val with 1000 observers: 0.014082249999999932s
+100,000 updates to "zdeepSettings.level1.level2.level3.level4.level5.level6.currentValue" string val with 10 observers: 0.021280209000000015s
+100,000 updates to "zdeepSettings.level1.level2.level3.level4.level5.level6.currentValue" string val with 100 observers: 0.02714695800000027s
+100,000 updates to "zdeepSettings.level1.level2.level3.level4.level5.level6.currentValue" string val with 1000 observers: 0.09046704200000022s
+1,000,000 updates to "zdeepSettings.level1.level2.level3.level4.level5.level6.currentValue" string val with 10 observers: 0.2687363329999998s
+1,000,000 updates to "zdeepSettings.level1.level2.level3.level4.level5.level6.currentValue" string val with 100 observers: 0.3244868329999999s
+1,000,000 updates to "zdeepSettings.level1.level2.level3.level4.level5.level6.currentValue" string val with 1000 observers: 0.9486893330000002s
 ```
 
 ### Intel i9-13900HX · 32 GB RAM · Windows 11

package/dist/object.d.ts

@@ -0,0 +1,3 @@
+export declare function isArray(thing: unknown): thing is unknown[];
+export declare function isObject(thing: unknown): thing is object;
+export declare function isNullOrUndefined(thing: unknown): thing is null | undefined;

package/dist/object.js

@@ -0,0 +1,9 @@
+export function isArray(thing) {
+    return Array.isArray(thing);
+}
+export function isObject(thing) {
+    return typeof thing === 'object';
+}
+export function isNullOrUndefined(thing) {
+    return thing === null || thing === undefined || typeof thing === 'undefined';
+}

package/dist/react.d.ts

@@ -28,3 +28,26 @@ import type { AllObjectKeys, PropType } from './types.js';
  * ```
  */
 export declare function useTubular<T extends object, K extends string>(tubular: Tubular<T>, key: K & AllObjectKeys<T>): readonly [PropType<T, K> | null, (newValOrCallback: PropType<T, K> | ((prevVal: PropType<T, K> | null) => PropType<T, K>)) => void];
+/**
+ * A React hook that returns a stable callback to reset a {@link Tubular} store
+ * back to its initial state.
+ *
+ * Every key in the store is restored to the value originally passed to the
+ * constructor, and every registered observer (including {@link useTubular}
+ * hooks) is notified of each change.
+ *
+ * The returned callback is stable across re-renders.
+ * It never changes its identity, so it is safe to pass as a dependency to `useEffect` or as a prop
+ * to memoized components.
+ *
+ * @example
+ * ```tsx
+ * const store = new Tubular({ name: 'Alice', count: 0 });
+ *
+ * function ResetButton() {
+ *   const handleReset = useTubularReset(store);
+ *   return <button onClick={handleReset}>Reset</button>;
+ * }
+ * ```
+ */
+export declare function useTubularReset<T extends object>(tubular: Tubular<T>): () => void;

package/dist/react.js

@@ -52,3 +52,28 @@ export function useTubular(tubular, key) {
     }, [tubular, key]);
     return [val, handleUpdateVal];
 }
+/**
+ * A React hook that returns a stable callback to reset a {@link Tubular} store
+ * back to its initial state.
+ *
+ * Every key in the store is restored to the value originally passed to the
+ * constructor, and every registered observer (including {@link useTubular}
+ * hooks) is notified of each change.
+ *
+ * The returned callback is stable across re-renders.
+ * It never changes its identity, so it is safe to pass as a dependency to `useEffect` or as a prop
+ * to memoized components.
+ *
+ * @example
+ * ```tsx
+ * const store = new Tubular({ name: 'Alice', count: 0 });
+ *
+ * function ResetButton() {
+ *   const handleReset = useTubularReset(store);
+ *   return <button onClick={handleReset}>Reset</button>;
+ * }
+ * ```
+ */
+export function useTubularReset(tubular) {
+    return useCallback(() => tubular.reset(), [tubular]);
+}

package/dist/totally-tubular.d.ts

@@ -8,6 +8,7 @@ import type { AllObjectKeys, ObservationCallback, PropType } from './types.js';
 export declare class Tubular<T extends object> {
     private observationCallbacks;
     private state;
+    private initialStateClone;
     constructor(initialState: T);
     private doSomethingToPath;
     private getPortionOfStateByPath;
@@ -19,6 +20,12 @@ export declare class Tubular<T extends object> {
      * reads a portion of your state
      */
     read<K extends string>(readPath: K & AllObjectKeys<T>): PropType<T, K> | null;
+    private resetImpl;
+    /**
+     * resets the state back to its initial value
+     * (the value you provided to the constructor)
+     */
+    reset(): void;
     /**
      * disconnects an observer callback from totally tubular
      */

package/dist/totally-tubular.js

@@ -1,3 +1,4 @@
+import { isArray, isNullOrUndefined, isObject } from './object.js';
 /**
  * A totally tubular instance that tracks a top-level
  * set of keys and values.
@@ -7,14 +8,13 @@
 export class Tubular {
     observationCallbacks = new Map();
     state;
+    initialStateClone;
     constructor(initialState) {
         this.state = initialState;
+        this.initialStateClone = globalThis.structuredClone(this.state);
     }
     doSomethingToPath(readPath, doSomething) {
         let thing = this.state;
-        if (typeof readPath !== 'string') {
-            return this.getPortionOfStateByPath(thing[readPath]);
-        }
         const splitPath = readPath.split('.');
         const len = splitPath.length;
         for (let i = 0; i < len; i++) {
@@ -26,15 +26,9 @@ export class Tubular {
             else
                 thing = thing?.[p];
         }
-        for (const p of splitPath) {
-            thing = thing?.[p];
-        }
     }
     getPortionOfStateByPath(readPath) {
         let thing = this.state;
-        if (typeof readPath !== 'string') {
-            return this.getPortionOfStateByPath(thing[readPath]);
-        }
         const splitPath = readPath.split('.');
         for (const p of splitPath) {
             thing = thing?.[p];
@@ -54,6 +48,32 @@ export class Tubular {
     read(readPath) {
         return this.getPortionOfStateByPath(readPath);
     }
+    resetImpl(parentKey) {
+        let sourceObj = this.initialStateClone;
+        if (parentKey) {
+            for (const p of parentKey.split('.')) {
+                sourceObj = sourceObj?.[p];
+            }
+            if (isNullOrUndefined(sourceObj) || !isObject(sourceObj))
+                return;
+        }
+        for (const [key, val] of Object.entries(sourceObj)) {
+            const childKey = parentKey ? `${parentKey}.${key}` : key;
+            if (!isNullOrUndefined(val) && isObject(val) && !isArray(val)) {
+                this.resetImpl(childKey);
+            }
+            else {
+                this.update(childKey, () => val);
+            }
+        }
+    }
+    /**
+     * resets the state back to its initial value
+     * (the value you provided to the constructor)
+     */
+    reset() {
+        this.resetImpl();
+    }
     /**
      * disconnects an observer callback from totally tubular
      */

package/dist/types.d.ts

@@ -8,7 +8,7 @@ type IsCollection<T> = T extends readonly any[] | Map<any, any> | Set<any> ? tru
 /**
  * Produces every dot-separated key path into T as a string union.
  *
- * - The `Depth` tuple acts as a recursion counter: when its length reaches 5 the
+ * - The `Depth` tuple acts as a recursion counter: when its length reaches 10 the
  *   type resolves to `never`, which caps the union size and prevents the language
  *   server from hanging on deeply-nested or self-referential shapes.
  * - Top-level keys are included as bare strings (`K`), so this type supersedes
@@ -18,7 +18,7 @@ type IsCollection<T> = T extends readonly any[] | Map<any, any> | Set<any> ? tru
  * - Returning `never` (not `''`) from every terminal branch avoids the need for
  *   a secondary `Extract<D, string>` pass over the full union.
  */
-export type DotNestedKeys<T, Depth extends 1[] = []> = Depth['length'] extends 5 ? never : T extends object ? IsCollection<T> extends true ? never : {
+export type DotNestedKeys<T, Depth extends 1[] = []> = Depth['length'] extends 10 ? never : T extends object ? IsCollection<T> extends true ? never : {
     [K in keyof T & string]: IsCollection<T[K]> extends true ? K : T[K] extends object ? K | `${K}.${DotNestedKeys<T[K], [...Depth, 1]>}` : K;
 }[keyof T & string] : never;
 /**

package/package.json

@@ -3,7 +3,7 @@
   "description": "A completely framework-agnostic, JavaScript / TypeScript state management and update broadcasting library wit zero dependencies, solid performance and a micro file size.",
   "name": "totally-tubular",
   "type": "module",
-  "version": "0.3.3",
+  "version": "0.4.1",
   "keywords": [
     "state",
     "management",
@@ -26,25 +26,24 @@
   "files": [
     "dist/"
   ],
-  "scripts": {
-    "build": "rm -rf dist/ && tsc --project ./tsconfig.build.json",
-    "clean": "rm -rf dist/",
-    "test": "bun test",
-    "test:watch": "bun test --watch"
-  },
   "devDependencies": {
     "@better-builds/lets-version": "^1.6.0",
-    "@biomejs/biome": "^2.4.11",
-    "@commitlint/cli": "^20.5.0",
-    "@commitlint/config-conventional": "^20.5.0",
-    "@happy-dom/global-registrator": "^20.9.0",
+    "@biomejs/biome": "^2.4.16",
+    "@commitlint/cli": "^20.5.3",
+    "@commitlint/config-conventional": "^20.5.3",
     "@testing-library/react": "^16.3.2",
     "@testing-library/user-event": "^14.6.1",
-    "@types/bun": "latest",
-    "@types/react": "^19.2.14",
-    "happy-dom": "^20.9.0",
-    "react": ">=18",
-    "typescript": "^5.9.3"
+    "@types/react": "^19.2.17",
+    "@types/node": "^26.1.1",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^6.0.3",
+    "happy-dom": "^20.10.2",
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7",
+    "tsx": "^4.23.0",
+    "typescript": "^5.9.3",
+    "vite": "^8.1.4",
+    "vitest": "^4.1.10"
   },
   "peerDependencies": {
     "react": ">=18"
@@ -72,5 +71,12 @@
       "default": "./dist/types.js"
     },
     "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "rm -rf dist/ && tsc --project ./tsconfig.build.json",
+    "clean": "rm -rf dist/",
+    "test": "vitest test",
+    "test:performance": "tsx ./performanceTests.ts",
+    "test:watch": "vitest test --watch"
   }
-}
+}