bigal 16.0.0-beta.2 → 16.0.0

package/docs/pnpm-workspace.yaml

@@ -0,0 +1,3 @@
+# Marks docs/ as a standalone pnpm project, separate from the library at the repo root.
+allowBuilds:
+  esbuild: true

package/docs/reference/api.md

@@ -1,5 +1,5 @@
 ---
-description: Complete API reference for BigAl - initialize(), table(), column builders, relationships, repository methods, query builder, and types.
+description: Complete API reference for BigAl — initialize(), Repository, ReadonlyRepository, query builder methods, subquery(), decorators, and types.
 ---
 
 # API Reference
@@ -8,279 +8,35 @@ All public exports from `bigal`.
 
 ## initialize()
 
-Creates a BigAl instance with typed repositories for all provided models.
-
-### Object-style models (recommended)
-
-Returns typed repositories directly via destructuring:
+Creates repositories for all provided models.
 
 ```ts
 import { initialize } from 'bigal';
 
-const { Product, Store } = initialize({
+const repos = initialize({
+  models: [Product, Store],
   pool,
   readonlyPool,
-  models: { Product, Store, Category, ProductCategory },
-  connections: {
-    audit: { pool: auditPool },
-  },
-  onQuery({ sql, params, duration, error, model, operation }) {
-    logger.debug({ sql, params, duration, model, operation });
-  },
-});
-```
-
-### Array-style models
-
-Returns an object with `getRepository()` and `getReadonlyRepository()` methods:
-
-```ts
-const bigal = initialize({
-  pool,
-  models: [Product, Store, Category, ProductCategory],
+  connections,
+  expose,
 });
-
-const Product = bigal.getRepository(Product);
-```
-
-**Parameters:**
-
-| Option         | Type                                       | Required | Description                                   |
-| -------------- | ------------------------------------------ | -------- | --------------------------------------------- |
-| `pool`         | `PoolLike`                                 | Yes      | Primary connection pool                       |
-| `readonlyPool` | `PoolLike`                                 | No       | Pool for read operations (defaults to `pool`) |
-| `models`       | `Record<string, TableDefinition>` or array | Yes      | All model definitions                         |
-| `connections`  | `Record<string, IConnection>`              | No       | Named connections for multi-database setups   |
-| `onQuery`      | `OnQueryCallback`                          | No       | Query observability callback                  |
-
-All relationships are validated at startup. If a `belongsTo` or `hasMany` references a model not
-included in `models`, `initialize()` throws immediately.
-
-## getRepository()
-
-Returns a typed read-write repository for a model.
-
-```ts
-const Product = bigal.getRepository(Product);
-// Type: IRepository<InferSelect<typeof Product.schema>>
-```
-
-Throws if the model was not included in `models`.
-
-## getReadonlyRepository()
-
-Returns a typed read-only repository for a model.
-
-```ts
-const ViewRepo = bigal.getReadonlyRepository(StoreSummary);
-// Type: IReadonlyRepository<InferSelect<typeof StoreSummary.schema>>
 ```
 
