@autumnsgrove/groveengine 0.4.12 → 0.6.1

package/dist/server/services/__mocks__/cloudflare.js

@@ -0,0 +1,470 @@
+/**
+ * Mock implementations for Cloudflare services (D1, KV, R2)
+ * Used for testing the service abstraction layer
+ */
+import { vi } from 'vitest';
+/**
+ * Creates a mock D1 database with in-memory storage
+ */
+export function createMockD1() {
+    const tables = new Map();
+    const createStatement = (sql) => {
+        let boundParams = [];
+        const statement = {
+            bind: (...params) => {
+                boundParams = params;
+                return statement;
+            },
+            first: vi.fn(async () => {
+                const result = await statement.all();
+                return result.results[0] ?? null;
+            }),
+            all: vi.fn(async () => {
+                const result = executeSql(sql, boundParams, tables);
+                return {
+                    results: result.results,
+                    success: result.success,
+                    meta: result.meta
+                };
+            }),
+            run: vi.fn(async () => {
+                return executeSql(sql, boundParams, tables);
+            }),
+            raw: vi.fn(async () => {
+                const result = await statement.all();
+                return result.results.map((row) => Object.values(row));
+            })
+        };
+        return statement;
+    };
+    const db = {
+        _tables: tables,
+        prepare: vi.fn((sql) => createStatement(sql)),
+        batch: vi.fn(async (statements) => {
+            const results = [];
+            for (const stmt of statements) {
+                results.push(await stmt.run());
+            }
+            return results;
+        }),
+        exec: vi.fn(async (sql) => {
+            // Simple exec - runs raw SQL
+            return { count: 1, duration: 0 };
+        }),
+        dump: vi.fn(async () => new ArrayBuffer(0)),
+        withSession: vi.fn(() => createMockD1Session(tables))
+    };
+    return db;
+}
+/**
+ * Creates a mock D1 session (for read replication testing)
+ */
+function createMockD1Session(tables) {
+    const createStatement = (sql) => {
+        let boundParams = [];
+        const statement = {
+            bind: (...params) => {
+                boundParams = params;
+                return statement;
+            },
+            first: vi.fn(async () => {
+                const result = await statement.all();
+                return result.results[0] ?? null;
+            }),
+            all: vi.fn(async () => {
+                const result = executeSql(sql, boundParams, tables);
+                return {
+                    results: result.results,
+                    success: result.success,
+                    meta: result.meta
+                };
+            }),
+            run: vi.fn(async () => {
+                return executeSql(sql, boundParams, tables);
+            }),
+            raw: vi.fn(async () => {
+                const result = await statement.all();
+                return result.results.map((row) => Object.values(row));
+            })
+        };
+        return statement;
+    };
+    return {
+        prepare: vi.fn((sql) => createStatement(sql))
+    };
+}
+/**
+ * Simple SQL parser/executor for mocking
+ * Supports basic SELECT, INSERT, UPDATE, DELETE operations
+ */
+function executeSql(sql, params, tables) {
+    const normalizedSql = sql.trim().toUpperCase();
+    let paramIndex = 0;
+    const getNextParam = () => params[paramIndex++];
+    // Extract table name from SQL
+    const tableMatch = sql.match(/(?:FROM|INTO|UPDATE)\s+(\w+)/i);
+    const tableName = tableMatch?.[1]?.toLowerCase() ?? 'unknown';
+    // Ensure table exists
+    if (!tables.has(tableName)) {
+        tables.set(tableName, []);
+    }
+    const tableData = tables.get(tableName);
+    if (normalizedSql.startsWith('SELECT')) {
+        // Handle SELECT queries
+        const whereMatch = sql.match(/WHERE\s+(.+?)(?:\s+ORDER|\s+LIMIT|$)/i);
+        let results = [...tableData];
+        if (whereMatch) {
+            results = filterRows(results, whereMatch[1], params);
+        }
+        // Handle LIMIT
+        const limitMatch = sql.match(/LIMIT\s+(\d+)/i);
+        if (limitMatch) {
+            results = results.slice(0, parseInt(limitMatch[1], 10));
+        }
+        return {
+            results,
+            success: true,
+            meta: {
+                changes: 0,
+                duration: 1,
+                last_row_id: 0,
+                rows_read: results.length,
+                rows_written: 0
+            }
+        };
+    }
+    if (normalizedSql.startsWith('INSERT')) {
+        // Handle INSERT queries
+        const columnsMatch = sql.match(/\(([^)]+)\)\s+VALUES/i);
+        const columns = columnsMatch?.[1]?.split(',').map((c) => c.trim()) ?? [];
+        const row = {};
+        for (const col of columns) {
+            row[col] = getNextParam();
+        }
+        tableData.push(row);
+        return {
+            results: [],
+            success: true,
+            meta: {
+                changes: 1,
+                duration: 1,
+                last_row_id: tableData.length,
+                rows_read: 0,
+                rows_written: 1
+            }
+        };
+    }
+    if (normalizedSql.startsWith('UPDATE')) {
+        // Handle UPDATE queries
+        const setMatch = sql.match(/SET\s+(.+?)\s+WHERE/i);
+        const whereMatch = sql.match(/WHERE\s+(.+)$/i);
+        if (!setMatch || !whereMatch) {
+            return {
+                results: [],
+                success: false,
+                meta: { changes: 0, duration: 1, last_row_id: 0, rows_read: 0, rows_written: 0 }
+            };
+        }
+        // Parse SET clause
+        const setClauses = setMatch[1].split(',').map((s) => s.trim());
+        const updates = {};
+        for (const clause of setClauses) {
+            const [col] = clause.split('=').map((s) => s.trim());
+            updates[col] = getNextParam();
+        }
+        // Find and update matching rows
+        let changes = 0;
+        const whereValue = getNextParam();
+        for (const row of tableData) {
+            // Simple WHERE id = ? matching
+            if (whereMatch[1].includes('id = ?') && row.id === whereValue) {
+                Object.assign(row, updates);
+                changes++;
+            }
+        }
+        return {
+            results: [],
+            success: true,
+            meta: {
+                changes,
+                duration: 1,
+                last_row_id: 0,
+                rows_read: changes,
+                rows_written: changes
+            }
+        };
+    }
+    if (normalizedSql.startsWith('DELETE')) {
+        // Handle DELETE queries
+        const whereMatch = sql.match(/WHERE\s+(.+)$/i);
+        if (!whereMatch) {
+            const changes = tableData.length;
+            tables.set(tableName, []);
+            return {
+                results: [],
+                success: true,
+                meta: { changes, duration: 1, last_row_id: 0, rows_read: 0, rows_written: changes }
+            };
+        }
+        const initialLength = tableData.length;
+        const filtered = filterRows(tableData, whereMatch[1], params, true);
+        tables.set(tableName, filtered);
+        const changes = initialLength - filtered.length;
+        return {
+            results: [],
+            success: true,
+            meta: {
+                changes,
+                duration: 1,
+                last_row_id: 0,
+                rows_read: 0,
+                rows_written: changes
+            }
+        };
+    }
+    // Default fallback
+    return {
+        results: [],
+        success: true,
+        meta: { changes: 0, duration: 1, last_row_id: 0, rows_read: 0, rows_written: 0 }
+    };
+}
+/**
+ * Simple row filtering for WHERE clauses
+ */
+function filterRows(rows, whereClause, params, invert = false) {
+    // Very simple WHERE parsing - supports "column = ?" patterns
+    const conditions = whereClause.split(/\s+AND\s+/i);
+    let paramIndex = 0;
+    return rows.filter((row) => {
+        let matches = true;
+        for (const condition of conditions) {
+            const match = condition.match(/(\w+)\s*=\s*\?/);
+            if (match) {
+                const col = match[1];
+                const value = params[paramIndex++];
+                if (row[col] !== value) {
+                    matches = false;
+                    break;
+                }
+            }
+        }
+        return invert ? !matches : matches;
+    });
+}
+/**
+ * Creates a mock KV namespace with in-memory storage
+ */
+export function createMockKV() {
+    const store = new Map();
+    const kv = {
+        _store: store,
+        get: vi.fn(async (key, options) => {
+            const entry = store.get(key);
+            if (!entry)
+                return null;
+            // Check expiration
+            if (entry.expiresAt && entry.expiresAt < Date.now()) {
+                store.delete(key);
+                return null;
+            }
+            return entry.value;
+        }),
+        getWithMetadata: vi.fn(async (key) => {
+            const entry = store.get(key);
+            if (!entry)
+                return { value: null, metadata: null };
+            if (entry.expiresAt && entry.expiresAt < Date.now()) {
+                store.delete(key);
+                return { value: null, metadata: null };
+            }
+            return { value: entry.value, metadata: entry.metadata ?? null };
+        }),
+        put: vi.fn(async (key, value, options) => {
+            const entry = { value };
+            if (options?.expirationTtl) {
+                entry.expiresAt = Date.now() + options.expirationTtl * 1000;
+            }
+            if (options?.metadata) {
+                entry.metadata = options.metadata;
+            }
+            store.set(key, entry);
+        }),
+        delete: vi.fn(async (key) => {
+            store.delete(key);
+        }),
+        list: vi.fn(async (options) => {
+            const keys = [];
+            const prefix = options?.prefix ?? '';
+            const limit = options?.limit ?? 1000;
+            for (const [key, entry] of store.entries()) {
+                if (key.startsWith(prefix)) {
+                    // Skip expired entries
+                    if (entry.expiresAt && entry.expiresAt < Date.now()) {
+                        continue;
+                    }
+                    keys.push({
+                        name: key,
+                        expiration: entry.expiresAt ? Math.floor(entry.expiresAt / 1000) : undefined,
+                        metadata: entry.metadata
+                    });
+                    if (keys.length >= limit)
+                        break;
+                }
+            }
+            return {
+                keys,
+                list_complete: keys.length < limit,
+                cursor: keys.length >= limit ? 'next-cursor' : undefined
+            };
+        })
+    };
+    return kv;
+}
+/**
+ * Creates a mock R2 bucket with in-memory storage
+ */
+export function createMockR2() {
+    const objects = new Map();
+    const createR2Object = (key, entry) => ({
+        key,
+        version: 'v1',
+        size: entry.size,
+        etag: entry.etag,
+        httpEtag: `"${entry.etag}"`,
+        uploaded: entry.uploaded,
+        httpMetadata: entry.httpMetadata,
+        customMetadata: entry.customMetadata,
+        range: undefined,
+        checksums: {
+            toJSON: () => ({})
+        },
+        storageClass: 'Standard',
+        writeHttpMetadata: vi.fn()
+    });
+    const createR2ObjectBody = (key, entry) => ({
+        ...createR2Object(key, entry),
+        body: new ReadableStream({
+            start(controller) {
+                controller.enqueue(new Uint8Array(entry.body));
+                controller.close();
+            }
+        }),
+        bodyUsed: false,
+        arrayBuffer: vi.fn(async () => entry.body),
+        text: vi.fn(async () => new TextDecoder().decode(entry.body)),
+        json: vi.fn(async () => JSON.parse(new TextDecoder().decode(entry.body))),
+        blob: vi.fn(async () => new Blob([entry.body]))
+    });
+    const bucket = {
+        _objects: objects,
+        head: vi.fn(async (key) => {
+            const entry = objects.get(key);
+            if (!entry)
+                return null;
+            return createR2Object(key, entry);
+        }),
+        get: vi.fn(async (key) => {
+            const entry = objects.get(key);
+            if (!entry)
+                return null;
+            return createR2ObjectBody(key, entry);
+        }),
+        put: vi.fn(async (key, value, options) => {
+            let body;
+            if (value instanceof ArrayBuffer) {
+                body = value;
+            }
+            else if (typeof value === 'string') {
+                body = new TextEncoder().encode(value).buffer;
+            }
+            else if (value instanceof Blob) {
+                body = await value.arrayBuffer();
+            }
+            else {
+                // ReadableStream
+                const reader = value.getReader();
+                const chunks = [];
+                let done = false;
+                while (!done) {
+                    const { value: chunk, done: isDone } = await reader.read();
+                    if (chunk)
+                        chunks.push(chunk);
+                    done = isDone;
+                }
+                const totalLength = chunks.reduce((sum, c) => sum + c.length, 0);
+                const result = new Uint8Array(totalLength);
+                let offset = 0;
+                for (const chunk of chunks) {
+                    result.set(chunk, offset);
+                    offset += chunk.length;
+                }
+                body = result.buffer;
+            }
+            const etag = `etag-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+            const entry = {
+                body,
+                httpMetadata: options?.httpMetadata,
+                customMetadata: options?.customMetadata,
+                etag,
+                uploaded: new Date(),
+                size: body.byteLength
+            };
+            objects.set(key, entry);
+            return createR2Object(key, entry);
+        }),
+        delete: vi.fn(async (key) => {
+            const keys = Array.isArray(key) ? key : [key];
+            for (const k of keys) {
+                objects.delete(k);
+            }
+        }),
+        list: vi.fn(async (options) => {
+            const prefix = options?.prefix ?? '';
+            const limit = options?.limit ?? 1000;
+            const result = [];
+            for (const [key, entry] of objects.entries()) {
+                if (key.startsWith(prefix)) {
+                    result.push(createR2Object(key, entry));
+                    if (result.length >= limit)
+                        break;
+                }
+            }
+            return {
+                objects: result,
+                truncated: result.length >= limit,
+                cursor: result.length >= limit ? 'next-cursor' : undefined,
+                delimitedPrefixes: []
+            };
+        }),
+        createMultipartUpload: vi.fn(),
+        resumeMultipartUpload: vi.fn()
+    };
+    return bucket;
+}
+// ============================================================================
+// Test Utilities
+// ============================================================================
+/**
+ * Seed a mock D1 database with initial data
+ */
+export function seedMockD1(db, tableName, rows) {
+    db._tables.set(tableName, [...rows]);
+}
+/**
+ * Clear all data from a mock D1 database
+ */
+export function clearMockD1(db) {
+    db._tables.clear();
+}
+/**
+ * Advance time for KV expiration testing
+ */
+export function advanceKVTime(kv, ms) {
+    // Modify expiration times to simulate time passage
+    for (const [key, entry] of kv._store.entries()) {
+        if (entry.expiresAt) {
+            entry.expiresAt -= ms;
+        }
+    }
+}

package/dist/server/services/cache.d.ts

@@ -0,0 +1,170 @@
+/**
+ * Cache Service - KV Key-Value Store Abstraction
+ *
+ * Provides typed caching operations with:
+ * - Automatic JSON serialization/deserialization
+ * - TTL management with sensible defaults
+ * - Namespace prefixing to avoid key collisions
+ * - Compute-if-missing pattern (getOrSet)
+ * - Specific error types for debugging
+ */
+export interface CacheOptions {
+    /** Time-to-live in seconds (default: 3600 = 1 hour) */
+    ttl?: number;
+    /** Namespace prefix for the key */
+    namespace?: string;
+}
+export interface GetOrSetOptions<T> extends CacheOptions {
+    /** Function to compute the value if not in cache */
+    compute: () => Promise<T>;
+    /** Skip cache read and always compute fresh (useful for cache invalidation) */
+    forceRefresh?: boolean;
+}
+export declare class CacheError extends Error {
+    readonly code: CacheErrorCode;
+    readonly cause?: unknown | undefined;
+    constructor(message: string, code: CacheErrorCode, cause?: unknown | undefined);
+}
+export type CacheErrorCode = 'GET_FAILED' | 'SET_FAILED' | 'DELETE_FAILED' | 'SERIALIZATION_ERROR' | 'COMPUTE_FAILED' | 'KV_UNAVAILABLE';
+/**
+ * Get a value from the cache
+ *
+ * @example
+ * ```ts
+ * const user = await cache.get<User>(kv, 'user:123');
+ * if (user) {
+ *   console.log(user.name);
+ * }
+ * ```
+ */
+export declare function get<T>(kv: KVNamespace, key: string, options?: Pick<CacheOptions, 'namespace'>): Promise<T | null>;
+/**
+ * Set a value in the cache
+ *
+ * @example
+ * ```ts
+ * await cache.set(kv, 'user:123', userData, { ttl: 3600 });
+ * ```
+ */
+export declare function set<T>(kv: KVNamespace, key: string, value: T, options?: CacheOptions): Promise<void>;
+/**
+ * Delete a value from the cache
+ *
+ * @example
+ * ```ts
+ * await cache.del(kv, 'user:123');
+ * ```
+ */
+export declare function del(kv: KVNamespace, key: string, options?: Pick<CacheOptions, 'namespace'>): Promise<void>;
+/**
+ * Get a value from cache, or compute and store it if missing
+ * This is the most common caching pattern.
+ *
+ * NOTE: Cache writes are fire-and-forget for better response time. This means
+ * subsequent requests might miss the cache briefly until the write completes.
+ * Use `getOrSetSync` if you need to ensure the value is cached before returning
+ * (e.g., when cache consistency is critical).
+ *
+ * @example
+ * ```ts
+ * const user = await cache.getOrSet(kv, `user:${id}`, {
+ *   ttl: 3600,
+ *   compute: async () => {
+ *     return await db.queryOne<User>('SELECT * FROM users WHERE id = ?', [id]);
+ *   }
+ * });
+ * ```
+ */
+export declare function getOrSet<T>(kv: KVNamespace, key: string, options: GetOrSetOptions<T>): Promise<T>;
+/**
+ * Get a value from cache, or compute and store it (awaiting the cache write)
+ * Use this when you need to ensure the value is cached before returning.
+ *
+ * @example
+ * ```ts
+ * const user = await cache.getOrSetSync(kv, `user:${id}`, {
+ *   ttl: 3600,
+ *   compute: async () => fetchUserFromApi(id)
+ * });
+ * ```
+ */
+export declare function getOrSetSync<T>(kv: KVNamespace, key: string, options: GetOrSetOptions<T>): Promise<T>;
+/**
+ * Delete multiple keys at once
+ *
+ * @example
+ * ```ts
+ * await cache.delMany(kv, ['user:1', 'user:2', 'user:3']);
+ * ```
+ */
+export declare function delMany(kv: KVNamespace, keys: string[], options?: Pick<CacheOptions, 'namespace'>): Promise<void>;
+/**
+ * Delete all keys matching a pattern (by listing and deleting)
+ * Note: KV list operations have pagination limits
+ *
+ * @example
+ * ```ts
+ * await cache.delByPrefix(kv, 'user:'); // Deletes all user cache entries
+ * ```
+ */
+export declare function delByPrefix(kv: KVNamespace, prefix: string, options?: Pick<CacheOptions, 'namespace'>): Promise<number>;
+/**
+ * Check if a key exists in the cache
+ *
+ * @example
+ * ```ts
+ * if (await cache.has(kv, 'user:123')) {
+ *   // Key exists
+ * }
+ * ```
+ */
+export declare function has(kv: KVNamespace, key: string, options?: Pick<CacheOptions, 'namespace'>): Promise<boolean>;
+/**
+ * Touch a key (refresh its TTL without changing value)
+ *
+ * @example
+ * ```ts
+ * await cache.touch(kv, 'session:abc', { ttl: 3600 });
+ * ```
+ */
+export declare function touch(kv: KVNamespace, key: string, options?: CacheOptions): Promise<boolean>;
+/**
+ * Simple rate limiting using KV
+ * Returns true if the action is allowed, false if rate limited
+ *
+ * LIMITATION: This implementation has a read-modify-write pattern that is not
+ * atomic. Under high concurrency, multiple requests may exceed the limit slightly.
+ * For precise rate limiting in high-traffic scenarios, consider using Cloudflare
+ * Durable Objects or an external rate limiting service.
+ *
+ * For most use cases (login attempts, API throttling), this is sufficient as
+ * slight over-allowance is acceptable.
+ *
+ * @example
+ * ```ts
+ * // Allow 5 login attempts per 15 minutes
+ * const result = await cache.rateLimit(kv, `login:${email}`, {
+ *   limit: 5,
+ *   windowSeconds: 900
+ * });
+ * if (!result.allowed) {
+ *   throw new Error('Too many attempts');
+ * }
+ * ```
+ */
+export declare function rateLimit(kv: KVNamespace, key: string, options: {
+    /** Maximum number of attempts allowed */
+    limit: number;
+    /** Time window in seconds */
+    windowSeconds: number;
+    /** Namespace for the rate limit key */
+    namespace?: string;
+}): Promise<{
+    allowed: boolean;
+    remaining: number;
+    resetAt: number;
+}>;
+export declare const CACHE_DEFAULTS: {
+    readonly TTL_SECONDS: 3600;
+    readonly KEY_PREFIX: "grove";
+};