totally-tubular 0.4.0 → 0.5.0

package/README.md

@@ -140,6 +140,11 @@ setCount((prev) => (prev ?? 0) + 1);
 `useTubular` automatically unsubscribes when the component unmounts, so you
 don't need to manage cleanup yourself.
 
+`useTubular` is built on React's `useSyncExternalStore`, so it works with
+server-side rendering: on the server it renders the store's current value
+without subscribing, and on the client it subscribes during hydration. The
+React bindings require React 18 or later.
+
 ### Resetting from React
 
 Import `useTubularReset` from `totally-tubular/react`. It returns a stable
@@ -158,6 +163,44 @@ function ResetButton() {
 The callback identity never changes, so it's safe to pass directly as an event
 handler or as a dependency to `useEffect`.
 
+### Binding hooks to a store
+
+Import `createUseTubular` and `createUseTubularReset` from
+`totally-tubular/react` to create hooks hard-locked to a single `Tubular`
+instance, so you don't have to pass the store around at every call site.
+
+Call them once, outside your components — they aren't hooks themselves, so
+module scope is safe — and name what they return with a `use` prefix so
+React's rules-of-hooks linting treats it as a hook.
+
+```tsx
+import { createUseTubular, createUseTubularReset } from "totally-tubular/react";
+
+// Using the `store` created in the example above
+const useAppState = createUseTubular(store);
+const useAppReset = createUseTubularReset(store);
+
+function Counter() {
+  const [count, setCount] = useAppState("count");
+
+  return (
+    <button onClick={() => setCount((n) => (n ?? 0) + 1)}>
+      Clicked {count} times
+    </button>
+  );
+}
+
+function ResetButton() {
+  const handleReset = useAppReset();
+  return <button onClick={handleReset}>Reset</button>;
+}
+```
+
+The returned hooks behave exactly like `useTubular` and `useTubularReset`
+minus the store argument. Key paths stay fully type-checked against the bound
+store's state shape, and each hook is scoped to exactly one instance — bound
+hooks from different stores never cross-talk.
+
 ## Things you should know
 
 - **Arrays and nested objects are observed at their path, not their contents.**
@@ -168,53 +211,55 @@ handler or as a dependency to `useEffect`.
 
 ## 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/react.d.ts

@@ -12,6 +12,11 @@ import type { AllObjectKeys, PropType } from './types.js';
  * The setter accepts either a new value directly or an updater function that
  * receives the current value and returns the next one.
  *
+ * The value is read through React's `useSyncExternalStore`, so the hook is
+ * safe to use during server-side rendering: the server renders the store's
+ * current value without subscribing, and the client subscribes during
+ * hydration.
+ *
  * @example
  * ```tsx
  * const store = new Tubular({ user: { name: 'Alice' }, count: 0 });
@@ -28,6 +33,37 @@ 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];
+/**
+ * Creates a hook bound to a specific {@link Tubular} instance, so you never
+ * have to pass the instance around at every call site.
+ *
+ * Call this once, outside your components (the factory itself is not a hook,
+ * so module scope is safe), and it returns a hook that works exactly like
+ * {@link useTubular} minus the first argument — just the key path.
+ *
+ * The returned function is a hook: name it with a `use` prefix so React's
+ * rules-of-hooks linting recognizes it, and call it unconditionally at the top
+ * level of your components. Key paths remain fully type-checked against the
+ * bound store's state shape.
+ *
+ * @example
+ * ```tsx
+ * const store = new Tubular({ user: { name: 'Alice' }, count: 0 });
+ *
+ * const useAppState = createUseTubular(store);
+ *
+ * function Counter() {
+ *   const [count, setCount] = useAppState('count');
+ *   return <button onClick={() => setCount(n => (n ?? 0) + 1)}>{count}</button>;
+ * }
+ *
+ * function Greeting() {
+ *   const [name] = useAppState('user.name');
+ *   return <p>Hello, {name}!</p>;
+ * }
+ * ```
+ */
+export declare function createUseTubular<T extends object>(tubular: Tubular<T>): <K extends string>(key: K & AllObjectKeys<T>) => readonly [PropType<T, K & AllObjectKeys<T>> | null, (newValOrCallback: PropType<T, K & AllObjectKeys<T>> | ((prevVal: PropType<T, K & AllObjectKeys<T>> | null) => PropType<T, K & AllObjectKeys<T>>)) => void];
 /**
  * A React hook that returns a stable callback to reset a {@link Tubular} store
  * back to its initial state.
@@ -51,3 +87,30 @@ export declare function useTubular<T extends object, K extends string>(tubular:
  * ```
  */
 export declare function useTubularReset<T extends object>(tubular: Tubular<T>): () => void;
+/**
+ * Creates a hook bound to a specific {@link Tubular} instance that returns a
+ * stable callback resetting that store back to its initial state.
+ *
+ * Call this once, outside your components (the factory itself is not a hook,
+ * so module scope is safe), and it returns a hook that works exactly like
+ * {@link useTubularReset} minus the first argument. Every bound
+ * {@link useTubular} (or {@link createUseTubular}) hook watching the store
+ * re-renders with the restored value.
+ *
+ * The returned function is a hook: name it with a `use` prefix so React's
+ * rules-of-hooks linting recognizes it, and call it unconditionally at the top
+ * level of your components.
+ *
+ * @example
+ * ```tsx
+ * const store = new Tubular({ name: 'Alice', count: 0 });
+ *
+ * const useAppReset = createUseTubularReset(store);
+ *
+ * function ResetButton() {
+ *   const handleReset = useAppReset();
+ *   return <button onClick={handleReset}>Reset</button>;
+ * }
+ * ```
+ */
+export declare function createUseTubularReset<T extends object>(tubular: Tubular<T>): () => () => void;

package/dist/react.js

@@ -1,4 +1,4 @@
-import { useCallback, useEffect, useState } from 'react';
+import { useCallback, useSyncExternalStore } from 'react';
 /**
  * A React hook that binds to a {@link Tubular} instance and a specific key path
  * within its state.
@@ -11,6 +11,11 @@ import { useCallback, useEffect, useState } from 'react';
  * The setter accepts either a new value directly or an updater function that
  * receives the current value and returns the next one.
  *
+ * The value is read through React's `useSyncExternalStore`, so the hook is
+ * safe to use during server-side rendering: the server renders the store's
+ * current value without subscribing, and the client subscribes during
+ * hydration.
+ *
  * @example
  * ```tsx
  * const store = new Tubular({ user: { name: 'Alice' }, count: 0 });
@@ -27,9 +32,17 @@ import { useCallback, useEffect, useState } from 'react';
  * ```
  */
 export function useTubular(tubular, key) {
-    /** state */
-    const [val, setVal] = useState(() => tubular.read(key));
     /** callbacks */
+    const subscribe = useCallback((onStoreChange) => {
+        const observeCb = () => {
+            onStoreChange();
+        };
+        tubular.observe(key, observeCb);
+        return () => {
+            tubular.unobserve(key, observeCb);
+        };
+    }, [tubular, key]);
+    const getSnapshot = useCallback(() => tubular.read(key), [tubular, key]);
     const handleUpdateVal = useCallback((newValOrCallback) => {
         if (typeof newValOrCallback === 'function') {
             tubular.update(key, newValOrCallback);
@@ -38,20 +51,43 @@ export function useTubular(tubular, key) {
             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]);
+    /** state */
+    const val = useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
     return [val, handleUpdateVal];
 }
+/**
+ * Creates a hook bound to a specific {@link Tubular} instance, so you never
+ * have to pass the instance around at every call site.
+ *
+ * Call this once, outside your components (the factory itself is not a hook,
+ * so module scope is safe), and it returns a hook that works exactly like
+ * {@link useTubular} minus the first argument — just the key path.
+ *
+ * The returned function is a hook: name it with a `use` prefix so React's
+ * rules-of-hooks linting recognizes it, and call it unconditionally at the top
+ * level of your components. Key paths remain fully type-checked against the
+ * bound store's state shape.
+ *
+ * @example
+ * ```tsx
+ * const store = new Tubular({ user: { name: 'Alice' }, count: 0 });
+ *
+ * const useAppState = createUseTubular(store);
+ *
+ * function Counter() {
+ *   const [count, setCount] = useAppState('count');
+ *   return <button onClick={() => setCount(n => (n ?? 0) + 1)}>{count}</button>;
+ * }
+ *
+ * function Greeting() {
+ *   const [name] = useAppState('user.name');
+ *   return <p>Hello, {name}!</p>;
+ * }
+ * ```
+ */
+export function createUseTubular(tubular) {
+    return (key) => useTubular(tubular, key);
+}
 /**
  * A React hook that returns a stable callback to reset a {@link Tubular} store
  * back to its initial state.
@@ -77,3 +113,32 @@ export function useTubular(tubular, key) {
 export function useTubularReset(tubular) {
     return useCallback(() => tubular.reset(), [tubular]);
 }
+/**
+ * Creates a hook bound to a specific {@link Tubular} instance that returns a
+ * stable callback resetting that store back to its initial state.
+ *
+ * Call this once, outside your components (the factory itself is not a hook,
+ * so module scope is safe), and it returns a hook that works exactly like
+ * {@link useTubularReset} minus the first argument. Every bound
+ * {@link useTubular} (or {@link createUseTubular}) hook watching the store
+ * re-renders with the restored value.
+ *
+ * The returned function is a hook: name it with a `use` prefix so React's
+ * rules-of-hooks linting recognizes it, and call it unconditionally at the top
+ * level of your components.
+ *
+ * @example
+ * ```tsx
+ * const store = new Tubular({ name: 'Alice', count: 0 });
+ *
+ * const useAppReset = createUseTubularReset(store);
+ *
+ * function ResetButton() {
+ *   const handleReset = useAppReset();
+ *   return <button onClick={handleReset}>Reset</button>;
+ * }
+ * ```
+ */
+export function createUseTubularReset(tubular) {
+    return () => useTubularReset(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.4.0",
+  "version": "0.5.0",
   "keywords": [
     "state",
     "management",
@@ -26,27 +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.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.17",
+    "@types/node": "^26.1.1",
     "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^6.0.3",
     "happy-dom": "^20.10.2",
-    "react-dom": "^19.2.7",
     "react": "^19.2.7",
-    "typescript": "^5.9.3"
+    "react-dom": "^19.2.7",
+    "tsx": "^4.23.0",
+    "typescript": "^5.9.3",
+    "vite": "^8.1.4",
+    "vitest": "^4.1.10"
   },
   "peerDependencies": {
     "react": ">=18"
@@ -74,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"
   }
-}
+}