@remix-run/data-table-mysql 0.0.0 → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Shopify Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,90 @@
-# Placeholder package
+# data-table-mysql
 
-This package is intentionally empty and published only as a temporary placeholder.
+MySQL adapter for [`remix/data-table`](https://github.com/remix-run/remix/tree/main/packages/data-table).
+Use this package when you want `data-table` APIs backed by `mysql2`.
+
+## Features
+
+- **Native `mysql2` Integration**: Works with `mysql2/promise` connection pools
+- **Full `data-table` API Support**: Queries, relations, writes, and transactions
+- **MySQL Capabilities Enabled By Default**:
+  - `returning: false`
+  - `savepoints: true`
+  - `upsert: true`
+
+## Installation
+
+```sh
+npm i remix mysql2
+```
+
+## Usage
+
+```ts
+import { createPool } from 'mysql2/promise'
+import { createDatabase } from 'remix/data-table'
+import { createMysqlDatabaseAdapter } from 'remix/data-table-mysql'
+
+let pool = createPool(process.env.DATABASE_URL as string)
+let db = createDatabase(createMysqlDatabaseAdapter(pool))
+```
+
+Use `db.query(...)`, relation loading, and transactions from `remix/data-table`.
+
+## Adapter Capabilities
+
+`data-table-mysql` reports this capability set by default:
+
+- `returning: false`
+- `savepoints: true`
+- `upsert: true`
+
+## Advanced Usage
+
+### Capability Overrides For Testing
+
+Capability overrides are mainly for tests where you want to force or disable specific behavior
+checks. In production, keep defaults so adapter behavior matches MySQL behavior.
+
+```ts
+import { createMysqlDatabaseAdapter } from 'remix/data-table-mysql'
+
+let adapter = createMysqlDatabaseAdapter(pool, {
+  capabilities: {
+    upsert: false,
+  },
+})
+```
+
+### `returning` On MySQL
+
+MySQL does not natively support SQL `RETURNING`. In this adapter, using `returning` on write
+operations throws `DataTableQueryError`.
+
+Use write metadata (`affectedRows`, `insertId`) on MySQL, or switch adapters when returned rows
+are required.
+
+```ts
+import { DataTableQueryError } from 'remix/data-table'
+
+try {
+  await db
+    .query(Accounts)
+    .insert({ email: 'a@example.com', status: 'active' }, { returning: ['id'] })
+} catch (error) {
+  if (error instanceof DataTableQueryError) {
+    // insert() returning is not supported by this adapter
+  }
+}
+```
+
+## Related Packages
+
+- [`data-table`](https://github.com/remix-run/remix/tree/main/packages/data-table) - Core query/relations API
+- [`data-schema`](https://github.com/remix-run/remix/tree/main/packages/data-schema) - Schema definitions and validation
+- [`data-table-postgres`](https://github.com/remix-run/remix/tree/main/packages/data-table-postgres) - PostgreSQL adapter
+- [`data-table-sqlite`](https://github.com/remix-run/remix/tree/main/packages/data-table-sqlite) - SQLite adapter
+
+## License
+
+See [LICENSE](https://github.com/remix-run/remix/blob/main/LICENSE)

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export type { MysqlDatabaseAdapterOptions, MysqlDatabaseConnection, MysqlDatabasePool, MysqlQueryResponse, MysqlQueryResultHeader, MysqlQueryRows, } from './lib/adapter.ts';
+export { createMysqlDatabaseAdapter, MysqlDatabaseAdapter } from './lib/adapter.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,2BAA2B,EAC3B,uBAAuB,EACvB,iBAAiB,EACjB,kBAAkB,EAClB,sBAAsB,EACtB,cAAc,GACf,MAAM,kBAAkB,CAAA;AACzB,OAAO,EAAE,0BAA0B,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAA"}

package/dist/index.js

@@ -0,0 +1 @@
+export { createMysqlDatabaseAdapter, MysqlDatabaseAdapter } from "./lib/adapter.js";

package/dist/lib/adapter.d.ts

@@ -0,0 +1,69 @@
+import type { AdapterCapabilityOverrides, AdapterExecuteRequest, AdapterResult, DatabaseAdapter, TransactionOptions, TransactionToken } from '@remix-run/data-table';
+/**
+ * Row-array response shape for mysql query calls.
+ */
+export type MysqlQueryRows = Record<string, unknown>[];
+/**
+ * Metadata shape for mysql write results.
+ */
+export type MysqlQueryResultHeader = {
+    affectedRows: number;
+    insertId: unknown;
+};
+/**
+ * Supported mysql `query()` response tuple.
+ */
+export type MysqlQueryResponse = [result: unknown, fields?: unknown];
+/**
+ * Single mysql connection contract used by this adapter.
+ */
+export type MysqlDatabaseConnection = {
+    query(text: string, values?: unknown[]): Promise<MysqlQueryResponse>;
+    beginTransaction(): Promise<void>;
+    commit(): Promise<void>;
+    rollback(): Promise<void>;
+    release?: () => void;
+};
+/**
+ * Mysql pool contract used by this adapter.
+ */
+export type MysqlDatabasePool = {
+    query(text: string, values?: unknown[]): Promise<MysqlQueryResponse>;
+    getConnection(): Promise<MysqlDatabaseConnection>;
+};
+/**
+ * Mysql adapter configuration.
+ */
+export type MysqlDatabaseAdapterOptions = {
+    capabilities?: AdapterCapabilityOverrides;
+};
+type MysqlQueryable = MysqlDatabasePool | MysqlDatabaseConnection;
+/**
+ * `DatabaseAdapter` implementation for mysql-compatible clients.
+ */
+export declare class MysqlDatabaseAdapter implements DatabaseAdapter {
+    #private;
+    dialect: string;
+    capabilities: {
+        returning: boolean;
+        savepoints: boolean;
+        upsert: boolean;
+    };
+    constructor(client: MysqlQueryable, options?: MysqlDatabaseAdapterOptions);
+    execute(request: AdapterExecuteRequest): Promise<AdapterResult>;
+    beginTransaction(options?: TransactionOptions): Promise<TransactionToken>;
+    commitTransaction(token: TransactionToken): Promise<void>;
+    rollbackTransaction(token: TransactionToken): Promise<void>;
+    createSavepoint(token: TransactionToken, name: string): Promise<void>;
+    rollbackToSavepoint(token: TransactionToken, name: string): Promise<void>;
+    releaseSavepoint(token: TransactionToken, name: string): Promise<void>;
+}
+/**
+ * Creates a mysql `DatabaseAdapter`.
+ * @param client Mysql pool or connection.
+ * @param options Optional adapter capability overrides.
+ * @returns A configured mysql adapter.
+ */
+export declare function createMysqlDatabaseAdapter(client: MysqlQueryable, options?: MysqlDatabaseAdapterOptions): MysqlDatabaseAdapter;
+export {};
+//# sourceMappingURL=adapter.d.ts.map

package/dist/lib/adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../../src/lib/adapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,0BAA0B,EAC1B,qBAAqB,EACrB,aAAa,EACb,eAAe,EACf,kBAAkB,EAClB,gBAAgB,EACjB,MAAM,uBAAuB,CAAA;AAK9B;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAA;AAEtD;;GAEG;AACH,MAAM,MAAM,sBAAsB,GAAG;IACnC,YAAY,EAAE,MAAM,CAAA;IACpB,QAAQ,EAAE,OAAO,CAAA;CAClB,CAAA;AAED;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAAG,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,OAAO,CAAC,CAAA;AAEpE;;GAEG;AACH,MAAM,MAAM,uBAAuB,GAAG;IACpC,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAA;IACpE,gBAAgB,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IACjC,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IACvB,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IACzB,OAAO,CAAC,EAAE,MAAM,IAAI,CAAA;CACrB,CAAA;AAED;;GAEG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAA;IACpE,aAAa,IAAI,OAAO,CAAC,uBAAuB,CAAC,CAAA;CAClD,CAAA;AAED;;GAEG;AACH,MAAM,MAAM,2BAA2B,GAAG;IACxC,YAAY,CAAC,EAAE,0BAA0B,CAAA;CAC1C,CAAA;AAOD,KAAK,cAAc,GAAG,iBAAiB,GAAG,uBAAuB,CAAA;AAEjE;;GAEG;AACH,qBAAa,oBAAqB,YAAW,eAAe;;IAC1D,OAAO,SAAU;IACjB,YAAY;;;;MAAA;IAMZ,YAAY,MAAM,EAAE,cAAc,EAAE,OAAO,CAAC,EAAE,2BAA2B,EAOxE;IAEK,OAAO,CAAC,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,aAAa,CAAC,CA6BpE;IAEK,gBAAgB,CAAC,OAAO,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAgC9E;IAEK,iBAAiB,CAAC,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAgB9D;IAEK,mBAAmB,CAAC,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAgBhE;IAEK,eAAe,CAAC,KAAK,EAAE,gBAAgB,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAG1E;IAEK,mBAAmB,CAAC,KAAK,EAAE,gBAAgB,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAG9E;IAEK,gBAAgB,CAAC,KAAK,EAAE,gBAAgB,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAG3E;CAmBF;AAED;;;;;GAKG;AACH,wBAAgB,0BAA0B,CACxC,MAAM,EAAE,cAAc,EACtB,OAAO,CAAC,EAAE,2BAA2B,GACpC,oBAAoB,CAEtB"}

package/dist/lib/adapter.js

@@ -0,0 +1,194 @@
+import { getTablePrimaryKey } from '@remix-run/data-table';
+import { compileMysqlStatement } from "./sql-compiler.js";
+/**
+ * `DatabaseAdapter` implementation for mysql-compatible clients.
+ */
+export class MysqlDatabaseAdapter {
+    dialect = 'mysql';
+    capabilities;
+    #client;
+    #transactions = new Map();
+    #transactionCounter = 0;
+    constructor(client, options) {
+        this.#client = client;
+        this.capabilities = {
+            returning: options?.capabilities?.returning ?? false,
+            savepoints: options?.capabilities?.savepoints ?? true,
+            upsert: options?.capabilities?.upsert ?? true,
+        };
+    }
+    async execute(request) {
+        if (request.statement.kind === 'insertMany' && request.statement.values.length === 0) {
+            return {
+                affectedRows: 0,
+                insertId: undefined,
+                rows: request.statement.returning ? [] : undefined,
+            };
+        }
+        let statement = compileMysqlStatement(request.statement);
+        let client = this.#resolveClient(request.transaction);
+        let [result] = await client.query(statement.text, statement.values);
+        if (isRowsResult(result)) {
+            let rows = normalizeRows(result);
+            if (request.statement.kind === 'count' || request.statement.kind === 'exists') {
+                rows = normalizeCountRows(rows);
+            }
+            return { rows };
+        }
+        let header = normalizeHeader(result);
+        return {
+            affectedRows: header.affectedRows,
+            insertId: normalizeInsertId(request.statement.kind, request.statement, header),
+        };
+    }
+    async beginTransaction(options) {
+        let releaseOnClose = false;
+        let connection;
+        if (isMysqlPool(this.#client)) {
+            connection = await this.#client.getConnection();
+            releaseOnClose = true;
+        }
+        else {
+            connection = this.#client;
+        }
+        if (options?.isolationLevel) {
+            await connection.query('set transaction isolation level ' + options.isolationLevel);
+        }
+        if (options?.readOnly !== undefined) {
+            await connection.query(options.readOnly ? 'set transaction read only' : 'set transaction read write');
+        }
+        await connection.beginTransaction();
+        this.#transactionCounter += 1;
+        let token = { id: 'tx_' + String(this.#transactionCounter) };
+        this.#transactions.set(token.id, {
+            connection,
+            releaseOnClose,
+        });
+        return token;
+    }
+    async commitTransaction(token) {
+        let transaction = this.#transactions.get(token.id);
+        if (!transaction) {
+            throw new Error('Unknown transaction token: ' + token.id);
+        }
+        try {
+            await transaction.connection.commit();
+        }
+        finally {
+            this.#transactions.delete(token.id);
+            if (transaction.releaseOnClose) {
+                transaction.connection.release?.();
+            }
+        }
+    }
+    async rollbackTransaction(token) {
+        let transaction = this.#transactions.get(token.id);
+        if (!transaction) {
+            throw new Error('Unknown transaction token: ' + token.id);
+        }
+        try {
+            await transaction.connection.rollback();
+        }
+        finally {
+            this.#transactions.delete(token.id);
+            if (transaction.releaseOnClose) {
+                transaction.connection.release?.();
+            }
+        }
+    }
+    async createSavepoint(token, name) {
+        let connection = this.#transactionConnection(token);
+        await connection.query('savepoint ' + quoteIdentifier(name));
+    }
+    async rollbackToSavepoint(token, name) {
+        let connection = this.#transactionConnection(token);
+        await connection.query('rollback to savepoint ' + quoteIdentifier(name));
+    }
+    async releaseSavepoint(token, name) {
+        let connection = this.#transactionConnection(token);
+        await connection.query('release savepoint ' + quoteIdentifier(name));
+    }
+    #resolveClient(token) {
+        if (!token) {
+            return this.#client;
+        }
+        return this.#transactionConnection(token);
+    }
+    #transactionConnection(token) {
+        let transaction = this.#transactions.get(token.id);
+        if (!transaction) {
+            throw new Error('Unknown transaction token: ' + token.id);
+        }
+        return transaction.connection;
+    }
+}
+/**
+ * Creates a mysql `DatabaseAdapter`.
+ * @param client Mysql pool or connection.
+ * @param options Optional adapter capability overrides.
+ * @returns A configured mysql adapter.
+ */
+export function createMysqlDatabaseAdapter(client, options) {
+    return new MysqlDatabaseAdapter(client, options);
+}
+function isMysqlPool(client) {
+    return typeof client.getConnection === 'function';
+}
+function isRowsResult(result) {
+    return Array.isArray(result) && (result.length === 0 || !Array.isArray(result[0]));
+}
+function normalizeRows(rows) {
+    return rows.map((row) => ({ ...row }));
+}
+function normalizeHeader(result) {
+    if (typeof result === 'object' && result !== null) {
+        let header = result;
+        return {
+            affectedRows: typeof header.affectedRows === 'number' ? header.affectedRows : 0,
+            insertId: header.insertId,
+        };
+    }
+    return {
+        affectedRows: 0,
+        insertId: undefined,
+    };
+}
+function normalizeCountRows(rows) {
+    return rows.map((row) => {
+        let count = row.count;
+        if (typeof count === 'string') {
+            let numeric = Number(count);
+            if (!Number.isNaN(numeric)) {
+                return {
+                    ...row,
+                    count: numeric,
+                };
+            }
+        }
+        if (typeof count === 'bigint') {
+            return {
+                ...row,
+                count: Number(count),
+            };
+        }
+        return row;
+    });
+}
+function normalizeInsertId(kind, statement, header) {
+    if (!isInsertStatementKind(kind) || !isInsertStatement(statement)) {
+        return undefined;
+    }
+    if (getTablePrimaryKey(statement.table).length !== 1) {
+        return undefined;
+    }
+    return header.insertId;
+}
+function quoteIdentifier(value) {
+    return '`' + value.replace(/`/g, '``') + '`';
+}
+function isInsertStatementKind(kind) {
+    return kind === 'insert' || kind === 'insertMany' || kind === 'upsert';
+}
+function isInsertStatement(statement) {
+    return (statement.kind === 'insert' || statement.kind === 'insertMany' || statement.kind === 'upsert');
+}

package/dist/lib/sql-compiler.d.ts

@@ -0,0 +1,8 @@
+import type { AdapterStatement } from '@remix-run/data-table';
+type CompiledSql = {
+    text: string;
+    values: unknown[];
+};
+export declare function compileMysqlStatement(statement: AdapterStatement): CompiledSql;
+export {};
+//# sourceMappingURL=sql-compiler.d.ts.map

package/dist/lib/sql-compiler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sql-compiler.d.ts","sourceRoot":"","sources":["../../src/lib/sql-compiler.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAa,MAAM,uBAAuB,CAAA;AAMxE,KAAK,WAAW,GAAG;IACjB,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,OAAO,EAAE,CAAA;CAClB,CAAA;AAMD,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,gBAAgB,GAAG,WAAW,CAgG9E"}