bigal 16.0.0-beta.2 → 16.0.0

package/docs/guide/models.md

@@ -1,486 +1,187 @@
 ---
-description: Define models with the table() function and PostgreSQL-native column builders for type-safe schema definitions.
+description: Define PostgreSQL tables as TypeScript classes with decorators for columns, primary keys, relationships, and automatic timestamps.
 ---
 
 # Models
 
-Models define the shape of your PostgreSQL tables. Each model is created with the `table()` function and
-a set of column builders that map directly to PostgreSQL column types. Types are inferred from the schema
-definition - no separate interfaces required.
+Models map TypeScript classes to PostgreSQL tables. Every model extends `Entity` and uses decorators for table and column configuration.
 
-## Defining a model
+## Table decorator
 
-Use `table()` (exported as `defineTable` from `'bigal'`) to create a model:
+Use `@table()` to bind a class to a database table:
 
 ```ts
-import { defineTable as table, serial, text, integer, boolean, createdAt, updatedAt } from 'bigal';
-
-export const Product = table('products', {
-  id: serial().primaryKey(),
-  name: text().notNull(),
-  priceCents: integer().notNull(),
-  isActive: boolean().notNull().default(true),
-  createdAt: createdAt(),
-  updatedAt: updatedAt(),
-});
-```
-
-The first argument is the database table name. The second is an object mapping property names to column
-builders. Column builders take no arguments by default - the database column name is auto-derived from
-the property key using snakeCase (e.g., `priceCents` becomes `price_cents`).
-
-### Auto-derived names
-
-BigAl automatically derives two names from your definitions:
-
-- **Column names** - property keys are converted to snake_case for the database column name.
-  `priceCents` becomes `price_cents`, `isActive` becomes `is_active`.
-- **Model names** - the table name is singularized and PascalCased for relationship lookups.
-  `products` becomes `Product`, `product__category` becomes `ProductCategory`.
-
-Override either when the convention does not match:
+import { table, Entity } from 'bigal';
 
-```ts
-// Override column name
-aliases: textArray({ name: 'alias_names' }).default([]),
-
-// Override model name
-const Product = table('items', { /* ... */ }, { modelName: 'Product' });
+@table({ name: 'products' })
+export class Product extends Entity {
+  // columns go here
+}
 ```
 
-### Table options
-
-Pass a third argument for additional options:
-
-```ts
-const AuditLog = table(
-  'audit_logs',
-  {
-    /* columns */
-  },
-  {
-    schema: 'audit',
-    readonly: true,
-    connection: 'audit',
-  },
-);
-```
+Options:
 
 | Option       | Type      | Description                                              |
 | ------------ | --------- | -------------------------------------------------------- |
+| `name`       | `string`  | Database table or view name                              |
 | `schema`     | `string`  | PostgreSQL schema (default: `public`)                    |
-| `readonly`   | `boolean` | If `true`, `initialize()` returns a read-only repository |
+| `readonly`   | `boolean` | If `true`, `initialize()` returns a `ReadonlyRepository` |
 | `connection` | `string`  | Named connection key (for multi-database setups)         |
