murmuration

library2.0.80jsnpmunverified

Murmuration is a low-level database library providing statement generation, transactions, and migrations. It serves as a lightweight alternative to ORMs like Sequelize or TypeORM, focusing on minimal, dynamic query building with a promise-like syntax. The base package (v2.0.80) is abstract and intended to be extended by specific implementations: Murmuration-MariaDB and Murmuration-PostGreSQL. Key differentiators include its use of operations to wrap transactions and its built-in migration support that synchronizes the database schema during deployment. It deliberately avoids abstractions like models or query builders, giving developers direct control over SQL.

database

npm install murmuration

github ↗package ↗

INSTALL

IMPORT

SIG · MURMURATION

murmuration

databasejavascriptv2.0.80

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.

using

✓ const using = require('murmuration');

✗ import using from 'murmuration';

The primary import is a function called 'using'. The package is CommonJS-only; ESM is not supported. In practice, you should install a specific package like 'murmuration-mariadb' and import from there.

Statement

✓ const { Statement } = require('murmuration');

✗ const Statement = require('murmuration').Statement;

The Statement class is exported as a named export. It is intended to be extended when creating the 'using' function with database-specific connection details.

migrate

✓ const { migrate } = require('murmuration');

✗ import { migrate } from 'murmuration';

The migrate function is a named export for running migrations. It is CommonJS only. Typically called from deployment scripts.

Demonstrates building a query dynamically with using(), where(), one(), else(), catch(), and execute().

const { Statement, migrate } = require('murmuration'); const withConnection = (connection) => ({ selectFromUsers: () => ({ where: (conditions) => ({ one: (handler) => ({ else: (elseHandler) => ({ catch: (errHandler) => ({ execute: async () => { const sql = `SELECT * FROM users WHERE ${Object.keys(conditions).map(k => `${k} = ?`).join(' AND ')}`; const values = Object.values(conditions); try { const rows = await connection.execute(sql, values); if (rows.length === 1) handler(rows[0]); else elseHandler(); } catch (err) { errHandler(err); } }}) }) }) }); const using = (connection) => withConnection(connection); async function quickstart() { const connection = { execute: async (sql, params) => [[{ id: 1, name: 'Alice' }], []] }; const context = { emailAddress: 'alice@example.com', password: 'secret' }; using(connection) .selectFromUsers() .where({ emailAddress: context.emailAddress, password: context.password }) .one(({ id }) => { console.log('Found user:', id); }) .else(() => { console.log('User not found'); }) .catch((err) => { console.error('Error:', err); }) .execute(); } quickstart();

Debug

Known issues

breakingVersion 2.x changed the API from callback-based to promise-like chaining. Old .end() method replaced with .execute().

fix

Replace .end() with .execute() on statement chains.

affects: >1.0

breakingVersion 2.0 removed the default export; require('murmuration') no longer returns a constructor. Use named exports like { Statement } or { migrate }.

fix

Change const Murmuration = require('murmuration') to const { Statement } = require('murmuration').

affects: >=2.0

deprecatedThe base Murmuration package is deprecated; use Murmuration-MariaDB or Murmuration-PostGreSQL instead.

fix

Install the appropriate database-specific package: npm install murmuration-mariadb or npm install murmuration-postgresql.

affects: >=2.0.80

gotchaThe using() function must be defined locally; the package does not export it directly. It is typically created by extending the Statement class with database-specific connection methods.

fix

Create a using.js file that imports and extends Statement with your database driver's execute method.

affects: >=2.0

gotchaThe where() method only supports equality conditions (simple object). For operators like IN, LIKE, or OR, you must write raw SQL and use a different approach.

fix

Use a raw query method or extend Statement to support custom conditions.

affects: all

breakingMigration schema changed: migration files must export an object with up and down functions instead of arrays of SQL strings.

fix

Refactor migration files to export { up: async (connection) => { ... }, down: async (connection) => { ... } }.

affects: >=2.0

Errors

Common errors & fixes

Cannot find module 'murmuration'

The package is not installed, or you are trying to use the base package without installing a database-specific implementation.

fix

Run `npm install murmuration-mariadb` or `npm install murmuration-postgresql` and import from that package instead.

TypeError: using is not a function

You are trying to use require('murmuration') directly as a function, but the package exports an object with named exports, not a function.

fix

Define a local `using` function by extending the Statement class. Example: const { Statement } = require('murmuration'); const using = (connection) => new Statement(connection);

TypeError: Cannot read properties of undefined (reading 'selectFromAccount')

The using() function is not properly set up with database-specific methods like selectFromAccount(). The base murmurration does not include these.

fix

Create a using function that extends Statement with your database schema's methods, or use a package like murmuration-mariadb that provides them.

Upgrade

Version history

2.0.80latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/djalbat/murmuration ↗

packagehttps://www.npmjs.com/package/murmuration ↗