ORMSO

0.0.151 verified Sat May 09 auth: no javascript

ORMSO is a JavaScript object-relational mapper for SQLite (with extensibility to other databases) supporting object-to-database mapping, cross-database synchronization, and client data publishing. Current stable version is 0.0.151, released with pre-1.0 cadence meaning frequent breaking changes. Key differentiators: built-in sync between databases, and a publish layer for clients (with basic OData planned). Early-stage library, documentation sparse; not recommended for production without thorough vetting.

Common errors

error Error: Cannot find module 'better-sqlite3' ↓

cause Missing peer dependency `better-sqlite3`.

fix

Run npm install better-sqlite3.

error ERR_REQUIRE_ESM: require() of ES Module .../ormso/index.js not supported. ↓

cause Using CommonJS `require` on an ESM-only package.

fix

Switch to import or use dynamic import('ormso') in a CommonJS context.

error TypeError: ormso.default is not a function ↓

cause Using default import incorrectly, possible version mismatch.

fix

Check version; use import { ORM } from 'ormso' instead.

Warnings

breaking Version 0.x is pre-1.0, breaking changes occur frequently. No semantic versioning adherence between minor/patch bumps. ↓

fix Pin exact version in package.json and test upgrades thoroughly.

deprecated The `ormso` default export may be deprecated in favor of named exports in future versions. ↓

fix Use named exports like `ORM` and `Model` instead of default import when possible.

gotcha Database schema sync with `{ force: true }` drops existing tables. Data loss risk. ↓

fix Use `{ alter: true }` for safe migrations if supported, or backup database before sync.

gotcha ESM-only: `require('ormso')` will fail. Package does not provide CommonJS bundle. ↓

fix Use `import` syntax and ensure project is configured for ESM (type: 'module' in package.json).

gotcha SQLite driver `better-sqlite3` must be installed separately as a peer dependency. ↓

fix Run `npm install better-sqlite3` alongside `ormso`.

Install

npm install ormso

yarn add ormso

pnpm add ormso

Imports

ormso
wrong
```
const ormso = require('ormso')
```
correct
```
import ormso from 'ormso'
```
Primary default export; ESM-only as of v0.0.151 (no CJS support).

ORM

wrong

const ORM = require('ormso').ORM

correct

import { ORM } from 'ormso'

Named export for class ORM; ESM-only.

Model
```
import { Model } from 'ormso'
```
Named export for base Model class; ESM-only.

Quickstart

Shows how to create a SQLite database, define a model with ORMSO, sync schema, create and query records.

import ormso, { ORM, Model } from 'ormso';
import Database from 'better-sqlite3';

const db = new Database(':memory:');
const orm = new ORM(db);

class User extends Model {
  static tableName = 'users';
  static fields = {
    id: { type: Number, primaryKey: true },
    name: { type: String },
    email: { type: String }
  };
}

orm.register(User);
await orm.sync({ force: true });

const user = new User({ name: 'John', email: 'john@example.com' });
await user.save();

const found = await User.findOne({ where: { name: 'John' } });
console.log(found);