turbine-orm 0.49.0 → 0.50.0

package/dist/cjs/mysql.d.ts

@@ -0,0 +1,173 @@
+/**
+ * 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 {};

package/dist/cjs/mysql.js

@@ -375,6 +375,10 @@ exports.mysqlDialect = {
     // No RETURNING → run the write, then re-SELECT by PK/where (Phase-0 reselect).
     resultStrategy: 'reselect',
     supportsReturning: false,
+    // `ON DUPLICATE KEY UPDATE` has no predicate slot, so `buildUpsertStatement`
+    // below cannot emit `input.updateWhere`. Reporting false keeps the builder
+    // from compiling one (and from binding its now-orphaned parameters).
+    supportsUpsertUpdateWhere: false,
     supportsILike: false,
     supportsVector: false,
     // MySQL full-text is `MATCH(col) AGAINST(...)` over a FULLTEXT index: a
@@ -414,6 +418,18 @@ exports.mysqlDialect = {
     quoteIdentifier(name) {
         return `\`${name.replace(/`/g, '``')}\``;
     },
+    /**
+     * MySQL is NOT Postgres here: unless the server runs with
+     * `NO_BACKSLASH_ESCAPES`, `\` is an escape character inside a string literal,
+     * so doubling only `'` (the inherited Postgres rule) leaves a value ending in
+     * a backslash able to escape its own closing quote. Escape the backslash
+     * first, then the quote; every other byte is safe raw. The only caller is
+     * `buildJsonObject` (relation / column names from schema metadata), so this
+     * is defence in depth rather than a user-value path.
+     */
+    escapeStringLiteral(value) {
+        return value.replace(/\\/g, '\\\\').replace(/'/g, "''");
+    },
     buildJsonObject(pairs) {
         const args = pairs.map(([key, expr]) => `'${this.escapeStringLiteral(key)}', ${expr}`);
         return `JSON_OBJECT(${args.join(', ')})`;

package/dist/cjs/nested-write.d.ts

@@ -0,0 +1,96 @@
+/**
+ * turbine-orm — Nested write engine
+ *
+ * Tree-walking create/update that resolves relation fields in `data` into
+ * batched SQL operations within a transaction. Supports create, connect,
+ * connectOrCreate, disconnect, set, delete, update, and upsert on related
+ * records at arbitrary depth (capped at 10).
+ *
+ * This module is imported by `query/builder.ts` when the `data` argument
+ * of `create()` or `update()` contains relation fields. It never imports
+ * `client.ts` directly — the transaction handle is passed in via
+ * `NestedWriteContext`.
+ */
+import type { RelationDef, SchemaMetadata, TableMetadata } from './schema.js';
+export interface ExtractedFields {
+    scalars: Record<string, unknown>;
+    relations: Record<string, Record<string, unknown>>;
+}
+/**
+ * Transaction context for nested write operations.
+ * Matches the subset of TransactionClient that we actually use.
+ */
+export interface NestedWriteContext {
+    schema: SchemaMetadata;
+    tx: {
+        table<T extends object>(name: string): {
+            create(args: {
+                data: Partial<T>;
+            }): Promise<T>;
+            createMany(args: {
+                data: Partial<T>[];
+                skipDuplicates?: boolean;
+            }): Promise<T[]>;
+            update(args: {
+                where: Record<string, unknown>;
+                data: Record<string, unknown>;
+            }): Promise<T>;
+            updateMany(args: {
+                where: Record<string, unknown>;
+                data: Record<string, unknown>;
+                allowFullTableScan?: boolean;
+            }): Promise<{
+                count: number;
+            }>;
+            delete(args: {
+                where: Record<string, unknown>;
+            }): Promise<T>;
+            deleteMany(args: {
+                where: Record<string, unknown>;
+            }): Promise<{
+                count: number;
+            }>;
+            findMany(args: {
+                where: Record<string, unknown>;
+                warnOnUnlimited?: boolean;
+            }): Promise<T[]>;
+            findUnique(args: {
+                where: Record<string, unknown>;
+                with?: Record<string, unknown>;
+            }): Promise<T | null>;
+        };
+    };
+}
+/**
+ * Separates scalar data fields from relation operation fields.
+ *
+ * A key is treated as a relation field only when:
+ * 1. It matches a relation name in `tableMeta.relations`
+ * 2. Its value is a non-null, non-array, non-Date plain object
+ *
+ * Everything else goes into `scalars`.
+ */
+export declare function extractRelationFields(data: Record<string, unknown>, tableMeta: TableMetadata): ExtractedFields;
+/**
+ * Quick check: does `data` contain any relation fields that would trigger
+ * the nested write path? Used by QueryInterface to decide whether to
+ * delegate to the nested write engine or take the fast scalar-only path.
+ */
+export declare function hasRelationFields(data: Record<string, unknown>, tableMeta: TableMetadata): boolean;
+/**
+ * Inject the parent row's PK value(s) as FK field(s) into child data.
+ * Handles composite keys. Returns a new object (does not mutate input).
+ */
+export declare function injectForeignKey(childData: Record<string, unknown>, relation: RelationDef, parentRow: Record<string, unknown>, schema: SchemaMetadata): Record<string, unknown>;
+/**
+ * Tree-walking create: inserts the parent row, then processes each relation
+ * operation (create, connect, connectOrCreate), and finally reads back the
+ * full tree using `findUnique` with an auto-built `with` clause.
+ */
+export declare function executeNestedCreate(ctx: NestedWriteContext, tableName: string, data: Record<string, unknown>, depth?: number, path?: string[]): Promise<Record<string, unknown>>;
+/**
+ * Tree-walking update: updates the parent row with scalar data, then
+ * processes each relation operation (create, connect, connectOrCreate,
+ * disconnect, set, delete), and reads back the full tree.
+ */
+export declare function executeNestedUpdate(ctx: NestedWriteContext, tableName: string, where: Record<string, unknown>, data: Record<string, unknown>, depth?: number, path?: string[]): Promise<Record<string, unknown>>;