@ereo/db 0.1.6

package/dist/adapter.d.ts

@@ -0,0 +1,151 @@
+/**
+ * @ereo/db - Database Adapter Interface
+ *
+ * Core abstraction for ORM-agnostic database operations.
+ * Adapters implement this interface to provide consistent access patterns.
+ */
+import type { AppContext } from '@ereo/core';
+import type { QueryResult, MutationResult, DedupResult, DedupStats, TransactionOptions, AdapterConfig, HealthCheckResult } from './types';
+/**
+ * Request-scoped database client with query deduplication.
+ * Created per-request and provides automatic caching of identical queries.
+ */
+export interface RequestScopedClient<TSchema> {
+    /**
+     * The underlying database client (e.g., Drizzle instance).
+     * Use this for building and executing queries.
+     */
+    readonly client: TSchema;
+    /**
+     * Execute a raw SQL query with automatic deduplication.
+     * Identical queries within the same request are cached.
+     */
+    query<T = unknown>(sql: string, params?: unknown[]): Promise<DedupResult<QueryResult<T>>>;
+    /**
+     * Get deduplication statistics for this request.
+     */
+    getDedupStats(): DedupStats;
+    /**
+     * Clear the deduplication cache.
+     * Call this after mutations to ensure fresh data.
+     */
+    clearDedup(): void;
+    /**
+     * Mark that a mutation has occurred, clearing relevant cache entries.
+     * Optionally specify table names to clear only related queries.
+     */
+    invalidate(tables?: string[]): void;
+}
+/**
+ * Core database adapter interface.
+ * All ORM adapters (Drizzle, Prisma, Kysely) implement this interface.
+ *
+ * @template TSchema - The schema type (e.g., Drizzle's `typeof schema`)
+ */
+export interface DatabaseAdapter<TSchema = unknown> {
+    /**
+     * Human-readable adapter name (e.g., 'drizzle-postgres', 'prisma').
+     */
+    readonly name: string;
+    /**
+     * Whether this adapter is compatible with edge runtimes.
+     * Edge-compatible adapters can run in Cloudflare Workers, Vercel Edge, etc.
+     */
+    readonly edgeCompatible: boolean;
+    /**
+     * Get the underlying database client.
+     * For Drizzle, this returns the Drizzle instance.
+     * Use this for direct database operations outside of request context.
+     */
+    getClient(): TSchema;
+    /**
+     * Get a request-scoped client with query deduplication.
+     * Call this in middleware/loaders to get per-request caching.
+     *
+     * @param context - The request context from EreoJS
+     */
+    getRequestClient(context: AppContext): RequestScopedClient<TSchema>;
+    /**
+     * Execute a raw SQL query.
+     *
+     * @param sql - The SQL query string
+     * @param params - Query parameters for parameterized queries
+     */
+    query<T = unknown>(sql: string, params?: unknown[]): Promise<QueryResult<T>>;
+    /**
+     * Execute a raw SQL statement that modifies data.
+     *
+     * @param sql - The SQL statement (INSERT, UPDATE, DELETE)
+     * @param params - Statement parameters
+     */
+    execute(sql: string, params?: unknown[]): Promise<MutationResult>;
+    /**
+     * Run operations within a transaction.
+     * Automatically handles commit on success and rollback on error.
+     *
+     * @param fn - Function receiving the transaction client
+     * @param options - Transaction configuration
+     */
+    transaction<T>(fn: (tx: TSchema) => Promise<T>, options?: TransactionOptions): Promise<T>;
+    /**
+     * Begin a manual transaction.
+     * Returns a transaction object that must be committed or rolled back.
+     *
+     * @param options - Transaction configuration
+     */
+    beginTransaction(options?: TransactionOptions): Promise<Transaction<TSchema>>;
+    /**
+     * Check database connectivity and health.
+     */
+    healthCheck(): Promise<HealthCheckResult>;
+    /**
+     * Disconnect from the database and cleanup resources.
+     * Call this on application shutdown.
+     */
+    disconnect(): Promise<void>;
+}
+/**
+ * Manual transaction handle for explicit control.
+ */
+export interface Transaction<TSchema> {
+    /**
+     * The transaction-scoped database client.
+     */
+    readonly client: TSchema;
+    /**
+     * Commit the transaction.
+     */
+    commit(): Promise<void>;
+    /**
+     * Rollback the transaction.
+     */
+    rollback(): Promise<void>;
+    /**
+     * Whether the transaction is still active.
+     */
+    readonly isActive: boolean;
+}
+/**
+ * Factory function type for creating database adapters.
+ */
+export type AdapterFactory<TConfig extends AdapterConfig, TSchema> = (config: TConfig) => DatabaseAdapter<TSchema>;
+/**
+ * Register an adapter instance globally.
+ * Useful for accessing the adapter from anywhere in the application.
+ */
+export declare function registerAdapter<TSchema>(name: string, adapter: DatabaseAdapter<TSchema>): void;
+/**
+ * Get a registered adapter by name.
+ */
+export declare function getAdapter<TSchema = unknown>(name: string): DatabaseAdapter<TSchema> | undefined;
+/**
+ * Get the default registered adapter.
+ * Returns the first registered adapter or undefined if none.
+ */
+export declare function getDefaultAdapter<TSchema = unknown>(): DatabaseAdapter<TSchema> | undefined;
+/**
+ * Clear all registered adapters.
+ * Useful for testing.
+ */
+export declare function clearAdapterRegistry(): void;
+//# sourceMappingURL=adapter.d.ts.map

