UQL ORM

Common errors

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

  cause 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

  cause 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.

  cause 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

  cause 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`.

Warnings

• breaking UQL 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`).
• gotcha If 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.
• gotcha UQL 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.
• gotcha Database 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.
• breaking Prior 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.

Install

• npm install uql-orm npm
• yarn add uql-orm yarn
• pnpm add uql-orm pnpm

Imports

• { Entity, Id, Field }
  wrong:

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

  correct:

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

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

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

  correct:

  import { defineEntity } from 'uql-orm';

  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
  wrong:

  import { PgQuerierPool } from 'uql-orm';

  correct:

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

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

  import { Relation } from 'uql-orm';

  correct:

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

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

Quickstart

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"
//   }
// }