@effuse/store 1.0.5 → 1.0.6

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@effuse/store",
-	"version": "1.0.5",
+	"version": "1.0.6",
 	"description": "A functional state management system built on Effect-ts. It offers typed, robust global state handling designed to scale with your application's logic.",
 	"author": "Chris M. Pérez",
 	"license": "MIT",
@@ -34,7 +34,8 @@
 		"build": "tsup",
 		"dev": "tsup --watch",
 		"lint": "eslint src",
-		"typecheck": "tsc --noEmit"
+		"typecheck": "tsc --noEmit",
+		"test": "vitest run"
 	},
 	"keywords": [
 		"state-management",
@@ -48,18 +49,18 @@
 		"node": ">=22.14.0"
 	},
 	"peerDependencies": {
-		"@effuse/core": "1.2.1"
+		"@effuse/core": "1.2.2"
 	},
 	"dependencies": {
-		"effect": "^3.19.17"
+		"effect": "^3.20.0"
 	},
 	"devDependencies": {
 		"@effect/eslint-plugin": "^0.3.2",
-		"@types/node": "^25.2.3",
-		"@effuse/core": "1.2.1",
-		"eslint": "^10.0.0",
+		"@types/node": "^25.5.0",
+		"@effuse/core": "1.2.2",
+		"eslint": "^10.0.3",
 		"tsup": "^8.5.1",
 		"typescript": "^5.9.3",
-		"vitest": "^4.0.18"
+		"vitest": "^4.1.0"
 	}
 }

package/src/__tests__/actions/useConcurrency.test.ts

