@manyducksco/stator 1.0.0-rc.1

package/.github/workflows/ci.yml

@@ -0,0 +1,32 @@
+name: CI
+
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+    branches: ["main"]
+
+jobs:
+  test-and-build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+          cache: "npm"
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Typecheck
+        run: npx tsc --noEmit
+
+      - name: Run tests
+        run: npm run test
+
+      - name: Build library
+        run: npm run build

package/.github/workflows/release.yml

@@ -0,0 +1,29 @@
+name: Publish to npm
+
+on:
+  release:
+    types: [created]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+          registry-url: "https://registry.npmjs.org"
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build library
+        run: npm run build
+
+      - name: Publish package
+        run: npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/LICENSE

@@ -0,0 +1,7 @@
+Copyright (c) 2026 That's a lot of ducks, LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,142 @@
+# @manyducksco/stator
+
+Stator answers the question, "How do I share one hook's state between multiple components?" Stator makes this simple.
+
+## Installation
+
+```bash
+npm install @manyducksco/stator
+```
+
+## Example: Counter Store
+
+```tsx
+import { createStore } from "@manyducksco/stator";
+import { useState, useCallback } from "react";
+
+type CounterOptions = {
+  initialValue?: number;
+};
+
+// Write your hook code, pass it to `createStore`, get a Provider and a hook.
+
+const [CounterProvider, useCounter] = createStore((options: CounterOptions) => {
+  const [value, setValue] = useState(options.initialValue ?? 0);
+
+  const increment = useCallback((amount = 1) => {
+    setValue((current) => current + amount);
+  }, []);
+
+  const decrement = useCallback((amount = 1) => {
+    setValue((current) => current - amount);
+  }, []);
+
+  const reset = useCallback(() => {
+    setValue(0);
+  }, []);
+
+  return {
+    value,
+    increment,
+    decrement,
+    reset,
+  };
+});
+
+function MyApp() {
+  return (
+    // One instance of your store is created wherever you render the provider.
+    // You can render multiple `<CounterProvider>`s in different parts of your app,
+    // and each one maintains its own isolated state.
+    <CounterProvider options={{ initialValue: 51 }}>
+      <CounterDisplay />
+      <CounterControls />
+    </CounterProvider>
+  );
+}
+
+function CounterDisplay() {
+  // All children can access the same instance via the hook.
+  // TypeScript will automatically infer the correct return types here.
+  const { value } = useCounter();
+
+  return <p>Count is: {value}</p>;
+}
+
+function CounterControls() {
+  const { increment, decrement, reset } = useCounter();
+
+  return (
+    <div>
+      <button onClick={increment}>+1</button>
+      <button onClick={decrement}>-1</button>
+      <button onClick={reset}>Reset</button>
+    </div>
+  );
+}
+```
+
+## Optimizing with a selector
+
+It's typical to only need part of a store's state. A component that calls `useCounter` will render every time the store state changes, even if it's not using the part of the state that changed. You can pass a selector function to pluck out the parts you care about so your component will only render when you need it to.
+
+Let's optimize the Counter components.
+
+```tsx
+function CounterDisplay() {
+  const value = useCounter((state) => state.value);
+  // We only care about the value.
+  // If we add more state to the counter store later, this component won't even notice.
+
+  return <p>Count is: {value}</p>;
+}
+
+function CounterControls() {
+  const [increment, decrement, reset] = useCounter((state) => [
+    state.increment,
+    state.decrement,
+    state.reset,
+  ]);
+  // We don't care about the value, only the functions to modify it.
+  // Because we've wrapped them in `useCallback` they will always reference the same functions.
+  // Changes to the counter value will never cause this component to render.
+
+  return (
+    <div>
+      <button onClick={increment}>+1</button>
+      <button onClick={decrement}>-1</button>
+      <button onClick={reset}>Reset</button>
+    </div>
+  );
+}
+```
+
+> [!NOTE]
+> The hook performs a shallow check on the selected value that treats arrays or objects with equivalent keys and values as equal.
+> A selector may return an array or object with multiple values (like in our CounterControls example above).
+> In this case the return value is just a container. It's the items _inside_ the array that are compared for equality.
+
+### Memoize everything
+
+> [!IMPORTANT]
+> Because Stator relies on referential equality when comparing selected state, you must memoize any selected functions and derived objects returned by your base hook.
+
+If you return a new function or object reference on every render, components selecting those values will also re-render every time, defeating the selector optimization.
+
+```ts
+// ❌ Bad: This creates a new function reference every render!
+const increment = (amount = 1) => setValue((current) => current + amount);
+
+// ✅ Good: The reference remains stable.
+const increment = useCallback((amount = 1) => {
+  setValue((current) => current + amount);
+}, []);
+```
+
+## Prior art
+
+We have been long time users of the great [unstated-next](https://github.com/jamiebuilds/unstated-next). Stator was created to add memoization and an improved API on top of that same idea.
+
+## License
+
+Stator is provided under the MIT license.

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@manyducksco/stator",
+  "description": "Memoized context stores for React",
+  "version": "1.0.0-rc.1",
+  "sideEffects": false,
+  "author": "Tony McCoy <tony@manyducks.co>",
+  "type": "module",
+  "exports": {
+    ".": "./dist/stator.js"
+  },
+  "main": "./dist/stator.js",
+  "types": "./dist/stator.d.ts",
+  "scripts": {
+    "build": "vite build && tsc",
+    "test": "vitest",
+    "lint": "eslint . --max-warnings 0",
+    "check-types": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@testing-library/react": "^16.3.2",
+    "@types/node": "^22.19.11",
+    "@types/react": "19.2.2",
+    "@types/react-dom": "19.2.2",
+    "eslint": "^9.39.1",
+    "jsdom": "^28.1.0",
+    "typescript": "5.9.2",
+    "vite": "^7.3.1",
+    "vitest": "^4.0.18"
+  },
+  "peerDependencies": {
+    "react": ">=18",
+    "react-dom": ">=18"
+  }
+}

