@nextlyhq/adapter-sqlite 0.0.2-alpha.7 → 0.0.2-alpha.71

package/dist/index.d.cts

@@ -1,48 +1,11 @@
-import { DrizzleAdapter } from '@nextlyhq/adapter-drizzle';
-import { SqliteAdapterConfig, PoolStats, SqlParam, TransactionContext, TransactionOptions, DatabaseCapabilities, InsertOptions, DatabaseError } from '@nextlyhq/adapter-drizzle/types';
-export { AdapterLogger, BaseAdapterConfig, DatabaseCapabilities, DatabaseError, DatabaseErrorKind, DeleteOptions, InsertOptions, JoinSpec, OrderBySpec, PoolStats, SelectOptions, SqlParam, SqliteAdapterConfig, TransactionContext, TransactionOptions, UpdateOptions, UpsertOptions, WhereClause, WhereCondition, WhereOperator } from '@nextlyhq/adapter-drizzle/types';
-import { BetterSQLite3Database } from 'drizzle-orm/better-sqlite3';
-
-/**
- * @nextlyhq/adapter-sqlite
- *
- * SQLite database adapter for Nextly.
- * Extends DrizzleAdapter from @nextlyhq/adapter-drizzle to provide SQLite-specific functionality.
- *
- * @remarks
- * This adapter uses the better-sqlite3 package for database connectivity and provides:
- * - Synchronous API wrapped for async interface compatibility
- * - Full transaction support with savepoints (via better-sqlite3's native transaction handling)
- * - CRUD operations with RETURNING clause support (SQLite 3.35+)
- * - WAL mode for better concurrent read performance
- * - In-memory and file-based database support
- *
- * @example
- * ```typescript
- * import { createSqliteAdapter } from '@nextlyhq/adapter-sqlite';
- *
- * const adapter = createSqliteAdapter({
- *   url: 'file:./data/app.db',
- * });
- *
- * 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, OrderBySpec, PoolStats, SelectOptions, SqlParam, SqliteAdapterConfig, TransactionContext, TransactionOptions, UpdateOptions, UpsertOptions, WhereClause, WhereCondition, WhereOperator } from "@nextlyhq/adapter-drizzle/types";
+import { AnyRelations } from "drizzle-orm";
+import { BetterSQLite3Database } from "drizzle-orm/better-sqlite3";
 /**
  * Package version
  */
-declare const VERSION = "0.1.0";
+export declare const VERSION = "0.1.0";
 /**
  * SQLite database adapter for Nextly.
  *
@@ -68,173 +31,274 @@ declare const VERSION = "0.1.0";
  * await adapter.connect();
  * ```
  */
