bigal 16.0.0-beta.3 → 16.0.0

package/docs/.vitepress/config.ts

@@ -68,7 +68,6 @@ export default defineConfig({
           { text: 'Relationships', link: '/guide/relationships' },
           { text: 'Subqueries & Joins', link: '/guide/subqueries-and-joins' },
           { text: 'Views', link: '/guide/views' },
-          { text: 'Migrating to v16', link: '/guide/migration-v16' },
         ],
       },
       {

package/docs/advanced/bigal-vs-raw-sql.md

@@ -29,35 +29,35 @@ Drop to raw SQL (via your pool directly) when:
 
 ### Basic queries
 
-| SQL                                                   | BigAl                                                    |
-| ----------------------------------------------------- | -------------------------------------------------------- |
-| `SELECT * FROM products WHERE id = 1`                 | `Product.findOne().where({ id: 1 })`                     |
-| `SELECT name FROM products WHERE id = 1`              | `Product.findOne({ select: ['name'] }).where({ id: 1 })` |
-| `SELECT * FROM products WHERE name ILIKE '%widget%'`  | `Product.find().where({ name: { contains: 'widget' } })` |
-| `SELECT * FROM products WHERE price >= 100`           | `Product.find().where({ price: { '>=': 100 } })`         |
-| `SELECT * FROM products WHERE status IN ('a','b')`    | `Product.find().where({ status: ['a', 'b'] })`           |
-| `SELECT * FROM products WHERE status <> 'x'`          | `Product.find().where({ status: { '!': 'x' } })`         |
-| `SELECT * FROM products WHERE deleted_at IS NOT NULL` | `Product.find().where({ deletedAt: { '!': null } })`     |
-| `SELECT * FROM products ORDER BY name LIMIT 10`       | `Product.find().where({}).sort('name asc').limit(10)`    |
-| `SELECT COUNT(*) FROM products WHERE active = true`   | `Product.count().where({ active: true })`                |
+| SQL                                                   | BigAl                                                        |
+| ----------------------------------------------------- | ------------------------------------------------------------ |
+| `SELECT * FROM products WHERE id = 1`                 | `productRepo.findOne().where({ id: 1 })`                     |
+| `SELECT name FROM products WHERE id = 1`              | `productRepo.findOne({ select: ['name'] }).where({ id: 1 })` |
+| `SELECT * FROM products WHERE name ILIKE '%widget%'`  | `productRepo.find().where({ name: { contains: 'widget' } })` |
+| `SELECT * FROM products WHERE price >= 100`           | `productRepo.find().where({ price: { '>=': 100 } })`         |
+| `SELECT * FROM products WHERE status IN ('a','b')`    | `productRepo.find().where({ status: ['a', 'b'] })`           |
+| `SELECT * FROM products WHERE status <> 'x'`          | `productRepo.find().where({ status: { '!': 'x' } })`         |
+| `SELECT * FROM products WHERE deleted_at IS NOT NULL` | `productRepo.find().where({ deletedAt: { '!': null } })`     |
+| `SELECT * FROM products ORDER BY name LIMIT 10`       | `productRepo.find().where({}).sort('name asc').limit(10)`    |
+| `SELECT COUNT(*) FROM products WHERE active = true`   | `productRepo.count().where({ active: true })`                |
 
 ### CRUD
 
-| SQL                                                         | BigAl                                      |
-| ----------------------------------------------------------- | ------------------------------------------ |
-| `INSERT INTO products (name) VALUES ('Widget') RETURNING *` | `Product.create({ name: 'Widget' })`       |
-| `UPDATE products SET name = 'X' WHERE id = 1 RETURNING *`   | `Product.update({ id: 1 }, { name: 'X' })` |
-| `DELETE FROM products WHERE id = 1 RETURNING *`             | `Product.destroy({ id: 1 })`               |
+| SQL                                                         | BigAl                                          |
+| ----------------------------------------------------------- | ---------------------------------------------- |
+| `INSERT INTO products (name) VALUES ('Widget') RETURNING *` | `productRepo.create({ name: 'Widget' })`       |
+| `UPDATE products SET name = 'X' WHERE id = 1 RETURNING *`   | `productRepo.update({ id: 1 }, { name: 'X' })` |
+| `DELETE FROM products WHERE id = 1 RETURNING *`             | `productRepo.destroy({ id: 1 })`               |
 
 ### Subqueries, joins, and advanced
 
-| SQL                                                                      | BigAl                                                                               |
-| ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------- |
-| `WHERE store_id IN (SELECT id FROM stores WHERE active)`                 | `.where({ store: { in: subquery(Store).select(['id']).where({ active: true }) } })` |
-| `INNER JOIN stores s ON p.store_id = s.id WHERE s.name = 'Acme'`         | `.join('store').where({ store: { name: 'Acme' } })`                                 |
-| `SELECT DISTINCT ON (store_id) * ... ORDER BY store_id, created_at DESC` | `.distinctOn(['store']).sort('store').sort('createdAt desc')`                       |
-| `ON CONFLICT (sku) DO NOTHING`                                           | `{ onConflict: { action: 'ignore', targets: ['sku'] } }`                            |
-| `ON CONFLICT (sku) DO UPDATE SET name = EXCLUDED.name`                   | `{ onConflict: { action: 'merge', targets: ['sku'], merge: ['name'] } }`            |
+| SQL                                                                      | BigAl                                                                                   |
+| ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------- |
+| `WHERE store_id IN (SELECT id FROM stores WHERE active)`                 | `.where({ store: { in: subquery(storeRepo).select(['id']).where({ active: true }) } })` |
+| `INNER JOIN stores s ON p.store_id = s.id WHERE s.name = 'Acme'`         | `.join('store').where({ store: { name: 'Acme' } })`                                     |
+| `SELECT DISTINCT ON (store_id) * ... ORDER BY store_id, created_at DESC` | `.distinctOn(['store']).sort('store').sort('createdAt desc')`                           |
+| `ON CONFLICT (sku) DO NOTHING`                                           | `{ onConflict: { action: 'ignore', targets: ['sku'] } }`                                |
+| `ON CONFLICT (sku) DO UPDATE SET name = EXCLUDED.name`                   | `{ onConflict: { action: 'merge', targets: ['sku'], merge: ['name'] } }`                |
 
 ## Mixing BigAl and raw SQL
 

package/docs/advanced/known-issues.md

@@ -1,42 +1,47 @@
 ---
-description: Known issues and workarounds - hasMany collections with populate, and query observability.
+description: Known issues and workarounds — optional collections, NotEntity for JSON objects with id fields, and DEBUG_BIGAL logging.
 ---
 
 # Known Issues
 
-## hasMany collections require populate
+## Entity collections must be optional
 
-`hasMany` relationships are excluded from the select and insert types. They are only present
-on query results after calling `.populate()`:
+Collection properties (one-to-many, many-to-many) must be declared as optional. They are only present after `.populate()` and will cause `QueryResult` type errors if required:
 
 ```ts
-// categories is NOT on the result type
-const product = await Product.findOne().where({ id: 42 });
+// Correct
+@column({ collection: () => 'Product', via: 'store' })
+public products?: Product[];
 
-// categories IS on the result type after populate
-const populated = await Product.findOne().where({ id: 42 }).populate('categories');
+// Incorrect — causes type issues
+@column({ collection: () => 'Product', via: 'store' })
+public products!: Product[];
 ```
 
-## Query observability
+## Non-entity objects with id fields
 
-Use the `onQuery` callback in `initialize()` for structured query logging:
+If a JSON column contains objects with an `id` property, TypeScript may mistake them for BigAl entities. Wrap the type with `NotEntity<T>`:
 
 ```ts
-const { Product } = initialize({
-  pool,
-  models: { Product },
-  onQuery({ sql, params, duration, error, model, operation }) {
-    logger.debug({ sql, params, duration, model, operation });
-  },
-});
+import type { NotEntity } from 'bigal';
+
+interface IMyJsonType {
+  id: string;
+  foo: string;
+}
+
+@column({ type: 'json' })
+public metadata?: NotEntity<IMyJsonType>;
 ```
 
-The `DEBUG_BIGAL` environment variable still works as a fallback when no `onQuery` callback is
-provided:
+Without `NotEntity`, BigAl's type system treats the type as an entity relationship, which leads to incorrect type narrowing in `QueryResult`.
+
+## Debugging queries
+
+Set the `DEBUG_BIGAL` environment variable to see generated SQL:
 
 ```sh
 DEBUG_BIGAL=true node app.js
 ```
 
-This logs all SQL statements and parameter values to the console. Note that `params` may contain
-sensitive data.
+This logs all SQL statements and parameter values to the console.

package/docs/getting-started.md

@@ -1,5 +1,5 @@
 ---
-description: Install BigAl, define your first model, create a repository, and run type-safe PostgreSQL queries.
+description: Install BigAl, define your first model with decorators, initialize a repository, and run type-safe PostgreSQL queries.
 ---
 
 # Getting Started
@@ -25,56 +25,63 @@ npm install @neondatabase/serverless
 
 ## Define a model
 
-Models are defined with the `table()` function and PostgreSQL-native column builders. Types are
-inferred from the schema definition. Column names are auto-derived from property keys using snakeCase.
+Models extend `Entity` and use decorators to map to database tables.
 
 ```ts
-import { createdAt, table, integer, serial, text, updatedAt, varchar } from 'bigal';
-
-export const Product = table('products', {
-  id: serial().primaryKey(),
-  name: text().notNull(),
-  sku: varchar({ length: 100 }),
-  priceCents: integer().notNull(),
-  createdAt: createdAt(),
-  updatedAt: updatedAt(),
-});
+import { column, primaryColumn, table, Entity } from 'bigal';
+
+@table({ name: 'products' })
+export class Product extends Entity {
+  @primaryColumn({ type: 'integer' })
+  public id!: number;
+
+  @column({ type: 'string', required: true })
+  public name!: string;
+
+  @column({ type: 'string' })
+  public sku?: string;
+
+  @column({ type: 'integer', required: true, name: 'price_cents' })
+  public priceCents!: number;
+}
 ```
 
 ## Initialize repositories
 
-Pass your models and a connection pool to `initialize()`. The object-style models option gives you
-typed repositories directly via destructuring:
+Pass your models and a connection pool to `initialize()`. It returns a map of repositories keyed by model name.
 
 ```ts
-import { initialize } from 'bigal';
+import { initialize, Repository } from 'bigal';
 import { Pool } from 'postgres-pool';
 import { Product } from './Product';
 
 const pool = new Pool('postgres://localhost/mydb');
 
-const { Product } = initialize({
-  models: { Product },
+const repos = initialize({
+  models: [Product],
   pool,
 });
+
+const productRepository = repos.Product as Repository<Product>;
 ```
 
 ## Run your first query
 
-Queries use a fluent builder and are `PromiseLike` - just `await` the chain.
+Queries use a fluent builder and are `PromiseLike` — just `await` the chain.
 
 ```ts
 // Find all products with price >= 1000 cents, sorted by name
-const products = await Product.find()
+const products = await productRepository
+  .find()
   .where({ priceCents: { '>=': 1000 } })
   .sort('name asc')
   .limit(10);
 
 // Find one product by ID
-const product = await Product.findOne().where({ id: 42 });
+const product = await productRepository.findOne().where({ id: 42 });
 
 // Count matching records
-const count = await Product.count().where({ sku: { '!': null } });
+const count = await productRepository.count().where({ sku: { '!': null } });
 ```
 
 ## Using with AI assistants
@@ -88,13 +95,12 @@ npx skills add bigalorm/bigal
 
 Machine-readable documentation is also available:
 
-- [llms.txt](/llms.txt) - structured overview
-- [llms-full.txt](/llms-full.txt) - complete documentation in a single file
+- [llms.txt](/llms.txt) — structured overview
+- [llms-full.txt](/llms-full.txt) — complete documentation in a single file
 
 ## Next steps
 
-- [Models](/guide/models) - table definitions, column types, relationships
-- [Querying](/guide/querying) - operators, pagination, JSONB, and more
-- [CRUD Operations](/guide/crud-operations) - create, update, and destroy
-- [API Reference](/reference/api) - all exports and method signatures
-- [Migrating from v15](/guide/migration-v16) - upgrade from decorators to the new API
+- [Models](/guide/models) — decorators, relationships, and Entity types
+- [Querying](/guide/querying) — operators, pagination, JSONB, and more
+- [CRUD Operations](/guide/crud-operations) — create, update, and destroy
+- [API Reference](/reference/api) — all exports and method signatures

package/docs/guide/crud-operations.md

@@ -1,19 +1,18 @@
 ---
-description: Create, update, and destroy records with RETURNING support, query projection, toSQL, and ON CONFLICT upserts.
+description: Create, update, and destroy records with RETURNING support, query projection, and ON CONFLICT upserts.
 ---
 
 # CRUD Operations
 
-BigAl repositories provide `create()`, `update()`, and `destroy()` methods. All three return affected
-records by default (using `RETURNING *`), and all support `returnRecords` and `returnSelect` options.
-Results are always plain objects.
+BigAl repositories provide `create()`, `update()`, and `destroy()` methods. All three return affected records
+by default (using `RETURNING *`), and all support `returnRecords` and `returnSelect` options.
 
 ## Create
 
 ### Single record
 
 ```ts
-const product = await Product.create({
+const product = await productRepository.create({
   name: 'Widget',
   priceCents: 999,
 });
@@ -23,17 +22,31 @@ const product = await Product.create({
 ### Multiple records
 
 ```ts
-const products = await Product.create([
+const products = await productRepository.create([
   { name: 'Widget', priceCents: 999 },
   { name: 'Gadget', priceCents: 1499 },
 ]);
 // products = [{ id: 42, ... }, { id: 43, ... }]
 ```
 
+Passing an array builds a single multi-row `INSERT` statement, one round trip for the whole batch. Prefer this over calling
+`create()` in a loop, which issues a separate `INSERT` (and round trip) per record:
+
+```ts
+// Correct — one INSERT statement for all rows
+const products = await productRepository.create(items);
+
+// Slower — a separate INSERT statement and round trip per item
+const products = [];
+for (const item of items) {
+  products.push(await productRepository.create(item));
+}
+```
+
 ### Skip returning records
 
 ```ts
-await Product.create({ name: 'Widget', priceCents: 999 }, { returnRecords: false });
+await productRepository.create({ name: 'Widget', priceCents: 999 }, { returnRecords: false });
 ```
 
 ### Query projection (returnSelect)
@@ -41,14 +54,14 @@ await Product.create({ name: 'Widget', priceCents: 999 }, { returnRecords: false
 Return only specific columns. The primary key is always included.
 
 ```ts
-const product = await Product.create({ name: 'Widget', priceCents: 999 }, { returnSelect: ['name'] });
+const product = await productRepository.create({ name: 'Widget', priceCents: 999 }, { returnSelect: ['name'] });
 // product = { id: 42, name: 'Widget' }
 ```
 
 Pass an empty array to return only the primary key:
 
 ```ts
-const product = await Product.create({ name: 'Widget', priceCents: 999 }, { returnSelect: [] });
+const product = await productRepository.create({ name: 'Widget', priceCents: 999 }, { returnSelect: [] });
 // product = { id: 42 }
 ```
 
@@ -59,7 +72,7 @@ Handle constraint violations with PostgreSQL's `ON CONFLICT` clause.
 ### Ignore (DO NOTHING)
 
 ```ts
-const product = await Product.create(
+const product = await productRepository.create(
   { name: 'Widget', sku: 'WDG-001' },
   {
     onConflict: {
@@ -73,7 +86,7 @@ const product = await Product.create(
 ### Merge (DO UPDATE) - all columns
 
 ```ts
-const product = await Product.create(
+const product = await productRepository.create(
   { name: 'Widget', sku: 'WDG-001', priceCents: 999 },
   {
     onConflict: {
@@ -87,7 +100,7 @@ const product = await Product.create(
 ### Merge - specific columns
 
 ```ts
-const product = await Product.create(
+const product = await productRepository.create(
   { name: 'Widget', sku: 'WDG-001', priceCents: 999 },
   {
     onConflict: {
@@ -105,11 +118,11 @@ const product = await Product.create(
 
 ```ts
 // Update a single record
-const products = await Product.update({ id: 42 }, { name: 'Super Widget' });
+const products = await productRepository.update({ id: 42 }, { name: 'Super Widget' });
 // products = [{ id: 42, name: 'Super Widget', ... }]
 
 // Update multiple records
-const products = await Product.update({ id: [42, 43] }, { priceCents: 1299 });
+const products = await productRepository.update({ id: [42, 43] }, { priceCents: 1299 });
 // products = [{ id: 42, ... }, { id: 43, ... }]
 ```
 
@@ -118,74 +131,42 @@ const products = await Product.update({ id: [42, 43] }, { priceCents: 1299 });
 Without returning records:
 
 ```ts
-await Product.update({ id: 42 }, { name: 'Super Widget' }, { returnRecords: false });
+await productRepository.update({ id: 42 }, { name: 'Super Widget' }, { returnRecords: false });
 ```
 
 With query projection:
 
 ```ts
-const products = await Product.update({ id: [42, 43] }, { priceCents: 1299 }, { returnSelect: ['id'] });
+const products = await productRepository.update({ id: [42, 43] }, { priceCents: 1299 }, { returnSelect: ['id'] });
 // products = [{ id: 42 }, { id: 43 }]
 ```
 
 ## Destroy
 
-`destroy()` takes a where clause object. Returns `void` by default.
-
-```ts
-// Delete records (returns void)
-await Product.destroy({ id: 42 });
-await Product.destroy({ id: [42, 43] });
-```
-
-With returning records:
+`destroy()` takes a where clause object. Returns an array of deleted records.
 
 ```ts
-const products = await Product.destroy({ id: 42 }, { returnRecords: true });
+// Delete a single record
+const products = await productRepository.destroy({ id: 42 });
 // products = [{ id: 42, name: 'Super Widget', ... }]
-```
-
-With query projection:
 
-```ts
-const products = await Product.destroy({ id: [42, 43] }, { returnSelect: ['name'] });
-// products = [{ id: 42, name: 'Widget' }, { id: 43, name: 'Gadget' }]
+// Delete multiple records
+const products = await productRepository.destroy({ id: [42, 43] });
 ```
 
-> The primary key is always included when returning records. Pass an empty array to return only the
-> primary key.
-
-## toSQL() on mutations
+> `destroy()` always returns an array, regardless of how many records were affected.
 
-All mutation operations support `toSQL()` to inspect the generated SQL without executing:
+Without returning records:
 
 ```ts
-// Create
-const { sql, params } = Product.create({ name: 'Widget', priceCents: 999 }).toSQL();
-
-// Update
-const { sql, params } = Product.update({ id: 42 }, { name: 'Super Widget' }).toSQL();
-
-// Destroy
-const { sql, params } = Product.destroy({ id: 42 }).toSQL();
+await productRepository.destroy({ id: 42 }, { returnRecords: false });
 ```
 
-This is useful for debugging, logging, and testing SQL generation.
-
-## Initialization example
+With query projection:
 
 ```ts
-import { initialize, table, serial, text, integer, createdAt, updatedAt } from 'bigal';
-import { Pool } from 'postgres-pool';
-
-const Product = table('products', {
-  id: serial().primaryKey(),
-  name: text().notNull(),
-  priceCents: integer().notNull(),
-  createdAt: createdAt(),
-  updatedAt: updatedAt(),
-});
-
-const pool = new Pool('postgres://localhost/mydb');
-const { Product } = initialize({ models: { Product }, pool });
+const products = await productRepository.destroy({ id: [42, 43] }, { returnSelect: ['name'] });
+// products = [{ id: 42, name: 'Widget' }, { id: 43, name: 'Gadget' }]
 ```
+
+> The primary key is always included. Pass an empty array to return only the primary key.