stoic-store 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+import { a as StoicPlugin, i as CircularDependencyError, n as ActionMeta, o as createStore, r as ActionStatus, t as ActionContext } from "./stoic-CTcIKsRK.js";
+export { type ActionContext, type ActionMeta, type ActionStatus, CircularDependencyError, type StoicPlugin, createStore };

package/dist/index.js

@@ -0,0 +1,206 @@
+import { useRef, useSyncExternalStore } from "react";
+//#region src/stoic.ts
+var CircularDependencyError = class extends Error {
+	constructor(cycle) {
+		super(`Circular dependency detected:\n${cycle.join(" → ")}`);
+		this.name = "CircularDependencyError";
+	}
+};
+function findDerivedDependencyCycle(derivedKeys, dependencies) {
+	const derivedKeySet = new Set(derivedKeys);
+	const status = /* @__PURE__ */ new Map();
+	const path = [];
+	const visit = (node) => {
+		status.set(node, "visiting");
+		path.push(node);
+		for (const dep of dependencies.get(node) ?? []) {
+			if (!derivedKeySet.has(dep)) continue;
+			const depStatus = status.get(dep);
+			if (depStatus === "visiting") return [...path.slice(path.indexOf(dep)), dep];
+			if (depStatus === void 0) {
+				const found = visit(dep);
+				if (found) return found;
+			}
+		}
+		path.pop();
+		status.set(node, "done");
+		return null;
+	};
+	for (const key of derivedKeys) if (!status.has(key)) {
+		const cycle = visit(key);
+		if (cycle) return cycle;
+	}
+	return null;
+}
+function internal__createStore(config) {
+	let state = { ...config.state };
+	const derivedEntries = Object.entries(config.derived ?? {});
+	const derivedKeys = derivedEntries.map(([key]) => key);
+	const plugins = config.plugins ?? [];
+	const runHooks = (hook, ...args) => {
+		for (const p of plugins) p[hook]?.(...args);
+	};
+	const listeners = /* @__PURE__ */ new Set();
+	const dependencies = /* @__PURE__ */ new Map();
+	const recomputeDerived = (dirty) => {
+		let recomputedAny = false;
+		for (const [key, fn] of derivedEntries) {
+			const deps = dependencies.get(key);
+			if (!(dirty === null || deps === void 0 || [...deps].some((d) => dirty.has(d)))) continue;
+			recomputedAny = true;
+			const trackedKeys = /* @__PURE__ */ new Set();
+			const proxiedState = new Proxy(state, { get(target, prop, receiver) {
+				if (typeof prop === "string") trackedKeys.add(prop);
+				return Reflect.get(target, prop, receiver);
+			} });
+			const prevValue = state[key];
+			const newValue = fn(proxiedState);
+			dependencies.set(key, trackedKeys);
+			state[key] = newValue;
+			if (dirty !== null && !Object.is(prevValue, newValue)) dirty.add(key);
+		}
+		if (recomputedAny) {
+			const cycle = findDerivedDependencyCycle(derivedKeys, dependencies);
+			if (cycle) throw new CircularDependencyError(cycle);
+		}
+	};
+	recomputeDerived(null);
+	const getState = () => state;
+	const setState = (partial) => {
+		const prevState = state;
+		const next = typeof partial === "function" ? partial(state) : partial;
+		runHooks("beforeSetState", next);
+		state = {
+			...state,
+			...next
+		};
+		const dirty = /* @__PURE__ */ new Set();
+		for (const key of Object.keys(next)) if (!Object.is(prevState[key], state[key])) dirty.add(key);
+		recomputeDerived(dirty);
+		runHooks("afterSetState", state);
+		listeners.forEach((l) => {
+			l(state);
+		});
+	};
+	const subscribe = (listener) => {
+		listeners.add(listener);
+		return () => listeners.delete(listener);
+	};
+	const createActionRunner = (name, fn) => {
+		let meta = {
+			status: "idle",
+			error: void 0
+		};
+		const metaListeners = /* @__PURE__ */ new Set();
+		const setMeta = (next) => {
+			if (meta.status === next.status && meta.error === next.error) return;
+			meta = next;
+			metaListeners.forEach((l) => {
+				l(meta);
+			});
+		};
+		const runner = (...args) => {
+			const ctx = {
+				name,
+				args,
+				state: getState()
+			};
+			runHooks("beforeAction", ctx);
+			const finish = () => {
+				runHooks("afterAction", {
+					name,
+					args,
+					state: getState()
+				});
+			};
+			setMeta({
+				status: "pending",
+				error: void 0
+			});
+			let result;
+			try {
+				result = fn(setState, ...args);
+			} catch (err) {
+				finish();
+				setMeta({
+					status: "error",
+					error: err
+				});
+				throw err;
+			}
+			if (result instanceof Promise) return result.then((value) => {
+				finish();
+				setMeta({
+					status: "success",
+					error: void 0
+				});
+				return value;
+			}, (err) => {
+				finish();
+				setMeta({
+					status: "error",
+					error: err
+				});
+				throw err;
+			});
+			finish();
+			setMeta({
+				status: "success",
+				error: void 0
+			});
+			return result;
+		};
+		runner.getMeta = () => meta;
+		runner.subscribeMeta = (listener) => {
+			metaListeners.add(listener);
+			return () => metaListeners.delete(listener);
+		};
+		return runner;
+	};
+	const actions = ((map) => {
+		const result = {};
+		for (const [name, fn] of Object.entries(map)) result[name] = createActionRunner(name, fn);
+		return result;
+	});
+	const destroy = () => {
+		runHooks("onDestroy");
+		listeners.clear();
+	};
+	const store = {
+		getState,
+		setState,
+		subscribe,
+		actions,
+		destroy
+	};
+	runHooks("onInit", store);
+	return store;
+}
+function createStore(config) {
+	const store = internal__createStore(config);
+	function useStore(selector = (s) => s, equality = Object.is) {
+		const selectedRef = useRef(selector(store.getState()));
+		return useSyncExternalStore(store.subscribe, () => {
+			const next = selector(store.getState());
+			if (!equality(selectedRef.current, next)) selectedRef.current = next;
+			return selectedRef.current;
+		}, () => selector(store.getState()));
+	}
+	const actions = ((map) => {
+		const runners = store.actions(map);
+		for (const runner of Object.values(runners)) runner.useMeta = () => useSyncExternalStore(runner.subscribeMeta, runner.getMeta, runner.getMeta);
+		return runners;
+	});
+	return {
+		useStore,
+		getState: store.getState,
+		setState: store.setState,
+		subscribe: store.subscribe,
+		actions,
+		destroy: store.destroy
+	};
+}
+//#endregion
+export { CircularDependencyError, createStore };
+
+//# sourceMappingURL=index.js.map

