@nextlyhq/adapter-mysql 0.0.2-alpha.67 → 0.0.2-alpha.69

package/dist/index.d.ts

@@ -1,49 +1,11 @@
-import { DrizzleAdapter } from '@nextlyhq/adapter-drizzle';
-import { MySqlAdapterConfig, PoolStats, SqlParam, TransactionContext, TransactionOptions, DatabaseCapabilities, UpsertOptions, DatabaseError } from '@nextlyhq/adapter-drizzle/types';
-export { AdapterLogger, BaseAdapterConfig, DatabaseCapabilities, DatabaseError, DatabaseErrorKind, DeleteOptions, InsertOptions, JoinSpec, MySqlAdapterConfig, OrderBySpec, PoolConfig, PoolStats, SelectOptions, SqlParam, SslConfig, TransactionContext, TransactionOptions, UpdateOptions, UpsertOptions, WhereClause, WhereCondition, WhereOperator } from '@nextlyhq/adapter-drizzle/types';
-import { AnyRelations } from 'drizzle-orm';
-import { MySql2Database } from 'drizzle-orm/mysql2';
-
-/**
- * @nextlyhq/adapter-mysql
- *
- * MySQL database adapter for Nextly.
- * Extends DrizzleAdapter from @nextlyhq/adapter-drizzle to provide MySQL-specific functionality.
- *
- * @remarks
- * This adapter uses the mysql2 package for database connectivity and provides:
- * - Connection pooling via mysql2 Pool
- * - Full transaction support with isolation levels
- * - CRUD operations with workarounds for missing RETURNING clause
- * - MySQL-specific error classification
- * - Automatic retry for deadlocks (error 1213)
- *
- * @example
- * ```typescript
- * import { createMySqlAdapter } from '@nextlyhq/adapter-mysql';
- *
- * const adapter = createMySqlAdapter({
- *   url: process.env.DATABASE_URL!,
- * });
- *
- * await adapter.connect();
- *
- * // Query data
- * const users = await adapter.select('users', {
- *   where: { and: [{ column: 'status', op: '=', value: 'active' }] },
- *   limit: 10,
- * });
- *
- * await adapter.disconnect();
- * ```
- *
- * @packageDocumentation
- */
-
+import { DrizzleAdapter } from "@nextlyhq/adapter-drizzle";
+import { AdapterLogger, BaseAdapterConfig, DatabaseCapabilities, DatabaseError, DatabaseErrorKind, DeleteOptions, InsertOptions, JoinSpec, MySqlAdapterConfig, OrderBySpec, PoolConfig, PoolStats, SelectOptions, SqlParam, SslConfig, TransactionContext, TransactionOptions, UpdateOptions, UpsertOptions, WhereClause, WhereCondition, WhereOperator } from "@nextlyhq/adapter-drizzle/types";
+import { AnyRelations } from "drizzle-orm";
+import { MySql2Database } from "drizzle-orm/mysql2";
 /**
  * Package version
  */
-declare const VERSION = "0.1.0";
+export declare const VERSION = "0.1.0";
 /**
  * MySQL database adapter for Nextly.
  *
@@ -68,258 +30,259 @@ declare const VERSION = "0.1.0";
  * await adapter.connect();
  * ```
  */
