@effuse/store 1.0.0

package/src/core/store.ts

@@ -0,0 +1,467 @@
+/**
+ * MIT License
+ *
+ * Copyright (c) 2025 Chris M. Perez
+ *
+ * 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.
+ */
+
+import { Effect, Option, pipe, Predicate } from 'effect';
+import { signal, type Signal } from '@effuse/core';
+import type {
+	Store,
+	StoreState,
+	StoreDefinition,
+	StoreOptions,
+	Middleware,
+} from './types.js';
+import { createAtomicState } from './state.js';
+import { getStoreConfig } from '../config/index.js';
+import { createMiddlewareManager } from '../middleware/index.js';
+import { registerStore } from '../registry/index.js';
+import {
+	type StorageAdapter,
+	runAdapter,
+	localStorageAdapter,
+} from '../persistence/index.js';
+import {
+	createCancellationScope,
+	createCancellationToken,
+	type CancellationScope,
+	type CancellationToken,
+} from '../actions/cancellation.js';
+
+interface StoreInternals {
+	signalMap: Map<string, Signal<unknown>>;
+	initialState: Record<string, unknown>;
+	actions: Record<string, (...args: unknown[]) => unknown>;
+	subscribers: Set<() => void>;
+	keySubscribers: Map<string, Set<(value: unknown) => void>>;
+	computedSelectors: Map<
+		(s: Record<string, unknown>) => unknown,
+		Signal<unknown>
+	>;
+	isBatching: boolean;
+	cancellationScope: CancellationScope;
+	pendingActions: Map<string, CancellationToken>;
+}
+
+const getSnapshot = (
+	signalMap: Map<string, Signal<unknown>>
+): Record<string, unknown> => {
+	const snapshot: Record<string, unknown> = {};
+	for (const [key, sig] of signalMap) {
+		snapshot[key] = sig.value;
+	}
+	return snapshot;
+};
+
+// Store configuration options
+export interface CreateStoreOptions extends StoreOptions {
+	storage?: StorageAdapter;
+}
+
+// Initialize reactive store
+export const createStore = <T extends object>(
+	name: string,
+	definition: StoreDefinition<T>,
+	options?: CreateStoreOptions
+): Store<T> & StoreState<T> => {
+	const config = getStoreConfig();
+	const shouldPersist = pipe(
+		Option.fromNullable(options),
+		Option.flatMap((o) => Option.fromNullable(o.persist)),
+		Option.getOrElse(() => config.persistByDefault)
+	);
+	const storageKey = pipe(
+		Option.fromNullable(options),
+		Option.flatMap((o) => Option.fromNullable(o.storageKey)),
+		Option.getOrElse(() => `${config.storagePrefix}${name}`)
+	);
+	const enableDevtools = pipe(
+		Option.fromNullable(options),
+		Option.flatMap((o) => Option.fromNullable(o.devtools)),
+		Option.getOrElse(() => config.debug)
+	);
+	const adapter = pipe(
+		Option.fromNullable(options),
+		Option.flatMap((o) => Option.fromNullable(o.storage)),
+		Option.getOrElse(() => localStorageAdapter)
+	);
+
+	if (config.debug) {
+		console.log(`[store] Creating: ${name}`);
+	}
+
+	const internals: StoreInternals = {
+		signalMap: new Map(),
+		initialState: {},
+		actions: {},
+		subscribers: new Set(),
+		keySubscribers: new Map(),
+		computedSelectors: new Map(),
+		isBatching: false,
+		cancellationScope: createCancellationScope(),
+		pendingActions: new Map(),
+	};
+
+	const middlewareManager = createMiddlewareManager<Record<string, unknown>>();
+
+	for (const [key, value] of Object.entries(definition)) {
+		if (typeof value === 'function') {
+			internals.actions[key] = value as (...args: unknown[]) => unknown;
+		} else {
+			internals.initialState[key] = value;
+			internals.signalMap.set(key, signal(value));
+		}
+	}
+
+	const atomicState = createAtomicState({ ...internals.initialState });
+
+	if (shouldPersist) {
+		pipe(
+			runAdapter.getItem(adapter, storageKey),
+			Option.fromNullable,
+			Option.flatMap((saved) =>
+				Effect.runSync(
+					Effect.try(() => JSON.parse(saved) as Record<string, unknown>).pipe(
+						Effect.map(Option.some),
+						Effect.catchAll(() =>
+							Effect.succeed(Option.none<Record<string, unknown>>())
+						)
+					)
+				)
+			),
+			Option.map((parsed) => {
+				for (const [key, value] of Object.entries(parsed)) {
+					const sig = internals.signalMap.get(key);
+					if (sig) sig.value = value;
+				}
+				atomicState.set({ ...atomicState.get(), ...parsed });
+			})
+		);
+	}
+
+	const notifySubscribers = (): void => {
+		if (internals.isBatching) return;
+		for (const callback of internals.subscribers) callback();
+	};
+
+	const notifyKeySubscribers = (key: string, value: unknown): void => {
+		if (internals.isBatching) return;
+		const subs = internals.keySubscribers.get(key);
+		if (subs) for (const cb of subs) cb(value);
+	};
+
+	const persistState = (): void => {
+		if (!shouldPersist) return;
+		const snapshot = getSnapshot(internals.signalMap);
+		runAdapter.setItem(adapter, storageKey, JSON.stringify(snapshot));
+	};
+
+	const updateComputed = (): void => {
+		const snapshot = getSnapshot(internals.signalMap);
+		for (const [selector, sig] of internals.computedSelectors) {
+			const newValue = selector(snapshot);
+			if (sig.value !== newValue) sig.value = newValue;
+		}
+	};
+
+	const stateProxy = new Proxy({} as Record<string, unknown>, {
+		get(_, prop: string) {
+			const sig = internals.signalMap.get(prop);
+			if (sig) return sig;
+			const action = internals.actions[prop];
+			if (action) return action.bind(stateProxy);
+			return undefined;
+		},
+		set(_, prop: string, value: unknown) {
+			if (!internals.signalMap.has(prop)) return false;
+
+			const sig = internals.signalMap.get(prop);
+			if (!sig) return false;
+			const newState = middlewareManager.execute(
+				{ ...atomicState.get(), [prop]: value },
+				`set:${prop}`,
+				[value]
+			);
+
+			sig.value = newState[prop];
+			atomicState.update((s) => ({ ...s, [prop]: newState[prop] }));
+
+			if (enableDevtools) {
+				const time = new Date().toLocaleTimeString();
+				console.groupCollapsed(
+					`%caction %c${name}/set:${prop} %c@ ${time}`,
+					'color: gray; font-weight: lighter;',
+					'color: inherit; font-weight: bold;',
+					'color: gray; font-weight: lighter;'
+				);
+				console.log(
+					'%cprev state',
+					'color: #9E9E9E; font-weight: bold;',
+					atomicState.get()
+				);
+				console.log('%caction', 'color: #03A9F4; font-weight: bold;', {
+					type: `set:${prop}`,
+					payload: value,
+				});
+				console.log('%cnext state', 'color: #4CAF50; font-weight: bold;', {
+					...atomicState.get(),
+					[prop]: newState[prop],
+				});
+				console.groupEnd();
+			}
+
+			notifySubscribers();
+			notifyKeySubscribers(prop, newState[prop]);
+			persistState();
+			updateComputed();
+			return true;
+		},
+	});
+
+	const boundActions: Record<string, (...args: unknown[]) => unknown> = {};
+	for (const [key, action] of Object.entries(internals.actions)) {
+		boundActions[key] = (...args: unknown[]) => {
+			const prevState = enableDevtools
+				? getSnapshot(internals.signalMap)
+				: undefined;
+
+			const existingToken = internals.pendingActions.get(key);
+			if (existingToken) {
+				existingToken.cancel();
+			}
+
+			const result = action.apply(stateProxy, args);
+
+			if (result instanceof Promise) {
+				const token = createCancellationToken();
+				internals.pendingActions.set(key, token);
+
+				return result
+					.then((value: unknown) => {
+						if (!token.isCancelled) {
+							internals.pendingActions.delete(key);
+							const currentState = getSnapshot(internals.signalMap);
+							middlewareManager.execute(currentState, key, args);
+
+							if (enableDevtools) {
+								const time = new Date().toLocaleTimeString();
+								console.groupCollapsed(
+									`%caction %c${name}/${key} (async) %c@ ${time}`,
+									'color: gray; font-weight: lighter;',
+									'color: inherit; font-weight: bold;',
+									'color: gray; font-weight: lighter;'
+								);
+								console.log(
+									'%cprev state',
+									'color: #9E9E9E; font-weight: bold;',
+									prevState
+								);
+								console.log('%caction', 'color: #03A9F4; font-weight: bold;', {
+									type: `${name}/${key}`,
+									payload: args,
+								});
+								console.log(
+									'%cnext state',
+									'color: #4CAF50; font-weight: bold;',
+									currentState
+								);
+								console.groupEnd();
+							}
+
+							notifySubscribers();
+						}
+						return value;
+					})
+					.catch((error: unknown) => {
+						internals.pendingActions.delete(key);
+						throw error;
+					});
+			}
+
+			const currentState = getSnapshot(internals.signalMap);
+			middlewareManager.execute(currentState, key, args);
+
+			if (enableDevtools) {
+				const time = new Date().toLocaleTimeString();
+				console.groupCollapsed(
+					`%caction %c${name}/${key} %c@ ${time}`,
+					'color: gray; font-weight: lighter;',
+					'color: inherit; font-weight: bold;',
+					'color: gray; font-weight: lighter;'
+				);
+				console.log(
+					'%cprev state',
+					'color: #9E9E9E; font-weight: bold;',
+					prevState
+				);
+				console.log('%caction', 'color: #03A9F4; font-weight: bold;', {
+					type: `${name}/${key}`,
+					payload: args,
+				});
+				console.log(
+					'%cnext state',
+					'color: #4CAF50; font-weight: bold;',
+					currentState
+				);
+				console.groupEnd();
+			}
+
+			notifySubscribers();
+
+			return result;
+		};
+	}
+
+	const storeState: Record<string, unknown> = {};
+	for (const [key, sig] of internals.signalMap) storeState[key] = sig;
+	for (const [key, action] of Object.entries(boundActions))
+		storeState[key] = action;
+
+	const store: Store<T> = {
+		name,
+		state: storeState as StoreState<T>,
+
+		subscribe: (callback) => {
+			internals.subscribers.add(callback);
+			return () => {
+				internals.subscribers.delete(callback);
+			};
+		},
+
+		subscribeToKey: (key, callback) => {
+			const keyStr = String(key);
+			let subs = internals.keySubscribers.get(keyStr);
+			if (!subs) {
+				subs = new Set();
+				internals.keySubscribers.set(keyStr, subs);
+			}
+			const typedCallback = callback as (value: unknown) => void;
+			subs.add(typedCallback);
+			return () => {
+				const subsSet = internals.keySubscribers.get(keyStr);
+				if (Predicate.isNotNullable(subsSet)) {
+					subsSet.delete(typedCallback);
+				}
+			};
+		},
+
+		getSnapshot: () =>
+			getSnapshot(internals.signalMap) as ReturnType<Store<T>['getSnapshot']>,
+
+		computed: <R>(
+			selector: (snapshot: Record<string, unknown>) => R
+		): Signal<R> => {
+			const selectorKey = selector as (s: Record<string, unknown>) => unknown;
+			const existing = internals.computedSelectors.get(selectorKey);
+			if (existing) return existing as Signal<R>;
+
+			const initial = selector(getSnapshot(internals.signalMap));
+			const sig = signal<R>(initial);
+			internals.computedSelectors.set(selectorKey, sig as Signal<unknown>);
+			return sig;
+		},
+
+		batch: (updates) => {
+			internals.isBatching = true;
+			updates();
+			internals.isBatching = false;
+			notifySubscribers();
+			persistState();
+			updateComputed();
+		},
+
+		reset: () => {
+			for (const [key, value] of Object.entries(internals.initialState)) {
+				const sig = internals.signalMap.get(key);
+				if (sig) sig.value = value;
+			}
+			atomicState.set({ ...internals.initialState });
+			notifySubscribers();
+			persistState();
+			updateComputed();
+		},
+
+		use: (middleware: Middleware<Record<string, unknown>>) =>
+			middlewareManager.add(middleware),
+
+		toJSON: () =>
+			getSnapshot(internals.signalMap) as ReturnType<Store<T>['getSnapshot']>,
+
+		update: (updater) => {
+			const draft = { ...getSnapshot(internals.signalMap) } as {
+				[K in keyof T]: T[K] extends (...args: unknown[]) => unknown
+					? never
+					: T[K];
+			};
+
+			updater(draft);
+
+			internals.isBatching = true;
+			for (const [key, val] of Object.entries(draft)) {
+				const sig = internals.signalMap.get(key);
+				if (sig && sig.value !== val) {
+					sig.value = val;
+					atomicState.update((s) => ({ ...s, [key]: val }));
+				}
+			}
+			internals.isBatching = false;
+
+			notifySubscribers();
+			persistState();
+			updateComputed();
+		},
+
+		select: <R>(
+			selector: (snapshot: Record<string, unknown>) => R
+		): Signal<R> => {
+			const selectorKey = selector as (s: Record<string, unknown>) => unknown;
+			const existing = internals.computedSelectors.get(selectorKey);
+			if (existing) return existing as Signal<R>;
+
+			const initial = selector(getSnapshot(internals.signalMap));
+			const sig = signal<R>(initial);
+			internals.computedSelectors.set(selectorKey, sig as Signal<unknown>);
+
+			internals.subscribers.add(() => {
+				const newValue = selector(getSnapshot(internals.signalMap));
+				if (sig.value !== newValue) sig.value = newValue;
+			});
+
+			return sig;
+		},
+	};
+
+	const storeProxy = new Proxy(store as unknown as Record<string, unknown>, {
+		get(target, prop: string | symbol): unknown {
+			const propStr = String(prop);
+			if (propStr === 'toJSON') return () => getSnapshot(internals.signalMap);
+			if (propStr in target) return target[propStr];
+			const sig = internals.signalMap.get(propStr);
+			if (sig) return sig;
+			if (propStr in boundActions) return boundActions[propStr];
+			return undefined;
+		},
+	}) as Store<T> & StoreState<T>;
+
+	registerStore(name, storeProxy);
+	return storeProxy;
+};

