totally-tubular 0.1.2 → 0.3.1

package/README.md

@@ -1,24 +1,14 @@
 # totally-tubular
 
-A completely framework-agnostic, JavaScript / TypeScript state management and update broadcasting library with zero dependencies, solid performance and a micro file size.
+A framework-agnostic JavaScript / TypeScript state management library with zero dependencies, a tiny file size, and solid performance.
 
-**Woahhhh**
+## Why another state management library?
 
-## But why is there _another_ state management library? I already use XYZ library.
+State management has a tendency to get complicated fast. This library is an experiment in keeping things simple:
 
-Great! I'm glad you found something that works for you!
-This library (`totally-tubular`) was an experiment that manifested out of feeling
-like state management is overcomplicated these days and often riddled with "gotchas"
-and easy-to-oopsie performance faux pas.
-
-Additionally, our shipped JavaScript bundles should be getting **smaller**, not **bigger**,
-but it's all-too-easy, especially when crafting enterprise software, to keep shoving more libraries
-into your bundle with questionable benefits, when there often exists a much simpler, closer-to-vanilla
-way to do what you need to do.
-
-As a final point, your state management system should be fully-portable, so if you swap out
-your rendering layer, be it React, Svelte, Angular, or something else, the meat-and-potatoes of
-your state management shouldn't need to be fully rewritten.
+- **Portable.** Your store is plain TypeScript. If you swap React for Svelte, or add a Node.js background worker, the store itself doesn't change.
+- **Small.** No framework coupling, no middleware pipeline, no magic — just a class that holds state, lets you read it, update it, and watch it for changes.
+- **Honest.** It mutates your state in place for performance. If you want immutability, return new objects from your updater functions.
 
 ## Install
 
@@ -26,12 +16,25 @@ your state management shouldn't need to be fully rewritten.
 npm i totally-tubular --save
 ```
 
+## Core concepts
+
+A `Tubular` instance wraps an object and gives you four things:
+
+| Method | What it does |
+|---|---|
+| `read(path)` | Returns the current value at a dot-separated path |
+| `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 |
+
+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.
+
 ## Quick start
 
 ```typescript
 import { Tubular } from "totally-tubular";
 
-interface MyStateShape {
+interface AppState {
   isActive: boolean;
   count: number;
   meta: {
@@ -40,107 +43,89 @@ interface MyStateShape {
   name: string;
 }
 
-const initialState: MyStateShape = {
+const store = new Tubular<AppState>({
   isActive: false,
   count: 123,
-  meta: {
-    title: "Director",
-  },
+  meta: { title: "Director" },
   name: "Test User",
-};
-
-const t = new Tubular(initialState);
+});
 
-// listen to any of the keys / values in your state object for changes
-// and do whatever you need with the values
-t.observe("meta.title", (newVal, oldVal, propPath) =>
-  console.info(propPath, "was updated from", oldVal, "to", newVal),
+// Watch a value for changes
+store.observe("meta.title", (newVal, oldVal) =>
+  console.info("title changed from", oldVal, "to", newVal),
 );
 
-console.info(t.read("meta.title")); // will print 'Director'
+console.info(store.read("meta.title")); // "Director"
+
+// Update a value — all observers are notified immediately after
+store.update("meta.title", (prev) => `Supreme ${prev}`);
 
-// update any of the keys / values in your state object.
-// all observers will be notified after the value has been set
-t.update("meta.title", (prev) => `Supreme ${prev}`);
-console.info(t.read("meta.title")); // will print the updated 'Supreme Director' value
+console.info(store.read("meta.title")); // "Supreme Director"
 ```
 
-### React example
+## React
 
