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

package/.claude/views.md

@@ -37,6 +37,7 @@ export default class OwnerStatsView extends View {
 | 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` |
@@ -90,6 +91,76 @@ export default class OwnerStatsView extends View {
 
 **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:

package/package.json

@@ -4,7 +4,7 @@
     "stonyx-async",
     "stonyx-module"
   ],
-  "version": "0.2.1-alpha.11",
+  "version": "0.2.1-alpha.12",
   "description": "",
   "main": "src/main.js",
   "type": "module",

package/src/aggregates.js

@@ -64,18 +64,30 @@ export function count(relationship) {
   return new AggregateProperty('count', relationship);
 }
 
-export function avg(relationship, field) {
-  return new AggregateProperty('avg', relationship, field);
+export function avg(relationshipOrField, field) {
+  if (field !== undefined) {
+    return new AggregateProperty('avg', relationshipOrField, field);
+  }
+  return new AggregateProperty('avg', undefined, relationshipOrField);
 }
 
-export function sum(relationship, field) {
-  return new AggregateProperty('sum', relationship, field);
+export function sum(relationshipOrField, field) {
+  if (field !== undefined) {
+    return new AggregateProperty('sum', relationshipOrField, field);
+  }
+  return new AggregateProperty('sum', undefined, relationshipOrField);
 }
 
-export function min(relationship, field) {
-  return new AggregateProperty('min', relationship, field);
+export function min(relationshipOrField, field) {
+  if (field !== undefined) {
+    return new AggregateProperty('min', relationshipOrField, field);
+  }
+  return new AggregateProperty('min', undefined, relationshipOrField);
 }
 
-export function max(relationship, field) {
-  return new AggregateProperty('max', relationship, field);
+export function max(relationshipOrField, field) {
+  if (field !== undefined) {
+    return new AggregateProperty('max', relationshipOrField, field);
+  }
+  return new AggregateProperty('max', undefined, relationshipOrField);
 }

package/src/mysql/schema-introspector.js

@@ -193,6 +193,7 @@ export function introspectViews() {
     schemas[name] = {
       viewName: getPluralName(name),
       source,
+      groupBy: viewClass.groupBy || undefined,
       columns,
       foreignKeys,
       aggregates,
@@ -219,32 +220,46 @@ export function buildViewDDL(name, viewSchema, modelSchemas = {}) {
   const selectColumns = [];
   const joins = [];
   const hasAggregates = Object.keys(viewSchema.aggregates || {}).length > 0;
+  const groupByField = viewSchema.groupBy;
 
-  // Source table primary key
-  selectColumns.push(`\`${sourceTable}\`.\`id\` AS \`id\``);
+  // ID column: groupBy field or source table PK
+  if (groupByField) {
+    selectColumns.push(`\`${sourceTable}\`.\`${groupByField}\` AS \`id\``);
+  } else {
+    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}\``);
+    if (aggProp.relationship === undefined) {
+      // Field-level aggregate (groupBy views)
+      if (aggProp.aggregateType === 'count') {
+        selectColumns.push(`COUNT(*) AS \`${key}\``);
+      } else {
+        selectColumns.push(`${aggProp.mysqlFunction}(\`${sourceTable}\`.\`${aggProp.field}\`) AS \`${key}\``);
+      }
     } else {
-      const field = aggProp.field;
-      selectColumns.push(`${aggProp.mysqlFunction}(\`${relTable}\`.\`${field}\`) AS \`${key}\``);
-    }
+      // Relationship aggregate
+      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\``
-      });
+      // Add LEFT JOIN for the relationship if not already added
+      const joinKey = `${relTable}`;
+      if (!joins.find(j => j.table === joinKey)) {
+        const fkColumn = `${sourceModelName}_id`;
+        joins.push({
+          table: relTable,
+          condition: `\`${relTable}\`.\`${fkColumn}\` = \`${sourceTable}\`.\`id\``
+        });
+      }
     }
   }
 
