@autumnsgrove/groveengine 0.5.0 → 0.6.1

package/dist/server/services/database.js

@@ -0,0 +1,450 @@
+/**
+ * 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.
+ */
+// ============================================================================
+// Errors
+// ============================================================================
+export class DatabaseError extends Error {
+    code;
+    cause;
+    constructor(message, code, cause) {
+        super(message);
+        this.code = code;
+        this.cause = cause;
+        this.name = 'DatabaseError';
+    }
+}
+// ============================================================================
+// Utility Functions
+// ============================================================================
+/**
+ * Generate a UUID v4 identifier
+ */
+export function generateId() {
+    return crypto.randomUUID();
+}
+/**
+ * Get current timestamp in ISO format
+ */
+export function now() {
+    return new Date().toISOString();
+}
+/**
+ * Get a timestamp for a future time
+ * @param ms - Milliseconds from now
+ */
+export function futureTimestamp(ms) {
+    return new Date(Date.now() + ms).toISOString();
+}
+/**
+ * Check if a timestamp has expired
+ */
+export function isExpired(timestamp) {
+    return new Date(timestamp) < new Date();
+}
+// ============================================================================
+// Query Helpers
+// ============================================================================
+/**
+ * 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 async function queryOne(db, sql, params = []) {
+    try {
+        const result = await db
+            .prepare(sql)
+            .bind(...params)
+            .first();
+        return result ?? null;
+    }
+    catch (err) {
+        throw new DatabaseError(`Query failed: ${sql}`, 'QUERY_FAILED', err);
+    }
+}
+/**
+ * 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 async function queryOneOrThrow(db, sql, params = [], errorMessage = 'Record not found') {
+    const result = await queryOne(db, sql, params);
+    if (result === null) {
+        throw new DatabaseError(errorMessage, 'NOT_FOUND');
+    }
+    return result;
+}
+/**
+ * Execute a query expecting multiple rows
+ *
+ * @example
+ * ```ts
+ * const users = await db.queryMany<User>(
+ *   db,
+ *   'SELECT * FROM users WHERE is_admin = ?',
+ *   [1]
+ * );
+ * ```
+ */
+export async function queryMany(db, sql, params = []) {
+    try {
+        const result = await db
+            .prepare(sql)
+            .bind(...params)
+            .all();
+        return result.results ?? [];
+    }
+    catch (err) {
+        throw new DatabaseError(`Query failed: ${sql}`, 'QUERY_FAILED', err);
+    }
+}
+/**
+ * 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 async function execute(db, sql, params = []) {
+    try {
+        const result = await db
+            .prepare(sql)
+            .bind(...params)
+            .run();
+        return {
+            success: result.success,
+            meta: {
+                changes: result.meta.changes ?? 0,
+                duration: result.meta.duration,
+                lastRowId: result.meta.last_row_id ?? 0,
+                rowsRead: result.meta.rows_read ?? 0,
+                rowsWritten: result.meta.rows_written ?? 0
+            }
+        };
+    }
+    catch (err) {
+        throw new DatabaseError(`Execute failed: ${sql}`, 'QUERY_FAILED', err);
+    }
+}
+/**
+ * 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 async function executeOrThrow(db, sql, params = [], errorMessage = 'No rows affected') {
+    const result = await execute(db, sql, params);
+    if (result.meta.changes === 0) {
+        throw new DatabaseError(errorMessage, 'NOT_FOUND');
+    }
+    return result;
+}
+// ============================================================================
+// Batch / Transaction Helpers
+// ============================================================================
+/**
+ * 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 async function batch(db, statements) {
+    try {
+        const prepared = statements.map((stmt, index) => {
+            try {
+                return db.prepare(stmt.sql).bind(...(stmt.params ?? []));
+            }
+            catch (prepareErr) {
+                throw new DatabaseError(`Batch statement ${index + 1}/${statements.length} failed to prepare: ${stmt.sql.slice(0, 100)}`, 'INVALID_QUERY', prepareErr);
+            }
+        });
+        const results = await db.batch(prepared);
+        return results.map((result) => ({
+            success: result.success,
+            meta: {
+                changes: result.meta.changes ?? 0,
+                duration: result.meta.duration,
+                lastRowId: result.meta.last_row_id ?? 0,
+                rowsRead: result.meta.rows_read ?? 0,
+                rowsWritten: result.meta.rows_written ?? 0
+            }
+        }));
+    }
+    catch (err) {
+        if (err instanceof DatabaseError) {
+            throw err;
+        }
+        // Include statement count for context
+        const stmtSummary = statements.map((s, i) => `${i + 1}: ${s.sql.slice(0, 50)}...`).join('; ');
+        throw new DatabaseError(`Batch operation failed (${statements.length} statements: ${stmtSummary})`, 'TRANSACTION_FAILED', err);
+    }
+}
+/**
+ * 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 async function withSession(db, fn) {
+    const session = db.withSession();
+    try {
+        return await fn(session);
+    }
+    catch (err) {
+        throw new DatabaseError('Session operation failed', 'TRANSACTION_FAILED', err);
+    }
+}
+// ============================================================================
+// Table Name Validation
+// ============================================================================
+/**
+ * Valid identifier pattern - alphanumeric and underscores only
+ * This prevents SQL injection in functions that accept table/column names
+ */
+const VALID_IDENTIFIER = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
+function validateTableName(table) {
+    if (!VALID_IDENTIFIER.test(table)) {
+        throw new DatabaseError(`Invalid table name: ${table}. Table names must be alphanumeric with underscores only.`, 'INVALID_QUERY');
+    }
+}
+function validateColumnName(column) {
+    if (!VALID_IDENTIFIER.test(column)) {
+        throw new DatabaseError(`Invalid column name: ${column}. Column names must be alphanumeric with underscores only.`, 'INVALID_QUERY');
+    }
+}
+function validateColumnNames(columns) {
+    for (const column of columns) {
+        validateColumnName(column);
+    }
+}
+// ============================================================================
+// Insert Helpers
+// ============================================================================
+/**
+ * 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 async function insert(db, table, data, options) {
+    validateTableName(table);
+    validateColumnNames(Object.keys(data));
+    const id = options?.id ?? generateId();
+    const timestamp = now();
+    const dataWithMeta = {
+        id,
+        ...data,
+        created_at: timestamp,
+        updated_at: timestamp
+    };
+    const columns = Object.keys(dataWithMeta);
+    const placeholders = columns.map(() => '?').join(', ');
+    const values = Object.values(dataWithMeta);
+    const sql = `INSERT INTO ${table} (${columns.join(', ')}) VALUES (${placeholders})`;
+    try {
+        await db
+            .prepare(sql)
+            .bind(...values)
+            .run();
+        return id;
+    }
+    catch (err) {
+        if (err instanceof Error && err.message.includes('UNIQUE constraint')) {
+            throw new DatabaseError(`Duplicate entry in ${table} (columns: ${columns.join(', ')})`, 'CONSTRAINT_VIOLATION', err);
+        }
+        throw new DatabaseError(`Insert into ${table} failed (columns: ${columns.join(', ')})`, 'QUERY_FAILED', err);
+    }
+}
+// ============================================================================
+// Update Helpers
+// ============================================================================
+/**
+ * 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 async function update(db, table, data, where, whereParams = []) {
+    validateTableName(table);
+    validateColumnNames(Object.keys(data));
+    const dataWithTimestamp = {
+        ...data,
+        updated_at: now()
+    };
+    const setClauses = Object.keys(dataWithTimestamp)
+        .map((key) => `${key} = ?`)
+        .join(', ');
+    const values = [...Object.values(dataWithTimestamp), ...whereParams];
+    const sql = `UPDATE ${table} SET ${setClauses} WHERE ${where}`;
+    try {
+        const result = await db
+            .prepare(sql)
+            .bind(...values)
+            .run();
+        return result.meta.changes ?? 0;
+    }
+    catch (err) {
+        const fields = Object.keys(dataWithTimestamp).join(', ');
+        throw new DatabaseError(`Update ${table} failed (fields: ${fields}, where: ${where})`, 'QUERY_FAILED', err);
+    }
+}
+// ============================================================================
+// Delete Helpers
+// ============================================================================
+/**
+ * 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 async function deleteWhere(db, table, where, whereParams = []) {
+    validateTableName(table);
+    const sql = `DELETE FROM ${table} WHERE ${where}`;
+    try {
+        const result = await db
+            .prepare(sql)
+            .bind(...whereParams)
+            .run();
+        return result.meta.changes ?? 0;
+    }
+    catch (err) {
+        throw new DatabaseError(`Delete from ${table} failed (where: ${where})`, 'QUERY_FAILED', err);
+    }
+}
+/**
+ * Delete a single row by ID
+ *
+ * @example
+ * ```ts
+ * await db.deleteById(db, 'users', userId);
+ * ```
+ */
+export async function deleteById(db, table, id) {
+    const changes = await deleteWhere(db, table, 'id = ?', [id]);
+    return changes > 0;
+}
+// ============================================================================
+// Existence Checks
+// ============================================================================
+/**
+ * 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 async function exists(db, table, where, whereParams = []) {
+    validateTableName(table);
+    const sql = `SELECT 1 FROM ${table} WHERE ${where} LIMIT 1`;
+    try {
+        const result = await db
+            .prepare(sql)
+            .bind(...whereParams)
+            .first();
+        return result !== null;
+    }
+    catch (err) {
+        throw new DatabaseError(`Existence check on ${table} failed`, 'QUERY_FAILED', err);
+    }
+}
+/**
+ * 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 async function count(db, table, where, whereParams = []) {
+    validateTableName(table);
+    const sql = where
+        ? `SELECT COUNT(*) as count FROM ${table} WHERE ${where}`
+        : `SELECT COUNT(*) as count FROM ${table}`;
+    try {
+        const result = await db
+            .prepare(sql)
+            .bind(...whereParams)
+            .first();
+        return result?.count ?? 0;
+    }
+    catch (err) {
+        throw new DatabaseError(`Count on ${table} failed`, 'QUERY_FAILED', err);
+    }
+}

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

@@ -0,0 +1,34 @@
+/**
+ * Grove Engine - Service Modules
+ *
+ * Cloudflare infrastructure abstraction layer providing clean interfaces
+ * for storage (R2), database (D1), and caching (KV) operations.
+ *
+ * @example
+ * ```ts
+ * import { storage, db, cache } from '@autumnsgrove/groveengine/services';
+ *
+ * // Storage operations
+ * const file = await storage.uploadFile(bucket, database, {
+ *   data: arrayBuffer,
+ *   filename: 'photo.jpg',
+ *   contentType: 'image/jpeg',
+ *   uploadedBy: userId
+ * });
+ *
+ * // Database operations
+ * const user = await db.queryOne<User>(database, 'SELECT * FROM users WHERE id = ?', [id]);
+ *
+ * // Cache operations
+ * const data = await cache.getOrSet(kv, 'user:123', {
+ *   ttl: 3600,
+ *   compute: () => fetchUser(id)
+ * });
+ * ```
+ */
+export * as storage from './storage.js';
+export { type StorageFile, type UploadOptions, type GetFileResult, type FileMetadata, StorageError, type StorageErrorCode, uploadFile, getFile, getFileMetadata, fileExists, deleteFile, deleteFileByKey, getFileRecord, getFileRecordByKey, listFiles, listAllFiles, listFolders, updateAltText, validateFile, isAllowedContentType, shouldReturn304, buildFileHeaders } from './storage.js';
+export * as db from './database.js';
+export { type D1DatabaseOrSession, type QueryMeta, type ExecuteResult, DatabaseError, type DatabaseErrorCode, generateId, now, futureTimestamp, isExpired, queryOne, queryOneOrThrow, queryMany, execute, executeOrThrow, batch, withSession, insert, update, deleteWhere, deleteById, exists, count } from './database.js';
+export * as cache from './cache.js';
+export { type CacheOptions, type GetOrSetOptions, CacheError, type CacheErrorCode, get as cacheGet, set as cacheSet, del as cacheDel, getOrSet, getOrSetSync, delMany, delByPrefix, has as cacheHas, touch, rateLimit, CACHE_DEFAULTS } from './cache.js';

