ff-serv 0.1.10 → 0.1.11

package/src/cache/cache.test.ts

@@ -0,0 +1,461 @@
+import { it } from '@effect/vitest';
+import { Clock, Duration, Effect, Option, Ref, TestClock } from 'effect';
+import { describe, expect } from 'vitest';
+import type { CacheAdapter, CacheEntry } from './adapter.js';
+import { Cache } from './cache.js';
+
+function makeTestAdapter<Key, Value>() {
+	const store = new Map<string, CacheEntry<Value>>();
+	const adapter: CacheAdapter<Key, Value> = {
+		get: (key) =>
+			Effect.sync(() => {
+				const entry = store.get(JSON.stringify(key));
+				return entry ? Option.some(entry) : Option.none();
+			}),
+		set: (key, entry, _ttl) =>
+			Effect.sync(() => {
+				store.set(JSON.stringify(key), entry);
+			}),
+		remove: (key) =>
+			Effect.sync(() => {
+				store.delete(JSON.stringify(key));
+			}),
+		removeAll: Effect.sync(() => {
+			store.clear();
+		}),
+	};
+	return { adapter, store };
+}
+
+describe('Cache', () => {
+	describe('core', () => {
+		it.effect('calls lookup and returns value', () =>
+			Effect.gen(function* () {
+				const cache = yield* Cache.make({
+					ttl: Duration.minutes(5),
+					lookup: (id: number) => Effect.succeed(`user-${id}`),
+				});
+				const value = yield* cache.get(1);
+				expect(value).toBe('user-1');
+			}),
+		);
+
+		it.effect('caches lookup result', () =>
+			Effect.gen(function* () {
+				const callCount = yield* Ref.make(0);
+				const cache = yield* Cache.make({
+					ttl: Duration.minutes(5),
+					lookup: (id: number) =>
+						Ref.update(callCount, (n) => n + 1).pipe(
+							Effect.map(() => `user-${id}`),
+						),
+				});
+				yield* cache.get(1);
+				yield* cache.get(1);
+				expect(yield* Ref.get(callCount)).toBe(1);
+			}),
+		);
+
+		it.effect('calls lookup for different keys', () =>
+			Effect.gen(function* () {
+				const callCount = yield* Ref.make(0);
+				const cache = yield* Cache.make({
+					ttl: Duration.minutes(5),
+					lookup: (id: number) =>
+						Ref.update(callCount, (n) => n + 1).pipe(
+							Effect.map(() => `user-${id}`),
+						),
+				});
+				yield* cache.get(1);
+				yield* cache.get(2);
+				expect(yield* Ref.get(callCount)).toBe(2);
+			}),
+		);
+
+		it.effect('expires entries after TTL', () =>
+			Effect.gen(function* () {
+				const callCount = yield* Ref.make(0);
+				const cache = yield* Cache.make({
+					ttl: Duration.minutes(5),
+					lookup: (id: number) =>
+						Ref.update(callCount, (n) => n + 1).pipe(
+							Effect.map(() => `user-${id}`),
+						),
+				});
+				yield* cache.get(1);
+				yield* TestClock.adjust(Duration.minutes(6));
+				yield* cache.get(1);
+				expect(yield* Ref.get(callCount)).toBe(2);
+			}),
+		);
+
+		it.effect('propagates lookup errors', () =>
+			Effect.gen(function* () {
+				const cache = yield* Cache.make({
+					ttl: Duration.minutes(5),
+					lookup: (_id: number) => Effect.fail('lookup-error' as const),
+				});
+				const result = yield* cache.get(1).pipe(Effect.either);
+				expect(result._tag).toBe('Left');
+			}),
+		);
+
+		it.effect('invalidates a single key', () =>
+			Effect.gen(function* () {
+				const callCount = yield* Ref.make(0);
+				const cache = yield* Cache.make({
+					ttl: Duration.minutes(5),
+					lookup: (id: number) =>
+						Ref.update(callCount, (n) => n + 1).pipe(
+							Effect.map(() => `user-${id}`),
+						),
+				});
+				yield* cache.get(1);
+				yield* cache.invalidate(1);
+				yield* cache.get(1);
+				expect(yield* Ref.get(callCount)).toBe(2);
+			}),
+		);
+
+		it.effect('invalidates all keys', () =>
+			Effect.gen(function* () {
+				const callCount = yield* Ref.make(0);
+				const cache = yield* Cache.make({
+					ttl: Duration.minutes(5),
+					lookup: (id: number) =>
+						Ref.update(callCount, (n) => n + 1).pipe(
+							Effect.map(() => `user-${id}`),
+						),
+				});
+				yield* cache.get(1);
+				yield* cache.get(2);
+				yield* cache.invalidateAll;
+				yield* cache.get(1);
+				yield* cache.get(2);
+				expect(yield* Ref.get(callCount)).toBe(4);
+			}),
+		);
+	});
+
+	describe('SWR', () => {
+		it.effect('returns stale value within SWR window', () =>
+			Effect.gen(function* () {
+				const callCount = yield* Ref.make(0);
+				const cache = yield* Cache.make({
+					ttl: Duration.minutes(5),
+					swr: Duration.minutes(10),
+					lookup: (id: number) =>
+						Effect.gen(function* () {
+							yield* Ref.update(callCount, (n) => n + 1);
+							const count = yield* Ref.get(callCount);
+							return `user-${id}-v${count}`;
+						}),
+				});
+
+				const v1 = yield* cache.get(1);
+				expect(v1).toBe('user-1-v1');
+
+				// Advance past TTL but within SWR window
+				yield* TestClock.adjust(Duration.minutes(7));
+				const v2 = yield* cache.get(1);
+				// Should return stale value immediately
+				expect(v2).toBe('user-1-v1');
+			}),
+		);
+
+		it.effect('triggers background refresh after stale read', () =>
+			Effect.gen(function* () {
+				const callCount = yield* Ref.make(0);
+				const cache = yield* Cache.make({
+					ttl: Duration.minutes(5),
+					swr: Duration.minutes(10),
+					lookup: (id: number) =>
+						Effect.gen(function* () {
+							yield* Ref.update(callCount, (n) => n + 1);
+							const count = yield* Ref.get(callCount);
+							return `user-${id}-v${count}`;
+						}),
+				});
+
+				yield* cache.get(1);
+				yield* TestClock.adjust(Duration.minutes(7));
+
+				// This returns stale but triggers background refresh
+				yield* cache.get(1);
+				// Let the background fiber run
+				yield* Effect.yieldNow();
+				yield* TestClock.adjust(Duration.zero);
+				yield* Effect.yieldNow();
+
+				// Background refresh should have been triggered
+				expect(yield* Ref.get(callCount)).toBe(2);
+			}),
+		);
+
+		it.effect('serves fresh value after background refresh', () =>
+			Effect.gen(function* () {
+				const callCount = yield* Ref.make(0);
+				const cache = yield* Cache.make({
+					ttl: Duration.minutes(5),
+					swr: Duration.minutes(10),
+					lookup: (id: number) =>
+						Effect.gen(function* () {
+							yield* Ref.update(callCount, (n) => n + 1);
+							const count = yield* Ref.get(callCount);
+							return `user-${id}-v${count}`;
+						}),
+				});
+
+				yield* cache.get(1);
+				yield* TestClock.adjust(Duration.minutes(7));
+				yield* cache.get(1);
+				yield* Effect.yieldNow();
+				yield* TestClock.adjust(Duration.zero);
+				yield* Effect.yieldNow();
+
+				// Next get should return the refreshed value
+				const v3 = yield* cache.get(1);
+				expect(v3).toBe('user-1-v2');
+			}),
+		);
+
+		it.effect('does not serve stale when swr is not set', () =>
+			Effect.gen(function* () {
+				const callCount = yield* Ref.make(0);
+				const cache = yield* Cache.make({
+					ttl: Duration.minutes(5),
+					lookup: (id: number) =>
+						Effect.gen(function* () {
+							yield* Ref.update(callCount, (n) => n + 1);
+							const count = yield* Ref.get(callCount);
+							return `user-${id}-v${count}`;
+						}),
+				});
+
+				yield* cache.get(1);
+				yield* TestClock.adjust(Duration.minutes(6));
+
+				// No SWR — should block and call lookup again
+				const v2 = yield* cache.get(1);
+				expect(v2).toBe('user-1-v2');
+				expect(yield* Ref.get(callCount)).toBe(2);
+			}),
+		);
+
+		it.effect('blocks for fresh value past SWR window', () =>
+			Effect.gen(function* () {
+				const callCount = yield* Ref.make(0);
+				const cache = yield* Cache.make({
+					ttl: Duration.minutes(5),
+					swr: Duration.minutes(10),
+					lookup: (id: number) =>
+						Effect.gen(function* () {
+							yield* Ref.update(callCount, (n) => n + 1);
+							const count = yield* Ref.get(callCount);
+							return `user-${id}-v${count}`;
+						}),
+				});
+
+				yield* cache.get(1);
+				// Advance past TTL + SWR window
+				yield* TestClock.adjust(Duration.minutes(16));
+				const v2 = yield* cache.get(1);
+				expect(v2).toBe('user-1-v2');
+				expect(yield* Ref.get(callCount)).toBe(2);
+			}),
+		);
+	});
+
+	describe('dynamic TTL', () => {
+		it.effect('Cache.entry overrides TTL', () =>
+			Effect.gen(function* () {
+				const callCount = yield* Ref.make(0);
+				const cache = yield* Cache.make({
+					ttl: Duration.minutes(5),
+					lookup: (id: number) =>
+						Effect.gen(function* () {
+							yield* Ref.update(callCount, (n) => n + 1);
+							const count = yield* Ref.get(callCount);
+							return Cache.entry(`user-${id}-v${count}`, {
+								ttl: Duration.hours(1),
+							});
+						}),
+				});
+
+				yield* cache.get(1);
+				// Advance past default TTL (5m) but within custom TTL (1h)
+				yield* TestClock.adjust(Duration.minutes(30));
+				yield* cache.get(1);
+				// Should still be cached — custom TTL is 1h
+				expect(yield* Ref.get(callCount)).toBe(1);
+			}),
+		);
+
+		it.effect('Cache.entry overrides SWR', () =>
+			Effect.gen(function* () {
+				const callCount = yield* Ref.make(0);
+				const cache = yield* Cache.make({
+					ttl: Duration.minutes(5),
+					swr: Duration.minutes(10),
+					lookup: (id: number) =>
+						Effect.gen(function* () {
+							yield* Ref.update(callCount, (n) => n + 1);
+							const count = yield* Ref.get(callCount);
+							return Cache.entry(`user-${id}-v${count}`, {
+								ttl: Duration.minutes(1),
+								swr: Duration.minutes(2),
+							});
+						}),
+				});
+
+				yield* cache.get(1);
+				// Advance past custom TTL (1m) but within custom SWR (1m + 2m = 3m)
+				yield* TestClock.adjust(Duration.minutes(2));
+				const stale = yield* cache.get(1);
+				// Should return stale value (SWR active)
+				expect(stale).toBe('user-1-v1');
+			}),
+		);
+
+		it.effect('plain return uses default TTL/SWR', () =>
+			Effect.gen(function* () {
+				const callCount = yield* Ref.make(0);
+				const cache = yield* Cache.make({
+					ttl: Duration.minutes(5),
+					swr: Duration.minutes(10),
+					lookup: (id: number) =>
+						Ref.update(callCount, (n) => n + 1).pipe(
+							Effect.map(() => `user-${id}`),
+						),
+				});
+
+				yield* cache.get(1);
+				// Within default TTL
+				yield* TestClock.adjust(Duration.minutes(3));
+				yield* cache.get(1);
+				expect(yield* Ref.get(callCount)).toBe(1);
+
+				// Past default TTL but within SWR
+				yield* TestClock.adjust(Duration.minutes(4));
+				const stale = yield* cache.get(1);
+				expect(stale).toBe('user-1');
+			}),
+		);
+
+		it.effect('mixed entries use their own TTL', () =>
+			Effect.gen(function* () {
+				const callCountA = yield* Ref.make(0);
+				const callCountB = yield* Ref.make(0);
+				const cache = yield* Cache.make({
+					ttl: Duration.minutes(5),
+					lookup: (id: string) =>
+						Effect.gen(function* () {
+							if (id === 'a') {
+								yield* Ref.update(callCountA, (n) => n + 1);
+								return `val-a`;
+							}
+							yield* Ref.update(callCountB, (n) => n + 1);
+							return Cache.entry(`val-b`, { ttl: Duration.hours(1) });
+						}),
+				});
+
+				yield* cache.get('a');
+				yield* cache.get('b');
+
+				// Advance past default TTL but within custom TTL
+				yield* TestClock.adjust(Duration.minutes(6));
+
+				yield* cache.get('a'); // should re-fetch (past 5m TTL)
+				yield* cache.get('b'); // should still be cached (within 1h TTL)
+
+				expect(yield* Ref.get(callCountA)).toBe(2);
+				expect(yield* Ref.get(callCountB)).toBe(1);
+			}),
+		);
+	});
+
+	describe('adapter', () => {
+		it.effect('uses adapter data on cold start without calling lookup', () =>
+			Effect.gen(function* () {
+				const { adapter, store } = makeTestAdapter<number, string>();
+				const now = yield* Clock.currentTimeMillis;
+				store.set(JSON.stringify(1), { value: 'cached-user-1', storedAt: now });
+
+				const callCount = yield* Ref.make(0);
+				const cache = yield* Cache.make({
+					ttl: Duration.minutes(5),
+					lookup: (id: number) =>
+						Ref.update(callCount, (n) => n + 1).pipe(
+							Effect.map(() => `user-${id}`),
+						),
+					adapter,
+				});
+
+				const value = yield* cache.get(1);
+				expect(value).toBe('cached-user-1');
+				expect(yield* Ref.get(callCount)).toBe(0);
+			}),
+		);
+
+		it.effect(
+			'SWR refresh calls lookup instead of short-circuiting with adapter',
+			() =>
+				Effect.gen(function* () {
+					const { adapter } = makeTestAdapter<number, string>();
+					const callCount = yield* Ref.make(0);
+					const cache = yield* Cache.make({
+						ttl: Duration.minutes(5),
+						swr: Duration.minutes(10),
+						lookup: (id: number) =>
+							Effect.gen(function* () {
+								yield* Ref.update(callCount, (n) => n + 1);
+								const count = yield* Ref.get(callCount);
+								return `user-${id}-v${count}`;
+							}),
+						adapter,
+					});
+
+					yield* cache.get(1);
+					yield* TestClock.adjust(Duration.minutes(7));
+
+					// Trigger SWR refresh
+					yield* cache.get(1);
+					yield* Effect.yieldNow();
+					yield* TestClock.adjust(Duration.zero);
+					yield* Effect.yieldNow();
+
+					// lookup must have been called twice (initial + refresh)
+					expect(yield* Ref.get(callCount)).toBe(2);
+				}),
+		);
+
+		it.effect('adapter updated after SWR refresh', () =>
+			Effect.gen(function* () {
+				const { adapter, store } = makeTestAdapter<number, string>();
+				const callCount = yield* Ref.make(0);
+				const cache = yield* Cache.make({
+					ttl: Duration.minutes(5),
+					swr: Duration.minutes(10),
+					lookup: (id: number) =>
+						Effect.gen(function* () {
+							yield* Ref.update(callCount, (n) => n + 1);
+							const count = yield* Ref.get(callCount);
+							return `user-${id}-v${count}`;
+						}),
+					adapter,
+				});
+
+				yield* cache.get(1);
+				yield* TestClock.adjust(Duration.minutes(7));
+
+				yield* cache.get(1);
+				yield* Effect.yieldNow();
+				yield* TestClock.adjust(Duration.zero);
+				yield* Effect.yieldNow();
+
+				const entry = store.get(JSON.stringify(1));
+				expect(entry?.value).toBe('user-1-v2');
+			}),
+		);
+	});
+});