@@ -259,7 +274,12 @@ export function buildViewDDL(name, viewSchema, modelSchemas = {}) {
   ).join('\n  ');
 
   // Build GROUP BY
-  const groupBy = hasAggregates ? `\nGROUP BY \`${sourceTable}\`.\`id\`` : '';
+  let groupBy = '';
+  if (groupByField) {
+    groupBy = `\nGROUP BY \`${sourceTable}\`.\`${groupByField}\``;
+  } else if (hasAggregates) {
+    groupBy = `\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}`;
@@ -274,6 +294,7 @@ export function viewSchemasToSnapshot(viewSchemas) {
     snapshot[name] = {
       viewName: schema.viewName,
       source: schema.source,
+      ...(schema.groupBy ? { groupBy: schema.groupBy } : {}),
       columns: { ...schema.columns },
       foreignKeys: { ...schema.foreignKeys },
       isView: true,

package/src/view-resolver.js

@@ -39,6 +39,16 @@ export default class ViewResolver {
       }
     }
 
+    const groupByField = viewClass.groupBy;
+
+    if (groupByField) {
+      return this._resolveGroupBy(sourceRecords, groupByField, aggregateFields, regularFields, resolveMap, viewClass);
+    }
+
+    return this._resolvePerRecord(sourceRecords, aggregateFields, regularFields, resolveMap, viewClass);
+  }
+
+  _resolvePerRecord(sourceRecords, aggregateFields, regularFields, resolveMap, viewClass) {
     const results = [];
 
     for (const sourceRecord of sourceRecords) {
@@ -94,6 +104,76 @@ export default class ViewResolver {
     return results;
   }
 
+  _resolveGroupBy(sourceRecords, groupByField, aggregateFields, regularFields, resolveMap, viewClass) {
+    // Group source records by the groupBy field value
+    const groups = new Map();
+    for (const record of sourceRecords) {
+      const key = record.__data?.[groupByField] ?? record[groupByField];
+      if (!groups.has(key)) {
+        groups.set(key, []);
+      }
+      groups.get(key).push(record);
+    }
+
+    const results = [];
+
+    for (const [groupKey, groupRecords] of groups) {
+      const rawData = { id: groupKey };
+
+      // Compute aggregate fields
+      for (const [key, aggProp] of Object.entries(aggregateFields)) {
+        if (aggProp.relationship === undefined) {
+          // Field-level aggregate — compute over group records directly
+          rawData[key] = aggProp.compute(groupRecords);
+        } else {
+          // Relationship aggregate — flatten related records across all group members
+          const allRelated = [];
+          for (const record of groupRecords) {
+            const relatedRecords = record.__relationships?.[aggProp.relationship]
+              || record[aggProp.relationship];
+            if (Array.isArray(relatedRecords)) {
+              allRelated.push(...relatedRecords);
+            }
+          }
+          rawData[key] = aggProp.compute(allRelated);
+        }
+      }
+
+      // Apply resolve map entries — functions receive the group array
+      for (const [key, resolver] of Object.entries(resolveMap)) {
+        if (typeof resolver === 'function') {
+          rawData[key] = resolver(groupRecords);
+        } else if (typeof resolver === 'string') {
+          // String path — take value from first record in group
+          const first = groupRecords[0];
+          rawData[key] = get(first.__data || first, resolver)
+            ?? get(first, resolver);
+        }
+      }
+
+      // Map regular attr fields from first record if not already set
+      for (const key of Object.keys(regularFields)) {
+        if (rawData[key] !== undefined) continue;
+        const first = groupRecords[0];
+        const sourceValue = first.__data?.[key] ?? first[key];
+        if (sourceValue !== undefined) {
+          rawData[key] = sourceValue;
+        }
+      }
+
+      // 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 => {

package/src/view.js

@@ -5,6 +5,7 @@ export default class View {
   static readOnly = true;
   static pluralName = undefined;
   static source = undefined;
+  static groupBy = undefined;
   static resolve = undefined;
 
   id = attr('number');