simple-builder 3.0.0: sql`` tagged template, real SQL lexer, identifier safety, TS rewrite, dual CJS/ESM

[Acro]

Overview

A ground-up modernization of simple-builder for 2026, staying true to the original purpose: your SQL stays visible. Still one file, still zero dependencies, ~16 kB compiled.

The ? partials API is byte-identical to 2.4.2 for all documented usage — a differential fuzzer proves it against the vendored original on every CI run (20k scenarios). Existing require('simple-builder').pg callers are unaffected.

Three things changed: the SQL is now lexed instead of ?-counted, identifiers are safe by default, and there's a new sql`` tagged template that makes injection structurally impossible.

---

1. Security — identifiers are the only real vector

Values were always parameterised and safe. Identifiers are the problem: no driver can bind an identifier (OWASP — placeholders name data, never tables or columns), and object keys become column names.

• Object keys are now allow-listed to plain identifiers (col, tbl.col); anything else throws. Legitimate keys pass through byte-for-byte, so this changes output for nothing except payloads:

  pg(['UPDATE users SET ?', { 'x=1; DROP TABLE users; --': 1 }])  // now throws

• Chosen over auto-quoting deliberately. Quoting would silently break case semantics — quoted identifiers are case-sensitive while Postgres folds unquoted names to lower case, so auto-quoting { userName: … } would stop matching a username column and break existing consumers.
• New sql.id(...parts) for the dynamic case — quotes per dialect ("pg" / `mysql`), doubles embedded quotes, and adds its own quotes so callers can't create a quote mismatch. Rejects NUL/empty.
• Documented the two footguns the library can't fix for you: LIKE wildcards in bound values (%/_ still match), and second-order injection.

2. Correctness — a real lexer replaces the ? scanner

Naive ?-counting corrupts real SQL. Reproduced on the old code:

pg(["SELECT * FROM t WHERE tags ?| ARRAY['x'] AND id = ?", 5])
// 2.4.2 → "... WHERE tags $1| ARRAY['x'] AND id = ?"   ← operator destroyed, value misbound
// 3.0.0 → "... WHERE tags ?| ARRAY['x'] AND id = $1"   ✓

This is the exact bug class that broke Aura.SqlQuery. The lexer now skips:

• single-quoted string literals ('' escapes, plus MySQL \ escapes)
• quoted identifiers ("…" and `…`)
• line comments and block comments (nested)
• dollar-quoted bodies ($$…$$, $tag$…$tag$) — the pgx injection class

…recognises ?| / ?& / ?? as operators, and honours \? as an escaped literal ? for the genuinely-ambiguous bare jsonb ?. Clause markers are now classified positionally with \b, which also fixes OFFSET ? being misread as SET ?. Too few values now throws instead of silently binding undefined.

3. DX — the new sql tagged template (recommended)

const { pg, sql } = require('simple-builder')

pg(sql`SELECT * FROM users WHERE id = ${id}`)
// { text: 'SELECT * FROM users WHERE id = $1', values: [id] }

Every ${interpolation} is always a bound parameter — you cannot forget to parameterise, so accidental injection is structurally impossible. Nothing is scanned for ?, so jsonb operators need no escaping. Fragments nest and compose:

const active = onlyActive ? sql`AND active = ${true}` : sql.empty
pg(sql`SELECT * FROM users WHERE org = ${org} ${active}`)

pg(sql`SELECT * FROM ${sql.id('public','users')} WHERE id IN ${[1,2,3]}`)
// { text: 'SELECT * FROM "public"."users" WHERE id IN ($1,$2,$3)', values: [1,2,3] }

Helpers: sql.id / sql.value / sql.join / sql.raw (unsafe by construction, documented) / sql.empty.

Both APIs lower to one node representation and render through one Renderer, so pg()/mysql() accept either. Rendering is pure — a fragment renders repeatedly, for either dialect.

Packaging & tooling

• TypeScript source → compiled CJS (dist/) + static ESM wrapper (esm/) via an exports map; no dual-package hazard. Complete types (the old index.d.ts only typed scalar arrays).
• publint --strict clean; attw green across node10 / node16-CJS / node16-ESM / bundler — both now gate CI and publish.
• CI: Node 16–24 matrix, both fuzzers, CJS+ESM package-boundary smoke against the packed tarball, typings gate. Provenance publish workflow.
• Added LICENSE, AGENTS.md/CLAUDE.md, llms.txt, .gitignore, issue templates.

Tests

50 unit tests (from 22), exact type-level tests, CJS+ESM boundary tests against the installed tarball, and two fuzzers:

• Differential — random well-formed queries through the new build and the vendored 2.4.2 builder; output must match byte-for-byte.
• Property — the tag/lexer have no 2.4.2 counterpart, so they're checked against invariants using injection-shaped inputs: values bind in order and never reach the text, pg renders exactly $1..$n, mysql renders n ?, rendering is pure.

Behaviour changes vs 2.4.2 (all unit-tested)

Each is a fix; all are kept out of the differential fuzzer's domain:

1. Lowercase in ? now expands (was left as a literal placeholder, mis-binding values).
2. The caller's partials array is no longer mutated.
3. Empty object to VALUES ?/SET ?/WHERE ? throws instead of emitting () VALUES ().
4. Non-identifier object keys throw.
5. Fewer values than placeholders throws instead of binding undefined.
6. OFFSET ? is no longer misread as SET ?.
7. ? inside literals/identifiers/comments/dollar-quotes is no longer a placeholder; ?|/?& survive.

Verification

npm test → 50/50 + type gate. npm run fuzz -- 20000 → 20k differential scenarios agree with 2.4.2, 20k property scenarios hold all invariants. Packed tarball passes CJS+ESM boundary tests and the latest-TypeScript typings gate under node16 resolution. publint --strict and attw clean.

Bumped to 3.0.0 — API-compatible for documented usage; major for the packaging/module-format change and the behaviour fixes above.

🤖 Generated with Claude Code