-Since React is one of the most popular UI libraries, here is how you might mimick the vanilla example, above, but in a React application.
+Import `useTubular` from `totally-tubular/react`. It works exactly like React's
+built-in `useState` — you get back a `[value, setter]` tuple — except the value
+comes from your store and every component watching the same path re-renders when
+it changes.
 
 ```tsx
 import { Tubular } from "totally-tubular";
-import { useEffect, useState } from "react";
+import { useTubular } from "totally-tubular/react";
 
-interface MyState {
-  permissions: {
-    entitlements: string[];
-  };
-  time: number;
-  username: string;
+interface AppState {
+  user: { name: string };
+  count: number;
 }
 
-const initialState: MyState = {
-  permissions: { entitlements: [] },
-  username: "Test User",
-  time: Date.now(),
-};
-
-const t = new Tubular<MyState>(initialState);
+// Create the store once, outside your components
+const store = new Tubular<AppState>({
+  user: { name: "Alice" },
+  count: 0,
+});
 
-const getTime = (timestamp: number) => {
-  const d = new Date();
-  d.setTime(timestamp);
-  return d.toLocaleTimeString();
-};
-
-export default function App() {
-  /** state */
-  const [username, setUsername] = useState(initialState.username);
-  const [time, setTime] = useState(initialState.time);
-
-  /** effects */
-  useEffect(() => {
-    t.observe("username", (v) => setUsername(v));
-    t.observe("time", (t) => setTime(t));
-  }, []);
-
-  useEffect(() => {
-    const interval = setInterval(() => t.update("time", (oldVal) => oldVal + 1000), 1000);
-
-    return () => {
-      clearInterval(interval);
-    };
-  }, []);
+function Counter() {
+  const [count, setCount] = useTubular(store, "count");
 
   return (
-    <div>
-      <strong>User: {username}</strong>
-      <div>The time: {getTime(time)}</div>
-    </div>
+    <button onClick={() => setCount((n) => (n ?? 0) + 1)}>
+      Clicked {count} times
+    </button>
   );
 }
+
+function Greeting() {
+  // Read-only — just destructure the first element
+  const [name] = useTubular(store, "user.name");
+  return <p>Hello, {name}!</p>;
+}
 ```
 
-## Things you should know
+The setter accepts either a plain value or an updater function:
+
+```ts
+// Plain value
+setCount(10);
+
+// Updater function (receives the current value)
+setCount((prev) => (prev ?? 0) + 1);
+```
 
-- This library _does not_ support observing arbitrary indices in an array, or objects inside of an array.
-  This is intentional.
-  If you want to be notified of changes to an array or you want to update some item in an array, you should use the path to the array in your state object, then perform reads or transformations on that.
-- This library **mutates your originally-provided `initialState`**.
-  This is for performance reasons, as mutating objects doesn't require cloning and iterating on all object properties, saving on computation time.
-  If you want to ensure immutability, you should make your calls to `.update()` return new objects, array, etc.
+`useTubular` automatically unsubscribes when the component unmounts, so you
+don't need to manage cleanup yourself.
 
-## (Extra) Synthetic Performance Benchmarks
+## Things you should know
 
-### Machine specs
+- **Arrays and nested objects are observed at their path, not their contents.**
+  `observe("items", fn)` fires when `items` itself is replaced. To add an item
+  to an array, use `update("items", prev => [...prev, newItem])`.
+- **Arbitrary array indices are not observable.** You cannot do `observe("items.0", fn)`. If you need per-item reactivity, store each item in its own `Tubular` instance.
+- **State is mutated in place.** `totally-tubular` does not clone your state on every update. This keeps things fast, but means the object you pass to `new Tubular(initialState)` will be modified directly. If that matters to you, pass a deep clone as the initial state.
 
-#### Apple Machine
+## Performance benchmarks
 
-CPU: M3 Max
-RAM: 36GB
-OS: MacOS Sequoia 15.5
+### Apple M3 Max · 36 GB RAM · macOS Sequoia 15.5
 
 ```
 -----shallow state object-----
@@ -189,11 +174,7 @@ OS: MacOS Sequoia 15.5
 1,000,000 updates to "zdeepSettings.level1.level2.level3.level4.level5.level6.currentValue" string val with 1000 observers: 1.1015419579999999s
 ```
 
