turbine-orm 0.19.2 → 0.21.0

package/dist/mysql.d.ts

@@ -0,0 +1,174 @@
+/**
+ * turbine-orm/mysql — MySQL 8 engine (driver-injected, optional peer)
+ *
+ * Binds Turbine to MySQL 8 via the `mysql2` driver. `mysql2` is **not** a root
+ * dependency — it is an **optional peer**: `npm i turbine-orm` pulls nothing
+ * extra, and only consumers who `import 'turbine-orm/mysql'` install `mysql2`
+ * themselves. The factory loads it through a dynamic `import('mysql2/promise')`
+ * so importing this module never crashes when `mysql2` is absent for a consumer
+ * who does not use it. Turbine's root runtime dependency stays exactly `pg`.
+ *
+ * ## The two hard MySQL realities this engine solves
+ *
+ *  1. **No `RETURNING`.** `INSERT`/`UPDATE`/`DELETE` cannot return the affected
+ *     rows. `mysqlDialect.resultStrategy = 'reselect'`: the executor runs the
+ *     write, then issues a follow-up `SELECT` by primary key (using mysql2's
+ *     `insertId` for auto-increment PKs) / by the `where` predicate, so
+ *     `create`/`update`/`upsert`/`delete` still return real rows. This is the
+ *     first shipped engine to exercise the Phase-0 `reselect` path.
+ *  2. **Positional `?` is broken for this builder.** Turbine pushes params in
+ *     1-indexed generation order but EMITS them in a different SQL-text position
+ *     (e.g. a `with`-relation `LIMIT` lands in the SELECT list, ahead of the
+ *     outer `WHERE`). Postgres reconciles this via numbered `$N`; positional `?`
+ *     silently mis-binds. So `mysqlDialect` uses **mysql2 named placeholders**
+ *     (`:p1`, `:p2`, …) and the driver shim binds via a `{ p1, p2, … }` object —
+ *     exactly mirroring `$N` semantics regardless of text order. (See
+ *     `turbine-orm/sqlite` for the same fix.)
+ *
+ * ## Capabilities & limits (vs PostgreSQL)
+ *
+ * - **Single query nested relations preserved** via MySQL 8 `JSON_OBJECT` /
+ *   `JSON_ARRAYAGG` with `COALESCE(…, JSON_ARRAY())`. `JSON_ARRAYAGG` has no
+ *   inline `ORDER BY` argument, so every ordered to-many relation is forced
+ *   through the inner-subquery rewrite (`aggSupportsInlineOrderBy = false`).
+ *   Nested subresults are `CAST(… AS JSON)`-wrapped so MySQL embeds them as real
+ *   nested JSON instead of double-encoding a scalar subquery result as a string.
+ * - **`createMany` returns an empty array** (count-not-rows). MySQL has no
+ *   `RETURNING` and the bulk-insert `insertId` is only the first generated id, so
+ *   re-selecting N rows reliably is unsafe. The rows ARE inserted; re-query if you
+ *   need them back. (Plan §4 documented divergence.)
+ * - **Unsupported (throw `UnsupportedFeatureError`):** pgvector distance ops,
+ *   LISTEN/NOTIFY (`$listen`/`$notify`), RLS `sessionContext` (no GUCs).
+ * - **Advisory-lock migration locking** is available in principle via
+ *   `GET_LOCK`/`RELEASE_LOCK` (`supportsAdvisoryLock = true`); the migrate CLI is
+ *   still PostgreSQL-only, so this flag documents intent for a future adapter.
+ * - **Case-insensitive matching** uses `LOWER(col) LIKE LOWER(ref)` — note this
+ *   can defeat indexes unless a functional/generated index exists.
+ * - **bignum:** mysql2 is configured `supportBigNumbers:true, bigNumberStrings:false`
+ *   — the same safe-int policy Turbine uses for Postgres `int8` (number when it
+ *   fits, decimal string otherwise). `DECIMAL` comes back as a string; `TINYINT(1)`
+ *   binds booleans as 1/0. No global parser state is mutated.
+ * - **Version:** MySQL **8.0+** required (5.7 lacks `JSON_ARRAYAGG`); MariaDB is
+ *   unsupported. The factory probes `SELECT VERSION()` and fails fast otherwise.
+ *
+ * ## Example
+ *
+ * ```ts
+ * import { turbineMysql } from 'turbine-orm/mysql';
+ * import { SCHEMA } from './generated/turbine/metadata.js';
+ *
+ * const db = await turbineMysql('mysql://user:pass@localhost:3306/app', SCHEMA);
+ * const users = await db.users.findMany({ with: { posts: true }, limit: 10 });
+ * await db.disconnect();
+ * ```
+ */
+import { type PgCompatPool, type PgCompatPoolClient, TurbineClient, type TurbineConfig } from './client.js';
+import { type Dialect, type IntrospectOptions } from './dialect.js';
+import { type SchemaMetadata } from './schema.js';
+/** mysql2's `[result, fields]` tuple. `result` is rows (SELECT) or a header (write). */
+type Mysql2Result = [unknown, unknown];
+interface Mysql2Queryable {
+    query(sql: string, values?: unknown): Promise<Mysql2Result>;
+    execute(sql: string, values?: unknown): Promise<Mysql2Result>;
+}
+interface Mysql2Connection extends Mysql2Queryable {
+    release(): void;
+}
+interface Mysql2Pool extends Mysql2Queryable {
+    getConnection(): Promise<Mysql2Connection>;
+    end(): Promise<void>;
+    on?(event: string, listener: (...args: any[]) => void): unknown;
+}
+/** pg-style query argument: a SQL string or a `{ text, values }` config object. */
+type QueryArg = string | {
+    name?: string;
+    text: string;
+    values?: unknown[];
+};
+/**
+ * A {@link PgCompatPool} backed by a `mysql2` pool. Non-transaction queries run
+ * on the pool directly (any connection); `connect()` checks out a dedicated
+ * connection so a transaction's `START TRANSACTION` / `COMMIT` / `ROLLBACK` /
+ * `SAVEPOINT` nesting all run on the same physical connection.
+ */
+export declare class MysqlPool implements PgCompatPool {
+    /** The underlying mysql2 pool — exposed as an escape hatch (seed / DDL / advanced ops). */
+    readonly pool: Mysql2Pool;
+    private closed;
+    constructor(pool: Mysql2Pool);
+    query(text: QueryArg, values?: unknown[]): Promise<any>;
+    connect(): Promise<PgCompatPoolClient>;
+    end(): Promise<void>;
+}
+/**
+ * Map a MySQL column type to a TypeScript type. `dialectType` is the
+ * `information_schema.COLUMNS.DATA_TYPE` (e.g. `bigint`, `varchar`, `datetime`);
+ * `columnType` is the full `COLUMN_TYPE` (e.g. `tinyint(1)`, `enum('a','b')`)
+ * used to detect `TINYINT(1)` booleans.
+ */
+export declare function mysqlTypeToTs(dialectType: string, nullable: boolean, columnType?: string): string;
+/**
+ * MySQL 8 implementation of the {@link Dialect} contract. Backtick identifier
+ * quoting, named `:pN` placeholders (NOT positional `?` — see the module
+ * docstring), `JSON_OBJECT` / `JSON_ARRAYAGG` for the single-query nested
+ * relation engine (`CAST(… AS JSON)`-wrapped nested subresults), no `RETURNING`
+ * (`resultStrategy = 'reselect'`), `INSERT … ON DUPLICATE KEY UPDATE` upserts,
+ * and the Postgres-only capabilities disabled (vector / LISTEN-NOTIFY / RLS).
+ */
+export declare const mysqlDialect: Dialect;
+/** Async executor that returns plain row objects for a parameterized query. */
+export type MysqlRowExecutor = (sql: string, params: unknown[]) => Promise<Record<string, unknown>[]>;
+/**
+ * Introspect a MySQL database into the same {@link SchemaMetadata} shape the
+ * Postgres catalog introspector produces, using a caller-supplied query
+ * executor (so tests can dogfood an already-open mysql2 pool/connection).
+ *
+ * @param exec    Runs a parameterized (`:p1`, `:p2`, …) query and returns rows.
+ * @param schema  The MySQL database (schema) name to introspect.
+ * @param options Optional include / exclude table-name filters.
+ */
+export declare function introspectMysqlWith(exec: MysqlRowExecutor, schema: string, options?: {
+    include?: string[];
+    exclude?: string[];
+}): Promise<SchemaMetadata>;
+/**
+ * Open a short-lived mysql2 connection from `options.connectionString`,
+ * introspect the database (schema = `options.schema` or the connection's current
+ * database), and close it. Wraps {@link introspectMysqlWith} for the
+ * {@link DialectIntrospector} seam used by `introspect()` / `npx turbine generate`.
+ */
+export declare function introspectMysql(options: IntrospectOptions): Promise<SchemaMetadata>;
+interface MysqlConnectionConfig {
+    host?: string;
+    port?: number;
+    user?: string;
+    password?: string;
+    database?: string;
+}
+/** Options for {@link turbineMysql}. Mirrors the relevant {@link TurbineConfig} fields. */
+export interface TurbineMysqlOptions extends Pick<TurbineConfig, 'logging' | 'defaultLimit' | 'warnOnUnlimited'> {
+    /** Maximum number of pooled connections (when Turbine builds the pool). Default: 10. */
+    connectionLimit?: number;
+}
+/**
+ * Create a {@link TurbineClient} bound to MySQL 8 via `mysql2`.
+ *
+ * Pass one of:
+ *  - a connection string (`'mysql://user:pass@host:3306/db'`),
+ *  - a mysql2 connection config object (`{ host, user, password, database }`), or
+ *  - an existing mysql2 pool / {@link MysqlPool} (injection — you own its lifecycle,
+ *    `disconnect()` is a no-op, advanced config like SSL lives here).
+ *
+ * When Turbine builds the pool (string/config), it pins the correct mysql2 flags
+ * (named placeholders, bignum, UTC dates, JSON-as-string), probes `SELECT VERSION()`
+ * to reject MySQL < 8.0 / MariaDB, and `disconnect()` closes the pool it created.
+ *
+ * @example
+ * ```ts
+ * import { turbineMysql } from 'turbine-orm/mysql';
+ * const db = await turbineMysql('mysql://root:root@localhost:3306/app', SCHEMA);
+ * ```
+ */
+export declare function turbineMysql(target: string | MysqlConnectionConfig | Mysql2Pool | MysqlPool, schema: SchemaMetadata, options?: TurbineMysqlOptions): Promise<TurbineClient>;
+export {};
+//# sourceMappingURL=mysql.d.ts.map