bigal 16.0.0-beta.3 → 16.0.0

package/docs/guide/querying.md

@@ -1,19 +1,18 @@
 ---
-description: Fluent query builder for find, findOne, and count with WHERE operators, JSONB querying, pagination, sorting, vector distance, global filters, toSQL, and populate. All results are plain objects.
+description: Fluent query builder for find, findOne, and count with WHERE operators, JSONB querying, pagination, sorting, DISTINCT ON, and populate.
 ---
 
 # Querying
 
-BigAl provides `findOne()`, `find()`, and `count()` methods on repositories. Queries use a fluent
-builder pattern - each method returns a new immutable instance, and queries are `PromiseLike` so you
-can `await` them directly.
+BigAl provides `findOne()`, `find()`, and `count()` methods on repositories. Queries use a fluent builder pattern —
+each method returns a new immutable instance, and queries are `PromiseLike` so you can `await` them directly.
 
 ## findOne
 
 Returns a single record or `null`:
 
 ```ts
-const product = await Product.findOne().where({ id: 42 });
+const product = await productRepository.findOne().where({ id: 42 });
 ```
 
 ### Query projection
@@ -21,9 +20,11 @@ const product = await Product.findOne().where({ id: 42 });
 Select specific columns:
 
 ```ts
-const product = await Product.findOne({
-  select: ['name', 'sku'],
-}).where({ id: 42 });
+const product = await productRepository
+  .findOne({
+    select: ['name', 'sku'],
+  })
+  .where({ id: 42 });
 ```
 
 ### Pool override
