@mpen/react-external-state 0.1.0

package/README.md

@@ -0,0 +1,189 @@
+# @mpen/react-external-state
+
+Small external state stores with optional React bindings and localStorage persistence.
+
+The base store does not depend on React. Use `@mpen/react-external-state/react` only when you want hooks or context-scoped stores.
+
+## Install
+
+```sh
+bun add @mpen/react-external-state
+```
+
+## Store
+
+```ts
+import { createStore } from '@mpen/react-external-state'
+
+const counter = createStore({ count: 0 })
+
+const unsubscribe = counter.subscribe((state, previousState) => {
+    console.log(previousState.count, '->', state.count)
+})
+
+counter.setState((state) => ({
+    count: state.count + 1,
+}))
+
+counter.set({ count: 10 })
+
+console.log(counter.get())
+
+unsubscribe()
+```
+
+Use `subscribeSelector` when code outside React only cares about part of the state.
+
+```ts
+const unsubscribe = counter.subscribeSelector(
+    (state) => state.count,
+    (count) => {
+        console.log('count changed:', count)
+    },
+    { fireImmediately: true },
+)
+```
+
+## React
+
+```tsx
+import { createReactStore } from '@mpen/react-external-state/react'
+
+const session = createReactStore({
+    userId: null as string | null,
+    theme: 'system' as 'light' | 'dark' | 'system',
+})
+
+export function ThemeButton() {
+    const theme = session.use((state) => state.theme)
+
+    return (
+        <button
+            type="button"
+            onClick={() => {
+                session.setState((state) => ({
+                    ...state,
+                    theme: state.theme === 'dark' ? 'light' : 'dark',
+                }))
+            }}
+        >
+            {theme}
+        </button>
+    )
+}
+
+session.setState((state) => ({
+    ...state,
+    userId: 'user_123',
+}))
+```
+
+You can also use an existing store with `useStore`.
+
+```tsx
+import { createStore } from '@mpen/react-external-state'
+import { useStore } from '@mpen/react-external-state/react'
+
+const counter = createStore({ count: 0 })
+
+export function Counter() {
+    const count = useStore(counter, (state) => state.count)
+
+    return (
+        <button
+            type="button"
+            onClick={() => counter.setState((state) => ({ count: state.count + 1 }))}
+        >
+            {count}
+        </button>
+    )
+}
+```
+
+## localStorage
+
+```ts
+import { createLocalStorageStore } from '@mpen/react-external-state'
+
+const settings = createLocalStorageStore('app.settings', {
+    theme: 'system' as 'light' | 'dark' | 'system',
+    sidebarOpen: true,
+})
+
+settings.setState((state) => ({
+    ...state,
+    sidebarOpen: !state.sidebarOpen,
+}))
+```
+
+By default values are serialized with `JSON.stringify` and restored with `JSON.parse`. Storage failures are ignored unless you pass `onError`.
+
+```ts
+const settings = createLocalStorageStore(
+    'app.settings',
+    { theme: 'system' },
+    {
+        onError(error, operation) {
+            console.warn(`Could not ${operation} settings`, error)
+        },
+    },
+)
+```
+
+## Context
+
+Use `createStoreContext` when state should be scoped to a React subtree instead of global module state.
+
+```tsx
+import { createStoreContext } from '@mpen/react-external-state/react'
+
+const DraftContext = createStoreContext({
+    title: '',
+    body: '',
+})
+
+export function DraftEditor() {
+    return (
+        <DraftContext.Provider initialValue={{ title: 'Untitled', body: '' }}>
+            <TitleInput />
+            <Preview />
+        </DraftContext.Provider>
+    )
+}
+
+function TitleInput() {
+    const title = DraftContext.use((state) => state.title)
+    const setDraft = DraftContext.useSetState()
+
+    return (
+        <input
+            value={title}
+            onChange={(event) => {
+                setDraft((state) => ({
+                    ...state,
+                    title: event.currentTarget.value,
+                }))
+            }}
+        />
+    )
+}
+
+function Preview() {
+    const draft = DraftContext.use()
+
+    return <article>{draft.title}</article>
+}
+```
+
+## API
+
+- `createStore(initialValue, options?)`
+- `createLocalStorageStore(key, initialValue, options?)`
+- `Store`
+- `store.get()` / `store.getSnapshot()`
+- `store.set(valueOrUpdater)` / `store.setState(valueOrUpdater)`
+- `store.subscribe(listener, options?)`
+- `store.subscribeSelector(selector, listener, options?)`
+- `useStore(store, selector?, options?)` from `@mpen/react-external-state/react`
+- `createReactStore(initialValue, options?)` from `@mpen/react-external-state/react`
+- `createStoreContext(defaultValue, options?)` from `@mpen/react-external-state/react`

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+import { a as Store, c as StoreSnapshot, d as createStore, f as resolveInitializer, i as StateUpdater, l as SubscribeOptions, n as Initializer, o as StoreListener, p as resolveStateUpdater, r as Selector, s as StoreOptions, t as EqualityFn, u as Unsubscribe } from "./store-B4lfgyM1.js";
+
+//#region src/local-storage.d.ts
+type StorageLike = Pick<Storage, 'getItem' | 'setItem'>;
+interface LocalStorageStoreOptions<T> extends StoreOptions<T> {
+  storage?: StorageLike | null;
+  serialize?: (value: T) => string;
+  deserialize?: (value: string) => T;
+  onError?: (error: unknown, operation: 'read' | 'write') => void;
+}
+declare function createLocalStorageStore<T>(key: string, initialValue: Initializer<T>, options?: LocalStorageStoreOptions<T>): Store<T>;
+//#endregion
+export { type EqualityFn, type Initializer, type LocalStorageStoreOptions, type Selector, type StateUpdater, type StorageLike, Store, type StoreListener, type StoreOptions, type StoreSnapshot, type SubscribeOptions, type Unsubscribe, createLocalStorageStore, createStore, resolveInitializer, resolveStateUpdater };

