@stonyx/orm 0.2.1-beta.4 → 0.2.1-beta.41

package/.claude/index.md

@@ -3,6 +3,7 @@
 ## Detailed Guides
 
 - [Usage Patterns](usage-patterns.md) — Model definitions, serializers, transforms, CRUD, DB schema, persistence, access control, REST API, and include parameters
+- [Views](views.md) — Read-only computed views with aggregate helpers, in-memory resolver, and MySQL VIEW auto-generation
 - [Middleware Hooks System](hooks.md) — Before/after hooks for CRUD operations, halting, context object, change detection, and testing
 - [Code Style Rules](code-style-rules.md) — Strict prettier/eslint rules to apply across all Stonyx projects
 
@@ -21,6 +22,7 @@
 5. **REST API Generation**: Auto-generated RESTful endpoints with access control
 6. **Data Transformation**: Custom type conversion and formatting
 7. **Middleware Hooks**: Before/after hooks for all CRUD operations with halting capability
+8. **Views**: Read-only computed projections over model data with aggregate helpers (count, avg, sum, min, max)
 
 ---
 
@@ -38,6 +40,9 @@
 8. **Include Logic** (inline in [src/orm-request.js](src/orm-request.js)) - Parses include query params, traverses relationships, collects and deduplicates included records
 9. **Hooks** ([src/hooks.js](src/hooks.js)) - Middleware-based hook registry for CRUD lifecycle
 10. **MySQL Driver** ([src/mysql/mysql-db.js](src/mysql/mysql-db.js)) - MySQL persistence, migrations, schema introspection. Loads records in topological order. `_rowToRawData()` converts TINYINT(1) → boolean, remaps FK columns, strips timestamps.
+11. **View** ([src/view.js](src/view.js)) - Read-only base class for computed views (does NOT extend Model)
+12. **Aggregates** ([src/aggregates.js](src/aggregates.js)) - AggregateProperty class + helper functions (count, avg, sum, min, max)
+13. **ViewResolver** ([src/view-resolver.js](src/view-resolver.js)) - In-memory view resolver (iterates source model, computes aggregates + resolve map)
 
 ### Project Structure
 
@@ -65,6 +70,10 @@ stonyx-orm/
 │   ├── migrate.js                # JSON DB mode migration (file <-> directory)
 │   ├── commands.js               # CLI commands (db:migrate-*, etc.)
 │   ├── utils.js                  # Pluralize wrapper for dasherized names
+│   ├── plural-registry.js        # Plural name registry (populated at init, supports Model.pluralName overrides)
+│   ├── view.js                   # View base class (read-only, source, resolve, memory)
+│   ├── aggregates.js             # AggregateProperty + count/avg/sum/min/max helpers
+│   ├── view-resolver.js          # In-memory view resolver
 │   ├── exports/
 │   │   └── db.js                 # Convenience re-export of DB instance
 │   └── mysql/
@@ -85,6 +94,7 @@ stonyx-orm/
 │       ├── serializers/          # Example serializers
 │       ├── transforms/           # Custom transforms
 │       ├── access/               # Access control
+│       ├── views/                # Example views
 │       ├── db-schema.js          # DB schema
 │       └── payload.js            # Test data
 └── package.json
