@octanejs/tanstack-store 0.0.1

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,71 @@
+# @octanejs/tanstack-store
+
+[TanStack Store](https://tanstack.com/store) bindings for the
+[Octane](https://github.com/octanejs/octane) UI framework.
+
+This package ports `@tanstack/react-store@0.11.0` by reusing the
+framework-agnostic `@tanstack/store` core unchanged and transcribing its small
+React hook layer onto Octane. The supported runtime and type surfaces match the
+React package, so an application can migrate by changing its import:
+
+```ts
+// before
+import { createStore, useSelector } from '@tanstack/react-store'
+
+// after
+import { createStore, useSelector } from '@octanejs/tanstack-store'
+```
+
+```tsx
+import { createStore, useSelector } from '@octanejs/tanstack-store'
+
+const counter = createStore({ count: 0 })
+
+export function Counter() @{
+  const count = useSelector(counter, (state) => state.count)
+
+  <button
+    onClick={() =>
+      counter.setState((state) => ({ count: state.count + 1 }))
+    }
+  >
+    {'Count: ' + count}
+  </button>
+}
+```
+
+## API
+
+The package re-exports all of `@tanstack/store@0.11.0`, including atoms,
+stores, actions, derived sources, `shallow`, and async atoms. It also provides
+the stable adapter surface from `@tanstack/react-store@0.11.0`:
+
+- `useSelector` reads any atom or store and supports a custom comparator.
+- `useAtom` returns a writable atom's current value and setter.
+- `useCreateAtom` and `useCreateStore` create a stable source for a component
+  lifetime.
+- `createStoreContext` transports typed bundles of atoms and stores through an
+  Octane subtree.
+- `useStore` remains available as the upstream-deprecated compatibility alias
+  for `useSelector`.
+
+The upstream experimental `_useStore` export is intentionally omitted. Use
+`useSelector` with `store.actions` or `store.setState` instead.
+
+The adapter forwards Octane's compiler-assigned hook slots through its composed
+hooks. Distinct calls in one component therefore keep independent subscriptions
+and component-created sources, including when optional selector and comparator
+arguments are omitted.
+
+## Verification
+
+Behavioral tests cover writable and derived sources, comparator semantics,
+source replacement, multiple hook call sites, context nesting, subscription
+cleanup, actions, and server rendering. Differential tests compile the same
+`.tsrx` fixture for Octane and React and compare rendered output after each
+interaction. Compile-time tests cover overload inference and readonly versus
+writable source constraints.
+
+Current scope and verification status are tracked in the generated
+[bindings status table](../../docs/bindings-status.md), sourced from this
+package's [`status.json`](./status.json).

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@octanejs/tanstack-store",
+  "version": "0.0.1",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "octane": {
+    "hookSlots": {
+      "manual": [
+        "src"
+      ]
+    }
+  },
+  "description": "TanStack Store bindings for Octane — reuses the framework-agnostic @tanstack/store core with an Octane hook adapter.",
+  "author": {
+    "name": "Dominic Gannaway",
+    "email": "dg@domgan.com"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/octanejs/octane.git",
+    "directory": "packages/tanstack-store"
+  },
+  "main": "src/index.ts",
+  "module": "src/index.ts",
+  "types": "src/index.ts",
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "dependencies": {
+    "@tanstack/store": "0.11.0"
+  },
+  "peerDependencies": {
+    "octane": "0.1.7"
+  },
+  "devDependencies": {
+    "@tanstack/react-store": "^0.11.0",
+    "@tsrx/react": "^0.2.37",
+    "esbuild": "^0.28.1",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "vitest": "^4.1.9",
+    "octane": "0.1.7"
+  },
+  "scripts": {
+    "test": "vitest run"
+  }
+}

package/src/createStoreContext.tsrx

@@ -0,0 +1,68 @@
+import { createContext, useContext } from 'octane';
+import type { ComponentBody } from 'octane';
+
+/**
+ * Creates a typed Octane context for sharing a bundle of atoms and stores with a subtree.
+ *
+ * The returned `StoreProvider` only transports the provided object through
+ * Octane context. Consumers destructure the contextual atoms and stores, then
+ * compose them with the existing hooks like {@link useSelector},
+ * {@link useSelector} and {@link useAtom}.
+ *
+ * The object shape is preserved exactly, so keyed atoms and stores remain fully
+ * typed when read back with `useStoreContext()`.
+ *
+ * @example
+ * ```tsx
+ * const { StoreProvider, useStoreContext } = createStoreContext<{
+ *   countAtom: Atom<number>
+ *   totalsStore: Store<{ count: number }>
+ * }>()
+ *
+ * function CountButton() {
+ *   const { countAtom, totalsStore } = useStoreContext()
+ *   const count = useSelector(countAtom)
+ *   const total = useSelector(totalsStore, (state) => state.count)
+ *
+ *   return (
+ *     <button
+ *       type="button"
+ *       onClick={() => totalsStore.setState((state) => ({ ...state, count: state.count + 1 }))}
+ *     >
+ *       {count} / {total}
+ *     </button>
+ *   )
+ * }
+ * ```
+ *
+ * @throws When `useStoreContext()` is called outside the matching `StoreProvider`.
+ */
+export function createStoreContext<TValue extends object>(): {
+	StoreProvider: ComponentBody<{
+		value: TValue;
+		children?: any;
+	}>;
+	useStoreContext: () => TValue;
+} {
+	const Context = createContext<TValue | null>(null);
+	(Context as typeof Context & { displayName?: string }).displayName = 'StoreContext';
+
+	function StoreProvider({ children, value }: { value: TValue; children?: any }) {
+		return <Context.Provider value={value}>{children}</Context.Provider>;
+	}
+
+	function useStoreContext() {
+		const value = useContext(Context);
+
+		if (value === null) {
+			throw new Error('Missing StoreProvider for StoreContext');
+		}
+
+		return value;
+	}
+
+	return {
+		StoreProvider,
+		useStoreContext,
+	};
+}

package/src/createStoreContext.tsrx.d.ts

@@ -0,0 +1,9 @@
+import type { ComponentBody } from 'octane';
+
+export function createStoreContext<TValue extends object>(): {
+	StoreProvider: ComponentBody<{
+		value: TValue;
+		children?: any;
+	}>;
+	useStoreContext: () => TValue;
+};

package/src/index.ts

@@ -0,0 +1,14 @@
+export * from '@tanstack/store';
+
+// create hooks
+export * from './createStoreContext.tsrx';
+export * from './useCreateAtom';
+export * from './useCreateStore';
+
+// read hooks
+export * from './useSelector';
+
+// tuple hooks - [state, setState]
+export * from './useAtom';
+
+export * from './useStore'; // @deprecated in favor of useSelector

package/src/internal.ts

@@ -0,0 +1,36 @@
+// Slot mechanics for the binding's plain-`.ts` hooks. Octane injects a
+// per-call-site Symbol into calls made by compiled components; the binding
+// forwards that symbol and derives a distinct sub-slot for each hook it
+// composes.
+const subSlotCache = new Map<symbol, Map<string, symbol>>();
+const bareTagCache = new Map<string, symbol>();
+
+export function subSlot(slot: symbol | undefined, tag: string): symbol {
+	if (slot === undefined) {
+		let bare = bareTagCache.get(tag);
+		if (bare === undefined) {
+			bare = Symbol.for(`@octanejs/tanstack-store:${tag}`);
+			bareTagCache.set(tag, bare);
+		}
+		return bare;
+	}
+
+	let byTag = subSlotCache.get(slot);
+	if (byTag === undefined) {
+		byTag = new Map();
+		subSlotCache.set(slot, byTag);
+	}
+
+	let child = byTag.get(tag);
+	if (child === undefined) {
+		child = Symbol.for(`${slot.description ?? ''}:${tag}`);
+		byTag.set(tag, child);
+	}
+	return child;
+}
+
+export function splitSlot(args: unknown[]): [unknown[], symbol | undefined] {
+	const tail = args[args.length - 1];
+	const slot = typeof tail === 'symbol' ? tail : undefined;
+	return [slot === undefined ? args : args.slice(0, -1), slot];
+}

package/src/useAtom.ts

@@ -0,0 +1,37 @@
+import { useSelector } from './useSelector';
+import { splitSlot, subSlot } from './internal';
+import type { Atom } from '@tanstack/store';
+import type { UseSelectorOptions } from './useSelector';
+
+/**
+ * Returns the current atom value together with a stable setter.
+ *
+ * This is the writable-atom convenience hook for components that need to both
+ * read and update the same atom.
+ *
+ * @example
+ * ```tsx
+ * const [count, setCount] = useAtom(countAtom)
+ * ```
+ */
+export function useAtom<TValue>(
+	atom: Atom<TValue>,
+	options?: UseSelectorOptions<TValue>,
+): [TValue, Atom<TValue>['set']];
+export function useAtom<TValue>(
+	atom: Atom<TValue>,
+	...rest: [options?: UseSelectorOptions<TValue>, slot?: symbol]
+): [TValue, Atom<TValue>['set']] {
+	const [user, slot] = splitSlot(rest);
+	const options = user[0] as UseSelectorOptions<TValue> | undefined;
+	const value = (
+		useSelector as (
+			source: Atom<TValue>,
+			selector: undefined,
+			options: UseSelectorOptions<TValue> | undefined,
+			slot: symbol,
+		) => TValue
+	)(atom, undefined, options, subSlot(slot, 'atom:value'));
+
+	return [value, atom.set];
+}

package/src/useCreateAtom.ts

@@ -0,0 +1,38 @@
+import { useState } from 'octane';
+import { createAtom } from '@tanstack/store';
+import { splitSlot } from './internal';
+import type { Atom, AtomOptions, ReadonlyAtom } from '@tanstack/store';
+
+/**
+ * Creates a stable atom instance for the lifetime of the component.
+ *
+ * Pass an initial value to create a writable atom, or a getter function to
+ * create a readonly derived atom. This hook mirrors the overloads from
+ * {@link createAtom}, but ensures the atom is only created once per mount.
+ *
+ * @example
+ * ```tsx
+ * const countAtom = useCreateAtom(0)
+ * ```
+ */
+export function useCreateAtom<T>(
+	getValue: (prev?: NoInfer<T>) => T,
+	options?: AtomOptions<T>,
+): ReadonlyAtom<T>;
+export function useCreateAtom<T>(initialValue: T, options?: AtomOptions<T>): Atom<T>;
+export function useCreateAtom<T>(
+	valueOrFn: T | ((prev?: T) => T),
+	...rest: [options?: AtomOptions<T>, slot?: symbol]
+): Atom<T> | ReadonlyAtom<T> {
+	const [user, slot] = splitSlot(rest);
+	const options = user[0] as AtomOptions<T> | undefined;
+	const [atom] = useState<Atom<T> | ReadonlyAtom<T>>(() => {
+		if (typeof valueOrFn === 'function') {
+			return createAtom(valueOrFn as (prev?: NoInfer<T>) => T, options);
+		}
+
+		return createAtom(valueOrFn, options);
+	}, slot);
+
+	return atom;
+}

package/src/useCreateStore.ts

@@ -0,0 +1,45 @@
+import { useState } from 'octane';
+import { createStore } from '@tanstack/store';
+import type { ReadonlyStore, Store, StoreActionMap, StoreActionsFactory } from '@tanstack/store';
+import { splitSlot } from './internal';
+
+type NonFunction<T> = T extends (...args: Array<any>) => any ? never : T;
+
+/**
+ * Creates a stable store instance for the lifetime of the component.
+ *
+ * Pass an initial value to create a writable store, or a getter function to
+ * create a readonly derived store. This hook mirrors the overloads from
+ * {@link createStore}, but ensures the store is only created once per mount.
+ *
+ * @example
+ * ```tsx
+ * const counterStore = useCreateStore({ count: 0 })
+ * ```
+ */
+export function useCreateStore<T>(getValue: (prev?: NoInfer<T>) => T): ReadonlyStore<T>;
+export function useCreateStore<T>(initialValue: T): Store<T>;
+export function useCreateStore<T, TActions extends StoreActionMap>(
+	initialValue: NonFunction<T>,
+	actions: StoreActionsFactory<T, TActions>,
+): Store<T, TActions>;
+export function useCreateStore<T, TActions extends StoreActionMap>(
+	valueOrFn: T | ((prev?: T) => T),
+	...rest: [actions?: StoreActionsFactory<T, TActions>, slot?: symbol]
+): Store<T, TActions> | Store<T> | ReadonlyStore<T> {
+	const [user, slot] = splitSlot(rest);
+	const actions = user[0] as StoreActionsFactory<T, TActions> | undefined;
+	const [store] = useState<Store<T, TActions> | Store<T> | ReadonlyStore<T>>(() => {
+		if (typeof valueOrFn === 'function') {
+			return createStore(valueOrFn as (prev?: NoInfer<T>) => T);
+		}
+
+		if (actions) {
+			return createStore(valueOrFn as NonFunction<T>, actions);
+		}
+
+		return createStore(valueOrFn);
+	}, slot);
+
+	return store;
+}

package/src/useSelector.ts

@@ -0,0 +1,81 @@
+import { useCallback } from 'octane';
+import { splitSlot, subSlot } from './internal';
+import { useSyncExternalStoreWithSelector } from './useSyncExternalStoreWithSelector';
+
+export interface UseSelectorOptions<TSelected> {
+	compare?: (a: TSelected, b: TSelected) => boolean;
+}
+
+type SyncExternalStoreSubscribe = Parameters<typeof useSyncExternalStoreWithSelector>[0];
+
+type SelectionSource<T> = {
+	get: () => T;
+	subscribe: (listener: (value: T) => void) => {
+		unsubscribe: () => void;
+	};
+};
+
+function defaultCompare<T>(a: T, b: T) {
+	return a === b;
+}
+
+/**
+ * Selects a slice of state from an atom or store and subscribes the component
+ * to that selection.
+ *
+ * This is the primary Octane read hook for TanStack Store. It works with any
+ * source that exposes `get()` and `subscribe()`, including atoms, readonly
+ * atoms, stores, and readonly stores.
+ *
+ * Omit the selector to subscribe to the whole value.
+ *
+ * @example
+ * ```tsx
+ * const count = useSelector(counterStore, (state) => state.count)
+ * ```
+ *
+ * @example
+ * ```tsx
+ * const value = useSelector(countAtom)
+ * ```
+ */
+export function useSelector<TSource, TSelected = NoInfer<TSource>>(
+	source: SelectionSource<TSource>,
+	selector?: (snapshot: TSource) => TSelected,
+	options?: UseSelectorOptions<TSelected>,
+): TSelected;
+export function useSelector<TSource, TSelected = NoInfer<TSource>>(
+	source: SelectionSource<TSource>,
+	...rest: [
+		selector?: (snapshot: TSource) => TSelected,
+		options?: UseSelectorOptions<TSelected>,
+		slot?: symbol,
+	]
+): TSelected {
+	const [user, slot] = splitSlot(rest);
+	const selector =
+		(user[0] as ((snapshot: TSource) => TSelected) | undefined) ??
+		((snapshot: TSource) => snapshot as unknown as TSelected);
+	const options = user[1] as UseSelectorOptions<TSelected> | undefined;
+	const compare = options?.compare ?? defaultCompare;
+
+	const subscribe: SyncExternalStoreSubscribe = useCallback(
+		(handleStoreChange) => {
+			const { unsubscribe } = source.subscribe(handleStoreChange);
+			return unsubscribe;
+		},
+		[source],
+		subSlot(slot, 'selector:subscribe'),
+	);
+
+	const getSnapshot = useCallback(() => source.get(), [source], subSlot(slot, 'selector:snapshot'));
+
+	return useSyncExternalStoreWithSelector(
+		subscribe,
+		getSnapshot,
+		getSnapshot,
+		selector,
+		compare,
+		subSlot(slot, 'selector:external-store'),
+	);
+}

package/src/useStore.ts

@@ -0,0 +1,47 @@
+import { useSelector } from './useSelector';
+import { splitSlot } from './internal';
+import type { UseSelectorOptions } from './useSelector';
+
+type SelectionSource<T> = {
+	get: () => T;
+	subscribe: (listener: (value: T) => void) => {
+		unsubscribe: () => void;
+	};
+};
+
+/**
+ * Deprecated alias for {@link useSelector}.
+ *
+ * @example
+ * ```tsx
+ * const count = useStore(counterStore, (state) => state.count)
+ * ```
+ *
+ * @deprecated Use `useSelector` instead.
+ */
+export function useStore<TSource, TSelected = NoInfer<TSource>>(
+	source: SelectionSource<TSource>,
+	selector?: (snapshot: TSource) => TSelected,
+	compare?: (a: TSelected, b: TSelected) => boolean,
+): TSelected;
+export function useStore<TSource, TSelected = NoInfer<TSource>>(
+	source: SelectionSource<TSource>,
+	...rest: [
+		selector?: (snapshot: TSource) => TSelected,
+		compare?: (a: TSelected, b: TSelected) => boolean,
+		slot?: symbol,
+	]
+): TSelected {
+	const [user, slot] = splitSlot(rest);
+	const selector = user[0] as ((snapshot: TSource) => TSelected) | undefined;
+	const compare = user[1] as ((a: TSelected, b: TSelected) => boolean) | undefined;
+
+	return (
+		useSelector as (
+			source: SelectionSource<TSource>,
+			selector: ((snapshot: TSource) => TSelected) | undefined,
+			options: UseSelectorOptions<TSelected>,
+			slot?: symbol,
+		) => TSelected
+	)(source, selector, { compare }, slot);
+}

package/src/useSyncExternalStoreWithSelector.ts

@@ -0,0 +1,90 @@
+// Port of React's `use-sync-external-store/with-selector` shim onto Octane's
+// native useSyncExternalStore. The selection is recomputed only when the
+// snapshot changes; when `isEqual` accepts the next selection, the previous
+// reference is retained so the external-store hook does not re-render.
+import { useEffect, useMemo, useRef, useSyncExternalStore } from 'octane';
+import { subSlot } from './internal';
+
+const objectIs: (x: unknown, y: unknown) => boolean =
+	typeof Object.is === 'function'
+		? Object.is
+		: (x: any, y: any) => (x === y && (x !== 0 || 1 / x === 1 / y)) || (x !== x && y !== y);
+
+export function useSyncExternalStoreWithSelector<Snapshot, Selection>(
+	subscribe: (onStoreChange: () => void) => () => void,
+	getSnapshot: () => Snapshot,
+	getServerSnapshot: undefined | null | (() => Snapshot),
+	selector: (snapshot: Snapshot) => Selection,
+	isEqual?: (a: Selection, b: Selection) => boolean,
+	slot?: symbol,
+): Selection {
+	const instRef = useRef<{ hasValue: boolean; value: Selection | null } | null>(
+		null,
+		subSlot(slot, 'ws:inst'),
+	);
+	let inst: { hasValue: boolean; value: Selection | null };
+	if (instRef.current === null) {
+		inst = { hasValue: false, value: null };
+		instRef.current = inst;
+	} else {
+		inst = instRef.current;
+	}
+
+	const [getSelection, getServerSelection] = useMemo(
+		() => {
+			let hasMemo = false;
+			let memoizedSnapshot: Snapshot;
+			let memoizedSelection: Selection;
+			const memoizedSelector = (nextSnapshot: Snapshot): Selection => {
+				if (!hasMemo) {
+					hasMemo = true;
+					memoizedSnapshot = nextSnapshot;
+					const nextSelection = selector(nextSnapshot);
+					if (isEqual !== undefined && inst.hasValue) {
+						const currentSelection = inst.value as Selection;
+						if (isEqual(currentSelection, nextSelection)) {
+							return (memoizedSelection = currentSelection);
+						}
+					}
+					return (memoizedSelection = nextSelection);
+				}
+				const currentSelection = memoizedSelection;
+				if (objectIs(memoizedSnapshot, nextSnapshot)) return currentSelection;
+				const nextSelection = selector(nextSnapshot);
+				if (isEqual !== undefined && isEqual(currentSelection, nextSelection)) {
+					memoizedSnapshot = nextSnapshot;
+					return currentSelection;
+				}
+				memoizedSnapshot = nextSnapshot;
+				return (memoizedSelection = nextSelection);
+			};
+			const maybeGetServerSnapshot = getServerSnapshot === undefined ? null : getServerSnapshot;
+			return [
+				() => memoizedSelector(getSnapshot()),
+				maybeGetServerSnapshot === null
+					? undefined
+					: () => memoizedSelector(maybeGetServerSnapshot!()),
+			] as const;
+		},
+		[getSnapshot, getServerSnapshot, selector, isEqual],
+		subSlot(slot, 'ws:memo'),
+	);
+
+	const value = useSyncExternalStore(
+		subscribe,
+		getSelection,
+		getServerSelection ?? getSelection,
+		subSlot(slot, 'ws:uses'),
+	);
+
+	useEffect(
+		() => {
+			inst.hasValue = true;
+			inst.value = value;
+		},
+		[value],
+		subSlot(slot, 'ws:eff'),
+	);
+
+	return value;
+}