-#### Windows Machine
-
-CPU: Intel i9-13900HX
-RAM: 32GB
-OS: Windows 11
+### Intel i9-13900HX · 32 GB RAM · Windows 11
 
 ```
 -----shallow state object-----

package/dist/cjs/package.json

@@ -0,0 +1 @@
+{ "type": "commonjs" }

package/dist/cjs/react.cjs

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+Object.defineProperty(exports, "useTubular", {
+    enumerable: true,
+    get: function() {
+        return useTubular;
+    }
+});
+const _react = require("./react.cjs");
+function useTubular(tubular, key) {
+    /** state */ const [val, setVal] = (0, _react.useState)(()=>tubular.read(key));
+    /** callbacks */ const handleUpdateVal = (0, _react.useCallback)((newValOrCallback)=>{
+        if (typeof newValOrCallback === 'function') {
+            tubular.update(key, newValOrCallback);
+        } else {
+            tubular.update(key, ()=>newValOrCallback);
+        }
+    }, [
+        tubular,
+        key
+    ]);
+    /** effects */ (0, _react.useEffect)(()=>{
+        // Sync in case the value changed between render and effect registration
+        setVal(tubular.read(key));
+        const observeCb = (newVal)=>{
+            setVal(newVal);
+        };
+        tubular.observe(key, observeCb);
+        return ()=>{
+            tubular.unobserve(key, observeCb);
+        };
+    }, [
+        tubular,
+        key
+    ]);
+    return [
+        val,
+        handleUpdateVal
+    ];
+}

package/dist/cjs/react.d.ts

@@ -0,0 +1,30 @@
+import type { Tubular } from './totally-tubular.js';
+import type { AllObjectKeys, PropType } from './types.js';
+/**
+ * A React hook that binds to a {@link Tubular} instance and a specific key path
+ * within its state.
+ *
+ * Returns a `[value, setter]` tuple that works exactly like React's built-in
+ * `useState`, except reads and writes go through the Tubular store — so every
+ * component (and non-React observer) watching the same path is notified on
+ * every update.
+ *
+ * The setter accepts either a new value directly or an updater function that
+ * receives the current value and returns the next one.
+ *
+ * @example
+ * ```tsx
+ * const store = new Tubular({ user: { name: 'Alice' }, count: 0 });
+ *
+ * function Counter() {
+ *   const [count, setCount] = useTubular(store, 'count');
+ *   return <button onClick={() => setCount(n => (n ?? 0) + 1)}>{count}</button>;
+ * }
+ *
+ * function Greeting() {
+ *   const [name] = useTubular(store, 'user.name');
+ *   return <p>Hello, {name}!</p>;
+ * }
+ * ```
+ */
+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];

package/dist/cjs/totally-tubular.cjs

@@ -0,0 +1,80 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+Object.defineProperty(exports, "Tubular", {
+    enumerable: true,
+    get: function() {
+        return Tubular;
+    }
+});
+class Tubular {
+    observationCallbacks = new Map();
+    state;
+    constructor(initialState){
+        this.state = initialState;
+    }
+    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++){
+            const p = splitPath[i] || '';
+            if (i === len - 1) {
+                if (thing) thing[p] = doSomething(thing[p]);
+            } 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];
+        }
+        return thing ?? null;
+    }
+    /**
+   * observe changes to some part of state that was updated
+   */ observe(propPath, observeCallback) {
+        const prevForPath = this.observationCallbacks.get(propPath) ?? [];
+        this.observationCallbacks.set(propPath, [
+            ...prevForPath,
+            observeCallback
+        ]);
+    }
+    /**
+   * reads a portion of your state
+   */ read(readPath) {
+        return this.getPortionOfStateByPath(readPath);
+    }
+    /**
+   * disconnects an observer callback from totally tubular
+   */ unobserve(propPath, observeCallback) {
+        const observers = this.observationCallbacks.get(propPath);
+        if (!observers?.length) return;
+        this.observationCallbacks.set(propPath, observers.filter((ob)=>ob !== observeCallback));
+    }
+    /**
+   * updates a portion of your state
+   */ update(updatePath, valUpdater) {
+        const prevVal = this.read(updatePath);
+        let newVal = null;
+        this.doSomethingToPath(updatePath, (oldVal)=>{
+            const n = valUpdater(oldVal);
+            newVal = n;
+            return n;
+        });
+        for (const cb of this.observationCallbacks.get(updatePath) ?? []){
+            cb(newVal, prevVal, updatePath);
+        }
+    }
+}

package/dist/{totally-tubular.d.ts → cjs/totally-tubular.d.ts}

@@ -1,4 +1,4 @@
-import type { AllObjectKeys, PropType } from './types.js';
+import type { AllObjectKeys, ObservationCallback, PropType } from './types.js';
 /**
  * A totally tubular instance that tracks a top-level
  * set of keys and values.
@@ -14,17 +14,17 @@ export declare class Tubular<T extends object> {
     /**
      * observe changes to some part of state that was updated
      */
-    observe<K extends AllObjectKeys<T>, V = PropType<T, K & string>>(propPath: K, observeCallback: (newVal: V, oldVal: V, propPath: K) => void): void;
+    observe<K extends string>(propPath: K & AllObjectKeys<T>, observeCallback: ObservationCallback<T>): void;
     /**
      * reads a portion of your state
      */
-    read<K extends AllObjectKeys<T>>(readPath: K): PropType<T, K & string> | null;
+    read<K extends string>(readPath: K & AllObjectKeys<T>): PropType<T, K> | null;
     /**
      * disconnects an observer callback from totally tubular
      */
-    unobserve<K extends AllObjectKeys<T>, V = PropType<T, K & string>>(propPath: K, observeCallback: (newVal: V, oldVal: V) => void): void;
+    unobserve<K extends string>(propPath: K & AllObjectKeys<T>, observeCallback: ObservationCallback<T>): void;
     /**
      * updates a portion of your state
      */
-    update<K extends AllObjectKeys<T>>(updatePath: K, valUpdater: (oldVal: PropType<T, K & string>) => PropType<T, K & string>): void;
+    update<K extends string>(updatePath: K & AllObjectKeys<T>, valUpdater: (oldVal: PropType<T, K>) => PropType<T, K>): void;
 }

package/dist/cjs/types.cjs

@@ -0,0 +1,4 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});

package/dist/cjs/types.d.ts

@@ -0,0 +1,53 @@
+export type TSPrimitve = string | number | bigint | boolean | symbol | undefined | null;
+/**
+ * Single-check collection guard.
+ * `readonly any[]` covers both `any[]` and `ReadonlyArray<any>` since `Array<T>`
+ * extends `ReadonlyArray<T>`. One distributive check instead of four sequential ones.
+ */
+type IsCollection<T> = T extends readonly any[] | Map<any, any> | Set<any> ? true : false;
+/**
+ * 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
+ *   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
+ *   `keyof T & string` — there is no need for a separate union with `keyof T`.
+ * - Collections (arrays, Map, Set) are terminated at their key rather than
+ *   recursed into.
+ * - 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 : {
+    [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;
+/**
+ * All valid key paths into T (top-level and dot-nested).
+ *
+ * `DotNestedKeys<T>` already emits top-level string keys alongside nested paths,
+ * so a `keyof T` union is redundant and was previously responsible for duplicate
+ * entries that the checker had to deduplicate on every instantiation.
+ */
+export type AllObjectKeys<T> = DotNestedKeys<T>;
+/**
+ * Resolves the value type at a dot-separated path P within T.
+ *
+ * The intermediate `Rest extends AllObjectKeys<T[Head]>` guard that previously
+ * existed here forced a full re-evaluation of `AllObjectKeys` at every recursive
+ * level. It has been removed: if `Rest` is not a valid path the recursion
+ * naturally returns `never`, which is the correct result.
+ */
+export type PropType<T, P extends string> = P extends keyof T ? T[P] : P extends `${infer Head}.${infer Rest}` ? Head extends keyof T ? PropType<T[Head], Rest> : never : never;
+/**
+ * Callback invoked by Tubular whenever an observed path changes.
+ *
+ * The previous definition used defaulted type parameters
+ * (`K = AllObjectKeys<T>`, `V = PropType<T, K & string>`). Default type
+ * parameters are eagerly evaluated by the checker at *every* reference to
+ * `ObservationCallback<T>`, causing a full `AllObjectKeys<T>` + distributed
+ * `PropType` expansion each time. Using `unknown` for the value parameters
+ * defers any narrowing to call sites that actually need it, which is a far
+ * smaller surface area.
+ */
+export type ObservationCallback<T> = (newVal: unknown, oldVal: unknown, propPath: AllObjectKeys<T>) => void;
+export {};

package/dist/esm/package.json

@@ -0,0 +1 @@
+{ "type": "module" }

package/dist/esm/react.d.ts

@@ -0,0 +1,30 @@
+import type { Tubular } from './totally-tubular.js';
+import type { AllObjectKeys, PropType } from './types.js';
+/**
+ * A React hook that binds to a {@link Tubular} instance and a specific key path
+ * within its state.
+ *
+ * Returns a `[value, setter]` tuple that works exactly like React's built-in
+ * `useState`, except reads and writes go through the Tubular store — so every
+ * component (and non-React observer) watching the same path is notified on
+ * every update.
+ *
+ * The setter accepts either a new value directly or an updater function that
+ * receives the current value and returns the next one.
+ *
+ * @example
+ * ```tsx
+ * const store = new Tubular({ user: { name: 'Alice' }, count: 0 });
+ *
+ * function Counter() {
+ *   const [count, setCount] = useTubular(store, 'count');
+ *   return <button onClick={() => setCount(n => (n ?? 0) + 1)}>{count}</button>;
+ * }
+ *
+ * function Greeting() {
+ *   const [name] = useTubular(store, 'user.name');
+ *   return <p>Hello, {name}!</p>;
+ * }
+ * ```
+ */
+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];

package/dist/esm/react.mjs

@@ -0,0 +1,58 @@
+import { useCallback, useEffect, useState } from './react.mjs';
+/**
+ * A React hook that binds to a {@link Tubular} instance and a specific key path
+ * within its state.
+ *
+ * Returns a `[value, setter]` tuple that works exactly like React's built-in
+ * `useState`, except reads and writes go through the Tubular store — so every
+ * component (and non-React observer) watching the same path is notified on
+ * every update.
+ *
+ * The setter accepts either a new value directly or an updater function that
+ * receives the current value and returns the next one.
+ *
+ * @example
+ * ```tsx
+ * const store = new Tubular({ user: { name: 'Alice' }, count: 0 });
+ *
+ * function Counter() {
+ *   const [count, setCount] = useTubular(store, 'count');
+ *   return <button onClick={() => setCount(n => (n ?? 0) + 1)}>{count}</button>;
+ * }
+ *
+ * function Greeting() {
+ *   const [name] = useTubular(store, 'user.name');
+ *   return <p>Hello, {name}!</p>;
+ * }
+ * ```
+ */ export function useTubular(tubular, key) {
+    /** state */ const [val, setVal] = useState(()=>tubular.read(key));
+    /** callbacks */ const handleUpdateVal = useCallback((newValOrCallback)=>{
+        if (typeof newValOrCallback === 'function') {
+            tubular.update(key, newValOrCallback);
+        } else {
+            tubular.update(key, ()=>newValOrCallback);
+        }
+    }, [
+        tubular,
+        key
+    ]);
+    /** effects */ useEffect(()=>{
+        // Sync in case the value changed between render and effect registration
+        setVal(tubular.read(key));
+        const observeCb = (newVal)=>{
+            setVal(newVal);
+        };
+        tubular.observe(key, observeCb);
+        return ()=>{
+            tubular.unobserve(key, observeCb);
+        };
+    }, [
+        tubular,
+        key
+    ]);
+    return [
+        val,
+        handleUpdateVal
+    ];
+}

package/dist/esm/totally-tubular.d.ts

@@ -0,0 +1,30 @@
+import type { AllObjectKeys, ObservationCallback, PropType } from './types.js';
+/**
+ * A totally tubular instance that tracks a top-level
+ * set of keys and values.
+ * if you want to support nested or "deep" state updates and observations,
+ * you should construct your state to be a series of Tubular instances
+ */
+export declare class Tubular<T extends object> {
+    private observationCallbacks;
+    private state;
+    constructor(initialState: T);
+    private doSomethingToPath;
+    private getPortionOfStateByPath;
+    /**
+     * observe changes to some part of state that was updated
+     */
+    observe<K extends string>(propPath: K & AllObjectKeys<T>, observeCallback: ObservationCallback<T>): void;
+    /**
+     * reads a portion of your state
+     */
+    read<K extends string>(readPath: K & AllObjectKeys<T>): PropType<T, K> | null;
+    /**
+     * disconnects an observer callback from totally tubular
+     */
+    unobserve<K extends string>(propPath: K & AllObjectKeys<T>, observeCallback: ObservationCallback<T>): void;
+    /**
+     * updates a portion of your state
+     */
+    update<K extends string>(updatePath: K & AllObjectKeys<T>, valUpdater: (oldVal: PropType<T, K>) => PropType<T, K>): void;
+}

package/dist/{totally-tubular.js → esm/totally-tubular.mjs}

@@ -3,11 +3,10 @@
  * set of keys and values.
  * if you want to support nested or "deep" state updates and observations,
  * you should construct your state to be a series of Tubular instances
- */
-export class Tubular {
+ */ export class Tubular {
     observationCallbacks = new Map();
     state;
-    constructor(initialState) {
+    constructor(initialState){
         this.state = initialState;
     }
     doSomethingToPath(readPath, doSomething) {
@@ -17,16 +16,13 @@ export class Tubular {
         }
         const splitPath = readPath.split('.');
         const len = splitPath.length;
-        for (let i = 0; i < len; i++) {
+        for(let i = 0; i < len; i++){
             const p = splitPath[i] || '';
             if (i === len - 1) {
-                if (thing)
-                    thing[p] = doSomething(thing[p]);
-            }
-            else
-                thing = thing?.[p];
+                if (thing) thing[p] = doSomething(thing[p]);
+            } else thing = thing?.[p];
         }
-        for (const p of splitPath) {
+        for (const p of splitPath){
             thing = thing?.[p];
         }
     }
@@ -36,46 +32,44 @@ export class Tubular {
             return this.getPortionOfStateByPath(thing[readPath]);
         }
         const splitPath = readPath.split('.');
-        for (const p of splitPath) {
+        for (const p of splitPath){
             thing = thing?.[p];
         }
         return thing ?? null;
     }
     /**
-     * observe changes to some part of state that was updated
-     */
-    observe(propPath, observeCallback) {
+   * observe changes to some part of state that was updated
+   */ observe(propPath, observeCallback) {
         const prevForPath = this.observationCallbacks.get(propPath) ?? [];
-        // @ts-expect-error - silce! they are the same
-        this.observationCallbacks.set(propPath, [...prevForPath, observeCallback]);
+        this.observationCallbacks.set(propPath, [
+            ...prevForPath,
+            observeCallback
+        ]);
     }
     /**
-     * reads a portion of your state
-     */
-    read(readPath) {
+   * reads a portion of your state
+   */ read(readPath) {
         return this.getPortionOfStateByPath(readPath);
     }
     /**
-     * disconnects an observer callback from totally tubular
-     */
-    unobserve(propPath, observeCallback) {
+   * disconnects an observer callback from totally tubular
+   */ unobserve(propPath, observeCallback) {
         const observers = this.observationCallbacks.get(propPath);
-        if (!observers?.length)
-            return;
-        this.observationCallbacks.set(propPath, observers.filter(ob => ob !== observeCallback));
+        if (!observers?.length) return;
+        this.observationCallbacks.set(propPath, observers.filter((ob)=>ob !== observeCallback));
     }
     /**
-     * updates a portion of your state
-     */
-    update(updatePath, valUpdater) {
+   * updates a portion of your state
+   */ update(updatePath, valUpdater) {
         const prevVal = this.read(updatePath);
         let newVal = null;
-        this.doSomethingToPath(updatePath, oldVal => {
+        this.doSomethingToPath(updatePath, (oldVal)=>{
             const n = valUpdater(oldVal);
             newVal = n;
             return n;
         });
-        // @ts-expect-error - runtime safe and solid in-IDE typing assistance, so silence as required
-        this.observationCallbacks.get(updatePath)?.forEach(cb => cb(newVal, prevVal, updatePath));
+        for (const cb of this.observationCallbacks.get(updatePath) ?? []){
+            cb(newVal, prevVal, updatePath);
+        }
     }
 }

package/dist/esm/types.d.ts

@@ -0,0 +1,53 @@
+export type TSPrimitve = string | number | bigint | boolean | symbol | undefined | null;
+/**
+ * Single-check collection guard.
+ * `readonly any[]` covers both `any[]` and `ReadonlyArray<any>` since `Array<T>`
+ * extends `ReadonlyArray<T>`. One distributive check instead of four sequential ones.
+ */
+type IsCollection<T> = T extends readonly any[] | Map<any, any> | Set<any> ? true : false;
+/**
+ * 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
+ *   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
+ *   `keyof T & string` — there is no need for a separate union with `keyof T`.
+ * - Collections (arrays, Map, Set) are terminated at their key rather than
+ *   recursed into.
+ * - 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 : {
+    [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;
+/**
+ * All valid key paths into T (top-level and dot-nested).
+ *
+ * `DotNestedKeys<T>` already emits top-level string keys alongside nested paths,
+ * so a `keyof T` union is redundant and was previously responsible for duplicate
+ * entries that the checker had to deduplicate on every instantiation.
+ */
+export type AllObjectKeys<T> = DotNestedKeys<T>;
+/**
+ * Resolves the value type at a dot-separated path P within T.
+ *
+ * The intermediate `Rest extends AllObjectKeys<T[Head]>` guard that previously
+ * existed here forced a full re-evaluation of `AllObjectKeys` at every recursive
+ * level. It has been removed: if `Rest` is not a valid path the recursion
+ * naturally returns `never`, which is the correct result.
+ */
+export type PropType<T, P extends string> = P extends keyof T ? T[P] : P extends `${infer Head}.${infer Rest}` ? Head extends keyof T ? PropType<T[Head], Rest> : never : never;
+/**
+ * Callback invoked by Tubular whenever an observed path changes.
+ *
+ * The previous definition used defaulted type parameters
+ * (`K = AllObjectKeys<T>`, `V = PropType<T, K & string>`). Default type
+ * parameters are eagerly evaluated by the checker at *every* reference to
+ * `ObservationCallback<T>`, causing a full `AllObjectKeys<T>` + distributed
+ * `PropType` expansion each time. Using `unknown` for the value parameters
+ * defers any narrowing to call sites that actually need it, which is a far
+ * smaller surface area.
+ */
+export type ObservationCallback<T> = (newVal: unknown, oldVal: unknown, propPath: AllObjectKeys<T>) => void;
+export {};

package/dist/esm/types.mjs

@@ -0,0 +1,11 @@
+/**
+ * Callback invoked by Tubular whenever an observed path changes.
+ *
+ * The previous definition used defaulted type parameters
+ * (`K = AllObjectKeys<T>`, `V = PropType<T, K & string>`). Default type
+ * parameters are eagerly evaluated by the checker at *every* reference to
+ * `ObservationCallback<T>`, causing a full `AllObjectKeys<T>` + distributed
+ * `PropType` expansion each time. Using `unknown` for the value parameters
+ * defers any narrowing to call sites that actually need it, which is a far
+ * smaller surface area.
+ */ export { };

package/package.json

@@ -6,7 +6,7 @@
   "main": "./dist/totally-tubular.js",
   "types": "./dist/totally-tubular.d.ts",
   "typings": "./dist/totally-tubular.d.ts",
-  "version": "0.1.2",
+  "version": "0.3.1",
   "keywords": [
     "state",
     "management",
@@ -30,19 +30,60 @@
     "dist/"
   ],
   "scripts": {
-    "build": "bun run clean && tsc",
+    "build": "ts-duality --clean",
     "clean": "rm -rf dist/",
-    "test": "vitest run",
-    "test:watch": "vitest"
+    "test": "bun test",
+    "test:watch": "bun test --watch"
   },
   "devDependencies": {
-    "@commitlint/cli": "^19.8.1",
-    "@commitlint/config-conventional": "^19.8.1",
+    "@better-builds/lets-version": "^1.6.0",
+    "@better-builds/ts-duality": "^1.3.2",
+    "@biomejs/biome": "^2.4.6",
+    "@commitlint/cli": "^20.4.3",
+    "@commitlint/config-conventional": "^20.4.3",
+    "@happy-dom/global-registrator": "^20.8.3",
+    "@testing-library/react": "^16.3.2",
+    "@testing-library/user-event": "^14.6.1",
     "@types/bun": "latest",
-    "eslint-config-react-yas": "^5.2.2",
-    "typescript": "^5",
-    "vite": "^6.3.5",
-    "vitest": "^3.1.4"
+    "@types/react": ">=18",
+    "happy-dom": "^20.8.3",
+    "react": ">=18",
+    "typescript": "^5"
   },
-  "peerDependencies": {}
+  "optionalDependencies": {
+    "react": ">=18"
+  },
+  "exports": {
+    "./react": {
+      "require": {
+        "types": "./dist/cjs/react.d.ts",
+        "default": "./dist/cjs/react.cjs"
+      },
+      "import": {
+        "types": "./dist/esm/react.d.ts",
+        "default": "./dist/esm/react.mjs"
+      }
+    },
+    "./totally-tubular": {
+      "require": {
+        "types": "./dist/cjs/totally-tubular.d.ts",
+        "default": "./dist/cjs/totally-tubular.cjs"
+      },
+      "import": {
+        "types": "./dist/esm/totally-tubular.d.ts",
+        "default": "./dist/esm/totally-tubular.mjs"
+      }
+    },
+    "./types": {
+      "require": {
+        "types": "./dist/cjs/types.d.ts",
+        "default": "./dist/cjs/types.cjs"
+      },
+      "import": {
+        "types": "./dist/esm/types.d.ts",
+        "default": "./dist/esm/types.mjs"
+      }
+    },
+    "./package.json": "./package.json"
+  }
 }

package/dist/types.d.ts

@@ -1,10 +0,0 @@
-export type TSPrimitve = string | number | bigint | boolean | symbol | undefined | null;
-type DotPrefix<T extends string> = T extends '' ? '' : `.${T}`;
-type IsCollection<T> = T extends any[] ? true : T extends ReadonlyArray<any> ? true : T extends Map<any, any> ? true : T extends Set<any> ? true : false;
-type DotNestedKeys<T> = (T extends object ? IsCollection<T> extends true ? '' : {
-    [K in Exclude<keyof T, symbol>]: `${K}${DotPrefix<DotNestedKeys<T[K]>>}`;
-}[Exclude<keyof T, symbol>] : '') extends infer D ? Extract<D, string> : never;
-export type AllObjectKeys<T> = keyof T | DotNestedKeys<T>;
-export type PropType<T, P extends string> = P extends keyof T ? T[P] : P extends `${infer Head}.${infer Rest}` ? Head extends keyof T ? Rest extends AllObjectKeys<T[Head]> ? PropType<T[Head], Rest> : never : never : never;
-export type ObservationCallback<T, K = AllObjectKeys<T>, V = PropType<T, K & string>> = (newVal: V, oldVal: V, propPath: K) => void;
-export {};

package/dist/types.js

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