@octanejs/zustand 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dominic Gannaway
+
+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,86 @@
+# @octanejs/zustand
+
+[zustand](https://github.com/pmndrs/zustand) for the [octane](https://github.com/octanejs/octane) renderer.
+
+zustand separates a framework-agnostic **vanilla store** (`createStore`) from a tiny
+**React binding** (`create` + `useStore`) built on `useSyncExternalStore`. This package
+reuses the vanilla store unchanged (re-exported verbatim from `zustand/vanilla`) and
+reimplements only the binding on top of octane's `useSyncExternalStore`. The public
+surface matches zustand 1:1 — most zustand code works by changing the import.
+
+```tsx
+// before
+import { create } from 'zustand';
+// after
+import { create } from '@octanejs/zustand';
+
+const useBearStore = create((set) => ({
+  bears: 0,
+  increase: () => set((s) => ({ bears: s.bears + 1 })),
+}));
+
+function BearCounter() @{
+  const bears = useBearStore((s) => s.bears);
+  <h1>{bears as string} bears</h1>
+}
+```
+
+## Entry points
+
+| import | what you get | notes |
+| --- | --- | --- |
+| `@octanejs/zustand` | `create`, `useStore`, `createStore` | the React binding, octane-bound |
+| `@octanejs/zustand/vanilla` | `createStore` + types | re-exported verbatim from zustand |
+| `@octanejs/zustand/shallow` | `shallow`, `useShallow` | `shallow` verbatim; `useShallow` octane-bound |
+| `@octanejs/zustand/middleware` | `persist`, `devtools`, `subscribeWithSelector`, `combine`, `redux`, `createJSONStorage`, … | re-exported verbatim (all framework-agnostic) |
+| `@octanejs/zustand/traditional` | `createWithEqualityFn`, `useStoreWithEqualityFn` | octane-bound (selector + equality fn) |
+
+## How it works
+
+octane keys hooks by a compiler-injected per-call-site `Symbol`, appended as the last
+argument of every `use*` call. A custom hook is just a wrapper that **forwards** that
+slot to the base hook it composes — which is all `useStore` does. Because the slot is
+per-call-site, `useBearStore(a)` and `useBearStore(b)` in one component (or the same
+hook used twice) stay independent, exactly like in React.
+
+> **Naming matters.** The hook you call must follow the `use*` convention (`const
+> useBearStore = create(...)`) so the compiler recognises it and injects the slot —
+> this is the same `use*`-is-reserved-for-hooks rule React uses.
+
+## Selecting object slices — `useShallow`
+
+A selector that returns a fresh object/array each call (`(s) => ({ a: s.a })`) never
+compares Object.is-equal, so it re-renders on every store change. Wrap it with
+`useShallow` to compare by shallow equality:
+
+```tsx
+import { useShallow } from '@octanejs/zustand/shallow';
+
+function Sliced() @{
+  const { a, b } = useBearStore(useShallow((s) => ({ a: s.a, b: s.b })));
+  // re-renders only when a or b actually changes
+}
+```
+
+## Divergences from React
+
+- **Unstable selectors don't loop.** React's `useSyncExternalStore` throws the dev
+  warning _"The result of getSnapshot should be cached"_ and re-renders in a loop when
+  a selector returns a new reference every render. octane settles after a bounded
+  number of renders instead — no loop, no warning. Prefer `useShallow` regardless, for
+  the same reason you would in React (avoid the extra renders).
+
+## Equality functions — `traditional`
+
+For the equality-fn pattern, `@octanejs/zustand/traditional` provides
+`createWithEqualityFn` / `useStoreWithEqualityFn`:
+
+```tsx
+import { createWithEqualityFn } from '@octanejs/zustand/traditional';
+import { shallow } from '@octanejs/zustand/shallow';
+
+const useStore = createWithEqualityFn((set) => ({ a: 0, b: 0 }), shallow);
+const { a } = useStore((s) => ({ a: s.a })); // bails out via shallow
+```
+
+For most object-slice selections, prefer `useShallow` — the v5-recommended approach.

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@octanejs/zustand",
+  "version": "0.1.0",
+  "license": "MIT",
+  "type": "module",
+  "description": "zustand bindings for the octane renderer — reuses zustand's framework-agnostic vanilla store and swaps the React binding for octane's useSyncExternalStore.",
+  "author": {
+    "name": "Dominic Gannaway",
+    "email": "dg@domgan.com"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/octanejs/octane.git",
+    "directory": "packages/zustand"
+  },
+  "main": "src/index.ts",
+  "module": "src/index.ts",
+  "types": "src/index.ts",
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "exports": {
+    ".": "./src/index.ts",
+    "./vanilla": "./src/vanilla.ts",
+    "./shallow": "./src/shallow.ts",
+    "./middleware": "./src/middleware.ts",
+    "./traditional": "./src/traditional.ts"
+  },
+  "dependencies": {
+    "zustand": "^5.0.0",
+    "octane": "0.1.1"
+  },
+  "devDependencies": {
+    "@tsrx/react": "^0.2.32",
+    "esbuild": "^0.28.1",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "vitest": "^4.1.9"
+  },
+  "scripts": {
+    "test": "vitest run"
+  }
+}

