@autumnsgrove/groveengine 0.4.12 → 0.6.1

package/dist/server/services/cache.js

@@ -0,0 +1,335 @@
+/**
+ * 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
+ */
+// ============================================================================
+// Errors
+// ============================================================================
+export class CacheError extends Error {
+    code;
+    cause;
+    constructor(message, code, cause) {
+        super(message);
+        this.code = code;
+        this.cause = cause;
+        this.name = 'CacheError';
+    }
+}
+// ============================================================================
+// Configuration
+// ============================================================================
+/** Default TTL: 1 hour */
+const DEFAULT_TTL_SECONDS = 3600;
+/** Key prefix to avoid collisions with other KV users */
+const KEY_PREFIX = 'grove';
+// ============================================================================
+// Key Management
+// ============================================================================
+/**
+ * Build a namespaced cache key
+ * @example buildKey('user', '123') => 'grove:user:123'
+ */
+function buildKey(namespace, key) {
+    const parts = [KEY_PREFIX];
+    if (namespace)
+        parts.push(namespace);
+    parts.push(key);
+    return parts.join(':');
+}
+// ============================================================================
+// Cache Operations
+// ============================================================================
+/**
+ * Get a value from the cache
+ *
+ * @example
+ * ```ts
+ * const user = await cache.get<User>(kv, 'user:123');
+ * if (user) {
+ *   console.log(user.name);
+ * }
+ * ```
+ */
+export async function get(kv, key, options) {
+    const fullKey = buildKey(options?.namespace, key);
+    try {
+        const value = await kv.get(fullKey, 'text');
+        if (value === null) {
+            return null;
+        }
+        try {
+            return JSON.parse(value);
+        }
+        catch {
+            // If it's not JSON, return as-is (for string values)
+            return value;
+        }
+    }
+    catch (err) {
+        throw new CacheError(`Failed to get key: ${fullKey}`, 'GET_FAILED', err);
+    }
+}
+/**
+ * Set a value in the cache
+ *
+ * @example
+ * ```ts
+ * await cache.set(kv, 'user:123', userData, { ttl: 3600 });
+ * ```
+ */
+export async function set(kv, key, value, options) {
+    const fullKey = buildKey(options?.namespace, key);
+    const ttl = options?.ttl ?? DEFAULT_TTL_SECONDS;
+    let serialized;
+    try {
+        serialized = typeof value === 'string' ? value : JSON.stringify(value);
+    }
+    catch (err) {
+        throw new CacheError('Failed to serialize value', 'SERIALIZATION_ERROR', err);
+    }
+    try {
+        await kv.put(fullKey, serialized, {
+            expirationTtl: ttl
+        });
+    }
+    catch (err) {
+        throw new CacheError(`Failed to set key: ${fullKey}`, 'SET_FAILED', err);
+    }
+}
+/**
+ * Delete a value from the cache
+ *
+ * @example
+ * ```ts
+ * await cache.del(kv, 'user:123');
+ * ```
+ */
+export async function del(kv, key, options) {
+    const fullKey = buildKey(options?.namespace, key);
+    try {
+        await kv.delete(fullKey);
+    }
+    catch (err) {
+        throw new CacheError(`Failed to delete key: ${fullKey}`, 'DELETE_FAILED', err);
+    }
+}
+/**
+ * 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 async function getOrSet(kv, key, options) {
+    const { compute, forceRefresh, ...cacheOptions } = options;
+    // Try to get from cache first (unless forcing refresh)
+    if (!forceRefresh) {
+        const cached = await get(kv, key, cacheOptions);
+        if (cached !== null) {
+            return cached;
+        }
+    }
+    // Compute the value
+    let value;
+    try {
+        value = await compute();
+    }
+    catch (err) {
+        throw new CacheError('Failed to compute value', 'COMPUTE_FAILED', err);
+    }
+    // Store in cache (don't await - fire and forget for performance)
+    // Errors here are logged but don't fail the request
+    set(kv, key, value, cacheOptions).catch((err) => {
+        console.error(`[Cache] Failed to store key ${key}:`, err);
+    });
+    return value;
+}
+/**
+ * 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 async function getOrSetSync(kv, key, options) {
+    const { compute, forceRefresh, ...cacheOptions } = options;
+    // Try to get from cache first (unless forcing refresh)
+    if (!forceRefresh) {
+        const cached = await get(kv, key, cacheOptions);
+        if (cached !== null) {
+            return cached;
+        }
+    }
+    // Compute the value
+    let value;
+    try {
+        value = await compute();
+    }
+    catch (err) {
+        throw new CacheError('Failed to compute value', 'COMPUTE_FAILED', err);
+    }
+    // Store in cache and wait for it
+    await set(kv, key, value, cacheOptions);
+    return value;
+}
+// ============================================================================
+// Batch Operations
+// ============================================================================
+/**
+ * Delete multiple keys at once
+ *
+ * @example
+ * ```ts
+ * await cache.delMany(kv, ['user:1', 'user:2', 'user:3']);
+ * ```
+ */
+export async function delMany(kv, keys, options) {
+    await Promise.all(keys.map((key) => del(kv, key, options)));
+}
+/**
+ * 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 async function delByPrefix(kv, prefix, options) {
+    const fullPrefix = buildKey(options?.namespace, prefix);
+    let deleted = 0;
+    let cursor;
+    do {
+        const list = await kv.list({ prefix: fullPrefix, cursor });
+        const keys = list.keys.map((k) => k.name);
+        if (keys.length > 0) {
+            await Promise.all(keys.map((key) => kv.delete(key)));
+            deleted += keys.length;
+        }
+        cursor = list.list_complete ? undefined : list.cursor;
+    } while (cursor);
+    return deleted;
+}
+// ============================================================================
+// Utility Functions
+// ============================================================================
+/**
+ * Check if a key exists in the cache
+ *
+ * @example
+ * ```ts
+ * if (await cache.has(kv, 'user:123')) {
+ *   // Key exists
+ * }
+ * ```
+ */
+export async function has(kv, key, options) {
+    const value = await get(kv, key, options);
+    return value !== null;
+}
+/**
+ * Touch a key (refresh its TTL without changing value)
+ *
+ * @example
+ * ```ts
+ * await cache.touch(kv, 'session:abc', { ttl: 3600 });
+ * ```
+ */
+export async function touch(kv, key, options) {
+    const value = await get(kv, key, options);
+    if (value === null) {
+        return false;
+    }
+    await set(kv, key, value, options);
+    return true;
+}
+// ============================================================================
+// Rate Limiting Helpers
+// ============================================================================
+/**
+ * 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 async function rateLimit(kv, key, options) {
+    const fullKey = buildKey(options.namespace ?? 'ratelimit', key);
+    // Get current count
+    const data = await get(kv, fullKey);
+    const now = Math.floor(Date.now() / 1000);
+    // If no data or window expired, start fresh
+    if (!data || data.resetAt <= now) {
+        const resetAt = now + options.windowSeconds;
+        await set(kv, fullKey, { count: 1, resetAt }, { ttl: options.windowSeconds });
+        return {
+            allowed: true,
+            remaining: options.limit - 1,
+            resetAt
+        };
+    }
+    // Check if over limit
+    if (data.count >= options.limit) {
+        return {
+            allowed: false,
+            remaining: 0,
+            resetAt: data.resetAt
+        };
+    }
+    // Increment count
+    const newCount = data.count + 1;
+    const remaining = Math.max(0, options.limit - newCount);
+    await set(kv, fullKey, { count: newCount, resetAt: data.resetAt }, { ttl: data.resetAt - now });
+    return {
+        allowed: true,
+        remaining,
+        resetAt: data.resetAt
+    };
+}
+// ============================================================================
+// Constants Export
+// ============================================================================
+export const CACHE_DEFAULTS = {
+    TTL_SECONDS: DEFAULT_TTL_SECONDS,
+    KEY_PREFIX
+};

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

@@ -0,0 +1,236 @@
+/**
+ * Database Service - D1 SQLite Abstraction
+ *
+ * Provides typed utilities for D1 database operations:
+ * - Type-safe query helpers
+ * - Transaction/batch support
+ * - Specific error types for debugging
+ * - Common utility functions
+ *
+ * Note: Domain-specific operations (users, sessions, etc.) remain in
+ * their respective packages. This module provides shared primitives.
+ */
+/**
+ * Type alias for D1 database or session
+ * Allows functions to accept either a raw database or a session-scoped connection
+ */
+export type D1DatabaseOrSession = D1Database | D1DatabaseSession;
+/**
+ * Query result metadata from D1
+ */
+export interface QueryMeta {
+    /** Number of rows changed (for INSERT/UPDATE/DELETE) */
+    changes: number;
+    /** Duration of the query in milliseconds */
+    duration: number;
+    /** Last inserted row ID (SQLite) */
+    lastRowId: number;
+    /** Number of rows read */
+    rowsRead: number;
+    /** Number of rows written */
+    rowsWritten: number;
+}
+/**
+ * Result from an execute (non-SELECT) operation
+ */
+export interface ExecuteResult {
+    success: boolean;
+    meta: QueryMeta;
+}
+export declare class DatabaseError extends Error {
+    readonly code: DatabaseErrorCode;
+    readonly cause?: unknown | undefined;
+    constructor(message: string, code: DatabaseErrorCode, cause?: unknown | undefined);
+}
+export type DatabaseErrorCode = 'QUERY_FAILED' | 'NOT_FOUND' | 'CONSTRAINT_VIOLATION' | 'TRANSACTION_FAILED' | 'CONNECTION_ERROR' | 'INVALID_QUERY';
+/**
+ * Generate a UUID v4 identifier
+ */
+export declare function generateId(): string;
+/**
+ * Get current timestamp in ISO format
+ */
+export declare function now(): string;
+/**
+ * Get a timestamp for a future time
+ * @param ms - Milliseconds from now
+ */
+export declare function futureTimestamp(ms: number): string;
+/**
+ * Check if a timestamp has expired
+ */
+export declare function isExpired(timestamp: string): boolean;
+/**
+ * Execute a query expecting a single row result
+ *
+ * @example
+ * ```ts
+ * const user = await db.queryOne<User>(
+ *   db,
+ *   'SELECT * FROM users WHERE id = ?',
+ *   [userId]
+ * );
+ * if (!user) throw new Error('User not found');
+ * ```
+ */
+export declare function queryOne<T>(db: D1DatabaseOrSession, sql: string, params?: unknown[]): Promise<T | null>;
+/**
+ * Execute a query expecting a single row, throw if not found
+ *
+ * @example
+ * ```ts
+ * const user = await db.queryOneOrThrow<User>(
+ *   db,
+ *   'SELECT * FROM users WHERE id = ?',
+ *   [userId]
+ * );
+ * // user is guaranteed to exist here
+ * ```
+ */
+export declare function queryOneOrThrow<T>(db: D1DatabaseOrSession, sql: string, params?: unknown[], errorMessage?: string): Promise<T>;
+/**
+ * Execute a query expecting multiple rows
+ *
+ * @example
+ * ```ts
+ * const users = await db.queryMany<User>(
+ *   db,
+ *   'SELECT * FROM users WHERE is_admin = ?',
+ *   [1]
+ * );
+ * ```
+ */
+export declare function queryMany<T>(db: D1DatabaseOrSession, sql: string, params?: unknown[]): Promise<T[]>;
+/**
+ * Execute a non-SELECT statement (INSERT, UPDATE, DELETE)
+ *
+ * @example
+ * ```ts
+ * const result = await db.execute(
+ *   db,
+ *   'UPDATE users SET name = ? WHERE id = ?',
+ *   [newName, userId]
+ * );
+ * console.log(`Updated ${result.meta.changes} rows`);
+ * ```
+ */
+export declare function execute(db: D1DatabaseOrSession, sql: string, params?: unknown[]): Promise<ExecuteResult>;
+/**
+ * Execute a statement and throw if no rows were affected
+ *
+ * @example
+ * ```ts
+ * await db.executeOrThrow(
+ *   db,
+ *   'DELETE FROM sessions WHERE id = ?',
+ *   [sessionId],
+ *   'Session not found'
+ * );
+ * ```
+ */
+export declare function executeOrThrow(db: D1DatabaseOrSession, sql: string, params?: unknown[], errorMessage?: string): Promise<ExecuteResult>;
+/**
+ * Execute multiple statements atomically
+ * All statements succeed or all fail (D1 batch semantics)
+ *
+ * @example
+ * ```ts
+ * await db.batch(db, [
+ *   { sql: 'INSERT INTO users (id, email) VALUES (?, ?)', params: [id, email] },
+ *   { sql: 'INSERT INTO profiles (user_id) VALUES (?)', params: [id] }
+ * ]);
+ * ```
+ */
+export declare function batch(db: D1Database, statements: Array<{
+    sql: string;
+    params?: unknown[];
+}>): Promise<ExecuteResult[]>;
+/**
+ * Execute a function within a database session for read consistency
+ *
+ * @example
+ * ```ts
+ * const result = await db.withSession(db, async (session) => {
+ *   const user = await queryOne<User>(session, 'SELECT * FROM users WHERE id = ?', [id]);
+ *   const posts = await queryMany<Post>(session, 'SELECT * FROM posts WHERE user_id = ?', [id]);
+ *   return { user, posts };
+ * });
+ * ```
+ */
+export declare function withSession<T>(db: D1Database, fn: (session: D1DatabaseSession) => Promise<T>): Promise<T>;
+/**
+ * Insert a row and return the generated ID
+ *
+ * SECURITY: Table and column names are validated to prevent SQL injection.
+ * Only use with hardcoded names, never user input.
+ *
+ * @example
+ * ```ts
+ * const id = await db.insert(db, 'users', {
+ *   email: 'user@example.com',
+ *   name: 'John'
+ * });
+ * ```
+ */
+export declare function insert(db: D1DatabaseOrSession, table: string, data: Record<string, unknown>, options?: {
+    id?: string;
+}): Promise<string>;
+/**
+ * Update rows matching a condition
+ *
+ * SECURITY: Table and column names are validated to prevent SQL injection.
+ * Only use with hardcoded names, never user input.
+ *
+ * @example
+ * ```ts
+ * const changes = await db.update(db, 'users', { name: 'Jane' }, 'id = ?', [userId]);
+ * ```
+ */
+export declare function update(db: D1DatabaseOrSession, table: string, data: Record<string, unknown>, where: string, whereParams?: unknown[]): Promise<number>;
+/**
+ * Delete rows matching a condition
+ *
+ * SECURITY: Table name is validated to prevent SQL injection.
+ * Only use with hardcoded table names, never user input.
+ *
+ * @example
+ * ```ts
+ * const deleted = await db.deleteWhere(db, 'sessions', 'expires_at < datetime("now")');
+ * ```
+ */
+export declare function deleteWhere(db: D1DatabaseOrSession, table: string, where: string, whereParams?: unknown[]): Promise<number>;
+/**
+ * Delete a single row by ID
+ *
+ * @example
+ * ```ts
+ * await db.deleteById(db, 'users', userId);
+ * ```
+ */
+export declare function deleteById(db: D1DatabaseOrSession, table: string, id: string): Promise<boolean>;
+/**
+ * Check if a row exists
+ *
+ * SECURITY: Table name is validated to prevent SQL injection.
+ * Only use with hardcoded table names, never user input.
+ *
+ * @example
+ * ```ts
+ * if (await db.exists(db, 'users', 'email = ?', [email])) {
+ *   throw new Error('Email already registered');
+ * }
+ * ```
+ */
+export declare function exists(db: D1DatabaseOrSession, table: string, where: string, whereParams?: unknown[]): Promise<boolean>;
+/**
+ * Count rows matching a condition
+ *
+ * SECURITY: Table name is validated to prevent SQL injection.
+ * Only use with hardcoded table names, never user input.
+ *
+ * @example
+ * ```ts
+ * const activeUsers = await db.count(db, 'users', 'is_active = ?', [1]);
+ * ```
+ */
+export declare function count(db: D1DatabaseOrSession, table: string, where?: string, whereParams?: unknown[]): Promise<number>;