@sylphx/lens-server 1.11.2 → 2.0.1

package/src/storage/index.ts

@@ -0,0 +1,26 @@
+/**
+ * @sylphx/lens-server - Storage
+ *
+ * Storage adapters for opLog plugin.
+ *
+ * Built-in:
+ * - `memoryStorage()` - In-memory (default, for long-running servers)
+ *
+ * External packages (install separately):
+ * - `@sylphx/lens-storage-redis` - Redis via ioredis
+ * - `@sylphx/lens-storage-upstash` - Upstash Redis HTTP (serverless/edge)
+ * - `@sylphx/lens-storage-vercel-kv` - Vercel KV (Next.js/Vercel)
+ */
+
+// In-memory (default)
+export { memoryStorage } from "./memory.js";
+
+// Types (for implementing custom storage adapters)
+export {
+	DEFAULT_STORAGE_CONFIG,
+	type EmitResult,
+	type OpLogStorage,
+	type OpLogStorageConfig,
+	type StoredEntityState,
+	type StoredPatchEntry,
+} from "./types.js";

package/src/storage/memory.ts

@@ -0,0 +1,279 @@
+/**
+ * @sylphx/lens-server - Memory Storage
+ *
+ * In-memory storage adapter for opLog plugin.
+ * Default storage for long-running servers.
+ *
+ * Features:
+ * - O(1) state and version lookups
+ * - Bounded patch history per entity
+ * - Automatic cleanup of old patches
+ *
+ * Memory: O(entities × maxPatchesPerEntity)
+ */
+
+import type { PatchOperation } from "@sylphx/lens-core";
+import {
+	DEFAULT_STORAGE_CONFIG,
+	type EmitResult,
+	type OpLogStorage,
+	type OpLogStorageConfig,
+	type StoredPatchEntry,
+} from "./types.js";
+
+/**
+ * Entity key for internal storage.
+ */
+type EntityKey = string;
+
+/**
+ * Internal entity state.
+ */
+interface EntityState {
+	data: Record<string, unknown>;
+	version: number;
+	patches: StoredPatchEntry[];
+}
+
+/**
+ * Create entity key from entity type and ID.
+ */
+function makeKey(entity: string, entityId: string): EntityKey {
+	return `${entity}:${entityId}`;
+}
+
+/**
+ * Compute JSON Patch operations between two states.
+ */
+function computePatch(
+	oldState: Record<string, unknown>,
+	newState: Record<string, unknown>,
+): PatchOperation[] {
+	const patch: PatchOperation[] = [];
+	const oldKeys = new Set(Object.keys(oldState));
+	const newKeys = new Set(Object.keys(newState));
+
+	// Additions and replacements
+	for (const key of newKeys) {
+		const oldValue = oldState[key];
+		const newValue = newState[key];
+
+		if (!oldKeys.has(key)) {
+			// New field
+			patch.push({ op: "add", path: `/${key}`, value: newValue });
+		} else if (JSON.stringify(oldValue) !== JSON.stringify(newValue)) {
+			// Changed field
+			patch.push({ op: "replace", path: `/${key}`, value: newValue });
+		}
+	}
+
+	// Deletions
+	for (const key of oldKeys) {
+		if (!newKeys.has(key)) {
+			patch.push({ op: "remove", path: `/${key}` });
+		}
+	}
+
+	return patch;
+}
+
+/**
+ * Hash entity state for change detection.
+ */
+function hashState(state: Record<string, unknown>): string {
+	return JSON.stringify(state);
+}
+
+/**
+ * Create an in-memory storage adapter.
+ *
+ * @example
+ * ```typescript
+ * const storage = memoryStorage();
+ *
+ * // Or with custom config
+ * const storage = memoryStorage({
+ *   maxPatchesPerEntity: 500,
+ *   maxPatchAge: 60000,
+ * });
+ * ```
+ */
+export function memoryStorage(config: OpLogStorageConfig = {}): OpLogStorage {
+	const cfg = { ...DEFAULT_STORAGE_CONFIG, ...config };
+	const entities = new Map<EntityKey, EntityState>();
+	let cleanupTimer: ReturnType<typeof setInterval> | null = null;
+
+	// Start cleanup timer
+	if (cfg.cleanupInterval > 0) {
+		cleanupTimer = setInterval(() => cleanup(), cfg.cleanupInterval);
+	}
+
+	/**
+	 * Cleanup old patches based on age.
+	 */
+	function cleanup(): void {
+		const now = Date.now();
+		const minTimestamp = now - cfg.maxPatchAge;
+
+		for (const state of entities.values()) {
+			// Remove patches older than maxPatchAge
+			state.patches = state.patches.filter((p) => p.timestamp >= minTimestamp);
+		}
+	}
+
+	/**
+	 * Trim patches to maxPatchesPerEntity.
+	 */
+	function trimPatches(state: EntityState): void {
+		if (state.patches.length > cfg.maxPatchesPerEntity) {
+			// Remove oldest patches
+			state.patches = state.patches.slice(-cfg.maxPatchesPerEntity);
+		}
+	}
+
+	return {
+		async emit(entity, entityId, data): Promise<EmitResult> {
+			const key = makeKey(entity, entityId);
+			const existing = entities.get(key);
+			const now = Date.now();
+
+			if (!existing) {
+				// First emit - no previous state
+				const newState: EntityState = {
+					data: { ...data },
+					version: 1,
+					patches: [],
+				};
+
+				// No patch for first emit (full state is sent instead)
+				entities.set(key, newState);
+
+				return {
+					version: 1,
+					patch: null,
+					changed: true,
+				};
+			}
+
+			// Check if state actually changed
+			const oldHash = hashState(existing.data);
+			const newHash = hashState(data);
+
+			if (oldHash === newHash) {
+				return {
+					version: existing.version,
+					patch: null,
+					changed: false,
+				};
+			}
+
+			// Compute patch
+			const patch = computePatch(existing.data, data);
+
+			// Update state
+			const newVersion = existing.version + 1;
+			existing.data = { ...data };
+			existing.version = newVersion;
+
+			// Append patch to log
+			if (patch.length > 0) {
+				existing.patches.push({
+					version: newVersion,
+					patch,
+					timestamp: now,
+				});
+				trimPatches(existing);
+			}
+
+			return {
+				version: newVersion,
+				patch: patch.length > 0 ? patch : null,
+				changed: true,
+			};
+		},
+
+		async getState(entity, entityId): Promise<Record<string, unknown> | null> {
+			const key = makeKey(entity, entityId);
+			const state = entities.get(key);
+			return state ? { ...state.data } : null;
+		},
+
+		async getVersion(entity, entityId): Promise<number> {
+			const key = makeKey(entity, entityId);
+			const state = entities.get(key);
+			return state?.version ?? 0;
+		},
+
+		async getLatestPatch(entity, entityId): Promise<PatchOperation[] | null> {
+			const key = makeKey(entity, entityId);
+			const state = entities.get(key);
+
+			if (!state || state.patches.length === 0) {
+				return null;
+			}
+
+			return state.patches[state.patches.length - 1].patch;
+		},
+
+		async getPatchesSince(entity, entityId, sinceVersion): Promise<PatchOperation[][] | null> {
+			const key = makeKey(entity, entityId);
+			const state = entities.get(key);
+
+			if (!state) {
+				return sinceVersion === 0 ? [] : null;
+			}
+
+			// Already up to date
+			if (sinceVersion >= state.version) {
+				return [];
+			}
+
+			// Find patches since the given version
+			const relevantPatches = state.patches.filter((p) => p.version > sinceVersion);
+
+			if (relevantPatches.length === 0) {
+				// No patches in log - version too old
+				return null;
+			}
+
+			// Verify continuity
+			relevantPatches.sort((a, b) => a.version - b.version);
+
+			// First patch must be sinceVersion + 1
+			if (relevantPatches[0].version !== sinceVersion + 1) {
+				return null;
+			}
+
+			// Check for gaps
+			for (let i = 1; i < relevantPatches.length; i++) {
+				if (relevantPatches[i].version !== relevantPatches[i - 1].version + 1) {
+					return null;
+				}
+			}
+
+			return relevantPatches.map((p) => p.patch);
+		},
+
+		async has(entity, entityId): Promise<boolean> {
+			const key = makeKey(entity, entityId);
+			return entities.has(key);
+		},
+
+		async delete(entity, entityId): Promise<void> {
+			const key = makeKey(entity, entityId);
+			entities.delete(key);
+		},
+
+		async clear(): Promise<void> {
+			entities.clear();
+		},
+
+		async dispose(): Promise<void> {
+			if (cleanupTimer) {
+				clearInterval(cleanupTimer);
+				cleanupTimer = null;
+			}
+			entities.clear();
+		},
+	};
+}

