relax-orm

library1.2.1jsnpmunverified

A lightweight ORM for OracleDB, inspired by Sequelize and sequelize-typescript. Provides decorator-based entity mapping (@Table, @Column, @PrimaryKey, @Sequence), CRUD operations (findAll, findOne, create, save, destroy, destroyAll), and support for WHERE conditions with logical operators (Op.or, Op.and). Current version 1.2.1, released as stable. Requires oracledb client (node-oracledb) as a peer dependency. Features TypeScript typings and ESM exports. Differentiated by being Oracle-specific (not multi-dialect) and using a class-based Entity pattern with automatic sequence handling and RETURNING clause on INSERT/UPDATE.

database

npm install relax-orm

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · RELAX-ORM

relax-orm

databasejavascriptv1.2.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.

ConnectionManager

✓ import { ConnectionManager } from 'relax-orm'

✗ const { ConnectionManager } = require('relax-orm')

Package uses ESM; require() works in older setups but import is recommended.

Entity

✓ import { Entity } from 'relax-orm'

Base class for entities; must be used with generics and decorators.

Table

✓ import { Table } from 'relax-orm'

Decorator to specify table name, required on each entity class.

✓ import { Op } from 'relax-orm'

Used for logical operators in where clauses (Op.or, Op.and).

Shows entity definition with decorators, connection setup, find/save/destroy operations.

import { ConnectionManager, Entity, Table, PrimaryKey, Column, Sequence, Op } from 'relax-orm'; import oracledb from 'oracledb'; @Table('USER_TABLE') export class User extends Entity<User>{ @PrimaryKey() @Sequence('USER_SEQUENCE') @Column('USER_ID') id?: number; @Column() name?: string; } const conn = new ConnectionManager({ user: process.env.DB_USER ?? '', password: process.env.DB_PASSWORD ?? '', connectString: process.env.DB_CONNECT_STRING ?? 'localhost:1521/XEPDB1' }); conn.addEntities([User]); await conn.init(); const users = await User.findAll({ where: { name: 'walker' } }); console.log(users); const user = await User.findOne({ where: { id: 1 } }); if (user) { user.name = 'new name'; await user.save(); } await User.destroy({ name: 'obsolete' }); await conn.close();

Debug

Known issues

gotchadestroy() deletes rows matching where filter without confirmation; missing where clause is not prevented (uses destroyAll behavior).

fix

Always pass a where condition explicitly, or call destroyAll() for full table delete.

affects: >=1.0.0

gotchaEntity must have exactly one @PrimaryKey for save() to work; save() uses it as the update condition.

fix

Ensure exactly one field is decorated with @PrimaryKey.

affects: >=1.0.0

gotchaIf @Sequence is declared, the id value passed to create() is ignored and the sequence value is used.

fix

Do not rely on provided id when @Sequence is present; query the inserted record to get generated id.

affects: >=1.0.0

deprecatedThe config properties maxRows and fetchAsString are deprecated; set them on ConnectionManager.config before creating the instance.

fix

Set ConnectionManager.config.maxRows = 100; ConnectionManager.config.fetchAsString = [oracledb.DATE, oracledb.NUMBER]; before new ConnectionManager().

affects: <=1.2.1

Errors

Common errors & fixes

Error: ORA-12505: TNS:listener does not currently know of SID given in connect descriptor

Incorrect connectString or SID/service name not available.

fix

Verify the connectString format (e.g., host:port/service_name) and that the database listener is running.

Error: NJS-045: cannot load the oracledb add-on

Oracle instant client not installed or not in PATH.

fix

Install Oracle Instant Client (Basic or Basic Light) and set LD_LIBRARY_PATH (Linux) or PATH (Windows) to the client directory.

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

Entity not exported correctly or circular dependency.

fix

Ensure import { Entity } from 'relax-orm' is at the top and no circular imports exist.

Upgrade

Version history

1.2.1latest on npm

Audit

Dependencies

oracledbrequiredRequired OracleDB client for database connectivity.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/walker-walks/relax-orm ↗

packagerelax-orm ↗

homepagehttps://github.com/walker-walks/relax-orm#readme ↗