sqigil

library0.4.0jsnpmunverified

SQigiL is an ESM-only Postgres SQL template string library (v0.4.0) that leverages ES2015 tagged template literals for safe, fast SQL construction without runtime parsing overhead. It provides auto-escaping for values, booleans, dates, identifiers, lists, and raw SQL, with full TypeScript types and 100% test coverage. Unlike pg-promise, it avoids string parsing overhead. Current status: maintenance – still in early stages (beta), with infrequent releases.

database

npm install sqigil

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · SQIGIL

sqigil

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

sql

✓ import { sql } from 'sqigil';

✗ const sql = require('sqigil');

Package is ESM-only and ships TypeScript types; default export is a tagged template function.

sql.value

✓ import { sql } from 'sqigil'; sql`...${sql.value('text')}...`;

✗ import { sql } from 'sqigil'; sql`...${value('text')}...`;

sql is the default export; value is a sub-method. Cannot import directly as value.

sql.csv

✓ import { sql } from 'sqigil'; sql`...${sql.csv([1,2,3])}...`;

✗ import { sql, csv } from 'sqigil';

csv is only accessible as a method on the sql tagged template function.

sql.id

✓ import { sql } from 'sqigil'; sql`...${sql.id('table_name')}...`;

✗ import { sqlId } from 'sqigil';

id is a sub-method of sql, not a standalone export.

Demonstrates basic sql tagged template usage with automatic escaping, csv list, bool conversion, identifier quoting, and dynamic column insertion.

import { sql } from 'sqigil'; const name = "O'Connor"; const ids = [1, 2, 3]; const active = true; const query = sql` SELECT * FROM users WHERE name = ${name} AND id IN (${sql.csv(ids)}) AND active = ${sql.bool(active)} `; console.log(query); // SELECT * FROM users WHERE name = 'O''Connor' AND id IN (1, 2, 3) AND active = TRUE // Also supports identifiers, raw SQL, dates, etc. const table = 'users'; const columns = ['name', 'email']; const insertQuery = sql` INSERT INTO ${sql.id(table)} (${sql.csids(columns)}) VALUES (${sql.values({ name: 'John', email: 'john@example.com' })}) `; console.log(insertQuery); // INSERT INTO "users" ("name", "email") VALUES ('John', 'john@example.com')

Debug

Known issues

gotchaUsing Symbols or Functions as values will throw an error at runtime.

fix

Ensure only strings, numbers, booleans, null, undefined, arrays, Dates, Buffers, or objects are passed as template expressions.

affects: >=0.4.0

gotchaArrays are converted to Postgres array literal format; nested arrays work but may produce unexpected SQL.

fix

Use sql.csv() for simple lists instead of relying on default array conversion, or wrap with sql.value() explicitly.

affects: >=0.4.0

gotchaDate objects are converted to ISO 8601 in UTC; using sql.tz() outputs local timezone; mixing can cause inconsistencies.

fix

Consistently use either default Date conversion (UTC) or sql.utc()/sql.tz() for explicit timezone handling.

affects: >=0.4.0

breakingThe library is ESM-only; CommonJS require() will fail with Module not found.

fix

Use import { sql } from 'sqigil'; or configure bundler/tester to handle ESM.

affects: >=0.4.0

Errors

Common errors & fixes

Error: Symbols are not supported as SQL values

Passing a Symbol as a template expression.

fix

Do not use Symbol values inside sql tagged templates.

TypeError: require() of ES Module sqigil not supported

Using CommonJS require() to import the ESM-only package.

fix

Switch to import syntax or use dynamic import(): const { sql } = await import('sqigil');

TypeError: sql(...) is not a function

Incorrectly imported sql as a default export but tried to use as named (e.g., import sql from 'sqigil') or vice versa.

fix

Use import { sql } from 'sqigil'; (named export).

Upgrade

Version history

0.4.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

19 hits · last 30 days

node