bigal

library15.11.9jsnpmunverified

A type-safe PostgreSQL ORM for Node.js written in TypeScript, featuring a fluent query builder, decorator-based models, and immutable query state. Version 15.11.9, released under MIT license. Exclusively for PostgreSQL, optimizing queries for JSONB, DISTINCT ON, subquery joins, and ON CONFLICT upserts. Requires Node.js >=20.11.0 and a PostgreSQL driver (postgres-pool, pg, or @neondatabase/serverless). Ships TypeScript types and provides machine-readable documentation for AI tools.

database

npm install bigal

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · BIGAL

bigal

databasejavascriptv15.11.9

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.

Entity

✓ import { Entity } from 'bigal'

✗ const { Entity } = require('bigal')

BigAl is ESM-only since v3; require() throws ERR_REQUIRE_ESM.

table

✓ import { table } from 'bigal'

✗ import { Table } from 'bigal'

The decorator is lowercase 'table', not uppercase.

Repository

✓ import { Repository } from 'bigal'

✗ import { Repository } from 'bigal/repository'

Repository is a top-level export, not a subpath.

initialize

✓ import { initialize } from 'bigal'

✗ import { initialize } from 'bigal/initialize'

initialize is also top-level.

column

✓ import { column } from 'bigal'

✗ import { Column } from 'bigal'

Decorator is lowercase.

primaryColumn

✓ import { primaryColumn } from 'bigal'

✗ import { PrimaryColumn } from 'bigal'

Decorator is lowercase camelCase.

Defines a Product model with decorators, initializes the ORM with a Pool, and performs a fluent query with filters and sorting.

import { column, primaryColumn, table, Entity, initialize, Repository } from 'bigal'; import { Pool } from 'postgres-pool'; @table({ name: 'products' }) class Product extends Entity { @primaryColumn({ type: 'integer' }) public id!: number; @column({ type: 'string', required: true }) public name!: string; @column({ type: 'integer', required: true, name: 'price_cents' }) public priceCents!: number; } const pool = new Pool(process.env.DATABASE_URL ?? 'postgres://localhost/mydb'); const repos = initialize({ models: [Product], pool }); const productRepository = repos.Product as Repository<Product>; const products = await productRepository .find() .where({ priceCents: { '>=': 1000 }, name: { contains: 'widget' } }) .sort('name asc') .limit(10); console.log(products);

Debug

Known issues

breakingBigAl v3 dropped CJS support and is ESM-only

fix

Use 'import' syntax or dynamic import() instead of require(). Ensure package.json contains "type": "module" or use .mjs extension.

affects: >=3.0.0

deprecatedAs of v15, Entity class is deprecated; use plain objects with @model decorator instead

fix

Extend Model instead of Entity, or use @model decorator on a class without extending Entity.

affects: >=15.0.0

gotchainitialize() requires all models to be decorated; otherwise they are silently ignored

fix

Ensure every model class has @table decorator (or @model in v15+) and extends Entity/Model.

affects: >=1.0.0

gotchaWhen using ON CONFLICT upsert, targets must be unique columns (indexed or primary key); otherwise PostgreSQL throws error

fix

Verify that columns in 'targets' array have a unique index or are primary keys.

affects: >=1.0.0

breakingBigAl v8 changed the return type of find() from Promise<Entity[]> to Promise<Entity[], {count: number}> for pagination

fix

Use .withCount() to explicitly request total count; default now returns only rows.

affects: >=8.0.0 <9.0.0

deprecatedThe 'postgres' driver option (postgres-pool) is replaced by 'postgres-pool' package name in v12

fix

Replace 'postgres' with 'postgres-pool' in your dependencies and import.

affects: >=12.0.0

gotchaDecorators require experimentalDecorators: true in tsconfig.json

fix

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

affects: >=1.0.0

Errors

Common errors & fixes

Error: Cannot find module 'bigal'

BigAl not installed or Node.js version below 20.11.0

fix

Run 'npm install bigal' and ensure node >=20.11.0 (use nvm or upgrade).

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

Missing import of Entity class before class definition, or circular dependency

fix

Add 'import { Entity } from 'bigal'' before using the decorator.

ER_NOT_USED: The decorator 'table' cannot be used without 'initialize'

Using @table decorator but never calling initialize()

fix

Call initialize({ models: [YourClass], pool }) before using any model.

QueryError: column "price_cents" of relation "products" does not exist

Database schema does not match the model's column definitions or column name mapping

fix

Ensure the database table has all columns defined in the model; check the 'name' property in @column decorator if different.

Type '{}' is not assignable to type 'Repository<Product>'

Incorrect type assertion after initialize() — repos.Product is typed as any

fix

Cast as Repository<Product>: const productRepository = repos.Product as Repository<Product>;

Upgrade

Version history

15.11.9latest on npm

Audit

Dependencies

postgres-pooloptionalRecommended PostgreSQL driver for connection pooling

pgoptionalAlternative PostgreSQL driver (node-postgres)

@neondatabase/serverlessoptionalAlternative for Neon serverless PostgreSQL

Agent activity

11 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/bigalorm/bigal ↗

packagebigal ↗

homepagehttps://bigalorm.github.io/bigal/ ↗