@@ -102,7 +112,8 @@ config.orm = {
     model: './models',
     serializer: './serializers',
     transform: './transforms',
-    access: './access'
+    access: './access',
+    view: './views'
   },
   db: {
     autosave: 'false',
@@ -150,6 +161,7 @@ The ORM supports two storage modes, configured via `db.mode`:
 - Models: `{PascalCase}Model` (e.g., `AnimalModel`)
 - Serializers: `{PascalCase}Serializer` (e.g., `AnimalSerializer`)
 - Transforms: Original filename (e.g., `animal.js`)
+- Plural names: Auto-pluralized by default (e.g., `animal` → `animals`). Override with `static pluralName` on the model class (e.g., `static pluralName = 'people'`). All call sites use `getPluralName()` from the plural registry, **not** `pluralize()` directly.
 
 ---
 
@@ -227,9 +239,10 @@ The ORM supports two storage modes, configured via `db.mode`:
 **Import the ORM:**
 ```javascript
 import {
-  Orm, Model, Serializer, attr, hasMany, belongsTo,
+  Orm, Model, View, Serializer, attr, hasMany, belongsTo,
   createRecord, updateRecord, store,
-  beforeHook, afterHook, clearHook, clearAllHooks
+  beforeHook, afterHook, clearHook, clearAllHooks,
+  count, avg, sum, min, max
 } from '@stonyx/orm';
 ```
 

package/.claude/usage-patterns.md

@@ -31,6 +31,23 @@ export default class AnimalModel extends Model {
 - Use `hasMany(modelName)` for one-to-many
 - Getters work as computed properties
 - Relationships auto-establish bidirectionally
+- Override auto-pluralization with `static pluralName` (see [Overriding Plural Names](#overriding-plural-names))
+
+### Overriding Plural Names
+
+By default, model names are auto-pluralized (e.g., `animal` → `animals`) for REST routes, JSON:API URLs, and DB table names. When auto-pluralization produces the wrong result, override it with `static pluralName`:
+
+```javascript
+import { Model, attr } from '@stonyx/orm';
+
+export default class PersonModel extends Model {
+  static pluralName = 'people';
+
+  name = attr('string');
+}
+```
+
+The override is picked up automatically during ORM initialization — no additional registration is needed. All internal call sites (REST routes, JSON:API type references, MySQL table names, foreign key references) use the overridden value.
 
 ## 2. Serializers (Data Transformation)
 
@@ -215,3 +232,69 @@ GET /scenes/e001-s001?include=slides.dialogue.character
 - `traverseIncludePath()` - Recursively traverses relationship paths
 - `collectIncludedRecords()` - Orchestrates traversal and deduplication
 - All implemented in [src/orm-request.js](src/orm-request.js)
+
+## 10. Views (Read-Only Computed Data)
+
+Views are read-only projections that compute derived data from existing models. They work in both JSON mode (in-memory) and MySQL mode (auto-generated SQL VIEWs). See the full guide at [views.md](views.md).
+
+### Defining a View
+
+```javascript
+// views/owner-stats.js
+import { View, attr, belongsTo, count, avg } from '@stonyx/orm';
+
+export default class OwnerStatsView extends View {
+  static source = 'owner';  // Required: model whose records produce view records
+
+  animalCount = count('pets');     // COUNT of hasMany relationship
+  averageAge = avg('pets', 'age'); // AVG of a field on related records
+  owner = belongsTo('owner');      // Link back to source record
+}
+```
+
+### Aggregate Helpers
+
+| Helper | Example | JS Behavior | MySQL |
+|--------|---------|-------------|-------|
+| `count(rel)` | `count('pets')` | `records.length` | `COUNT(table.id)` |
+| `avg(rel, field)` | `avg('pets', 'age')` | Average of values | `AVG(table.field)` |
+| `sum(rel, field)` | `sum('pets', 'age')` | Sum of values | `SUM(table.field)` |
+| `min(rel, field)` | `min('pets', 'age')` | Minimum value | `MIN(table.field)` |
+| `max(rel, field)` | `max('pets', 'age')` | Maximum value | `MAX(table.field)` |
+
+### Resolve Map (Escape Hatch)
+
+For fields that can't be expressed as aggregates:
+
+```javascript
+export default class OwnerStatsView extends View {
+  static source = 'owner';
+  static resolve = {
+    gender: 'gender',              // String path from source data
+    score: (owner) => owner.__data.age * 10,  // Function
+  };
+
+  gender = attr('string');  // Must also define as attr()
+  score = attr('number');
+  animalCount = count('pets');
+}
+```
+
+### Querying Views
+
+```javascript
+const stats = await store.findAll('owner-stats');
+const stat = await store.find('owner-stats', ownerId);
+```
+
+### Read-Only Enforcement
+
+```javascript
+createRecord('owner-stats', data);   // Throws: Cannot create records for read-only view
+updateRecord(viewRecord, data);       // Throws: Cannot update records for read-only view
+store.remove('owner-stats', id);      // Throws: Cannot remove records from read-only view
+```
+
+### REST API
+
+Only GET endpoints are mounted for views — no POST, PATCH, or DELETE.

package/.claude/views.md

@@ -0,0 +1,292 @@
+# Views
+
+Views are read-only, model-like structures that compute derived data from existing models. They work in both JSON file mode (in-memory computation) and MySQL mode (auto-generated SQL VIEWs).
+
+## What Views Are
+
+A View defines a read-only projection over source model data. Use views when you need:
+- Aggregated data (counts, averages, sums) derived from model relationships
+- Computed read-only summaries that shouldn't be persisted as separate records
+- MySQL VIEWs that are auto-generated from your JavaScript definition
+
+## Defining a View
+
+Views extend the `View` base class and are placed in the `views/` directory (configurable via `paths.view`).
+
+```javascript
+// views/owner-stats.js
+import { View, attr, belongsTo, count, avg } from '@stonyx/orm';
+
+export default class OwnerStatsView extends View {
+  static source = 'owner'; // The model whose records are iterated
+
+  animalCount = count('pets');    // COUNT of hasMany relationship
+  averageAge = avg('pets', 'age'); // AVG of a field on related records
+  owner = belongsTo('owner');     // Link back to the source record
+}
+```
+
+### File Naming
+
+- File: `owner-stats.js` → Class: `OwnerStatsView` → Store name: `'owner-stats'`
+- Directory: configured via `paths.view` (default: `'./views'`)
+- Environment variable: `ORM_VIEW_PATH`
+
+### Key Static Properties
+
+| Property | Default | Description |
+|----------|---------|-------------|
+| `source` | `undefined` | **(Required)** The model name whose records produce view records |
+| `groupBy` | `undefined` | Field name to group source records by (one view record per unique value) |
+| `resolve` | `undefined` | Optional escape-hatch map for custom derivations |
+| `memory` | `false` | `false` = computed on demand; `true` = cached on startup |
+| `readOnly` | `true` | **Enforced** — cannot be overridden to `false` |
+| `pluralName` | `undefined` | Custom plural name (same as Model) |
+
+## Aggregate Helpers
+
+Aggregate helpers define fields that compute values from related records. Each helper knows both its JavaScript computation logic and its MySQL SQL translation.
+
+| Helper | JS Behavior | MySQL Translation |
+|--------|-------------|-------------------|
+| `count(relationship)` | `relatedRecords.length` | `COUNT(table.id)` |
+| `avg(relationship, field)` | Average of field values | `AVG(table.field)` |
+| `sum(relationship, field)` | Sum of field values | `SUM(table.field)` |
+| `min(relationship, field)` | Minimum field value | `MIN(table.field)` |
+| `max(relationship, field)` | Maximum field value | `MAX(table.field)` |
+
+### Empty/Null Handling
+
+- `count` with empty/null relationship → `0`
+- `avg` with empty/null relationship → `0`
+- `sum` with empty/null relationship → `0`
+- `min` with empty/null relationship → `null`
+- `max` with empty/null relationship → `null`
+- Non-numeric values are filtered/treated as 0
+
+## Resolve Map (Escape Hatch)
+
+For computed fields that can't be expressed as aggregates, use `static resolve`:
+
+```javascript
+export default class OwnerStatsView extends View {
+  static source = 'owner';
+
+  static resolve = {
+    gender: 'gender',           // String path: maps from source record data
+    score: (owner) => {         // Function: custom computation
+      return owner.__data.age * 10;
+    },
+    nestedVal: 'details.nested', // Nested string paths supported
+  };
+
+  // Must also define as attr() for the serializer to process
+  gender = attr('string');
+  score = attr('number');
+  nestedVal = attr('passthrough');
+
+  animalCount = count('pets');
+}
+```
+
+**Important:** Each resolve map entry needs a corresponding `attr()` field definition on the view.
+
+## GroupBy Views
+
+GroupBy views produce one view record per unique value of a field on the source model, with aggregates computed within each group.
+
+### Defining a GroupBy View
+
+```javascript
+import { View, attr, count, avg, sum } from '@stonyx/orm';
+
+export default class AnimalCountBySizeView extends View {
+  static source = 'animal';
+  static groupBy = 'size';    // Group animals by their size field
+
+  id = attr('string');         // The group key becomes the id
+  animalCount = count();       // Count records in each group
+  averageAge = avg('age');     // Average of 'age' field within each group
+}
+```
+
+### Aggregate Helpers in GroupBy Views
+
+In groupBy views, aggregate helpers operate on the group's records rather than on relationships:
+
+| Helper | GroupBy Behavior | MySQL Translation |
+|--------|-----------------|-------------------|
+| `count()` | Number of records in the group | `COUNT(*)` |
+| `sum('field')` | Sum of field across group records | `SUM(source.field)` |
+| `avg('field')` | Average of field across group records | `AVG(source.field)` |
+| `min('field')` | Minimum field value in the group | `MIN(source.field)` |
+| `max('field')` | Maximum field value in the group | `MAX(source.field)` |
+
+Relationship aggregates (e.g., `count('traits')`) also work — they flatten related records across all group members and aggregate the combined set.
+
+### Resolve Map in GroupBy Views
+
+The resolve map behaves differently in groupBy views:
+- **Function resolvers** receive the **array of group records** (not a single record)
+- **String path resolvers** take the value from the **first record** in the group
+
+```javascript
+export default class LeagueStatsView extends View {
+  static source = 'game-stats';
+  static groupBy = 'competition';
+
+  static resolve = {
+    totalGoals: (groupRecords) => {
+      return groupRecords.reduce((sum, r) => {
+        const fs = r.__data.finalScore;
+        return fs ? sum + fs[0] + fs[1] : sum;
+      }, 0);
+    },
+  };
+
+  matchCount = count();
+  totalGoals = attr('number');
+}
+```
+
+### MySQL DDL for GroupBy Views
+
+```sql
+CREATE OR REPLACE VIEW `animal-count-by-sizes` AS
+SELECT
+  `animals`.`size` AS `id`,
+  COUNT(*) AS `animalCount`,
+  AVG(`animals`.`age`) AS `averageAge`
+FROM `animals`
+GROUP BY `animals`.`size`
+```
+
+## Querying Views
+
+Views use the same store API as models:
+
+```javascript
+// All view records (computed fresh each call in JSON mode)
+const stats = await store.findAll('owner-stats');
+
+// Single view record by source ID
+const stat = await store.find('owner-stats', ownerId);
+
+// With conditions
+const filtered = await store.findAll('owner-stats', { animalCount: 5 });
+```
+
+## Read-Only Enforcement
+
+Views are strictly read-only at all layers:
+
+```javascript
+// All of these throw errors:
+createRecord('owner-stats', data);        // Error: Cannot create records for read-only view
+updateRecord(viewRecord, data);            // Error: Cannot update records for read-only view
+store.remove('owner-stats', id);           // Error: Cannot remove records from read-only view
+
+// Internal use only — bypasses guard:
+createRecord('owner-stats', data, { isDbRecord: true }); // Used by resolver/loader
+```
+
+## REST API Behavior
+
+When a view is included in an access configuration, only GET endpoints are mounted:
+
+- `GET /view-plural-name` — Returns list of view records
+- `GET /view-plural-name/:id` — Returns single view record
+- `GET /view-plural-name/:id/{relationship}` — Related resources
+- No POST, PATCH, DELETE endpoints
+
+## JSON Mode (In-Memory Resolver)
+
+In JSON/non-MySQL mode, the ViewResolver:
+
+1. Iterates all records of the `source` model from the store
+2. For each source record:
+   - Computes aggregate properties from relationships
+   - Applies resolve map entries (string paths or functions)
+   - Maps regular attr fields from source data
+3. Creates view records via `createRecord` with `isDbRecord: true`
+4. Returns computed array
+
+## MySQL Mode
+
+In MySQL mode:
+
+1. **Schema introspection** generates VIEW metadata via `introspectViews()`
+2. **DDL generation** creates `CREATE OR REPLACE VIEW` SQL from aggregates and relationships
+3. **Queries** use `SELECT * FROM \`view_name\`` just like tables
+4. **Migrations** include `CREATE OR REPLACE VIEW` after table statements
+5. **persist()** is a no-op for views
+6. **loadMemoryRecords()** loads views with `memory: true` from the MySQL VIEW
+
+### Generated SQL Example
+
+For `OwnerStatsView` with `count('pets')` and `avg('pets', 'age')`:
+
+```sql
+CREATE OR REPLACE VIEW `owner-stats` AS
+SELECT
+  `owners`.`id` AS `id`,
+  COUNT(`animals`.`id`) AS `animalCount`,
+  AVG(`animals`.`age`) AS `avgAge`
+FROM `owners`
+  LEFT JOIN `animals` ON `animals`.`owner_id` = `owners`.`id`
+GROUP BY `owners`.`id`
+```
+
+## Migration Support
+
+Views are handled in migrations alongside tables:
+
+- **Added views** → `CREATE OR REPLACE VIEW ...` in UP, `DROP VIEW IF EXISTS ...` in DOWN
+- **Removed views** → Commented `DROP VIEW` warning in UP (matching model removal pattern)
+- **Changed views** → `CREATE OR REPLACE VIEW ...` in UP (replaces automatically)
+- Views appear AFTER table statements in migrations (dependency order)
+- Snapshots include view entries with `isView: true` and `viewQuery`
+
+## Memory Flag
+
+- `static memory = false` (default) — View records are computed fresh on each query
+- `static memory = true` — View records are loaded from MySQL VIEW on startup and cached
+
+## Testing Views
+
+```javascript
+import QUnit from 'qunit';
+import { store } from '@stonyx/orm';
+
+QUnit.test('view returns computed data', async function(assert) {
+  // Create source data
+  createRecord('owner', { id: 1, name: 'Alice' }, { serialize: false });
+  createRecord('animal', { id: 1, age: 3, owner: 1 }, { serialize: false });
+
+  // Query the view
+  const results = await store.findAll('owner-stats');
+  const stat = results.find(r => r.id === 1);
+
+  assert.strictEqual(stat.__data.animalCount, 1);
+});
+```
+
+## Architecture
+
+### Source Files
+
+| File | Purpose |
+|------|---------|
+| `src/view.js` | View base class |
+| `src/aggregates.js` | AggregateProperty class + helper functions |
+| `src/view-resolver.js` | In-memory view resolver |
+| `src/mysql/schema-introspector.js` | `introspectViews()`, `buildViewDDL()` |
+| `src/mysql/migration-generator.js` | `diffViewSnapshots()`, view migration generation |
+
+### Key Design Decisions
+
+1. **View does NOT extend Model** — conceptually separate; shared behavior is minimal
+2. **Driver-agnostic API** — No SQL in view definitions; MySQL driver generates SQL automatically
+3. **Aggregate helpers follow the transform pattern** — Each knows both JS computation and MySQL mapping
+4. **Resolve map mirrors Serializer.map** — String paths or function resolvers
+5. **View schemas are separate** — `introspectViews()` is separate from `introspectModels()`

package/README.md

@@ -109,6 +109,22 @@ export default class OwnerModel extends Model {
 }
 ```
 
+### Overriding Plural Names
+
+By default, model names are auto-pluralized for REST routes, JSON:API URLs, and DB table names (e.g., `animal` → `animals`). When auto-pluralization produces the wrong result, override it with `static pluralName`:
+
+```js
+import { Model, attr } from '@stonyx/orm';
+
+export default class PersonModel extends Model {
+  static pluralName = 'people';
+
+  name = attr('string');
+}
+```
+
+The override is picked up automatically during ORM initialization. All routes, JSON:API type references, and MySQL table names will use the overridden value.
+
 ## Serializers
 
 Based on the following sample payload structure which represents a poorly structure third-party data source:
@@ -207,6 +223,27 @@ Set the `MYSQL_HOST` environment variable to enable MySQL persistence. The ORM l
 | `stonyx db:migrate:rollback` | Rollback the most recent migration |
 | `stonyx db:migrate:status` | Show migration status |
 
+### Running MySQL Tests
+
+The ORM includes integration tests that run against a real MySQL database. These are optional — all other tests work without MySQL.
+
+**One-time setup:**
+
+```bash
+# Requires local MySQL 8.0+ running
+./scripts/setup-test-db.sh
+```
+
+This creates a `stonyx_orm_test` database with a `stonyx_test` user. Safe to re-run.
+
+**Running tests:**
+
+```bash
+npm test
+```
+
+MySQL integration tests run automatically when MySQL is available. In CI (where `CI=true`), they skip gracefully.
+
 ## REST Server Integration
 
 The ORM can automatically register REST routes using your access classes.

package/config/environment.js

@@ -4,6 +4,7 @@ const {
   ORM_REST_ROUTE,
   ORM_SERIALIZER_PATH,
   ORM_TRANSFORM_PATH,
+  ORM_VIEW_PATH,
   ORM_USE_REST_SERVER,
   DB_AUTO_SAVE,
   DB_FILE,
@@ -36,7 +37,8 @@ export default {
     access: ORM_ACCESS_PATH ?? './access', // Optional for restServer access hooks
     model: ORM_MODEL_PATH ?? './models',
     serializer: ORM_SERIALIZER_PATH ?? './serializers',
-    transform: ORM_TRANSFORM_PATH ?? './transforms'
+    transform: ORM_TRANSFORM_PATH ?? './transforms',
+    view: ORM_VIEW_PATH ?? './views'
   },
   mysql: MYSQL_HOST ? {
     host: MYSQL_HOST ?? 'localhost',

package/package.json

@@ -4,7 +4,7 @@
     "stonyx-async",
     "stonyx-module"
   ],
-  "version": "0.2.1-beta.4",
+  "version": "0.2.1-beta.41",
   "description": "",
   "main": "src/main.js",
   "type": "module",
@@ -33,21 +33,26 @@
   },
   "homepage": "https://github.com/abofs/stonyx-orm#readme",
   "dependencies": {
-    "stonyx": "0.2.3-beta.2",
-    "@stonyx/events": "0.1.1-beta.2",
-    "@stonyx/cron": "0.2.1-beta.3"
+    "@stonyx/cron": "0.2.1-beta.15",
+    "@stonyx/events": "0.1.1-beta.7",
+    "stonyx": "0.2.3-beta.6"
   },
   "peerDependencies": {
+    "@stonyx/rest-server": ">=0.2.1-beta.14",
     "mysql2": "^3.0.0"
   },
   "peerDependenciesMeta": {
     "mysql2": {
       "optional": true
+    },
+    "@stonyx/rest-server": {
+      "optional": true
     }
   },
   "devDependencies": {
-    "@stonyx/rest-server": "0.2.1-beta.4",
-    "@stonyx/utils": "0.2.3-beta.3",
+    "@stonyx/rest-server": "0.2.1-beta.19",
+    "@stonyx/utils": "0.2.3-beta.5",
+    "mysql2": "^3.20.0",
     "qunit": "^2.24.1",
     "sinon": "^21.0.0"
   },

package/scripts/setup-test-db.sh

@@ -0,0 +1,21 @@
+#!/usr/bin/env bash
+# scripts/setup-test-db.sh
+# Creates the stonyx_orm_test database and stonyx_test user.
+# Idempotent — safe to re-run. Requires local MySQL with root access.
+
+set -euo pipefail
+
+echo "Setting up stonyx-orm test database..."
+
+mysql -u root <<SQL
+CREATE DATABASE IF NOT EXISTS stonyx_orm_test CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
+CREATE USER IF NOT EXISTS 'stonyx_test'@'localhost' IDENTIFIED BY 'stonyx_test';
+GRANT ALL PRIVILEGES ON stonyx_orm_test.* TO 'stonyx_test'@'localhost';
+FLUSH PRIVILEGES;
+SQL
+
+echo ""
+echo "Done! Test database 'stonyx_orm_test' is ready."
+echo "User: stonyx_test / Password: stonyx_test"
+echo ""
+echo "Run tests with: npm test"

package/src/aggregates.js

@@ -0,0 +1,93 @@
+export class AggregateProperty {
+  constructor(aggregateType, relationship, field) {
+    this.aggregateType = aggregateType;
+    this.relationship = relationship;
+    this.field = field;
+    this.mysqlFunction = aggregateType.toUpperCase();
+    this.resultType = aggregateType === 'avg' ? 'float' : 'number';
+  }
+
+  compute(relatedRecords) {
+    if (!relatedRecords || !Array.isArray(relatedRecords) || relatedRecords.length === 0) {
+      if (this.aggregateType === 'min' || this.aggregateType === 'max') return null;
+      return 0;
+    }
+
+    switch (this.aggregateType) {
+      case 'count':
+        return relatedRecords.length;
+
+      case 'sum':
+        return relatedRecords.reduce((acc, record) => {
+          const val = parseFloat(record?.__data?.[this.field] ?? record?.[this.field]);
+          return acc + (isNaN(val) ? 0 : val);
+        }, 0);
+
+      case 'avg': {
+        let sum = 0;
+        let count = 0;
+        for (const record of relatedRecords) {
+          const val = parseFloat(record?.__data?.[this.field] ?? record?.[this.field]);
+          if (!isNaN(val)) {
+            sum += val;
+            count++;
+          }
+        }
+        return count === 0 ? 0 : sum / count;
+      }
+
+      case 'min': {
+        let min = null;
+        for (const record of relatedRecords) {
+          const val = parseFloat(record?.__data?.[this.field] ?? record?.[this.field]);
+          if (!isNaN(val) && (min === null || val < min)) min = val;
+        }
+        return min;
+      }
+
+      case 'max': {
+        let max = null;
+        for (const record of relatedRecords) {
+          const val = parseFloat(record?.__data?.[this.field] ?? record?.[this.field]);
+          if (!isNaN(val) && (max === null || val > max)) max = val;
+        }
+        return max;
+      }
+
+      default:
+        return null;
+    }
+  }
+}
+
+export function count(relationship) {
+  return new AggregateProperty('count', relationship);
+}
+
+export function avg(relationshipOrField, field) {
+  if (field !== undefined) {
+    return new AggregateProperty('avg', relationshipOrField, field);
+  }
+  return new AggregateProperty('avg', undefined, relationshipOrField);
+}
+
+export function sum(relationshipOrField, field) {
+  if (field !== undefined) {
+    return new AggregateProperty('sum', relationshipOrField, field);
+  }
+  return new AggregateProperty('sum', undefined, relationshipOrField);
+}
+
+export function min(relationshipOrField, field) {
+  if (field !== undefined) {
+    return new AggregateProperty('min', relationshipOrField, field);
+  }
+  return new AggregateProperty('min', undefined, relationshipOrField);
+}
+
+export function max(relationshipOrField, field) {
+  if (field !== undefined) {
+    return new AggregateProperty('max', relationshipOrField, field);
+  }
+  return new AggregateProperty('max', undefined, relationshipOrField);
+}