package/dist/plugins.d.ts

@@ -0,0 +1,16 @@
+import { a as StoicPlugin } from "./stoic-CTcIKsRK.js";
+
+//#region src/plugins/persist.d.ts
+declare function persist<T extends object>(options: {
+  key: string;
+  storage?: () => Storage;
+  include?: (keyof T)[];
+  exclude?: (keyof T)[];
+  serialize?: (state: Partial<T>) => string;
+  deserialize?: (raw: string) => Partial<T>;
+  debounceMs?: number;
+  throttleMs?: number;
+}): StoicPlugin<T, T>;
+//#endregion
+export { persist };
+//# sourceMappingURL=plugins.d.ts.map

package/dist/plugins.js

@@ -0,0 +1,89 @@
+//#region src/plugins/persist.ts
+function filterKeys(state, options) {
+	if (options.include) {
+		const result = {};
+		for (const key of options.include) result[key] = state[key];
+		return result;
+	}
+	if (options.exclude) {
+		const excluded = new Set(options.exclude);
+		const result = {};
+		for (const key of Object.keys(state)) if (!excluded.has(key)) result[key] = state[key];
+		return result;
+	}
+	return state;
+}
+function persist(options) {
+	if (options.include && options.exclude) throw new Error("persist: pass either `include` or `exclude`, not both");
+	if (options.debounceMs !== void 0 && options.throttleMs !== void 0) throw new Error("persist: pass either `debounceMs` or `throttleMs`, not both");
+	const getStorage = options.storage ?? (() => localStorage);
+	const doSerialize = options.serialize ?? JSON.stringify;
+	const doDeserialize = options.deserialize ?? JSON.parse;
+	const writeToStorage = (state) => {
+		try {
+			getStorage().setItem(options.key, doSerialize(filterKeys(state, options)));
+		} catch {
+			console.warn("Stoic persist plugin: failed to write state to storage");
+		}
+	};
+	let debounceTimer;
+	let pendingState;
+	let throttleTimer;
+	let lastWriteTime = 0;
+	return {
+		onInit(store) {
+			try {
+				const raw = getStorage().getItem(options.key);
+				if (raw != null) {
+					const parsed = doDeserialize(raw);
+					store.setState(filterKeys(parsed, options));
+				}
+			} catch {
+				console.warn("Stoic persist plugin: failed to read state from storage");
+			}
+		},
+		afterSetState(state) {
+			if (options.debounceMs !== void 0) {
+				pendingState = state;
+				if (debounceTimer !== void 0) clearTimeout(debounceTimer);
+				debounceTimer = setTimeout(() => {
+					debounceTimer = void 0;
+					writeToStorage(state);
+				}, options.debounceMs);
+				return;
+			}
+			if (options.throttleMs !== void 0) {
+				pendingState = state;
+				const elapsed = Date.now() - lastWriteTime;
+				if (elapsed >= options.throttleMs) {
+					lastWriteTime = Date.now();
+					writeToStorage(state);
+					return;
+				}
+				if (throttleTimer === void 0) throttleTimer = setTimeout(() => {
+					throttleTimer = void 0;
+					lastWriteTime = Date.now();
+					writeToStorage(pendingState);
+				}, options.throttleMs - elapsed);
+				return;
+			}
+			writeToStorage(state);
+		},
+		onDestroy() {
+			if (debounceTimer !== void 0) {
+				clearTimeout(debounceTimer);
+				debounceTimer = void 0;
+				writeToStorage(pendingState);
+			}
+			if (throttleTimer !== void 0) {
+				clearTimeout(throttleTimer);
+				throttleTimer = void 0;
+				writeToStorage(pendingState);
+			}
+		}
+	};
+}
+//#endregion
+export { persist };
+
+//# sourceMappingURL=plugins.js.map