package/dist/index.js

@@ -0,0 +1,30 @@
+import { i as resolveStateUpdater, n as createStore, r as resolveInitializer, t as Store } from "./store-DblPx3Yb.js";
+//#region src/local-storage.ts
+function getDefaultStorage() {
+	if (typeof globalThis.localStorage === "undefined") return null;
+	return globalThis.localStorage;
+}
+function createLocalStorageStore(key, initialValue, options) {
+	const storage = options?.storage === void 0 ? getDefaultStorage() : options.storage;
+	const deserialize = options?.deserialize ?? JSON.parse;
+	const serialize = options?.serialize ?? JSON.stringify;
+	let value = initialValue;
+	if (storage !== null) try {
+		const storedValue = storage.getItem(key);
+		if (storedValue !== null) value = deserialize(storedValue);
+	} catch (error) {
+		options?.onError?.(error, "read");
+	}
+	const store = createStore(value, options);
+	store.subscribe((nextValue) => {
+		if (storage === null) return;
+		try {
+			storage.setItem(key, serialize(nextValue));
+		} catch (error) {
+			options?.onError?.(error, "write");
+		}
+	});
+	return store;
+}
+//#endregion
+export { Store, createLocalStorageStore, createStore, resolveInitializer, resolveStateUpdater };

package/dist/react.d.ts

@@ -0,0 +1,39 @@
+import { a as Store, c as StoreSnapshot, i as StateUpdater, n as Initializer, r as Selector, s as StoreOptions, t as EqualityFn } from "./store-B4lfgyM1.js";
+import * as _$react from "react";
+import { ReactNode } from "react";
+import * as _$react_jsx_runtime0 from "react/jsx-runtime";
+
+//#region src/react.d.ts
+interface UseStoreOptions<S> {
+  isEqual?: EqualityFn<S>;
+}
+interface ReactStore<T> extends Store<T> {
+  use(): T;
+  use<S>(selector: Selector<T, S>, options?: UseStoreOptions<S>): S;
+}
+interface StoreProviderProps<T> {
+  children?: ReactNode;
+  initialValue?: StateUpdater<T>;
+}
+declare function useStore<T>(store: StoreSnapshot<T>): T;
+declare function useStore<T, S>(store: StoreSnapshot<T>, selector: Selector<T, S>, options?: UseStoreOptions<S>): S;
+declare function createReactStore<T>(initialValue: Initializer<T>, options?: StoreOptions<T>): ReactStore<T>;
+declare function createStoreContext<T>(defaultValue: Initializer<T>, options?: StoreOptions<T>): {
+  Context: _$react.Context<Store<T> | null>;
+  Provider: ({
+    children,
+    initialValue
+  }: StoreProviderProps<T>) => _$react_jsx_runtime0.JSX.Element;
+  use: {
+    (): T;
+    <S>(selector: Selector<T, S>, useOptions?: UseStoreOptions<S>): S;
+  };
+  useStore: {
+    (): T;
+    <S>(selector: Selector<T, S>, useOptions?: UseStoreOptions<S>): S;
+  };
+  useStoreInstance: () => Store<T>;
+  useSetState: () => (state: StateUpdater<T>) => T;
+};
+//#endregion
+export { ReactStore, StoreProviderProps, UseStoreOptions, createReactStore, createStoreContext, useStore };