-declare class SqliteAdapter extends DrizzleAdapter {
-    /**
-     * The database dialect - always 'sqlite' for this adapter.
-     */
-    readonly dialect: "sqlite";
-    /**
-     * Adapter configuration.
-     */
-    protected readonly config: SqliteAdapterConfig;
-    /**
-     * better-sqlite3 Database instance.
-     */
-    private db;
-    /**
-     * Connection state flag.
-     */
-    private connected;
-    /**
-     * Serialization queue for concurrent `transaction()` calls.
-     *
-     * better-sqlite3 is synchronous, single-connection, and rejects nested
-     * `BEGIN` with "cannot start a transaction within a transaction".
-     * When two `await adapter.transaction(...)` calls overlap (e.g. a bulk
-     * mutation calling `Promise.allSettled` with N per-row updates), the
-     * second one tries to BEGIN while the first is still open and the
-     * driver throws.
-     *
-     * Postgres/MySQL avoid this by allocating a fresh client/connection
-     * per transaction from a pool — there is no equivalent for
-     * better-sqlite3, so we serialize at the JS layer instead. Every
-     * `transaction()` invocation chains onto this promise; only one
-     * BEGIN→COMMIT/ROLLBACK section runs at any moment, preserving
-     * write-isolation semantics that callers expect from a transactional
-     * adapter.
-     *
-     * Performance impact is the natural floor: SQLite already serializes
-     * writers at the file-lock level, so the queue removes failed-call
-     * surface area without changing the achievable concurrency.
-     */
-    private transactionQueue;
-    /**
-     * Creates a new SQLite adapter instance.
-     *
-     * @param config - Adapter configuration
-     */
-    constructor(config: SqliteAdapterConfig);
-    /**
-     * Connect to the SQLite database.
-     *
-     * @remarks
-     * This method initializes the database connection. For SQLite, this
-     * opens the database file or creates an in-memory database.
-     * Also configures WAL mode and foreign keys based on config.
-     *
-     * @throws {DatabaseError} If connection fails
-     */
-    connect(): Promise<void>;
-    /**
-     * Disconnect from the SQLite database.
-     *
-     * @remarks
-     * This method closes the database connection and releases resources.
-     */
-    disconnect(): Promise<void>;
-    /**
-     * Check if connected to the database.
-     */
-    isConnected(): boolean;
-    /**
-     * Get connection pool statistics.
-     *
-     * @remarks
-     * SQLite doesn't use connection pooling, so this returns null.
-     * The database is single-file with a single connection.
-     */
-    getPoolStats(): PoolStats | null;
-    /**
-     * Execute a raw SQL query.
-     *
-     * @param sql - SQL query string with $1, $2 placeholders (converted to ? for SQLite)
-     * @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 not fully supported in SQLite)
-     * @returns Result of the work function
-     *
-     * @remarks
-     * Uses better-sqlite3's native transaction handling which:
-     * - Automatically commits on success
-     * - Automatically rolls back on error
-     * - Converts nested transactions to savepoints
-     *
-     * Note: SQLite uses DEFERRED, IMMEDIATE, or EXCLUSIVE transaction modes
-     * rather than isolation levels. This adapter uses IMMEDIATE by default.
-     */
-    transaction<T>(work: (tx: TransactionContext) => Promise<T>, _options?: TransactionOptions): Promise<T>;
-    /**
-     * Inner transaction body. Kept private so callers always go through
-     * the serialized `transaction()` queue above and the BEGIN/COMMIT
-     * pair is never invoked outside of it.
-     */
-    private runTransaction;
-    /**
-     * Get SQLite database capabilities.
-     *
-     * @remarks
-     * SQLite capabilities:
-     * - JSON support (not JSONB)
-     * - No arrays
-     * - No native ILIKE
-     * - RETURNING clause (3.35+)
-     * - Savepoints supported
-     * - ON CONFLICT supported
-     */
-    getCapabilities(): DatabaseCapabilities;
-    /**
-     * Override insertMany for bulk insert optimization.
-     *
-     * @remarks
-     * Uses a single multi-row INSERT statement for better performance.
-     */
-    insertMany<T = unknown>(table: string, data: Record<string, unknown>[], options?: InsertOptions): Promise<T[]>;
-    /**
-     * Ensures database is connected and returns it.
-     *
-     * @throws {DatabaseError} If not connected
-     */
-    private ensureDb;
-    /**
-     * Return the typed Drizzle instance for SQLite.
-     * 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 better-sqlite3 connection
-     * @throws {Error} If called in browser or not connected
-     */
-    getDrizzle<T = BetterSQLite3Database<any>>(schema?: Record<string, unknown>): T;
-    /**
-     * Convert $1, $2 placeholders to ? for better-sqlite3.
-     *
-     * @param sql - SQL with PostgreSQL-style placeholders
-     * @returns SQL with ? placeholders
-     */
-    private convertPlaceholders;
-    /**
-     * Creates a TransactionContext for the given database connection.
-     */
-    private createTransactionContext;
-    /**
-     * Classifies a SQLite error into a DatabaseError.
-     *
-     * @param error - Original error from better-sqlite3
-     * @param sql - SQL statement that caused the error (optional)
-     * @returns DatabaseError with proper classification
-     */
-    private classifyError;
-    /**
-     * Override handleQueryError to use SQLite-specific classification.
-     */
-    protected handleQueryError(error: unknown, operation: string, table: string): DatabaseError;
+export declare class SqliteAdapter extends DrizzleAdapter {
+  private drizzleByRelations;
+  private drizzleBare;
+  /**
+   * The database dialect - always 'sqlite' for this adapter.
+   */
+  readonly dialect: "sqlite";
+  /**
+   * Adapter configuration.
+   */
+  protected readonly config: SqliteAdapterConfig;
+  /**
+   * better-sqlite3 Database instance.
+   */
+  private db;
+  /**
+   * Connection state flag.
+   */
+  private connected;
+  /**
+   * Serialization queue for concurrent `transaction()` calls.
+   *
+   * better-sqlite3 is synchronous, single-connection, and rejects nested
+   * `BEGIN` with "cannot start a transaction within a transaction".
+   * When two `await adapter.transaction(...)` calls overlap (e.g. a bulk
+   * mutation calling `Promise.allSettled` with N per-row updates), the
+   * second one tries to BEGIN while the first is still open and the
+   * driver throws.
+   *
+   * Postgres/MySQL avoid this by allocating a fresh client/connection
+   * per transaction from a pool — there is no equivalent for
+   * better-sqlite3, so we serialize at the JS layer instead. Every
+   * `transaction()` invocation chains onto this promise; only one
+   * BEGIN→COMMIT/ROLLBACK section runs at any moment, preserving
+   * write-isolation semantics that callers expect from a transactional
+   * adapter.
+   *
+   * Performance impact is the natural floor: SQLite already serializes
+   * writers at the file-lock level, so the queue removes failed-call
+   * surface area without changing the achievable concurrency.
+   */
+  private transactionQueue;
+  /**
+   * The transaction the current async chain is running inside, if any.
+   *
+   * A `transaction()` call made from INSIDE a transaction's work — a store
+   * writing on behalf of the caller, a plugin's write inside its own
+   * `ctx.db.transaction` — used to queue behind the very transaction that
+   * was waiting for it, and neither ever settled: that hung every later
+   * transaction on the instance too. Such a call now runs as a SAVEPOINT of
+   * the active transaction instead, so it commits or rolls back with it and
+   * its own failure undoes only its own part.
+   */
+  private readonly transactionScope;
+  /**
+   * Creates a new SQLite adapter instance.
+   *
+   * @param config - Adapter configuration
+   */
+  constructor(config: SqliteAdapterConfig);
+  /**
+   * Connect to the SQLite database.
+   *
+   * @remarks
+   * This method initializes the database connection. For SQLite, this
+   * opens the database file or creates an in-memory database.
+   * Also configures WAL mode and foreign keys based on config.
+   *
+   * @throws {DatabaseError} If connection fails
+   */
+  connect(): Promise<void>;
+  /**
+   * Disconnect from the SQLite database.
+   *
+   * @remarks
+   * This method closes the database connection and releases resources.
+   */
+  disconnect(): Promise<void>;
+  /**
+   * Check if connected to the database.
+   */
+  isConnected(): boolean;
+  /**
+   * Get connection pool statistics.
+   *
+   * @remarks
+   * SQLite doesn't use connection pooling, so this returns null.
+   * The database is single-file with a single connection.
+   */
+  getPoolStats(): PoolStats | null;
+  /**
+   * Execute a raw SQL query.
+   *
+   * @param sql - SQL query string with $1, $2 placeholders (converted to ? for SQLite)
+   * @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 not fully supported in SQLite)
+   * @returns Result of the work function
+   *
+   * @remarks
+   * The adapter manages the transaction itself, because better-sqlite3's
+   * `db.transaction()` does not take async work: it runs `BEGIN IMMEDIATE`,
+   * then `COMMIT` when `work` resolves or `ROLLBACK` when it throws.
+   * - Top-level calls run one at a time.
+   * - A call made inside an open transaction's work joins it as a savepoint
+   *   (`SAVEPOINT` / `RELEASE` / `ROLLBACK TO`).
+   * - Nested calls of one scope run one at a time.
+   * - A call made later from a savepoint that has already released joins the
+   *   innermost scope still open.
+   * - Nested work started and not awaited finishes before the enclosing scope
+   *   commits or rolls back.
+   *
+   * Note: SQLite uses DEFERRED, IMMEDIATE, or EXCLUSIVE transaction modes
+   * rather than isolation levels. This adapter uses IMMEDIATE.
+   */
+  /** How long a transaction waits for the connection: `pool.connectionTimeoutMs`. */
+  private transactionWaitMs;
+  transaction<T>(work: (tx: TransactionContext) => Promise<T>, _options?: TransactionOptions): Promise<T>;
+  /**
+   * Hold `effect` until the transaction enclosing this async context commits,
+   * or run it now when none does.
+   *
+   * The effect belongs to the scope this async context runs in, even one
+   * that has already released or rolled back: a service whose own
+   * transaction nested as a savepoint registers from its caller's scope once
+   * that savepoint has released, and the change is undoable for as long as
+   * any scope around it is. The outermost transaction runs the effect once
+   * its COMMIT succeeds, unless a scope between the effect's scope and the
+   * outermost transaction rolled back, and drops every effect on ROLLBACK or
+   * a failed COMMIT. A context whose outermost transaction has already
+   * finished is outside any transaction, so its effect runs now, unless what
+   * it announces was undone and it has run no transaction since.
+   */
+  override afterCommit(effect: () => unknown, onDeferredFailure?: (error: unknown) => void): Promise<void>;
+  /**
+   * `effect`, bound to the async context it is registered from.
+   *
+   * A held effect runs after the outermost COMMIT, from the code that ran the
+   * outermost transaction, so without this it sees that code's context rather
+   * than its own: whatever its caller pinned around the write is gone. That
+   * includes who is calling. A scope pinned for a scoped API key lost there
+   * leaves a hook's nested call judged by the key's owner instead of the key,
+   * and a person's frame lost there leaves the hook told of nobody.
+   *
+   * The adapter's own transaction scope is the one store it leaves: the
+   * effect runs once that transaction has finished, outside it, as an effect
+   * held to the outermost commit always has.
+   */
+  private inRegisteringContext;
+  /**
+   * Run the effects a committed transaction held, in order. A failure is
+   * reported, never thrown: the change is durable, and reporting the
+   * transaction as failed would invite a retry of something already done.
+   */
+  private runHeldEffects;
+  /** Hand a held effect's failure to its reporter, or to the adapter's log. */
+  private reportHeldEffectFailure;
+  /**
+   * Whether a `transaction()` call made here would join an open transaction
+   * as a savepoint. On SQLite it would: the connection is the only one, so a
+   * transaction open on it encloses whatever the async chain that opened it
+   * starts.
+   */
+  override inTransaction(): boolean;
+  /**
+   * Whether the calling async flow is inside a transaction that has not
+   * finished, judged from the transaction this flow was started inside,
+   * never from the connection: another request's open transaction answers
+   * false here, where its own `transaction()` queues behind that one.
+   *
+   * A flow started inside a transaction, even inside a savepoint that has
+   * since released, stays inside it until its outermost transaction has
+   * committed or rolled back: until then whatever it writes on the one
+   * connection lands in that transaction.
+   */
+  override transactionOpenInFlow(): boolean;
+  /**
+   * The scope a `transaction()` call made here nests in, or none when it
+   * opens a transaction of its own.
+   *
+   * A call made later from inside a savepoint that has since released runs
+   * inside the innermost scope open on the connection. Queued on an enclosing
+   * scope, or on the instance, it would wait behind the scope running there,
+   * which may be the one awaiting it. Savepoints on one connection form a
+   * stack, so whatever opens now is inside that innermost scope anyway; when
+   * none is open the call queues on the instance.
+   *
+   * The innermost open scope need not be related to the call. When it is a
+   * sibling savepoint that later rolls back, the call's write rolls back with
+   * it, although the call itself already resolved. Waiting for an unrelated
+   * scope instead could wait on the very scope that awaits the call.
+   */
+  private nestingScope;
+  /**
+   * Run `work` as a savepoint of the active transaction: released when it
+   * resolves, rolled back to when it throws.
+   */
+  private runSavepoint;
+  /**
+   * Inner transaction body. Kept private so callers always go through
+   * the serialized `transaction()` queue above and the BEGIN/COMMIT
+   * pair is never invoked outside of it.
+   */
+  private runTransaction;
+  /**
+   * Get SQLite database capabilities.
+   *
+   * @remarks
+   * SQLite capabilities:
+   * - JSON support (not JSONB)
+   * - No arrays
+   * - No native ILIKE
+   * - RETURNING clause (3.35+)
+   * - Savepoints supported
+   * - ON CONFLICT supported
+   */
+  getCapabilities(): DatabaseCapabilities;
+  /**
+   * Override insertMany for bulk insert optimization.
+   *
+   * @remarks
+   * Uses a single multi-row INSERT statement for better performance.
+   */
+  override insertMany<T = unknown>(table: string, data: Record<string, unknown>[], options?: InsertOptions): Promise<T[]>;
+  /**
+   * Ensures database is connected and returns it.
+   *
+   * @throws {DatabaseError} If not connected
+   */
+  private ensureDb;
+  /**
+   * Return the typed Drizzle instance for SQLite.
+   * 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 better-sqlite3 connection
+   * @throws {Error} If called in browser or not connected
+   */
+  getDrizzle<T = BetterSQLite3Database<AnyRelations>>(relations?: AnyRelations): T;
+  /**
+   * Convert $1, $2 placeholders to ? for better-sqlite3.
+   *
+   * @param sql - SQL with PostgreSQL-style placeholders
+   * @returns SQL with ? placeholders
+   */
+  private convertPlaceholders;
+  /**
+   * Creates a TransactionContext for the given database connection.
+   */
+  /** A table-level `primaryKey({ columns })`, read through the SQLite table config. */
+  protected override compositePrimaryKey(tableObj: Record<string, unknown>): object[];
+  private createTransactionContext;
+  /**
+   * Classifies a SQLite error into a DatabaseError.
+   *
+   * @param error - Original error from better-sqlite3
+   * @param sql - SQL statement that caused the error (optional)
+   * @returns DatabaseError with proper classification
+   */
+  protected override classifyError(error: unknown, sql?: string): DatabaseError;
 }
 /**
  * Create a SQLite database adapter.
@@ -268,7 +332,7 @@ declare class SqliteAdapter extends DrizzleAdapter {
  * await adapter.connect();
  * ```
  */
-declare function createSqliteAdapter(config: SqliteAdapterConfig): SqliteAdapter;
+export declare function createSqliteAdapter(config: SqliteAdapterConfig): SqliteAdapter;
 /**
  * Type guard to check if a value is a SqliteAdapter.
  *
@@ -283,6 +347,6 @@ declare function createSqliteAdapter(config: SqliteAdapterConfig): SqliteAdapter
  * }
  * ```
  */
-declare function isSqliteAdapter(value: unknown): value is SqliteAdapter;
-
-export { SqliteAdapter, VERSION, createSqliteAdapter, isSqliteAdapter };
+export declare function isSqliteAdapter(value: unknown): value is SqliteAdapter;
+export type { AdapterLogger, BaseAdapterConfig, DatabaseCapabilities, DatabaseError, DatabaseErrorKind, DeleteOptions, InsertOptions, JoinSpec, OrderBySpec, PoolStats, SelectOptions, SqlParam, SqliteAdapterConfig, TransactionContext, TransactionOptions, UpdateOptions, UpsertOptions, WhereClause, WhereCondition, WhereOperator };
+//# sourceMappingURL=index.d.cts.map