@remix-run/data-table-postgres 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,81 @@
-# Placeholder package
+# data-table-postgres
 
-This package is intentionally empty and published only as a temporary placeholder.
+PostgreSQL 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 `pg`.
+
+## Features
+
+- **Native `pg` Integration**: Works with `Pool` and Postgres connection strings
+- **Full `data-table` API Support**: Queries, relations, writes, and transactions
+- **Postgres Capabilities Enabled By Default**:
+  - `returning: true`
+  - `savepoints: true`
+  - `upsert: true`
+
+## Installation
+
+```sh
+npm i remix pg
+```
+
+## Usage
+
+```ts
+import { Pool } from 'pg'
+import { createDatabase } from 'remix/data-table'
+import { createPostgresDatabaseAdapter } from 'remix/data-table-postgres'
+
+let pool = new Pool({
+  connectionString: process.env.DATABASE_URL,
+})
+
+let db = createDatabase(createPostgresDatabaseAdapter(pool))
+```
+
+Use `db.query(...)`, relation loading, and transactions from `remix/data-table`.
+
+## Adapter Capabilities
+
+`data-table-postgres` reports this capability set by default:
+
+- `returning: true`
+- `savepoints: true`
+- `upsert: true`
+
+## Advanced Usage
+
+### Transaction Options
+
+Transaction options are passed through to the adapter as hints.
+
+```ts
+await db.transaction(async (txDb) => txDb.exec('select 1'), {
+  isolationLevel: 'serializable',
+  readOnly: false,
+})
+```
+
+### Capability Overrides For Testing
+
+You can override capabilities to verify fallback paths in tests.
+
+```ts
+import { createPostgresDatabaseAdapter } from 'remix/data-table-postgres'
+
+let adapter = createPostgresDatabaseAdapter(pool, {
+  capabilities: {
+    returning: false,
+  },
+})
+```
+
+## 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-mysql`](https://github.com/remix-run/remix/tree/main/packages/data-table-mysql) - MySQL 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 { PostgresDatabaseAdapterOptions, PostgresDatabaseClient, PostgresDatabasePool, PostgresQueryResult, PostgresTransactionClient, } from './lib/adapter.ts';
+export { createPostgresDatabaseAdapter, PostgresDatabaseAdapter } 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,8BAA8B,EAC9B,sBAAsB,EACtB,oBAAoB,EACpB,mBAAmB,EACnB,yBAAyB,GAC1B,MAAM,kBAAkB,CAAA;AACzB,OAAO,EAAE,6BAA6B,EAAE,uBAAuB,EAAE,MAAM,kBAAkB,CAAA"}

package/dist/index.js

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

package/dist/lib/adapter.d.ts