-| `modelName`  | `string`  | Override auto-derived model name                         |
-| `hooks`      | `object`  | Lifecycle hooks (see [Hooks](#hooks))                    |
-| `filters`    | `object`  | Global filters (see [Global filters](#global-filters))   |
 
-## Column types
+## Column decorators
 
-Each builder maps to a PostgreSQL column type. All columns are nullable by default - use `.notNull()`
-to make them required. Column builders take no arguments; pass `{ name: 'custom_name' }` only when the
-auto-derived snake_case name does not match your database column.
+### `@primaryColumn()`
 
-### String types
+Marks the primary key column:
 
 ```ts
-import { text, varchar, uuid } from 'bigal';
-
-name: text(),                                 // TEXT - string | null
-sku: varchar({ length: 100 }),                // VARCHAR(100) - string | null
-externalId: uuid(),                           // UUID - string | null
-status: text<'active' | 'inactive'>(),        // TEXT - 'active' | 'inactive' | null
-role: varchar<'admin' | 'user'>({ length: 50 }).notNull(), // VARCHAR(50) - 'admin' | 'user'
-```
+import { primaryColumn } from 'bigal';
 
-`text()` and `varchar()` accept an optional generic to narrow the type to a string literal union.
-This is useful for columns that store enum-like values.
-
-### Numeric types
-
-```ts
-import { serial, bigserial, integer, bigint, smallint, float, double } from 'bigal';
-
-id: serial().primaryKey(),                    // SERIAL - number (notNull + default implied)
-bigId: bigserial(),                           // BIGSERIAL - number (notNull + default implied)
-quantity: integer(),                          // INTEGER - number | null
-views: bigint(),                              // BIGINT - number | null
-rank: smallint(),                             // SMALLINT - number | null
-score: float(),                               // REAL - number | null
-precise: double(),                            // DOUBLE PRECISION - number | null
+@primaryColumn({ type: 'integer' })
+public id!: number;
 ```
 
-`serial()` and `bigserial()` automatically imply `.notNull()` and `.default()`. They are always
-`number` on select and optional on insert.
+### `@column()`
 
-### Boolean
+Defines a regular column:
 
 ```ts
-import { boolean } from 'bigal';
-
-isActive: boolean(),                                       // BOOLEAN -- boolean | null
-isPublished: boolean().notNull(),                          // BOOLEAN -- boolean
-isArchived: boolean().notNull().default(false),            // BOOLEAN -- boolean (optional on insert)
-```
-
-### Date and time
-
-```ts
-import { date, timestamp, timestamptz, createdAt, updatedAt } from 'bigal';
-
-birthDate: date(),                            // DATE -- Date | null
-occurredAt: timestamp(),                      // TIMESTAMP -- Date | null
-scheduledFor: timestamptz(),                  // TIMESTAMPTZ -- Date | null
-createdAt: createdAt(),                       // TIMESTAMPTZ -- Date (notNull, auto-set on insert)
-updatedAt: updatedAt(),                       // TIMESTAMPTZ -- Date (notNull, auto-set on insert/update)
-```
-
-`createdAt()` and `updatedAt()` default to column names `created_at` and `updated_at`. Pass a custom
-name if needed: `createdAt({ name: 'creation_time' })`.
-
-### JSON
+import { column } from 'bigal';
 
-```ts
-import { json, jsonb } from 'bigal';
+@column({ type: 'string', required: true })
+public name!: string;
 
-settings: json<{ theme: string }>(),                      // JSON -- { theme: string } | null
-metadata: jsonb<{ color?: string }>(),                     // JSONB -- { color?: string } | null
+@column({ type: 'string' })
+public sku?: string;
 ```
 
-The generic parameter controls the TypeScript type. If omitted, it defaults to
-`Record<string, unknown>`.
+### Vector (pgvector)
 
-### Binary
+Declare a `VECTOR(n)` column with `type: 'vector'`. Values are `number[] | null`:
 
 ```ts
-import { bytea } from 'bigal';
+import { column } from 'bigal';
 
-data: bytea(),                                // BYTEA -- Buffer | null
+@column({ type: 'vector', dimensions: 1536 })
+public embedding?: number[];
 ```
 
-### Array types
-
-```ts
-import { textArray, integerArray, booleanArray } from 'bigal';
+Requires the [pgvector](https://github.com/pgvector/pgvector) extension. The `dimensions` option is
+informational — BigAl does not issue DDL. See
+[Querying > Vector distance queries](/guide/querying#vector-distance-queries) for sorting and
+filtering by similarity.
 
-tags: textArray(),                            // TEXT[] -- string[] | null
-scores: integerArray(),                       // INTEGER[] -- number[] | null
-flags: booleanArray(),                        // BOOLEAN[] -- boolean[] | null
-```
+### `@createDateColumn()`
 
-### Vector (pgvector)
+Automatically set on insert:
 
 ```ts
-import { vector } from 'bigal';
-
-embedding: vector({ dimensions: 1536 }),      // VECTOR(1536) -- number[] | null
-```
-
-The `dimensions` option is required. See [Querying > Vector distance](/guide/querying#vector-distance-queries)
-for sorting and filtering by similarity.
+import { createDateColumn } from 'bigal';
 
-## Column modifiers
-
-Chain methods on any column builder to set constraints. Each method returns the builder, so chains
-compose naturally.
-
-### .notNull()
-
-Removes `null` from the TypeScript type. Maps to a `NOT NULL` constraint.
-
-```ts
-name: text().notNull(),   // string (not string | null)
+@createDateColumn()
+public createdAt!: Date;
 ```
 
-### .default(value)
+### `@updateDateColumn()`
 
-Makes the column optional on insert. The value is used as the TypeScript default hint.
+Automatically set on update:
 
 ```ts
-isActive: boolean().notNull().default(true),               // boolean, optional on insert
-aliases: textArray().default([]),                           // string[] | null, optional on insert
-```
+import { updateDateColumn } from 'bigal';
 
-### .primaryKey()
-
-Marks the column as the primary key. Implies `.notNull()` and makes the column optional on insert
-(the database assigns the value).
-
-```ts
-id: serial().primaryKey(),                    // number, optional on insert
-id: uuid().primaryKey(),                      // string, optional on insert
+@updateDateColumn()
+public updatedAt!: Date;
 ```
 
-### .unique()
+### `@versionColumn()`
 
-Adds a UNIQUE constraint. No effect on the TypeScript type.
+Auto-incrementing version for optimistic locking:
 
 ```ts
-email: text().notNull().unique(),             // string, must be unique
-```
-
-### .version()
-
-Marks the column for optimistic locking. Implies `.notNull()`. BigAl automatically increments the
-value on each update.
+import { versionColumn } from 'bigal';
 
-```ts
-revision: integer().version(),               // number, auto-incremented on update
+@versionColumn()
+public version!: number;
 ```
 
-### Chaining
-
-Modifiers compose in any order:
-
-```ts
-email: text().notNull().unique(),
-isActive: boolean().notNull().default(true),
-score: integer().default(0),
-```
+## Column options
 
-## Complete column reference
-
-| Builder                  | PostgreSQL type  | TypeScript type     | Notes                                   |
-| ------------------------ | ---------------- | ------------------- | --------------------------------------- |
-| `serial()`               | SERIAL           | `number`            | notNull + default implied               |
-| `bigserial()`            | BIGSERIAL        | `number`            | notNull + default implied               |
-| `text<T>()`              | TEXT             | `T \| null`         | Defaults to `string`; narrow with union |
-| `varchar<T>({ length })` | VARCHAR(n)       | `T \| null`         | Defaults to `string`; narrow with union |
-| `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`         | Defaults to `Record<string, unknown>`   |
-| `jsonb<T>()`             | JSONB            | `T \| null`         | Defaults to `Record<string, unknown>`   |
-| `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`  | Requires pgvector extension             |
-| `createdAt()`            | TIMESTAMPTZ      | `Date`              | notNull, auto-set on insert             |
-| `updatedAt()`            | TIMESTAMPTZ      | `Date`              | notNull, auto-set on insert/update      |
+| Option       | Type           | Description                                                                                                                                                         |
+| ------------ | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `type`       | `string`       | Column type: `'string'`, `'integer'`, `'float'`, `'boolean'`, `'date'`, `'datetime'`, `'json'`, `'string[]'`, `'integer[]'`, `'float[]'`, `'boolean[]'`, `'vector'` |
+| `name`       | `string`       | Database column name (if different from property name)                                                                                                              |
+| `required`   | `boolean`      | If `true`, value must not be null                                                                                                                                   |
+| `defaultsTo` | `any`          | Default value                                                                                                                                                       |
+| `dimensions` | `number`       | Number of dimensions for `'vector'` columns. Informational only — BigAl does not issue DDL                                                                          |
+| `model`      | `() => string` | Foreign key relationship (many-to-one)                                                                                                                              |
+| `collection` | `() => string` | Inverse relationship (one-to-many or many-to-many)                                                                                                                  |
+| `through`    | `() => string` | Join table for many-to-many                                                                                                                                         |
+| `via`        | `string`       | Property on related model that holds the foreign key                                                                                                                |
 
 ## Relationships
 
-### Many-to-one (belongsTo)
-
-Use `belongsTo` when this table holds the foreign key:
+### Many-to-one
 
-```ts
-import { belongsTo } from 'bigal';
-
-store: belongsTo('Store'),
-```
-
-The argument is the model name of the related table. The FK column name is auto-derived as
-`snakeCase(propertyKey) + '_id'` (e.g., `store` becomes `store_id`).
-
-Override the FK column name when the convention does not match:
+Use `model` when the current entity holds the foreign key:
 
 ```ts
-store: belongsTo('Store', { name: 'shop_id' }),
-```
+import { column, Entity, primaryColumn, table } from 'bigal';
+import type { Store } from './Store';
 
-In the inferred select type, a `belongsTo` column is typed as the FK value (typically `number`). After
-`.populate('store')`, the type changes to the full related entity.
+@table({ name: 'products' })
+export class Product extends Entity {
+  @primaryColumn({ type: 'integer' })
+  public id!: number;
 
-### One-to-many (hasMany)
-
-Use `hasMany` for the inverse side of a relationship:
-
-```ts
-import { hasMany } from 'bigal';
-
-products: hasMany('Product').via('store'),
+  @column({ model: () => 'Store', name: 'store_id' })
+  public store!: number | Store;
+}
 ```
 
-`.via()` specifies the property name on the related table that holds the foreign key back to this
-table.
+The property type is `number | Store` — it holds the foreign key when not populated, or the full entity after `.populate()`.
 
-### Many-to-many (hasMany with through)
+### One-to-many
 
-Use `.through()` for relationships via a junction table:
+Use `collection` on the inverse side:
 
 ```ts
-categories: hasMany('Category')
-  .through('ProductCategory')
-  .via('product'),
+@column({ collection: () => 'Product', via: 'store' })
+public products?: Product[];
 ```
 
-`hasMany` columns appear in `InferSelect` as optional `Record<string, unknown>[]` to support
-populate. `QueryResult` strips them from results, so they only appear after `.populate()`.
-They are excluded from the insert type entirely.
-
-See [Relationships](/guide/relationships) for complete examples.
+Collections **must** be optional (`?`) since they are only present after `.populate()`.
 
-## Shared columns
+### Many-to-many
 
-Extract a shared base only for columns that appear in every model (typically `id` + timestamps).
-Domain-specific columns like relationships should stay inline in each model.
+Use `collection` with `through` for join tables:
 
 ```ts
-const modelBase = {
-  id: serial().primaryKey(),
-  createdAt: createdAt(),
-  updatedAt: updatedAt(),
-};
-
-export const Product = table('products', {
-  ...modelBase,
-  name: text().notNull(),
-  store: belongsTo('Store'),
-});
-
-export const Store = table('stores', {
-  ...modelBase,
-  name: text(),
-});
+@column({
+  collection: () => 'Category',
+  through: () => 'ProductCategory',
+  via: 'product',
+})
+public categories?: Category[];
 ```
 
-## Type inference
+See [Relationships](/guide/relationships) for complete examples including join tables and self-referencing models.
 
-Use `QueryResult` to extract the row type from a model, and `InferInsert` for insert parameters:
+## Entity base class
 
-```ts
-import type { QueryResult, InferInsert } from 'bigal';
-
-type ProductRow = QueryResult<typeof Product>;
-// { id: number; name: string; priceCents: number; isActive: boolean;
-//   store: number; metadata: { color?: string } | null; createdAt: Date; updatedAt: Date }
-// hasMany collections (categories) are stripped by QueryResult
-
-type ProductInsert = InferInsert<(typeof Product)['schema']>;
-// { name: string; priceCents: number; store: number;  <-- required
-//   id?: number; isActive?: boolean;                   <-- optional (has default or primary key)
-//   metadata?: { color?: string } | null; }            <-- optional (nullable)
-```
+All models extend `Entity`, which provides no properties by itself — it serves as a marker for BigAl's type system to distinguish ORM entities from plain objects.
 
-### Repository and ReadonlyRepository type aliases
+## NotEntity\<T\>
 
-When you need to annotate a function parameter or variable with a repository type, use the
-`Repository` and `ReadonlyRepository` type aliases:
+If a JSON column contains objects with an `id` field, TypeScript may mistake them for BigAl entities. Wrap the type with `NotEntity<T>`:
 
 ```ts
-import type { Repository, ReadonlyRepository } from 'bigal';
-
-function processProducts(repo: Repository<typeof Product>) {
-  return repo.find().where({ name: { contains: 'widget' } });
-}
+import type { NotEntity } from 'bigal';
 
-function readSummary(repo: ReadonlyRepository<typeof StoreSummary>) {
-  return repo.findOne().where({ id: 1 });
+interface IMyJsonType {
+  id: string;
+  foo: string;
 }
-```
-
-These accept `typeof YourTableDef` and resolve to the correctly typed `IRepository` or
-`IReadonlyRepository`.
-
-### Insert type rules
-
-Columns are **required** on insert when they are `.notNull()` and have no default, are not a primary
-key, and are not auto-set.
-
-Columns are **optional** on insert when any of the following is true:
-
-- Nullable (no `.notNull()`)
-- Has a `.default()` value
-- Is a `.primaryKey()`
-- Is auto-set (`createdAt()`, `updatedAt()`)
-
-`hasMany` columns are excluded from the insert type entirely.
-
-## Hooks
-
-Define lifecycle hooks in the third argument to `table()`:
-
-```ts
-export const Product = table(
-  'products',
-  {
-    id: serial().primaryKey(),
-    name: text().notNull(),
-    slug: text().notNull(),
-  },
-  {
-    hooks: {
-      beforeCreate(values) {
-        return { ...values, slug: slugify(values.name) };
-      },
-      afterCreate(result) {
-        audit.log('product.created', result.id);
-      },
-      beforeUpdate(values) {
-        if (values.name) {
-          return { ...values, slug: slugify(values.name) };
-        }
-        return values;
-      },
-      afterUpdate(result) {
-        audit.log('product.updated', result.id);
-      },
-      beforeDestroy(where) {
-        return where;
-      },
-      afterDestroy({ rowCount }) {
-        audit.log('product.destroyed', rowCount);
-      },
-      afterFind(results) {
-        return results;
-      },
-    },
-  },
-);
-```
 
-| Hook            | Called          | Receives               | Returns                |
-| --------------- | --------------- | ---------------------- | ---------------------- |
-| `beforeCreate`  | Before `INSERT` | Insert values          | Modified insert values |
-| `afterCreate`   | After `INSERT`  | Created record         | void                   |
-| `beforeUpdate`  | Before `UPDATE` | Partial update values  | Modified update values |
-| `afterUpdate`   | After `UPDATE`  | Updated record         | void                   |
-| `beforeDestroy` | Before `DELETE` | Where clause object    | Modified where clause  |
-| `afterDestroy`  | After `DELETE`  | `{ rowCount: number }` | void                   |
-| `afterFind`     | After `SELECT`  | Array of results       | Modified results array |
-
-All hook parameters are fully typed based on the schema definition. Hooks can be synchronous or
-return a Promise.
-
-## Global filters
-
-Define named filters that are automatically applied to every `find` and `findOne` query:
-
-```ts
-const Product = table(
-  'products',
-  {
-    /* columns */
-  },
-  {
-    filters: {
-      active: { isActive: true },
-      notDeleted: () => ({ deletedAt: null }),
-    },
-  },
-);
-```
-
-Filters can be static objects or functions that return a where clause dynamically. They are merged
-into every query's WHERE clause.
-
-Override filters per query:
-
-```ts
-// Disable all filters
-await Product.find().where({}).filters(false);
-
-// Disable a specific filter
-await Product.find().where({}).filters({ active: false });
+@column({ type: 'json' })
+public metadata?: NotEntity<IMyJsonType>;
 ```
-
-See [Querying > Global filters](/guide/querying#global-filters) for more details.