MasterRecord ORM

Common errors

• ERR_REQUIRE_ESM: require() of ES module .../masterrecord/index.js from ... not supported.

  cause 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.

  cause 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')

  cause 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

  cause 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.

Warnings

• breaking MasterRecord 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';`).
• gotcha When 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.
• gotcha While 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.
• gotcha The `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.

Install

• npm install masterrecord npm
• yarn add masterrecord yarn
• pnpm add masterrecord pnpm

Imports

• MasterRecord
  wrong:

  const { MasterRecord } = require('masterrecord');

  correct:

  import { MasterRecord } from '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
  wrong:

  const { defineEntity } = require('masterrecord');

  correct:

  import { defineEntity } from 'masterrecord';

  Used for programmatically defining new database entities and their schema. Follows ESM import syntax.
• Entity
  wrong:

  const { Entity } = require('masterrecord');

  correct:

  import { Entity } from 'masterrecord';

  The base class for all data models. Custom entities should extend this class to gain ORM capabilities.

Quickstart

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);