Registry / database / named-placeholders

named-placeholders

library1.1.6jsnpmunverified

Compiles SQL queries with named placeholders (:name) to unnamed positional parameterized queries (?) with a separate array of values. Version 1.1.7 (April 2026) is current; maintained under mysqljs organization on GitHub. Key differentiator: lightweight, zero-dependency solution for converting named placeholders in SQL strings for use with mysql/mysql2 or any ?-based driver. Handles nested quotes and escape sequences properly. Active development with frequent bug fixes.

database serialization

npm install named-placeholders

github ↗package ↗

INSTALL

IMPORT

SIG · NAMED-PLACEHOLDERS

named-placeholders

databasejavascriptv1.1.6

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.

default (toUnnamed)

✓ import toUnnamed from 'named-placeholders'

✗ import { toUnnamed } from 'named-placeholders'

Default export is a factory function. CommonJS: const toUnnamed = require('named-placeholders')() — note the extra call parentheses.

factory result

✓ const compile = toUnnamed(); const [sql, params] = compile('SELECT :id', { id: 1 })

✗ const [sql, params] = toUnnamed('SELECT :id', { id: 1 })

toUnnamed() returns a compiler function. The factory must be called first, then the resulting function is used for each query.

namedToUnnamed

✓ import { namedToUnnamed } from 'named-placeholders'; const q = namedToUnnamed('...', [])

Named export available since v1.1.0. Accepts query string and array of values (order matters).

Shows basic usage: import factory, call it to get compiler, invoke with query and parameters object, then use resulting array with mysql/mysql2.

import toUnnamed from 'named-placeholders'; const compile = toUnnamed(); const [sql, params] = compile( 'SELECT * FROM users WHERE id = :id AND name = :name', { id: 1, name: 'Alice' } ); console.log(sql); // 'SELECT * FROM users WHERE id = ? AND name = ?' console.log(params); // [1, 'Alice'] // Also works with MySQL2: // const mysql = require('mysql2'); // const connection = mysql.createConnection({ /* ... */ }); // connection.execute(sql, params);

Debug

Known issues

gotchaFactory returns a compiler function, not the compiled result. Must call factory first: const compile = toUnnamed()

fix

const compile = toUnnamed(); const [sql, vals] = compile(query, params);

affects: >=1.0.0

gotchaParameter order in returned array follows the order of named placeholders as they appear in the query string, not alphabetical.

fix

Remember the order is sequential occurrence in the query, not object key order.

affects: >=1.0.0

breakingIn v1.1.0, the namedToUnnamed export changed signature from (query, valuesArray) to (query, valuesArray, config?).

fix

Update calls to pass optional config object as third argument if needed.

affects: >=1.1.0

deprecatedThe factory function can also be called as require('named-placeholders')(). This pattern is deprecated but still works.

fix

Use import toUnnamed from 'named-placeholders' then call toUnnamed()

affects: >=1.0.0

Errors

Common errors & fixes

toUnnamed is not a function

Missing parentheses: const compile = toUnnamed; instead of const compile = toUnnamed();

fix

const compile = toUnnamed(); // call factory first

Cannot read properties of undefined (reading '0')

Destructuring result of toUnnamed() directly without calling compile first.

fix

const compile = toUnnamed();
const [sql, params] = compile('SELECT :val', { val: 1 });

Unexpected token ':'

Library misused if placeholders are not escaped properly inside quotes.

fix

Ensure placeholders are outside string literals or use proper escaping.

Upgrade

Version history

1.1.6latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

5 hits · last 30 days

node

Resources

githubhttps://github.com/mysqljs/named-placeholders ↗

packagehttps://www.npmjs.com/package/named-placeholders ↗