package/src/index.ts

@@ -0,0 +1,89 @@
+// @octanejs/zustand — zustand for the octane renderer.
+//
+// zustand cleanly separates a framework-agnostic vanilla store (`createStore`)
+// from a tiny React binding (`create` + `useStore`) layered on
+// `useSyncExternalStore`. This package reuses the vanilla store UNCHANGED (it's
+// pure JS — re-exported verbatim from `zustand/vanilla`) and reimplements only
+// the binding on top of octane's `useSyncExternalStore`. The public surface
+// (`create`, `useStore`, `createStore`) matches zustand 1:1, so existing zustand
+// code works by changing the import from `zustand` to `@octanejs/zustand`.
+//
+// The one octane-specific detail is hook slots: octane keys hooks by a
+// compiler-injected per-call-site Symbol, appended as the LAST argument of every
+// `use*` call. A custom hook is just a wrapper that FORWARDS that slot to the
+// base hook it composes — which is exactly what `useStore` does below. Because
+// the slot is per-call-site, `useFoo(a)` and `useFoo(b)` in one component (or
+// the same `useFoo` used twice) stay independent, just like in React.
+import { useSyncExternalStore } from 'octane';
+import { createStore } from 'zustand/vanilla';
+import type { Mutate, StateCreator, StoreApi, StoreMutatorIdentifier } from 'zustand/vanilla';
+
+// Re-export the vanilla core so `@octanejs/zustand` is a drop-in for both the
+// store-only (`createStore`) and binding (`create`) entry points of zustand.
+export { createStore } from 'zustand/vanilla';
+export type * from 'zustand/vanilla';
+
+type ExtractState<S> = S extends { getState: () => infer T } ? T : never;
+type ReadonlyStoreApi<T> = Pick<StoreApi<T>, 'getState' | 'getInitialState' | 'subscribe'>;
+
+const identity = <T>(arg: T): T => arg;
+
+export function useStore<S extends ReadonlyStoreApi<unknown>>(api: S): ExtractState<S>;
+export function useStore<S extends ReadonlyStoreApi<unknown>, U>(
+	api: S,
+	selector: (state: ExtractState<S>) => U,
+): U;
+export function useStore<TState, StateSlice>(
+	api: ReadonlyStoreApi<TState>,
+	// The compiler appends the call-site slot Symbol after the user args, so the
+	// runtime tuple is `[selector?, slot?]`. Both are optional to the author; the
+	// slot is supplied by the octane transform.
+	...rest: [selector?: (state: TState) => StateSlice, slot?: symbol]
+): StateSlice {
+	// Resolve the slot the way every base hook does: it's the LAST argument and a
+	// Symbol. Counting from the end means `useFoo()` (where the slot lands in the
+	// selector position) and `useFoo(sel)` both work.
+	const tail = rest[rest.length - 1];
+	const slot = typeof tail === 'symbol' ? (tail as symbol) : undefined;
+	const selector = (typeof rest[0] === 'function' ? rest[0] : identity) as (
+		state: TState,
+	) => StateSlice;
+	return useSyncExternalStore(
+		api.subscribe,
+		() => selector(api.getState()),
+		() => selector(api.getInitialState()),
+		slot,
+	);
+}
+
+type UseBoundStore<S extends ReadonlyStoreApi<unknown>> = {
+	(): ExtractState<S>;
+	<U>(selector: (state: ExtractState<S>) => U): U;
+} & S;
+
+type Create = {
+	<T, Mos extends [StoreMutatorIdentifier, unknown][] = []>(
+		initializer: StateCreator<T, [], Mos>,
+	): UseBoundStore<Mutate<StoreApi<T>, Mos>>;
+	<T>(): <Mos extends [StoreMutatorIdentifier, unknown][] = []>(
+		initializer: StateCreator<T, [], Mos>,
+	) => UseBoundStore<Mutate<StoreApi<T>, Mos>>;
+};
+
+const createImpl = (<T>(createState: StateCreator<T, [], []>) => {
+	const api = createStore(createState);
+	// The bound hook forwards ALL args (selector + the appended slot) straight
+	// through to `useStore`. It is NOT compiled by octane (it lives in this
+	// dependency), so no slot is injected here — the slot is the one the consumer's
+	// `useFoo(...)` call site carries, which is exactly what makes each call-site
+	// independent.
+	const useBoundStore = (...args: unknown[]) =>
+		(useStore as (...a: unknown[]) => unknown)(api, ...args);
+	Object.assign(useBoundStore, api);
+	return useBoundStore;
+}) as Create;
+
+export const create = (<T>(createState?: StateCreator<T, [], []>) =>
+	createState ? createImpl(createState) : createImpl) as Create;
+
+export default create;

