@stonyx/orm 0.2.1-alpha.10 → 0.2.1-alpha.11

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
 
@@ -66,6 +71,9 @@ stonyx-orm/
 │   ├── 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/
@@ -86,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
@@ -103,7 +112,8 @@ config.orm = {
     model: './models',
     serializer: './serializers',
     transform: './transforms',
-    access: './access'
+    access: './access',
+    view: './views'
   },
   db: {
     autosave: 'false',
@@ -229,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

@@ -232,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,221 @@
+# 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 |
+| `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.
+
+## 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/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-alpha.10",
+  "version": "0.2.1-alpha.11",
   "description": "",
   "main": "src/main.js",
   "type": "module",
@@ -33,9 +33,9 @@
   },
   "homepage": "https://github.com/abofs/stonyx-orm#readme",
   "dependencies": {
-    "stonyx": "0.2.3-beta.4",
-    "@stonyx/events": "0.1.1-beta.5",
-    "@stonyx/cron": "0.2.1-beta.8"
+    "stonyx": "0.2.3-beta.5",
+    "@stonyx/events": "0.1.1-beta.6",
+    "@stonyx/cron": "0.2.1-beta.10"
   },
   "peerDependencies": {
     "mysql2": "^3.0.0"
@@ -46,7 +46,7 @@
     }
   },
   "devDependencies": {
-    "@stonyx/rest-server": "0.2.1-beta.10",
+    "@stonyx/rest-server": "0.2.1-beta.14",
     "@stonyx/utils": "0.2.3-beta.4",
     "qunit": "^2.24.1",
     "sinon": "^21.0.0"

package/src/aggregates.js

@@ -0,0 +1,81 @@
+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(relationship, field) {
+  return new AggregateProperty('avg', relationship, field);
+}
+
+export function sum(relationship, field) {
+  return new AggregateProperty('sum', relationship, field);
+}
+
+export function min(relationship, field) {
+  return new AggregateProperty('min', relationship, field);
+}
+
+export function max(relationship, field) {
+  return new AggregateProperty('max', relationship, field);
+}

package/src/index.js

@@ -15,17 +15,20 @@
  */
 
 import Model from './model.js';
+import View from './view.js';
 import Serializer from './serializer.js';
 
 import attr from './attr.js';
 import belongsTo from './belongs-to.js';
 import hasMany from './has-many.js';
 import { createRecord, updateRecord } from './manage-record.js';
+import { count, avg, sum, min, max } from './aggregates.js';
 
 export { default } from './main.js';
 export { store, relationships } from './main.js';
-export { Model, Serializer }; // base classes
+export { Model, View, Serializer }; // base classes
 export { attr, belongsTo, hasMany, createRecord, updateRecord }; // helpers
+export { count, avg, sum, min, max }; // aggregate helpers
 export { beforeHook, afterHook, clearHook, clearAllHooks } from './hooks.js'; // middleware hooks
 
 // Store API:

package/src/main.js

@@ -37,6 +37,7 @@ export default class Orm {
   
   models = {};
   serializers = {};
+  views = {};
   transforms = { ...baseTransforms };
   warnings = new Set();
 
@@ -79,14 +80,28 @@ export default class Orm {
     // Wait for imports before db & rest server setup
     await Promise.all(promises);
 
+    // Discover views from paths.view (separate from model/serializer/transform)
+    if (paths.view) {
+      await forEachFileImport(paths.view, (exported, { name }) => {
+        const alias = `${kebabCaseToPascalCase(name)}View`;
+        Orm.store.set(name, new Map());
+        registerPluralName(name, exported);
+        this.views[alias] = exported;
+      }, { ignoreAccessFailure: true, rawName: true, recursive: true, recursiveNaming: true });
+    }
+
     // Setup event names for hooks after models are loaded
     const eventNames = [];
     const operations = ['list', 'get', 'create', 'update', 'delete'];
+    const viewOperations = ['list', 'get'];
     const timings = ['before', 'after'];
 
     for (const modelName of Orm.store.data.keys()) {
+      const isView = this.isView(modelName);
+      const ops = isView ? viewOperations : operations;
+
       for (const timing of timings) {
-        for (const operation of operations) {
+        for (const operation of ops) {
           eventNames.push(`${timing}:${operation}:${modelName}`);
         }
       }
@@ -141,13 +156,27 @@ export default class Orm {
 
   getRecordClasses(modelName) {
     const modelClassPrefix = kebabCaseToPascalCase(modelName);
-  
+
+    // Check views first, then models
+    const viewClass = this.views[`${modelClassPrefix}View`];
+    if (viewClass) {
+      return {
+        modelClass: viewClass,
+        serializerClass: this.serializers[`${modelClassPrefix}Serializer`] || Serializer
+      };
+    }
+
     return {
       modelClass: this.models[`${modelClassPrefix}Model`],
       serializerClass: this.serializers[`${modelClassPrefix}Serializer`] || Serializer
     };
   }
 
+  isView(modelName) {
+    const modelClassPrefix = kebabCaseToPascalCase(modelName);
+    return !!this.views[`${modelClassPrefix}View`];
+  }
+
   // Queue warnings to avoid the same error from being logged in the same iteration
   warn(message) {
     this.warnings.add(message);

package/src/manage-record.js

@@ -14,6 +14,11 @@ export function createRecord(modelName, rawData={}, userOptions={}) {
 
   if (!initialized && !options.isDbRecord) throw new Error('ORM is not ready');
 
+  // Guard: read-only views cannot have records created directly
+  if (orm?.isView?.(modelName) && !options.isDbRecord) {
+    throw new Error(`Cannot create records for read-only view '${modelName}'`);
+  }
+
   const modelStore = store.get(modelName);
   const globalRelationships = relationships.get('global');
   const pendingRelationships = relationships.get('pending');
@@ -83,6 +88,12 @@ export function createRecord(modelName, rawData={}, userOptions={}) {
 export function updateRecord(record, rawData, userOptions={}) {
   if (!rawData) throw new Error('rawData must be passed in to updateRecord call');
 
+  // Guard: read-only views cannot be updated
+  const modelName = record?.__model?.__name;
+  if (modelName && Orm.instance?.isView?.(modelName)) {
+    throw new Error(`Cannot update records for read-only view '${modelName}'`);
+  }
+
   const options = { ...defaultOptions, ...userOptions, update:true };
 
   record.serialize(rawData, options);

package/src/mysql/migration-generator.js

@@ -1,4 +1,4 @@
-import { introspectModels, buildTableDDL, schemasToSnapshot, getTopologicalOrder } from './schema-introspector.js';
+import { introspectModels, introspectViews, buildTableDDL, buildViewDDL, schemasToSnapshot, viewSchemasToSnapshot, getTopologicalOrder } from './schema-introspector.js';
 import { readFile, createFile, createDirectory, fileExists } from '@stonyx/utils/file';
 import path from 'path';
 import config from 'stonyx/config';
@@ -16,9 +16,18 @@ export async function generateMigration(description = 'migration') {
   const previousSnapshot = await loadLatestSnapshot(migrationsPath);
   const diff = diffSnapshots(previousSnapshot, currentSnapshot);
 
+  // Don't return early — check view changes too before deciding
   if (!diff.hasChanges) {
-    log.db('No schema changes detected.');
-    return null;
+    // Check if there are view changes before returning null
+    const viewSchemasPrelim = introspectViews();
+    const currentViewSnapshotPrelim = viewSchemasToSnapshot(viewSchemasPrelim);
+    const previousViewSnapshotPrelim = extractViewsFromSnapshot(previousSnapshot);
+    const viewDiffPrelim = diffViewSnapshots(previousViewSnapshotPrelim, currentViewSnapshotPrelim);
+
+    if (!viewDiffPrelim.hasChanges) {
+      log.db('No schema changes detected.');
+      return null;
+    }
   }
 
   const upStatements = [];
@@ -85,17 +94,71 @@ export async function generateMigration(description = 'migration') {
     downStatements.push(`ALTER TABLE \`${table}\` ADD FOREIGN KEY (\`${column}\`) REFERENCES \`${references.references}\`(\`${references.column}\`) ON DELETE SET NULL;`);
   }
 