package/src/core/types.ts

@@ -0,0 +1,107 @@
+/**
+ * MIT License
+ *
+ * Copyright (c) 2025 Chris M. Perez
+ *
+ * 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.
+ */
+
+import { Schema } from 'effect';
+import type { Signal } from '@effuse/core';
+
+export const StoreOptionsSchema = Schema.Struct({
+	persist: Schema.optional(Schema.Boolean),
+	storageKey: Schema.optional(Schema.String),
+	devtools: Schema.optional(Schema.Boolean),
+});
+
+// Store configuration schema
+export type StoreOptions = Schema.Schema.Type<typeof StoreOptionsSchema>;
+
+// Reactive store state
+export type StoreState<T> = {
+	[K in keyof T]: T[K] extends (...args: infer A) => infer R
+		? (...args: A) => R
+		: Signal<T[K]>;
+};
+
+// Internal store context
+export type StoreContext<T> = {
+	[K in keyof T]: T[K] extends (...args: unknown[]) => unknown
+		? T[K]
+		: Signal<T[K]>;
+};
+
+// Store definition structure
+export type StoreDefinition<T> = {
+	[K in keyof T]: T[K] extends (...args: infer A) => infer R
+		? (this: StoreContext<T>, ...args: A) => R
+		: T[K];
+};
+
+// Action execution context
+export type ActionContext<T> = StoreContext<T>;
+
+// Global state middleware
+export type Middleware<T> = (
+	state: T,
+	action: string,
+	args: unknown[]
+) => T | undefined;
+
+// Reactive store instance
+export interface Store<T> {
+	readonly name: string;
+	readonly state: StoreState<T>;
+	subscribe: (callback: () => void) => () => void;
+	subscribeToKey: <K extends keyof T>(
+		key: K,
+		callback: (value: T[K]) => void
+	) => () => void;
+	getSnapshot: () => {
+		[K in keyof T]: T[K] extends (...args: unknown[]) => unknown ? never : T[K];
+	};
+	computed: <R>(
+		selector: (snapshot: Record<string, unknown>) => R
+	) => Signal<R>;
+	batch: (updates: () => void) => void;
+	reset: () => void;
+	use: (middleware: Middleware<Record<string, unknown>>) => () => void;
+	toJSON: () => {
+		[K in keyof T]: T[K] extends (...args: unknown[]) => unknown ? never : T[K];
+	};
+	update: (
+		updater: (draft: {
+			[K in keyof T]: T[K] extends (...args: unknown[]) => unknown
+				? never
+				: T[K];
+		}) => void
+	) => void;
+	select: <R>(selector: (snapshot: Record<string, unknown>) => R) => Signal<R>;
+}
+
+// Extract state type from store
+export type InferStoreState<S> =
+	S extends Store<infer T>
+		? {
+				[K in keyof T]: T[K] extends (...args: unknown[]) => unknown
+					? never
+					: T[K];
+			}
+		: never;

