@nextlyhq/adapter-drizzle 0.0.2-alpha.6 → 0.0.2-alpha.62

package/dist/{adapter-BxJVtttb.d.ts → adapter-BRvxUZrS.d.ts}

@@ -1,68 +1,49 @@
+import { AnyRelations, SQL } from 'drizzle-orm';
+import { T as TransactionContext, S as SelectOptions, W as WhereClause, U as UpdateOptions, D as DeleteOptions, e as UpsertOptions, f as TransactionOptions, g as DatabaseCapabilities, P as PoolStats, I as InsertOptions, a as Migration, d as MigrationResult } from './migration-BnT96HFp.js';
 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';
+import { D as DatabaseErrorKind, a as DatabaseError } from './error-BrdknH2s.js';
 
 /**
- * Base database adapter abstract class.
+ * Transaction CRUD forwarder helper for database adapters.
  *
  * @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.
+ * Encapsulates the delegation pattern where a transaction context forwards its
+ * CRUD methods to the adapter's implementation while passing the transaction-bound
+ * Drizzle executor.
  *
  * @packageDocumentation
  */
 
 /**
- * Abstract base class for database adapters.
+ * Interface representing an adapter that can execute CRUD operations with an optional executor.
+ */
+interface TransactionCrudDelegator {
+    select<T = unknown>(table: string, options?: SelectOptions, executor?: unknown): Promise<T[]>;
+    selectOne<T = unknown>(table: string, options?: SelectOptions, executor?: unknown): Promise<T | null>;
+    update<T = unknown>(table: string, data: Record<string, unknown>, where: WhereClause, options?: UpdateOptions, executor?: unknown): Promise<T[]>;
+    updateCount(table: string, data: Record<string, unknown>, where: WhereClause, executor?: unknown): Promise<number>;
+    delete(table: string, where: WhereClause, options?: DeleteOptions, executor?: unknown): Promise<number>;
+    upsert<T = unknown>(table: string, data: Record<string, unknown>, options: UpsertOptions, executor?: unknown): Promise<T>;
+}
+/**
+ * Transaction context CRUD methods provided by the forwarder.
+ */
+type TransactionCrudForwarders = Pick<TransactionContext, "select" | "selectOne" | "update" | "updateCount" | "delete" | "upsert" | "getDrizzle">;
+
+/**
+ * Base database adapter abstract class.
  *
  * @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[];
- *   }
+ * 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.
  *
- *   // ... other required methods
- * }
- * ```
+ * Dialect adapters can override any default method to provide optimized implementations.
  *
- * @public
+ * @packageDocumentation
  */