package/src/storage/types.ts

@@ -0,0 +1,205 @@
+/**
+ * @sylphx/lens-server - Storage Types
+ *
+ * Storage adapter interface for opLog plugin.
+ * Enables serverless support by abstracting state/version/patch storage.
+ */
+
+import type { PatchOperation } from "@sylphx/lens-core";
+
+/**
+ * Entity state stored in the operation log.
+ */
+export interface StoredEntityState {
+	/** Canonical state data */
+	data: Record<string, unknown>;
+	/** Current version */
+	version: number;
+	/** Timestamp of last update */
+	updatedAt: number;
+}
+
+/**
+ * Operation log entry stored in storage.
+ */
+export interface StoredPatchEntry {
+	/** Version this patch creates */
+	version: number;
+	/** Patch operations */
+	patch: PatchOperation[];
+	/** Timestamp when patch was created */
+	timestamp: number;
+}
+
+/**
+ * Result from emit operation.
+ */
+export interface EmitResult {
+	/** New version after emit */
+	version: number;
+	/** Computed patch (null if first emit) */
+	patch: PatchOperation[] | null;
+	/** Whether state actually changed */
+	changed: boolean;
+}
+
+/**
+ * Storage adapter interface for opLog.
+ *
+ * Implementations:
+ * - `memoryStorage()` - In-memory (default, for long-running servers)
+ * - `redisStorage()` - Redis/Upstash (for serverless)
+ * - `kvStorage()` - Cloudflare KV, Vercel KV
+ *
+ * All methods are async to support external storage.
+ *
+ * @example
+ * ```typescript
+ * // Default (in-memory)
+ * const app = createApp({
+ *   router,
+ *   plugins: [opLog()],
+ * });
+ *
+ * // With Redis for serverless
+ * const app = createApp({
+ *   router,
+ *   plugins: [opLog({
+ *     storage: redisStorage({ url: process.env.REDIS_URL }),
+ *   })],
+ * });
+ * ```
+ */
+export interface OpLogStorage {
+	/**
+	 * Emit new state for an entity.
+	 * This is an atomic operation that:
+	 * 1. Computes patch from previous state (if exists)
+	 * 2. Stores new state with incremented version
+	 * 3. Appends patch to operation log
+	 *
+	 * @param entity - Entity type name
+	 * @param entityId - Entity ID
+	 * @param data - New state data
+	 * @returns Emit result with version, patch, and changed flag
+	 */
+	emit(entity: string, entityId: string, data: Record<string, unknown>): Promise<EmitResult>;
+
+	/**
+	 * Get current canonical state for an entity.
+	 *
+	 * @param entity - Entity type name
+	 * @param entityId - Entity ID
+	 * @returns State data or null if not found
+	 */
+	getState(entity: string, entityId: string): Promise<Record<string, unknown> | null>;
+
+	/**
+	 * Get current version for an entity.
+	 * Returns 0 if entity doesn't exist.
+	 *
+	 * @param entity - Entity type name
+	 * @param entityId - Entity ID
+	 * @returns Current version (0 if not found)
+	 */
+	getVersion(entity: string, entityId: string): Promise<number>;
+
+	/**
+	 * Get the latest patch for an entity.
+	 * Returns null if no patches available.
+	 *
+	 * @param entity - Entity type name
+	 * @param entityId - Entity ID
+	 * @returns Latest patch or null
+	 */
+	getLatestPatch(entity: string, entityId: string): Promise<PatchOperation[] | null>;
+
+	/**
+	 * Get all patches since a given version.
+	 * Used for reconnection to bring client up to date.
+	 *
+	 * @param entity - Entity type name
+	 * @param entityId - Entity ID
+	 * @param sinceVersion - Client's current version
+	 * @returns Array of patches (one per version), or null if too old
+	 */
+	getPatchesSince(
+		entity: string,
+		entityId: string,
+		sinceVersion: number,
+	): Promise<PatchOperation[][] | null>;
+
+	/**
+	 * Check if entity exists in storage.
+	 *
+	 * @param entity - Entity type name
+	 * @param entityId - Entity ID
+	 * @returns True if entity exists
+	 */
+	has(entity: string, entityId: string): Promise<boolean>;
+
+	/**
+	 * Delete an entity from storage.
+	 * Removes state, version, and all patches.
+	 *
+	 * @param entity - Entity type name
+	 * @param entityId - Entity ID
+	 */
+	delete(entity: string, entityId: string): Promise<void>;
+
+	/**
+	 * Clear all data from storage.
+	 * Used for testing.
+	 */
+	clear(): Promise<void>;
+
+	/**
+	 * Dispose storage resources.
+	 * Called when shutting down.
+	 */
+	dispose?(): Promise<void>;
+}
+
+/**
+ * Configuration for operation log storage.
+ */
+export interface OpLogStorageConfig {
+	/**
+	 * Maximum number of patches to keep per entity.
+	 * Older patches are evicted when limit is reached.
+	 * @default 1000
+	 */
+	maxPatchesPerEntity?: number;
+
+	/**
+	 * Maximum age of patches in milliseconds.
+	 * Patches older than this are evicted.
+	 * @default 300000 (5 minutes)
+	 */
+	maxPatchAge?: number;
+
+	/**
+	 * Cleanup interval in milliseconds.
+	 * Set to 0 to disable automatic cleanup.
+	 * @default 60000 (1 minute)
+	 */
+	cleanupInterval?: number;
+
+	/**
+	 * Maximum retries for emit operations on version conflict.
+	 * Only applies to external storage (Redis, Upstash, Vercel KV).
+	 * Set to 0 to disable retries (fail immediately on conflict).
+	 * @default 3
+	 */
+	maxRetries?: number;
+}
+
+/**
+ * Default storage configuration.
+ */
+export const DEFAULT_STORAGE_CONFIG: Required<OpLogStorageConfig> = {
+	maxPatchesPerEntity: 1000,
+	maxPatchAge: 5 * 60 * 1000, // 5 minutes
+	cleanupInterval: 60 * 1000, // 1 minute
+	maxRetries: 3,
+};