near-orm

library0.4.1jsnpmunverified

A minimalist, fully-typed ORM for IndexedDB inspired by Prisma. Version 0.4.1, released as @latest. Zero dependencies, ~10KB uncompressed. Key differentiators: type-safe schema definition, query builder, migrations, transactions, event system, and integration with IndexedDB for offline-first web apps. Unlike raw IndexedDB, it provides a Prisma-like API with automatic type inference and simple migration handling.

database

npm install near-orm

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · NEAR-ORM

near-orm

databasejavascriptv0.4.1

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.

ORM

✓ import { ORM } from 'near-orm'

✗ import ORM from 'near-orm'

ORM is a named export, not default.

defineSchema

✓ import { defineSchema } from 'near-orm'

✗ const defineSchema = require('near-orm').defineSchema

ESM-only; no CommonJS support.

field

✓ import { field } from 'near-orm'

Used inside defineSchema to define field properties.

QueryBuilder

✓

Internal type; not exported directly. Use db.models.tableName.query() to get a QueryBuilder instance.

Shows schema definition using defineSchema and field, initializing the ORM, and performing a create and read operation.

import { defineSchema, field, ORM } from 'near-orm'; const schema = defineSchema({ users: { fields: { id: field({ type: 'string', primaryKey: true }), name: field({ type: 'string' }), email: field({ type: 'string', unique: true }), createdAt: field({ type: 'date', default: { type: 'now' } }), updatedAt: field({ type: 'date', default: { type: 'now' } }), } } }); async function main() { const db = await ORM.init({ schema }); // Create a record await db.models.users.create({ id: '1', name: 'John Doe', email: 'john@example.com', }); // Read all users const users = await db.models.users.findAll(); console.log(users); } main().catch(console.error);

Debug

Known issues

deprecatedIn v0.3.x, seeding required including fields with defaults. Since v0.4.0 this is no longer necessary.

fix

Update to v0.4.0+ and remove explicit default fields from seed data where possible.

affects: >=0.3.0 <0.4.0

breakingThe 'upsert' method was added in v0.4.0. Code relying on older versions will not have this method.

fix

Upgrade to v0.4.0+ to use upsert, or implement custom logic for create-or-update.

affects: <0.4.0

gotchaPrimary keys must be defined exactly one per model; not doing so will cause silent failures or runtime errors.

fix

Ensure each model has exactly one field with primaryKey: true.

affects: >=0.1.0

gotchaIndexedDB is only available in browser environments; using near-orm in non-browser runtimes (Node.js, Deno) will fail.

fix

Only use near-orm in code that runs in a browser or with a polyfill like fake-indexeddb.

affects: >=0.1.0

breakingIn v0.x prior to 0.4.0, the 'init' function returned a different internal structure; after v0.4.0 it returns an ORM instance with a 'models' property.

fix

Update code to use db.models instead of direct db methods.

affects: <0.4.0

Errors

Common errors & fixes

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

Trying to call db.models.users.create() before db is fully initialized (await missing).

fix

Ensure await ORM.init() completes before using db.models: const db = await ORM.init({ schema });

Uncaught (in promise) DOMException: The database connection is closing

Calling IndexedDB operations after the database connection has been closed manually.

fix

Avoid calling db.close() prematurely, or ensure all operations are completed before closing.

Error: Migration failed: schema mismatch

Schema definition changed between runs causing IndexedDB schema version mismatch.

fix

Run db.migrate() after schema changes, or delete the IndexedDB database in browser DevTools to start fresh.

Upgrade

Version history

0.4.1latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

6 hits · last 30 days

node

Resources

githubhttps://github.com/ShafSpecs/near-orm ↗

packagenear-orm ↗

homepagehttps://github.com/ShafSpecs/near-orm#readme ↗