@nextlyhq/adapter-drizzle 0.0.1

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 NextlyHQ <info@nextlyhq.com>
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,9 @@
+# @nextlyhq/adapter-drizzle
+
+Internal Drizzle ORM utilities for Nextly's database adapters.
+
+> This package is part of Nextly's internals. It is installed automatically as a dependency of [`nextly`](../nextly). Choose [`@nextlyhq/adapter-postgres`](../adapter-postgres), [`@nextlyhq/adapter-mysql`](../adapter-mysql), or [`@nextlyhq/adapter-sqlite`](../adapter-sqlite) for your project.
+
+## License
+
+[MIT](../../LICENSE.md)

package/dist/adapter-BxJVtttb.d.ts

@@ -0,0 +1,592 @@
+import { S as SupportedDialect, a as SqlParam, T as TableResolver } from './core-CVO7WYDj.js';
+import { T as TransactionContext, e as TransactionOptions, D as DatabaseCapabilities, P as PoolStats, S as SelectOptions, I as InsertOptions, W as WhereClause, U as UpdateOptions, f as DeleteOptions, g as UpsertOptions, a as Migration, d as MigrationResult } from './migration-Qe70wDOC.js';
+import { T as TableDefinition, C as CreateTableOptions, D as DropTableOptions, A as AlterTableOperation, a as AlterTableOptions } from './schema-BIQ0YQZ_.js';
+import { D as DatabaseErrorKind, a as DatabaseError } from './error-um1d_3Uo.js';
+
+/**
+ * Base database adapter abstract class.
+ *
+ * @remarks
+ * This abstract class provides the foundation for all dialect-specific database adapters
+ * (PostgreSQL, MySQL, SQLite). It defines required abstract methods that must be implemented
+ * by subclasses, while providing default implementations for CRUD operations and query building.
+ *
+ * Dialect adapters can override any default method to provide optimized implementations.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Abstract base class for database adapters.
+ *
+ * @remarks
+ * All dialect-specific adapters must extend this class and implement the abstract methods.
+ * Default implementations are provided for CRUD operations, which can be overridden for
+ * optimization or dialect-specific behavior.
+ *
+ * ## Required Implementations
+ *
+ * Subclasses must implement:
+ * - `dialect` - Database dialect identifier
+ * - `connect()` - Establish database connection
+ * - `disconnect()` - Close database connection
+ * - `executeQuery()` - Execute raw SQL query
+ * - `transaction()` - Execute operations within a transaction
+ * - `getCapabilities()` - Report database feature support
+ *
+ * ## Optional Overrides
+ *
+ * Subclasses can override default CRUD methods for optimization:
+ * - `select()`, `selectOne()` - Custom query optimization
+ * - `insert()`, `insertMany()` - Bulk insert optimization
+ * - `update()`, `delete()` - Custom update/delete logic
+ * - `upsert()` - Dialect-specific upsert syntax
+ *
+ * @example
+ * ```typescript
+ * export class PostgresAdapter extends DrizzleAdapter {
+ *   readonly dialect = 'postgresql' as const;
+ *
+ *   async connect() {
+ *     this.pool = new Pool({ connectionString: this.config.url });
+ *     // ... connection logic
+ *   }
+ *
+ *   async executeQuery<T>(sql: string, params?: SqlParam[]) {
+ *     const result = await this.pool.query(sql, params);
+ *     return result.rows as T[];
+ *   }
+ *
+ *   // ... other required methods
+ * }
+ * ```
+ *
+ * @public
+ */
+declare abstract class DrizzleAdapter {
+    /**
+     * Database dialect identifier.
+     *
+     * @remarks
+     * Must be set by subclass to identify the database type.
+     */
+    abstract readonly dialect: SupportedDialect;
+    /**
+     * Establish connection to the database.
+     *
+     * @remarks
+     * This method should be idempotent - calling it multiple times
+     * should not create multiple connections.
+     *
+     * @throws {DatabaseError} If connection fails
+     */
+    abstract connect(): Promise<void>;
+    /**
+     * Close database connection and release resources.
+     *
+     * @remarks
+     * This method should be idempotent - calling it multiple times
+     * should be safe.
+     */
+    abstract disconnect(): Promise<void>;
+    /**
+     * Execute a raw SQL query.
+     *
+     * @param sql - SQL query to execute
+     * @param params - Query parameters
+     * @returns Array of result rows
+     *
+     * @throws {DatabaseError} If query execution fails
+     */
+    abstract executeQuery<T = unknown>(sql: string, params?: SqlParam[]): Promise<T[]>;
+    /**
+     * Execute operations within a database transaction.
+     *
+     * @remarks
+     * The transaction is automatically committed on success or rolled back on error.
+     * Supports nested transactions via savepoints on databases that support them.
+     *
+     * @param callback - Function to execute within transaction
+     * @param options - Transaction options
+     * @returns Result from the callback
+     *
+     * @throws {DatabaseError} If transaction fails
+     */
+    abstract transaction<T>(callback: (ctx: TransactionContext) => Promise<T>, options?: TransactionOptions): Promise<T>;
+    /**
+     * Get database capabilities.
+     *
+     * @remarks
+     * Returns static capability flags for this adapter's dialect.
+     * Used by services to conditionally enable features or implement fallbacks.
+     *
+     * @returns Database capability flags
+     */
+    abstract getCapabilities(): DatabaseCapabilities;
+    /**
+     * Get the raw Drizzle ORM instance for direct queries.
+     *
+     * @remarks
+     * This method provides escape hatch access to the raw Drizzle instance.
+     * Use this when you need to run complex queries that the adapter API
+     * doesn't support, or for legacy code migration.
+     *
+     * **Note:** Prefer using adapter methods when possible as they provide:
+     * - Database-agnostic API
+     * - Consistent error handling
+     * - Proper connection pooling
+     *
+     * @param schema - Optional schema object for typed queries
+     * @returns Raw Drizzle ORM database instance
+     *
+     * @example
+     * ```typescript
+     * // For legacy code that needs direct Drizzle access
+     * const db = adapter.getDrizzle(mySchemas);
+     * const result = await db.insert(users).values({ ... }).returning();
+     * ```
+     */
+    abstract getDrizzle<T = unknown>(schema?: Record<string, unknown>): T;
+    /**
+     * Table resolver for looking up Drizzle table objects by name.
+     * When set, CRUD methods use Drizzle's query API instead of raw SQL.
+     * Set via setTableResolver() after boot-time schema loading.
+     */
+    protected tableResolver: TableResolver | null;
+    /**
+     * Set the table resolver for Drizzle query API support.
+     * When a resolver is set, CRUD methods (select, insert, update, delete, upsert)
+     * will use Drizzle's query API (db.select().from(), etc.) instead of raw SQL
+     * string building. Falls back to raw SQL if the resolver doesn't have the table.
+     *
+     * @param resolver - TableResolver implementation (e.g. SchemaRegistry)
+     */
+    setTableResolver(resolver: TableResolver): void;
+    /**
+     * Get a Drizzle table object by name from the resolver.
+     * Returns null if no resolver is set or table is not found.
+     */
+    protected getTableObject(tableName: string): unknown;
+    /**
+     * Map data keys from SQL column names (snake_case) to Drizzle JS property names (camelCase).
+     * Drizzle schemas define columns as e.g. `createdAt: timestamp("created_at")` — the JS
+     * property is `createdAt` but the SQL column is `created_at`. Services pass snake_case keys
+     * because they match the DB column names. This method maps them to the JS names Drizzle expects.
+     */
+    protected mapDataToColumnNames(tableObj: unknown, data: Record<string, unknown>): Record<string, unknown>;
+    /**
+     * Check if the adapter is currently connected.
+     *
+     * @remarks
+     * Default implementation returns false. Subclasses should override
+     * to provide accurate connection status.
+     *
+     * @returns True if connected, false otherwise
+     */
+    isConnected(): boolean;
+    /**
+     * Get connection pool statistics.
+     *
+     * @remarks
+     * Returns null by default. Subclasses with connection pooling
+     * should override to provide pool statistics.
+     *
+     * @returns Pool statistics or null if not applicable
+     */
+    getPoolStats(): PoolStats | null;
+    /**
+     * Default query timeout in milliseconds.
+     *
+     * @remarks
+     * This value is used by executeWithTimeout() when no explicit timeout
+     * is provided. Subclasses should set this from their config.
+     *
+     * @default 15000 (15 seconds)
+     *
+     * @protected
+     */
+    protected defaultQueryTimeoutMs: number;
+    /**
+     * Execute an async operation with a timeout.
+     *
+     * @remarks
+     * Wraps an async operation with a timeout that aborts if the operation
+     * exceeds the specified duration. Uses Promise.race for clean timeout
+     * handling without memory leaks.
+     *
+     * When the timeout is reached, a DatabaseError with kind 'timeout' is thrown.
+     * Note that this does NOT cancel the underlying database query - it only
+     * prevents the calling code from waiting indefinitely. For true query
+     * cancellation, use database-level statement timeouts (PostgreSQL) or
+     * similar mechanisms.
+     *
+     * @param operation - Async operation to execute
+     * @param timeoutMs - Timeout in milliseconds (defaults to defaultQueryTimeoutMs)
+     * @returns Result of the operation
+     *
+     * @throws {DatabaseError} With kind 'timeout' if operation exceeds timeout
+     *
+     * @example
+     * ```typescript
+     * // Use default timeout
+     * const result = await adapter.executeWithTimeout(
+     *   () => adapter.select('users', { limit: 1000 })
+     * );
+     *
+     * // Use custom timeout for specific operation
+     * const result = await adapter.executeWithTimeout(
+     *   () => adapter.select('large_table'),
+     *   60000 // 60 seconds for large queries
+     * );
+     * ```
+     *
+     * @public
+     */
+    executeWithTimeout<T>(operation: () => Promise<T>, timeoutMs?: number): Promise<T>;
+    /**
+     * Set the default query timeout.
+     *
+     * @remarks
+     * This method allows runtime configuration of the default timeout.
+     * Subclasses should call this in their constructor or connect() method
+     * based on their configuration.
+     *
+     * @param timeoutMs - Timeout in milliseconds (0 to disable)
+     *
+     * @protected
+     */
+    protected setDefaultQueryTimeout(timeoutMs: number): void;
+    /**
+     * Get the current default query timeout.
+     *
+     * @returns Current default timeout in milliseconds
+     *
+     * @public
+     */
+    getDefaultQueryTimeout(): number;
+    /**
+     * Select multiple records from a table.
+     *
+     * @remarks
+     * Default implementation builds a SELECT query and executes it.
+     * Subclasses can override for optimization or dialect-specific features.
+     *
+     * @param table - Table name
+     * @param options - Select options (filtering, sorting, pagination)
+     * @returns Array of matching records
+     *
+     * @throws {DatabaseError} If query fails
+     *
+     * @example
+     * ```typescript
+     * const users = await adapter.select('users', {
+     *   where: { and: [{ column: 'role', op: '=', value: 'admin' }] },
+     *   orderBy: [{ column: 'created_at', direction: 'desc' }],
+     *   limit: 10
+     * });
+     * ```
+     */
+    select<T = unknown>(table: string, options?: SelectOptions): Promise<T[]>;
+    /**
+     * Select a single record from a table.
+     *
+     * @remarks
+     * Default implementation uses `select()` with limit 1 and returns first result.
+     * Returns null if no matching record is found.
+     *
+     * @param table - Table name
+     * @param options - Select options
+     * @returns First matching record or null
+     *
+     * @throws {DatabaseError} If query fails
+     *
+     * @example
+     * ```typescript
+     * const user = await adapter.selectOne('users', {
+     *   where: { and: [{ column: 'email', op: '=', value: 'user@example.com' }] }
+     * });
+     * ```
+     */
+    selectOne<T = unknown>(table: string, options?: SelectOptions): Promise<T | null>;
+    /**
+     * Insert a single record into a table.
+     *
+     * @remarks
+     * Default implementation handles databases with and without RETURNING support.
+     * For databases without RETURNING (MySQL), performs INSERT followed by SELECT.
+     *
+     * @param table - Table name
+     * @param data - Record data to insert
+     * @param options - Insert options
+     * @returns Inserted record (with RETURNING columns if specified)
+     *
+     * @throws {DatabaseError} If insert fails
+     *
+     * @example
+     * ```typescript
+     * const user = await adapter.insert('users', {
+     *   email: 'user@example.com',
+     *   name: 'John Doe'
+     * }, { returning: ['id', 'email', 'created_at'] });
+     * ```
+     */
+    insert<T = unknown>(table: string, data: Record<string, unknown>, options?: InsertOptions): Promise<T>;
+    /**
+     * Insert multiple records into a table.
+     *
+     * @remarks
+     * Default implementation performs individual inserts in sequence.
+     * Subclasses can override for bulk insert optimization (e.g., COPY in PostgreSQL).
+     *
+     * @param table - Table name
+     * @param data - Array of records to insert
+     * @param options - Insert options
+     * @returns Inserted records (with RETURNING columns if specified)
+     *
+     * @throws {DatabaseError} If insert fails
+     *
+     * @example
+     * ```typescript
+     * const users = await adapter.insertMany('users', [
+     *   { email: 'user1@example.com', name: 'User 1' },
+     *   { email: 'user2@example.com', name: 'User 2' }
+     * ], { returning: ['id'] });
+     * ```
+     */
+    insertMany<T = unknown>(table: string, data: Record<string, unknown>[], options?: InsertOptions): Promise<T[]>;
+    /**
+     * Update records in a table.
+     *
+     * @remarks
+     * Default implementation builds an UPDATE query with WHERE clause.
+     * Returns updated records if RETURNING is supported and requested.
+     *
+     * @param table - Table name
+     * @param data - Data to update
+     * @param where - Conditions for records to update
+     * @param options - Update options
+     * @returns Updated records (with RETURNING columns if specified)
+     *
+     * @throws {DatabaseError} If update fails
+     *
+     * @example
+     * ```typescript
+     * const updated = await adapter.update('users',
+     *   { status: 'active' },
+     *   { and: [{ column: 'id', op: '=', value: userId }] },
+     *   { returning: ['id', 'status', 'updated_at'] }
+     * );
+     * ```
+     */
+    update<T = unknown>(table: string, data: Record<string, unknown>, where: WhereClause, options?: UpdateOptions): Promise<T[]>;
+    /**
+     * Delete records from a table.
+     *
+     * @remarks
+     * Default implementation builds a DELETE query with WHERE clause.
+     * Returns the number of deleted records.
+     *
+     * @param table - Table name
+     * @param where - Conditions for records to delete
+     * @param options - Delete options
+     * @returns Number of deleted records
+     *
+     * @throws {DatabaseError} If delete fails
+     *
+     * @example
+     * ```typescript
+     * const count = await adapter.delete('users', {
+     *   and: [{ column: 'status', op: '=', value: 'inactive' }]
+     * });
+     * console.log(`Deleted ${count} users`);
+     * ```
+     */
+    delete(table: string, where: WhereClause, _options?: DeleteOptions): Promise<number>;
+    /**
+     * Upsert (INSERT or UPDATE) a record.
+     *
+     * @remarks
+     * Default implementation uses dialect-specific ON CONFLICT syntax.
+     * PostgreSQL/SQLite: ON CONFLICT ... DO UPDATE
+     * MySQL: ON DUPLICATE KEY UPDATE
+     *
+     * @param table - Table name
+     * @param data - Record data
+     * @param options - Upsert options (must specify conflict columns)
+     * @returns Upserted record (with RETURNING columns if specified)
+     *
+     * @throws {DatabaseError} If upsert fails
+     *
+     * @example
+     * ```typescript
+     * const user = await adapter.upsert('users', {
+     *   email: 'user@example.com',
+     *   name: 'Updated Name'
+     * }, {
+     *   conflictColumns: ['email'],
+     *   updateColumns: ['name'],
+     *   returning: ['id', 'email', 'name']
+     * });
+     * ```
+     */
+    upsert<T = unknown>(table: string, data: Record<string, unknown>, options: UpsertOptions): Promise<T>;
+    /**
+     * Run pending migrations.
+     *
+     * @remarks
+     * Default implementation is a placeholder. Subclasses should implement
+     * migration tracking and execution logic.
+     *
+     * @param migrations - Array of migrations to run
+     * @returns Migration result with applied and pending migrations
+     *
+     * @throws {DatabaseError} If migration fails
+     */
+    migrate(_migrations: Migration[]): Promise<MigrationResult>;
+    /**
+     * Rollback the last migration.
+     *
+     * @remarks
+     * Default implementation is a placeholder. Subclasses should implement
+     * migration rollback logic.
+     *
+     * @returns Migration result after rollback
+     *
+     * @throws {DatabaseError} If rollback fails
+     */
+    rollback(): Promise<MigrationResult>;
+    /**
+     * Get migration status.
+     *
+     * @remarks
+     * Default implementation is a placeholder. Subclasses should implement
+     * migration status checking.
+     *
+     * @returns Current migration status
+     *
+     * @throws {DatabaseError} If status check fails
+     */
+    getMigrationStatus(): Promise<MigrationResult>;
+    /**
+     * Create a new table.
+     *
+     * @remarks
+     * Default implementation is a placeholder. Subclasses should implement
+     * table creation logic.
+     *
+     * @param definition - Table definition
+     * @param options - Creation options
+     *
+     * @throws {DatabaseError} If table creation fails
+     */
+    createTable(definition: TableDefinition, options?: CreateTableOptions): Promise<void>;
+    /**
+     * Drop a table.
+     *
+     * @remarks
+     * Default implementation is a placeholder. Subclasses should implement
+     * table dropping logic.
+     *
+     * @param tableName - Name of table to drop
+     * @param options - Drop options
+     *
+     * @throws {DatabaseError} If table drop fails
+     */
+    dropTable(tableName: string, options?: DropTableOptions): Promise<void>;
+    /**
+     * Alter an existing table.
+     *
+     * @remarks
+     * Default implementation is a placeholder. Subclasses should implement
+     * table alteration logic.
+     *
+     * @param tableName - Name of table to alter
+     * @param operations - Alteration operations
+     * @param options - Alter options
+     *
+     * @throws {DatabaseError} If table alteration fails
+     */
+    alterTable(tableName: string, operations: AlterTableOperation[], _options?: AlterTableOptions): Promise<void>;
+    /**
+     * Check if a table exists in the database.
+     *
+     * @remarks
+     * Uses dialect-specific information schema queries to check table existence.
+     * This is useful for development mode auto-sync to determine whether to
+     * CREATE or DROP/CREATE tables.
+     *
+     * @param tableName - Name of table to check
+     * @param schema - Optional schema name (defaults to 'public' for PostgreSQL)
+     * @returns True if table exists, false otherwise
+     *
+     * @throws {DatabaseError} If query fails
+     *
+     * @example
+     * ```typescript
+     * const exists = await adapter.tableExists('users');
+     * if (exists) {
+     *   await adapter.dropTable('users');
+     * }
+     * await adapter.createTable(userTableDef);
+     * ```
+     */
+    tableExists(tableName: string, schema?: string): Promise<boolean>;
+    /**
+     * Get list of all tables in the database.
+     *
+     * @remarks
+     * Uses dialect-specific information schema queries to list tables.
+     * Useful for detecting orphaned tables or validating schema state.
+     *
+     * @param schema - Optional schema name (defaults to 'public' for PostgreSQL)
+     * @returns Array of table names
+     *
+     * @throws {DatabaseError} If query fails
+     */
+    listTables(schema?: string): Promise<string[]>;
+    /**
+     * Escape a table or column identifier.
+     *
+     * @remarks
+     * Default uses double quotes (SQL standard).
+     * MySQL adapter should override to use backticks.
+     *
+     * @param identifier - Identifier to escape
+     * @returns Escaped identifier
+     *
+     * @protected
+     */
+    protected escapeIdentifier(identifier: string): string;
+    /**
+     * Create a DatabaseError with proper error kind classification.
+     *
+     * @remarks
+     * Protected helper for subclasses to create consistent errors.
+     * Subclasses can override to add dialect-specific error classification.
+     *
+     * @param kind - Error kind
+     * @param message - Error message
+     * @param cause - Original error
+     * @returns DatabaseError instance
+     *
+     * @protected
+     */
+    protected createDatabaseError(kind: DatabaseErrorKind, message: string, cause?: Error): DatabaseError;
+    /**
+     * Handle query errors and convert to DatabaseError.
+     *
+     * @remarks
+     * Protected helper for consistent error handling across CRUD operations.
+     * Subclasses can override to add dialect-specific error classification.
+     *
+     * @param error - Original error
+     * @param operation - Operation that failed
+     * @param table - Table name
+     * @returns DatabaseError instance
+     *
+     * @protected
+     */
+    protected handleQueryError(error: unknown, operation: string, table: string): DatabaseError;
+}
+
+export { DrizzleAdapter as D };