package/src/stator.test.tsx

@@ -0,0 +1,153 @@
+import { cleanup, fireEvent, render, renderHook } from "@testing-library/react";
+import { useCallback, useState } from "react";
+import { afterEach, expect, test, vi } from "vitest";
+import { createStore } from "./stator.js";
+
+type TestStoreOptions = { initialCount?: number; initialText?: string };
+
+afterEach(() => {
+  cleanup();
+});
+
+const [TestProvider, useTestStore] = createStore(
+  (options?: TestStoreOptions) => {
+    const [count, setCount] = useState(options?.initialCount ?? 0);
+    const [text, setText] = useState(options?.initialText ?? "hello");
+
+    const increment = useCallback(() => setCount((c) => c + 1), []);
+    const updateText = useCallback((t: string) => setText(t), []);
+
+    return { count, text, increment, updateText };
+  },
+);
+
+test("throws when hook is used outside of provider", () => {
+  // Suppress React's internal error logging for this specific test
+  const consoleError = vi.spyOn(console, "error").mockImplementation(() => {});
+
+  expect(() => renderHook(() => useTestStore())).toThrow(
+    "Component must be wrapped with a store <Provider>",
+  );
+
+  consoleError.mockRestore();
+});
+
+test("store receives options object from provider props", () => {
+  const { result } = renderHook(() => useTestStore(), {
+    wrapper: ({ children }) => (
+      <TestProvider options={{ initialCount: 10, initialText: "initialized" }}>
+        {children}
+      </TestProvider>
+    ),
+  });
+
+  expect(result.current.count).toBe(10);
+  expect(result.current.text).toBe("initialized");
+  expect(typeof result.current.increment).toBe("function");
+});
+
+test("hook returns only the selected state", () => {
+  const { result } = renderHook(() => useTestStore((state) => state.count), {
+    wrapper: ({ children }) => <TestProvider>{children}</TestProvider>,
+  });
+
+  expect(result.current).toBe(0);
+});
+
+test("renders only when selected state changes", () => {
+  const displaySpy = vi.fn();
+  const controlSpy = vi.fn();
+
+  const DisplayComponent = () => {
+    displaySpy();
+    const count = useTestStore((state) => state.count);
+    return <div data-testid="display">{count}</div>;
+  };
+
+  const ControlComponent = () => {
+    controlSpy();
+    const increment = useTestStore((state) => state.increment);
+    return (
+      <button data-testid="increment" onClick={increment}>
+        Increment
+      </button>
+    );
+  };
+
+  const { getByTestId } = render(
+    <TestProvider>
+      <DisplayComponent />
+      <ControlComponent />
+    </TestProvider>,
+  );
+
+  expect(displaySpy).toHaveBeenCalledTimes(1);
+  expect(controlSpy).toHaveBeenCalledTimes(1);
+
+  fireEvent.click(getByTestId("increment"));
+
+  expect(displaySpy).toHaveBeenCalledTimes(2);
+  expect(controlSpy).toHaveBeenCalledTimes(1);
+  expect(getByTestId("display").textContent).toBe("1");
+});
+
+test("handles new array/object references deeply", () => {
+  const selectSpy = vi.fn();
+  const renderSpy = vi.fn();
+
+  const CountComponent = () => {
+    renderSpy();
+    const [count, increment] = useTestStore((state) => {
+      selectSpy();
+      return [state.count, state.increment];
+    });
+    return (
+      <div>
+        <div>{count}</div>
+        <button data-testid="increment" onClick={() => increment()}>
+          Increment
+        </button>
+      </div>
+    );
+  };
+
+  const TextComponent = () => {
+    const [text, setText] = useTestStore((state) => [
+      state.text,
+      state.updateText,
+    ]);
+    return (
+      <button
+        data-testid="update-text"
+        onClick={() => {
+          setText("text has been updated!");
+        }}
+      >
+        {text}
+      </button>
+    );
+  };
+
+  const { getByTestId } = render(
+    <TestProvider>
+      <CountComponent />
+      <TextComponent />
+    </TestProvider>,
+  );
+
+  expect(selectSpy).toHaveBeenCalledTimes(1);
+  expect(renderSpy).toHaveBeenCalledTimes(1);
+  expect(getByTestId("update-text").textContent).toBe("hello");
+
+  // The hook should see the contents are deeply equal and abort the render.
+  fireEvent.click(getByTestId("update-text"));
+
+  expect(selectSpy).toHaveBeenCalledTimes(2); // selected again
+  expect(renderSpy).toHaveBeenCalledTimes(1); // still rendered once
+  expect(getByTestId("update-text").textContent).toBe("text has been updated!");
+
+  fireEvent.click(getByTestId("increment"));
+
+  expect(selectSpy).toHaveBeenCalledTimes(3);
+  expect(renderSpy).toHaveBeenCalledTimes(2);
+});

