@ereo/db 0.1.6

package/dist/index.js

@@ -0,0 +1,505 @@
+// @bun
+// src/adapter.ts
+var adapterRegistry = new Map;
+function registerAdapter(name, adapter) {
+  adapterRegistry.set(name, adapter);
+}
+function getAdapter(name) {
+  return adapterRegistry.get(name);
+}
+function getDefaultAdapter() {
+  const first = adapterRegistry.values().next();
+  return first.done ? undefined : first.value;
+}
+function clearAdapterRegistry() {
+  adapterRegistry.clear();
+}
+// src/dedup.ts
+var DEDUP_CACHE_KEY = "__ereo_db_dedup_cache";
+var DEDUP_STATS_KEY = "__ereo_db_dedup_stats";
+function generateFingerprint(query, params) {
+  const normalizedQuery = query.trim().replace(/\s+/g, " ");
+  const serializedParams = params ? JSON.stringify(params, (_, value) => {
+    if (value instanceof Date) {
+      return `__date:${value.toISOString()}`;
+    }
+    if (typeof value === "bigint") {
+      return `__bigint:${value.toString()}`;
+    }
+    if (value === undefined) {
+      return "__undefined";
+    }
+    return value;
+  }) : "";
+  return `${hashString(normalizedQuery)}:${hashString(serializedParams)}`;
+}
+function hashString(str) {
+  let hash = 5381;
+  for (let i = 0;i < str.length; i++) {
+    hash = hash * 33 ^ str.charCodeAt(i);
+  }
+  return (hash >>> 0).toString(36);
+}
+function getCache(context) {
+  let cache = context.get(DEDUP_CACHE_KEY);
+  if (!cache) {
+    cache = new Map;
+    context.set(DEDUP_CACHE_KEY, cache);
+  }
+  return cache;
+}
+function getStats(context) {
+  let stats = context.get(DEDUP_STATS_KEY);
+  if (!stats) {
+    stats = { total: 0, hits: 0, misses: 0 };
+    context.set(DEDUP_STATS_KEY, stats);
+  }
+  return stats;
+}
+async function dedupQuery(context, query, params, executor, options) {
+  const stats = getStats(context);
+  stats.total++;
+  if (options?.noCache) {
+    const result2 = await executor();
+    stats.misses++;
+    return {
+      result: result2,
+      fromCache: false,
+      cacheKey: ""
+    };
+  }
+  const cache = getCache(context);
+  const cacheKey = generateFingerprint(query, params);
+  const cached = cache.get(cacheKey);
+  if (cached) {
+    stats.hits++;
+    return {
+      result: cached.result,
+      fromCache: true,
+      cacheKey
+    };
+  }
+  const result = await executor();
+  stats.misses++;
+  cache.set(cacheKey, {
+    result,
+    timestamp: Date.now(),
+    tables: options?.tables
+  });
+  return {
+    result,
+    fromCache: false,
+    cacheKey
+  };
+}
+function clearDedupCache(context) {
+  const cache = context.get(DEDUP_CACHE_KEY);
+  if (cache) {
+    cache.clear();
+  }
+}
+function invalidateTables(context, tables) {
+  const cache = context.get(DEDUP_CACHE_KEY);
+  if (!cache)
+    return;
+  const tableSet = new Set(tables.map((t) => t.toLowerCase()));
+  for (const [key, entry] of cache.entries()) {
+    if (entry.tables) {
+      const hasOverlap = entry.tables.some((t) => tableSet.has(t.toLowerCase()));
+      if (hasOverlap) {
+        cache.delete(key);
+      }
+    }
+  }
+}
+function getRequestDedupStats(context) {
+  const stats = context.get(DEDUP_STATS_KEY);
+  if (!stats) {
+    return {
+      total: 0,
+      deduplicated: 0,
+      unique: 0,
+      hitRate: 0
+    };
+  }
+  return {
+    total: stats.total,
+    deduplicated: stats.hits,
+    unique: stats.misses,
+    hitRate: stats.total > 0 ? stats.hits / stats.total : 0
+  };
+}
+function debugGetCacheContents(context) {
+  const cache = context.get(DEDUP_CACHE_KEY);
+  if (!cache)
+    return [];
+  const now = Date.now();
+  return Array.from(cache.entries()).map(([key, entry]) => ({
+    key,
+    tables: entry.tables,
+    age: now - entry.timestamp
+  }));
+}
+// src/types.ts
+class DatabaseError extends Error {
+  code;
+  cause;
+  constructor(message, code, cause) {
+    super(message);
+    this.code = code;
+    this.cause = cause;
+    this.name = "DatabaseError";
+  }
+}
+
+class ConnectionError extends DatabaseError {
+  constructor(message, cause) {
+    super(message, "CONNECTION_ERROR", cause);
+    this.name = "ConnectionError";
+  }
+}
+
+class QueryError extends DatabaseError {
+  query;
+  params;
+  constructor(message, query, params, cause) {
+    super(message, "QUERY_ERROR", cause);
+    this.query = query;
+    this.params = params;
+    this.name = "QueryError";
+  }
+}
+
+class TransactionError extends DatabaseError {
+  constructor(message, cause) {
+    super(message, "TRANSACTION_ERROR", cause);
+    this.name = "TransactionError";
+  }
+}
+
+class TimeoutError extends DatabaseError {
+  timeoutMs;
+  constructor(message, timeoutMs) {
+    super(message, "TIMEOUT_ERROR");
+    this.timeoutMs = timeoutMs;
+    this.name = "TimeoutError";
+  }
+}
+
+// src/pool.ts
+var DEFAULT_POOL_CONFIG = {
+  min: 2,
+  max: 10,
+  idleTimeoutMs: 30000,
+  acquireTimeoutMs: 1e4,
+  acquireRetries: 3
+};
+function createEdgePoolConfig(overrides) {
+  return {
+    min: 0,
+    max: 1,
+    idleTimeoutMs: 0,
+    acquireTimeoutMs: 5000,
+    acquireRetries: 2,
+    ...overrides
+  };
+}
+function createServerlessPoolConfig(overrides) {
+  return {
+    min: 0,
+    max: 5,
+    idleTimeoutMs: 1e4,
+    acquireTimeoutMs: 8000,
+    acquireRetries: 2,
+    ...overrides
+  };
+}
+
+class ConnectionPool {
+  config;
+  connections = [];
+  activeConnections = new Set;
+  waitQueue = [];
+  closed = false;
+  stats = {
+    totalCreated: 0,
+    totalClosed: 0
+  };
+  constructor(config) {
+    this.config = {
+      ...DEFAULT_POOL_CONFIG,
+      ...config
+    };
+  }
+  async acquire() {
+    if (this.closed) {
+      throw new ConnectionError("Pool is closed");
+    }
+    const idle = this.connections.pop();
+    if (idle) {
+      try {
+        const isValid = await this.validateConnection(idle);
+        if (isValid) {
+          this.activeConnections.add(idle);
+          return idle;
+        }
+        await this.closeConnection(idle);
+        this.stats.totalClosed++;
+      } catch {}
+    }
+    if (this.activeConnections.size + this.connections.length < this.config.max) {
+      return this.createAndAcquire();
+    }
+    return this.waitForConnection();
+  }
+  async release(connection) {
+    if (!this.activeConnections.has(connection)) {
+      return;
+    }
+    this.activeConnections.delete(connection);
+    if (this.waitQueue.length > 0) {
+      const waiter = this.waitQueue.shift();
+      clearTimeout(waiter.timeout);
+      this.activeConnections.add(connection);
+      waiter.resolve(connection);
+      return;
+    }
+    if (!this.closed && this.connections.length < this.config.max) {
+      this.connections.push(connection);
+      this.scheduleIdleTimeout(connection);
+    } else {
+      await this.closeConnection(connection);
+      this.stats.totalClosed++;
+    }
+  }
+  async close() {
+    this.closed = true;
+    for (const waiter of this.waitQueue) {
+      clearTimeout(waiter.timeout);
+      waiter.reject(new ConnectionError("Pool is closing"));
+    }
+    this.waitQueue = [];
+    const closePromises = this.connections.map(async (conn) => {
+      try {
+        await this.closeConnection(conn);
+        this.stats.totalClosed++;
+      } catch {}
+    });
+    this.connections = [];
+    await Promise.all(closePromises);
+  }
+  getStats() {
+    return {
+      active: this.activeConnections.size,
+      idle: this.connections.length,
+      total: this.activeConnections.size + this.connections.length,
+      waiting: this.waitQueue.length,
+      totalCreated: this.stats.totalCreated,
+      totalClosed: this.stats.totalClosed
+    };
+  }
+  async healthCheck() {
+    const start = Date.now();
+    try {
+      const conn = await this.acquire();
+      const isValid = await this.validateConnection(conn);
+      await this.release(conn);
+      return {
+        healthy: isValid,
+        latencyMs: Date.now() - start,
+        metadata: this.getStats()
+      };
+    } catch (error) {
+      return {
+        healthy: false,
+        latencyMs: Date.now() - start,
+        error: error instanceof Error ? error.message : String(error),
+        metadata: this.getStats()
+      };
+    }
+  }
+  async createAndAcquire() {
+    let lastError;
+    for (let attempt = 0;attempt < this.config.acquireRetries; attempt++) {
+      try {
+        const connection = await this.createConnection();
+        this.stats.totalCreated++;
+        this.activeConnections.add(connection);
+        return connection;
+      } catch (error) {
+        lastError = error instanceof Error ? error : new Error(String(error));
+        if (attempt < this.config.acquireRetries - 1) {
+          await this.delay(Math.pow(2, attempt) * 100);
+        }
+      }
+    }
+    throw new ConnectionError(`Failed to create connection after ${this.config.acquireRetries} attempts`, lastError);
+  }
+  waitForConnection() {
+    return new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        const index = this.waitQueue.findIndex((w) => w.resolve === resolve);
+        if (index !== -1) {
+          this.waitQueue.splice(index, 1);
+        }
+        reject(new TimeoutError("Timed out waiting for connection", this.config.acquireTimeoutMs));
+      }, this.config.acquireTimeoutMs);
+      this.waitQueue.push({ resolve, reject, timeout });
+    });
+  }
+  scheduleIdleTimeout(connection) {
+    if (this.config.idleTimeoutMs <= 0)
+      return;
+    setTimeout(async () => {
+      const index = this.connections.indexOf(connection);
+      if (index !== -1) {
+        this.connections.splice(index, 1);
+        try {
+          await this.closeConnection(connection);
+          this.stats.totalClosed++;
+        } catch {}
+      }
+    }, this.config.idleTimeoutMs);
+  }
+  delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+}
+var DEFAULT_RETRY_CONFIG = {
+  maxAttempts: 3,
+  baseDelayMs: 100,
+  maxDelayMs: 5000,
+  exponential: true
+};
+async function withRetry(operation, config = {}) {
+  const {
+    maxAttempts,
+    baseDelayMs,
+    maxDelayMs,
+    exponential,
+    isRetryable
+  } = { ...DEFAULT_RETRY_CONFIG, ...config };
+  let lastError;
+  for (let attempt = 1;attempt <= maxAttempts; attempt++) {
+    try {
+      return await operation();
+    } catch (error) {
+      lastError = error instanceof Error ? error : new Error(String(error));
+      if (isRetryable && !isRetryable(lastError)) {
+        throw lastError;
+      }
+      if (attempt < maxAttempts) {
+        const delay = exponential ? Math.min(baseDelayMs * Math.pow(2, attempt - 1), maxDelayMs) : baseDelayMs;
+        await new Promise((resolve) => setTimeout(resolve, delay));
+      }
+    }
+  }
+  throw lastError;
+}
+function isCommonRetryableError(error) {
+  const message = error.message.toLowerCase();
+  if (message.includes("connection") && (message.includes("refused") || message.includes("reset") || message.includes("closed") || message.includes("timeout"))) {
+    return true;
+  }
+  if (message.includes("deadlock")) {
+    return true;
+  }
+  if (message.includes("serialization failure") || message.includes("could not serialize")) {
+    return true;
+  }
+  if (message.includes("too many connections")) {
+    return true;
+  }
+  return false;
+}
+// src/plugin.ts
+var DB_CLIENT_KEY = "__ereo_db_client";
+var DB_ADAPTER_KEY = "__ereo_db_adapter";
+function createDatabasePlugin(adapter, options = {}) {
+  const {
+    registerDefault = true,
+    registrationName = adapter.name,
+    debug = false
+  } = options;
+  const log = debug ? (...args) => console.log(`[db:${adapter.name}]`, ...args) : () => {};
+  return {
+    name: `@ereo/db:${adapter.name}`,
+    async setup() {
+      log("Initializing database adapter...");
+      if (registerDefault) {
+        registerAdapter(registrationName, adapter);
+        log(`Registered as "${registrationName}"`);
+      }
+      const health = await adapter.healthCheck();
+      if (health.healthy) {
+        log(`Connected successfully (${health.latencyMs}ms)`);
+      } else {
+        console.warn(`[db:${adapter.name}] Health check failed:`, health.error);
+      }
+    },
+    configureServer(server) {
+      server.middlewares.push(async (_request, context, next) => {
+        const client = adapter.getRequestClient(context);
+        context.set(DB_CLIENT_KEY, client);
+        context.set(DB_ADAPTER_KEY, adapter);
+        log("Attached request-scoped client to context");
+        return next();
+      });
+    }
+  };
+}
+function useDb(context) {
+  const client = context.get(DB_CLIENT_KEY);
+  if (!client) {
+    throw new Error("Database not available in context. " + "Ensure createDatabasePlugin is registered in your config.");
+  }
+  return client;
+}
+function useAdapter(context) {
+  const adapter = context.get(DB_ADAPTER_KEY);
+  if (!adapter) {
+    throw new Error("Database adapter not available in context. " + "Ensure createDatabasePlugin is registered in your config.");
+  }
+  return adapter;
+}
+function getDb() {
+  return getDefaultAdapter();
+}
+async function withTransaction(context, fn) {
+  const adapter = useAdapter(context);
+  const result = await adapter.transaction(fn);
+  const client = context.get(DB_CLIENT_KEY);
+  if (client) {
+    client.clearDedup();
+  }
+  return result;
+}
+export {
+  withTransaction,
+  withRetry,
+  useDb,
+  useAdapter,
+  registerAdapter,
+  isCommonRetryableError,
+  invalidateTables,
+  getRequestDedupStats,
+  getDefaultAdapter,
+  getDb,
+  getAdapter,
+  generateFingerprint,
+  dedupQuery,
+  debugGetCacheContents,
+  createServerlessPoolConfig,
+  createEdgePoolConfig,
+  createDatabasePlugin,
+  clearDedupCache,
+  clearAdapterRegistry,
+  TransactionError,
+  TimeoutError,
+  QueryError,
+  DatabaseError,
+  DEFAULT_RETRY_CONFIG,
+  DEFAULT_POOL_CONFIG,
+  ConnectionPool,
+  ConnectionError
+};