@@ -0,0 +1,275 @@
+import { vi, describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { Effect } from 'effect';
+import type { ConcurrencyStrategy } from '../../actions/useConcurrency.js';
+import { useConcurrency } from '../../actions/useConcurrency.js';
+
+describe('useConcurrency', () => {
+	beforeEach(() => {
+		vi.useFakeTimers();
+	});
+
+	afterEach(() => {
+		vi.restoreAllMocks();
+	});
+
+	describe('execution strategies', () => {
+		it('should execute all actions concurrently when using "merge" strategy', async () => {
+			const executedArgs: number[] = [];
+			const action = (id: number) =>
+				Effect.sync(() => {
+					executedArgs.push(id);
+				});
+
+			const wrappedAction = useConcurrency(action, { strategy: 'merge' });
+
+			wrappedAction(1);
+			wrappedAction(2);
+			wrappedAction(3);
+
+			// sync effects run quickly via runFork
+			await Promise.resolve(); // wait for microtasks
+			expect(executedArgs).toEqual([1, 2, 3]);
+		});
+
+		it('should interrupt previous action when using "switch" strategy', async () => {
+			const completedArgs: number[] = [];
+			const action = (id: number) =>
+				Effect.gen(function* () {
+					yield* Effect.sleep(100);
+					completedArgs.push(id);
+				});
+
+			const wrappedAction = useConcurrency(action, { strategy: 'switch' });
+
+			wrappedAction(1);
+			await vi.advanceTimersByTimeAsync(50);
+			wrappedAction(2); // Should interrupt 1
+			await vi.advanceTimersByTimeAsync(50);
+			wrappedAction(3); // Should interrupt 2
+			await vi.advanceTimersByTimeAsync(100); // 3 finishes
+
+			expect(completedArgs).toEqual([3]);
+		});
+
+		it('should ignore new actions while current is running when using "exhaust" strategy', async () => {
+			const completedArgs: number[] = [];
+			const action = (id: number) =>
+				Effect.gen(function* () {
+					yield* Effect.sleep(100);
+					completedArgs.push(id);
+				});
+
+			const wrappedAction = useConcurrency(action, { strategy: 'exhaust' });
+
+			wrappedAction(1);
+			await vi.advanceTimersByTimeAsync(50);
+			wrappedAction(2); // Should be ignored
+			await vi.advanceTimersByTimeAsync(100); // 1 finishes running
+			wrappedAction(3); // runs after 1 completes
+			await vi.advanceTimersByTimeAsync(100); // 3 finishes
+
+			expect(completedArgs).toEqual([1, 3]);
+		});
+
+		it('should execute actions sequentially when using "concat" strategy', async () => {
+			const completedArgs: number[] = [];
+			const action = (id: number) =>
+				Effect.gen(function* () {
+					yield* Effect.sleep(50);
+					completedArgs.push(id);
+				});
+
+			const wrappedAction = useConcurrency(action, { strategy: 'concat' });
+
+			wrappedAction(1);
+			wrappedAction(2);
+			wrappedAction(3);
+
+			await vi.advanceTimersByTimeAsync(50); // 1 finishes
+			// flush Effect microtasks
+			await Promise.resolve();
+			expect(completedArgs).toContain(1);
+			expect(completedArgs).not.toContain(2);
+
+			await vi.advanceTimersByTimeAsync(50); // 2 finishes
+			await Promise.resolve();
+			expect(completedArgs).toContain(2);
+			expect(completedArgs).not.toContain(3);
+
+			await vi.advanceTimersByTimeAsync(50); // 3 finishes
+			await Promise.resolve();
+			expect(completedArgs).toContain(3);
+			
+			expect(completedArgs).toEqual([1, 2, 3]);
+		});
+	});
+
+	describe('Debounce and Throttle', () => {
+		it('should delay execution until debounceMs has elapsed since last call', async () => {
+			const executedArgs: number[] = [];
+			const action = (id: number) =>
+				Effect.sync(() => {
+					executedArgs.push(id);
+				});
+
+			const wrappedAction = useConcurrency(action, {
+				strategy: 'merge',
+				debounceMs: 100,
+			});
+
+			wrappedAction(1);
+			await vi.advanceTimersByTimeAsync(50);
+			wrappedAction(2);
+			await vi.advanceTimersByTimeAsync(50);
+			wrappedAction(3); // Resets timer
+
+			expect(executedArgs).toEqual([]); // Not executed yet
+
+			await vi.advanceTimersByTimeAsync(100); // wait for debounce
+			await Promise.resolve();
+			
+			expect(executedArgs).toEqual([3]);
+		});
+
+		it('should limit execution rate based on throttleMs', async () => {
+			const executedArgs: number[] = [];
+			const action = (id: number) =>
+				Effect.sync(() => {
+					executedArgs.push(id);
+				});
+
+			const wrappedAction = useConcurrency(action, {
+				strategy: 'merge',
+				throttleMs: 100,
+			});
+
+			wrappedAction(1); // Executed immediately
+			wrappedAction(2); // Ignored
+			
+			await vi.advanceTimersByTimeAsync(50);
+			wrappedAction(3); // Still ignored (50ms < 100ms)
+
+			await vi.advanceTimersByTimeAsync(60); // Total 110ms elapsed
+			wrappedAction(4); // Executed
+
+			await Promise.resolve();
+
+			expect(executedArgs).toEqual([1, 4]);
+		});
+
+		it('should prioritize throttle over debounce if both are provided', async () => {
+			const executedArgs: number[] = [];
+			const action = (id: number) =>
+				Effect.sync(() => {
+					executedArgs.push(id);
+				});
+
+			const wrappedAction = useConcurrency(action, {
+				strategy: 'merge',
+				throttleMs: 100,
+				debounceMs: 50,
+			});
+
+			wrappedAction(1); // Throttle allows, debounce delays by 50ms
+			
+			await vi.advanceTimersByTimeAsync(60); // 1 gets executed
+			await Promise.resolve();
+			expect(executedArgs).toEqual([1]);
+
+			// We are at 60ms since last execution. Throttle is 100ms.
+			wrappedAction(2); // Ignored by throttle
+			
+			await vi.advanceTimersByTimeAsync(100);
+			
+			expect(executedArgs).toEqual([1]); // throttle drops 2 entirely
+		});
+	});
+
+	describe('Edge cases and boundary values', () => {
+		it('should handle zero debounce time same as no debounce', async () => {
+			const executedArgs: number[] = [];
+			const action = (id: number) =>
+				Effect.sync(() => {
+					executedArgs.push(id);
+				});
+
+			const wrappedAction = useConcurrency(action, {
+				strategy: 'merge',
+				debounceMs: 0,
+			});
+
+			wrappedAction(1);
+			wrappedAction(2);
+
+			await Promise.resolve();
+			expect(executedArgs).toEqual([1, 2]);
+		});
+
+		it('should handle negative debounce time same as no debounce', async () => {
+			const executedArgs: number[] = [];
+			const action = (id: number) =>
+				Effect.sync(() => {
+					executedArgs.push(id);
+				});
+
+			const wrappedAction = useConcurrency(action, {
+				strategy: 'merge',
+				debounceMs: -100,
+			});
+
+			wrappedAction(1);
+			
+			await Promise.resolve();
+			expect(executedArgs).toEqual([1]);
+		});
+	});
+});
+
+describe('Generative Permutation Matrix (500 cases)', () => {
+	const strategies: ConcurrencyStrategy[] = ['switch', 'exhaust', 'merge', 'concat'];
+	const debounceTimes = [undefined, 0, -5, 10, 50];
+	const throttleTimes = [undefined, 0, -5, 10, 50];
+	const callCounts = [1, 2, 3, 5, 10];
+
+	const permutations: Array<
+		[ConcurrencyStrategy, number | undefined, number | undefined, number]
+	> = [];
+
+	for (const strategy of strategies) {
+		for (const debounceMs of debounceTimes) {
+			for (const throttleMs of throttleTimes) {
+				for (const calls of callCounts) {
+					permutations.push([strategy, debounceMs, throttleMs, calls]);
+				}
+			}
+		}
+	}
+
+	it.each(permutations)(
+		'Strategy: %s, Debounce: %s, Throttle: %s, Calls: %d',
+		async (strategy, debounceMs, throttleMs, calls) => {
+			const executed: number[] = [];
+			const action = (id: number) =>
+				Effect.sync(() => {
+					executed.push(id);
+				});
+
+			const wrapped = useConcurrency(action, {
+				strategy,
+				debounceMs,
+				throttleMs,
+			});
+
+			for (let i = 0; i < calls; i++) {
+				wrapped(i);
+				await vi.advanceTimersByTimeAsync(1);
+			}
+
+			await vi.runAllTimersAsync();
+			await Promise.resolve();
+
+			expect(Array.isArray(executed)).toBe(true);
+			expect(executed.length).toBeLessThanOrEqual(calls);
+		}
+	);
+});

package/src/actions/async.ts

@@ -24,7 +24,7 @@
 
 import { Effect, Duration, Schedule } from 'effect';
 import type { Store } from '../core/types.js';
-import { createCancellationToken } from './cancellation.js';
+
 import { runWithAbortSignal } from './cancellation.js';
 import {
 	DEFAULT_RETRY_INITIAL_DELAY_MS,
@@ -33,7 +33,6 @@ import {
 } from '../config/constants.js';
 import {
 	ActionNotFoundError,
-	CancellationError,
 	TimeoutError,
 } from '../errors.js';
 
@@ -195,133 +194,7 @@ export const withRetry = <A extends unknown[], R>(
 	};
 };
 
-export const takeLatest = <A extends unknown[], R>(
-	fn: ActionFn<A, R>
-): CancellableAction<A, R> => {
-	let pending = false;
-	let currentToken = createCancellationToken();
-	let callId = 0;
-
-	const action = async (...args: A): Promise<R> => {
-		currentToken.cancel();
-		currentToken = createCancellationToken();
-		const myToken = currentToken;
-		const myCallId = ++callId;
-
-		pending = true;
-
-		try {
-			const result = await fn(...args);
-
-			if (myToken.isCancelled || myCallId !== callId) {
-				throw new CancellationError({ message: 'Superseded by newer call' });
-			}
-
-			return result;
-		} finally {
-			if (myCallId === callId) {
-				pending = false;
-			}
-		}
-	};
-
-	Object.defineProperty(action, 'pending', {
-		get: () => pending,
-		enumerable: true,
-	});
-
-	Object.defineProperty(action, 'cancel', {
-		value: () => {
-			currentToken.cancel();
-			pending = false;
-		},
-		enumerable: true,
-	});
-
-	return action as CancellableAction<A, R>;
-};
-
-export const takeFirst = <A extends unknown[], R>(
-	fn: ActionFn<A, R>
-): AsyncAction<A, R | undefined> => {
-	let pending = false;
-
-	const action = async (...args: A): Promise<R | undefined> => {
-		if (pending) {
-			return undefined;
-		}
 
-		pending = true;
-		try {
-			return await fn(...args);
-		} finally {
-			pending = false;
-		}
-	};
-
-	Object.defineProperty(action, 'pending', {
-		get: () => pending,
-		enumerable: true,
-	});
-
-	return action as AsyncAction<A, R | undefined>;
-};
-
-export const debounceAction = <A extends unknown[], R>(
-	fn: ActionFn<A, R>,
-	delayMs: number
-): ((...args: A) => Promise<R>) => {
-	let timeout: ReturnType<typeof setTimeout> | null = null;
-	let currentToken = createCancellationToken();
-
-	return (...args: A): Promise<R> => {
-		if (timeout) {
-			clearTimeout(timeout);
-			currentToken.cancel();
-		}
-
-		currentToken = createCancellationToken();
-		const myToken = currentToken;
-
-		return new Promise((resolve, reject) => {
-			timeout = setTimeout(() => {
-				if (myToken.isCancelled) return;
-
-				Promise.resolve(fn(...args))
-					.then((result) => {
-						if (!myToken.isCancelled) resolve(result);
-					})
-					.catch((error: unknown) => {
-						if (!myToken.isCancelled) reject(error as Error);
-					});
-			}, delayMs);
-		});
-	};
-};
-
-export const throttleAction = <A extends unknown[], R>(
-	fn: ActionFn<A, R>,
-	intervalMs: number
-): ((...args: A) => Promise<R | undefined>) => {
-	let lastCallTime = 0;
-	let pending = false;
-
-	return async (...args: A): Promise<R | undefined> => {
-		const now = Date.now();
-		if (now - lastCallTime < intervalMs || pending) {
-			return undefined;
-		}
-
-		lastCallTime = now;
-		pending = true;
-
-		try {
-			return await fn(...args);
-		} finally {
-			pending = false;
-		}
-	};
-};
 
 export const dispatch = <T>(
 	store: Store<T>,

package/src/actions/index.ts

@@ -30,10 +30,7 @@ export {
 	withTimeout,
 	withRetry,
 	withAbortSignal,
-	takeLatest,
-	takeFirst,
-	debounceAction,
-	throttleAction,
+
 	type ActionResult,
 	type AsyncAction,
 	type CancellableAction,
@@ -46,3 +43,9 @@ export {
 	type CancellationToken,
 	type CancellationScope,
 } from './cancellation.js';
+
+export {
+	useConcurrency,
+	type ConcurrencyStrategy,
+	type ConcurrencyOptions,
+} from './useConcurrency.js';

package/src/actions/useConcurrency.ts

@@ -0,0 +1,137 @@
+/**
+ * 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, Fiber, Queue } from 'effect';
+
+export type ConcurrencyStrategy = 'switch' | 'exhaust' | 'merge' | 'concat';
+
+export interface ConcurrencyOptions {
+	strategy?: ConcurrencyStrategy;
+	debounceMs?: number;
+	throttleMs?: number;
+}
+
+export function useConcurrency<A extends unknown[], R, E = never>(
+	action: (...args: A) => Effect.Effect<R, E>,
+	options: ConcurrencyOptions = {}
+): (...args: A) => void {
+	const { strategy = 'switch', debounceMs, throttleMs } = options;
+
+	let runningFiber: Fiber.RuntimeFiber<unknown, unknown> | null = null;
+	let debounceTimeout: ReturnType<typeof setTimeout> | null = null;
+	let lastCallTime = 0;
+
+	// Dedicated unbounded queue for sequential 'concat' strategy
+	const queue =
+		strategy === 'concat' ? Effect.runSync(Queue.unbounded<A>()) : null;
+
+	if (queue) {
+		// Spin up a background worker to consume the queue sequentially
+		Effect.runFork(
+			Effect.forever(
+				Effect.gen(function* () {
+					const args = yield* Queue.take(queue);
+					// Catch all errors so the worker doesn't die on failure
+					yield* Effect.catchAll(action(...args), () => Effect.void);
+				})
+			)
+		);
+	}
+
+	const execute = (...args: A) => {
+		switch (strategy) {
+			case 'switch':
+				if (runningFiber) {
+					Effect.runFork(Fiber.interrupt(runningFiber));
+				}
+				runningFiber = Effect.runFork(
+					Effect.match(action(...args), {
+						onFailure: () => {
+							runningFiber = null;
+						},
+						onSuccess: () => {
+							runningFiber = null;
+						},
+					})
+				);
+				break;
+
+			case 'exhaust':
+				if (runningFiber) {
+					return; // Ignore execution if already running
+				}
+				runningFiber = Effect.runFork(
+					Effect.match(action(...args), {
+						onFailure: () => {
+							runningFiber = null;
+						},
+						onSuccess: () => {
+							runningFiber = null;
+						},
+					})
+				);
+				break;
+
+			case 'merge':
+				// Unbounded concurrency: fire and forget
+				Effect.runFork(
+					Effect.catchAll(action(...args), () => Effect.void)
+				);
+				break;
+
+			case 'concat':
+				// Sequential execution via the background queue
+				if (queue) {
+					Effect.runFork(Queue.offer(queue, args));
+				}
+				break;
+		}
+	};
+
+	return (...args: A) => {
+		const now = Date.now();
+
+		// 1. Evaluate Throttle
+		if (throttleMs !== undefined && throttleMs > 0) {
+			if (now - lastCallTime < throttleMs) {
+				return;
+			}
+			lastCallTime = now;
+		}
+
+		// 2. Evaluate Debounce
+		if (debounceMs !== undefined && debounceMs > 0) {
+			if (debounceTimeout) {
+				clearTimeout(debounceTimeout);
+			}
+			debounceTimeout = setTimeout(() => {
+				execute(...args);
+			}, debounceMs);
+			return;
+		}
+
+		// 3. Fallthrough immediate execution
+		execute(...args);
+	};
+}

package/src/index.ts

@@ -75,10 +75,6 @@ export {
 	withTimeout,
 	withRetry,
 	withAbortSignal,
-	takeLatest,
-	takeFirst,
-	debounceAction,
-	throttleAction,
 	createCancellationToken,
 	createCancellationScope,
 	type ActionResult,
@@ -87,6 +83,9 @@ export {
 	type RetryConfig,
 	type CancellationToken,
 	type CancellationScope,
+	useConcurrency,
+	type ConcurrencyStrategy,
+	type ConcurrencyOptions,
 } from './actions/index.js';
 
 export {

package/src/reactivity/derived.ts

@@ -154,7 +154,7 @@ export const hydrateStores = (serialized: string): Effect.Effect<void> =>
 				);
 			}
 		},
-		catch: () => new HydrationError({}),
+		catch: () => new HydrationError(),
 	}).pipe(Effect.catchAll(() => Effect.void));
 
 // Hydrate stores synchronously