package/dist/stoic-CTcIKsRK.d.ts

@@ -0,0 +1,62 @@
+//#region src/stoic.d.ts
+type Listener<T> = (state: T) => void;
+type DerivedConfig<T, D> = { [K in keyof D]: (state: T & D) => D[K] };
+declare class CircularDependencyError extends Error {
+  constructor(cycle: string[]);
+}
+type SetState<T, Full = T> = (partial: Partial<T> | ((s: Full) => Partial<T>)) => void;
+type SyncActionFn<T, Full, A extends unknown[]> = (setState: SetState<T, Full>, ...args: A) => void;
+type AsyncActionFn<T, Full, A extends unknown[]> = (setState: SetState<T, Full>, ...args: A) => Promise<void>;
+type ActionStatus = "idle" | "pending" | "success" | "error";
+type ActionMeta = {
+  status: ActionStatus;
+  error: unknown;
+};
+type ActionHandle<A extends unknown[], R> = ((...args: A) => R) & {
+  getMeta: () => ActionMeta;
+  subscribeMeta: (listener: (meta: ActionMeta) => void) => () => void;
+};
+type ActionMap<T, Full> = Record<string, SyncActionFn<T, Full, any> | AsyncActionFn<T, Full, any>>;
+type ActionHandlesFor<M extends ActionMap<unknown, unknown>, T, Full> = { [K in keyof M]: M[K] extends AsyncActionFn<T, Full, infer A> ? ActionHandle<A, Promise<void>> : M[K] extends SyncActionFn<T, Full, infer A> ? ActionHandle<A, void> : never };
+type StoicStore<T, Full = T> = {
+  getState: () => Full;
+  setState: SetState<T, Full>;
+  subscribe: (listener: Listener<Full>) => () => void;
+  actions<M extends ActionMap<T, Full>>(map: M): ActionHandlesFor<M, T, Full>;
+  destroy: () => void;
+};
+type ActionContext<Full = unknown> = {
+  name: string;
+  args: unknown[];
+  state: Full;
+};
+interface StoicPlugin<T extends object = object, Full extends object = T> {
+  onInit?(store: StoicStore<T, Full>): void;
+  beforeAction?(ctx: ActionContext<Full>): void;
+  afterAction?(ctx: ActionContext<Full>): void;
+  beforeSetState?(nextState: Partial<T>): void;
+  afterSetState?(state: Full): void;
+  onDestroy?(): void;
+}
+type UseStore<Full> = <U = Full>(selector?: (state: Full) => U, equality?: (a: U, b: U) => boolean) => U;
+type ActionHandleWithHook<A extends unknown[], R> = ActionHandle<A, R> & {
+  useMeta: () => ActionMeta;
+};
+type ActionHandlesWithHookFor<M extends ActionMap<unknown, unknown>, T, Full> = { [K in keyof M]: M[K] extends AsyncActionFn<T, Full, infer A> ? ActionHandleWithHook<A, Promise<void>> : M[K] extends SyncActionFn<T, Full, infer A> ? ActionHandleWithHook<A, void> : never };
+type StoicHookedStore<T, Full> = Omit<StoicStore<T, Full>, "actions"> & {
+  useStore: UseStore<Full>;
+  actions<M extends ActionMap<T, Full>>(map: M): ActionHandlesWithHookFor<M, T, Full>;
+};
+declare function createStore<T extends object>(config: {
+  state: T;
+  derived?: undefined;
+  plugins?: StoicPlugin<T, T>[];
+}): StoicHookedStore<T, T>;
+declare function createStore<T extends object, D extends object>(config: {
+  state: T;
+  derived: DerivedConfig<T, D>;
+  plugins?: StoicPlugin<T, T & D>[];
+}): StoicHookedStore<T, T & D>;
+//#endregion
+export { StoicPlugin as a, CircularDependencyError as i, ActionMeta as n, createStore as o, ActionStatus as r, ActionContext as t };
+//# sourceMappingURL=stoic-CTcIKsRK.d.ts.map

