Why NormalJS

- Simple: minimal surface area. Define models with a static fields object and go.
- Transaction-first: fully isolated repos inside transactions without leaking state.
- Advanced caching: centralized in-memory cache shared across child processes, with UDP-based clustering for peer invalidation.
- Powerful: relations (1:n, n:m), transactions, model mixins/extension, inheritance with discriminators, relation proxies.
- Productive: active records you can call methods on; lazy, ID-first reads that auto-hydrate fields; request-level caching with invalidation markers.
- Portable: works with Postgres and SQLite. Uses Knex under the hood.

$3

- Extensible field system: add custom field types that control serialization, JSON output, schema, and lifecycle hooks.
- Model extension and overwrite: register multiple classes with the same static _name to merge fields and attach static/instance behavior over time.
- Inheritance with discriminators: share a base model schema and behavior; allocate correct child records automatically.
- Schema sync (base synchronization): generate and evolve tables from model fields with migration-safe helpers.
- Clear split of responsibilities: simple static APIs for model-level operations, and instance methods/getters for active records.

Install


``bash
npm install normaljs pg -y
`

$3

NormalJS is written in TypeScript and includes full type definitions. TypeScript users get:

- Type-safe model definitions with autocomplete for fields and relations
- Type inference for query results and active records
- Generic types for models and records
- Declaration files (.d.ts) for all public APIs

`bash
npm install normaljs pg


TypeScript types are included - no @types package needed


`

`typescript
class MyModel {
static table = 'my_table';
static fields = {
/ ... /
};
}
`

Database engines

NormalJS supports these SQL databases via Knex:

Note: You only need the driver for the database(s) you use (e.g., pg for PostgreSQL, sqlite3 or better-sqlite3 for SQLite).

60‑second Quickstart

$3

`typescript
// index.ts
import { Connection, Repository } from 'normaljs';

// 1) Create a connection (SQLite in-memory shown; Postgres or MySQL also supported)
const db = new Connection({ client: 'sqlite3', connection: { filename: ':memory:' } });

// 2) Define models
class Users {
static table = 'users';
static fields = {
id: 'primary' as const,
firstname: { type: 'string', required: true },
lastname: { type: 'string', required: true },
email: { type: 'string', unique: true, required: true },
created_at: { type: 'datetime', default: () => new Date() },
updated_at: { type: 'datetime', default: () => new Date() },
};

get name() {
return ${this.firstname} ${this.lastname};
}
}
// Override readonly 'name' property for NormalJS
Object.defineProperty(Users, 'name', { value: 'Users', configurable: true });

class Posts {
static table = 'posts';
static fields = {
id: 'primary' as const,
title: { type: 'string', required: true },
content: { type: 'string', required: true },
author_id: { type: 'many-to-one', required: true, model: 'Users' },
};
}
Object.defineProperty(Posts, 'name', { value: 'Posts', configurable: true });

// 3) Register & sync
const repo = new Repository(db);
repo.register({ Users, Posts });
await repo.sync({ force: true });

// 4) Use it
const u = await repo
.get('Users')
.create({ firstname: 'Ada', lastname: 'Lovelace', email: 'ada@example.com' });
const p = await repo.get('Posts').create({ title: 'Hello', content: 'World', author_id: u.id });
console.log(u.name); // "Ada Lovelace"
`

$3

`js
// index.js
const { Connection, Repository } = require('normaljs');

// 1) Create a connection (SQLite in-memory shown; Postgres or MySQL also supported)
const db = new Connection({ client: 'sqlite3', connection: { filename: ':memory:' } });

// 2) Define models
class Users {
static table = 'users';
static fields = {
id: 'primary',
firstname: { type: 'string', required: true },
lastname: { type: 'string', required: true },
email: { type: 'string', unique: true, required: true },
created_at: { type: 'datetime', default: () => new Date() },
updated_at: { type: 'datetime', default: () => new Date() },
};

get name() {
return ${this.firstname} ${this.lastname};
}
}
// Override readonly 'name' property for NormalJS
Object.defineProperty(Users, 'name', { value: 'Users', configurable: true });

class Posts {
static table = 'posts';
static fields = {
id: 'primary',
title: { type: 'string', required: true },
content: { type: 'string', required: true },
author_id: { type: 'many-to-one', required: true, model: 'Users' },
};
}
Object.defineProperty(Posts, 'name', { value: 'Posts', configurable: true });

