sql-fn

library0.0.1jsnpmunverified

sql-fn (v0.0.1) generates JavaScript functions from SQL files, eliminating the need for an ORM. It parses .sql files in a directory and produces functions named after the files, with smart defaults: single-row return for CRUD prefixes (findOne, updateOne, createOne, deleteOne) and automatic transaction wrapping for UPDATE, DELETE, INSERT. Options allow overriding these rules globally or per query, including cursor support for streaming. Released with sparse cadence, it targets Node.js >=12 and is loosely inspired by Clojure's HugSQL. Unlike traditional ORMs, it offers zero abstraction overhead and direct SQL control.

database

npm install sql-fn

package ↗

INSTALL

IMPORT

SIG · SQL-FN

sql-fn

databasejavascriptv0.0.1

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.

generate

✓ import { generate } from 'sql-fn';

✗ const { generate } = require('sql-fn');

The library exports both CommonJS and ESM. However, the 'generate' function is a named export, not a default export. Also, the default export is a factory function that must be called with a config object.

withOptions

✓ import { withOptions } from 'sql-fn';

Helper function to create per-query or global overrides for transaction wrapping and single-row behavior.

withTransaction

✓ import { withTransaction } from 'sql-fn';

Used for advanced transaction control (txSeries, txParallel, txWaterfall). Requires calling the default export factory first to get this symbol.

Generates and uses SQL functions from a directory of .sql files with custom options for transaction and single-row behavior.

Debug

Known issues

breakingIn version 0.0.1, the 'generate' function's second parameter must be created with 'withOptions()' if using per-query overrides; passing a plain object will silently be ignored.

fix

Use withOptions({ ... }) to wrap options, e.g., generate('./sql', withOptions({ tx: false })).

affects: 0.0.1

gotchaThe default export is a factory function that must be invoked with a config object. Importing 'generate' directly without calling the factory returns undefined.

fix

Always do: const { generate } = require('sql-fn')(config); or await import('sql-fn').then(m => m({config})).

affects: all

gotchaCursors override both 'tx' and 'single' settings. If cursor is set on a query, it will not run in a transaction and will return multiple pages of rows via async iteration.

fix

Ensure cursor queries do not expect transaction isolation or single-row return.

affects: all

gotchaThe library assumes SQL filenames follow conventions like 'findOne*.sql' for single-row results. Mismatched naming can cause unexpected multiple row returns or no automatic transaction wrapping.

fix

Override with 'withOptions' to explicitly set 'single' and 'tx' per query.

affects: all

deprecatedThe package version 0.0.1 is a very early release; API may change without major version bump. There is no documented semver policy.

fix

Pin exact version and review changelog before upgrading.

affects: 0.0.1

Errors

Common errors & fixes

TypeError: (0 , _sqlFn.generate) is not a function

Importing 'generate' directly from the module without calling the default export factory.

fix

const { generate } = require('sql-fn')(config); OR await import('sql-fn').then(m => m({config})).then(m => m.generate)

Error: Connection terminated unexpectedly

The pg.Pool config passed to the factory function has incorrect credentials or database host.

fix

Check database connection parameters: host, port, user, password, database.

TypeError: withOptions is not a function

Using withOptions as a named export without calling the factory first.

fix

const { withOptions } = require('sql-fn')(config); or destructure after calling the default export.

Query returned multiple rows but single row expected

The SQL file name does not match the conventional prefix (e.g., 'findOne*') or the 'single' option is not set correctly.

fix

Override using withOptions({ myQuery: {single: true} }).

SyntaxError: Unexpected token '.'

Using the library with a Node.js version below 12 (does not support optional chaining or newer syntax).

fix

Upgrade Node.js to v12 or higher.

Upgrade

Version history

0.0.1latest on npm

Audit

Dependencies

pgrequiredUses pg.Pool for PostgreSQL database connections; required at runtime.

globrequiredUsed to discover SQL files in the specified directory.

Agent activity

16 hits · last 30 days

node