package/dist/react.js

@@ -0,0 +1,70 @@
+import { i as resolveStateUpdater, n as createStore, r as resolveInitializer, t as Store } from "./store-DblPx3Yb.js";
+import { createContext, useContext, useMemo, useState, useSyncExternalStore } from "react";
+import { jsx } from "react/jsx-runtime";
+//#region src/react.tsx
+const identity = (value) => value;
+function createSelectedSnapshot(store, selector, isEqual) {
+	let hasSnapshot = false;
+	let lastStoreSnapshot;
+	let lastSelectedSnapshot;
+	return () => {
+		const storeSnapshot = store.getSnapshot();
+		if (hasSnapshot && Object.is(storeSnapshot, lastStoreSnapshot)) return lastSelectedSnapshot;
+		const selectedSnapshot = selector(storeSnapshot);
+		if (hasSnapshot && isEqual(lastSelectedSnapshot, selectedSnapshot)) {
+			lastStoreSnapshot = storeSnapshot;
+			return lastSelectedSnapshot;
+		}
+		hasSnapshot = true;
+		lastStoreSnapshot = storeSnapshot;
+		lastSelectedSnapshot = selectedSnapshot;
+		return selectedSnapshot;
+	};
+}
+function useStore(store, selector = identity, options) {
+	const getSnapshot = useMemo(() => createSelectedSnapshot(store, selector, options?.isEqual ?? Object.is), [
+		store,
+		selector,
+		options?.isEqual
+	]);
+	return useSyncExternalStore((onStoreChange) => store.subscribe(onStoreChange), getSnapshot, getSnapshot);
+}
+function createReactStore(initialValue, options) {
+	const store = createStore(initialValue, options);
+	function useReactStore(selector, useOptions) {
+		return useStore(store, selector ?? identity, useOptions);
+	}
+	store.use = useReactStore;
+	return store;
+}
+function createStoreContext(defaultValue, options) {
+	const Context = createContext(null);
+	function useStoreInstance() {
+		const store = useContext(Context);
+		if (store === null) throw new Error("Store context is missing a matching Provider");
+		return store;
+	}
+	function Provider({ children, initialValue }) {
+		const [store] = useState(() => {
+			const resolvedDefaultValue = resolveInitializer(defaultValue);
+			return new Store(initialValue === void 0 ? resolvedDefaultValue : resolveStateUpdater(initialValue, resolvedDefaultValue), options);
+		});
+		return /* @__PURE__ */ jsx(Context.Provider, {
+			value: store,
+			children
+		});
+	}
+	function useContextStore(selector, useOptions) {
+		return useStore(useStoreInstance(), selector ?? identity, useOptions);
+	}
+	return {
+		Context,
+		Provider,
+		use: useContextStore,
+		useStore: useContextStore,
+		useStoreInstance,
+		useSetState: () => useStoreInstance().setState
+	};
+}
+//#endregion
+export { createReactStore, createStoreContext, useStore };

package/dist/store-B4lfgyM1.d.ts

