named-placeholders

1.1.6 verified Fri May 01 auth: no javascript

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.

Common errors

error toUnnamed is not a function ↓

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

fix

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

error Cannot read properties of undefined (reading '0') ↓

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

fix

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

error Unexpected token ':' ↓

cause Library misused if placeholders are not escaped properly inside quotes.

fix

Ensure placeholders are outside string literals or use proper escaping.

Warnings

gotcha Factory 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);

gotcha Parameter 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.

breaking In 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.

deprecated The 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()

Install

npm install named-placeholders

yarn add named-placeholders

pnpm add named-placeholders

Imports

default (toUnnamed)
wrong
```
import { toUnnamed } from 'named-placeholders'
```
correct
```
import toUnnamed from 'named-placeholders'
```
Default export is a factory function. CommonJS: const toUnnamed = require('named-placeholders')() — note the extra call parentheses.

factory result

wrong

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

correct

const compile = toUnnamed(); const [sql, params] = compile('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).

Quickstart

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);