@atscript/db-mysql 0.1.39 → 0.1.40

package/dist/index.d.ts

@@ -1,271 +0,0 @@
-import { BaseDbAdapter, TDbDefaultFn, TExistingTableOption, TTableOptionDiff, TDbFieldMeta, TValueFormatterPair, TDbInsertResult, TDbInsertManyResult, DbQuery, FilterExpr, TDbUpdateResult, TDbDeleteResult, TExistingColumn, TColumnDiff, TSyncColumnResult, TSearchIndexInfo, DbSpace } from '@atscript/db';
-import { TAtscriptAnnotatedType, TMetadataMap } from '@atscript/typescript/utils';
-import * as mysql2_promise from 'mysql2/promise';
-import { TAtscriptPlugin } from '@atscript/core';
-import { FilterExpr as FilterExpr$1 } from '@uniqu/core';
-import { TSqlFragment } from '@atscript/db-sql-tools';
-export { TSqlFragment } from '@atscript/db-sql-tools';
-
-/**
- * Result of a MySQL statement that modifies data (INSERT, UPDATE, DELETE).
- */
-interface TMysqlRunResult {
-    /** Number of rows affected by the statement. */
-    affectedRows: number;
-    /** Auto-generated ID from last INSERT (0 if not applicable). */
-    insertId: number | bigint;
-    /** Number of rows changed by an UPDATE (differs from affectedRows when row matches but value unchanged). */
-    changedRows: number;
-}
-/**
- * Async driver interface for MySQL engines.
- *
- * Unlike SQLite's synchronous driver, MySQL is network-based
- * and requires async operations throughout.
- *
- * The driver has two modes of operation:
- * 1. **Pool mode** (default) — each call acquires/releases a connection automatically
- * 2. **Connection mode** (for transactions) — a dedicated connection is acquired
- *    and all operations run on it until released
- *
- * Implementations: {@link Mysql2Driver}
- */
-interface TMysqlDriver {
-    /**
-     * Execute a SQL statement that modifies data (INSERT, UPDATE, DELETE, DDL).
-     * Uses parameterized queries (`?` placeholders).
-     */
-    run(sql: string, params?: unknown[]): Promise<TMysqlRunResult>;
-    /**
-     * Execute a query and return all matching rows.
-     */
-    all<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<T[]>;
-    /**
-     * Execute a query and return the first matching row, or null.
-     */
-    get<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<T | null>;
-    /**
-     * Execute raw SQL without returning results.
-     * Used for DDL, SET statements, multi-statement strings, etc.
-     */
-    exec(sql: string): Promise<void>;
-    /**
-     * Acquire a dedicated connection for transaction use.
-     * Returns a {@link TMysqlConnection} that must be released after use.
-     */
-    getConnection(): Promise<TMysqlConnection>;
-    /**
-     * Close the pool / end all connections.
-     */
-    close(): Promise<void>;
-}
-/**
- * A dedicated connection acquired from the pool.
- * Used for transactions where all operations must run on the same connection.
- */
-interface TMysqlConnection {
-    /** Execute a statement that modifies data. */
-    run(sql: string, params?: unknown[]): Promise<TMysqlRunResult>;
-    /** Execute a query and return all matching rows. */
-    all<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<T[]>;
-    /** Execute a query and return the first matching row, or null. */
-    get<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<T | null>;
-    /** Execute raw SQL without returning results. */
-    exec(sql: string): Promise<void>;
-    /** Release this connection back to the pool. */
-    release(): void;
-}
-
-/**
- * MySQL adapter for {@link AtscriptDbTable}.
- *
- * Accepts any {@link TMysqlDriver} implementation — the actual MySQL driver
- * is fully swappable (mysql2/promise pool, custom implementations, etc.).
- *
- * Usage:
- * ```typescript
- * import { Mysql2Driver, MysqlAdapter } from '@atscript/db-mysql'
- * import { DbSpace } from '@atscript/db'
- *
- * const driver = new Mysql2Driver('mysql://root@localhost:3306/mydb')
- * const space = new DbSpace(() => new MysqlAdapter(driver))
- * const users = space.getTable(UsersType)
- * ```
- */
-declare class MysqlAdapter extends BaseDbAdapter {
-    protected readonly driver: TMysqlDriver;
-    supportsColumnModify: boolean;
-    private static readonly NATIVE_DEFAULT_FNS;
-    private _engine;
-    private _charset;
-    private _collation;
-    private _autoIncrementStart?;
-    private _incrementFields;
-    private _onUpdateFields;
-    /** Whether the connected MySQL instance supports native VECTOR type (MySQL 9.0+). */
-    private _supportsVector;
-    /** Vector fields: physical field name → { dimensions, similarity, indexName }. */
-    private _vectorFields;
-    /** Default similarity thresholds per vector field (from @db.search.vector.threshold). */
-    private _vectorThresholds;
-    /** Schema name for INFORMATION_SCHEMA queries (null falls through to DATABASE()). */
-    private get _schema();
-    constructor(driver: TMysqlDriver);
-    protected _beginTransaction(): Promise<TMysqlConnection>;
-    protected _commitTransaction(state: unknown): Promise<void>;
-    protected _rollbackTransaction(state: unknown): Promise<void>;
-    /**
-     * Returns the active executor: dedicated connection if inside a transaction,
-     * otherwise the pool-based driver.
-     */
-    private _exec;
-    /** MySQL InnoDB enforces FK constraints natively. */
-    supportsNativeForeignKeys(): boolean;
-    prepareId(id: unknown, _fieldType: TAtscriptAnnotatedType): unknown;
-    supportsNativeValueDefaults(): boolean;
-    nativeDefaultFns(): ReadonlySet<TDbDefaultFn>;
-    onBeforeFlatten(type: TAtscriptAnnotatedType): void;
-    onFieldScanned(field: string, _type: TAtscriptAnnotatedType, metadata: TMetadataMap<AtscriptMetadata>): void;
-    getDesiredTableOptions(): TExistingTableOption[];
-    getExistingTableOptions(): Promise<TExistingTableOption[]>;
-    applyTableOptions(changes: TTableOptionDiff['changed']): Promise<void>;
-    /**
-     * Returns a value formatter for TIMESTAMP-mapped fields.
-     * Number fields with @db.default.now map to MySQL TIMESTAMP — the formatter
-     * converts epoch ms to a UTC datetime string for the wire protocol.
-     */
-    formatValue(field: TDbFieldMeta): TValueFormatterPair | ((value: unknown) => unknown) | undefined;
-    /**
-     * Wraps an async write operation to catch MySQL constraint errors
-     * and rethrow as structured `DbError`.
-     *
-     * MySQL uses numeric error codes:
-     * - 1062 = ER_DUP_ENTRY (unique constraint violation)
-     * - 1451 = ER_ROW_IS_REFERENCED_2 (FK violation on delete)
-     * - 1452 = ER_NO_REFERENCED_ROW_2 (FK violation on insert/update)
-     */
-    private _wrapConstraintError;
-    private _mapFkError;
-    insertOne(data: Record<string, unknown>): Promise<TDbInsertResult>;
-    insertMany(data: Array<Record<string, unknown>>): Promise<TDbInsertManyResult>;
-    findOne(query: DbQuery): Promise<Record<string, unknown> | null>;
-    findMany(query: DbQuery): Promise<Array<Record<string, unknown>>>;
-    count(query: DbQuery): Promise<number>;
-    aggregate(query: DbQuery): Promise<Array<Record<string, unknown>>>;
-    updateOne(filter: FilterExpr, data: Record<string, unknown>): Promise<TDbUpdateResult>;
-    updateMany(filter: FilterExpr, data: Record<string, unknown>): Promise<TDbUpdateResult>;
-    replaceOne(filter: FilterExpr, data: Record<string, unknown>): Promise<TDbUpdateResult>;
-    replaceMany(filter: FilterExpr, data: Record<string, unknown>): Promise<TDbUpdateResult>;
-    deleteOne(filter: FilterExpr): Promise<TDbDeleteResult>;
-    deleteMany(filter: FilterExpr): Promise<TDbDeleteResult>;
-    ensureTable(): Promise<void>;
-    private _ensureView;
-    getExistingColumns(): Promise<TExistingColumn[]>;
-    getExistingColumnsForTable(tableName: string): Promise<TExistingColumn[]>;
-    syncColumns(diff: TColumnDiff): Promise<TSyncColumnResult>;
-    recreateTable(): Promise<void>;
-    dropTable(): Promise<void>;
-    dropColumns(columns: string[]): Promise<void>;
-    dropTableByName(tableName: string): Promise<void>;
-    dropViewByName(viewName: string): Promise<void>;
-    renameTable(oldName: string): Promise<void>;
-    typeMapper(field: TDbFieldMeta): string;
-    syncIndexes(): Promise<void>;
-    syncForeignKeys(): Promise<void>;
-    dropForeignKeys(fkFieldKeys: string[]): Promise<void>;
-    /** Queries INFORMATION_SCHEMA for existing FK constraints, grouped by constraint name → column names. */
-    private _getExistingFkConstraints;
-    getSearchIndexes(): TSearchIndexInfo[];
-    search(text: string, query: DbQuery, indexName?: string): Promise<Array<Record<string, unknown>>>;
-    searchWithCount(text: string, query: DbQuery, indexName?: string): Promise<{
-        data: Array<Record<string, unknown>>;
-        count: number;
-    }>;
-    private _buildSearchWhere;
-    private _getFulltextIndex;
-    /**
-     * Detects native VECTOR type support by inspecting the server version.
-     * MySQL 9.0+ supports the VECTOR column type natively.
-     * Caches the result for the lifetime of this adapter instance.
-     */
-    private _detectVectorSupport;
-    isVectorSearchable(): boolean;
-    vectorSearch(vector: number[], query: DbQuery, indexName?: string): Promise<Array<Record<string, unknown>>>;
-    vectorSearchWithCount(vector: number[], query: DbQuery, indexName?: string): Promise<{
-        data: Array<Record<string, unknown>>;
-        count: number;
-    }>;
-    /** Resolves vector field and computes shared context for vector search SQL builders. */
-    private _prepareVectorSearch;
-    private _buildVectorSearchQuery;
-    private _buildVectorSearchCountQuery;
-    /** Resolves threshold: query-time $threshold > schema-level @db.search.vector.threshold. */
-    private _resolveVectorThreshold;
-}
-
-/**
- * {@link TMysqlDriver} implementation backed by `mysql2/promise`.
- *
- * Accepts a connection URI string, a `PoolOptions` object, or a pre-created
- * `Pool` instance from `mysql2/promise`.
- *
- * ```typescript
- * import { Mysql2Driver } from '@atscript/db-mysql'
- *
- * // Connection URI
- * const driver = new Mysql2Driver('mysql://root:pass@localhost:3306/mydb')
- *
- * // Pool options
- * const driver = new Mysql2Driver({
- *   host: 'localhost',
- *   user: 'root',
- *   database: 'mydb',
- *   waitForConnections: true,
- *   connectionLimit: 10,
- * })
- *
- * // Pre-created pool
- * import mysql from 'mysql2/promise'
- * const pool = mysql.createPool({ host: 'localhost', database: 'mydb' })
- * const driver = new Mysql2Driver(pool)
- * ```
- *
- * Requires `mysql2` to be installed:
- * ```bash
- * pnpm add mysql2
- * ```
- */
-declare class Mysql2Driver implements TMysqlDriver {
-    private pool;
-    private poolInit;
-    constructor(poolOrConfig: string | mysql2_promise.Pool | mysql2_promise.PoolOptions);
-    private getPool;
-    run(sql: string, params?: unknown[]): Promise<TMysqlRunResult>;
-    all<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<T[]>;
-    get<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<T | null>;
-    exec(sql: string): Promise<void>;
-    getConnection(): Promise<TMysqlConnection>;
-    close(): Promise<void>;
-}
-
-declare const MysqlPlugin: () => TAtscriptPlugin;
-
-/**
- * Translates a uniqu filter expression into a parameterized MySQL WHERE clause.
- *
- * @returns `{ sql, params }` — the WHERE clause (without "WHERE") and bound params.
- *          Returns `{ sql: '1=1', params: [] }` for empty/null filters.
- */
-declare function buildWhere(filter: FilterExpr$1): TSqlFragment;
-
-/**
- * Creates a {@link DbSpace} backed by a MySQL connection pool.
- *
- * @param uri - MySQL connection URI (e.g., `mysql://root@localhost:3306/mydb`)
- * @param options - Additional pool options passed to mysql2.
- * @returns A `DbSpace` that creates `MysqlAdapter` instances per table.
- */
-declare function createAdapter(uri: string, options?: Record<string, unknown>): DbSpace;
-
-export { Mysql2Driver, MysqlAdapter, MysqlPlugin, buildWhere, createAdapter };
-export type { TMysqlConnection, TMysqlDriver, TMysqlRunResult };

package/dist/plugin.d.ts

@@ -1,5 +0,0 @@
-import { TAtscriptPlugin } from '@atscript/core';
-
-declare const MysqlPlugin: () => TAtscriptPlugin;
-
-export { MysqlPlugin };