+  // View migrations — views are created AFTER tables (dependency order)
+  const viewSchemas = introspectViews();
+  const currentViewSnapshot = viewSchemasToSnapshot(viewSchemas);
+  const previousViewSnapshot = extractViewsFromSnapshot(previousSnapshot);
+  const viewDiff = diffViewSnapshots(previousViewSnapshot, currentViewSnapshot);
+
+  if (viewDiff.hasChanges) {
+    upStatements.push('');
+    upStatements.push('-- Views');
+    downStatements.push('');
+    downStatements.push('-- Views');
+
+    // Added views
+    for (const name of viewDiff.addedViews) {
+      try {
+        const ddl = buildViewDDL(name, viewSchemas[name], schemas);
+        upStatements.push(ddl + ';');
+        downStatements.unshift(`DROP VIEW IF EXISTS \`${viewSchemas[name].viewName}\`;`);
+      } catch (error) {
+        upStatements.push(`-- WARNING: Could not generate DDL for view '${name}': ${error.message}`);
+      }
+    }
+
+    // Removed views
+    for (const name of viewDiff.removedViews) {
+      upStatements.push(`-- WARNING: View '${name}' was removed. Uncomment to drop view:`);
+      upStatements.push(`-- DROP VIEW IF EXISTS \`${previousViewSnapshot[name].viewName}\`;`);
+      downStatements.push(`-- Recreate view for removed view '${name}' manually if needed`);
+    }
+
+    // Changed views (source or aggregates changed)
+    for (const name of viewDiff.changedViews) {
+      try {
+        const ddl = buildViewDDL(name, viewSchemas[name], schemas);
+        upStatements.push(ddl + ';');
+      } catch (error) {
+        upStatements.push(`-- WARNING: Could not generate DDL for changed view '${name}': ${error.message}`);
+      }
+    }
+  }
+
+  const combinedHasChanges = diff.hasChanges || viewDiff.hasChanges;
+
+  if (!combinedHasChanges) {
+    log.db('No schema changes detected.');
+    return null;
+  }
+
+  // Merge view snapshot into the main snapshot
+  const combinedSnapshot = { ...currentSnapshot };
+  for (const [name, viewSnap] of Object.entries(currentViewSnapshot)) {
+    combinedSnapshot[name] = viewSnap;
+  }
+
   const sanitizedDescription = description.replace(/\s+/g, '_').replace(/[^a-zA-Z0-9_]/g, '');
   const timestamp = Math.floor(Date.now() / 1000);
   const filename = `${timestamp}_${sanitizedDescription}.sql`;
   const content = `-- UP\n${upStatements.join('\n')}\n\n-- DOWN\n${downStatements.join('\n')}\n`;
 
   await createFile(path.join(migrationsPath, filename), content);
