Stingerloom ORM

A decorator-driven TypeScript ORM with layered multi-tenancy, built for PostgreSQL, MySQL, and SQLite.

Documentation · Getting Started · API Reference · Examples

---

Why Stingerloom?

• Decorator-first — Define entities, relations, hooks, and validation with TypeScript decorators. Column types are inferred automatically.
• Multi-tenancy built in — Layered metadata system (inspired by Docker OverlayFS) with AsyncLocalStorage-based context isolation. Zero cross-tenant leakage by design.
• Three databases, one API — MySQL, PostgreSQL, and SQLite share the same EntityManager interface. Switch drivers without rewriting queries.
• Schema Diff migrations — Compare live database state against entity metadata and auto-generate migration code.
• NestJS-ready — First-party module with @InjectRepository, @InjectEntityManager, and multi-DB named connections.

Quick Start

npm install @stingerloom/orm reflect-metadata
npm install pg        # or mysql2, better-sqlite3

import { EntityManager, Entity, PrimaryGeneratedColumn, Column } from "@stingerloom/orm";

@Entity()
class Post {
  @PrimaryGeneratedColumn()
  id!: number;

  @Column()
  title!: string;
}

const em = new EntityManager();
await em.register({ type: "postgres", entities: [Post], synchronize: true, /* ... */ });

const post = await em.save(Post, { title: "Hello World" });
const found = await em.findOne(Post, { where: { id: post.id } });

See the Getting Started guide for full setup instructions.

Features

Category	Highlights
Modeling	@Entity, @Column, @ManyToOne, @OneToMany, @ManyToMany, @OneToOne, eager/lazy loading
Querying	find, findOne, findWithCursor, findAndCount, Query Builder with JOIN/GROUP BY/HAVING
Mutations	save, update, delete, softDelete, restore, upsert, batch operations
Transactions	@Transactional decorator, manual BEGIN/COMMIT/ROLLBACK, savepoints, isolation levels
Multi-tenancy	Layered metadata (OverlayFS model), MetadataContext.run(), PostgreSQL schema isolation, TenantMigrationRunner
Migrations	SchemaDiff auto-detection, MigrationGenerator, CLI runner
Observability	N+1 detection, slow query warnings, EXPLAIN analysis, EntitySubscriber events
Validation	@NotNull, @MinLength, @MaxLength, @Min, @Max
Infrastructure	Connection pooling, read replicas, retry with backoff, per-query timeout, graceful shutdown
NestJS	StinglerloomOrmModule.forRoot/forFeature, @InjectRepository, @InjectEntityManager, multi-DB connections

Database Support

	MySQL	PostgreSQL	SQLite
CRUD	✓	✓	✓
Transactions	✓	✓	✓
Schema Sync	✓	✓	✓
Migrations	✓	✓	✓
ENUM	✓	✓ (native)	—
Schema Isolation	—	✓	—
Read Replica	✓	✓	—

Examples

Four NestJS example projects are included in examples/:

Project	Description
nestjs-cats	CRUD, relations, soft delete, cursor pagination, EntitySubscriber
nestjs-blog	ManyToMany, upsert, 59 e2e tests
nestjs-todo	Minimal CRUD with npm package verification
nestjs-multitenant	PostgreSQL schema-based tenant isolation

Contributing

Contributions are welcome. Please open an issue first to discuss what you'd like to change.

License

MIT