bigal 16.0.0-beta.3 → 16.0.0

package/docs/guide/subqueries-and-joins.md

@@ -13,7 +13,7 @@ Use the `subquery()` function:
 ```ts
 import { subquery } from 'bigal';
 
-const activeStores = subquery(Store).select(['id']).where({ isActive: true });
+const activeStores = subquery(storeRepository).select(['id']).where({ isActive: true });
 ```
 
 `SubqueryBuilder` methods:
@@ -31,16 +31,16 @@ const activeStores = subquery(Store).select(['id']).where({ isActive: true });
 ## WHERE IN / NOT IN
 
 ```ts
-const activeStores = subquery(Store).select(['id']).where({ isActive: true });
+const activeStores = subquery(storeRepository).select(['id']).where({ isActive: true });
 
 // WHERE IN
-const products = await Product.find().where({
+const products = await productRepository.find().where({
   store: { in: activeStores },
 });
 // SQL: WHERE "store_id" IN (SELECT "id" FROM "stores" WHERE "is_active"=$1)
 
 // WHERE NOT IN
-const products = await Product.find().where({
+const products = await productRepository.find().where({
   store: { '!': { in: activeStores } },
 });
 ```
@@ -48,15 +48,15 @@ const products = await Product.find().where({
 ## WHERE EXISTS / NOT EXISTS
 
 ```ts
-const hasProducts = subquery(Product).where({ name: { like: 'Widget%' } });
+const hasProducts = subquery(productRepository).where({ name: { like: 'Widget%' } });
 
 // EXISTS
-const stores = await Store.find().where({
+const stores = await storeRepository.find().where({
   exists: hasProducts,
 });
 
 // NOT EXISTS
-const stores = await Store.find().where({
+const stores = await storeRepository.find().where({
   '!': { exists: hasProducts },
 });
 ```
@@ -68,9 +68,9 @@ If no columns are selected in the subquery, it defaults to `SELECT 1`.
 Compare column values against single-value subquery results:
 
 ```ts
-const avgPrice = subquery(Product).avg('price');
+const avgPrice = subquery(productRepository).avg('price');
 
-const expensiveProducts = await Product.find().where({
+const expensiveProducts = await productRepository.find().where({
   price: { '>': avgPrice },
 });
 // SQL: WHERE "price">(SELECT AVG("price") FROM "products")
@@ -80,10 +80,10 @@ Supported operators: `>`, `>=`, `<`, `<=`, `'!'` (not equal), or direct equality
 
 ```ts
 // Equal to max price
-.where({ price: subquery(Product).max('price') })
+.where({ price: subquery(productRepository).max('price') })
 
 // Not equal to min price
-.where({ price: { '!': subquery(Product).min('price') } })
+.where({ price: { '!': subquery(productRepository).min('price') } })
 ```
 
 ## Model joins
@@ -92,56 +92,62 @@ Join to related entities defined in your model:
 
 ```ts
 // Inner join
-const products = await Product.find()
+const products = await productRepository
+  .find()
   .join('store')
   .where({ store: { name: 'Acme' } });
-// SQL: SELECT "products".* FROM "products"
-//   INNER JOIN "stores" ON "products"."store_id"="stores"."id"
-//   WHERE "stores"."name"=$1
+// SQL: SELECT "products"."id","products"."name",… FROM "products"
+//   INNER JOIN "stores" AS "store" ON "products"."store_id"="store"."id"
+//   WHERE "store"."name"=$1
 
 // Left join
-const products = await Product.find()
+const products = await productRepository
+  .find()
   .leftJoin('store')
   .where({ store: { name: 'Acme' } });
 
 // Custom alias
-const products = await Product.find()
+const products = await productRepository
+  .find()
   .join('store', 'primaryStore')
   .where({ primaryStore: { name: 'Acme' } });
 
 // Additional ON conditions (left join only)
-const products = await Product.find().leftJoin('store', 'activeStore', { isActive: true });
+const products = await productRepository.find().leftJoin('store', 'activeStore', { isActive: true });
 ```
 
+When a query includes any join, BigAl automatically qualifies the base table's own columns (in `SELECT`, `WHERE`, `ORDER BY`, and `DISTINCT ON`) with the base table name.
+This keeps columns that share a name across the base and joined tables (most commonly `id`) from being ambiguous, so `.join()` is safe to use without falling back to raw SQL.
+
 ## Subquery joins
 
 Join to subquery results:
 
 ```ts
-const productCounts = subquery(Product)
+const productCounts = subquery(productRepository)
   .select(['store', (sb) => sb.count().as('productCount')])
   .groupBy(['store']);
 
 // Inner join
-const stores = await Store.find().join(productCounts, 'stats', { on: { id: 'store' } });
-// SQL: SELECT "stores".* FROM "stores"
+const stores = await storeRepository.find().join(productCounts, 'stats', { on: { id: 'store' } });
+// SQL: SELECT "stores"."id","stores"."name" FROM "stores"
 //   INNER JOIN (
 //     SELECT "store_id" AS "store", COUNT(*) AS "productCount"
 //     FROM "products" GROUP BY "store_id"
 //   ) AS "stats" ON "stores"."id"="stats"."store"
 
 // Left join
-const stores = await Store.find().leftJoin(productCounts, 'stats', { on: { id: 'store' } });
+const stores = await storeRepository.find().leftJoin(productCounts, 'stats', { on: { id: 'store' } });
 ```
 
 Multiple ON conditions:
 
 ```ts
-const categoryStats = subquery(Product)
+const categoryStats = subquery(productRepository)
   .select(['store', 'category', (sb) => sb.count().as('count')])
   .groupBy(['store', 'category']);
 
-const stores = await Store.find().join(categoryStats, 'stats', { on: { id: 'store', categoryId: 'category' } });
+const stores = await storeRepository.find().join(categoryStats, 'stats', { on: { id: 'store', categoryId: 'category' } });
 ```
 
 ## Sorting on joined columns
@@ -150,10 +156,11 @@ Use dot notation to sort by joined table columns:
 
 ```ts
 // Model join
-const products = await Product.find().join('store').sort('store.name asc');
+const products = await productRepository.find().join('store').sort('store.name asc');
 
 // Subquery join
-const stores = await Store.find()
+const stores = await storeRepository
+  .find()
   .join(productCounts, 'stats', { on: { id: 'store' } })
   .sort('stats.productCount desc');
 ```
@@ -173,7 +180,7 @@ Available in subquery selects:
 | `min(column)`              | Minimum value          |
 
 ```ts
-const stats = subquery(Product)
+const stats = subquery(productRepository)
   .select(['store', (sb) => sb.count().as('totalProducts'), (sb) => sb.sum('price').as('totalValue'), (sb) => sb.avg('price').as('avgPrice'), (sb) => sb.count('name').distinct().as('uniqueNames')])
   .groupBy(['store']);
 ```
@@ -183,7 +190,7 @@ If `.as()` is not called, aggregates use their function name as the alias (e.g.
 ## GROUP BY and HAVING
 
 ```ts
-const popularCategories = subquery(Product)
+const popularCategories = subquery(productRepository)
   .select(['category', (sb) => sb.count().as('productCount')])
   .groupBy(['category'])
   .having({ productCount: { '>': 10 } });
@@ -215,14 +222,14 @@ Annotate aggregate callbacks with `TypedAggregateExpression` for compile-time co
 ```ts
 import type { TypedAggregateExpression } from 'bigal';
 
-const productCounts = subquery(Product)
+const productCounts = subquery(productRepository)
   .select([
     'store',
     (sb): TypedAggregateExpression<'productCount'> => sb.count().as('productCount'),
   ])
   .groupBy(['store']);
 
-const stores = await Store.find()
+const stores = await storeRepository.find()
   .join(productCounts, 'stats', { on: { id: 'store' } })
   .sort('stats.productCount desc'); // Type-safe!
 
@@ -235,9 +242,9 @@ const stores = await Store.find()
 Use `distinctOn()` for "greatest-per-group" patterns:
 
 ```ts
-const latestProducts = subquery(Product).select(['store', 'name', 'createdAt']).distinctOn(['store']).sort('store').sort('createdAt desc');
+const latestProducts = subquery(productRepository).select(['store', 'name', 'createdAt']).distinctOn(['store']).sort('store').sort('createdAt desc');
 
-const stores = await Store.find().join(latestProducts, 'latestProduct', { on: { id: 'store' } });
+const stores = await storeRepository.find().join(latestProducts, 'latestProduct', { on: { id: 'store' } });
 ```
 
 See [Querying > DISTINCT ON](/guide/querying#distinct-on) for constraints and usage with top-level queries.

package/docs/guide/views.md

@@ -1,28 +1,39 @@
 ---
-description: Define readonly models backed by PostgreSQL views with view() and ReadonlyRepository. Supports schema options and all query features.
+description: Map PostgreSQL views to readonly models with ReadonlyRepository. Supports inheritance, schema options, and all query features.
 ---
 
 # Views and Readonly Repositories
 
-BigAl provides a `view()` function for defining models backed by PostgreSQL views. The `view()`
-function is equivalent to `table()` with `readonly: true` - it produces a `ReadonlyRepository`
-that omits `create`, `update`, and `destroy` methods, catching accidental writes at compile time.
+BigAl does not distinguish between tables and views. Both use the `@table()` decorator. Setting `readonly: true` causes
+`initialize()` to return a `ReadonlyRepository` — which omits `create`, `update`, and `destroy` methods,
+catching accidental writes at compile time.
 
 BigAl does not create or manage views. Create them in PostgreSQL via your migration tool.
 
 ## Defining a view model
 
-### Using view()
+### Standalone model
 
 ```ts
-import { view, serial, text, integer } from 'bigal';
+import { column, primaryColumn, table, Entity } from 'bigal';
 
-export const ProductSummary = view('product_summaries', {
-  id: serial().primaryKey(),
-  name: text().notNull(),
-  storeName: text().notNull(),
-  categoryCount: integer().notNull(),
-});
+@table({
+  name: 'product_summaries',
+  readonly: true,
+})
+export class ProductSummary extends Entity {
+  @primaryColumn({ type: 'integer' })
+  public id!: number;
+
+  @column({ type: 'string', required: true })
+  public name!: string;
+
+  @column({ type: 'string', required: true, name: 'store_name' })
+  public storeName!: string;
+
+  @column({ type: 'integer', required: true, name: 'category_count' })
+  public categoryCount!: number;
+}
 ```
 
 Corresponding view in PostgreSQL:
@@ -40,47 +51,19 @@ LEFT JOIN product_categories pc ON pc.product_id = p.id
 GROUP BY p.id, p.name, s.name;
 ```
 
-### Using table() with readonly option
-
-Alternatively, use `table()` with `readonly: true`:
-
-```ts
-import { table, serial, text, integer } from 'bigal';
-
-export const ProductSummary = table(
-  'product_summaries',
-  {
-    id: serial().primaryKey(),
-    name: text().notNull(),
-    storeName: text().notNull(),
-    categoryCount: integer().notNull(),
-  },
-  { readonly: true },
-);
-```
-
-### Sharing columns with a table
+### Inheriting from an existing model
 
-If a view returns the same columns as a table (e.g., a filtered subset),
-share the column definitions:
+If the view has the same columns as an existing table, extend the model to reuse column definitions:
 
 ```ts
-import { table, view, serial, text, integer, boolean } from 'bigal';
-
-const productColumns = {
-  id: serial().primaryKey(),
-  name: text().notNull(),
-  priceCents: integer().notNull(),
-  isActive: boolean().notNull(),
-};
-
-export const Product = table('products', {
-  ...productColumns,
-  store: belongsTo('Store'),
-});
-
-// View returns the same columns, just filtered to active products
-export const ActiveProduct = view('active_products', productColumns);
+import { table } from 'bigal';
+import { Product } from './Product';
+
+@table({
+  name: 'readonly_products',
+  readonly: true,
+})
+export class ReadonlyProduct extends Product {}
 ```
 
 ### Schema option
@@ -88,42 +71,31 @@ export const ActiveProduct = view('active_products', productColumns);
 For views in a non-default schema:
 
 ```ts
-export const ReportSummary = view(
-  'product_summaries',
-  {
-    id: serial().primaryKey(),
-    storeName: text().notNull(),
-    totalRevenue: integer().notNull(),
-  },
-  { schema: 'reporting' },
-);
+@table({
+  schema: 'reporting',
+  name: 'product_summaries',
+  readonly: true,
+})
+export class ProductSummary extends Entity {
+  // ...
+}
 ```
 
 ## Initializing the repository
 
-Include the model in `initialize()`. BigAl creates a `ReadonlyRepository` automatically for models
-defined with `view()` or `table()` with `readonly: true`:
+Include the view model in `initialize()`. BigAl creates a `ReadonlyRepository` automatically:
 
 ```ts
-import { initialize } from 'bigal';
-import type { ReadonlyRepository } from 'bigal';
+import { initialize, ReadonlyRepository } from 'bigal';
 import { Product, Store, ProductSummary } from './models';
 
-const { Product, ProductSummary } = initialize({
-  models: { Product, Store, ProductSummary },
+const repos = initialize({
+  models: [Product, Store, ProductSummary],
   pool,
   readonlyPool,
 });
 
-// ProductSummary only has find(), findOne(), and count()
-```
-
-For repository type annotations, use `ReadonlyRepository<typeof Model>`:
-
-```ts
-function getSummaries(repo: ReadonlyRepository<typeof ProductSummary>) {
-  return repo.find().where({ categoryCount: { '>': 5 } });
-}
+const productSummaryRepository = repos.ProductSummary as ReadonlyRepository<ProductSummary>;
 ```
 
 ## Querying
@@ -131,18 +103,18 @@ function getSummaries(repo: ReadonlyRepository<typeof ProductSummary>) {
 Readonly repositories support the same query methods as regular repositories:
 
 ```ts
-const summaries = await ProductSummary.find()
+const summaries = await productSummaryRepository
+  .find()
   .where({ storeName: { contains: 'Acme' } })
   .sort('categoryCount desc')
   .limit(10);
 
-const summary = await ProductSummary.findOne().where({ id: 42 });
+const summary = await productSummaryRepository.findOne().where({ id: 42 });
 
-const count = await ProductSummary.count().where({ categoryCount: { '>': 5 } });
+const count = await productSummaryRepository.count().where({ categoryCount: { '>': 5 } });
 ```
 
-All query features work: `where` operators, `sort`, `skip`, `limit`, `paginate`, `populate`, `join`,
-`withCount`, and `distinctOn`.
+All query features work: `where` operators, `sort`, `skip`, `limit`, `paginate`, `populate`, `join`, `withCount`, and `distinctOn`.
 
 ## Available methods
 

package/docs/index.md

@@ -2,7 +2,7 @@
 layout: home
 hero:
   text: PostgreSQL-optimized TypeScript ORM
-  tagline: Built exclusively for Postgres. Type-safe fluent query builder, function-based models, and queries tuned for Postgres performance.
+  tagline: Built exclusively for Postgres. Type-safe fluent query builder, decorator-based models, and queries tuned for Postgres performance.
   actions:
     - theme: brand
       text: Get Started
@@ -15,10 +15,10 @@ features:
     details: Built exclusively for Postgres, not a lowest-common-denominator abstraction. Queries are tuned for Postgres performance. JSONB, DISTINCT ON, subquery joins, and ON CONFLICT upserts work out of the box.
   - title: Fluent builder pattern
     details: Chain .where(), .sort(), .limit(), .join(), and .populate() calls. Each method returns a new immutable instance.
-  - title: Function-based models
-    details: Define models with table() and view(), PostgreSQL-native column builders, and relationship helpers. Types are inferred from the schema definition.
+  - title: Decorator-based models
+    details: Define tables, columns, and relationships with TypeScript decorators. Inheritance and schema support built in.
   - title: Type-safe queries
-    details: WhereQuery types narrow automatically - relationship fields resolve to foreign keys or populated entities without type assertions.
+    details: WhereQuery types narrow automatically — relationship fields resolve to foreign keys or populated entities without type assertions.
 ---
 
 <!-- markdownlint-disable MD013 MD033 MD041 -->
@@ -48,47 +48,51 @@ features:
 <div class="code-showcase">
 
 <h2>What it looks like</h2>
-<p class="subtitle">Define a model, query it - that's it.</p>
+<p class="subtitle">Define a model, query it — that's it.</p>
 
 ```ts
-// models/Product.ts
-import { table, serial, text, integer, belongsTo } from 'bigal';
-
-export const Product = table('products', {
-  id: serial().primaryKey(),
-  name: text().notNull(),
-  priceCents: integer().notNull(),
-  sku: text(),
-  store: belongsTo('Store'),
-});
-```
-
-```ts
-// app.ts
-import { initialize, subquery } from 'bigal';
+import { column, primaryColumn, table, Entity, initialize } from 'bigal';
 import { Pool } from 'postgres-pool';
 
-const { Product, Store } = initialize({
-  models: { Product, Store },
+@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 })
+  public priceCents!: number;
+
+  @column({ model: () => 'Store', name: 'store_id' })
+  public store!: number | Store;
+}
+
+const repos = initialize({
+  models: [Product, Store],
   pool: new Pool('postgres://localhost/mydb'),
 });
+const productRepo = repos.Product as Repository<Product>;
 
-// Fluent queries - just await the chain
-const products = await Product.find()
+// Fluent queries — just await the chain
+const products = await productRepo
+  .find()
   .where({ priceCents: { '>': 1000 }, name: { contains: 'widget' } })
   .sort('name asc')
   .limit(10);
 
 // Joins and subqueries
-const expensiveProducts = await Product.find()
+const expensiveProducts = await productRepo
+  .find()
   .join('store')
   .where({
     store: { name: 'Acme' },
-    priceCents: { '>': subquery(Product).avg('priceCents') },
+    price: { '>': subquery(productRepo).avg('price') },
   });
 
 // Upserts with ON CONFLICT
-await Product.create({ name: 'Widget', sku: 'WDG-001', priceCents: 999 }, { onConflict: { action: 'merge', targets: ['sku'], merge: ['priceCents'] } });
+await productRepo.create({ name: 'Widget', sku: 'WDG-001', priceCents: 999 }, { onConflict: { action: 'merge', targets: ['sku'], merge: ['priceCents'] } });
 ```
 
 </div>

package/docs/package.json

@@ -9,6 +9,7 @@
   },
   "devDependencies": {
     "vitepress": "1.6.4",
-    "vitepress-plugin-llms": "1.12.0"
-  }
+    "vitepress-plugin-llms": "1.13.2"
+  },
+  "packageManager": "pnpm@11.11.0+sha512.4463f65fd80ed80d69bc1d4bf163ee94f605c7380fc318bb5b2ebe15f8cd12d49c51a4d59e951b401e764d3b6ca751cbf51bc50ed7001a6bcb4935e684c34882"
 }