uql-orm

library0.9.0jsnpmunverified

UQL ORM is a fast, type-safe TypeScript Object-Relational Mapper (ORM) designed with a JSON-native query protocol. Currently at version 0.9.0, it aims for universal compatibility, running across Node.js, Bun, Deno, Cloudflare Workers, Electron, React Native, and browsers. It provides a unified API for various SQL and NoSQL databases, including PostgreSQL, MySQL, MariaDB, SQLite, LibSQL, Neon, D1, and MongoDB. Key differentiators include 100% serializable queries, deeply type-safe APIs for intelligent auto-completion, multi-level operators, and robust support for advanced features like semantic search. While still pre-1.0, the project shows active development with frequent updates and a strong focus on performance and developer experience, offering both decorator-based and imperative entity definition styles.

database serialization

npm install uql-orm

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · UQL-ORM

uql-orm

databasejavascriptv0.9.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

{ Entity, Id, Field }

✓ import { Entity, Id, Field } from 'uql-orm';

✗ import * as uql from 'uql-orm'; // Then uql.Entity

These are core decorators for defining entities, IDs, and fields. Requires 'experimentalDecorators' and 'emitDecoratorMetadata' in tsconfig.json if not using 'defineEntity'.

defineEntity

✓ import { defineEntity } from 'uql-orm';

✗ const defineEntity = require('uql-orm').defineEntity;

Introduced in v0.8.0, this imperative API allows defining entities without decorators, bypassing tsconfig.json requirements. UQL is Pure ESM, so `require` is generally incorrect.

PgQuerierPool

✓ import { PgQuerierPool } from 'uql-orm/postgres';

✗ import { PgQuerierPool } from 'uql-orm';

Database-specific querier pools are imported from subpaths (e.g., '/postgres', '/mysql', '/mongo') to keep bundles lean.

type Relation

✓ import { type Relation } from 'uql-orm';

✗ import { Relation } from 'uql-orm';

Utility type used for defining relationships between entities, preventing TypeScript circular dependency errors. Use `import type` for type-only imports.

This quickstart demonstrates defining a User entity with decorators, connecting to a PostgreSQL database using a querier pool, syncing the schema (caution: drops table), creating a new user, and performing a filtered query to fetch users by name. It also highlights necessary TypeScript compiler options.

import { Entity, Id, Field } from 'uql-orm'; import { PgQuerierPool } from 'uql-orm/postgres'; // 1. Define your Entity (User.ts) @Entity() export class User { @Id({ type: 'uuid' }) id?: string; @Field({ unique: true }) email?: string; @Field() name?: string; } // 2. Set up the Pool and Query (app.ts) async function runQuery() { const pool = new PgQuerierPool({ host: process.env.DB_HOST ?? 'localhost', port: parseInt(process.env.DB_PORT ?? '5432', 10), database: process.env.DB_NAME ?? 'app_db', user: process.env.DB_USER ?? 'postgres', password: process.env.DB_PASSWORD ?? 'password', }); try { await pool.withQuerier(async (querier) => { // Ensure schema is in sync (for development/testing) // In production, use migrations CLI await querier.sync(User, { drop: true }); // DANGER: drops table // Create a user const newUser = await querier.createOne(User, { email: 'test@example.com', name: 'John Doe' }); console.log('Created user:', newUser); // Find users const users = await querier.findMany(User, { $where: { name: { $istartsWith: 'John' } }, $select: { id: true, email: true }, }); console.log('Found users:', users); }); } catch (error) { console.error('Database operation failed:', error); } finally { await pool.end(); // Don't forget to release connections } } runQuery(); // tsconfig.json configuration for decorators: // { // "compilerOptions": { // "experimentalDecorators": true, // "emitDecoratorMetadata": true, // "moduleResolution": "NodeNext", // "module": "NodeNext", // "target": "ES2022" // } // }

Debug

Known issues

breakingUQL is currently pre-1.0 (v0.9.0), meaning API surfaces may evolve rapidly and introduce breaking changes in minor versions. Always review release notes when upgrading to new 0.x.x versions.

fix

Consult the official UQL documentation and release notes for migration guides when updating. Pin exact versions in production (`~0.x.y` rather than `^0.x.y`).

affects: >=0.0.0