@@ -31,9 +32,11 @@ const product = await Product.findOne({
 Use an explicit connection pool:
 
 ```ts
-const product = await Product.findOne({
-  pool: poolOverride,
-}).where({ id: 42 });
+const product = await productRepository
+  .findOne({
+    pool: poolOverride,
+  })
+  .where({ id: 42 });
 ```
 
 ## find
@@ -41,7 +44,7 @@ const product = await Product.findOne({
 Returns an array of records:
 
 ```ts
-const products = await Product.find().where({ store: storeId });
+const products = await productRepository.find().where({ store: storeId });
 ```
 
 ## count
@@ -49,11 +52,17 @@ const products = await Product.find().where({ store: storeId });
 Returns the number of matching records:
 
 ```ts
-const count = await Product.count().where({
+const count = await productRepository.count().where({
   name: { like: 'Widget%' },
 });
 ```
 
+If you only need to know whether a match exists, use `count()` instead of `findOne()` — it performs better since it doesn't select or hydrate a row:
+
+```ts
+const exists = (await productRepository.count().where({ sku: 'ABC123' })) > 0;
+```
+
 ## Where operators
 
 ### String matching
@@ -68,10 +77,10 @@ All string operators use case-insensitive matching (`ILIKE`) and accept arrays f
 | `endsWith`   | Suffix match      | `%value`    |
 
 ```ts
-await Product.find().where({ name: { contains: 'widget' } });
+await productRepository.find().where({ name: { contains: 'widget' } });
 // SQL: WHERE name ILIKE '%widget%'
 
-await Product.find().where({ name: { startsWith: 'Pro' } });
+await productRepository.find().where({ name: { startsWith: 'Pro' } });
 // SQL: WHERE name ILIKE 'Pro%'
 ```
 
@@ -85,10 +94,10 @@ await Product.find().where({ name: { startsWith: 'Pro' } });
 | `>=`     | Greater than or equal |
 
 ```ts
-await Product.find().where({ price: { '>=': 100 } });
+await productRepository.find().where({ price: { '>=': 100 } });
 
 // Multiple operators on same field (AND)
-await Product.find().where({
+await productRepository.find().where({
   createdAt: { '>=': startDate, '<': endDate },
 });
 ```
@@ -103,13 +112,13 @@ await personRepository.find().where({ age: [22, 23, 24] });
 ### Negation (`!`)
 
 ```ts
-await Product.find().where({ status: { '!': 'discontinued' } });
+await productRepository.find().where({ status: { '!': 'discontinued' } });
 // SQL: WHERE status <> $1
 
-await Product.find().where({ status: { '!': ['a', 'b'] } });
+await productRepository.find().where({ status: { '!': ['a', 'b'] } });
 // SQL: WHERE status NOT IN ($1, $2)
 
-await Product.find().where({ deletedAt: { '!': null } });
+await productRepository.find().where({ deletedAt: { '!': null } });
 // SQL: WHERE deleted_at IS NOT NULL
 ```
 
@@ -122,7 +131,7 @@ await personRepository.find().where({
 // SQL: WHERE (first_name = $1) OR (last_name = $2)
 ```
 
-### Nested AND / OR
+### AND with nested OR
 
 ```ts
 await personRepository.find().where({
@@ -177,28 +186,11 @@ await repo.find().where({ bar: { theme: { '!': null } } });
 // SQL: WHERE "bar"->>'theme' IS NOT NULL
 ```
 
-Note that `IS NULL` on a JSONB property is true both when the key is missing from the object and when
-it is explicitly set to `null`. This matches PostgreSQL's behavior - the `->>` operator returns
-`NULL` in both cases.
-
-Properties set to `undefined` in a where clause are silently ignored (standard JavaScript -
-`undefined` values are dropped by `Object.entries`). To query for missing or null properties, always
-use `null` explicitly.
+Note that `IS NULL` on a JSONB property is true both when the key is missing from the object and when it is
+explicitly set to `null`. This matches PostgreSQL's behavior — the `->>` operator returns `NULL` in both cases.
 
-### String matching on JSON properties
-
-The same string operators available on regular columns work on JSONB properties:
-
-```ts
-await repo.find().where({ bar: { theme: { contains: 'dark' } } });
-// SQL: WHERE "bar"->>'theme' ILIKE '%dark%'
-
-await repo.find().where({ bar: { theme: { startsWith: 'mid' } } });
-// SQL: WHERE "bar"->>'theme' ILIKE 'mid%'
-
-await repo.find().where({ bar: { failure: { message: { contains: 'timeout' } } } });
-// SQL: WHERE "bar"->'failure'->>'message' ILIKE '%timeout%'
-```
+Properties set to `undefined` in a where clause are silently ignored (standard JavaScript — `undefined` values are
+dropped by `Object.entries`). To query for missing or null properties, always use `null` explicitly.
 
 ### JSONB containment
 
@@ -216,49 +208,51 @@ await repo.find().where({
 ### String syntax
 
 ```ts
-await Product.find().where({}).sort('name asc');
-await Product.find().where({}).sort('name asc, createdAt desc');
+await productRepository.find().where({}).sort('name asc');
+await productRepository.find().where({}).sort('name asc, createdAt desc');
 ```
 
 ### Object syntax
 
 ```ts
-await Product.find().where({}).sort({ name: 1 }); // ASC
-await Product.find().where({}).sort({ name: 1, createdAt: -1 }); // ASC, DESC
+await productRepository.find().where({}).sort({ name: 1 }); // ASC
+await productRepository.find().where({}).sort({ name: 1, createdAt: -1 }); // ASC, DESC
 ```
 
 ## Vector distance queries
 
-BigAl supports nearest-neighbor queries on `vector()` columns using pgvector. Four distance metrics
-are available: `cosine`, `l2`, `l1`, and `innerProduct`.
+BigAl supports nearest-neighbor queries on columns declared with `@column({ type: 'vector', dimensions: n })`,
+backed by the [pgvector](https://github.com/pgvector/pgvector) extension. Four distance metrics are
+available: `cosine`, `l2`, `l1`, and `innerProduct`. The `l1` metric requires pgvector >= 0.7.0.
+
+| Metric         | PostgreSQL operator | Description               |
+| -------------- | ------------------- | ------------------------- |
+| `cosine`       | `<=>`               | Cosine distance (default) |
+| `l2`           | `<->`               | Euclidean distance        |
+| `l1`           | `<+>`               | Manhattan distance        |
+| `innerProduct` | `<#>`               | Negative inner product    |
 
 ### Sorting by distance
 
 Use the `nearestTo` sort to order results by vector similarity:
 
 ```ts
-const similar = await documentRepo
+const similar = await documentRepository
   .find()
-  .where({})
+  .where({ title: { contains: 'biology' } })
   .sort({ embedding: { nearestTo: queryVector, metric: 'cosine' } })
   .limit(10);
+// SQL: ... WHERE "title" ILIKE $1 ORDER BY "embedding" <=> $2 LIMIT 10
 ```
 
-The `metric` option defaults to `'cosine'` if omitted.
-
-| Metric         | PostgreSQL operator | Description               |
-| -------------- | ------------------- | ------------------------- |
-| `cosine`       | `<=>`               | Cosine distance (default) |
-| `l2`           | `<->`               | Euclidean distance        |
-| `l1`           | `<+>`               | Manhattan distance        |
-| `innerProduct` | `<#>`               | Negative inner product    |
+The `metric` option defaults to `'cosine'` if omitted. An unknown metric throws a `QueryError`.
 
 ### Filtering by distance
 
 Combine `nearestTo` in the where clause with a distance threshold:
 
 ```ts
-const nearby = await documentRepo
+const nearby = await documentRepository
   .find()
   .where({
     embedding: {
@@ -269,6 +263,21 @@ const nearby = await documentRepo
   })
   .sort({ embedding: { nearestTo: queryVector, metric: 'cosine' } })
   .limit(10);
+// SQL: ... WHERE "embedding" <=> $1 < $2 ORDER BY "embedding" <=> $3 LIMIT 10
+```
+
+At least one `distance` bound is required in where clauses; multiple bounds are combined with `AND`
+(for example `distance: { '>': 0.1, '<': 0.5 }` finds a distance band). Vectors must be non-empty
+arrays of finite numbers.
+
+### Equality and writes
+
+Vector values round-trip as `number[]`. Where clauses compare whole vectors, and create/update
+serialize the array to pgvector's text format:
+
+```ts
+await documentRepository.create({ title: 'foo', embedding: [0.1, 0.2, 0.3] }); // Sends '[0.1,0.2,0.3]'
+await documentRepository.findOne({ embedding: queryVector }); // WHERE "embedding"=$1
 ```
 
 ## Pagination
@@ -276,7 +285,7 @@ const nearby = await documentRepo
 ### skip and limit
 
 ```ts
-await Product.find().where({}).skip(20).limit(10);
+await productRepository.find().where({}).skip(20).limit(10);
 ```
 
 ### paginate
@@ -284,7 +293,7 @@ await Product.find().where({}).skip(20).limit(10);
 ```ts
 const page = 2;
 const pageSize = 25;
-await Product.find().where({}).paginate(page, pageSize);
+await productRepository.find().where({}).paginate(page, pageSize);
 ```
 
 ### withCount
@@ -292,7 +301,7 @@ await Product.find().where({}).paginate(page, pageSize);
 Get paginated results with total count in a single query using `COUNT(*) OVER()`:
 
 ```ts
-const { results, totalCount } = await Product.find().where({ store: storeId }).sort('name').limit(10).skip(20).withCount();
+const { results, totalCount } = await productRepository.find().where({ store: storeId }).sort('name').limit(10).skip(20).withCount();
 
 const totalPages = Math.ceil(totalCount / 10);
 ```
@@ -303,7 +312,7 @@ PostgreSQL's `DISTINCT ON` returns one row per unique combination of columns:
 
 ```ts
 // Most recently created product per store
-const latest = await Product.find().distinctOn(['store']).sort('store').sort('createdAt desc');
+const latest = await productRepository.find().distinctOn(['store']).sort('store').sort('createdAt desc');
 ```
 
 Requirements:
@@ -311,49 +320,24 @@ Requirements:
 - `ORDER BY` is required and must start with the `DISTINCT ON` columns
 - Cannot be combined with `withCount()`
 
-## Global filters
-
-When a table defines named filters (see [Models > Global filters](/guide/models#global-filters)),
-they are automatically applied to every `find` and `findOne` query. Override them per query:
-
-```ts
-// Disable all filters for this query
-await Product.find().where({}).filters(false);
-
-// Disable a specific filter
-await Product.find().where({}).filters({ active: false });
-```
-
-Filters are not applied to `count()` queries.
-
-## toSQL()
-
-Inspect the generated SQL and parameters without executing the query:
-
-```ts
-const { sql, params } = Product.find()
-  .where({ name: { contains: 'widget' } })
-  .sort('name')
-  .toSQL();
-
-console.log(sql); // SELECT ... FROM "products" WHERE "name" ILIKE $1 ORDER BY ...
-console.log(params); // ['%widget%']
-```
-
-Available on `find`, `findOne`, `create`, `update`, and `destroy`. Useful for debugging, logging,
-and testing SQL generation.
-
 ## Populate
 
 Load related entities:
 
 ```ts
-const product = await Product.findOne()
+const product = await productRepository
+  .findOne()
   .where({ id: 42 })
   .populate('store', { select: ['name'] });
 
-// product.store is the full Store entity (not just the FK number)
+// product.store is the full Store entity
 console.log(product.store.name);
 ```
 
-All query results are plain objects - no `.toJSON()` conversion needed.
+## toJSON
+
+Return plain objects without class prototypes:
+
+```ts
+const product = await productRepository.findOne().where({ id: 42 }).toJSON();
+```

package/docs/guide/relationships.md

@@ -1,154 +1,188 @@
 ---
-description: Many-to-one, one-to-many, and many-to-many relationships with belongsTo and hasMany builders, QueryResult type narrowing, and populate options.
+description: Many-to-one, one-to-many, and many-to-many relationships with decorators, QueryResult type narrowing, and populate options.
 ---
 
 # Relationships
 
-BigAl supports three relationship patterns: many-to-one, one-to-many, and many-to-many. Relationships
-use string model name references by default. Model names are auto-derived from table names (e.g.,
-`products` becomes `Product`).
+BigAl supports three relationship patterns via the `@column` decorator: many-to-one, one-to-many, and many-to-many.
 
-## Many-to-one (belongsTo)
+## Many-to-one (model)
 
-Use `belongsTo` when this table holds the foreign key:
+Use `model` when the current entity holds the foreign key:
 
 ```ts
-import { belongsTo, table, serial, text, createdAt, updatedAt } from 'bigal';
-
-export const Product = table('products', {
-  id: serial().primaryKey(),
-  name: text().notNull(),
-  store: belongsTo('Store'),
-  createdAt: createdAt(),
-  updatedAt: updatedAt(),
-});
+import { column, Entity, primaryColumn, table } from 'bigal';
+import type { Store } from './Store';
+
+@table({ name: 'products' })
+export class Product extends Entity {
+  @primaryColumn({ type: 'integer' })
+  public id!: number;
+
+  @column({ type: 'string', required: true })
+  public name!: string;
+
+  @column({ model: () => 'Store', name: 'store_id' })
+  public store!: number | Store;
+}
 ```
 
-- The inferred select type for `store` is `number` (the FK value)
-- After `.populate('store')`, the type changes to the full Store entity
-- The FK column name is auto-derived as `snakeCase(propertyKey) + '_id'` (e.g., `store_id`)
-- Override the FK column name: `belongsTo('Store', { name: 'shop_id' })`
+- The property type is `number | Store` — foreign key when not populated, full entity after `.populate()`
+- Use `name: 'store_id'` when the database column differs from the property name
+- Reference the model by string name (`'Store'`) to avoid circular imports
+- Model names are case-insensitive
 
-## One-to-many (hasMany)
+## One-to-many (collection)
 
-Use `hasMany` on the inverse side:
+Use `collection` on the inverse side:
 
 ```ts
-import { table, hasMany, serial, text, createdAt, updatedAt } from 'bigal';
-
-export const Store = table('stores', {
-  id: serial().primaryKey(),
-  name: text(),
-  products: hasMany('Product').via('store'),
-  createdAt: createdAt(),
-  updatedAt: updatedAt(),
-});
+import { column, Entity, primaryColumn, table } from 'bigal';
+import type { Product } from './Product';
+
+@table({ name: 'stores' })
+export class Store extends Entity {
+  @primaryColumn({ type: 'integer' })
+  public id!: number;
+
+  @column({ type: 'string' })
+  public name?: string;
+
+  @column({ collection: () => 'Product', via: 'store' })
+  public products?: Product[];
+}
 ```
 
-- `.via('store')` references the property name on the related table (not the database column)
-- `hasMany` columns appear in `InferSelect` as optional `Record<string, unknown>[]` to support
-  populate. `QueryResult` strips them from results, so they only appear after `.populate()`
+- `via` references the property name on the related model (not the database column)
+- Collections **must** be optional (`?`) — they are only present after `.populate()`
 
 ## Many-to-many (through)
 
-Use `.through()` for relationships via a junction table:
+Use `through` for relationships that require a join table:
 
 ```ts
 // Product.ts
-export const Product = table('products', {
-  id: serial().primaryKey(),
-  name: text().notNull(),
-  categories: hasMany('Category').through('ProductCategory').via('product'),
-});
+@table({ name: 'products' })
+export class Product extends Entity {
+  @primaryColumn({ type: 'integer' })
+  public id!: number;
+
+  @column({ type: 'string', required: true })
+  public name!: string;
+
+  @column({
+    collection: () => 'Category',
+    through: () => 'ProductCategory',
+    via: 'product',
+  })
+  public categories?: Category[];
+}
 ```
 
 ```ts
 // Category.ts
-export const Category = table('categories', {
-  id: serial().primaryKey(),
-  name: text().notNull(),
-  products: hasMany('Product').through('ProductCategory').via('category'),
-});
+@table({ name: 'categories' })
+export class Category extends Entity {
+  @primaryColumn({ type: 'integer' })
+  public id!: number;
+
+  @column({ type: 'string', required: true })
+  public name!: string;
+
+  @column({
+    collection: () => 'Product',
+    through: () => 'ProductCategory',
+    via: 'category',
+  })
+  public products?: Product[];
+}
 ```
 
 ```ts
-// ProductCategory.ts (junction table)
-export const ProductCategory = table('product__category', {
-  id: serial().primaryKey(),
-  product: belongsTo('Product'),
-  category: belongsTo('Category'),
-  ordering: integer(),
-  isPrimary: boolean(),
-});
+// ProductCategory.ts (join table)
+@table({ name: 'product__category' })
+export class ProductCategory extends Entity {
+  @primaryColumn({ type: 'integer' })
+  public id!: number;
+
+  @column({ model: () => 'Product', name: 'product_id' })
+  public product!: number | Product;
+
+  @column({ model: () => 'Category', name: 'category_id' })
+  public category!: number | Category;
+}
 ```
 
-- `.through()` specifies the junction table model name
-- `.via()` references the property on the junction table that points back to this table
-- The junction table must have `belongsTo` relationships to both sides
+- `through` specifies the join table model
+- `via` references the property on the join table that points back to this entity
+- The join table must have `model` relationships to both sides
 
 ## Self-referencing relationships
 
-Models can reference themselves for hierarchical data. Use the model name string (auto-derived
-from the table name, or set via `modelName` option):
+Entities can reference themselves for hierarchical data:
 
 ```ts
-export const Category = table('categories', {
-  id: serial().primaryKey(),
-  name: text().notNull(),
-  parent: belongsTo('Category'),
-  children: hasMany('Category').via('parent'),
-});
-```
+@table({ name: 'categories' })
+export class Category extends Entity {
+  @primaryColumn({ type: 'integer' })
+  public id!: number;
+
+  @column({ type: 'string', required: true })
+  public name!: string;
 
-String references are resolved at `initialize()` time, so there is no circular import issue.
+  @column({ model: () => 'Category', name: 'parent_id' })
+  public parent?: number | Category | null;
+
+  @column({ collection: () => 'Category', via: 'parent' })
+  public children?: Category[];
+}
+```
 
 ## QueryResult type narrowing
 
-When you query entities, BigAl returns `QueryResult<T>` which narrows relationship fields
-automatically:
+When you query entities, BigAl returns `QueryResult<T>` which automatically narrows relationship fields:
 
 ```ts
-const product = await Product.findOne().where({ id: 1 });
+const product = await productRepository.findOne().where({ id: 1 });
 
-// product.store is `number`, not a union type
+// product.store is `number`, not `number | Store`
+// QueryResult narrows the union automatically
 console.log(product.store); // number (the foreign key ID)
 ```
 
 The narrowing rules:
 
-| InferSelect type                                   | QueryResult type     |
-| -------------------------------------------------- | -------------------- |
-| `number` (belongsTo FK)                            | `number`             |
-| `Record<string, unknown>[] \| undefined` (hasMany) | Stripped from result |
+| Entity property type      | QueryResult type     |
+| ------------------------- | -------------------- |
+| `number \| Store`         | `number`             |
+| `number \| Store \| null` | `number \| null`     |
+| `Product[]` (collection)  | Excluded from result |
 
 ### Using QueryResult in type definitions
 
-`QueryResult` accepts a `TableDefinition` directly - no need to manually call `InferSelect`:
+Use `Pick<QueryResult<T>, ...>` instead of `Pick<T, ...>` for derived types:
 
 ```ts
 import type { QueryResult } from 'bigal';
 
-// store is `number`, categories (hasMany) is stripped
-type ProductRow = QueryResult<typeof Product>;
+// Correct: store is `number`
+type ProductSummary = Pick<QueryResult<Product>, 'id' | 'name' | 'store'>;
 
-// Pick specific fields
-type ProductSummary = Pick<QueryResult<typeof Product>, 'id' | 'name' | 'store'>;
+// Wrong: store is `number | Store`
+type ProductSummaryWrong = Pick<Product, 'id' | 'name' | 'store'>;
 ```
 
-## Typed populate
+## QueryResultPopulated
 
-When using object-style `initialize({ models: { Product, Store } })`, populate results are fully
-typed. The full models map is threaded through repositories, so `.populate('store')` resolves to the
-related entity type rather than `Record<string, unknown>`.
+For type safety with populated relations:
 
 ```ts
-const product = await Product.findOne().where({ id: 1 }).populate('store');
+import type { QueryResultPopulated } from 'bigal';
 
-// product.store is typed as the full Store entity, not unknown
+// store is QueryResult<Store>
+type ProductWithStore = QueryResultPopulated<Product, 'store'>;
 ```
 
-Array-style `initialize({ models: [...] })` still works but does not provide typed populate results.
-
 ## Populate with junction table filtering
 
 For many-to-many relationships, you can filter and sort by columns on the junction table:
@@ -173,7 +207,8 @@ const compilation = await compilationRepository
 
 ## Best practices
 
-1. **Use `QueryResult<typeof Model>` for return types** - strips hasMany, narrows FK types
-2. **Use string references for model relationships** - avoids circular import issues
-3. **Use object-style `initialize()`** - enables typed populate results
-4. **All relationships are validated at startup** - `initialize()` throws if a referenced model is missing from the `models` object/array
+1. **Use `QueryResult<T>` for return types** — avoids union type ambiguity
+2. **Use string references for model names** — prevents circular imports
+3. **Mark collections as optional** — they are `undefined` unless populated
+4. **Avoid type assertions** — `QueryResult` narrows types automatically
+5. **Use `.toJSON()` for serializable results** — strips class prototypes