npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

sql-strings

v1.0.0

Published

Write SQL-injection protected SQL statements using template strings!

Downloads

156

Readme

sql-strings

LOC FileCount Tests Coverage

Write SQL-injection protected SQL statements using template strings. Useful for longer queries and dynamically created queries where keeping the SQL and bind parameters separate becomes disorienting.

import { SQL } from 'sql-strings';

const username = 'bob'; // potentially unsafe input

// postgres:
await client.query(SQL`SELECT * FROM users WHERE username = ${username}`);
// is equivalent to:
await client.query('SELECT * FROM users WHERE username = ?', [username]);

// mysql:
connection.query(SQL`SELECT * FROM users WHERE username = ${username}`());
// is equivalent to:
connection.query('SELECT * FROM users WHERE username = ?', [username]);

// sqlite3:
db.all(...SQL`SELECT * FROM users WHERE username = ${username}`);
// is equivalent to:
db.all('SELECT * FROM users WHERE username = ?', [username]);

// sequelize:
sequelize.query(SQL`SELECT * FROM users WHERE username = ${username}`());
// is equivalent to:
sequelize.query({ query: 'SELECT * FROM users WHERE username = ?', values: [username] });

Compatible with node-sqlite3, Sequelize, mysql, postgres, and more!

Note: This is my first npm package and made for learning purposes. Feedback is welcome! I'll keep it updated with bug/security fixes but will not be adding new features. Consider an alternative for more features.

Installation

This is a Node.js module available through the npm registry. Node.js v18.17.0 or higher is recommended.

Installation is done using the npm install command:

$ npm install sql-strings

Recommended Extensions for Syntax Highlighting

These editor extensions will syntax highlight the SQL template strings for better readability:

Usage

Prefix your template strings with SQL and use ${} for bind parameters.

const username = 'bob';
const sql = SQL`SELECT * FROM users WHERE username = ${username}`;

This SQLString object can be called as a function using () to get an object compatible with most database drivers.

connection.query(sql());

To insert raw values into the SQL string without escaping them as bind parameters, pass them to the SQLString using parentheses:

const tablename = 'users';
connection.query(SQL`SELECT * FROM "`(tablename)`" WHERE username = ${username};`());

To append to an existing SQLString object, use the append method:

const sql = SQL`SELECT * FROM "`;
sql.append(tablename);
sql.append`" WHERE username = ${username}`;
sql.append` ID in (`;
for (const id of [1, 2, 3]) {
    sql.append`${id}, `;
}
sql.append`4)`;
connection.query(sql());

You can optionally leave out the .append:

const sql = SQL`SELECT * FROM "`;
sql(tablename);
sql`" WHERE username = ${username}`;
sql` ID in (`;
for (const id of [1, 2, 3]) {
    sql`${id}, `;
}
sql`4)`;
connection.query(sql());

SQL Driver Specific Syntax

  • node-sqlite3 like APIs use the spread operator ...SQL`query`​ instead of the final parenthesis SQL`query`() syntax.
import sqlite3 from 'sqlite3';
import { SQL } from 'sql-strings';

const db = new sqlite3.Database(':memory:');
const username = 'bob';
const tablename = '"users"';

const sql = SQL`SELECT * FROM `;
sql.append(tablename);
sql.append` WHERE username = ${tablename}`;

db.all(...sql);
// is equivalent to:
db.all('SELECT * FROM "users" WHERE username = ?', [username]);
  • node-postgres can optionally omit the final parenthesis and use SQL`query`​ syntax.

  • sequelize by default replaces the parameters on the client. To use bind parameters on the database side, pass SQL.SEQUELIZE_USE_BIND to the final parenthesis with SQL`query`(SQL.SEQUELIZE_USE_BIND) syntax.

import { SQL } from 'sql-strings';
import { Sequelize } from 'sequelize';

const sequelize = new Sequelize('sqlite::memory:');
const username = 'bob';
const tablename = '"users"';

const sql = SQL`SELECT * FROM "`(tablename)`" WHERE username = ${username}`;
sequelize.query(sql(SQL.SEQUELIZE_USE_BIND));
// is equivalent to:
sequelize.query({ query: 'SELECT * FROM "users" WHERE username = $1', bind: [username] });

Examples

The following application uses the sql-strings package: Attendance Scanner. You can also take a look at the test suite for more examples.

Alternatives

  • sql-template-strings does the same thing but doesn't support node-sqlite3 and has a different syntax.

Contributing

All constructive contributions are welcome including anything from bug fixes and new features to improved documentation, tests and more! Feel free to open an issue to discuss the proposed change and then submit a pull request :)

Security Issues

If you discover a security vulnerability in sql-strings, please contact the current main maintainer.

Running Tests

Tests run automatically pre-commit using Husky. To run the test suite manually, first install the dependencies, then run npm test:

$ npm install
$ npm test

You will need to set up a mysql and postgres database on localhost with username test, password test, and database test to run their respective tests.

Linting and Formatting

Eslint is used for static analysis, fixpack is used to standardize package.json and Prettier is used for automatic formatting. Linting will automatically run pre-commit using Husky and Lint-Staged. Formatting can be set up to happen automatically in your editor (e.g. on save). Formatting and linting can also be run manually:

$ npm install
$ npm run format
$ npm run lint

Generating TypeScript Types

Typescript types are automatically generated from the JSDoc in the /types folder when the npm package is packaged/published. To update the TypeScript types manually, run the following command:

$ npm run types

This will allow TypeScript users to benefit from the type information provided in the JSDoc.

If you also want to generate the readme badges, run the following command:

$ npm run build

Contributors

The author of sql-strings is Alexander Metzger.

Functionality is inspired by sql-template-strings.

All contributors will be listed here.

License

MIT