bigal 15.1.0 → 15.3.0

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+# [15.3.0](https://github.com/bigalorm/bigal/compare/v15.2.0...v15.3.0) (2026-01-08)
+
+### Features
+
+- Add SQL subquery support for WHERE clauses ([#265](https://github.com/bigalorm/bigal/issues/265)) ([2af8d7f](https://github.com/bigalorm/bigal/commit/2af8d7f4ad53642907f3e8d1539bd6f07e1ccecc))
+
+# [15.2.0](https://github.com/bigalorm/bigal/compare/v15.1.0...v15.2.0) (2026-01-08)
+
+### Features
+
+- Add SQL JOIN support for filtering and sorting by related tables ([#263](https://github.com/bigalorm/bigal/issues/263)) ([e5f1a97](https://github.com/bigalorm/bigal/commit/e5f1a97f524d8e784943d179347dc364a62959e1))
+
 # [15.1.0](https://github.com/bigalorm/bigal/compare/v15.0.1...v15.1.0) (2026-01-07)
 
 ### Features

package/CLAUDE.md

@@ -0,0 +1,81 @@
+# CLAUDE.md
+
+This file provides guidance for Claude Code when working on the BigAl project.
+
+## Project Overview
+
+BigAl is a type-safe PostgreSQL ORM for Node.js/TypeScript. It uses a fluent builder pattern for queries and provides strongly-typed results.
+
+## Build and Test Commands
+
+```bash
+npm run build    # Build the project using unbuild
+npm test         # Run all tests with Mocha
+npm run lint     # Run ESLint and markdownlint
+npx tsc --noEmit # Type-check without emitting files
+```
+
+## Code Style Guidelines
+
+### Naming Conventions
+
+- Use self-descriptive names for variables, functions, parameters, and types
+- Avoid single-letter variables or abbreviations (use `maxRows` instead of `n`, `parentSubquery` instead of `subquery` when shadowing)
+- Class names should be PascalCase
+- Functions, methods, and variables should be camelCase
+- Constants should be SCREAMING_SNAKE_CASE
+
+### Comments
+
+- Only add comments when they provide meaningful insight that cannot be inferred from self-describing code
+- Remove or refine unnecessary comments
+- JSDoc is acceptable for public API documentation
+
+### TypeScript Practices
+
+- Avoid using the `as` keyword for type assertions unless absolutely necessary
+- Prefer type inference where possible
+- Use generic type parameters to narrow types rather than casting (e.g., `max<K extends keyof T>(column: K): T[K]`)
+- Never disable linter rules unless there is no other option - it should be a last resort
+
+### Linting and JSDoc
+
+- All linting errors and warnings must be resolved, including JSDoc issues
+- Use restraint with examples in JSDoc comments. Only provide an example if usage is unclear.
+- Ensure JSDoc tags are properly escaped if referencing decorators (use backticks or escape with backslash)
+
+### Code Organization
+
+- Don't create interfaces unnecessarily - if a class can serve as both implementation and type, the interface is redundant
+- Split classes into separate files only when needed to comply with linter rules
+
+## Architecture Patterns
+
+### Repository Pattern
+
+Repositories provide CRUD operations with type-safe query building:
+
+- `IReadonlyRepository<T>` - read operations (find, findOne, count)
+- `IRepository<T>` - full CRUD operations
+
+### Query Building
+
+Queries use a fluent builder pattern with immutable state:
+
+- Each method returns a new instance (clone pattern)
+- Methods chain naturally: `.where({...}).sort('name').limit(10)`
+- Queries are `PromiseLike` for automatic execution
+
+### SQL Generation
+
+- `SqlHelper.ts` handles all SQL string generation
+- Use parameterized queries (`$1`, `$2`, etc.) to prevent SQL injection
+- The `buildWhere()` function recursively processes WHERE clause objects
+
+## Testing Conventions
+
+- Tests are in `tests/` directory with `.tests.ts` suffix
+- Use Mocha with Chai assertions
+- Test file structure mirrors source structure
+- Repository tests use a shared setup with `repositoriesByModelNameLowered`
+- When test infrastructure types are too generic, type assertions are acceptable

package/README.md

@@ -9,7 +9,6 @@ A fast, lightweight ORM for PostgreSQL and Node.js, written in TypeScript.
 This ORM does not:
 
 - Create or update db schemas for you
-- Handle associations/joins
 - Do much else than basic queries, inserts, updates, and deletes
 
 ## Compatibility
@@ -461,6 +460,218 @@ const items = await FooRepository.find()
   .paginate(page, pageSize);
 ```
 
+#### Join related tables
+
+Use `join()` for INNER JOIN or `leftJoin()` for LEFT JOIN to filter or sort by related table columns in a single query.
+
+```ts
+// INNER JOIN - only returns products that have a store
+const items = await ProductRepository.find()
+  .join('store')
+  .where({
+    store: {
+      name: 'Acme',
+    },
+  });
+```
+
+```ts
+// LEFT JOIN - returns all products, even those without a store
+const items = await ProductRepository.find()
+  .leftJoin('store')
+  .where({
+    store: {
+      name: 'Acme',
+    },
+  });
+```
+
+#### Join with alias
+
+Use an alias when you need to join the same table multiple times or for clarity.
+
+```ts
+const items = await ProductRepository.find()
+  .join('store', 'primaryStore')
+  .where({
+    primaryStore: {
+      name: 'Acme',
+    },
+  });
+```
+
+#### Join with additional ON constraints
+
+Add extra conditions to the JOIN's ON clause using `leftJoin()`.
+
+```ts
+const items = await ProductRepository.find()
+  .leftJoin('store', 'store', {
+    isDeleted: false,
+  })
+  .where({
+    name: {
+      like: 'Widget%',
+    },
+  });
+```
+
+#### Sort by joined table columns
+
+Use dot notation to sort by columns on joined tables.
+
+```ts
+const items = await ProductRepository.find().join('store').sort('store.name asc');
+```
+
+#### Combine multiple where conditions
+
+Mix regular where conditions with joined table conditions.
+
+```ts
+const items = await ProductRepository.find()
+  .join('store')
+  .where({
+    name: {
+      like: 'Widget%',
+    },
+    store: {
+      name: {
+        like: ['Acme', 'foo'],
+      },
+    },
+  });
+```
+
+> Note: `join()` and `populate()` serve different purposes. Use `join()` when you need to filter or sort by related
+> table columns in SQL. Use `populate()` when you want to fetch the full related object(s) as nested data in results.
+
+---
+
+#### Subqueries
+
+Use the `subquery()` function to create subqueries for use in WHERE clauses.
+
+##### WHERE IN with subquery
+
+```ts
+import { subquery } from 'bigal';
+
+// Find products from active stores
+const activeStoreIds = subquery(StoreRepository).select(['id']).where({ isActive: true });
+
+const items = await ProductRepository.find().where({
+  store: { in: activeStoreIds },
+});
+```
+
+Equivalent SQL:
+
+```sql
+SELECT * FROM products
+WHERE store_id IN (SELECT id FROM stores WHERE is_active = $1)
+```
+
+##### WHERE NOT IN with subquery
+
+Use the existing `!` negation operator:
+
+```ts
+const discontinuedProductIds = subquery(DiscontinuedProductRepository).select(['productId']);
+
+const items = await ProductRepository.find().where({
+  id: { '!': { in: discontinuedProductIds } },
+});
+```
+
+Equivalent SQL:
+
+```sql
+SELECT * FROM products
+WHERE id NOT IN (SELECT product_id FROM discontinued_products)
+```
+
+##### WHERE EXISTS
+
+```ts
+// Find stores that have at least one product
+const items = await StoreRepository.find().where({
+  exists: subquery(ProductRepository).where({ storeId: 42 }),
+});
+```
+
+Equivalent SQL:
+
+```sql
+SELECT * FROM stores
+WHERE EXISTS (SELECT 1 FROM products WHERE store_id = $1)
+```
+
+##### WHERE NOT EXISTS
+
+```ts
+// Find stores with no products
+const items = await StoreRepository.find().where({
+  '!': {
+    exists: subquery(ProductRepository).where({ storeId: 42 }),
+  },
+});
+```
+
+Equivalent SQL:
+
+```sql
+SELECT * FROM stores
+WHERE NOT EXISTS (SELECT 1 FROM products WHERE store_id = $1)
+```
+
+##### Scalar subquery comparisons
+
+Use aggregate methods (`count()`, `avg()`, `sum()`, `max()`, `min()`) to create scalar subqueries for comparisons:
+
+```ts
+// Find products priced above the average
+const avgPrice = subquery(ProductRepository).where({ category: 'electronics' }).avg('price');
+
+const items = await ProductRepository.find().where({
+  price: { '>': avgPrice },
+});
+```
+
+Equivalent SQL:
+
+```sql
+SELECT * FROM products
+WHERE price > (SELECT AVG(price) FROM products WHERE category = $1)
+```
+
+##### Combining subqueries with other conditions
+
+Subqueries can be combined with regular where conditions and other operators:
+
+```ts
+const premiumStoreIds = subquery(StoreRepository).select(['id']).where({ tier: 'premium' });
+
+const items = await ProductRepository.find().where({
+  store: { in: premiumStoreIds },
+  price: { '>=': 100 },
+  isActive: true,
+});
+```
+
+##### Reusable subqueries
+
+Subqueries are standalone objects that can be reused across multiple queries:
+
+```ts
+const activeStoreIds = subquery(StoreRepository).select(['id']).where({ isActive: true });
+
+// Use in multiple queries
+const products = await ProductRepository.find().where({ store: { in: activeStoreIds } });
+
+const orders = await OrderRepository.find().where({ store: { in: activeStoreIds } });
+```
+
 ---
 
 ### `.count()` - Get the number of records matching the where criteria