-  await createFile(path.join(migrationsPath, '.snapshot.json'), JSON.stringify(currentSnapshot, null, 2));
+  await createFile(path.join(migrationsPath, '.snapshot.json'), JSON.stringify(combinedSnapshot, null, 2));
 
   log.db(`Migration generated: ${filename}`);
 
-  return { filename, content, snapshot: currentSnapshot };
+  return { filename, content, snapshot: combinedSnapshot };
 }
 
 export async function loadLatestSnapshot(migrationsPath) {
@@ -186,3 +249,38 @@ export function detectSchemaDrift(schemas, snapshot) {
   const current = schemasToSnapshot(schemas);
   return diffSnapshots(snapshot, current);
 }
+
+export function extractViewsFromSnapshot(snapshot) {
+  const views = {};
+  for (const [name, entry] of Object.entries(snapshot)) {
+    if (entry.isView) views[name] = entry;
+  }
+  return views;
+}
+
+export function diffViewSnapshots(previous, current) {
+  const addedViews = [];
+  const removedViews = [];
+  const changedViews = [];
+
+  for (const name of Object.keys(current)) {
+    if (!previous[name]) {
+      addedViews.push(name);
+    } else if (
+      current[name].viewQuery !== previous[name].viewQuery ||
+      current[name].source !== previous[name].source
+    ) {
+      changedViews.push(name);
+    }
+  }
+
+  for (const name of Object.keys(previous)) {
+    if (!current[name]) {
+      removedViews.push(name);
+    }
+  }
+
+  const hasChanges = addedViews.length > 0 || removedViews.length > 0 || changedViews.length > 0;
+
+  return { hasChanges, addedViews, removedViews, changedViews };
+}

package/src/mysql/mysql-db.js

@@ -1,6 +1,6 @@
 import { getPool, closePool } from './connection.js';
 import { ensureMigrationsTable, getAppliedMigrations, getMigrationFiles, applyMigration, parseMigrationFile } from './migration-runner.js';
-import { introspectModels, getTopologicalOrder, schemasToSnapshot } from './schema-introspector.js';
+import { introspectModels, introspectViews, getTopologicalOrder, schemasToSnapshot } from './schema-introspector.js';
 import { loadLatestSnapshot, detectSchemaDrift } from './migration-generator.js';
 import { buildInsert, buildUpdate, buildDelete, buildSelect } from './query-builder.js';
 import { createRecord, store } from '@stonyx/orm';
@@ -14,7 +14,7 @@ import path from 'path';
 const defaultDeps = {
   getPool, closePool, ensureMigrationsTable, getAppliedMigrations,
   getMigrationFiles, applyMigration, parseMigrationFile,
-  introspectModels, getTopologicalOrder, schemasToSnapshot,
+  introspectModels, introspectViews, getTopologicalOrder, schemasToSnapshot,
   loadLatestSnapshot, detectSchemaDrift,
   buildInsert, buildUpdate, buildDelete, buildSelect,
   createRecord, store, confirm, readFile, getPluralName, config, log, path
@@ -148,6 +148,35 @@ export default class MysqlDB {
         throw error;
       }
     }
+
+    // Load views with memory: true
+    const viewSchemas = this.deps.introspectViews();
+
+    for (const [viewName, viewSchema] of Object.entries(viewSchemas)) {
+      const { modelClass: viewClass } = Orm.instance.getRecordClasses(viewName);
+      if (viewClass?.memory !== true) {
+        this.deps.log.db(`Skipping memory load for view '${viewName}' (memory: false)`);
+        continue;
+      }
+
+      const schema = { table: viewSchema.viewName, columns: viewSchema.columns || {}, foreignKeys: viewSchema.foreignKeys || {} };
+      const { sql, values } = this.deps.buildSelect(schema.table);
+
+      try {
+        const [rows] = await this.pool.execute(sql, values);
+
+        for (const row of rows) {
+          const rawData = this._rowToRawData(row, schema);
+          this.deps.createRecord(viewName, rawData, { isDbRecord: true, serialize: false, transform: false });
+        }
+      } catch (error) {
+        if (error.code === 'ER_NO_SUCH_TABLE') {
+          this.deps.log.db(`View '${viewSchema.viewName}' does not exist yet. Skipping load for '${viewName}'.`);
+          continue;
+        }
+        throw error;
+      }
+    }
   }
 
   /**
@@ -166,7 +195,16 @@ export default class MysqlDB {
    */
   async findRecord(modelName, id) {
     const schemas = this.deps.introspectModels();
-    const schema = schemas[modelName];
+    let schema = schemas[modelName];
+
+    // Check views if not found in models
+    if (!schema) {
+      const viewSchemas = this.deps.introspectViews();
+      const viewSchema = viewSchemas[modelName];
+      if (viewSchema) {
+        schema = { table: viewSchema.viewName, columns: viewSchema.columns || {}, foreignKeys: viewSchema.foreignKeys || {} };
+      }
+    }
 
     if (!schema) return undefined;
 
@@ -199,7 +237,16 @@ export default class MysqlDB {
    */
   async findAll(modelName, conditions) {
     const schemas = this.deps.introspectModels();
-    const schema = schemas[modelName];
+    let schema = schemas[modelName];
+
+    // Check views if not found in models
+    if (!schema) {
+      const viewSchemas = this.deps.introspectViews();
+      const viewSchema = viewSchemas[modelName];
+      if (viewSchema) {
+        schema = { table: viewSchema.viewName, columns: viewSchema.columns || {}, foreignKeys: viewSchema.foreignKeys || {} };
+      }
+    }
 
     if (!schema) return [];
 
@@ -277,6 +324,10 @@ export default class MysqlDB {
   }
 
   async persist(operation, modelName, context, response) {
+    // Views are read-only — no-op for all write operations
+    const Orm = (await import('@stonyx/orm')).default;
+    if (Orm.instance?.isView?.(modelName)) return;
+
     switch (operation) {
       case 'create':
         return this._persistCreate(modelName, context, response);

package/src/mysql/schema-introspector.js

@@ -3,6 +3,7 @@ import { getMysqlType } from './type-map.js';
 import { camelCaseToKebabCase } from '@stonyx/utils/string';
 import { getPluralName } from '../plural-registry.js';
 import { dbKey } from '../db.js';
+import { AggregateProperty } from '../aggregates.js';
 
 function getRelationshipInfo(property) {
   if (typeof property !== 'function') return null;
@@ -144,6 +145,145 @@ export function getTopologicalOrder(schemas) {
   return order;
 }
 
+export function introspectViews() {
+  const orm = Orm.instance;
+  if (!orm.views) return {};
+
+  const schemas = {};
+
+  for (const [viewKey, viewClass] of Object.entries(orm.views)) {
+    const name = camelCaseToKebabCase(viewKey.slice(0, -4)); // Remove 'View' suffix
+
+    const source = viewClass.source;
+    if (!source) continue;
+
+    const model = new viewClass(name);
+    const columns = {};
+    const foreignKeys = {};
+    const aggregates = {};
+    const relationships = { belongsTo: {}, hasMany: {} };
+
+    for (const [key, property] of Object.entries(model)) {
+      if (key.startsWith('__')) continue;
+      if (key === 'id') continue;
+
+      if (property instanceof AggregateProperty) {
+        aggregates[key] = property;
+        continue;
+      }
+
+      const relType = getRelationshipInfo(property);
+
+      if (relType === 'belongsTo') {
+        relationships.belongsTo[key] = true;
+        const modelName = camelCaseToKebabCase(key);
+        const fkColumn = `${key}_id`;
+        foreignKeys[fkColumn] = {
+          references: getPluralName(modelName),
+          column: 'id',
+        };
+      } else if (relType === 'hasMany') {
+        relationships.hasMany[key] = true;
+      } else if (property?.constructor?.name === 'ModelProperty') {
+        const transforms = Orm.instance.transforms;
+        columns[key] = getMysqlType(property.type, transforms[property.type]);
+      }
+    }
+
+    schemas[name] = {
+      viewName: getPluralName(name),
+      source,
+      columns,
+      foreignKeys,
+      aggregates,
+      relationships,
+      isView: true,
+      memory: viewClass.memory !== false ? false : false, // Views default to memory:false
+    };
+  }
+
+  return schemas;
+}
+
+export function buildViewDDL(name, viewSchema, modelSchemas = {}) {
+  if (!viewSchema.source) {
+    throw new Error(`View '${name}' must define a source model`);
+  }
+
+  const sourceModelName = viewSchema.source;
+  const sourceSchema = modelSchemas[sourceModelName];
+  const sourceTable = sourceSchema
+    ? sourceSchema.table
+    : getPluralName(sourceModelName);
+
+  const selectColumns = [];
+  const joins = [];
+  const hasAggregates = Object.keys(viewSchema.aggregates || {}).length > 0;
+
+  // Source table primary key
+  selectColumns.push(`\`${sourceTable}\`.\`id\` AS \`id\``);
+
+  // Aggregate columns
+  for (const [key, aggProp] of Object.entries(viewSchema.aggregates || {})) {
+    const relName = aggProp.relationship;
+    const relModelName = camelCaseToKebabCase(relName);
+    const relTable = getPluralName(relModelName);
+
+    if (aggProp.aggregateType === 'count') {
+      selectColumns.push(`${aggProp.mysqlFunction}(\`${relTable}\`.\`id\`) AS \`${key}\``);
+    } else {
+      const field = aggProp.field;
+      selectColumns.push(`${aggProp.mysqlFunction}(\`${relTable}\`.\`${field}\`) AS \`${key}\``);
+    }
+
+    // Add LEFT JOIN for the relationship if not already added
+    const joinKey = `${relTable}`;
+    if (!joins.find(j => j.table === joinKey)) {
+      // Determine the FK column: the related table has a belongsTo back to the source
+      const fkColumn = `${sourceModelName}_id`;
+      joins.push({
+        table: relTable,
+        condition: `\`${relTable}\`.\`${fkColumn}\` = \`${sourceTable}\`.\`id\``
+      });
+    }
+  }
+
+  // Regular columns (from resolve map string paths or direct attr fields)
+  for (const [key, mysqlType] of Object.entries(viewSchema.columns || {})) {
+    selectColumns.push(`\`${sourceTable}\`.\`${key}\` AS \`${key}\``);
+  }
+
+  // Build JOIN clauses
+  const joinClauses = joins.map(j =>
+    `LEFT JOIN \`${j.table}\` ON ${j.condition}`
+  ).join('\n  ');
+
+  // Build GROUP BY
+  const groupBy = hasAggregates ? `\nGROUP BY \`${sourceTable}\`.\`id\`` : '';
+
+  const viewName = viewSchema.viewName;
+  const sql = `CREATE OR REPLACE VIEW \`${viewName}\` AS\nSELECT\n  ${selectColumns.join(',\n  ')}\nFROM \`${sourceTable}\`${joinClauses ? '\n  ' + joinClauses : ''}${groupBy}`;
+
+  return sql;
+}
+
+export function viewSchemasToSnapshot(viewSchemas) {
+  const snapshot = {};
+
+  for (const [name, schema] of Object.entries(viewSchemas)) {
+    snapshot[name] = {
+      viewName: schema.viewName,
+      source: schema.source,
+      columns: { ...schema.columns },
+      foreignKeys: { ...schema.foreignKeys },
+      isView: true,
+      viewQuery: buildViewDDL(name, schema),
+    };
+  }
+
+  return snapshot;
+}
+
 export function schemasToSnapshot(schemas) {
   const snapshot = {};
 

package/src/orm-request.js

@@ -323,21 +323,27 @@ export default class OrmRequest extends Request {
     };
 
     // Wrap handlers with hooks
+    const isView = Orm.instance?.isView?.(model);
+
     this.handlers = {
       get: {
         '/': this._withHooks('list', getCollectionHandler),
         '/:id': this._withHooks('get', getSingleHandler),
         ...this._generateRelationshipRoutes(model, pluralizedModel, modelRelationships)
       },
-      patch: {
+    };
+
+    // Views are read-only — no write endpoints
+    if (!isView) {
+      this.handlers.patch = {
         '/:id': this._withHooks('update', updateHandler)
-      },
-      post: {
+      };
+      this.handlers.post = {
         '/': this._withHooks('create', createHandler)
-      },
-      delete: {
+      };
+      this.handlers.delete = {
         '/:id': this._withHooks('delete', deleteHandler)
-      }
+      };
     }
   }
 

package/src/serializer.js

@@ -86,6 +86,13 @@ export default class Serializer {
         continue;
       }
 
+      // Aggregate property handling — use the rawData value, not the aggregate descriptor
+      if (handler?.constructor?.name === 'AggregateProperty') {
+        parsedData[key] = data;
+        record[key] = data;
+        continue;
+      }
+
       // Direct assignment handling
       if (handler?.constructor?.name !== 'ModelProperty') {
         parsedData[key] = handler;

package/src/setup-rest-server.js

@@ -41,7 +41,7 @@ export default async function(route, accessPath, metaRoute) {
   // Remove "/" prefix and name mount point accordingly
   const name = route === '/' ? 'index' : (route[0] === '/' ? route.slice(1) : route);
 
-  // Configure endpoints for models with access configuration
+  // Configure endpoints for models and views with access configuration
   for (const [model, access] of Object.entries(accessFiles)) {
     const pluralizedModel = getPluralName(model);
     const modelName = name === 'index' ? pluralizedModel : `${name}/${pluralizedModel}`;

package/src/store.js

@@ -1,5 +1,6 @@
-import { relationships } from '@stonyx/orm';
+import Orm, { relationships } from '@stonyx/orm';
 import { TYPES } from './relationships.js';
+import ViewResolver from './view-resolver.js';
 
 export default class Store {
   constructor() {
@@ -28,6 +29,12 @@ export default class Store {
    * @returns {Promise<Record|undefined>}
    */
   async find(modelName, id) {
+    // For views in non-MySQL mode, use view resolver
+    if (Orm.instance?.isView?.(modelName) && !this._mysqlDb) {
+      const resolver = new ViewResolver(modelName);
+      return resolver.resolveOne(id);
+    }
+
     // For memory: true models, the store is authoritative
     if (this._isMemoryModel(modelName)) {
       return this.get(modelName, id);
@@ -50,6 +57,18 @@ export default class Store {
    * @returns {Promise<Record[]>}
    */
   async findAll(modelName, conditions) {
+    // For views in non-MySQL mode, use view resolver
+    if (Orm.instance?.isView?.(modelName) && !this._mysqlDb) {
+      const resolver = new ViewResolver(modelName);
+      const records = await resolver.resolveAll();
+
+      if (!conditions || Object.keys(conditions).length === 0) return records;
+
+      return records.filter(record =>
+        Object.entries(conditions).every(([key, value]) => record.__data[key] === value)
+      );
+    }
+
     // For memory: true models without conditions, return from store
     if (this._isMemoryModel(modelName) && !conditions) {
       const modelStore = this.get(modelName);
@@ -125,6 +144,11 @@ export default class Store {
   }
 
   remove(key, id) {
+    // Guard: read-only views cannot have records removed
+    if (Orm.instance?.isView?.(key)) {
+      throw new Error(`Cannot remove records from read-only view '${key}'`);
+    }
+
     if (id) return this.unloadRecord(key, id);
 
     this.unloadAllRecords(key);

package/src/view-resolver.js

@@ -0,0 +1,103 @@
+import Orm, { createRecord, store } from '@stonyx/orm';
+import { AggregateProperty } from './aggregates.js';
+import { get } from '@stonyx/utils/object';
+
+export default class ViewResolver {
+  constructor(viewName) {
+    this.viewName = viewName;
+  }
+
+  async resolveAll() {
+    const orm = Orm.instance;
+    const { modelClass: viewClass } = orm.getRecordClasses(this.viewName);
+
+    if (!viewClass) return [];
+
+    const source = viewClass.source;
+    if (!source) return [];
+
+    const sourceRecords = await store.findAll(source);
+    if (!sourceRecords || sourceRecords.length === 0) {
+      return [];
+    }
+
+    const resolveMap = viewClass.resolve || {};
+    const viewInstance = new viewClass(this.viewName);
+    const aggregateFields = {};
+    const regularFields = {};
+
+    // Categorize fields on the view instance
+    for (const [key, value] of Object.entries(viewInstance)) {
+      if (key.startsWith('__')) continue;
+      if (key === 'id') continue;
+
+      if (value instanceof AggregateProperty) {
+        aggregateFields[key] = value;
+      } else if (typeof value !== 'function') {
+        // Regular attr or direct value — not a relationship handler
+        regularFields[key] = value;
+      }
+    }
+
+    const results = [];
+
+    for (const sourceRecord of sourceRecords) {
+      const rawData = { id: sourceRecord.id };
+
+      // Compute aggregate fields from source record's relationships
+      for (const [key, aggProp] of Object.entries(aggregateFields)) {
+        const relatedRecords = sourceRecord.__relationships?.[aggProp.relationship]
+          || sourceRecord[aggProp.relationship];
+        const relArray = Array.isArray(relatedRecords) ? relatedRecords : [];
+        rawData[key] = aggProp.compute(relArray);
+      }
+
+      // Apply resolve map entries
+      for (const [key, resolver] of Object.entries(resolveMap)) {
+        if (typeof resolver === 'function') {
+          rawData[key] = resolver(sourceRecord);
+        } else if (typeof resolver === 'string') {
+          rawData[key] = get(sourceRecord.__data || sourceRecord, resolver)
+            ?? get(sourceRecord, resolver);
+        }
+      }
+
+      // Map regular attr fields from source record if not already set
+      for (const key of Object.keys(regularFields)) {
+        if (rawData[key] !== undefined) continue;
+
+        const sourceValue = sourceRecord.__data?.[key] ?? sourceRecord[key];
+        if (sourceValue !== undefined) {
+          rawData[key] = sourceValue;
+        }
+      }
+
+      // Set belongsTo source relationship
+      const viewInstanceForRel = new viewClass(this.viewName);
+      for (const [key, value] of Object.entries(viewInstanceForRel)) {
+        if (typeof value === 'function' && key !== 'id') {
+          // This is a relationship handler — pass the source record id
+          rawData[key] = sourceRecord.id;
+        }
+      }
+
+      // Clear existing record from store to allow re-resolution
+      const viewStore = store.get(this.viewName);
+      if (viewStore?.has(rawData.id)) {
+        viewStore.delete(rawData.id);
+      }
+
+      const record = createRecord(this.viewName, rawData, { isDbRecord: true });
+      results.push(record);
+    }
+
+    return results;
+  }
+
+  async resolveOne(id) {
+    const all = await this.resolveAll();
+    return all.find(record => {
+      return record.id === id || record.id == id;
+    });
+  }
+}

package/src/view.js

@@ -0,0 +1,20 @@
+import { attr } from '@stonyx/orm';
+
+export default class View {
+  static memory = false;
+  static readOnly = true;
+  static pluralName = undefined;
+  static source = undefined;
+  static resolve = undefined;
+
+  id = attr('number');
+
+  constructor(name) {
+    this.__name = name;
+
+    // Enforce readOnly — cannot be overridden to false
+    if (this.constructor.readOnly !== true) {
+      throw new Error(`View '${name}' cannot override readOnly to false`);
+    }
+  }
+}