package/src/devtools/connector.ts

@@ -0,0 +1,115 @@
+/**
+ * MIT License
+ *
+ * Copyright (c) 2025 Chris M. Perez
+ *
+ * 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.
+ */
+
+import { Option, pipe } from 'effect';
+import type { Store } from '../core/types.js';
+
+interface DevToolsExtension {
+	connect: (options?: { name?: string }) => DevToolsConnection;
+}
+
+interface DevToolsConnection {
+	init: (state: unknown) => void;
+	send: (action: { type: string; payload?: unknown }, state: unknown) => void;
+	subscribe: (listener: (message: { type: string }) => void) => () => void;
+}
+
+// Detect Redux DevTools extension
+export const hasDevTools = (): boolean => {
+	if (typeof globalThis === 'undefined') return false;
+	const w = globalThis as unknown as {
+		__REDUX_DEVTOOLS_EXTENSION__?: DevToolsExtension;
+	};
+	return w.__REDUX_DEVTOOLS_EXTENSION__ !== undefined;
+};
+
+const connections = new Map<string, DevToolsConnection>();
+
+// Connect store to DevTools
+export const connectDevTools = <T>(
+	store: Store<T>,
+	options?: { name?: string }
+): (() => void) => {
+	if (!hasDevTools()) {
+		return () => {};
+	}
+
+	const w = globalThis as unknown as {
+		__REDUX_DEVTOOLS_EXTENSION__?: DevToolsExtension;
+	};
+	const extension = w.__REDUX_DEVTOOLS_EXTENSION__;
+	if (!extension) return () => {};
+
+	const storeName = pipe(
+		Option.fromNullable(options),
+		Option.flatMap((o) => Option.fromNullable(o.name)),
+		Option.getOrElse(() => store.name)
+	);
+
+	if (connections.has(storeName)) {
+		return () => {};
+	}
+
+	const devTools = extension.connect({ name: `Effuse: ${storeName}` });
+	connections.set(storeName, devTools);
+
+	devTools.init(store.getSnapshot());
+
+	const unsubscribe = store.subscribe(() => {
+		devTools.send({ type: `${storeName}/update` }, store.getSnapshot());
+	});
+
+	return () => {
+		unsubscribe();
+		connections.delete(storeName);
+	};
+};
+
+// DevTools reporting middleware
+export const devToolsMiddleware = <T>(storeName: string) => {
+	return (state: T, action: string, args: unknown[]): T | undefined => {
+		const connection = connections.get(storeName);
+		if (connection) {
+			connection.send(
+				{ type: action, payload: args.length === 1 ? args[0] : args },
+				state
+			);
+		}
+		return undefined;
+	};
+};
+
+// Build DevTools middleware
+export const createDevToolsMiddleware = <T>(storeName: string) =>
+	devToolsMiddleware<T>(storeName);
+
+// Disconnect store from DevTools
+export const disconnectDevTools = (storeName: string): void => {
+	connections.delete(storeName);
+};
+
+// Disconnect all DevTools connections
+export const disconnectAllDevTools = (): void => {
+	connections.clear();
+};