modular-orm

library0.3.51jsnpmunverified

ModularORM (v0.3.51) is a lightweight, fully object-oriented ORM for TypeScript and MySQL. It uses a class-based, decorator-driven API to define tables, columns, and relationships, and supports DTO mapping with validation/transforms. Key differentiators: repository pattern out of the box, in-memory caching, typed information schema access, and auto or file-based migrations. Released as weekly updates, it targets developers who want a type-safe, minimal-overhead alternative to heavier ORMs like TypeORM or Sequelize. Note: only MySQL is currently supported, and the package is pre-1.0 (breaking changes possible).

database

npm install modular-orm

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · MODULAR-ORM

modular-orm

databasejavascriptv0.3.51

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.

ModularORM

✓ import { ModularORM } from 'modular-orm'

✗ const ModularORM = require('modular-orm');

Package ships TypeScript types and is ESM only via 'import'; CommonJS require will break if module not configured.

Table

✓ import { Table } from 'modular-orm'

✗ import { Table } from './Table'

All decorators and classes are top-level exports from 'modular-orm'; no deep imports.

Repository

✓ import { Repository } from 'modular-orm'

✗ import Repository from 'modular-orm';

Repository is a named export, not default. Also, Repository is generic: new Repository<User, UserDTO>(Users, UserDTO).

ColumnType

✓ import { ColumnType } from 'modular-orm'

✗ import { ColumnTypes } from 'modular-orm';

Enum is named ColumnType (singular), not ColumnTypes.

Connects to MySQL, defines a Users table with decorators, creates a DTO for mapping, queries all rows with repository pattern, and outputs results.

import { ModularORM, Table, NamedTable, Column, ColumnType, Repository, AutoIncrementId, Module, Result } from 'modular-orm'; import { Validate, IsSafeString, ToNumber } from 'modular-orm'; // Connect const orm = ModularORM.getInstance(); await orm.start({ host: 'localhost', user: 'root', password: 'password', database: 'test', port: 3306, connectionType: 'pool', checkTablesExists: true, }); // Define table @Table({ comment: 'Users table' }) @NamedTable('users') class Users extends Module { @AutoIncrementId() public id!: number; @Column({ type: ColumnType.VARCHAR(64), notNull: true }) public first_name!: string; @Column({ type: ColumnType.VARCHAR(64), notNull: true }) public last_name!: string; } // Define DTO class UserDTO implements Validate { @Result() public id!: number; @Result('first_name') @IsSafeString() public firstName!: string; @Result('last_name') @IsSafeString() public lastName!: string; // Validate interface public validateErrors: Set<string> = new Set(); } // Create repository and query const repo = new Repository(Users, UserDTO); const users = await repo.find({}); console.log(users); // Close connection await orm.stop();

Debug

Known issues

breakingBreaking changes may occur before v1.0; update lockfiles and test migrations.

fix

Pin exact version in package.json (e.g., "modular-orm": "0.3.51") and run integration tests on upgrade.

affects: <1.0

deprecatedAs of v0.3.0, the `start()` method now requires `connectionType` to be explicitly set; previously defaulted to 'pool'

fix

Add 'connectionType: 'pool'' to start() options, or upgrade to v0.3.0+

affects: <0.3.0

gotchaModule (base class) must be extended by table classes; if not, migrations and cache may fail.

fix

Ensure all table classes extend Module (imported from 'modular-orm').

affects: >=0.0.0

gotchaValidation errors are silent by default; set 'validationErrors: true' in start() options to throw exceptions.

fix

Pass { validationErrors: true } to start() options.

affects: >=0.0.0

gotchaOnly MySQL is supported; no PostgreSQL, SQLite, etc.

fix

Use a different ORM if you need multi-dialect support.

affects: >=0.0.0

Errors

Common errors & fixes

Cannot find module 'modular-orm' or its corresponding type declarations.

Package not installed or tsconfig missing 'node' module resolution.

fix

Run `npm install modular-orm` and ensure tsconfig.json has `"moduleResolution": "node"` with `"module": "ES2020"` or use `--esModuleInterop`.

Error: ModularORM is not constructed properly. Did you call ModularORM.getInstance()?

Using `new ModularORM()` instead of singleton getInstance().

fix

Replace `const orm = new ModularORM();` with `const orm = ModularORM.getInstance();`.

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

Repository.find() expects a valid filter object; passing undefined/null breaks internal mapping.

fix

Always pass an object, e.g., `repo.find({})` for all rows.

SQL Error: Unknown column 'first_name' in 'field list'

Table column defined with a different name than in database, or migration not run.

fix

Ensure @Column() decorator matches DB schema, or run auto-migrations with `checkTablesExists: true` in start().

Upgrade

Version history

0.3.51latest on npm

Audit

Dependencies

mysql2requiredMySQL database driver for query execution

Agent activity

5 hits · last 30 days

node

Amazon

Resources

githubhttps://github.com/KoP3YkA/ModularORM ↗

packagemodular-orm ↗

homepagehttps://github.com/KoP3YkA/ModularORM/wiki ↗