package/dist/server/services/index.js

@@ -0,0 +1,77 @@
+/**
+ * Grove Engine - Service Modules
+ *
+ * Cloudflare infrastructure abstraction layer providing clean interfaces
+ * for storage (R2), database (D1), and caching (KV) operations.
+ *
+ * @example
+ * ```ts
+ * import { storage, db, cache } from '@autumnsgrove/groveengine/services';
+ *
+ * // Storage operations
+ * const file = await storage.uploadFile(bucket, database, {
+ *   data: arrayBuffer,
+ *   filename: 'photo.jpg',
+ *   contentType: 'image/jpeg',
+ *   uploadedBy: userId
+ * });
+ *
+ * // Database operations
+ * const user = await db.queryOne<User>(database, 'SELECT * FROM users WHERE id = ?', [id]);
+ *
+ * // Cache operations
+ * const data = await cache.getOrSet(kv, 'user:123', {
+ *   ttl: 3600,
+ *   compute: () => fetchUser(id)
+ * });
+ * ```
+ */
+// ============================================================================
+// Storage Service (R2)
+// ============================================================================
+export * as storage from './storage.js';
+export { 
+// Errors
+StorageError, 
+// Operations
+uploadFile, getFile, getFileMetadata, fileExists, deleteFile, deleteFileByKey, 
+// Metadata Operations
+getFileRecord, getFileRecordByKey, listFiles, listAllFiles, listFolders, updateAltText, 
+// Validation
+validateFile, isAllowedContentType, 
+// Response Helpers
+shouldReturn304, buildFileHeaders } from './storage.js';
+// ============================================================================
+// Database Service (D1)
+// ============================================================================
+export * as db from './database.js';
+export { 
+// Errors
+DatabaseError, 
+// Utilities
+generateId, now, futureTimestamp, isExpired, 
+// Query Helpers
+queryOne, queryOneOrThrow, queryMany, execute, executeOrThrow, 
+// Batch Operations
+batch, withSession, 
+// CRUD Helpers
+insert, update, deleteWhere, deleteById, 
+// Existence Checks
+exists, count } from './database.js';
+// ============================================================================
+// Cache Service (KV)
+// ============================================================================
+export * as cache from './cache.js';
+export { 
+// Errors
+CacheError, 
+// Operations
+get as cacheGet, set as cacheSet, del as cacheDel, getOrSet, getOrSetSync, 
+// Batch Operations
+delMany, delByPrefix, 
+// Utilities
+has as cacheHas, touch, 
+// Rate Limiting
+rateLimit, 
+// Constants
+CACHE_DEFAULTS } from './cache.js';