bigal 15.10.1 → 15.10.2

package/CHANGELOG.md

@@ -1,3 +1,5 @@
+## [15.10.2](https://github.com/bigalorm/bigal/compare/v15.10.1...v15.10.2) (2026-02-27)
+
 ## [15.10.1](https://github.com/bigalorm/bigal/compare/v15.10.0...v15.10.1) (2026-02-07)
 
 ### Bug Fixes

package/docs/views-and-readonly-repositories.md

@@ -0,0 +1,153 @@
+# Views and Readonly Repositories
+
+This guide covers how to use BigAl with PostgreSQL views by creating readonly repositories.
+Readonly repositories expose only read operations (`findOne`, `find`, `count`),
+making them a natural fit for database views.
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Defining a Model for a View](#defining-a-model-for-a-view)
+  - [Standalone Model](#standalone-model)
+  - [Inheriting from an Existing Model](#inheriting-from-an-existing-model)
+  - [Using a Schema](#using-a-schema)
+- [Initializing the Repository](#initializing-the-repository)
+- [Querying](#querying)
+- [Available Methods](#available-methods)
+
+## Overview
+
+BigAl does not distinguish between tables and views at the ORM level. Both use the `@table()` decorator.
+Setting `readonly: true` in the decorator options causes `initialize()` to return a `ReadonlyRepository`
+instead of a `Repository`. The `ReadonlyRepository` type does not include `create`, `update`, or `destroy` methods,
+so TypeScript will catch accidental write attempts at compile time.
+
+BigAl does not create or manage database schemas, so you are responsible for creating the view in PostgreSQL (e.g. via a migration tool).
+
+## Defining a Model for a View
+
+### Standalone Model
+
+Define a model class that maps to the view's columns, and set `readonly: true` in the `@table()` decorator:
+
+```ts
+import { column, primaryColumn, table, Entity } from 'bigal';
+
+@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;
+}
+```
+
+This maps to a view created in PostgreSQL:
+
+```sql
+CREATE VIEW product_summaries AS
+SELECT
+  p.id,
+  p.name,
+  s.name AS store_name,
+  COUNT(pc.category_id) AS category_count
+FROM products p
+JOIN stores s ON s.id = p.store_id
+LEFT JOIN product_categories pc ON pc.product_id = p.id
+GROUP BY p.id, p.name, s.name;
+```
+
+### Inheriting from an Existing Model
+
+If your view has the same columns as an existing table (or a subset), you can extend the existing model to reuse its column definitions:
+
+```ts
+import { table } from 'bigal';
+import { Product } from './Product';
+
+@table({
+  name: 'readonly_products',
+  readonly: true,
+})
+export class ReadonlyProduct extends Product {}
+```
+
+This avoids duplicating `@column()` definitions. The `ReadonlyProduct` model inherits all column metadata from `Product` but maps to the `readonly_products` view and produces a `ReadonlyRepository`.
+
+### Using a Schema
+
+If the view lives in a non-default schema, specify it with the `schema` option:
+
+```ts
+@table({
+  schema: 'reporting',
+  name: 'product_summaries',
+  readonly: true,
+})
+export class ProductSummary extends Entity {
+  // ...
+}
+```
+
+## Initializing the Repository
+
+Include the model in the `initialize()` call. BigAl automatically creates a `ReadonlyRepository` for models marked with `readonly: true`.
+
+```ts
+import { initialize, ReadonlyRepository } from 'bigal';
+import { Product, Store, ProductSummary } from './models';
+
+const repositoriesByName = initialize({
+  models: [Product, Store, ProductSummary],
+  pool,
+  readonlyPool,
+});
+
+const productSummaryRepository = repositoriesByName.ProductSummary as ReadonlyRepository<ProductSummary>;
+```
+
+## Querying
+
+Readonly repositories support the same query methods and chaining as regular repositories:
+
+```ts
+// Find multiple records with filtering, sorting, and pagination
+const summaries = await productSummaryRepository
+  .find()
+  .where({
+    storeName: { contains: 'Acme' },
+  })
+  .sort('categoryCount desc')
+  .limit(10);
+
+// Find a single record
+const summary = await productSummaryRepository.findOne().where({ id: 42 });
+
+// Count matching records
+const count = await productSummaryRepository.count().where({
+  categoryCount: { '>': 5 },
+});
+```
+
+All query features documented in the [README](../README.md) work with readonly repositories, including `where` operators, `sort`, `skip`, `limit`, `paginate`, `populate`, `join`, `withCount`, and `distinctOn`.
+
+## Available Methods
+
+| Method      | `Repository` | `ReadonlyRepository` |
+| ----------- | ------------ | -------------------- |
+| `findOne()` | Yes          | Yes                  |
+| `find()`    | Yes          | Yes                  |
+| `count()`   | Yes          | Yes                  |
+| `create()`  | Yes          | No                   |
+| `update()`  | Yes          | No                   |
+| `destroy()` | Yes          | No                   |

package/eslint.config.mjs

@@ -3,8 +3,6 @@ import { config } from 'eslint-config-decent';
 export default [
   ...config({
     tsconfigRootDir: import.meta.dirname,
-    enableJest: false,
-    enableVitest: false,
     enableTestingLibrary: false,
   }),
   {
@@ -13,10 +11,4 @@ export default [
       '@typescript-eslint/no-invalid-void-type': 'off',
     },
   },
-  {
-    files: ['tests/**/*.ts'],
-    rules: {
-      '@typescript-eslint/no-non-null-assertion': 'off',
-    },
-  },
 ];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bigal",
-  "version": "15.10.1",
+  "version": "15.10.2",
   "description": "A fast and lightweight orm for postgres and node.js, written in typescript.",
   "main": "./dist/index.cjs",
   "module": "./dist/index.mjs",
@@ -32,40 +32,34 @@
   "engines": {
     "node": ">=20.11.0"
   },
-  "dependencies": {},
   "devDependencies": {
-    "@faker-js/faker": "10.2.0",
+    "@faker-js/faker": "10.3.0",
     "@semantic-release/changelog": "6.0.3",
     "@semantic-release/commit-analyzer": "13.0.1",
     "@semantic-release/git": "10.0.1",
-    "@semantic-release/github": "12.0.3",
-    "@semantic-release/npm": "13.1.3",
+    "@semantic-release/github": "12.0.6",
+    "@semantic-release/npm": "13.1.4",
     "@semantic-release/release-notes-generator": "14.1.0",
-    "@types/chai": "5.2.3",
-    "@types/mocha": "10.0.10",
-    "@types/node": ">=20",
-    "chai": "6.2.2",
-    "eslint": "9.39.2",
-    "eslint-config-decent": "3.1.115",
+    "@types/node": ">=22",
+    "eslint": "10.0.2",
+    "eslint-config-decent": "4.1.0",
     "husky": "9.1.7",
     "lint-staged": "16.2.7",
     "markdownlint-cli": "0.47.0",
-    "mocha": "11.7.5",
     "npm-run-all2": "8.0.4",
     "pinst": "3.0.0",
     "prettier": "3.8.1",
     "semantic-release": "25.0.3",
     "strict-event-emitter-types": "2.0.0",
-    "postgres-pool": "11.0.2",
-    "ts-mockito": "2.6.1",
-    "ts-node": "10.9.2",
+    "postgres-pool": "11.0.3",
     "typescript": "5.9.3",
-    "unbuild": "3.6.1"
+    "unbuild": "3.6.1",
+    "vitest": "4.0.18"
   },
   "scripts": {
     "build": "unbuild",
     "check:types": "tsc --noEmit --skipLibCheck",
-    "test": "mocha --loader=ts-node/esm tests/**/*.tests.ts",
+    "test": "npm run check:types && vitest run",
     "lint:markdown": "prettier --write '**/*.md' '!**/node_modules/**' '!**/dist/**' && markdownlint '**/*.md' --ignore '**/node_modules/**' --ignore '**/dist/**' --config=.github/linters/.markdown-lint.yml --fix",
     "lint:code": "eslint --fix",
     "lint": "run-p lint:*",