bigal 15.0.1 → 15.2.0

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+# [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
+
+- Add `and` property to WhereQuery for combining OR groups ([#262](https://github.com/bigalorm/bigal/issues/262)) ([903eeb8](https://github.com/bigalorm/bigal/commit/903eeb826e3dedd7574aa940527ca07b264a40b2))
+
 ## [15.0.1](https://github.com/bigalorm/bigal/compare/v15.0.0...v15.0.1) (2026-01-07)
 
 # [15.0.0](https://github.com/bigalorm/bigal/compare/v14.1.26...v15.0.0) (2025-12-28)

package/README.md

@@ -4,12 +4,11 @@
 [![node version](https://img.shields.io/node/v/bigal.svg?style=flat)](https://nodejs.org)
 [![Known Vulnerabilities](https://snyk.io/test/npm/bigal/badge.svg)](https://snyk.io/test/npm/bigal)
 
-A fast, lightweight ORM for PostgreSQL and node.js, written in Typescript.
+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
@@ -365,6 +364,34 @@ Equivalent to:
 select id,first_name as firstName,last_name as lastName,created_at as createdAt from person where created_at >= $1 AND created_at < $2
 ```
 
+#### Using `or` for OR conditions across different columns
+
+```ts
+const items = await PersonRepository.find().where({
+  or: [{ firstName: 'Walter' }, { lastName: 'White' }],
+});
+```
+
+Equivalent to:
+
+```postgresql
+select * from person where (first_name = $1) OR (last_name = $2)
+```
+
+#### Using `and` to combine multiple OR groups
+
+```ts
+const items = await PersonRepository.find().where({
+  and: [{ or: [{ firstName: 'Walter' }, { lastName: 'White' }] }, { or: [{ firstName: 'Jesse' }, { lastName: 'Pinkman' }] }],
+});
+```
+
+Equivalent to:
+
+```postgresql
+select * from person where ((first_name = $1) OR (last_name = $2)) AND ((first_name = $3) OR (last_name = $4))
+```
+
 #### Fetch multiple objects and perform a db sort before returning result
 
 ```ts
@@ -433,6 +460,92 @@ 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.
+
 ---
 
 ### `.count()` - Get the number of records matching the where criteria
@@ -721,7 +834,7 @@ export class Store extends Entity {
 
 #### Non-entity object arrays
 
-If you have a json property, with an `id` field, on an entity model, TypeScript will probably think it is a BigAl
+If you have a JSON property, with an `id` field, on an entity model, TypeScript will probably think it is a BigAl
 entity due to how the type system works. In that case, you'll want to wrap the type with `NotEntity<>`. For example:
 
 ```ts