@@ -0,0 +1,64 @@
+import type { AdapterCapabilityOverrides, AdapterExecuteRequest, AdapterResult, DatabaseAdapter, TransactionOptions, TransactionToken } from '@remix-run/data-table';
+type Pretty<value> = {
+    [key in keyof value]: value[key];
+} & {};
+/**
+ * Result shape returned by postgres client `query()` calls.
+ */
+export type PostgresQueryResult = {
+    rows: unknown[];
+    rowCount: number | null;
+};
+/**
+ * Minimal postgres client contract used by this adapter.
+ */
+export type PostgresDatabaseClient = {
+    query(text: string, values?: unknown[]): Promise<PostgresQueryResult>;
+};
+/**
+ * Postgres transaction client with optional connection release support.
+ */
+export type PostgresTransactionClient = Pretty<PostgresDatabaseClient & {
+    release?: () => void;
+}>;
+/**
+ * Postgres pool-like client contract used by this adapter.
+ */
+export type PostgresDatabasePool = Pretty<PostgresDatabaseClient & {
+    connect?: () => Promise<PostgresTransactionClient>;
+}>;
+/**
+ * Postgres adapter configuration.
+ */
+export type PostgresDatabaseAdapterOptions = {
+    capabilities?: AdapterCapabilityOverrides;
+};
+/**
+ * `DatabaseAdapter` implementation for postgres-compatible clients.
+ */
+export declare class PostgresDatabaseAdapter implements DatabaseAdapter {
+    #private;
+    dialect: string;
+    capabilities: {
+        returning: boolean;
+        savepoints: boolean;
+        upsert: boolean;
+    };
+    constructor(client: PostgresDatabasePool, options?: PostgresDatabaseAdapterOptions);
+    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 postgres `DatabaseAdapter`.
+ * @param client Postgres pool or client.
+ * @param options Optional adapter capability overrides.
+ * @returns A configured postgres adapter.
+ */
+export declare function createPostgresDatabaseAdapter(client: PostgresDatabasePool, options?: PostgresDatabaseAdapterOptions): PostgresDatabaseAdapter;
+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,KAAK,MAAM,CAAC,KAAK,IAAI;KAClB,GAAG,IAAI,MAAM,KAAK,GAAG,KAAK,CAAC,GAAG,CAAC;CACjC,GAAG,EAAE,CAAA;AAEN;;GAEG;AACH,MAAM,MAAM,mBAAmB,GAAG;IAChC,IAAI,EAAE,OAAO,EAAE,CAAA;IACf,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;CACxB,CAAA;AAED;;GAEG;AACH,MAAM,MAAM,sBAAsB,GAAG;IACnC,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAA;CACtE,CAAA;AAED;;GAEG;AACH,MAAM,MAAM,yBAAyB,GAAG,MAAM,CAC5C,sBAAsB,GAAG;IACvB,OAAO,CAAC,EAAE,MAAM,IAAI,CAAA;CACrB,CACF,CAAA;AAED;;GAEG;AACH,MAAM,MAAM,oBAAoB,GAAG,MAAM,CACvC,sBAAsB,GAAG;IACvB,OAAO,CAAC,EAAE,MAAM,OAAO,CAAC,yBAAyB,CAAC,CAAA;CACnD,CACF,CAAA;AAED;;GAEG;AACH,MAAM,MAAM,8BAA8B,GAAG;IAC3C,YAAY,CAAC,EAAE,0BAA0B,CAAA;CAC1C,CAAA;AAOD;;GAEG;AACH,qBAAa,uBAAwB,YAAW,eAAe;;IAC7D,OAAO,SAAa;IACpB,YAAY;;;;MAAA;IAMZ,YAAY,MAAM,EAAE,oBAAoB,EAAE,OAAO,CAAC,EAAE,8BAA8B,EAOjF;IAEK,OAAO,CAAC,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,aAAa,CAAC,CAuBpE;IAEK,gBAAgB,CAAC,OAAO,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CA0B9E;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,6BAA6B,CAC3C,MAAM,EAAE,oBAAoB,EAC5B,OAAO,CAAC,EAAE,8BAA8B,GACvC,uBAAuB,CAEzB"}

package/dist/lib/adapter.js

@@ -0,0 +1,199 @@
+import { getTablePrimaryKey } from '@remix-run/data-table';
+import { compilePostgresStatement } from "./sql-compiler.js";
+/**
+ * `DatabaseAdapter` implementation for postgres-compatible clients.
+ */
+export class PostgresDatabaseAdapter {
+    dialect = 'postgres';
+    capabilities;
+    #client;
+    #transactions = new Map();
+    #transactionCounter = 0;
+    constructor(client, options) {
+        this.#client = client;
+        this.capabilities = {
+            returning: options?.capabilities?.returning ?? true,
+            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 = compilePostgresStatement(request.statement);
+        let client = this.#resolveClient(request.transaction);
+        let result = await client.query(statement.text, statement.values);
+        let rows = normalizeRows(result.rows);
+        if (request.statement.kind === 'count' || request.statement.kind === 'exists') {
+            rows = normalizeCountRows(rows);
+        }
+        return {
+            rows,
+            affectedRows: normalizeAffectedRows(request.statement.kind, result.rowCount, rows),
+            insertId: normalizeInsertId(request.statement.kind, request.statement, rows),
+        };
+    }
+    async beginTransaction(options) {
+        let releaseOnClose = false;
+        let transactionClient;
+        if (this.#client.connect) {
+            transactionClient = await this.#client.connect();
+            releaseOnClose = true;
+        }
+        else {
+            transactionClient = this.#client;
+        }
+        await transactionClient.query('begin');
+        if (options?.isolationLevel || options?.readOnly !== undefined) {
+            await transactionClient.query(buildSetTransactionStatement(options));
+        }
+        this.#transactionCounter += 1;
+        let token = { id: 'tx_' + String(this.#transactionCounter) };
+        this.#transactions.set(token.id, {
+            client: transactionClient,
+            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.client.query('commit');
+        }
+        finally {
+            this.#transactions.delete(token.id);
+            if (transaction.releaseOnClose) {
+                transaction.client.release?.();
+            }
+        }
+    }
+    async rollbackTransaction(token) {
+        let transaction = this.#transactions.get(token.id);
+        if (!transaction) {
+            throw new Error('Unknown transaction token: ' + token.id);
+        }
+        try {
+            await transaction.client.query('rollback');
+        }
+        finally {
+            this.#transactions.delete(token.id);
+            if (transaction.releaseOnClose) {
+                transaction.client.release?.();
+            }
+        }
+    }
+    async createSavepoint(token, name) {
+        let client = this.#transactionClient(token);
+        await client.query('savepoint ' + quoteIdentifier(name));
+    }
+    async rollbackToSavepoint(token, name) {
+        let client = this.#transactionClient(token);
+        await client.query('rollback to savepoint ' + quoteIdentifier(name));
+    }
+    async releaseSavepoint(token, name) {
+        let client = this.#transactionClient(token);
+        await client.query('release savepoint ' + quoteIdentifier(name));
+    }
+    #resolveClient(token) {
+        if (!token) {
+            return this.#client;
+        }
+        return this.#transactionClient(token);
+    }
+    #transactionClient(token) {
+        let transaction = this.#transactions.get(token.id);
+        if (!transaction) {
+            throw new Error('Unknown transaction token: ' + token.id);
+        }
+        return transaction.client;
+    }
+}
+/**
+ * Creates a postgres `DatabaseAdapter`.
+ * @param client Postgres pool or client.
+ * @param options Optional adapter capability overrides.
+ * @returns A configured postgres adapter.
+ */
+export function createPostgresDatabaseAdapter(client, options) {
+    return new PostgresDatabaseAdapter(client, options);
+}
+function buildSetTransactionStatement(options) {
+    let parts = ['set transaction'];
+    if (options.isolationLevel) {
+        parts.push('isolation level ' + options.isolationLevel);
+    }
+    if (options.readOnly !== undefined) {
+        parts.push(options.readOnly ? 'read only' : 'read write');
+    }
+    return parts.join(' ');
+}
+function normalizeRows(rows) {
+    return rows.map((row) => {
+        if (typeof row !== 'object' || row === null) {
+            return {};
+        }
+        return { ...row };
+    });
+}
+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 normalizeAffectedRows(kind, rowCount, rows) {
+    if (kind === 'select' || kind === 'count' || kind === 'exists') {
+        return undefined;
+    }
+    if (rowCount !== null) {
+        return rowCount;
+    }
+    if (kind === 'raw') {
+        return undefined;
+    }
+    return rows.length;
+}
+function normalizeInsertId(kind, statement, rows) {
+    if (!isInsertStatementKind(kind) || !isInsertStatement(statement)) {
+        return undefined;
+    }
+    let primaryKey = getTablePrimaryKey(statement.table);
+    if (primaryKey.length !== 1) {
+        return undefined;
+    }
+    let key = primaryKey[0];
+    let row = rows[rows.length - 1];
+    return row ? row[key] : undefined;
+}
+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 compilePostgresStatement(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,EAA2B,MAAM,uBAAuB,CAAA;AAMtF,KAAK,WAAW,GAAG;IACjB,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,OAAO,EAAE,CAAA;CAClB,CAAA;AAMD,wBAAgB,wBAAwB,CAAC,SAAS,EAAE,gBAAgB,GAAG,WAAW,CAqGjF"}