totally-tubular 0.4.1 → 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.**

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/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.1",
+  "version": "0.5.0",
   "keywords": [
     "state",
     "management",