sql-stamp

library0.8.0jsnpmunverified

sql-stamp is a tiny SQL templating library (v0.8.0) focused on simplicity and keeping SQL clean and readable. It supports conditional placeholders (`{=key, default}` for parameterized values, `{!key}` for raw values), ternary switches (`{?key, truthy, falsey}`), and file inclusion (`{>path}`). It automatically converts most placeholders to `?` for injection-safe parameterized queries. Unlike HTML template engines, it avoids loops and complex conditionals. Release cadence is low; last commit was 2019. Key differentiator: it outputs both SQL string and args array, integrating well with database drivers.

database

npm install sql-stamp

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · SQL-STAMP

sql-stamp

databasejavascriptv0.8.0

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 export

✓ import sqlStamp from 'sql-stamp';

✗ const sqlStamp = require('sql-stamp').default;

The package has a default export (function). In CJS, use require('sql-stamp') without .default.

sqlStamp() result

✓ const tmpl = await sqlStamp(['./template.sql']); const result = tmpl('./template.sql', { key: 'val' });

✗ const tmpl = new sqlStamp(['./template.sql']);

sqlStamp() returns a Promise that resolves to a function. Do not call with new.

result object

✓ const { sql, args } = tmpl('./query.sql', { id: 1 });

✗ const result = tmpl('./query.sql', { id: 1 }); console.log(result.sql, result.args);

Result has 'sql' (string) and 'args' (array) properties. Common to destructure.

Shows basic usage: loading templates, calling a template with data, and destructuring the result into sql string and args array.

import sqlStamp from 'sql-stamp'; const templates = [ './friends.sql', './example.sql' ]; const tmpl = await sqlStamp(templates); const result = tmpl('./example.sql', { accountId: 1, filterDisabled: false, filterKey: 'role', filterVal: 'dev' }); console.log(result.sql); console.log(result.args);

Debug

Known issues

breakingIn v0.7.0, the API changed from synchronous to Promise-based. sqlStamp() now returns a Promise, not a function.

fix

Use await or .then() on the return value of sqlStamp().

affects: >=0.7.0

deprecatedThe 'prettyErrors' option may be removed. Enable error pretty printing by default was the behavior, but now it's configurable.

fix

Set {prettyErrors: true} explicitly if you want detailed error locations.

affects: >=0.6.0

gotchaRaw values with {!key} are inserted directly into SQL without escaping. Use only with trusted input.

fix

Avoid user-provided data with {!key}. For user input, use {=key} for parameterized queries.

affects: *

gotchaTemplate paths in include directives {>path} are relative to the current working directory, not the file location.

fix

Use absolute paths or ensure the cwd is set correctly.

affects: *

breakingIn v0.7.0, the default export changed from a synchronous function to a Promise-based function. Direct require('sql-stamp')() without handling the promise will fail.

fix

Wrap in async function or use .then().

affects: >=0.7.0

Errors

Common errors & fixes

TypeError: sqlStamp is not a function

Used import sqlStamp from 'sql-stamp' in CommonJS without transpilation, or used require incorrectly.

fix

In CommonJS: const sqlStamp = require('sql-stamp'); (no .default). In ESM: import sqlStamp from 'sql-stamp';

Cannot read properties of undefined (reading 'sql')

Called tmpl() without awaiting the promise from sqlStamp().

fix

const tmpl = await sqlStamp(templates); or use .then().

SQLError: Too many args

Provided more arguments than placeholders in the template.

fix

Check the number of placeholders and the data object keys match exactly.

Error: Template file not found: ./path/to/file.sql

Included file path resolved incorrectly.

fix

Use absolute paths or set the current working directory correctly. Include directive paths are relative to cwd.

Upgrade

Version history

0.8.0latest on npm

Audit

Dependencies

globoptionalUsed for resolving template file paths when passing glob patterns

Agent activity

11 hits · last 30 days

node