package/dist/adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"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"}

package/dist/dedup.d.ts

@@ -0,0 +1,70 @@
+/**
+ * @ereo/db - Query Deduplication
+ *
+ * Request-scoped query deduplication using EreoJS's RequestContext.
+ * Automatically caches identical queries within a single request to avoid
+ * redundant database calls (e.g., N+1 queries in nested loaders).
+ */
+import type { AppContext } from '@ereo/core';
+import type { DedupStats, DedupResult } from './types';
+/**
+ * Generate a cache key (fingerprint) for a query.
+ * The fingerprint is deterministic for the same query + params combination.
+ *
+ * @param query - SQL query or query identifier
+ * @param params - Query parameters
+ * @returns A string fingerprint suitable for use as a cache key
+ */
+export declare function generateFingerprint(query: string, params?: unknown[]): string;
+/**
+ * Execute a query with automatic deduplication.
+ * If an identical query was already executed in this request, returns the cached result.
+ *
+ * @param context - The request context
+ * @param query - SQL query or query identifier
+ * @param params - Query parameters
+ * @param executor - Function that executes the actual query
+ * @param options - Additional options for caching behavior
+ * @returns The query result wrapped with dedup metadata
+ */
+export declare function dedupQuery<T>(context: AppContext, query: string, params: unknown[] | undefined, executor: () => Promise<T>, options?: {
+    /** Tables affected by this query (for selective invalidation) */
+    tables?: string[];
+    /** Skip caching for this query */
+    noCache?: boolean;
+}): Promise<DedupResult<T>>;
+/**
+ * Clear the entire dedup cache for a request.
+ * Call this after mutations to ensure subsequent reads get fresh data.
+ *
+ * @param context - The request context
+ */
+export declare function clearDedupCache(context: AppContext): void;
+/**
+ * Invalidate cache entries related to specific tables.
+ * More selective than clearing the entire cache.
+ *
+ * @param context - The request context
+ * @param tables - Table names to invalidate
+ */
+export declare function invalidateTables(context: AppContext, tables: string[]): void;
+/**
+ * Get deduplication statistics for the current request.
+ *
+ * @param context - The request context
+ * @returns Statistics about query deduplication
+ */
+export declare function getRequestDedupStats(context: AppContext): DedupStats;
+/**
+ * Get the current cache contents for debugging.
+ * Only use this in development.
+ *
+ * @param context - The request context
+ * @returns Array of cache entries with their keys
+ */
+export declare function debugGetCacheContents(context: AppContext): Array<{
+    key: string;
+    tables?: string[];
+    age: number;
+}>;
+//# sourceMappingURL=dedup.d.ts.map

package/dist/dedup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dedup.d.ts","sourceRoot":"","sources":["../src/dedup.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAqCvD;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,GAAG,MAAM,CAwB7E;AA8CD;;;;;;;;;;GAUG;AACH,wBAAsB,UAAU,CAAC,CAAC,EAChC,OAAO,EAAE,UAAU,EACnB,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,OAAO,EAAE,GAAG,SAAS,EAC7B,QAAQ,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAC1B,OAAO,CAAC,EAAE;IACR,iEAAiE;IACjE,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,kCAAkC;IAClC,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB,GACA,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CA4CzB;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,UAAU,GAAG,IAAI,CAKzD;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,IAAI,CAc5E;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,UAAU,GAAG,UAAU,CAkBpE;AAMD;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,UAAU,GAClB,KAAK,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC,CAUxD"}

