Registry / database / masterrecord

masterrecord

JSON →
library1.0.4jsnpmunverified

MasterRecord is a lightweight, code-first Object-Relational Mapper (ORM) for Node.js, currently at version 1.0.4. It emphasizes a fluent, lambda-based query API, a comprehensive CLI-driven migration system, and out-of-the-box support for multiple relational databases including MySQL (5.7+/8.0+), PostgreSQL (9.6+/12+), and SQLite (3.x). The ORM operates on an Active Record pattern, providing entity serialization, lifecycle hooks, and built-in validation. A key differentiator is its "ESM only" nature, requiring Node.js 20+ and a host project configured as a module, with no CommonJS build available. It offers features like query result caching, bulk operations, and robust SQL injection protection through parameterized queries. The project seems to follow a stable release cadence with its initial major v1.0 release.

npm install masterrecord
INSTALL
IMPORT
SIG · MASTERRECORD
M
masterrecord
databasejavascriptv1.0.4
Install
—
Import
—
Disk
—
Pass rate
0/ 6
Env Coverage0 / 6
glibc
18–22
musl
18–22
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18–226 runs
build_error
glibc
node 18–226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

MasterRecord
✓ import { MasterRecord } from 'masterrecord';
✗ const { MasterRecord } = require('masterrecord');
MasterRecord is a pure ESM package since v1.0, requiring Node.js 20+ and '"type": "module"' in package.json. This import typically accesses the global configuration and factory methods.
defineEntity
✓ import { defineEntity } from 'masterrecord';
✗ const { defineEntity } = require('masterrecord');
Used for programmatically defining new database entities and their schema. Follows ESM import syntax.
Entity
✓ import { Entity } from 'masterrecord';
✗ const { Entity } = require('masterrecord');
The base class for all data models. Custom entities should extend this class to gain ORM capabilities.

This quickstart demonstrates how to configure MasterRecord with an SQLite database, define a `User` entity, sync the schema, and perform basic CRUD operations (create, save, query) on entity instances.

import { MasterRecord } from 'masterrecord'; // 1. Define an entity extending MasterRecord.Entity class User extends MasterRecord.Entity { id!: number; name!: string; email!: string; age?: number; static tableName = 'users'; // Explicitly define the table name static fields = { id: { type: 'number', primaryKey: true, autoIncrement: true }, name: { type: 'string', required: true, length: { min: 3, max: 255 } }, email: { type: 'string', required: true, pattern: /^\S+@\S+\.\S+$/, unique: true }, age: { type: 'number', required: false, min: 18 } }; } async function runMasterRecord() { // 2. Configure MasterRecord for SQLite database await MasterRecord.configure({ connection: { client: 'sqlite', filename: './quickstart.sqlite' }, entities: [User], debug: process.env.NODE_ENV !== 'production' // Enable logging in development }); // 3. Sync schema (for development; use migrations in production) await MasterRecord.syncSchema(); console.log('Database schema synced successfully for User entity.'); // 4. Create a new user instance using the factory method const newUser = MasterRecord.create(User, { name: 'Alice Wonderland', email: 'alice@example.com', age: 28 }); await newUser.save(); console.log('Created new user:', newUser.toObject()); // 5. Find a user by email const foundUser = await MasterRecord.query(User).where(u => u.email === 'alice@example.com').first(); if (foundUser) { console.log('Found user:', foundUser.toObject()); // 6. Update the user foundUser.age = 29; await foundUser.save(); console.log('Updated user age:', foundUser.toObject()); } // 7. Disconnect from the database await MasterRecord.disconnect(); console.log('MasterRecord disconnected.'); } runMasterRecord().catch(console.error);
masterrecord --version
Debug
Known issues
breakingMasterRecord v1.0+ is a pure ECMAScript Module (ESM) package. It does not provide a CommonJS build and requires Node.js v20.0.0 or higher. Your project's `package.json` must include `"type": "module"`.
fix
Ensure Node.js >=20.0.0 is installed and your project's `package.json` has `"type": "module"`. Update import statements to use ESM syntax (e.g., `import { MasterRecord } from 'masterrecord';`).
affects: >=1.0.0
gotchaWhen creating new entity instances, it is critical to use the `MasterRecord.create(Entity, data)` factory method instead of directly instantiating with `new Entity(data)`. Direct instantiation bypasses internal lifecycle hooks, validation, and proper field initialization.
fix
Always use `const newEntity = MasterRecord.create(YourEntityClass, { ...data });` to ensure full ORM functionality and adherence to defined business logic and lifecycle processes.
affects: >=1.0.0
gotchaWhile MasterRecord offers 'Raw SQL Queries' as an advanced feature, developers should exercise extreme caution. Although the ORM's primary query API provides automatic SQL injection protection, direct raw SQL requires manual parameterization and sanitization to prevent security vulnerabilities.
fix
Prioritize using MasterRecord's fluent query builder for all data operations. If raw SQL is absolutely necessary, rigorously validate and sanitize all user-supplied input and utilize parameterized queries diligently.
affects: >=1.0.0
gotchaThe `MasterRecord.syncSchema()` method is convenient for rapid development and testing but should not be used in production environments, as it can lead to data loss or unintended schema changes. Production environments should rely exclusively on the CLI-driven migration system.
fix
For production deployments, utilize the MasterRecord CLI to generate and run migrations (`masterrecord migrate up`, `masterrecord migrate down`) to manage schema changes in a controlled and versioned manner.
affects: >=1.0.0
Errors
Common errors & fixes
ERR_REQUIRE_ESM: require() of ES module .../masterrecord/index.js from ... not supported.
Attempting to import MasterRecord using CommonJS `require()` syntax in a non-ESM project, or in an older Node.js environment.
fix
Ensure your project's `package.json` has `"type": "module"` and use `import { ... } from 'masterrecord';` syntax. Upgrade your Node.js environment to version 20.0.0 or newer.
Error: The current Node.js version (vX.Y.Z) is not supported. MasterRecord requires Node.js v20.0.0 or higher.
Running MasterRecord with an incompatible Node.js version.
fix
Upgrade your Node.js environment to version 20.0.0 or newer. Consider using a version manager like `nvm` or `volta` to manage Node.js versions.
TypeError: MasterRecord.create is not a function OR Cannot read properties of undefined (reading 'create')
Attempting to create an entity instance directly via `new YourEntityClass()` instead of using the factory method, or incorrectly accessing the `create` method.
fix
Always ensure you are correctly importing `MasterRecord` and using the factory method as `const newEntity = MasterRecord.create(YourEntityClass, { data });`.
Error: connect ECONNREFUSED 127.0.0.1:3306 (for MySQL) / Connection refused (for PostgreSQL) / SQLITE_CANTOPEN: unable to open database file
The database server is not running, is inaccessible from the application's host, or the connection credentials (host, port, user, password, database) are incorrect. For SQLite, the path to the database file might be invalid or permissions might be insufficient.
fix
Verify that your database server is running and accessible. Double-check all connection parameters in your `MasterRecord.configure()` settings. Ensure no firewalls are blocking the connection. For SQLite, check the `filename` path and file system permissions.
Upgrade
Version history
1.0.4latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
8 hits · last 30 days
node
8
Resources
masterrecord — npm install masterrecord · libregistry