@effuse/store 1.0.0

package/src/reactivity/selectors.ts

@@ -0,0 +1,180 @@
+/**
+ * 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 { signal, type Signal } from '@effuse/core';
+import type { Store } from '../core/types.js';
+import {
+	createCancellationToken,
+	type CancellationToken,
+} from '../actions/cancellation.js';
+
+// Shallow value comparison
+export const shallowEqual = <T>(a: T, b: T): boolean => {
+	if (Object.is(a, b)) return true;
+	if (
+		typeof a !== 'object' ||
+		a === null ||
+		typeof b !== 'object' ||
+		b === null
+	) {
+		return false;
+	}
+
+	if (Array.isArray(a) && Array.isArray(b)) {
+		if (a.length !== b.length) return false;
+		for (let i = 0; i < a.length; i++) {
+			if (!Object.is(a[i], b[i])) return false;
+		}
+		return true;
+	}
+
+	const keysA = Object.keys(a);
+	const keysB = Object.keys(b);
+	if (keysA.length !== keysB.length) return false;
+
+	for (const key of keysA) {
+		if (!Object.prototype.hasOwnProperty.call(b, key)) return false;
+		if (
+			!Object.is(
+				(a as Record<string, unknown>)[key],
+				(b as Record<string, unknown>)[key]
+			)
+		) {
+			return false;
+		}
+	}
+	return true;
+};
+
+// State extraction selector
+export type Selector<T, R> = (state: T) => R;
+
+// State equality check
+export type EqualityFn<T> = (a: T, b: T) => boolean;
+
+// Build memoized selector signal
+export const createSelector = <T, R>(
+	store: Store<T>,
+	selector: Selector<ReturnType<Store<T>['getSnapshot']>, R>,
+	equalityFn: EqualityFn<R> = shallowEqual
+): Signal<R> => {
+	const snapshot = store.getSnapshot();
+	const initialValue = selector(snapshot);
+	const derived = signal(initialValue);
+
+	store.subscribe(() => {
+		const currentSnapshot = store.getSnapshot();
+		const newValue = selector(currentSnapshot);
+		if (!equalityFn(derived.value, newValue)) {
+			derived.value = newValue;
+		}
+	});
+
+	return derived;
+};
+
+// Asynchronous state selector
+export type AsyncSelector<T, R> = (
+	state: T,
+	token: CancellationToken
+) => Promise<R>;
+
+// Build asynchronous selector signal
+export const createSelectorAsync = <T, R>(
+	store: Store<T>,
+	asyncSelector: AsyncSelector<ReturnType<Store<T>['getSnapshot']>, R>,
+	initialValue: R
+): Signal<R> & { pending: Signal<boolean>; cleanup: () => void } => {
+	const derived = signal<R>(initialValue);
+	const pending = signal<boolean>(false);
+	let currentToken = createCancellationToken();
+
+	const update = () => {
+		currentToken.cancel();
+		currentToken = createCancellationToken();
+		const myToken = currentToken;
+		pending.value = true;
+
+		const snapshot = store.getSnapshot();
+		asyncSelector(snapshot, myToken)
+			.then((newValue) => {
+				if (!myToken.isCancelled && derived.value !== newValue) {
+					derived.value = newValue;
+				}
+			})
+			.catch(() => {})
+			.finally(() => {
+				if (!myToken.isCancelled) {
+					pending.value = false;
+				}
+			});
+	};
+
+	const unsub = store.subscribe(update);
+	update();
+
+	const result = derived as Signal<R> & {
+		pending: Signal<boolean>;
+		cleanup: () => void;
+	};
+	result.pending = pending;
+	result.cleanup = () => {
+		currentToken.cancel();
+		unsub();
+	};
+
+	return result;
+};
+
+// Build property pick selector
+export const pick = <T, K extends keyof T>(
+	store: Store<T>,
+	keys: K[]
+): Signal<Pick<T, K>> => {
+	return createSelector(store, (state) => {
+		const picked = {} as Pick<T, K>;
+		for (const key of keys) {
+			if (key in (state as object)) {
+				picked[key] = (state as T)[key];
+			}
+		}
+		return picked;
+	});
+};
+
+// Build combined selector signal
+export const combineSelectors = <T, R extends Record<string, unknown>>(
+	store: Store<T>,
+	selectors: {
+		[K in keyof R]: Selector<ReturnType<Store<T>['getSnapshot']>, R[K]>;
+	}
+): Signal<R> => {
+	return createSelector(store, (state) => {
+		const result = {} as R;
+		for (const key of Object.keys(selectors) as (keyof R)[]) {
+			result[key] = selectors[key](state);
+		}
+		return result;
+	});
+};

package/src/reactivity/streams.ts

@@ -0,0 +1,194 @@
+/**
+ * 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 type { Store } from '../core/types.js';
+import {
+	createCancellationToken,
+	type CancellationToken,
+} from '../actions/cancellation.js';
+
+// Store state change stream
+export interface StoreStream<T> {
+	subscribe: (handler: (value: T) => void) => () => void;
+	map: <R>(fn: (value: T) => R) => StoreStream<R>;
+	filter: (predicate: (value: T) => boolean) => StoreStream<T>;
+	debounce: (ms: number) => StoreStream<T>;
+	throttle: (ms: number) => StoreStream<T>;
+	takeLatest: <R>(
+		asyncHandler: (value: T, token: CancellationToken) => Promise<R>
+	) => StoreStream<R>;
+}
+
+const createBaseStream = <T>(
+	addListener: (handler: (value: T) => void) => () => void
+): StoreStream<T> => {
+	return {
+		subscribe: addListener,
+
+		map: <R>(fn: (value: T) => R): StoreStream<R> => {
+			const mappedListeners = new Set<(value: R) => void>();
+			addListener((value) => {
+				const mapped = fn(value);
+				for (const h of mappedListeners) h(mapped);
+			});
+			return createBaseStream((h) => {
+				mappedListeners.add(h);
+				return () => mappedListeners.delete(h);
+			});
+		},
+
+		filter: (predicate): StoreStream<T> => {
+			const filteredListeners = new Set<(value: T) => void>();
+			addListener((value) => {
+				if (predicate(value)) {
+					for (const h of filteredListeners) h(value);
+				}
+			});
+			return createBaseStream((h) => {
+				filteredListeners.add(h);
+				return () => filteredListeners.delete(h);
+			});
+		},
+
+		debounce: (ms): StoreStream<T> => {
+			const debouncedListeners = new Set<(value: T) => void>();
+			let timeout: ReturnType<typeof setTimeout> | null = null;
+			let latestValue: T | undefined;
+			let currentToken = createCancellationToken();
+
+			addListener((value) => {
+				latestValue = value;
+				if (timeout) {
+					clearTimeout(timeout);
+					currentToken.cancel();
+				}
+				currentToken = createCancellationToken();
+				const myToken = currentToken;
+
+				timeout = setTimeout(() => {
+					if (!myToken.isCancelled && latestValue !== undefined) {
+						for (const h of debouncedListeners) h(latestValue);
+					}
+				}, ms);
+			});
+
+			return createBaseStream((h) => {
+				debouncedListeners.add(h);
+				return () => debouncedListeners.delete(h);
+			});
+		},
+
+		throttle: (ms): StoreStream<T> => {
+			const throttledListeners = new Set<(value: T) => void>();
+			let lastEmitTime = 0;
+
+			addListener((value) => {
+				const now = Date.now();
+				if (now - lastEmitTime >= ms) {
+					lastEmitTime = now;
+					for (const h of throttledListeners) h(value);
+				}
+			});
+
+			return createBaseStream((h) => {
+				throttledListeners.add(h);
+				return () => throttledListeners.delete(h);
+			});
+		},
+
+		takeLatest: <R>(
+			asyncHandler: (value: T, token: CancellationToken) => Promise<R>
+		): StoreStream<R> => {
+			const latestListeners = new Set<(value: R) => void>();
+			let currentToken = createCancellationToken();
+
+			addListener((value) => {
+				currentToken.cancel();
+				currentToken = createCancellationToken();
+				const myToken = currentToken;
+
+				asyncHandler(value, myToken)
+					.then((result) => {
+						if (!myToken.isCancelled) {
+							for (const h of latestListeners) h(result);
+						}
+					})
+					.catch(() => {});
+			});
+
+			return createBaseStream((h) => {
+				latestListeners.add(h);
+				return () => latestListeners.delete(h);
+			});
+		},
+	};
+};
+
+// Build store property stream
+export const createStoreStream = <T, K extends keyof T>(
+	store: Store<T>,
+	key: K
+): StoreStream<T[K]> => {
+	const listeners = new Set<(value: T[K]) => void>();
+	let lastValue: T[K] = (store.getSnapshot() as Record<string, unknown>)[
+		key as string
+	] as T[K];
+
+	store.subscribe(() => {
+		const snapshot = store.getSnapshot() as Record<string, unknown>;
+		const newValue = snapshot[key as string] as T[K];
+		if (newValue !== lastValue) {
+			lastValue = newValue;
+			for (const listener of listeners) {
+				listener(newValue);
+			}
+		}
+	});
+
+	return createBaseStream((handler) => {
+		listeners.add(handler);
+		return () => listeners.delete(handler);
+	});
+};
+
+// Observe entire store stream
+export const streamAll = <T>(
+	store: Store<T>
+): StoreStream<ReturnType<Store<T>['getSnapshot']>> => {
+	const listeners = new Set<
+		(value: ReturnType<Store<T>['getSnapshot']>) => void
+	>();
+
+	store.subscribe(() => {
+		const snapshot = store.getSnapshot();
+		for (const listener of listeners) {
+			listener(snapshot);
+		}
+	});
+
+	return createBaseStream((handler) => {
+		listeners.add(handler);
+		return () => listeners.delete(handler);
+	});
+};

package/src/registry/index.ts

@@ -0,0 +1,60 @@
+/**
+ * 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 type { Store } from '../core/types.js';
+import { getStoreConfig } from '../config/index.js';
+import { StoreNotFoundError } from '../errors.js';
+
+const stores = new Map<string, Store<unknown>>();
+
+// Register store instance
+export const registerStore = <T>(name: string, store: Store<T>): void => {
+	if (stores.has(name) && getStoreConfig().debug) {
+		// eslint-disable-next-line no-console
+		console.warn(`[store] Overwriting existing store: ${name}`);
+	}
+	stores.set(name, store as Store<unknown>);
+};
+
+// Access registered store
+export const getStore = <T>(name: string): Store<T> => {
+	const store = stores.get(name);
+	if (!store) {
+		throw new StoreNotFoundError({ name });
+	}
+	return store as Store<T>;
+};
+
+// Detect registered store
+export const hasStore = (name: string): boolean => stores.has(name);
+
+// Remove registered store
+export const removeStore = (name: string): boolean => stores.delete(name);
+
+// Reset store registry
+export const clearStores = (): void => {
+	stores.clear();
+};
+
+// Access store names
+export const getStoreNames = (): string[] => Array.from(stores.keys());

package/src/validation/index.ts

@@ -0,0 +1,33 @@
+/**
+ * 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.
+ */
+
+export {
+	validateState,
+	validateStateAsync,
+	createValidatedSetter,
+	createFieldValidator,
+	createSafeFieldSetter,
+	type StateSchema,
+	type ValidationResult,
+} from './schema.js';

