bigal 15.4.0 → 15.6.0

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+# [15.6.0](https://github.com/bigalorm/bigal/compare/v15.5.0...v15.6.0) (2026-01-18)
+
+### Features
+
+- Add support for joining to subqueries with GROUP BY and aggregates ([#275](https://github.com/bigalorm/bigal/issues/275)) ([6108663](https://github.com/bigalorm/bigal/commit/6108663f29f22bc4abb87028f9537305c69055b7))
+
+# [15.5.0](https://github.com/bigalorm/bigal/compare/v15.4.0...v15.5.0) (2026-01-13)
+
+### Features
+
+- Add toJSON() method for returning plain objects instead of class instances ([#271](https://github.com/bigalorm/bigal/issues/271)) ([3e2ee5d](https://github.com/bigalorm/bigal/commit/3e2ee5d803d705bc54bc8b08044f5848088563bb))
+
 # [15.4.0](https://github.com/bigalorm/bigal/compare/v15.3.0...v15.4.0) (2026-01-08)
 
 ### Features

package/README.md

@@ -183,8 +183,8 @@ export function startup({
   });
 
   let categoryRepository: Repository<Category>;
-  let productRepository: Repository<Category>;
-  let storeRepository: Repository<Category>;
+  let productRepository: Repository<Product>;
+  let storeRepository: Repository<Store>;
   for (const [modelName, repository] = Object.entries(repositoriesByName)) {
     switch (modelName) {
       case 'Category':
@@ -803,6 +803,185 @@ const orders = await OrderRepository.find().where({ store: { in: activeStoreIds
 
 ---
 
+#### Joining to Subqueries
+
+You can join to subqueries (derived tables) using `join()` or `leftJoin()`. This is useful for aggregating data and joining it back to the main query.
+
+##### Basic subquery join with COUNT aggregate
+
+```ts
+import { subquery } from 'bigal';
+
+// Count products per store
+const productCounts = subquery(ProductRepository)
+  .select(['store', (s) => s.count().as('productCount')])
+  .groupBy(['store']);
+
+// Join to get stores with their product counts
+const stores = await StoreRepository.find().join(productCounts, 'productStats', { on: { id: 'store' } });
+```
+
+Equivalent SQL:
+
+```sql
+SELECT * FROM stores
+INNER JOIN (
+  SELECT store_id AS store, COUNT(*) AS "productCount"
+  FROM products
+  GROUP BY store_id
+) AS "productStats" ON stores.id = "productStats".store
+```
+
+##### LEFT JOIN to subquery
+
+Use `leftJoin()` to include rows even when there's no matching subquery row:
+
+```ts
+const productCounts = subquery(ProductRepository)
+  .select(['store', (s) => s.count().as('productCount')])
+  .groupBy(['store']);
+
+// LEFT JOIN returns all stores, even those with no products
+const stores = await StoreRepository.find().leftJoin(productCounts, 'productStats', { on: { id: 'store' } });
+```
+
+##### Sorting by subquery columns
+
+Use dot notation to sort by columns from the subquery:
+
+```ts
+const productCounts = subquery(ProductRepository)
+  .select(['store', (s) => s.count().as('productCount')])
+  .groupBy(['store']);
+
+// Sort by product count descending (most products first)
+const stores = await StoreRepository.find()
+  .join(productCounts, 'productStats', { on: { id: 'store' } })
+  .sort('productStats.productCount desc');
+```
+
+##### Subquery with WHERE clause and aggregate
+
+Filter within the subquery before aggregating:
+
+```ts
+// Count only active products per store
+const activeProductCounts = subquery(ProductRepository)
+  .select(['store', (s) => s.count().as('activeCount')])
+  .where({ isActive: true })
+  .groupBy(['store']);
+
+const stores = await StoreRepository.find().join(activeProductCounts, 'activeStats', { on: { id: 'store' } });
+```
+
+##### COUNT DISTINCT in subquery
+
+Use `.distinct()` for counting unique values:
+
+```ts
+// Count unique product names per store
+const uniqueNameCounts = subquery(ProductRepository)
+  .select(['store', (s) => s.count('name').distinct().as('uniqueNames')])
+  .groupBy(['store']);
+
+const stores = await StoreRepository.find().join(uniqueNameCounts, 'stats', { on: { id: 'store' } });
+```
+
+Equivalent SQL:
+
+```sql
+SELECT * FROM stores
+INNER JOIN (
+  SELECT store_id AS store, COUNT(DISTINCT name) AS "uniqueNames"
+  FROM products
+  GROUP BY store_id
+) AS stats ON stores.id = stats.store
+```
+
+##### Multiple aggregates in a single subquery
+
+Compute multiple aggregates in one subquery:
+
+```ts
+const orderStats = subquery(OrderRepository)
+  .select(['store', (s) => s.count().as('orderCount'), (s) => s.sum('total').as('totalRevenue'), (s) => s.avg('total').as('avgOrderValue')])
+  .groupBy(['store']);
+
+const stores = await StoreRepository.find()
+  .join(orderStats, 'stats', { on: { id: 'store' } })
+  .sort('stats.totalRevenue desc');
+```
+
+##### Default aggregate aliases
+
+Aggregate functions have default aliases matching their function name:
+
+```ts
+// Without .as() - alias defaults to function name
+const counts = subquery(ProductRepository)
+  .select(['store', (s) => s.count()]) // alias: "count"
+  .groupBy(['store']);
+
+// With .as() - custom alias
+const counts = subquery(ProductRepository)
+  .select(['store', (s) => s.count().as('productCount')]) // alias: "productCount"
+  .groupBy(['store']);
+```
+
+##### HAVING clause for filtering aggregated results
+
+Use `.having()` to filter groups based on aggregate values:
+
+```ts
+// Only include stores with more than 10 products
+const productCounts = subquery(ProductRepository)
+  .select(['store', (s) => s.count().as('productCount')])
+  .groupBy(['store'])
+  .having({ productCount: { '>': 10 } });
+
+const popularStores = await StoreRepository.find().join(productCounts, 'stats', { on: { id: 'store' } });
+```
+
+Supported comparison operators: `>`, `>=`, `<`, `<=`, `!=`, or exact equality (number).
+
+```ts
+// Multiple conditions on different aggregates
+const orderStats = subquery(OrderRepository)
+  .select(['store', (s) => s.count().as('orderCount'), (s) => s.avg('total').as('avgOrderValue')])
+  .groupBy(['store'])
+  .having({ orderCount: { '>=': 5 }, avgOrderValue: { '>': 100 } });
+```
+
+##### WHERE vs HAVING in subqueries
+
+`WHERE` and `HAVING` serve different purposes in aggregated subqueries:
+
+- **WHERE** filters individual rows _before_ grouping
+- **HAVING** filters groups _after_ aggregation
+
+```ts
+// WHERE: Only count active products (filters rows before counting)
+const activeProductCounts = subquery(ProductRepository)
+  .select(['store', (s) => s.count().as('productCount')])
+  .where({ isActive: true }) // Excludes inactive products from the count
+  .groupBy(['store']);
+
+// HAVING: Only include stores with high product counts (filters groups after counting)
+const highVolumeStores = subquery(ProductRepository)
+  .select(['store', (s) => s.count().as('productCount')])
+  .groupBy(['store'])
+  .having({ productCount: { '>': 100 } }); // Excludes stores with 100 or fewer products
+
+// Combined: Count active products, then filter to stores with many active products
+const highVolumeActiveStores = subquery(ProductRepository)
+  .select(['store', (s) => s.count().as('activeCount')])
+  .where({ isActive: true }) // Step 1: Only consider active products
+  .groupBy(['store'])
+  .having({ activeCount: { '>': 50 } }); // Step 2: Only keep stores with >50 active products
+```
+
+---
+
 ### `.count()` - Get the number of records matching the where criteria
 
 ```ts