// 3) Register & sync
const repo = new Repository(db);
repo.register({ Users, Posts });
await repo.sync({ force: true });

// 4) Use it
const u = await repo
.get('Users')
.create({ firstname: 'Ada', lastname: 'Lovelace', email: 'ada@example.com' });
const p = await repo.get('Posts').create({ title: 'Hello', content: 'World', author_id: u.id });
console.log(u.name); // "Ada Lovelace"
`

$3

Static methods live on models; instance methods live on records. You can extend models incrementally or inherit from a base model.

`js
// Extension: register the same model name again to add fields + behavior
class Users {
static _name = 'Users';
static fields = { id: 'primary' };
}

// Extend Users with fields and static/instance APIs
class UsersExt {
static _name = 'Users';
static fields = { email: 'string' };
static byEmail(email) {
return this.where({ email }).first(); // simple, model-scoped static API
}
get domain() {
return this.email?.split('@')[1] || null; // instance API on active record
}
}

// Inheritance: child model shares base structure and behavior
class Payment {
static _name = 'Payment';
static fields = { id: 'primary', amount: 'float' };
}
class CardPayment {
static _name = 'CardPayment';
static inherits = 'Payment';
static fields = { pan: 'string' };
}

repo.register(Users);
repo.register(UsersExt); // extension merged
repo.register({ Payment, CardPayment });
`

Features at a glance

- Models
- Simple class with static _name, static table, static fields.
- Extension system: register multiple times with same static _name to add/override fields and behavior.
- Inheritance with discriminators for polymorphic models.
- NEW: Model scopes for reusable query filters and eager loading patterns.
- Fields
- Built-ins: primary, integer/float, string/text, boolean, date/datetime, enum, json, reference.
- Constraints: default, required, unique, index.
- Custom fields: implement serialization, JSON, schema, and lifecycle hooks.
- NEW: Model-level indexes for composite, unique, and partial indexes (e.g., static indexes = { idx_name: { fields: ['email', 'company'], unique: true } }).
- Relations
- 1:n via one-to-many (e.g., comments: { type: 'one-to-many', foreign: 'Comments.post_id' }).
- n:m via paired many-to-many (auto-join table).
- Relation proxies on instances: add, remove, load.
- NEW: Automatic join generation for relational filters (e.g., where({ 'author.organization.name': 'ACME' })).
- Scopes
- Define reusable query patterns at the model level.
- Support for defaultScope applied to all queries unless bypassed.
- Parameterized scopes via functions.
- Composable scopes with deterministic merging.
- NEW: See docs/scopes.md for comprehensive guide.
- Transactions
- repo.transaction(async (tx) => { / ... / }) gives an isolated tx-bound repository.
- Post-commit cache flush of changed records.
- Active records
- Rows are wrapped into instances; instance methods and getters work naturally.
- Default reads select only id (fast), with lazy hydration from cache/DB.
- Cache and discovery
- Request-level caching via .cache(ttl) and entry cache per Model:ID.
- Per-model invalidation markers ($Model) to evict request caches without dropping entry caches.
- Centralized in-memory cache across processes with UDP-based clustering.
- Discovery protocol auto-syncs peer list for invalidations.
- Repository Context
- NEW: Repository-wide context accessible in transactions, models, and records.
- get_context(key, defaultValue) retrieves context values.
- set_context(key, value) stores context values.
- Transactions inherit parent context but modifications are isolated.
- Use cases: multi-tenancy, user context, feature flags, request metadata.
- Schema sync
- Create/update tables from model fields with repo.sync().
- Migration-safe helpers for column replacement and index updates.

See full field reference in docs/fields.md.

$3

- docs/models.md — Model definitions, inheritance, and extension system.
- docs/fields.md — Built-in field types and options.
- docs/scopes.md — NEW: Model scopes for reusable query filters.
- docs/requests.md — Request API, criteria DSL, and request-level caching.
- docs/relational-filters.md — NEW: Automatic joins for relational field filters.
- docs/cache.md — Cache architecture, connection options, discovery, and model cache options.
- docs/custom-fields.md — In-depth custom fields with hooks and a file-storage example.
- docs/adoption-sequelize.md — Step-by-step migration guide from Sequelize.

Demo

Explore demo/` for a working blog schema (Users, Posts, Tags, Comments) and a CRM and Stocks example.

License

The MIT License (MIT)