@nextlyhq/adapter-drizzle 0.0.1

package/dist/migration-BbO5meEV.d.cts

@@ -0,0 +1,622 @@
+import { a as SqlParam, S as SupportedDialect } from './core-CVO7WYDj.cjs';
+
+/**
+ * Query building type definitions for database-agnostic queries.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Supported WHERE clause operators.
+ *
+ * @remarks
+ * - Standard comparison: =, !=, <, >, <=, >=
+ * - Set operations: IN, NOT IN
+ * - Pattern matching: LIKE, ILIKE (case-insensitive, PostgreSQL/emulated)
+ * - NULL checks: IS NULL, IS NOT NULL
+ * - Range: BETWEEN, NOT BETWEEN
+ * - JSON/Array: CONTAINS, OVERLAPS
+ *
+ * @public
+ */
+type WhereOperator = "=" | "!=" | "<" | ">" | "<=" | ">=" | "IN" | "NOT IN" | "LIKE" | "ILIKE" | "IS NULL" | "IS NOT NULL" | "BETWEEN" | "NOT BETWEEN" | "CONTAINS" | "OVERLAPS";
+/**
+ * Individual WHERE condition.
+ *
+ * @remarks
+ * Represents a single condition in a WHERE clause. For IS NULL and IS NOT NULL
+ * operators, the value field is optional.
+ *
+ * @public
+ */
+interface WhereCondition {
+    /** Column name to filter on */
+    column: string;
+    /** Comparison operator */
+    op: WhereOperator;
+    /** Value(s) to compare against (optional for IS NULL/IS NOT NULL) */
+    value?: SqlParam | SqlParam[];
+    /** Second value for BETWEEN operator */
+    valueTo?: SqlParam;
+}
+/**
+ * Complex WHERE clause with logical operators.
+ *
+ * @remarks
+ * Supports nested conditions with AND, OR, and NOT logical operators.
+ * Can be recursively nested for complex queries.
+ *
+ * @example
+ * ```typescript
+ * const where: WhereClause = {
+ *   and: [
+ *     { column: "status", op: "=", value: "published" },
+ *     {
+ *       or: [
+ *         { column: "author", op: "=", value: "john" },
+ *         { column: "author", op: "=", value: "jane" }
+ *       ]
+ *     }
+ *   ]
+ * };
+ * ```
+ *
+ * @public
+ */
+interface WhereClause {
+    /** All conditions must be true (AND) */
+    and?: (WhereCondition | WhereClause)[];
+    /** At least one condition must be true (OR) */
+    or?: (WhereCondition | WhereClause)[];
+    /** Negate a condition (NOT) */
+    not?: WhereCondition | WhereClause;
+}
+/**
+ * ORDER BY specification for query results.
+ *
+ * @remarks
+ * Controls the sorting of query results. NULL handling varies by database
+ * but can be explicitly controlled with the nulls field.
+ *
+ * @public
+ */
+interface OrderBySpec {
+    /** Column name to sort by */
+    column: string;
+    /** Sort direction (default: asc) */
+    direction?: "asc" | "desc";
+    /** NULL value ordering (database-specific defaults vary) */
+    nulls?: "first" | "last";
+}
+/**
+ * JOIN specification for table joins.
+ *
+ * @remarks
+ * Supports different types of JOINs. Note that complex joins may require
+ * dialect-specific handling.
+ *
+ * @public
+ */
+interface JoinSpec {
+    /** Type of join */
+    type: "inner" | "left" | "right" | "full";
+    /** Table name to join */
+    table: string;
+    /** Join condition */
+    on: {
+        /** Column from the left table */
+        leftColumn: string;
+        /** Column from the right table */
+        rightColumn: string;
+    };
+    /** Optional alias for the joined table */
+    alias?: string;
+}
+
+/**
+ * CRUD operation type definitions.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Options for SELECT queries.
+ *
+ * @remarks
+ * Provides a database-agnostic way to build SELECT queries with filtering,
+ * sorting, pagination, and joins.
+ *
+ * @public
+ */
+interface SelectOptions {
+    /** Specific columns to select (default: all columns) */
+    columns?: string[];
+    /** Filter conditions */
+    where?: WhereClause;
+    /** Sort order */
+    orderBy?: OrderBySpec[];
+    /** Maximum number of rows to return */
+    limit?: number;
+    /** Number of rows to skip */
+    offset?: number;
+    /** Table joins */
+    joins?: JoinSpec[];
+    /** GROUP BY columns */
+    groupBy?: string[];
+    /** HAVING clause (for aggregated results) */
+    having?: WhereClause;
+    /** Return distinct rows only */
+    distinct?: boolean;
+}
+/**
+ * Options for INSERT operations.
+ *
+ * @remarks
+ * Controls the behavior of INSERT operations including conflict handling
+ * and returning inserted data.
+ *
+ * @public
+ */
+interface InsertOptions {
+    /** Columns to return after insert (use "*" for all columns) */
+    returning?: string[] | "*";
+    /** Handle conflicts (unique constraint violations) */
+    onConflict?: {
+        /** Columns that define the conflict (unique constraint) */
+        columns: string[];
+        /** Action to take on conflict */
+        action: "ignore" | "update";
+        /** Columns to update on conflict (required if action is "update") */
+        updateColumns?: string[];
+    };
+}
+/**
+ * Options for UPDATE operations.
+ *
+ * @remarks
+ * Controls what data is returned after an update operation.
+ *
+ * @public
+ */
+interface UpdateOptions {
+    /** Columns to return after update (use "*" for all columns) */
+    returning?: string[] | "*";
+}
+/**
+ * Options for DELETE operations.
+ *
+ * @remarks
+ * Controls what data is returned after a delete operation.
+ *
+ * @public
+ */
+interface DeleteOptions {
+    /** Columns to return after delete (use "*" for all columns) */
+    returning?: string[] | "*";
+}
+/**
+ * Options for UPSERT operations (INSERT or UPDATE).
+ *
+ * @remarks
+ * Combines INSERT and UPDATE behavior. If a row with the specified
+ * conflict columns exists, it will be updated; otherwise, a new row
+ * will be inserted.
+ *
+ * @public
+ */
+interface UpsertOptions {
+    /** Columns that define uniqueness for conflict detection */
+    conflictColumns: string[];
+    /** Columns to update if conflict occurs (default: all provided columns) */
+    updateColumns?: string[];
+    /** Columns to return after upsert (use "*" for all columns) */
+    returning?: string[] | "*";
+}
+
+/**
+ * Transaction type definitions for database operations.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Transaction isolation levels.
+ *
+ * @remarks
+ * Controls the visibility of changes between concurrent transactions.
+ * Not all levels are supported by all databases:
+ * - PostgreSQL: All levels supported
+ * - MySQL: All levels supported
+ * - SQLite: Serializable only (default)
+ *
+ * @public
+ */
+type TransactionIsolationLevel = "read uncommitted" | "read committed" | "repeatable read" | "serializable";
+/**
+ * Options for transaction execution.
+ *
+ * @remarks
+ * Configures transaction behavior including isolation level, read-only mode,
+ * timeouts, and retry logic.
+ *
+ * @public
+ */
+interface TransactionOptions {
+    /** Transaction isolation level */
+    isolationLevel?: TransactionIsolationLevel;
+    /** Read-only transaction (optimization hint) */
+    readOnly?: boolean;
+    /** Per-transaction statement timeout in milliseconds */
+    timeoutMs?: number;
+    /** Number of retry attempts on serialization failures (default: 0) */
+    retryCount?: number;
+    /** Delay between retry attempts in milliseconds (default: 100) */
+    retryDelayMs?: number;
+}
+/**
+ * Transaction context for executing operations within a transaction.
+ *
+ * @remarks
+ * All operations executed through this context are part of the same
+ * database transaction. The transaction is automatically committed on
+ * success or rolled back on error.
+ *
+ * Savepoint methods are optional and only available on databases that
+ * support them (PostgreSQL, SQLite).
+ *
+ * @public
+ */
+interface TransactionContext {
+    /**
+     * Execute raw SQL within the transaction.
+     *
+     * @param sql - SQL statement to execute
+     * @param params - Optional parameters for the statement
+     * @returns Array of result rows
+     */
+    execute<T = unknown>(sql: string, params?: SqlParam[]): Promise<T[]>;
+    /**
+     * Insert a single record.
+     *
+     * @param table - Table name
+     * @param data - Record data to insert
+     * @param options - Insert options
+     * @returns Inserted record (with RETURNING columns if specified)
+     */
+    insert<T = unknown>(table: string, data: Record<string, unknown>, options?: InsertOptions): Promise<T>;
+    /**
+     * Insert multiple records.
+     *
+     * @param table - Table name
+     * @param data - Array of records to insert
+     * @param options - Insert options
+     * @returns Inserted records (with RETURNING columns if specified)
+     */
+    insertMany<T = unknown>(table: string, data: Record<string, unknown>[], options?: InsertOptions): Promise<T[]>;
+    /**
+     * Select multiple records.
+     *
+     * @param table - Table name
+     * @param options - Select options (filtering, sorting, etc.)
+     * @returns Array of matching records
+     */
+    select<T = unknown>(table: string, options?: SelectOptions): Promise<T[]>;
+    /**
+     * Select a single record.
+     *
+     * @param table - Table name
+     * @param options - Select options (filtering, sorting, etc.)
+     * @returns First matching record or null
+     */
+    selectOne<T = unknown>(table: string, options?: SelectOptions): Promise<T | null>;
+    /**
+     * Update records.
+     *
+     * @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)
+     */
+    update<T = unknown>(table: string, data: Record<string, unknown>, where: WhereClause, options?: UpdateOptions): Promise<T[]>;
+    /**
+     * Delete records.
+     *
+     * @param table - Table name
+     * @param where - Conditions for records to delete
+     * @param options - Delete options
+     * @returns Number of deleted records
+     */
+    delete(table: string, where: WhereClause, options?: DeleteOptions): Promise<number>;
+    /**
+     * Upsert a record (INSERT or 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)
+     */
+    upsert<T = unknown>(table: string, data: Record<string, unknown>, options: UpsertOptions): Promise<T>;
+    /**
+     * Create a savepoint (PostgreSQL, SQLite only).
+     *
+     * @remarks
+     * Savepoints allow partial rollback within a transaction.
+     * Not supported on MySQL.
+     *
+     * @param name - Savepoint name
+     */
+    savepoint?(name: string): Promise<void>;
+    /**
+     * Rollback to a savepoint (PostgreSQL, SQLite only).
+     *
+     * @remarks
+     * Discards all changes made after the savepoint was created.
+     *
+     * @param name - Savepoint name
+     */
+    rollbackToSavepoint?(name: string): Promise<void>;
+    /**
+     * Release a savepoint (PostgreSQL, SQLite only).
+     *
+     * @remarks
+     * Commits the savepoint, making its changes permanent within the transaction.
+     *
+     * @param name - Savepoint name
+     */
+    releaseSavepoint?(name: string): Promise<void>;
+}
+
+/**
+ * Database capability type definitions.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Database feature capabilities.
+ *
+ * @remarks
+ * Describes what features are supported by a specific database adapter.
+ * Services can check these capabilities to conditionally enable features
+ * or implement fallback behavior.
+ *
+ * @example
+ * ```typescript
+ * const capabilities = adapter.getCapabilities();
+ * if (capabilities.supportsJsonb) {
+ *   // Use JSONB-specific features
+ * } else if (capabilities.supportsJson) {
+ *   // Fallback to JSON
+ * }
+ * ```
+ *
+ * @public
+ */
+interface DatabaseCapabilities {
+    /** Database dialect */
+    dialect: SupportedDialect;
+    /**
+     * Native JSONB support (PostgreSQL only).
+     *
+     * @remarks
+     * JSONB provides better performance and indexing than JSON.
+     * Other databases will use JSON or emulated JSON.
+     */
+    supportsJsonb: boolean;
+    /**
+     * JSON column type support.
+     *
+     * @remarks
+     * All supported databases have some form of JSON support:
+     * - PostgreSQL: Native JSON and JSONB
+     * - MySQL: Native JSON column type
+     * - SQLite: JSON functions (json_extract, json_array, etc.)
+     */
+    supportsJson: boolean;
+    /**
+     * Array column type support (PostgreSQL only).
+     *
+     * @remarks
+     * PostgreSQL has native array types. Other databases must use
+     * JSON arrays or separate tables.
+     */
+    supportsArrays: boolean;
+    /**
+     * Generated/computed columns support.
+     *
+     * @remarks
+     * Support for columns whose values are automatically computed from
+     * other columns:
+     * - PostgreSQL: GENERATED ALWAYS AS ... STORED
+     * - MySQL: Generated columns
+     * - SQLite: Generated columns (3.31.0+)
+     */
+    supportsGeneratedColumns: boolean;
+    /**
+     * Full-text search support.
+     *
+     * @remarks
+     * Native full-text search capabilities:
+     * - PostgreSQL: tsvector/tsquery
+     * - MySQL: FULLTEXT indexes (limited)
+     * - SQLite: FTS5 extension (not enabled by default)
+     */
+    supportsFts: boolean;
+    /**
+     * Case-insensitive ILIKE operator support (PostgreSQL only).
+     *
+     * @remarks
+     * Other databases must emulate with LOWER(column) LIKE LOWER(value).
+     */
+    supportsIlike: boolean;
+    /**
+     * RETURNING clause support.
+     *
+     * @remarks
+     * Support for returning data from INSERT/UPDATE/DELETE:
+     * - PostgreSQL: Yes
+     * - MySQL: No (requires separate SELECT)
+     * - SQLite: Yes
+     */
+    supportsReturning: boolean;
+    /**
+     * Savepoint support for nested transactions.
+     *
+     * @remarks
+     * - PostgreSQL: Yes
+     * - MySQL: No (limited support, not recommended)
+     * - SQLite: Yes
+     */
+    supportsSavepoints: boolean;
+    /**
+     * ON CONFLICT clause support for upserts.
+     *
+     * @remarks
+     * - PostgreSQL: ON CONFLICT DO NOTHING/UPDATE
+     * - MySQL: ON DUPLICATE KEY UPDATE (different syntax)
+     * - SQLite: ON CONFLICT (similar to PostgreSQL)
+     */
+    supportsOnConflict: boolean;
+    /**
+     * Maximum number of parameters per query.
+     *
+     * @remarks
+     * Database-specific limits:
+     * - PostgreSQL: 65,535
+     * - MySQL: 65,535
+     * - SQLite: 999 (can be increased with SQLITE_MAX_VARIABLE_NUMBER)
+     */
+    maxParamsPerQuery: number;
+    /**
+     * Maximum length for table/column identifiers.
+     *
+     * @remarks
+     * - PostgreSQL: 63 bytes
+     * - MySQL: 64 characters
+     * - SQLite: No limit (practically unlimited)
+     */
+    maxIdentifierLength: number;
+}
+/**
+ * Connection pool statistics.
+ *
+ * @remarks
+ * Provides visibility into connection pool health. Not all adapters
+ * provide pool statistics (e.g., SQLite is single-connection).
+ *
+ * @public
+ */
+interface PoolStats {
+    /** Total number of connections in the pool */
+    total: number;
+    /** Number of idle (available) connections */
+    idle: number;
+    /** Number of clients waiting for a connection */
+    waiting: number;
+    /** Number of connections currently in use */
+    active: number;
+}
+
+/**
+ * Database migration type definitions.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Migration definition.
+ *
+ * @remarks
+ * Represents a single database migration with up and optional down functions.
+ * Migrations can be defined as raw SQL strings or as functions that use the
+ * transaction context for more complex operations.
+ *
+ * @public
+ */
+interface Migration {
+    /** Unique migration identifier (e.g., "20250104_001_create_users") */
+    id: string;
+    /** Human-readable migration name */
+    name: string;
+    /** Unix timestamp when migration was created */
+    timestamp: number;
+    /** Forward migration (apply changes) */
+    up: string | ((tx: TransactionContext) => Promise<void>);
+    /** Reverse migration (undo changes) - optional */
+    down?: string | ((tx: TransactionContext) => Promise<void>);
+}
+/**
+ * Migration record stored in the database.
+ *
+ * @remarks
+ * Tracks which migrations have been applied to the database.
+ * The migrations table is automatically created by the adapter.
+ *
+ * @public
+ */
+interface MigrationRecord {
+    /** Migration identifier */
+    id: string;
+    /** Migration name */
+    name: string;
+    /** When the migration was applied */
+    appliedAt: Date;
+    /** Optional checksum to detect migration changes */
+    checksum?: string;
+}
+/**
+ * Migration execution result.
+ *
+ * @remarks
+ * Provides information about migration status including applied and
+ * pending migrations.
+ *
+ * @public
+ */
+interface MigrationResult {
+    /** Migrations that were applied in this execution */
+    applied: MigrationRecord[];
+    /** Migrations that are pending (not yet applied) */
+    pending: Migration[];
+    /** ID of the current (most recent) migration, or null if none applied */
+    current: string | null;
+}
+/**
+ * Options for migration execution.
+ *
+ * @public
+ */
+interface MigrationOptions {
+    /** Target migration to migrate to (default: latest) */
+    target?: string;
+    /** Dry run mode - don't actually apply migrations */
+    dryRun?: boolean;
+    /** Run migrations in a single transaction (default: true) */
+    useTransaction?: boolean;
+    /**
+     * Strict checksum validation (default: true).
+     * If true, modified migrations will cause an error.
+     * If false, modified migrations will generate a warning.
+     */
+    strictChecksums?: boolean;
+}
+/**
+ * Migration status information.
+ *
+ * @public
+ */
+interface MigrationStatus {
+    /** Current migration ID (most recently applied) */
+    current: string | null;
+    /** Total number of applied migrations */
+    appliedCount: number;
+    /** Total number of pending migrations */
+    pendingCount: number;
+    /** Applied migration records */
+    applied: MigrationRecord[];
+    /** Pending migrations */
+    pending: Migration[];
+}
+
+export type { DatabaseCapabilities as D, InsertOptions as I, JoinSpec as J, MigrationRecord as M, OrderBySpec as O, PoolStats as P, SelectOptions as S, TransactionContext as T, UpdateOptions as U, WhereClause as W, Migration as a, MigrationStatus as b, MigrationOptions as c, MigrationResult as d, TransactionOptions as e, DeleteOptions as f, UpsertOptions as g, TransactionIsolationLevel as h, WhereCondition as i, WhereOperator as j };