Registry / database / node-pg-format

node-pg-format

JSON →
library1.3.5jsnpmunverified

Node.js implementation of PostgreSQL's format() function for safely constructing dynamic SQL queries. Version 1.3.5 is stable and actively maintained, with TypeScript type definitions included. It escapes SQL identifiers (%I) and literals (%L) to prevent SQL injection, supports argument position reordering (n$ syntax), Node Buffers, arrays, and objects. Unlike template literal concatenation (which is unsafe), this library mirrors PostgreSQL's own format() behavior exactly, making it ideal for tools that generate SQL dynamically. The release cadence is low (occasional patches), but the library is mature and reliable.

npm install node-pg-format
INSTALL
IMPORT
SIG · NODE-PG-FORMAT
N
node-pg-format
databasejavascriptv1.3.5
harness data pending
Install & Compatibility
Where this runs

No compatibility data collected yet for this library.

Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

format
import { format } from 'node-pg-format'
import format from 'node-pg-format'
This is a named export, not a default export. In CommonJS, use const { format } = require('node-pg-format').
quoteIdent
import { quoteIdent } from 'node-pg-format'
import { quoteIdent } from 'node-pg-format/quoteIdent'
All functions are exported from the main module; there are no subpath exports.
quoteLiteral
import { quoteLiteral } from 'node-pg-format'
const quoteLiteral = require('node-pg-format').quoteLiteral
Works with both ESM and CJS. The CJS pattern shown is also correct; the wrong example is less common but included for completeness.
formatWithArray
import { formatWithArray } from 'node-pg-format'
import { formatWithArray } from 'node-pg-format/dist/formatWithArray'
No subpath exports exist; all exports are directly from the package root.
config
import { config } from 'node-pg-format'
import { formatConfig } from 'node-pg-format'
The function is named 'config', not 'formatConfig'. It is used via format.config() in older documentation; the import name is 'config'.

Shows importing and using format(), formatWithArray(), quoteIdent(), quoteLiteral(), argument positions, and array/object handling.

import { format, formatWithArray, quoteIdent, quoteLiteral } from 'node-pg-format'; // Basic usage const sql = format('SELECT * FROM %I WHERE id = %L', 'users', 42); console.log(sql); // Output: SELECT * FROM users WHERE id = 42 // With array for dynamic parameters const params = ['users', 42]; const sql2 = formatWithArray('SELECT * FROM %I WHERE id = %L', params); // Quoting identifiers and literals separately const ident = quoteIdent('myTable'); // "myTable" const lit = quoteLiteral("O'Brien"); // 'O''Brien' // Using argument positions const sql3 = format('SELECT %1$L, %1$L, %L', 34, 'test'); console.log(sql3); // Output: SELECT 34, 34, 'test' // Arrays and objects const arr = [1, 2, 3]; const obj = { a: 1 }; const sql4 = format('SELECT * FROM t WHERE c1 IN (%L) AND c2 = %L', arr, obj); console.log(sql4); // Output: SELECT * FROM t WHERE c1 IN (1,2,3) AND c2 = '{"a":1}'
Debug
Known issues
gotchaThe format() function does NOT accept semicolons to end queries or support multiple statements. Doing so can introduce SQL injection via statement separation.
fix
Ensure format() is only used to build single SQL statements. Do not embed user input that could contain semicolons as %s; use %I or %L for identifiers/literals.
affects: *
gotchaIdentifiers quoted with %I are wrapped in double quotes. PostgreSQL will respect case sensitivity inside double quotes, so 'myTable' becomes "myTable" and will not be folded to lowercase.
fix
Be aware that quoted identifiers are case-sensitive. Use consistent casing (e.g., lowercase) for unquoted identifiers to avoid unexpected behavior.
affects: *
gotchaInputs that are undefined or null do NOT throw for %L (returns 'NULL') or %s (returns empty string), but DO throw for %I. This can lead to missing values in generated SQL if not handled.
fix
Always validate inputs before passing to format() if you expect non-null values, especially for identifiers. Consider wrapping in a null-check.
affects: *
gotchaObjects passed to %L are converted via JSON.stringify(), which may produce unexpected SQL if the object contains functions or symbols. Only plain objects with JSON-safe values work as expected.
fix
Only pass plain objects (not class instances, Maps, Sets, etc.) to %L. Use JSON.stringify() beforehand if you need custom serialization.
affects: *
deprecatedThe global configuration via format.config() mutates module-level state, which can affect concurrent requests in server environments. This is an antipattern and may be removed in a future major version.
fix
Avoid using format.config() in production. If you need custom patterns, consider forking the library or wrapping the format call with local configuration.
affects: *
Errors
Common errors & fixes
Cannot find module 'node-pg-format'
Package is not installed or node_modules is missing.
fix
Run `npm install node-pg-format` in your project root.
TypeError: format is not a function
Default import instead of named import (e.g., `import format from 'node-pg-format'`).
fix
Use named import: `import { format } from 'node-pg-format'`.
Error: Expected escaped SQL identifier string, got null
Passed null or undefined to %I placeholder.
fix
Ensure you only pass non-null strings to %I. Use a conditional or default value: `const ident = name ?? 'default'`.
Upgrade
Version history
1.3.5latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
8 hits · last 30 days
node
6
Resources
node-pg-format — npm install node-pg-format · libregistry