extra-sql-builder

library0.3.4jsnpmunverified

A lightweight, composable SQL builder for TypeScript and JavaScript that constructs SQL statements programmatically without string concatenation or ORM overhead. Current stable version 0.3.4 (semver pre-1.0). It provides a flexible `sql` tagged template literal and function, along with a `ParameterCollector` for named or indexed parameters to prevent SQL injection. Key differentiators: no dependency on ORM, intuitive function-based query construction (e.g., `INSERT_INTO`, `SELECT`, `WHERE`), support for conditional fragments via falsy values, and a small API surface focused solely on SQL generation. TypeScript types included.

database

npm install extra-sql-builder

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · EXTRA-SQL-BUILDER

extra-sql-builder

databasejavascriptv0.3.4

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.

sql

✓ import { sql } from 'extra-sql-builder'

✗ const sql = require('extra-sql-builder')

Package is ESM-only. Use named import, not default.

INSERT_INTO, VALUES, SELECT, etc.

✓ import { INSERT_INTO, VALUES, SELECT } from 'extra-sql-builder'

✗ import InsertInto from 'extra-sql-builder'

All fragment functions (e.g., INSERT_INTO, VALUES, SELECT) are named exports, not default exports.

ParameterCollector

✓ import { ParameterCollector } from 'extra-sql-builder'

✗ const pc = new (require('extra-sql-builder').ParameterCollector)('$')

Use named import with ES module syntax.

Shows building a parameterized INSERT with conditional rows using ParameterCollector.

import { sql, INSERT_INTO, VALUES, integer, text, ParameterCollector } from 'extra-sql-builder' const cond = true const collector = new ParameterCollector('$param') const result = sql( INSERT_INTO('users', ['id', 'name']), VALUES( [collector.add(1), collector.add('Alice')], cond && [collector.add(2), collector.add('Bob')] ) ) // result: INSERT INTO users (id, name) VALUES ($param1, $param2), ($param3, $param4) const params = collector.toRecord() // { param1: 1, param2: 'Alice', param3: 2, param4: 'Bob' } console.log(result, params)

Debug

Known issues

gotchaThe `sql` function accepts both tagged template literals and function arguments, but mixing them can cause unexpected results.

fix

Use only one calling convention per statement: either `sql\`...\`` or `sql(...)`.

affects: >=0.0.0

gotchaFalsy values (false, null, undefined, 0, '') are omitted from fragments, which may inadvertently drop zero or empty strings used as legitimate values.

fix

Explicitly cast to string or use a wrapper for values that could be falsy but intended to be included.

affects: >=0.0.0

gotchaThe `ParameterCollector` stores values by reference; mutating values after adding them does not affect collected parameters.

fix

Call `add()` with the final value and avoid mutation afterwards.

affects: >=0.0.0

breakingPre-1.0 semver: minor version bumps may introduce breaking changes. No stable API yet.

fix

Pin exact version or use ^0.3.4 and review changelog on updates.

affects: <1.0.0

deprecatedThe package does not support CommonJS; using `require()` will fail.

fix

Ensure your project uses ESM (e.g., `"type": "module"` in package.json) and import via `import`.

affects: >=0.0.0

Errors

Common errors & fixes

Error [ERR_REQUIRE_ESM]: require() of ES Module

Package is ESM-only, CommonJS require() not supported.

fix

Switch to ESM imports: use `import { sql } from 'extra-sql-builder'` instead of `require()`.

TypeError: sql is not a function

Importing incorrectly (e.g., default import instead of named).

fix

Use `import { sql } from 'extra-sql-builder'`.

ReferenceError: INSERT_INTO is not defined

Fragment functions are named exports; not importing them.

fix

Add to import: `import { INSERT_INTO, VALUES } from 'extra-sql-builder'`.

Upgrade

Version history

0.3.4latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

8 hits · last 30 days

node

Resources

githubssh://git@github.com/BlackGlory/extra-sql-builder ↗

packageextra-sql-builder ↗

homepagehttps://github.com/BlackGlory/extra-sql-builder#readme ↗