package/dist/index.d.ts

@@ -0,0 +1,41 @@
+/**
+ * @ereo/db - Database Adapter Abstractions
+ *
+ * This package provides ORM-agnostic database abstractions for EreoJS:
+ * - Adapter interface for pluggable database backends
+ * - Query deduplication for request-scoped caching
+ * - Connection pooling primitives
+ * - Type utilities for end-to-end type safety
+ *
+ * @example
+ * // Using with Drizzle adapter
+ * import { createDatabasePlugin, useDb } from '@ereo/db';
+ * import { createDrizzleAdapter } from '@ereo/db-drizzle';
+ *
+ * // In ereo.config.ts
+ * const adapter = createDrizzleAdapter({
+ *   driver: 'postgres-js',
+ *   url: process.env.DATABASE_URL,
+ *   schema,
+ * });
+ *
+ * export default defineConfig({
+ *   plugins: [createDatabasePlugin(adapter)],
+ * });
+ *
+ * // In a route loader
+ * export const loader = createLoader({
+ *   load: async ({ context }) => {
+ *     const db = useDb(context);
+ *     return db.client.select().from(users);
+ *   },
+ * });
+ *
+ * @packageDocumentation
+ */
+export { type DatabaseAdapter, type RequestScopedClient, type Transaction, type AdapterFactory, registerAdapter, getAdapter, getDefaultAdapter, clearAdapterRegistry, } from './adapter';
+export { generateFingerprint, dedupQuery, clearDedupCache, invalidateTables, getRequestDedupStats, debugGetCacheContents, } from './dedup';
+export { ConnectionPool, DEFAULT_POOL_CONFIG, createEdgePoolConfig, createServerlessPoolConfig, withRetry, isCommonRetryableError, DEFAULT_RETRY_CONFIG, type PoolStats, type RetryConfig, } from './pool';
+export { createDatabasePlugin, useDb, useAdapter, getDb, withTransaction, type DatabasePluginOptions, } from './plugin';
+export { type QueryResult, type MutationResult, type DedupResult, type DedupStats, type PoolConfig, type AdapterConfig, type TransactionOptions, type IsolationLevel, type InferSelect, type InferInsert, type DatabaseTables, type TableNames, type TableType, type TypedWhere, type WhereOperator, type TypedOrderBy, type TypedSelect, type HealthCheckResult, DatabaseError, ConnectionError, QueryError, TransactionError, TimeoutError, } from './types';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAMH,OAAO,EAEL,KAAK,eAAe,EACpB,KAAK,mBAAmB,EACxB,KAAK,WAAW,EAChB,KAAK,cAAc,EAEnB,eAAe,EACf,UAAU,EACV,iBAAiB,EACjB,oBAAoB,GACrB,MAAM,WAAW,CAAC;AAMnB,OAAO,EAEL,mBAAmB,EACnB,UAAU,EACV,eAAe,EACf,gBAAgB,EAChB,oBAAoB,EAEpB,qBAAqB,GACtB,MAAM,SAAS,CAAC;AAMjB,OAAO,EAEL,cAAc,EAEd,mBAAmB,EACnB,oBAAoB,EACpB,0BAA0B,EAE1B,SAAS,EACT,sBAAsB,EACtB,oBAAoB,EAEpB,KAAK,SAAS,EACd,KAAK,WAAW,GACjB,MAAM,QAAQ,CAAC;AAMhB,OAAO,EAEL,oBAAoB,EAEpB,KAAK,EACL,UAAU,EACV,KAAK,EAEL,eAAe,EAEf,KAAK,qBAAqB,GAC3B,MAAM,UAAU,CAAC;AAMlB,OAAO,EAEL,KAAK,WAAW,EAChB,KAAK,cAAc,EACnB,KAAK,WAAW,EAChB,KAAK,UAAU,EAEf,KAAK,UAAU,EACf,KAAK,aAAa,EAClB,KAAK,kBAAkB,EACvB,KAAK,cAAc,EAEnB,KAAK,WAAW,EAChB,KAAK,WAAW,EAChB,KAAK,cAAc,EACnB,KAAK,UAAU,EACf,KAAK,SAAS,EAEd,KAAK,UAAU,EACf,KAAK,aAAa,EAClB,KAAK,YAAY,EACjB,KAAK,WAAW,EAEhB,KAAK,iBAAiB,EAEtB,aAAa,EACb,eAAe,EACf,UAAU,EACV,gBAAgB,EAChB,YAAY,GACb,MAAM,SAAS,CAAC"}