-## table()
-
-Creates a model with column metadata and inferred types. Exported as `defineTable` from the main
-`'bigal'` package to avoid naming conflicts.
-
-```ts
-import { defineTable as table, serial, text } from 'bigal';
-
-export const Product = table(
-  'products',
-  {
-    id: serial().primaryKey(),
-    name: text().notNull(),
-  },
-  {
-    schema: 'public',
-    readonly: false,
-    hooks: {
-      beforeCreate(v) {
-        return v;
-      },
-    },
-    filters: {
-      active: { isActive: true },
-    },
-  },
-);
-```
-
-**Parameters:**
-
-| Parameter   | Type               | Description                         |
-| ----------- | ------------------ | ----------------------------------- |
-| `tableName` | `string`           | Database table or view name         |
-| `schema`    | `SchemaDefinition` | Column and relationship definitions |
-| `options`   | `TableOptions`     | Optional table-level configuration  |
-
-**Returns:** `TableDefinition<TName, TSchema>` (frozen object)
-
-### TableOptions
-
-| Option       | Type                               | Description                                        |
-| ------------ | ---------------------------------- | -------------------------------------------------- |
-| `schema`     | `string`                           | PostgreSQL schema (default: `public`)              |
-| `readonly`   | `boolean`                          | If `true`, returns read-only repository            |
-| `connection` | `string`                           | Named connection key                               |
-| `modelName`  | `string`                           | Override auto-derived model name                   |
-| `hooks`      | `ModelHooks`                       | Lifecycle hooks                                    |
-| `filters`    | `Record<string, FilterDefinition>` | Named filters auto-applied to find/findOne queries |
-
-### TableDefinition
-
-The returned object exposes:
-
-| Property                | Type                               | Description                       |
-| ----------------------- | ---------------------------------- | --------------------------------- |
-| `tableName`             | `string`                           | Database table name               |
-| `modelName`             | `string`                           | Auto-derived or overridden name   |
-| `dbSchema`              | `string \| undefined`              | PostgreSQL schema                 |
-| `isReadonly`            | `boolean`                          | Whether this is a read-only model |
-| `connection`            | `string \| undefined`              | Named connection key              |
-| `schema`                | `SchemaDefinition`                 | The column definitions            |
-| `hooks`                 | `ModelHooks \| undefined`          | Lifecycle hooks                   |
-| `filters`               | `Record<string, ...> \| undefined` | Global filters                    |
-| `columns`               | `ColumnMetadata[]`                 | All column metadata               |
-| `primaryKeyColumn`      | `ColumnMetadata`                   | Primary key column metadata       |
-| `columnsByPropertyName` | `Record<string, ColumnMetadata>`   | Lookup by property name           |
-| `columnsByColumnName`   | `Record<string, ColumnMetadata>`   | Lookup by database column name    |
-
-## view()
-
-Defines a read-only model backed by a PostgreSQL view. Equivalent to
-`table(name, schema, { readonly: true, ...options })`.
-
-```ts
-import { view, serial, text, integer } from 'bigal';
-
-export const ProductSummary = view('product_summaries', {
-  id: serial().primaryKey(),
-  name: text().notNull(),
-  storeName: text().notNull(),
-  categoryCount: integer().notNull(),
-});
-```
-
-## Column builders
-
-All column builders accept an optional `{ name: 'column_name' }` options object. When omitted, the
-database column name is auto-derived from the property key using snakeCase conversion.
-
-### Chain methods
-
-| Method            | Description                                                         |
-| ----------------- | ------------------------------------------------------------------- |
-| `.notNull()`      | Removes `null` from the type                                        |
-| `.default(value)` | Makes column optional on insert                                     |
-| `.primaryKey()`   | Implies `.notNull()`, optional on insert                            |
-| `.unique()`       | UNIQUE constraint (no type-level effect)                            |
-| `.version()`      | Optimistic locking; implies `.notNull()`, auto-increments on update |
-
-### Builder functions
-
-| Function                 | PostgreSQL type  | TypeScript type     |
-| ------------------------ | ---------------- | ------------------- |
-| `serial()`               | SERIAL           | `number`            |
-| `bigserial()`            | BIGSERIAL        | `number`            |
-| `text<T>()`              | TEXT             | `T \| null`         |
-| `varchar<T>(options?)`   | VARCHAR(n)       | `T \| null`         |
-| `integer()`              | INTEGER          | `number \| null`    |
-| `bigint()`               | BIGINT           | `number \| null`    |
-| `smallint()`             | SMALLINT         | `number \| null`    |
-| `float()` / `real()`     | REAL             | `number \| null`    |
-| `double()`               | DOUBLE PRECISION | `number \| null`    |
-| `boolean()`              | BOOLEAN          | `boolean \| null`   |
-| `timestamp()`            | TIMESTAMP        | `Date \| null`      |
-| `timestamptz()`          | TIMESTAMPTZ      | `Date \| null`      |
-| `date()`                 | DATE             | `Date \| null`      |
-| `json<T>()`              | JSON             | `T \| null`         |
-| `jsonb<T>()`             | JSONB            | `T \| null`         |
-| `uuid()`                 | UUID             | `string \| null`    |
-| `bytea()`                | BYTEA            | `Buffer \| null`    |
-| `textArray()`            | TEXT[]           | `string[] \| null`  |
-| `integerArray()`         | INTEGER[]        | `number[] \| null`  |
-| `booleanArray()`         | BOOLEAN[]        | `boolean[] \| null` |
-| `vector({ dimensions })` | VECTOR(n)        | `number[] \| null`  |
-| `createdAt()`            | TIMESTAMPTZ      | `Date`              |
-| `updatedAt()`            | TIMESTAMPTZ      | `Date`              |
-
-`serial()` and `bigserial()` imply `.notNull()` and `.default()`.
-
-`createdAt()` defaults to column name `created_at`. `updatedAt()` defaults to `updated_at`.
-
-`vector()` requires the `dimensions` option. Requires the pgvector PostgreSQL extension.
-
-### VarcharOptions
-
-```ts
-interface VarcharOptions {
-  name?: string;
-  length?: number;
-}
-```
-
-### VectorOptions
-
-```ts
-interface VectorOptions {
-  name?: string;
-  dimensions: number;
-}
-```
-
-## Relationship builders
-
-### belongsTo()
-
-Defines a many-to-one relationship where this table holds the foreign key.
-
-```ts
-import { belongsTo } from 'bigal';
-
-store: belongsTo('Store'),
-store: belongsTo('Store', { name: 'shop_id' }),
-```
-
-**Parameters:**
-
-| Parameter   | Type                           | Description                                          |
-| ----------- | ------------------------------ | ---------------------------------------------------- |
-| `modelName` | `string`                       | Model name string (e.g., `'Store'`)                  |
-| `options`   | `string` or `{ name: string }` | FK column name (auto-derived as `snakeCase(key)_id`) |
-
-**Select type:** the FK type (typically `number`).
+**Parameters:** `InitializeOptions`
 