-declare class MySqlAdapter extends DrizzleAdapter {
-    private drizzleByRelations;
-    private drizzleBare;
-    /**
-     * The database dialect - always 'mysql' for this adapter.
-     */
-    readonly dialect: "mysql";
-    /**
-     * Adapter configuration.
-     */
-    protected readonly config: MySqlAdapterConfig;
-    /**
-     * Connection pool instance.
-     */
-    private pool;
-    /**
-     * Connection state flag.
-     */
-    private connected;
-    /**
-     * Whether the server accepts `SELECT ... FOR SHARE`, read from its version
-     * string at connect. Undefined until then, which callers treat as not known.
-     */
-    private sharedRowLock;
-    /**
-     * Creates a new MySQL adapter instance.
-     *
-     * @param config - Adapter configuration
-     */
-    constructor(config: MySqlAdapterConfig);
-    /**
-     * Connect to the MySQL database.
-     * Creates a connection pool using mysql2.
-     *
-     * @remarks
-     * This method initializes the connection pool and verifies connectivity
-     * by executing a simple query. It is idempotent - calling it multiple
-     * times will not create multiple pools.
-     *
-     * @throws {DatabaseError} If connection fails
-     */
-    connect(): Promise<void>;
-    /**
-     * Disconnect from the MySQL database.
-     * Gracefully closes the connection pool.
-     *
-     * @remarks
-     * This method is idempotent - calling it multiple times is safe.
-     * It waits for all connections to be released before shutting down.
-     */
-    disconnect(): Promise<void>;
-    /**
-     * Check if connected to the database.
-     */
-    isConnected(): boolean;
-    /**
-     * Get connection pool statistics.
-     * Returns null if not connected.
-     *
-     * @remarks
-     * MySQL2 pool exposes different stats than pg:
-     * - _allConnections: all connections
-     * - _freeConnections: idle connections
-     * - _connectionQueue: waiting requests
-     */
-    getPoolStats(): PoolStats | null;
-    /**
-     * Execute a raw SQL query.
-     *
-     * @param sql - SQL query string with ? placeholders
-     * @param params - Query parameters
-     * @returns Query results
-     *
-     * @throws {DatabaseError} If query execution fails
-     */
-    executeQuery<T = unknown>(sql: string, params?: SqlParam[]): Promise<T[]>;
-    /**
-     * Execute work within a transaction.
-     *
-     * @param work - Function containing transactional operations
-     * @param options - Transaction options (isolation level, timeout, retry)
-     * @returns Result of the work function
-     *
-     * @remarks
-     * MySQL transactions support isolation levels. Automatic retry is
-     * implemented for deadlocks (error 1213) when `retryCount` is specified.
-     *
-     * Note: Savepoints are disabled in this adapter for safety due to
-     * MySQL's quirks with nested transactions.
-     */
-    transaction<T>(work: (tx: TransactionContext) => Promise<T>, options?: TransactionOptions): Promise<T>;
-    /** The attempts `transaction` makes, each on a connection of its own. */
-    private runTransactionAttempts;
-    /**
-     * Get MySQL database capabilities.
-     *
-     * @remarks
-     * MySQL has some limitations:
-     * - No JSONB (uses JSON)
-     * - No arrays
-     * - No native ILIKE
-     * - No RETURNING clause
-     * - Savepoints disabled for safety
-     */
-    getCapabilities(): DatabaseCapabilities;
-    /**
-     * Build a placeholder for MySQL (uses ? instead of $1, $2, etc.)
-     *
-     * @param _index - Parameter index (ignored for MySQL)
-     * @returns The ? placeholder
-     */
-    protected buildPlaceholder(_index: number): string;
-    /**
-     * Build multiple placeholders for MySQL.
-     *
-     * @param count - Number of placeholders needed
-     * @param _startIndex - Starting index (ignored for MySQL)
-     * @returns Comma-separated ? placeholders
-     */
-    protected buildPlaceholders(count: number, _startIndex?: number): string;
-    /**
-     * Escape an identifier for MySQL (uses backticks instead of double quotes).
-     *
-     * @param identifier - The identifier to escape
-     * @returns Escaped identifier with backticks
-     */
-    protected escapeIdentifier(identifier: string): string;
-    /**
-     * Ensures pool is connected and returns it.
-     *
-     * @throws {DatabaseError} If not connected
-     */
-    private ensurePool;
-    /**
-     * Return the typed Drizzle instance for MySQL.
-     * Guarded for server-only usage and requires an active connection.
-     *
-     * @param schema - Optional schema for relational queries (db.query.*)
-     * @returns Drizzle ORM instance wrapping the mysql2 pool connection
-     * @throws {Error} If called in browser or not connected
-     */
-    getDrizzle<T = MySql2Database<AnyRelations>>(relations?: AnyRelations): T;
-    /**
-     * A Drizzle handle on the pool, for `getDrizzle`.
-     *
-     * Its `transaction` runs on a connection this adapter checks out and
-     * returns itself (`pinDrizzleTransactions`): destroyed rather than pooled
-     * when no ROLLBACK could be confirmed on it. And it counts for
-     * `transactionOpenInFlow`, as the adapter's does.
-     */
-    private poolDrizzle;
-    /**
-     * Builds mysql2 Pool configuration from adapter config.
-     */
-    private buildPoolConfig;
-    /**
-     * Begins a transaction with the specified options, and returns what it
-     * changed on the session for `restoreSession` to put back.
-     */
-    private beginTransaction;
-    /**
-     * Creates a TransactionContext for the given connection.
-     *
-     * @remarks
-     * Note: Savepoint methods are not implemented (set to undefined)
-     * as savepoints are disabled in this adapter per approved approach.
-     */
-    /**
-     * Upsert with the meaning `INSERT … ON CONFLICT (target)` has on PostgreSQL
-     * and SQLite, on the tables where MySQL can keep that promise.
-     *
-     * MySQL cannot limit a duplicate to one key: `ON DUPLICATE KEY UPDATE`
-     * fires on a collision with ANY unique key, and a failed insert does not
-     * say reliably which one. So the conflict target must be the table's only
-     * unique key apart from its primary key, and any other table is refused
-     * before anything is written. On such a table the row is inserted first —
-     * its validation and triggers apply, as they do before `ON CONFLICT`
-     * elsewhere — and a duplicate is resolved by a locking read of the target
-     * key, which sees the latest committed row rather than the transaction's
-     * snapshot. The row found is kept as it is when there is nothing to update
-     * (a no-op assignment would still run its update triggers), or updated by
-     * its key. No row there means the collision was on the primary key, and it
-     * is refused as `ON CONFLICT (target)` refuses it.
-     *
-     * The steps run in the caller's transaction, or in one of their own, since a
-     * locking read locks nothing past its statement under autocommit. Rows are
-     * read back by their primary key, so a trigger that rewrites the conflict
-     * value still returns the row stored. The conflict columns must also be
-     * given values: MySQL cannot look a row up by a key the database would only
-     * fill in itself. A conflict is resolved on the caller's key value: a
-     * BEFORE INSERT trigger that moves the key onto another row's value is
-     * refused as a unique violation rather than resolved onto that row. A failed insert rolls back only itself on MySQL, so a
-     * caller's transaction stays usable.
-     */
-    upsert<T = unknown>(table: string, data: Record<string, unknown>, options: UpsertOptions, executor?: unknown): Promise<T>;
-    /**
-     * What an upsert is keyed on: the target's condition, and whether its key
-     * holds a NULL. Refuses a target this dialect cannot keep to, and a conflict
-     * column left for the database to fill — MySQL cannot look a row up by a key
-     * value only the database would supply.
-     */
-    private upsertTarget;
-    /**
-     * The table's columns for a conflict target, refusing a target MySQL cannot
-     * keep to: one that is not a primary or unique key, which an update could
-     * spread over several rows, and one beside which the table has another
-     * unique key, a collision on which MySQL would not tell apart.
-     */
-    private conflictKey;
-    /** The update an upsert applies to an existing row: never its key. */
-    private updateValues;
-    /** The row matching `where`, by a locking (current) read. */
-    private lockedRow;
-    /**
-     * Insert the row, or resolve a duplicate on the target key. The insert is
-     * read back by the primary key it reports, not by the conflict key: a
-     * BEFORE INSERT trigger may have rewritten the conflict value, and the row
-     * stored is the one to return.
-     *
-     * A duplicate is resolved when a row holds the TARGET key, whichever unique
-     * key MySQL names in its error. PostgreSQL checks the target's index before
-     * any other, so a row colliding on the target and on another key resolves
-     * on the target there too; refusing it here because MySQL happened to check
-     * the other index first would answer that case differently. A target row
-     * committed by another transaction after this insert failed is the order in
-     * which that transaction ran first, where PostgreSQL also resolves on it.
-     */
-    private insertOrResolve;
-    /**
-     * Insert a row and read it back by its primary key: the value the caller
-     * gave, or the one MySQL or the model generated, which `$returningId()`
-     * reports and a given value it does not. Undefined when the table has no
-     * primary key to read by.
-     */
-    private insertRow;
-    /**
-     * A row's primary key as a condition, from a record keyed as the model's
-     * properties are. Undefined when the table has no primary key or the record
-     * lacks part of it.
-     */
-    private byIdentity;
-    /** A table-level `primaryKey({ columns })`, read through the MySQL table config. */
-    protected compositePrimaryKey(tableObj: Record<string, unknown>): object[];
-    private createTransactionContext;
-    /**
-     * Classifies a MySQL error into a DatabaseError.
-     *
-     * @param error - Original error from mysql2
-     * @param sql - SQL statement that caused the error (optional)
-     * @returns DatabaseError with proper classification
-     */
-    protected classifyError(error: unknown, sql?: string): DatabaseError;
+export declare class MySqlAdapter extends DrizzleAdapter {
+  private drizzleByRelations;
+  private drizzleBare;
+  /**
+   * The database dialect - always 'mysql' for this adapter.
+   */
+  readonly dialect: "mysql";
+  /**
+   * Adapter configuration.
+   */
+  protected readonly config: MySqlAdapterConfig;
+  /**
+   * Connection pool instance.
+   */
+  private pool;
+  /**
+   * Connection state flag.
+   */
+  private connected;
+  /**
+   * Whether the server accepts `SELECT ... FOR SHARE`, read from its version
+   * string at connect. Undefined until then, which callers treat as not known.
+   */
+  private sharedRowLock;
+  /**
+   * Creates a new MySQL adapter instance.
+   *
+   * @param config - Adapter configuration
+   */
+  constructor(config: MySqlAdapterConfig);
+  /**
+   * Connect to the MySQL database.
+   * Creates a connection pool using mysql2.
+   *
+   * @remarks
+   * This method initializes the connection pool and verifies connectivity
+   * by executing a simple query. It is idempotent - calling it multiple
+   * times will not create multiple pools.
+   *
+   * @throws {DatabaseError} If connection fails
+   */
+  connect(): Promise<void>;
+  /**
+   * Disconnect from the MySQL database.
+   * Gracefully closes the connection pool.
+   *
+   * @remarks
+   * This method is idempotent - calling it multiple times is safe.
+   * It waits for all connections to be released before shutting down.
+   */
+  disconnect(): Promise<void>;
+  /**
+   * Check if connected to the database.
+   */
+  isConnected(): boolean;
+  /**
+   * Get connection pool statistics.
+   * Returns null if not connected.
+   *
+   * @remarks
+   * MySQL2 pool exposes different stats than pg:
+   * - _allConnections: all connections
+   * - _freeConnections: idle connections
+   * - _connectionQueue: waiting requests
+   */
+  getPoolStats(): PoolStats | null;
+  /**
+   * Execute a raw SQL query.
+   *
+   * @param sql - SQL query string with ? placeholders
+   * @param params - Query parameters
+   * @returns Query results
+   *
+   * @throws {DatabaseError} If query execution fails
+   */
+  executeQuery<T = unknown>(sql: string, params?: SqlParam[]): Promise<T[]>;
+  /**
+   * Execute work within a transaction.
+   *
+   * @param work - Function containing transactional operations
+   * @param options - Transaction options (isolation level, timeout, retry)
+   * @returns Result of the work function
+   *
+   * @remarks
+   * MySQL transactions support isolation levels. Automatic retry is
+   * implemented for deadlocks (error 1213) when `retryCount` is specified.
+   *
+   * Note: Savepoints are disabled in this adapter for safety due to
+   * MySQL's quirks with nested transactions.
+   */
+  transaction<T>(work: (tx: TransactionContext) => Promise<T>, options?: TransactionOptions): Promise<T>;
+  /** The attempts `transaction` makes, each on a connection of its own. */
+  private runTransactionAttempts;
+  /**
+   * Get MySQL database capabilities.
+   *
+   * @remarks
+   * MySQL has some limitations:
+   * - No JSONB (uses JSON)
+   * - No arrays
+   * - No native ILIKE
+   * - No RETURNING clause
+   * - Savepoints disabled for safety
+   */
+  getCapabilities(): DatabaseCapabilities;
+  /**
+   * Build a placeholder for MySQL (uses ? instead of $1, $2, etc.)
+   *
+   * @param _index - Parameter index (ignored for MySQL)
+   * @returns The ? placeholder
+   */
+  protected buildPlaceholder(_index: number): string;
+  /**
+   * Build multiple placeholders for MySQL.
+   *
+   * @param count - Number of placeholders needed
+   * @param _startIndex - Starting index (ignored for MySQL)
+   * @returns Comma-separated ? placeholders
+   */
+  protected buildPlaceholders(count: number, _startIndex?: number): string;
+  /**
+   * Escape an identifier for MySQL (uses backticks instead of double quotes).
+   *
+   * @param identifier - The identifier to escape
+   * @returns Escaped identifier with backticks
+   */
+  protected escapeIdentifier(identifier: string): string;
+  /**
+   * Ensures pool is connected and returns it.
+   *
+   * @throws {DatabaseError} If not connected
+   */
+  private ensurePool;
+  /**
+   * Return the typed Drizzle instance for MySQL.
+   * Guarded for server-only usage and requires an active connection.
+   *
+   * @param schema - Optional schema for relational queries (db.query.*)
+   * @returns Drizzle ORM instance wrapping the mysql2 pool connection
+   * @throws {Error} If called in browser or not connected
+   */
+  getDrizzle<T = MySql2Database<AnyRelations>>(relations?: AnyRelations): T;
+  /**
+   * A Drizzle handle on the pool, for `getDrizzle`.
+   *
+   * Its `transaction` runs on a connection this adapter checks out and
+   * returns itself (`pinDrizzleTransactions`): destroyed rather than pooled
+   * when no ROLLBACK could be confirmed on it. And it counts for
+   * `transactionOpenInFlow`, as the adapter's does.
+   */
+  private poolDrizzle;
+  /**
+   * Builds mysql2 Pool configuration from adapter config.
+   */
+  private buildPoolConfig;
+  /**
+   * Begins a transaction with the specified options, recording in `changed`
+   * each session setting it changes, as it changes it, for `restoreSession`
+   * to put back.
+   */
+  private beginTransaction;
+  /**
+   * Creates a TransactionContext for the given connection.
+   *
+   * @remarks
+   * Note: Savepoint methods are not implemented (set to undefined)
+   * as savepoints are disabled in this adapter per approved approach.
+   */
+  /**
+   * Upsert with the meaning `INSERT … ON CONFLICT (target)` has on PostgreSQL
+   * and SQLite, on the tables where MySQL can keep that promise.
+   *
+   * MySQL cannot limit a duplicate to one key: `ON DUPLICATE KEY UPDATE`
+   * fires on a collision with ANY unique key, and a failed insert does not
+   * say reliably which one. So the conflict target must be the table's only
+   * unique key apart from its primary key, and any other table is refused
+   * before anything is written. On such a table the row is inserted first —
+   * its validation and triggers apply, as they do before `ON CONFLICT`
+   * elsewhere — and a duplicate is resolved by a locking read of the target
+   * key, which sees the latest committed row rather than the transaction's
+   * snapshot. The row found is kept as it is when there is nothing to update
+   * (a no-op assignment would still run its update triggers), or updated by
+   * its key. No row there means the collision was on the primary key, and it
+   * is refused as `ON CONFLICT (target)` refuses it.
+   *
+   * The steps run in the caller's transaction, or in one of their own, since a
+   * locking read locks nothing past its statement under autocommit. Rows are
+   * read back by their primary key, so a trigger that rewrites the conflict
+   * value still returns the row stored. The conflict columns must also be
+   * given values: MySQL cannot look a row up by a key the database would only
+   * fill in itself. A conflict is resolved on the caller's key value: a
+   * BEFORE INSERT trigger that moves the key onto another row's value is
+   * refused as a unique violation rather than resolved onto that row. A failed insert rolls back only itself on MySQL, so a
+   * caller's transaction stays usable.
+   */
+  override upsert<T = unknown>(table: string, data: Record<string, unknown>, options: UpsertOptions, executor?: unknown): Promise<T>;
+  /**
+   * What an upsert is keyed on: the target's condition, and whether its key
+   * holds a NULL. Refuses a target this dialect cannot keep to, and a conflict
+   * column left for the database to fill — MySQL cannot look a row up by a key
+   * value only the database would supply.
+   */
+  private upsertTarget;
+  /**
+   * The table's columns for a conflict target, refusing a target MySQL cannot
+   * keep to: one that is not a primary or unique key, which an update could
+   * spread over several rows, and one beside which the table has another
+   * unique key, a collision on which MySQL would not tell apart.
+   */
+  private conflictKey;
+  /** The update an upsert applies to an existing row: never its key. */
+  private updateValues;
+  /** The row matching `where`, by a locking (current) read. */
+  private lockedRow;
+  /**
+   * Insert the row, or resolve a duplicate on the target key. The insert is
+   * read back by the primary key it reports, not by the conflict key: a
+   * BEFORE INSERT trigger may have rewritten the conflict value, and the row
+   * stored is the one to return.
+   *
+   * A duplicate is resolved when a row holds the TARGET key, whichever unique
+   * key MySQL names in its error. PostgreSQL checks the target's index before
+   * any other, so a row colliding on the target and on another key resolves
+   * on the target there too; refusing it here because MySQL happened to check
+   * the other index first would answer that case differently. A target row
+   * committed by another transaction after this insert failed is the order in
+   * which that transaction ran first, where PostgreSQL also resolves on it.
+   */
+  private insertOrResolve;
+  /**
+   * Insert a row and read it back by its primary key: the value the caller
+   * gave, or the one MySQL or the model generated, which `$returningId()`
+   * reports and a given value it does not. Undefined when the table has no
+   * primary key to read by.
+   */
+  private insertRow;
+  /**
+   * A row's primary key as a condition, from a record keyed as the model's
+   * properties are. Undefined when the table has no primary key or the record
+   * lacks part of it.
+   */
+  private byIdentity;
+  /** A table-level `primaryKey({ columns })`, read through the MySQL table config. */
+  protected override compositePrimaryKey(tableObj: Record<string, unknown>): object[];
+  private createTransactionContext;
+  /**
+   * Classifies a MySQL error into a DatabaseError.
+   *
+   * @param error - Original error from mysql2
+   * @param sql - SQL statement that caused the error (optional)
+   * @returns DatabaseError with proper classification
+   */
+  protected override classifyError(error: unknown, sql?: string): DatabaseError;
 }
 /**
  * Create a MySQL database adapter.
@@ -351,7 +314,7 @@ declare class MySqlAdapter extends DrizzleAdapter {
  * await adapter.connect();
  * ```
  */
-declare function createMySqlAdapter(config: MySqlAdapterConfig): MySqlAdapter;
+export declare function createMySqlAdapter(config: MySqlAdapterConfig): MySqlAdapter;
 /**
  * Type guard to check if a value is a MySqlAdapter.
  *
@@ -366,6 +329,6 @@ declare function createMySqlAdapter(config: MySqlAdapterConfig): MySqlAdapter;
  * }
  * ```
  */
-declare function isMySqlAdapter(value: unknown): value is MySqlAdapter;
-
-export { MySqlAdapter, VERSION, createMySqlAdapter, isMySqlAdapter };
+export declare function isMySqlAdapter(value: unknown): value is MySqlAdapter;
+export type { AdapterLogger, BaseAdapterConfig, DatabaseCapabilities, DatabaseError, DatabaseErrorKind, DeleteOptions, InsertOptions, JoinSpec, MySqlAdapterConfig, OrderBySpec, PoolConfig, PoolStats, SelectOptions, SqlParam, SslConfig, TransactionContext, TransactionOptions, UpdateOptions, UpsertOptions, WhereClause, WhereCondition, WhereOperator };
+//# sourceMappingURL=index.d.ts.map