package/src/stator.ts

@@ -0,0 +1,199 @@
+import {
+  createContext,
+  createElement,
+  useContext,
+  useLayoutEffect,
+  useRef,
+  useSyncExternalStore,
+} from "react";
+
+const EMPTY: unique symbol = Symbol();
+
+export interface StoreProviderProps<Options> {
+  options?: Options;
+  children: React.ReactNode;
+}
+
+export interface StoreProviderPropsWithOptions<
+  Options,
+> extends StoreProviderProps<Options> {
+  options: Options;
+}
+
+/**
+ * Provides a single instance of a store to all its children.
+ */
+export type StoreProvider<Options> = React.ComponentType<
+  StoreProviderProps<Options>
+>;
+
+/**
+ * Provides a single instance of a store to all its children.
+ * Store options are passed as props.
+ */
+export type StoreProviderWithOptions<Options> = React.ComponentType<
+  StoreProviderPropsWithOptions<Options>
+>;
+
+/**
+ * Plucks only the parts of the state this component cares about.
+ */
+export type Selector<Value, Selected> = (value: Value) => Selected;
+
+/**
+ * Accesses the nearest parent instance of a store.
+ */
+export interface StoreHook<Value> {
+  (): Value;
+  <Selected>(select: Selector<Value, Selected>): Selected;
+}
+
+class Store<T> {
+  public value: T;
+  private listeners = new Set<() => void>();
+
+  constructor(value: T) {
+    this.value = value;
+  }
+
+  update(value: T) {
+    this.value = value;
+  }
+
+  notify() {
+    this.listeners.forEach((listener) => listener());
+  }
+
+  subscribe = (listener: () => void) => {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  };
+
+  get = () => this.value;
+}
+
+/**
+ * Defines a new store, returning its provider and hook.
+ */
+export function createStore<Value, Options>(
+  fn: () => Value,
+): [StoreProvider<Options>, StoreHook<Value>];
+
+/**
+ * Defines a new store, returning its provider and hook.
+ */
+export function createStore<Value, Options>(
+  fn: (options: Options) => Value,
+): [StoreProviderWithOptions<Options>, StoreHook<Value>];
+
+export function createStore<Value, Options>(
+  fn: (options?: Options) => Value,
+):
+  | [StoreProvider<Options>, StoreHook<Value>]
+  | [StoreProviderWithOptions<Options>, StoreHook<Value>] {
+  const Context = createContext<Store<Value> | typeof EMPTY>(EMPTY);
+
+  function Provider(props: StoreProviderProps<Options>) {
+    const value = fn(props.options);
+    const storeRef = useRef<Store<Value>>(null);
+
+    if (!storeRef.current) {
+      storeRef.current = new Store(value);
+    } else {
+      storeRef.current.update(value);
+    }
+
+    useLayoutEffect(() => {
+      storeRef.current!.notify();
+    }, [value]);
+
+    return createElement(Context.Provider, {
+      value: storeRef.current,
+      children: props.children,
+    });
+  }
+
+  function useStore<Selected = Value>(select?: Selector<Value, Selected>) {
+    const store = useContext(Context);
+
+    if (store === EMPTY) {
+      throw new Error("Component must be wrapped with a store <Provider>");
+    }
+
+    const snapshotRef = useRef<{ root: Value; selected: Selected } | null>(
+      null,
+    );
+
+    const getSnapshot = () => {
+      const root = store.get();
+      if (!select) return root as unknown as Selected;
+
+      const prev = snapshotRef.current;
+
+      if (prev && Object.is(prev.root, root)) {
+        return prev.selected;
+      }
+
+      const selected = select(root);
+
+      // If the selected values are equal, return the old reference to bail out of the render.
+      if (prev && _equals(selected, prev.selected)) {
+        snapshotRef.current = { root, selected: prev.selected };
+        return prev.selected;
+      }
+
+      // Otherwise, cache and return the new reference.
+      snapshotRef.current = { root, selected };
+      return selected;
+    };
+
+    return useSyncExternalStore(store.subscribe, getSnapshot, getSnapshot);
+  }
+
+  return [Provider, useStore];
+}
+
+/**
+ * Shallow `Object.is` comparison for selected objects and arrays.
+ */
+function _equals(a: any, b: any): boolean {
+  // Exact match (handles identical object references and primitive matches like 1 === 1)
+  if (Object.is(a, b)) return true;
+
+  // If either is not an object (primitive, function) or is null,
+  // and they failed the Object.is check above, they are definitely not equal.
+  if (
+    typeof a !== "object" ||
+    a === null ||
+    typeof b !== "object" ||
+    b === null
+  ) {
+    return false;
+  }
+
+  // Shallow array compare
+  if (Array.isArray(a)) {
+    if (!Array.isArray(b) || a.length !== b.length) return false;
+    for (let i = 0; i < a.length; i++) {
+      if (!Object.is(a[i], b[i])) return false;
+    }
+    return true;
+  }
+
+  // Bail out on different types (e.g., Object vs Date)
+  if (a.constructor !== b.constructor) return false;
+
+  // Shallow object compare
+  const keys = Object.keys(a);
+  if (keys.length !== Object.keys(b).length) return false;
+
+  const hasOwn = Object.prototype.hasOwnProperty;
+  for (let i = 0; i < keys.length; i++) {
+    const key = keys[i];
+    if (!hasOwn.call(b, key) || !Object.is(a[key], b[key])) {
+      return false;
+    }
+  }
+
+  return true;
+}

package/tsconfig.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "compilerOptions": {
+    "declaration": true,
+    "declarationMap": true,
+    "emitDeclarationOnly": true,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "incremental": false,
+    "isolatedModules": true,
+    "lib": ["es2022", "DOM", "DOM.Iterable", "WebWorker"],
+    "module": "preserve",
+    "moduleDetection": "force",
+    "moduleResolution": "bundler",
+    "noUncheckedIndexedAccess": false,
+    "resolveJsonModule": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "target": "ES2022",
+    "outDir": "dist",
+    "jsx": "react-jsx"
+  },
+  "include": ["src"],
+  "exclude": ["node_modules", "dist", "src/*.test.*"]
+}

package/vite.config.ts

@@ -0,0 +1,27 @@
+import { defineConfig } from "vitest/config";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+export default defineConfig({
+  build: {
+    lib: {
+      entry: resolve(__dirname, "src/stator.ts"),
+      name: "Stator",
+      fileName: "stator",
+      formats: ["es"],
+    },
+    rollupOptions: {
+      external: ["react"],
+      output: {
+        globals: {
+          react: "React",
+        },
+      },
+    },
+  },
+  test: {
+    environment: "jsdom",
+  },
+});