-**Insert type:** the FK type (required by default).
+| Option         | Type                          | Required | Description                                   |
+| -------------- | ----------------------------- | -------- | --------------------------------------------- |
+| `models`       | `EntityStatic<Entity>[]`      | Yes      | Model classes decorated with `@table()`       |
+| `pool`         | `PoolLike`                    | Yes      | Primary connection pool                       |
+| `readonlyPool` | `PoolLike`                    | No       | Pool for read operations (defaults to `pool`) |
+| `connections`  | `Record<string, IConnection>` | No       | Named connections for multi-database setups   |
+| `expose`       | `(repo, metadata) => void`    | No       | Callback invoked for each created repository  |
 
-### hasMany()
-
-Defines a one-to-many or many-to-many relationship.
-
-```ts
-import { hasMany } from 'bigal';
-
-// One-to-many
-products: hasMany('Product').via('store'),
-
-// Many-to-many
-categories: hasMany('Category')
-  .through('ProductCategory')
-  .via('product'),
-```
-
-**Chain methods:**
-
-| Method               | Description                               |
-| -------------------- | ----------------------------------------- |
-| `.via(propertyName)` | Property on the related table with the FK |
-| `.through(modelRef)` | Junction table for many-to-many           |
-
-`hasMany` columns appear in `InferSelect` as optional `Record<string, unknown>[]` to support
-populate. `QueryResult` strips them from query results, so they only appear after `.populate()`.
+**Returns:** `Record<string, IReadonlyRepository<Entity> | IRepository<Entity>>`
 
 ## Repository
 
-Full CRUD repository returned by `getRepository()` or object-style destructuring.
+Full CRUD repository returned by `initialize()` for non-readonly models.
 
 ### find()
 
@@ -304,7 +60,7 @@ Returns a query builder for a single record or `null`. Options: `{ select?, pool
 repository.count(options?): CountQuery<T>
 ```
 
-Returns a query builder that resolves to a number. Options: `{ pool? }`.
+Returns a query builder that resolves to a number. Options: `{ pool? }`. Prefer this over `findOne()` for existence checks — it performs better since it doesn't select or hydrate a row.
 
 ### create()
 
@@ -315,6 +71,8 @@ repository.create(values[], options?): Promise<QueryResult<T>[]>
 
 Insert one or multiple records. Options: `{ returnRecords?, returnSelect?, onConflict? }`.
 