package/src/middleware.ts

@@ -0,0 +1,8 @@
+// `@octanejs/zustand/middleware` — re-exported verbatim from zustand.
+//
+// Every zustand middleware (persist, devtools, subscribeWithSelector, combine,
+// redux, createJSONStorage, …) is a framework-agnostic store enhancer of the form
+// `(set, get, api) => state` — it operates purely on the vanilla store and imports
+// NO React. So it composes with octane's `create`/`useStore` unchanged, and we
+// re-export it as-is (mirroring src/vanilla.ts).
+export * from 'zustand/middleware';

package/src/shallow.ts

@@ -0,0 +1,29 @@
+// `@octanejs/zustand/shallow` — the zustand selector-equality helpers.
+//
+// `shallow` is a pure comparator (no hooks) and is re-exported verbatim from
+// zustand. `useShallow` IS a hook (zustand builds it on React.useRef), so it gets
+// an octane reimplementation: same memoize-the-selection-by-shallow-equality
+// logic, but built on octane's `useRef` with the compiler-injected slot forwarded
+// through (exactly like `useStore`). Use it to select an object/array slice
+// without the unstable-selector re-render churn:
+//
+//   const { a, b } = useBearStore(useShallow((s) => ({ a: s.a, b: s.b })));
+import { useRef } from 'octane';
+import { shallow } from 'zustand/vanilla/shallow';
+
+export { shallow } from 'zustand/vanilla/shallow';
+
+export function useShallow<S, U>(selector: (state: S) => U): (state: S) => U;
+export function useShallow<S, U>(
+	selector: (state: S) => U,
+	// Compiler-injected trailing slot (forwarded to the inner useRef).
+	...rest: [slot?: symbol]
+): (state: S) => U {
+	const tail = rest[rest.length - 1];
+	const slot = typeof tail === 'symbol' ? (tail as symbol) : undefined;
+	const prev = useRef<U | undefined>(undefined, slot);
+	return (state: S) => {
+		const next = selector(state);
+		return shallow(prev.current, next) ? (prev.current as U) : (prev.current = next);
+	};
+}

package/src/traditional.ts