package/dist/tools.d.ts

@@ -0,0 +1,5 @@
+//#region src/tools/shallow.d.ts
+declare function shallow<T>(a: T, b: T): boolean;
+//#endregion
+export { shallow };
+//# sourceMappingURL=tools.d.ts.map

package/dist/tools.js

@@ -0,0 +1,14 @@
+//#region src/tools/shallow.ts
+function shallow(a, b) {
+	if (Object.is(a, b)) return true;
+	if (typeof a !== "object" || a === null || typeof b !== "object" || b === null) return false;
+	const keysA = Object.keys(a);
+	const keysB = Object.keys(b);
+	if (keysA.length !== keysB.length) return false;
+	for (const key of keysA) if (!Object.hasOwn(b, key) || !Object.is(a[key], b[key])) return false;
+	return true;
+}
+//#endregion
+export { shallow };
+
+//# sourceMappingURL=tools.js.map

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "stoic-store",
+  "type": "module",
+  "version": "0.0.1",
+  "description": "Minimal and powerful React state manager. Tiny, intuitive, and fully TypeScript-ready.",
+  "author": "peakercope <peakercope@gmail.com> (https://github.com/peakercope)",
+  "license": "MIT",
+  "keywords": [
+    "react",
+    "state",
+    "state-management",
+    "store",
+    "derived-state",
+    "typescript"
+  ],
+  "homepage": "https://github.com/peakercope/stoic#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/peakercope/stoic.git",
+    "directory": "packages/stoic"
+  },
+  "bugs": {
+    "url": "https://github.com/peakercope/stoic/issues"
+  },
+  "exports": {
+    ".": "./dist/index.js",
+    "./plugins": "./dist/plugins.js",
+    "./tools": "./dist/tools.js",
+    "./package.json": "./package.json"
+  },
+  "types": "./dist/index.d.ts",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "!dist/**/*.map"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "test": "vitest",
+    "typecheck": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0",
+    "react-dom": "^18.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "^18.0.0",
+    "@types/react-dom": "^18.0.0",
+    "@vitejs/plugin-react": "^6.0.1",
+    "@vitest/coverage-v8": "^4.1.9",
+    "happy-dom": "^20.8.4",
+    "react": "^18.0.0",
+    "react-dom": "^18.0.0",
+    "tsdown": "^0.22.3",
+    "vite": "^8.1.3",
+    "vitest": "^4.1.9"
+  }
+}