tagged-sql

library0.9.0jsnpmunverified

tagged-sql is a lightweight JavaScript/TypeScript library (v0.9.0, stable) that leverages ES6 tagged template literals for writing SQL statements. It supports table name prefixes, separate field and table references via TaggedSql.Table and TaggedSql.Field, and flexible placeholder building for PostgreSQL and MySQL. Unlike other template SQL libraries, it provides a build() method that lets you control placeholder syntax (e.g., $1 for Postgres, ? for MySQL) and a transform() method for prefixing table names. The package ships with TypeScript definitions and has minimal dependencies.

database

npm install tagged-sql

package ↗homepage ↗

INSTALL

IMPORT

SIG · TAGGED-SQL

tagged-sql

databasejavascriptv0.9.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

✓ import TaggedSql from 'tagged-sql'

✗ import { TaggedSql } from 'tagged-sql'

The default export is a function that transforms tagged literals into a Sql object. Named import of TaggedSql is incorrect; the package has no named exports.

TaggedSql.Table

✓ const table = TaggedSql.Table('books')

✗ const table = TaggedSql.table('books')

TaggedSql.Table is a static method, not a property. Ensure proper capitalization: 'Table', not 'table'.

Sql.build

✓ sql.build((_, i) => `$${i+1}`)

✗ sql.build('$1')

build() expects a function that receives (value, index) and returns a placeholder string. Passing a string directly causes a runtime error.

Demonstrates basic usage: creating a TaggedSql query with template literals, building query strings with placeholder generators (PostgreSQL $1, MySQL ?), and using Table/Field for prefix-safe identifiers.

import TaggedSql from 'tagged-sql'; const book = 'Book Title'; const author = 'NyLoong'; // Build a query with placeholders const sql = TaggedSql`SELECT author FROM books WHERE name = ${book} AND author = ${author}`; // For PostgreSQL: use $1, $2 placeholders const queryString = sql.build((_, i) => `$${ i + 1 }`); console.log(queryString); // SELECT author FROM books WHERE name = $1 AND author = $2 console.log(sql.values); // ['Book Title', 'NyLoong'] // For MySQL: use ? placeholders const queryStringMySQL = sql.build('?'); console.log(queryStringMySQL); // SELECT author FROM books WHERE name = ? AND author = ? // Using Table and Field const bookTable = TaggedSql.Table('books'); const nameField = TaggedSql.Field('name', bookTable); const sql2 = TaggedSql`SELECT ${nameField} FROM ${bookTable}`; console.log(sql2.build('?')); // SELECT "books"."name" FROM "books"

Debug

Known issues

gotchaThe build method expects a function, not a string placeholder string.

fix

Use sql.build((value, index) => `$${index+1}`) for Postgres or sql.build('?') for MySQL.

affects: >=0.0.0

gotchaTable and Field references are case-sensitive: TaggedSql.Table() not TaggedSql.table().

fix

Use TaggedSql.Table('table') and TaggedSql.Field('field', table).

affects: >=0.0.0

gotchaThe values array is not automatically escaped; it is up to the user to pass values to the database driver.

fix

Always use parameterized queries: sql.build(...) for the text and pass sql.values to the database driver.

affects: >=0.0.0

gotchaThe transform function requires a callback with three arguments (value, type, group). Using incorrect arguments causes a runtime error.

fix

Use .transform((v, t, g) => t !== 'table' || g ? v : 'prefix_' + v).

affects: >=0.0.0

Errors

Common errors & fixes

TypeError: sql.build is not a function

The import is incorrect (e.g., importing a named export instead of default).

fix

Use import TaggedSql from 'tagged-sql' (without braces).

TaggedSql.Table is not a function

Using lowercase 'table' or forgetting to import TaggedSql as default.

fix

Ensure you have imported TaggedSql correctly and call TaggedSql.Table (capital T).

Uncaught TypeError: sql.build is not a function

Attempting to use build() on a string instead of the Sql object returned by TaggedSql.

fix

Check that the variable contains a Sql object: const sql = TaggedSql`SELECT * FROM table`; then sql.build(...).

Upgrade

Version history

0.9.0latest on npm

Audit

Dependencies

typescriptoptionalType definitions bundled, but not a runtime dependency

Agent activity

14 hits · last 30 days

node