totally-tubular 0.3.3 → 0.4.0

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.**

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/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.0",
   "keywords": [
     "state",
     "management",
@@ -34,16 +34,18 @@
   },
   "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",
+    "@happy-dom/global-registrator": "^20.10.2",
     "@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",
+    "@types/react": "^19.2.17",
+    "@types/react-dom": "^19.2.3",
+    "happy-dom": "^20.10.2",
+    "react-dom": "^19.2.7",
+    "react": "^19.2.7",
     "typescript": "^5.9.3"
   },
   "peerDependencies": {