@@ -0,0 +1,33 @@
+//#region src/store.d.ts
+type EqualityFn<T> = (a: T, b: T) => boolean;
+type Initializer<T> = T | (() => T);
+type Selector<T, S = T> = (value: T) => S;
+type StateUpdater<T> = T | ((previous: T) => T);
+type StoreListener<T> = (value: T, previousValue: T) => void;
+type Unsubscribe = () => void;
+interface StoreSnapshot<T> {
+  subscribe(listener: () => void): Unsubscribe;
+  getSnapshot(): T;
+}
+interface StoreOptions<T> {
+  isEqual?: EqualityFn<T>;
+}
+interface SubscribeOptions<T> {
+  fireImmediately?: boolean;
+  isEqual?: EqualityFn<T>;
+}
+declare function resolveInitializer<T>(value: Initializer<T>): T;
+declare function resolveStateUpdater<T>(value: StateUpdater<T>, previousValue: T): T;
+declare class Store<T> implements StoreSnapshot<T> {
+  #private;
+  constructor(initialValue: Initializer<T>, options?: StoreOptions<T>);
+  getSnapshot: () => T;
+  get: () => T;
+  setState: (state: StateUpdater<T>) => T;
+  set: (state: StateUpdater<T>) => T;
+  subscribe: (listener: StoreListener<T>, options?: SubscribeOptions<T>) => Unsubscribe;
+  subscribeSelector: <S>(selector: Selector<T, S>, listener: StoreListener<S>, options?: SubscribeOptions<S>) => Unsubscribe;
+}
+declare function createStore<T>(initialValue: Initializer<T>, options?: StoreOptions<T>): Store<T>;
+//#endregion
+export { Store as a, StoreSnapshot as c, createStore as d, resolveInitializer as f, StateUpdater as i, SubscribeOptions as l, Initializer as n, StoreListener as o, resolveStateUpdater as p, Selector as r, StoreOptions as s, EqualityFn as t, Unsubscribe as u };

package/dist/store-DblPx3Yb.js

@@ -0,0 +1,55 @@
+//#region src/store.ts
+const identity = (value) => value;
+function resolveInitializer(value) {
+	if (typeof value === "function") return value();
+	return value;
+}
+function resolveStateUpdater(value, previousValue) {
+	if (typeof value === "function") return value(previousValue);
+	return value;
+}
+var Store = class {
+	#isEqual;
+	#listeners = /* @__PURE__ */ new Set();
+	#value;
+	constructor(initialValue, options) {
+		this.#value = resolveInitializer(initialValue);
+		this.#isEqual = options?.isEqual ?? Object.is;
+	}
+	getSnapshot = () => this.#value;
+	get = () => this.#value;
+	setState = (state) => {
+		const previousValue = this.#value;
+		const nextValue = resolveStateUpdater(state, previousValue);
+		if (this.#isEqual(previousValue, nextValue)) return this.#value;
+		this.#value = nextValue;
+		for (const listener of [...this.#listeners]) listener(nextValue, previousValue);
+		return nextValue;
+	};
+	set = this.setState;
+	subscribe = (listener, options) => {
+		return this.subscribeSelector(identity, listener, options);
+	};
+	subscribeSelector = (selector, listener, options) => {
+		const select = selector;
+		const isEqual = options?.isEqual ?? Object.is;
+		let selectedValue = select(this.#value);
+		const storeListener = (value) => {
+			const nextSelectedValue = select(value);
+			if (isEqual(selectedValue, nextSelectedValue)) return;
+			const previousSelectedValue = selectedValue;
+			selectedValue = nextSelectedValue;
+			listener(nextSelectedValue, previousSelectedValue);
+		};
+		this.#listeners.add(storeListener);
+		if (options?.fireImmediately) listener(selectedValue, selectedValue);
+		return () => {
+			this.#listeners.delete(storeListener);
+		};
+	};
+};
+function createStore(initialValue, options) {
+	return new Store(initialValue, options);
+}
+//#endregion
+export { resolveStateUpdater as i, createStore as n, resolveInitializer as r, Store as t };

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@mpen/react-external-state",
+  "description": "Small external state stores with React hooks and localStorage persistence.",
+  "version": "0.1.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mnpenner/npm-packages.git",
+    "directory": "packages/react-external-state"
+  },
+  "license": "MIT",
+  "author": "Mark Penner <npm@mpen.ca>",
+  "packageManager": "bun@1.3.6",
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": "./dist/index.js",
+    "./react": "./dist/react.js",
+    "./package.json": "./package.json"
+  },
+  "types": "./dist/index.d.ts",
+  "peerDependencies": {
+    "react": "^19"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "@types/react": "^19",
+    "react": "catalog:",
+    "tsdown": "catalog:",
+    "typescript": "^6.0.2"
+  },
+  "scripts": {
+    "build": "bun run --bun tsdown",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit",
+    "_prepublishOnly": "bun run build && bun run test"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js"
+}