+An array inserts in a single statement. Prefer this over calling `create()` in a loop, which costs one round trip per record.
+
 ### update()
 
 ```ts
@@ -333,48 +91,25 @@ Delete matching records. Options: `{ returnRecords?, returnSelect? }`.
 
 ## ReadonlyRepository
 
-Read-only repository returned by `getReadonlyRepository()` or for models with `readonly: true`.
-Exposes `find()`, `findOne()`, and `count()` only.
+Read-only repository returned for models with `readonly: true`. Exposes `find()`, `findOne()`, and `count()` only.
 
 ## Query builder methods
 
 All query types support fluent chaining. Each method returns a new immutable instance.
 
-| Method                             | Available on         | Description                       |
-| ---------------------------------- | -------------------- | --------------------------------- |
-| `.where(query)`                    | find, findOne, count | Filter records                    |
-| `.sort(value)`                     | find, findOne        | Order results                     |
-| `.limit(n)`                        | find                 | Limit rows returned               |
-| `.skip(n)`                         | find                 | Skip rows                         |
-| `.paginate(page, pageSize)`        | find                 | Shorthand for skip + limit        |
-| `.withCount()`                     | find                 | Return `{ results, totalCount }`  |
-| `.populate(relation, options?)`    | find, findOne        | Load related entities             |
-| `.join(relation, alias?, on?)`     | find, findOne        | INNER JOIN                        |
-| `.leftJoin(relation, alias?, on?)` | find, findOne        | LEFT JOIN                         |
-| `.distinctOn(columns)`             | find                 | PostgreSQL DISTINCT ON            |
-| `.filters(value)`                  | find, findOne        | Override global filters           |
-| `.toSQL()`                         | all operations       | Get generated SQL without running |
-
-### toSQL()
-
-Returns the generated SQL and parameters without executing the query. Available on `find`, `findOne`,
-`create`, `update`, and `destroy`:
-
-```ts
-const { sql, params } = Product.find().where({ name: 'Widget' }).toSQL();
-```
-
-### filters()
-
-Override global filters defined on the table:
-
-```ts
-// Disable all filters
-Product.find().where({}).filters(false);
-
-// Disable a specific filter
-Product.find().where({}).filters({ active: false });
-```
+| Method                             | Available on         | Description                      |
+| ---------------------------------- | -------------------- | -------------------------------- |
+| `.where(query)`                    | find, findOne, count | Filter records                   |
+| `.sort(value)`                     | find, findOne        | Order results                    |
+| `.limit(n)`                        | find                 | Limit rows returned              |
+| `.skip(n)`                         | find                 | Skip rows                        |
+| `.paginate(page, pageSize)`        | find                 | Shorthand for skip + limit       |
+| `.withCount()`                     | find                 | Return `{ results, totalCount }` |
+| `.populate(relation, options?)`    | find, findOne        | Load related entities            |
+| `.join(relation, alias?, on?)`     | find, findOne        | INNER JOIN                       |
+| `.leftJoin(relation, alias?, on?)` | find, findOne        | LEFT JOIN                        |
+| `.distinctOn(columns)`             | find                 | PostgreSQL DISTINCT ON           |
+| `.toJSON()`                        | find, findOne        | Return plain objects             |
 
 ## subquery()
 
@@ -384,93 +119,71 @@ import { subquery } from 'bigal';
 const sub = subquery(repository);
 ```
 
-Returns a `SubqueryBuilder` with methods: `select()`, `where()`, `sort()`, `limit()`, `groupBy()`,
-`having()`, `distinctOn()`.
+Returns a `SubqueryBuilder` with methods: `select()`, `where()`, `sort()`, `limit()`, `groupBy()`, `having()`, `distinctOn()`.
 
-Scalar aggregate shortcuts: `sub.count()`, `sub.sum(col)`, `sub.avg(col)`, `sub.max(col)`,
-`sub.min(col)`.
+Scalar aggregate shortcuts: `sub.count()`, `sub.sum(col)`, `sub.avg(col)`, `sub.max(col)`, `sub.min(col)`.
 
-## Types
+## Decorators
 
-### Repository\<T\>
+### @table(options)
 
-Type alias for a typed read-write repository. Accepts `typeof YourTableDef`:
+Binds a class to a database table or view.
 
-```ts
-import type { Repository } from 'bigal';
+| Option       | Type      | Description                            |
+| ------------ | --------- | -------------------------------------- |
+| `name`       | `string`  | Table or view name                     |
+| `schema`     | `string`  | PostgreSQL schema (default: `public`)  |
+| `readonly`   | `boolean` | Returns `ReadonlyRepository` if `true` |
+| `connection` | `string`  | Named connection key                   |
 
-function process(repo: Repository<typeof Product>) {
-  /* ... */
-}
-```
+### @primaryColumn(options)
 
-### ReadonlyRepository\<T\>
+Marks the primary key. Options: `{ type }`.
 
-Type alias for a typed read-only repository:
+### @column(options)
 
-```ts
-import type { ReadonlyRepository } from 'bigal';
+Defines a column. See [Models > Column options](/guide/models#column-options) for all options.
+Vector columns are declared with `{ type: 'vector', dimensions: n }` (`dimensions` is informational —
+BigAl does not issue DDL).
 
-function read(repo: ReadonlyRepository<typeof ProductSummary>) {
-  /* ... */
-}
-```
+### @createDateColumn()
 
-### InferSelect\<TSchema\>
+Auto-set on insert.
 
-Mapped type that extracts the row type from a schema definition:
+### @updateDateColumn()
 
-```ts
-type ProductRow = InferSelect<(typeof Product)['schema']>;
-```
+Auto-set on update.
 
-### InferInsert\<TSchema\>
+### @versionColumn()
 
-Mapped type that extracts the insert parameter type from a schema definition:
+Auto-incrementing version for optimistic locking.
 