package/src/cache/cache.ts

@@ -0,0 +1,184 @@
+import {
+	Clock,
+	Duration,
+	Effect,
+	Cache as EffectCache,
+	Exit,
+	Option,
+} from 'effect';
+import type { CacheAdapter, CacheEntry } from './adapter.js';
+
+// Bundles value with resolved TTL/SWR so the SWR check at read time uses per-entry durations
+type CacheValue<Value> = {
+	readonly value: Value;
+	readonly ttlMs: number;
+	readonly swrMs: number;
+};
+
+export type CacheInstance<Key, Value, Error> = {
+	readonly get: (key: Key) => Effect.Effect<Value, Error>;
+	readonly invalidate: (key: Key) => Effect.Effect<void>;
+	readonly invalidateAll: Effect.Effect<void>;
+};
+
+export namespace Cache {
+	export type Entry<Value> = {
+		readonly _tag: 'CacheEntry';
+		readonly value: Value;
+		readonly ttl: Duration.DurationInput;
+		readonly swr?: Duration.DurationInput;
+	};
+
+	export function entry<Value>(
+		value: Value,
+		opts: { ttl: Duration.DurationInput; swr?: Duration.DurationInput },
+	): Entry<Value> {
+		return { _tag: 'CacheEntry', value, ttl: opts.ttl, swr: opts.swr };
+	}
+
+	export type LookupResult<Value> = Value | Entry<Value>;
+
+	export function make<Key, Value, Error = never, R = never>(opts: {
+		ttl: Duration.DurationInput;
+		swr?: Duration.DurationInput;
+		lookup: (key: Key) => Effect.Effect<LookupResult<Value>, Error, R>;
+		adapter?: CacheAdapter<Key, Value>;
+	}): Effect.Effect<CacheInstance<Key, Value, Error>, never, R> {
+		return Effect.gen(function* () {
+			const adapter = opts.adapter;
+			const defaultTtlMs = Duration.toMillis(Duration.decode(opts.ttl));
+			const defaultSwrMs = opts.swr
+				? Duration.toMillis(Duration.decode(opts.swr))
+				: 0;
+			const capacity = adapter?.capacity ?? Number.MAX_SAFE_INTEGER;
+
+			// Safe without synchronization — no yield points between has() and add() (cooperative scheduling)
+			const refreshingKeys = new Set<string>();
+
+			// makeWith uses `timeToLive: (exit) => Duration` — the lookup stores CacheValue
+			// so timeToLive can extract the total window (ttl + swr) from the exit result
+			const inner = yield* EffectCache.makeWith({
+				capacity,
+				lookup: (key: Key) =>
+					Effect.gen(function* () {
+						const isRefreshing = refreshingKeys.has(JSON.stringify(key));
+
+						if (adapter && !isRefreshing) {
+							const cached = yield* adapter.get(key);
+							if (Option.isSome(cached)) {
+								const now = yield* Clock.currentTimeMillis;
+								const age = now - cached.value.storedAt;
+								const totalWindow = defaultTtlMs + defaultSwrMs;
+								if (age < totalWindow) {
+									// Adjust remaining TTL/SWR for elapsed age so SWR triggers at correct real-world time
+									return {
+										value: cached.value.value,
+										ttlMs: Math.max(0, defaultTtlMs - age),
+										swrMs: Math.max(
+											0,
+											defaultSwrMs - Math.max(0, age - defaultTtlMs),
+										),
+									} satisfies CacheValue<Value>;
+								}
+							}
+						}
+
+						const result = yield* opts.lookup(key);
+						const cv = resolveLookupResult(result, defaultTtlMs, defaultSwrMs);
+
+						if (adapter) {
+							const now = yield* Clock.currentTimeMillis;
+							yield* adapter.set(
+								key,
+								{ value: cv.value, storedAt: now } satisfies CacheEntry<Value>,
+								Duration.millis(cv.ttlMs + cv.swrMs),
+							);
+						}
+
+						return cv;
+					}),
+				timeToLive: (exit) => {
+					if (Exit.isSuccess(exit)) {
+						return Duration.millis(exit.value.ttlMs + exit.value.swrMs);
+					}
+					return Duration.zero;
+				},
+			});
+
+			const get = (key: Key) =>
+				Effect.gen(function* () {
+					const cv = yield* inner.get(key);
+
+					if (cv.swrMs > 0) {
+						const stats = yield* inner.entryStats(key);
+						if (Option.isSome(stats)) {
+							const now = yield* Clock.currentTimeMillis;
+							const age = now - stats.value.loadedMillis;
+							if (age > cv.ttlMs) {
+								const keyStr = JSON.stringify(key);
+								if (!refreshingKeys.has(keyStr)) {
+									refreshingKeys.add(keyStr);
+									// refresh() recomputes without invalidating, so stale value remains available during recomputation
+									yield* Effect.forkDaemon(
+										inner.refresh(key).pipe(
+											Effect.ensuring(
+												Effect.sync(() => {
+													refreshingKeys.delete(keyStr);
+												}),
+											),
+											Effect.ignore,
+										),
+									);
+								}
+							}
+						}
+					}
+
+					return cv.value;
+				});
+
+			const invalidate = (key: Key) =>
+				Effect.gen(function* () {
+					yield* inner.invalidate(key);
+					if (adapter) yield* adapter.remove(key);
+				});
+
+			const invalidateAll = Effect.gen(function* () {
+				yield* inner.invalidateAll;
+				if (adapter) yield* adapter.removeAll;
+			});
+
+			return { get, invalidate, invalidateAll } satisfies CacheInstance<
+				Key,
+				Value,
+				Error
+			>;
+		});
+	}
+}
+
+function isCacheEntry<Value>(
+	result: Cache.LookupResult<Value>,
+): result is Cache.Entry<Value> {
+	return (
+		typeof result === 'object' &&
+		result !== null &&
+		'_tag' in result &&
+		(result as Cache.Entry<Value>)._tag === 'CacheEntry'
+	);
+}
+
+function resolveLookupResult<Value>(
+	result: Cache.LookupResult<Value>,
+	defaultTtlMs: number,
+	defaultSwrMs: number,
+): CacheValue<Value> {
+	if (isCacheEntry(result)) {
+		return {
+			value: result.value,
+			ttlMs: Duration.toMillis(Duration.decode(result.ttl)),
+			swrMs: result.swr ? Duration.toMillis(Duration.decode(result.swr)) : 0,
+		};
+	}
+	return { value: result, ttlMs: defaultTtlMs, swrMs: defaultSwrMs };
+}