gotchaIf using TypeScript decorators for entity definition (e.g., `@Entity`, `@Field`), your `tsconfig.json` must have `"experimentalDecorators": true` and `"emitDecoratorMetadata": true` enabled. Failure to do so will result in decorators being ignored or runtime errors due to missing metadata.

fix

Add or ensure the following in `compilerOptions` in your `tsconfig.json`: `{ "experimentalDecorators": true, "emitDecoratorMetadata": true }`. Alternatively, use the imperative `defineEntity` API which does not require these flags.

affects: >=0.0.0

gotchaUQL is a Pure ESM (ECMAScript Module) package. Using CommonJS `require()` statements to import UQL modules will lead to import errors. Your project's module resolution must be configured for ESM.

fix

Ensure your `tsconfig.json` (for TypeScript) or `package.json` (for Node.js) specifies ESM. For TypeScript, set `"module": "NodeNext"`, `"moduleResolution": "NodeNext"`, `"target": "ES2022"` or similar. For Node.js, ensure `"type": "module"` in `package.json` or use `.mjs` file extensions.

affects: >=0.0.0

gotchaDatabase drivers (e.g., `pg`, `mysql2`, `better-sqlite3`, `mongodb`) are peer dependencies and must be installed separately alongside `uql-orm`. UQL does not bundle these drivers.

fix

Install the appropriate driver package(s) for your chosen database(s). For example, `npm install uql-orm pg` for PostgreSQL.

affects: >=0.0.0

breakingPrior to v0.8.0, entity definitions in UQL were exclusively decorator-based, which required specific TypeScript compiler flags (`experimentalDecorators`). Version 0.8.0 introduced the `defineEntity` API as an alternative, decoupling entity metadata from class definitions and making decorators optional. This was a significant shift for projects constrained by decorator support.

fix

For new projects or if encountering decorator issues, consider using the `defineEntity` API. For existing projects relying on decorators, ensure your `tsconfig.json` is correctly configured as per `tsconfig.json` warnings.

affects: <0.8.0

Errors

Common errors & fixes

Decorators not working: Ensure experimentalDecorators and emitDecoratorMetadata are enabled in tsconfig.json

TypeScript compiler options are not set for decorator processing.

fix

Add `"experimentalDecorators": true` and `"emitDecoratorMetadata": true` to your `tsconfig.json` under `compilerOptions`.

ESM import issues: UQL is Pure ESM — set your module to NodeNext, ESNext, or Bundler

Attempting to import UQL in a CommonJS environment or with incorrect module resolution settings.

fix

Configure your project to use ECMAScript Modules (ESM). For TypeScript, set `"module": "NodeNext"` and `"moduleResolution": "NodeNext"` in `tsconfig.json`. For Node.js, ensure `"type": "module"` in `package.json`.

Connection errors: Double-check database credentials and that your driver package (for example pg, mysql2, or better-sqlite3) is installed and compatible with your runtime.

Incorrect database connection string, invalid credentials, or the required database driver package is missing or incompatible.

fix

Verify all connection parameters (host, port, user, password, database). Ensure you have installed the correct database driver (e.g., `npm install pg` for PostgreSQL) and that its version is compatible with your Node.js runtime and UQL.

TypeError: Cannot read properties of undefined (reading 'constructor') at Reflect.getMetadata

This error often occurs when decorators are used, but `emitDecoratorMetadata` is not enabled, leading to missing type metadata at runtime.

fix

Ensure `"emitDecoratorMetadata": true` is set in your `tsconfig.json` under `compilerOptions`.

Upgrade

Version history

0.9.0latest on npm

Audit

Dependencies

@libsql/clientoptionalRequired for connecting to LibSQL / Turso databases.

@neondatabase/serverlessoptionalRequired for connecting to Neon serverless PostgreSQL databases.

better-sqlite3optionalRequired for connecting to SQLite databases.

expressoptionalRequired for the 'uql-orm/express' middleware, which provides auto-generated REST APIs.

mariadboptionalRequired for connecting to MariaDB databases (dedicated driver).

mongodboptionalRequired for connecting to MongoDB databases.

mysql2optionalRequired for connecting to MySQL and MariaDB databases.

pgoptionalRequired for connecting to PostgreSQL, CockroachDB, and Neon databases.

pg-query-streamoptionalProvides streaming capabilities for PostgreSQL queries, often used with 'pg'.

Agent activity

28 hits · last 30 days

node