sql-mapper

library1.2.1jsnpmunverified

sql-mapper is a Node.js SQL mapper library inspired by MyBatis, providing a template-based approach to write SQL queries in XML or JS object format. Version 1.2.1 is the latest stable release. It allows dynamic SQL generation with conditions, loops, and fragments, similar to MyBatis. Different from ORMs like Sequelize, it gives full control over SQL while reducing boilerplate. The package is lightweight, with no production dependencies, and supports both CommonJS and ESM via bundlers.

database

npm install sql-mapper

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · SQL-MAPPER

sql-mapper

databasejavascriptv1.2.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.

default

✓ import sqlMapper from 'sql-mapper'

✗ const sqlMapper = require('sql-mapper')

Package uses default export. CJS require works, but ESM import is preferred for modern projects.

SqlMapper

✓ import { SqlMapper } from 'sql-mapper'

Named export SqlMapper class is available for advanced usage.

createMapper

✓ import { createMapper } from 'sql-mapper'

Factory function to create mapper instances, recommended for most users.

Shows basic setup: create mapper, define a dynamic SQL template, and execute with parameters.

import sqlMapper from 'sql-mapper'; const mapper = sqlMapper.create({ database: 'mysql', // optional, default 'mysql' }); // Define a SQL template with dynamic conditions const getUser = mapper.define({ sql: 'SELECT * FROM users WHERE 1=1' + '<#if username??> AND username = #{username}</#if>' + '<#if active??> AND active = #{active}</#if>' }); // Execute with parameters const result = getUser.execute({ username: 'john', active: true }); console.log(result); // rows from database // Also works with XML configuration files // const mapper = sqlMapper.createFromXml('./mappers/UserMapper.xml');

Debug

Known issues

breakingIn version 1.0.0, the API changed from `sqlMapper.createMapper()` to `sqlMapper.create()`. Old code will break.

fix

Use `sqlMapper.create()` instead of `sqlMapper.createMapper()`.

affects: <1.0.0

gotchaTemplate syntax uses `#{param}` for parameters and `<#if>` for conditionals, similar to MyBatis but with slight differences. Using `?` placeholders will not work.

fix

Always use `#{paramName}` syntax for parameters, and `<#if condition>...</#if>` for conditionals.

affects: >=0.0.0

gotchaThe package does NOT include a database driver. You must install a compatible driver (e.g., mysql2, pg) separately and configure connection.

fix

Install a database driver and pass connection config to `create()` or define in mapper.

affects: >=0.0.0

deprecatedThe `createFromXml()` function is considered less flexible and may not receive updates. Recommend using programmatic templates.

fix

Use `sqlMapper.create()` with SQL string templates instead of XML files.

affects: >=1.0.0

Errors

Common errors & fixes

Cannot find module 'sql-mapper'

Package not installed or wrong import path.

fix

Run `npm install sql-mapper` and ensure import is correct: `import sqlMapper from 'sql-mapper'`.

template syntax error: unexpected token

Incorrect template syntax, e.g., using `{{param}}` instead of `#{param}`.

fix

Use `#{param}` for placeholders and `<#if condition> ... </#if>` for conditionals.

Error: Database not configured

No database connection provided when executing a query.

fix

Pass connection configuration to `create()` or set up a global connection pool.

TypeError: mapper.define is not a function

Using an older version with different API or incorrect import.

fix

Update to latest version (1.2.1) and use `sqlMapper.create().define(...)`.

Upgrade

Version history

1.2.1latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

14 hits · last 30 days

node