{"id":25972,"library":"named-placeholders","title":"named-placeholders","description":"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.","status":"active","version":"1.1.6","language":"javascript","source_language":"en","source_url":"https://github.com/mysqljs/named-placeholders","tags":["javascript","sql","pdo","named","placeholders","mysql","postgres"],"install":[{"cmd":"npm install named-placeholders","lang":"bash","label":"npm"},{"cmd":"yarn add named-placeholders","lang":"bash","label":"yarn"},{"cmd":"pnpm add named-placeholders","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Default export is a factory function. CommonJS: const toUnnamed = require('named-placeholders')() — note the extra call parentheses.","wrong":"import { toUnnamed } from 'named-placeholders'","symbol":"default (toUnnamed)","correct":"import toUnnamed from 'named-placeholders'"},{"note":"toUnnamed() returns a compiler function. The factory must be called first, then the resulting function is used for each query.","wrong":"const [sql, params] = toUnnamed('SELECT :id', { id: 1 })","symbol":"factory result","correct":"const compile = toUnnamed(); const [sql, params] = compile('SELECT :id', { id: 1 })"},{"note":"Named export available since v1.1.0. Accepts query string and array of values (order matters).","wrong":null,"symbol":"namedToUnnamed","correct":"import { namedToUnnamed } from 'named-placeholders'; const q = namedToUnnamed('...', [])"}],"quickstart":{"code":"import toUnnamed from 'named-placeholders';\n\nconst compile = toUnnamed();\nconst [sql, params] = compile(\n  'SELECT * FROM users WHERE id = :id AND name = :name',\n  { id: 1, name: 'Alice' }\n);\nconsole.log(sql);   // 'SELECT * FROM users WHERE id = ? AND name = ?'\nconsole.log(params); // [1, 'Alice']\n\n// Also works with MySQL2:\n// const mysql = require('mysql2');\n// const connection = mysql.createConnection({ /* ... */ });\n// connection.execute(sql, params);","lang":"typescript","description":"Shows basic usage: import factory, call it to get compiler, invoke with query and parameters object, then use resulting array with mysql/mysql2."},"warnings":[{"fix":"const compile = toUnnamed(); const [sql, vals] = compile(query, params);","message":"Factory returns a compiler function, not the compiled result. Must call factory first: const compile = toUnnamed()","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Remember the order is sequential occurrence in the query, not object key order.","message":"Parameter order in returned array follows the order of named placeholders as they appear in the query string, not alphabetical.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Update calls to pass optional config object as third argument if needed.","message":"In v1.1.0, the namedToUnnamed export changed signature from (query, valuesArray) to (query, valuesArray, config?).","severity":"breaking","affected_versions":">=1.1.0"},{"fix":"Use import toUnnamed from 'named-placeholders' then call toUnnamed()","message":"The factory function can also be called as require('named-placeholders')(). This pattern is deprecated but still works.","severity":"deprecated","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-05-01T00:00:00.000Z","next_check":"2026-07-30T00:00:00.000Z","problems":[{"fix":"const compile = toUnnamed(); // call factory first","cause":"Missing parentheses: const compile = toUnnamed; instead of const compile = toUnnamed();","error":"toUnnamed is not a function"},{"fix":"const compile = toUnnamed();\nconst [sql, params] = compile('SELECT :val', { val: 1 });","cause":"Destructuring result of toUnnamed() directly without calling compile first.","error":"Cannot read properties of undefined (reading '0')"},{"fix":"Ensure placeholders are outside string literals or use proper escaping.","cause":"Library misused if placeholders are not escaped properly inside quotes.","error":"Unexpected token ':'"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}