-```ts
-type ProductInsert = InferInsert<(typeof Product)['schema']>;
-```
+## Types
 
-### ModelHooks\<TInsert, TSelect\>
+### Entity
 
-```ts
-interface ModelHooks<TInsert, TSelect = TInsert> {
-  beforeCreate?: (values: TInsert) => Promise<TInsert> | TInsert;
-  afterCreate?: (result: TSelect) => Promise<void> | void;
-  beforeUpdate?: (values: Partial<TInsert>) => Partial<TInsert> | Promise<Partial<TInsert>>;
-  afterUpdate?: (result: TSelect) => Promise<void> | void;
-  beforeDestroy?: (where: Record<string, unknown>) => Promise<Record<string, unknown>> | Record<string, unknown>;
-  afterDestroy?: (result: { rowCount: number }) => Promise<void> | void;
-  afterFind?: (results: TSelect[]) => Promise<TSelect[]> | TSelect[];
-}
-```
+Base class for all models.
 
-### FilterDefinition
+### NotEntity\<T\>
 
-```ts
-type FilterDefinition = (() => Record<string, unknown>) | Record<string, unknown>;
-```
+Wrapper type for JSON column objects that have an `id` field. Prevents BigAl's type system from treating them as entities.
 
-A static where clause object or a function that returns one dynamically.
+### QueryResult\<T\>
 
-### OnQueryCallback
+Narrows relationship fields from union types to foreign key types. See [Relationships > QueryResult](/guide/relationships#queryresult-type-narrowing).
 
-```ts
-type OnQueryCallback = (event: OnQueryEvent) => void;
-```
+### QueryResultPopulated\<T, K\>
 
-### OnQueryEvent
+Type for entities with specific relationships populated.
+
+### TypedAggregateExpression\<Alias\>
+
+Return type annotation for aggregate callbacks that enables type-safe sorting on subquery join columns.
+
+### VectorDistanceMetric
 
 ```ts
-interface OnQueryEvent {
-  sql: string;
-  params: readonly unknown[];
-  duration: number;
-  error?: Error;
-  model: string;
-  operation: 'count' | 'create' | 'destroy' | 'find' | 'findOne' | 'update';
-}
+type VectorDistanceMetric = 'cosine' | 'innerProduct' | 'l1' | 'l2';
 ```
 
 ### VectorDistanceSort
@@ -478,42 +191,31 @@ interface OnQueryEvent {
 ```ts
 interface VectorDistanceSort {
   nearestTo: number[];
-  metric?: 'cosine' | 'innerProduct' | 'l1' | 'l2';
+  metric?: VectorDistanceMetric;
 }
 ```
 
-Used in `.sort()` for nearest-neighbor queries on vector columns.
+Used in `.sort()` for nearest-neighbor queries on vector columns. See
+[Querying > Vector distance queries](/guide/querying#vector-distance-queries).
 
-### VectorDistanceMetric
-
-```ts
-type VectorDistanceMetric = 'cosine' | 'innerProduct' | 'l1' | 'l2';
-```
-
-### QueryResult\<T\>
-
-Produces the row type for query results. Accepts a `TableDefinition` directly or a row type.
-Strips hasMany collections (which appear in `InferSelect` as optional arrays) and narrows
-belongsTo FK types:
+### VectorDistanceConstraint
 
 ```ts
-// From a TableDefinition - strips hasMany, narrows FKs
-type ProductRow = QueryResult<typeof Product>;
-
-// From a row type - passthrough
-type Row = QueryResult<{ id: number; name: string }>;
+interface VectorDistanceConstraint {
+  nearestTo: number[];
+  metric?: VectorDistanceMetric;
+  distance: Partial<Record<'<' | '<=' | '>' | '>=', number>>;
+}
 ```
 
-See [Relationships > QueryResult](/guide/relationships#queryresult-type-narrowing).
-
-### TypedAggregateExpression\<Alias\>
-
-Return type annotation for aggregate callbacks that enables type-safe sorting on subquery join columns.
+Used in where clauses to filter vector columns by distance threshold. At least one `distance` bound is
+required (pgvector distance operators return a number, so a bare distance expression is not a valid
+where clause); multiple bounds are combined with `AND`. To order by distance without filtering, use
+`sort()` with `nearestTo` instead.
 
 ### PoolLike
 
-Interface for compatible connection pools. Supported: `postgres-pool`, `pg`,
-`@neondatabase/serverless`.
+Interface for compatible connection pools. Supported: `postgres-pool`, `pg`, `@neondatabase/serverless`.
 
 ### IConnection