Named Parameters for Node-Postgres

2.4.1 verified Sat Apr 25 auth: no javascript abandoned

node-postgres-named is a utility library designed to introduce named parameter support to the `node-postgres` client by monkeypatching its `query` method. As of its latest release, version 2.4.1 (published in 2018), this package allows developers to write more readable SQL queries using `$name` syntax, which it then translates into the positional `$1`, `$2` parameters required by PostgreSQL. This addresses a deliberate design choice in `node-postgres` to maintain a minimal API consistent with PostgreSQL's native capabilities, which do not inherently support named parameters. Given the absence of updates since 2018, this project is considered abandoned. Consequently, its compatibility with contemporary Node.js versions, recent `node-postgres` releases, and modern JavaScript module systems like ESM is highly uncertain and likely problematic.

Common errors

error TypeError: client.query is not a function ↓

cause The `named.patch` function was called on an object that is not a `pg.Client` instance or whose `query` method has been removed or redefined by another library.

fix

Ensure client is a valid, unpatched pg.Client instance before calling named.patch(client).

error Error: bind message supplies N parameters, but prepared statement "name" requires M ↓

cause This error can occur if the named parameters in the `text` property of the query object do not exactly match the keys in the `values` object, or if the patching did not correctly transform the query.

fix

Double-check that every named parameter (e.g., $name) in your SQL query string has a corresponding key in the values object, and vice-versa. Also, verify that named.patch(client) was successfully called.

error SyntaxError: require() of ES Module ... not supported. Instead, change the require of index.js to a dynamic import() or remove the 'type': 'module' in your package.json. ↓

cause Attempting to `require('node-postgres-named')` in an ESM context, or attempting to `import` it when the library itself is CJS-only.

fix

If your project is ESM, consider using a dynamic import (await import('node-postgres-named')) or revert to CJS if possible. However, the best long-term solution is to migrate to a maintained library for named parameters or ORM functionality.

Warnings

breaking This package performs monkeypatching on the `node-postgres` client. Monkeypatching can lead to unexpected behavior, conflicts with other libraries, or compatibility issues with future versions of `node-postgres` or Node.js. ↓

fix Consider migrating to a more modern ORM or query builder that offers named parameter-like functionality natively without monkeypatching, or manually mapping named parameters to positional ones.

gotcha The project is abandoned, with the last update in 2018. It is highly unlikely to be compatible with recent versions of `node-postgres` (e.g., v8 or later) or modern Node.js runtimes (e.g., Node.js 16+), especially regarding async/await syntax or ESM support. ↓

fix Evaluate alternatives for named parameters or query building that are actively maintained and compatible with current ecosystem standards. If forced to use, thorough testing with your specific `node-postgres` and Node.js versions is crucial.

gotcha This library is exclusively CommonJS (`require`). It does not provide native ESM support. Using it in an ESM module will require a CommonJS wrapper or a build step that handles CJS interoperability. ↓

fix If using ESM, you will need to `import named from 'node-postgres-named'` (with appropriate `package.json` configuration or a build tool) or explicitly use `createRequire` from `module` to load it in an ESM context.

deprecated The pattern matching for named parameters (`\$[a-zA-Z]([a-zA-Z0-9_\-]*)\b`) is specific. Using unsupported characters or incorrect syntax for named parameters will cause the query to fail or be interpreted incorrectly. ↓

fix Ensure named parameters strictly adhere to the `$` followed by a letter, then alphanumerics, underscores, or dashes.

Install

npm install node-postgres-named

yarn add node-postgres-named

pnpm add node-postgres-named

Imports

named
```
const named = require('node-postgres-named');
```
This library is CommonJS-only and relies on `require` for module loading. Direct ESM `import` is not supported without a wrapper.
patch
wrong
```
const { patch } = require('node-postgres-named');
```
correct
```
named.patch(client);
```
The `patch` function is exported as a property of the main module object, not a named export from the CommonJS module.

Quickstart

This quickstart demonstrates how to import, patch a `pg` client, and then execute a query using named parameters.

const pg = require('pg');
const named = require('node-postgres-named');

const conString = process.env.DATABASE_URL || 'postgres://user:password@host:5432/database';

async function runQuery() {
  const client = new pg.Client(conString);
  named.patch(client); // Patch the client instance in-place

  try {
    await client.connect();

    const query = {
      text: 'SELECT name FROM person WHERE name = $name AND tenure <= $tenure AND age <= $age',
      values: { 'name': 'Ursus', 'tenure': 2.5, 'age': 24 }
    };

    const res = await client.query(query);
    console.log('Query result:', res.rows);
  } catch (err) {
    console.error('Error executing query', err.stack);
  } finally {
    await client.end();
  }
}

runQuery();