package/src/validation/schema.ts

@@ -0,0 +1,142 @@
+/**
+ * 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, Schema, Duration, Predicate } from 'effect';
+import { TimeoutError } from '../errors.js';
+import { DEFAULT_TIMEOUT_MS } from '../config/constants.js';
+
+// State validation schema type
+export type StateSchema<T> = Schema.Schema<T, T>;
+
+// Validation check result
+export interface ValidationResult<T> {
+	success: boolean;
+	data: T | null;
+	errors: string[];
+}
+
+// Validate state synchronously
+export const validateState = <T>(
+	schema: StateSchema<T>,
+	state: unknown
+): ValidationResult<T> => {
+	const result = Effect.runSync(
+		Schema.decodeUnknown(schema)(state).pipe(
+			Effect.map((data) => ({
+				success: true as const,
+				data,
+				errors: [] as string[],
+			})),
+			Effect.catchAll((error) =>
+				Effect.succeed({
+					success: false as const,
+					data: null,
+					errors: [String(error)],
+				})
+			)
+		)
+	);
+	return result;
+};
+
+// Validate state asynchronously
+export const validateStateAsync = <T>(
+	schema: StateSchema<T>,
+	state: unknown,
+	timeoutMs = DEFAULT_TIMEOUT_MS
+): Promise<ValidationResult<T>> => {
+	return Effect.runPromise(
+		Schema.decodeUnknown(schema)(state).pipe(
+			Effect.map((data) => ({
+				success: true as const,
+				data,
+				errors: [] as string[],
+			})),
+			Effect.timeoutFail({
+				duration: Duration.millis(timeoutMs),
+				onTimeout: () => new TimeoutError({ ms: timeoutMs }),
+			}),
+			Effect.catchAll((error) =>
+				Effect.succeed({
+					success: false as const,
+					data: null,
+					errors: [
+						error instanceof TimeoutError
+							? `Validation timed out after ${String(timeoutMs)}ms`
+							: String(error),
+					],
+				})
+			)
+		)
+	);
+};
+
+// Build validated state setter
+export const createValidatedSetter = <T extends Record<string, unknown>>(
+	schema: StateSchema<T>,
+	onValid: (state: T) => void,
+	onInvalid?: (errors: string[]) => void
+): ((state: unknown) => boolean) => {
+	return (state: unknown): boolean => {
+		const result = validateState(schema, state);
+		if (result.success && result.data) {
+			onValid(result.data);
+			return true;
+		}
+		if (Predicate.isNotNullable(onInvalid)) {
+			onInvalid(result.errors);
+		}
+		return false;
+	};
+};
+
+// Build field validator
+export const createFieldValidator = <T>(
+	schema: Schema.Schema<T, T>
+): ((value: unknown) => T) => {
+	return (value: unknown): T => {
+		return Effect.runSync(Schema.decodeUnknown(schema)(value));
+	};
+};
+
+// Build safe field setter
+export const createSafeFieldSetter = <T>(
+	schema: Schema.Schema<T, T>,
+	setter: (value: T) => void
+): ((value: unknown) => boolean) => {
+	return (value: unknown): boolean => {
+		const result = Effect.runSync(
+			Schema.decodeUnknown(schema)(value).pipe(
+				Effect.map((decoded) => {
+					setter(decoded);
+					return true;
+				}),
+				Effect.catchAll(() => Effect.succeed(false))
+			)
+		);
+		return result;
+	};
+};
+
+export { Schema };