humble-node-orm

library0.0.53jsnpmunverified

A didactic, lightweight ORM for Node.js inspired by Rails' ActiveRecord. Version 0.0.53 is the latest stable release. It supports SQLite via a JSON configuration file, provides basic CRUD operations, associations (belongsTo, hasMany), validations, and a simple migration system. Unlike large ORMs like Sequelize or TypeORM, this package focuses on simplicity and learning, with minimal abstraction. Release cadence is irregular—mainly minor patches. Key differentiator: pure JavaScript, no dependencies, and a single-file approach for learning ORM concepts.

database

npm install humble-node-orm

package ↗

INSTALL

IMPORT

SIG · HUMBLE-NODE-ORM

humble-node-orm

databasejavascriptv0.0.53

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.

Model

✓ import { Model } from 'humble-node-orm'

✗ const Model = require('humble-node-orm').Model

Package is ESM-only. Do not use CommonJS require.

ORM

✓ import { ORM } from 'humble-node-orm'

✗ import ORM from 'humble-node-orm'

ORM is a named export, not default.

humble-migrate CLI

✓ npx humble-migrate migration:create <name>

✗ humble-migrate migration:run

CLI must be invoked via npx or global install. The command 'humble-migrate migration:run' works only if installed globally.

Shows basic setup: define models with associations and validations, create a table, insert a record, and query all users.

import { Model, ORM } from 'humble-node-orm'; class Post extends Model { constructor(data) { super(data); this.belongsTo(User); } } class User extends Model { static validations = { pseudo: (value) => value.length > 3 }; constructor(data) { super(data); this.hasMany(Post); } } const orm = new ORM({ type: 'sqlite', database: './databases/test.db' }); async function main() { await orm.connection.query(`CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, pseudo TEXT, password TEXT)`); const newUser = await User.create({ pseudo: 'Alice', password: 'alice123' }); console.log('New User:', newUser); const users = await User.all(); console.log('All Users:', users); await orm.close(); } main();

Debug

Known issues

gotchaConfiguration file must be named 'node-orm.config.json' and placed at project root. Other location or name is not supported.

fix

Place the config file at the project root with the exact name.

affects: >=0.0.0

breakingThe 'belongsTo' and 'hasMany' associations are defined inside the constructor using 'this' instead of static properties. This can cause issues with inheritance and multiple instances.

fix

Define associations in the constructor as shown in the docs. Do not define them as static methods.

affects: >=0.0.0

deprecatedGlobal installation of humble-node-orm is required for CLI migrations. The package does not recommend npx usage in early versions.

fix

Install globally: 'npm install -g humble-node-orm' then run 'humble-migrate' commands.

affects: <=0.0.53

gotchaValidation is only applied on 'create' and 'save', not on 'update'. If you need validation on update, you must manually call the validation function.

fix

Call the validation function manually in your update logic or override the update method.

affects: >=0.0.0

gotchaThe ORM only supports SQLite. There is no support for other databases like PostgreSQL or MySQL.

fix

Use a different ORM for other databases.

affects: >=0.0.0

Errors

Common errors & fixes

Error: Cannot find module 'better-sqlite3'

The package depends on 'better-sqlite3' but it's not installed automatically. It is missing from peerDependencies or optionalDependencies.

fix

Install the missing driver: 'npm install better-sqlite3'

TypeError: Class extends value undefined is not a constructor or null

Model is not imported correctly, often due to CommonJS require.

fix

Use ES6 import syntax: 'import { Model } from 'humble-node-orm''

Error: getaddrinfo ENOTFOUND localhost

The configuration file is missing or malformed. The ORM falls back to trying a network connection.

fix

Create a valid 'node-orm.config.json' at the project root with SQLite type and database path.

Error: Migration file not found: ./migrations/XXX

CLI migration commands require a 'migrations' directory at project root. It is not auto-created.

fix

Create the 'migrations' folder: 'mkdir migrations' or use 'humble-migrate migration:create' to generate files.

Upgrade

Version history

0.0.53latest on npm

Audit

Dependencies

better-sqlite3requiredSQLite database driver used internally for database connections

sqlite3optionalAlternative database driver for SQLite support

Agent activity

4 hits · last 30 days

node

Resources

packagehumble-node-orm ↗