package/dist/plugin.d.ts

@@ -0,0 +1,117 @@
+/**
+ * @ereo/db - Database Plugin Factory
+ *
+ * Creates an EreoJS plugin that integrates a database adapter
+ * with the framework's request lifecycle.
+ */
+import type { Plugin, AppContext } from '@ereo/core';
+import type { DatabaseAdapter, RequestScopedClient } from './adapter';
+/**
+ * Options for the database plugin.
+ */
+export interface DatabasePluginOptions {
+    /**
+     * Register this adapter as the default.
+     * @default true
+     */
+    registerDefault?: boolean;
+    /**
+     * Name to register the adapter under.
+     * @default adapter.name
+     */
+    registrationName?: string;
+    /**
+     * Enable debug logging.
+     * @default false
+     */
+    debug?: boolean;
+}
+/**
+ * Create an EreoJS plugin for a database adapter.
+ * This handles the lifecycle integration:
+ * - Registers the adapter globally on setup
+ * - Attaches request-scoped clients to context via middleware
+ * - Handles cleanup on shutdown
+ *
+ * @param adapter - The database adapter instance
+ * @param options - Plugin configuration options
+ * @returns An EreoJS plugin
+ *
+ * @example
+ * import { createDatabasePlugin } from '@ereo/db';
+ * import { createDrizzleAdapter } from '@ereo/db-drizzle';
+ *
+ * const adapter = createDrizzleAdapter({
+ *   driver: 'postgres-js',
+ *   url: process.env.DATABASE_URL,
+ *   schema,
+ * });
+ *
+ * export default defineConfig({
+ *   plugins: [
+ *     createDatabasePlugin(adapter),
+ *   ],
+ * });
+ */
+export declare function createDatabasePlugin<TSchema>(adapter: DatabaseAdapter<TSchema>, options?: DatabasePluginOptions): Plugin;
+/**
+ * Get the database client from request context.
+ * Use this in loaders, actions, and middleware.
+ *
+ * @param context - The request context from EreoJS
+ * @returns The request-scoped database client with deduplication
+ * @throws Error if database plugin is not configured
+ *
+ * @example
+ * export const loader = createLoader({
+ *   load: async ({ context }) => {
+ *     const db = useDb(context);
+ *     return db.client.select().from(users).where(eq(users.id, 1));
+ *   },
+ * });
+ */
+export declare function useDb<TSchema = unknown>(context: AppContext): RequestScopedClient<TSchema>;
+/**
+ * Get the raw database adapter from context.
+ * Use this when you need direct adapter access (e.g., for transactions).
+ *
+ * @param context - The request context from EreoJS
+ * @returns The database adapter
+ * @throws Error if database plugin is not configured
+ */
+export declare function useAdapter<TSchema = unknown>(context: AppContext): DatabaseAdapter<TSchema>;
+/**
+ * Get the default registered database adapter.
+ * Use this outside of request context when you need database access.
+ *
+ * @returns The default database adapter or undefined
+ *
+ * @example
+ * // In a script or background job
+ * const adapter = getDb();
+ * if (adapter) {
+ *   const users = await adapter.getClient().select().from(users);
+ * }
+ */
+export declare function getDb<TSchema = unknown>(): DatabaseAdapter<TSchema> | undefined;
+/**
+ * Run a function within a database transaction using request context.
+ * Convenience wrapper around adapter.transaction().
+ *
+ * @param context - The request context
+ * @param fn - Function to run within the transaction
+ * @returns The result of the function
+ *
+ * @example
+ * export const action = createAction({
+ *   async run({ context }) {
+ *     return withTransaction(context, async (tx) => {
+ *       await tx.insert(users).values({ name: 'Alice' });
+ *       await tx.insert(profiles).values({ userId: 1 });
+ *       return { success: true };
+ *     });
+ *   },
+ * });
+ */
+export declare function withTransaction<TSchema, TResult>(context: AppContext, fn: (tx: TSchema) => Promise<TResult>): Promise<TResult>;
+//# sourceMappingURL=plugin.d.ts.map

package/dist/plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACrD,OAAO,KAAK,EAAE,eAAe,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAiBtE;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC;;;OAGG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAE1B;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAE1B;;;OAGG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAC1C,OAAO,EAAE,eAAe,CAAC,OAAO,CAAC,EACjC,OAAO,GAAE,qBAA0B,GAClC,MAAM,CAsDR;AAMD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,KAAK,CAAC,OAAO,GAAG,OAAO,EACrC,OAAO,EAAE,UAAU,GAClB,mBAAmB,CAAC,OAAO,CAAC,CAW9B;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,OAAO,GAAG,OAAO,EAC1C,OAAO,EAAE,UAAU,GAClB,eAAe,CAAC,OAAO,CAAC,CAW1B;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,KAAK,CAAC,OAAO,GAAG,OAAO,KAAK,eAAe,CAAC,OAAO,CAAC,GAAG,SAAS,CAE/E;AAMD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,eAAe,CAAC,OAAO,EAAE,OAAO,EACpD,OAAO,EAAE,UAAU,EACnB,EAAE,EAAE,CAAC,EAAE,EAAE,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC,GACpC,OAAO,CAAC,OAAO,CAAC,CAWlB"}