package/src/cli/commands/db/pull.ts

@@ -1,6 +1,6 @@
 import * as cli from '@effect/cli';
 import * as platform from '@effect/platform';
-import { Effect, Option, Cause } from 'effect';
+import { type Cause, Effect, Option } from 'effect';
 import inquirer from 'inquirer';
 import postgres from 'postgres';
 import { loadConfig } from '../../config/index.js';
@@ -35,10 +35,7 @@ const parsePostgresUrl = (url: string): DatabaseInfo => {
 	};
 };
 
-const confirmDatabaseUrls = (
-	sourceUrl: string | null,
-	targetUrl: string,
-) =>
+const confirmDatabaseUrls = (sourceUrl: string | null, targetUrl: string) =>
 	Effect.gen(function* () {
 		const target = parsePostgresUrl(targetUrl);
 
@@ -170,9 +167,7 @@ const truncateAllTables = (
 				`Truncating ${tables.length} table(s) in schema "${schema}"...`,
 			);
 
-			const tableNames = tables
-				.map((t) => `"${schema}"."${t}"`)
-				.join(', ');
+			const tableNames = tables.map((t) => `"${schema}"."${t}"`).join(', ');
 
 			yield* Effect.tryPromise(() =>
 				conn.unsafe(`TRUNCATE ${tableNames} RESTART IDENTITY CASCADE`),
@@ -282,10 +277,7 @@ export const pullCommand = cli.Command.make(
 
 				const sourceUrl = yield* getDatabaseUrlFromSource(source);
 
-				const urlsConfirmed = yield* confirmDatabaseUrls(
-					sourceUrl,
-					targetUrl,
-				);
+				const urlsConfirmed = yield* confirmDatabaseUrls(sourceUrl, targetUrl);
 				if (!urlsConfirmed) {
 					yield* Effect.log('Operation cancelled');
 					return;
@@ -321,9 +313,7 @@ export const pullCommand = cli.Command.make(
 			);
 
 			if (!Option.isSome(fromDump)) {
-				const shouldCleanup = yield* promptCleanupDump(
-					dumpState.filePath,
-				);
+				const shouldCleanup = yield* promptCleanupDump(dumpState.filePath);
 				if (shouldCleanup) {
 					const fs = yield* platform.FileSystem.FileSystem;
 					yield* fs.remove(dumpState.filePath, { recursive: true });