+
 declare abstract class DrizzleAdapter {
     /**
      * Database dialect identifier.
@@ -106,11 +87,29 @@ declare abstract class DrizzleAdapter {
      * The transaction is automatically committed on success or rolled back on error.
      * Supports nested transactions via savepoints on databases that support them.
      *
+     * Two kinds of error leave this method, and a caller has to be able to tell
+     * them apart. An error carrying the Nextly application brand — see
+     * `isApplicationError` — arrives exactly as it was thrown, because that is
+     * the application refusing the write rather than the database failing to
+     * perform it, and rewriting it would discard the code and payload the caller
+     * is meant to act on.
+     *
+     * Everything else arrives as a `DatabaseError` with its kind classified, and
+     * that deliberately includes an unbranded error the callback itself threw:
+     * the brand is the only thing distinguishing a deliberate refusal from a
+     * driver failure that surfaced through callback code, and guessing from the
+     * throw site would put raw driver text on the wire under a caller's own
+     * error shape.
+     *
+     * The rollback is the same either way.
+     *
      * @param callback - Function to execute within transaction
      * @param options - Transaction options
      * @returns Result from the callback
      *
-     * @throws {DatabaseError} If transaction fails
+     * @throws {DatabaseError} If the transaction itself fails, or if the callback
+     * threw an error that does not carry the application brand
+     * @throws The callback's own error, unchanged, when it carries that brand
      */
     abstract transaction<T>(callback: (ctx: TransactionContext) => Promise<T>, options?: TransactionOptions): Promise<T>;
     /**
@@ -136,17 +135,18 @@ declare abstract class DrizzleAdapter {
      * - Consistent error handling
      * - Proper connection pooling
      *
-     * @param schema - Optional schema object for typed queries
+     * @param relations - Optional drizzle v1 relations config (defineRelations
+     *   output) that enables the typed relational query API on the instance
      * @returns Raw Drizzle ORM database instance
      *
      * @example
      * ```typescript
      * // For legacy code that needs direct Drizzle access
-     * const db = adapter.getDrizzle(mySchemas);
+     * const db = adapter.getDrizzle(myRelations); // defineRelations output
      * const result = await db.insert(users).values({ ... }).returning();
      * ```
      */
-    abstract getDrizzle<T = unknown>(schema?: Record<string, unknown>): T;
+    abstract getDrizzle<T = unknown>(relations?: AnyRelations): T;
     /**
      * Table resolver for looking up Drizzle table objects by name.
      * When set, CRUD methods use Drizzle's query API instead of raw SQL.
@@ -167,6 +167,27 @@ declare abstract class DrizzleAdapter {
      * Returns null if no resolver is set or table is not found.
      */
     protected getTableObject(tableName: string): unknown;
+    /**
+     * Run a Drizzle-built statement and return its rows.
+     *
+     * @remarks
+     * The CRUD methods resolve their table through the schema registry and reject
+     * any name it does not declare, which leaves no way to read from a table the
+     * ORM does not know — one mid-rename, above all — except by assembling SQL and
+     * quoting identifiers by hand. This takes Drizzle's `sql` template instead, so
+     * the dialect in use decides the quoting and the parameter binding.
+     *
+     * Concrete rather than abstract so existing adapters keep working unchanged.
+     * The three drivers disagree about both the call and the result: node-postgres
+     * returns `{ rows }`, mysql2 a `[rows, fields]` tuple, and better-sqlite3 has
+     * no `execute` at all and answers `all`. Keeping that here rather than at each
+     * call site is the point — a caller reasoning about it would be reasoning
+     * about a driver it cannot see.
+     *
+     * @param statement - Drizzle `sql` template to run
+     * @returns Rows the statement produced
+     */
+    queryStatement<T = Record<string, unknown>>(statement: SQL): Promise<T[]>;
     /**
      * 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
@@ -174,6 +195,131 @@ declare abstract class DrizzleAdapter {
      * 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>;
+    /**
+     * Map data keys from Drizzle JS property names to SQL column names for the
+     * raw-SQL transaction insert path. The transaction context builds INSERT
+     * statements from Object.keys(data) used directly as column identifiers, so a
+     * table whose Drizzle property names differ from its SQL column names
+     * (camelCase core tables like nextly_versions) needs its keys translated
+     * first. For tables whose property names already equal their column names
+     * (the dynamic dc_/single_/comp_ tables) every lookup is identity, so
+     * existing callers are unaffected.
+     */
+    protected mapKeysToSqlColumns(tableObj: unknown, data: Record<string, unknown>): Record<string, unknown>;
+    /**
+     * Map a list of column identifiers (Drizzle property names) to their SQL
+     * column names, for the raw-SQL transaction insert paths that build a
+     * RETURNING clause from `options.returning`. Same identity behavior as
+     * `mapKeysToSqlColumns`: names that are already SQL columns (the dynamic
+     * dc_/single_/comp_ tables) pass through unchanged.
+     */
+    protected mapColumnNamesToSql(tableObj: unknown, names: string[]): string[];
+    /**
+     * Remap a raw-SQL result row's KEYS from SQL column names to Drizzle property
+     * names, so the raw-SQL transaction insert paths return the same key casing
+     * as the non-transactional (Drizzle) insert. Keys only - values are left
+     * untouched, so this does not change how JSON/date columns are decoded. For
+     * tables whose property names already equal their SQL columns (the dynamic
+     * dc_/single_/comp_ tables) every lookup is identity, so existing callers see
+     * no change.
+     */
+    protected mapRowKeysToJs<T = unknown>(tableObj: unknown, row: T): T;
+    /**
+     * Decode a raw-SQL result row's DATE column values the way a Drizzle query
+     * would, so a write answers with the same representation a read of the same
+     * column gives.
+     *
+     * A Drizzle query path runs every value through its column definition; a
+     * raw-SQL path does not, so a dialect that stores a timestamp as a number
+     * answers a write with that number while every read answers a `Date`. Only
+     * date columns are touched, and a value that is already a `Date` is left
+     * alone, so a driver that decodes on its own is unaffected.
+     *
+     * Runs after {@link mapRowKeysToJs}: keys are Drizzle property names by then,
+     * which is what the table definition is keyed by.
+     */
+    protected mapDateValuesFromDriver<T = unknown>(tableObj: unknown, row: T): T;
+    /**
+     * Encode a row's DATE values the way a Drizzle query would before binding
+     * them, so what lands in the column does not depend on the server's timezone.
+     *
+     * A column declared without a time zone stores a wall clock and records
+     * nothing about which zone it belongs to, so both ends have to agree. Drizzle
+     * writes UTC and reads UTC. A driver handed a `Date` writes the LOCAL wall
+     * clock instead, and the same row then reads back shifted by the offset --
+     * on a UTC server the two agree and nothing is visibly wrong, which is why
+     * this survives CI.
+     *
+     * Only date columns are touched. A value that is not a `Date` is left as it
+     * is, so a caller that already encoded one is not encoded twice.
+     *
+     * Keys may be spelled either way at this point, so both the Drizzle property
+     * name and the SQL column name resolve.
+     */
+    protected mapDateValuesToDriver(tableObj: unknown, data: Record<string, unknown>): Record<string, unknown>;
+    /**
+     * Bring a row about to be written through a raw-SQL statement into the shape
+     * a Drizzle query would have bound: SQL column names for keys, encoded values
+     * for date columns.
+     *
+     * The mirror of {@link mapRowFromRawSql}. The raw-SQL write paths exist
+     * because a dialect needs SQL a Drizzle query cannot express, not because
+     * their callers want different values in the table.
+     */
+    protected mapRowToRawSql(tableObj: unknown, data: Record<string, unknown>): Record<string, unknown>;
+    /**
+     * Bring a raw-SQL result row into the shape a Drizzle query would have
+     * produced: Drizzle property names for keys, decoded values for date columns.
+     *
+     * The raw-SQL write paths exist because a dialect needs SQL a Drizzle query
+     * cannot express, not because their callers want a different row shape, so
+     * every one of them ends here.
+     */
+    protected mapRowFromRawSql<T = unknown>(tableObj: unknown, row: T, aliases?: ReadonlyArray<{
+        alias: string;
+        jsName: string;
+    }>): T;
+    /**
+     * The date columns a statement is about to return, and the alias each one's
+     * wall clock is spelled out under.
+     *
+     * A driver turns a timestamp into a `Date` using ITS zone before any of this
+     * code runs, and that conversion is lossy: a wall clock inside a
+     * daylight-saving gap is a local time that does not exist, so the driver
+     * normalizes it and the original is gone. Asking the database for the wall
+     * clock as text alongside the row is the only way to read it exactly.
+     *
+     * `"*"` covers every date column; a projection covers only the ones it asked
+     * for, so a caller still gets back what it requested and nothing more.
+     */
+    protected dateWallClockAliases(tableObj: unknown, returning: string[] | "*" | undefined): Array<{
+        sqlName: string;
+        alias: string;
+        jsName: string;
+    }>;
+    /**
+     * Replace each date in a row with the wall clock the database spelled out,
+     * read as UTC, and drop the aliases that carried it.
+     *
+     * The statement writes a UTC wall clock, so reading one back as UTC is what
+     * makes a write and a later read agree. Whatever the column actually stored
+     * is what arrives -- a column keeping only whole seconds reports whole
+     * seconds -- because this is the database's own text, not a value
+     * reconstructed from the one that was bound.
+     */
+    protected applyWallClockAliases<T>(row: T, aliases: ReadonlyArray<{
+        alias: string;
+        jsName: string;
+    }>): T;
+    /**
+     * Build a Drizzle column projection object (`{ propertyName: column }`) from a
+     * requested column list, used by `select` (columns) and `insert` (returning).
+     * A requested name resolves against either the Drizzle property name
+     * (camelCase) or the SQL column name (snake_case); the projection is keyed by
+     * the property name so the row shape matches a full select. Returns undefined
+     * for `"*"` or when nothing resolves, so callers fall back to all columns.
+     */
+    protected buildColumnProjection(tableObj: unknown, names: string[] | "*" | undefined): Record<string, unknown> | undefined;
     /**
      * Check if the adapter is currently connected.
      *
@@ -286,7 +432,7 @@ declare abstract class DrizzleAdapter {
      * });
      * ```
      */
-    select<T = unknown>(table: string, options?: SelectOptions): Promise<T[]>;
+    select<T = unknown>(table: string, options?: SelectOptions, executor?: unknown): Promise<T[]>;
     /**
      * Select a single record from a table.
      *
@@ -307,7 +453,7 @@ declare abstract class DrizzleAdapter {
      * });
      * ```
      */
-    selectOne<T = unknown>(table: string, options?: SelectOptions): Promise<T | null>;
+    selectOne<T = unknown>(table: string, options?: SelectOptions, executor?: unknown): Promise<T | null>;
     /**
      * Insert a single record into a table.
      *
@@ -378,7 +524,24 @@ declare abstract class DrizzleAdapter {
      * );
      * ```
      */
-    update<T = unknown>(table: string, data: Record<string, unknown>, where: WhereClause, options?: UpdateOptions): Promise<T[]>;
+    update<T = unknown>(table: string, data: Record<string, unknown>, where: WhereClause, options?: UpdateOptions, executor?: unknown): Promise<T[]>;
+    /**
+     * Update records in a table and report how many rows the statement affected.
+     *
+     * The count is the whole return value, mirroring `delete`. `update` cannot answer this: without
+     * `returning` it discards the driver's count, and WITH `returning` on a dialect that lacks
+     * RETURNING it re-SELECTs using the same WHERE — so a conditional update that just changed a
+     * column named in that WHERE reads back zero rows and a write that landed reports as unmatched.
+     * Reading the driver's own count has no second query to disagree with the first.
+     *
+     * 🔴 MySQL reports CHANGED rows, not matched rows: an UPDATE that matches a row but writes values
+     * identical to what it holds counts zero. A caller using this as a compare-and-set must therefore
+     * include a column the write always moves — a version bump, a timestamp with enough resolution —
+     * so that matched implies changed. Postgres (`rowCount`) and SQLite (`changes`) count matched
+     * rows and do not need the precaution, which is exactly why it cannot be dropped: the dialect
+     * where the distinction exists is the one with no RETURNING to fall back on.
+     */
+    updateCount(table: string, data: Record<string, unknown>, where: WhereClause, executor?: unknown): Promise<number>;
     /**
      * Delete records from a table.
      *
@@ -401,7 +564,7 @@ declare abstract class DrizzleAdapter {
      * console.log(`Deleted ${count} users`);
      * ```
      */
-    delete(table: string, where: WhereClause, _options?: DeleteOptions): Promise<number>;
+    delete(table: string, where: WhereClause, _options?: DeleteOptions, executor?: unknown): Promise<number>;
     /**
      * Upsert (INSERT or UPDATE) a record.
      *
@@ -429,7 +592,7 @@ declare abstract class DrizzleAdapter {
      * });
      * ```
      */
-    upsert<T = unknown>(table: string, data: Record<string, unknown>, options: UpsertOptions): Promise<T>;
+    upsert<T = unknown>(table: string, data: Record<string, unknown>, options: UpsertOptions, executor?: unknown): Promise<T>;
     /**
      * Run pending migrations.
      *
@@ -572,12 +735,35 @@ declare abstract class DrizzleAdapter {
      * @protected
      */
     protected createDatabaseError(kind: DatabaseErrorKind, message: string, cause?: Error): DatabaseError;
+    /**
+     * Helper to create transaction context CRUD forwarding methods.
+     *
+     * @param txDb - Thunk returning the transaction-bound Drizzle executor
+     * @returns Object providing forwarded CRUD and getDrizzle methods
+     *
+     * @protected
+     */
+    protected createTransactionForwarders(txDb: () => unknown): TransactionCrudForwarders;
+    /**
+     * Classify an error into a DatabaseError.
+     *
+     * @remarks
+     * Subclasses can override this method to add dialect-specific error code classification.
+     *
+     * @param error - Original error
+     * @param sql - SQL statement that caused the error (optional)
+     * @returns DatabaseError instance
+     *
+     * @protected
+     */
+    protected classifyError(error: unknown, sql?: string): 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.
+     * Delegates to `classifyError` and attaches operation and table context if not present.
+     * Subclasses override `classifyError` to provide dialect-specific error code classification.
      *
      * @param error - Original error
      * @param operation - Operation that failed
@@ -589,4 +775,4 @@ declare abstract class DrizzleAdapter {
     protected handleQueryError(error: unknown, operation: string, table: string): DatabaseError;
 }
 
-export { DrizzleAdapter as D };
+export { DrizzleAdapter as D, type TransactionCrudDelegator as T, type TransactionCrudForwarders as a };