@@ -0,0 +1,144 @@
+// `@octanejs/zustand/traditional` — zustand's equality-function binding.
+//
+// `createWithEqualityFn` / `useStoreWithEqualityFn` let a selector pair with a
+// custom equality function (e.g. `shallow`). zustand builds these on React's
+// `use-sync-external-store/shim/with-selector` — a polyfill whose extra machinery
+// (a closure-memoizer in useMemo + a useEffect commit) exists for React's
+// CONCURRENT rendering, where a render can be produced and then thrown away.
+//
+// octane renders synchronously (a render always commits), so none of that is
+// needed: we build directly on octane's REAL `useSyncExternalStore`. A ref caches
+// the last-returned selection and `getSnapshot` returns that SAME reference while
+// the equality fn says the selection is unchanged — so useSyncExternalStore's own
+// Object.is check bails out the re-render. One extra base hook (the ref), with its
+// slot derived from the wrapper's forwarded slot.
+//
+// Note: v5 recommends `useShallow` over this equality-fn pattern for object
+// slices; `traditional` exists for code that still uses it.
+import { useSyncExternalStore, useRef } from 'octane';
+import { createStore } from 'zustand/vanilla';
+import type { StateCreator, StoreApi } from 'zustand/vanilla';
+
+type ExtractState<S> = S extends { getState: () => infer T } ? T : never;
+type ReadonlyStoreApi<T> = Pick<StoreApi<T>, 'getState' | 'getInitialState' | 'subscribe'>;
+
+const identity = <T>(arg: T): T => arg;
+
+// Derive a stable, distinct sub-slot from the wrapper's slot. `Symbol.for` interns
+// by description, so the same call site always yields the same sub-slot; the
+// `:wsel:` namespace keeps it clear of useSyncExternalStore's `:uses:` slots.
+function subSlot(slot: symbol | undefined, tag: string): symbol | undefined {
+	return slot !== undefined ? Symbol.for((slot.description ?? '') + ':wsel:' + tag) : undefined;
+}
+
+interface SelectionCell<U> {
+	hasValue: boolean;
+	value: U | undefined;
+}
+
+export function useStoreWithEqualityFn<S extends ReadonlyStoreApi<unknown>>(
+	api: S,
+): ExtractState<S>;
+export function useStoreWithEqualityFn<S extends ReadonlyStoreApi<unknown>, U>(
+	api: S,
+	selector: (state: ExtractState<S>) => U,
+	equalityFn?: (a: U, b: U) => boolean,
+): U;
+export function useStoreWithEqualityFn<TState, StateSlice>(
+	api: ReadonlyStoreApi<TState>,
+	// Runtime args are `[selector?, equalityFn?, slot?]`; the slot is appended by
+	// the octane compiler and is always LAST.
+	...rest: [
+		selector?: (state: TState) => StateSlice,
+		equalityFn?: (a: StateSlice, b: StateSlice) => boolean,
+		slot?: symbol,
+	]
+): StateSlice {
+	const tail = rest[rest.length - 1];
+	const slot = typeof tail === 'symbol' ? (tail as symbol) : undefined;
+	const userArgs = slot !== undefined ? rest.slice(0, -1) : rest;
+	const selector = (typeof userArgs[0] === 'function' ? userArgs[0] : identity) as (
+		state: TState,
+	) => StateSlice;
+	const equalityFn =
+		typeof userArgs[1] === 'function'
+			? (userArgs[1] as (a: StateSlice, b: StateSlice) => boolean)
+			: undefined;
+
+	const cache = useRef<SelectionCell<StateSlice>>(
+		{ hasValue: false, value: undefined },
+		subSlot(slot, 'sel'),
+	);
+	// Returns the cached reference while the selection is "equal" → octane's
+	// useSyncExternalStore sees an Object.is-equal snapshot and bails out.
+	const select = (state: TState): StateSlice => {
+		const next = selector(state);
+		const c = cache.current;
+		if (c.hasValue) {
+			const prev = c.value as StateSlice;
+			if (equalityFn ? equalityFn(prev, next) : Object.is(prev, next)) return prev;
+		}
+		c.hasValue = true;
+		c.value = next;
+		return next;
+	};
+
+	return useSyncExternalStore(
+		api.subscribe,
+		() => select(api.getState()),
+		() => select(api.getInitialState()),
+		slot,
+	);
+}
+
+type UseBoundStoreWithEqualityFn<S extends ReadonlyStoreApi<unknown>> = {
+	(): ExtractState<S>;
+	<U>(selector: (state: ExtractState<S>) => U, equalityFn?: (a: U, b: U) => boolean): U;
+} & S;
+
+type CreateWithEqualityFn = {
+	<T, U = T>(
+		initializer: StateCreator<T, [], []>,
+		defaultEqualityFn?: (a: U, b: U) => boolean,
+	): UseBoundStoreWithEqualityFn<StoreApi<T>>;
+	<T, U = T>(): (
+		initializer: StateCreator<T, [], []>,
+		defaultEqualityFn?: (a: U, b: U) => boolean,
+	) => UseBoundStoreWithEqualityFn<StoreApi<T>>;
+};
+
+const createWithEqualityFnImpl = (<T>(
+	createState: StateCreator<T, [], []>,
+	defaultEqualityFn?: (a: unknown, b: unknown) => boolean,
+) => {
+	const api = createStore(createState);
+	// The bound hook receives `[selector?, equalityFn?, slot?]`. We resolve the
+	// default equality fn, then hand off to useStoreWithEqualityFn with the slot
+	// kept last (it re-parses the same trailing-slot shape).
+	const useBoundStoreWithEqualityFn = (...args: unknown[]) => {
+		const tail = args[args.length - 1];
+		const slot = typeof tail === 'symbol' ? tail : undefined;
+		const u = slot !== undefined ? args.slice(0, -1) : args;
+		const selector = u[0];
+		const equalityFn = u.length > 1 ? u[1] : defaultEqualityFn;
+		return (useStoreWithEqualityFn as (...a: unknown[]) => unknown)(
+			api,
+			selector,
+			equalityFn,
+			slot,
+		);
+	};
+	Object.assign(useBoundStoreWithEqualityFn, api);
+	return useBoundStoreWithEqualityFn;
+}) as CreateWithEqualityFn;
+
+export const createWithEqualityFn = (<T, U = T>(
+	createState?: StateCreator<T, [], []>,
+	defaultEqualityFn?: (a: U, b: U) => boolean,
+) =>
+	createState
+		? createWithEqualityFnImpl(
+				createState,
+				defaultEqualityFn as (a: unknown, b: unknown) => boolean,
+			)
+		: createWithEqualityFnImpl) as CreateWithEqualityFn;

package/src/vanilla.ts

@@ -0,0 +1,7 @@
+// The framework-agnostic core, re-exported verbatim from zustand. @octanejs/zustand
+// reuses zustand's vanilla store unchanged — only the React binding (see index.ts)
+// is swapped for one built on octane's `useSyncExternalStore`. Authors who only
+// need the store (no component binding) can import from `@octanejs/zustand/vanilla`
+// exactly as they would from `zustand/vanilla`.
+export * from 'zustand/vanilla';
+export { createStore as default } from 'zustand/vanilla';