@stonyx/orm 0.2.1-beta.9 → 0.2.1-beta.91

package/src/view-resolver.ts

@@ -0,0 +1,211 @@
+import Orm, { store } from '@stonyx/orm';
+import { createRecord } from './manage-record.js';
+import { AggregateProperty } from './aggregates.js';
+import { get } from '@stonyx/utils/object';
+import type { SourceRecord } from './types/orm-types.js';
+
+interface ViewClass {
+  source?: string;
+  resolve?: Record<string, unknown>;
+  groupBy?: string;
+  new (viewName: string): Record<string, unknown>;
+}
+
+export default class ViewResolver {
+  viewName: string;
+
+  constructor(viewName: string) {
+    this.viewName = viewName;
+  }
+
+  async resolveAll(): Promise<unknown[]> {
+    const orm = Orm.instance;
+    const { modelClass: viewClass } = orm.getRecordClasses(this.viewName) as { modelClass: ViewClass | undefined; serializerClass: unknown };
+
+    if (!viewClass) return [];
+
+    const source = viewClass.source;
+    if (!source) return [];
+
+    const sourceRecords = await store.findAll(source) as SourceRecord[];
+    if (!sourceRecords || sourceRecords.length === 0) {
+      return [];
+    }
+
+    const resolveMap = viewClass.resolve || {};
+    const viewInstance = new viewClass(this.viewName);
+    const aggregateFields: Record<string, AggregateProperty> = {};
+    const regularFields: Record<string, unknown> = {};
+
+    // 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 groupByField = viewClass.groupBy;
+
+    if (groupByField) {
+      return this._resolveGroupBy(sourceRecords, groupByField, aggregateFields, regularFields, resolveMap, viewClass);
+    }
+
+    return this._resolvePerRecord(sourceRecords, aggregateFields, regularFields, resolveMap, viewClass);
+  }
+
+  private _resolvePerRecord(
+    sourceRecords: SourceRecord[],
+    aggregateFields: Record<string, AggregateProperty>,
+    regularFields: Record<string, unknown>,
+    resolveMap: Record<string, unknown>,
+    viewClass: ViewClass
+  ): unknown[] {
+    const results: unknown[] = [];
+
+    for (const sourceRecord of sourceRecords) {
+      const rawData: Record<string, unknown> = { id: sourceRecord.id };
+
+      // Compute aggregate fields from source record's relationships
+      for (const [key, aggProp] of Object.entries(aggregateFields)) {
+        if (!aggProp.relationship) continue;
+        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 as number | string)) {
+        viewStore.delete(rawData.id as number | string);
+      }
+
+      const record = createRecord(this.viewName, rawData, { isDbRecord: true });
+      results.push(record);
+    }
+
+    return results;
+  }
+
+  private _resolveGroupBy(
+    sourceRecords: SourceRecord[],
+    groupByField: string,
+    aggregateFields: Record<string, AggregateProperty>,
+    regularFields: Record<string, unknown>,
+    resolveMap: Record<string, unknown>,
+    viewClass: ViewClass
+  ): unknown[] {
+    // Group source records by the groupBy field value
+    const groups = new Map<unknown, SourceRecord[]>();
+    for (const record of sourceRecords) {
+      const key = record.__data?.[groupByField] ?? record[groupByField];
+      if (!groups.has(key)) {
+        groups.set(key, []);
+      }
+      const group = groups.get(key);
+      if (group) group.push(record);
+    }
+
+    const results: unknown[] = [];
+
+    for (const [groupKey, groupRecords] of groups) {
+      const rawData: Record<string, unknown> = { 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
+          if (!aggProp.relationship) continue;
+          const allRelated: unknown[] = [];
+          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 as { __data?: Record<string, unknown>; [key: string]: unknown }[]);
+        }
+      }
+
+      // 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 as number | string)) {
+        viewStore.delete(rawData.id as number | string);
+      }
+
+      const record = createRecord(this.viewName, rawData, { isDbRecord: true });
+      results.push(record);
+    }
+
+    return results;
+  }
+
+  async resolveOne(id: unknown): Promise<unknown> {
+    const all = await this.resolveAll();
+    return all.find((record: unknown) => {
+      const r = record as SourceRecord;
+      return r.id === id || r.id == id;
+    });
+  }
+}

package/src/view.ts

@@ -0,0 +1,22 @@
+import attr from './attr.js';
+
+export default class View {
+  static memory: boolean = false;
+  static readOnly: boolean = true;
+  static pluralName: string | undefined = undefined;
+  static source: string | undefined = undefined;
+  static groupBy: string | undefined = undefined;
+  static resolve: ((record: unknown) => unknown) | undefined = undefined;
+
+  id = attr('number');
+  __name: string;
+
+  constructor(name: string) {
+    this.__name = name;
+
+    // Enforce readOnly — cannot be overridden to false
+    if ((this.constructor as typeof View).readOnly !== true) {
+      throw new Error(`View '${name}' cannot override readOnly to false`);
+    }
+  }
+}

package/.claude/code-style-rules.md

@@ -1,44 +0,0 @@
-# Stonyx Code Style Rules
-
-Strict prettier/eslint rules to apply across all Stonyx projects. These will be formalized into an ESLint/Prettier config once enough patterns are collected.
-
----
-
-## Rules
-
-### 1. Destructure config objects in function signatures
-
-When a function receives a config/options object and only uses specific properties, destructure them in the function signature rather than accessing them via dot notation in the body.
-
-**Bad:**
-```javascript
-export async function getPool(mysqlConfig) {
-  pool = mysql.createPool({
-    host: mysqlConfig.host,
-    port: mysqlConfig.port,
-    user: mysqlConfig.user,
-    password: mysqlConfig.password,
-    database: mysqlConfig.database,
-    connectionLimit: mysqlConfig.connectionLimit,
-    // ...
-  });
-}
-```
-
-**Good:**
-```javascript
-export async function getPool({ host, port, user, password, database, connectionLimit }) {
-  pool = mysql.createPool({
-    host,
-    port,
-    user,
-    password,
-    database,
-    connectionLimit,
-    // ...
-  });
-}
-```
-
-**Source:** PR #14, `src/mysql/connection.js`
-**ESLint rule (candidate):** `prefer-destructuring` (with custom config for function parameters)

package/.claude/hooks.md

@@ -1,250 +0,0 @@
-# Middleware Hooks System
-
-The ORM provides a powerful middleware-based hook system that allows custom logic before and after CRUD operations. **Before hooks can halt operations** by returning a value.
-
-## Architecture
-
-**Hook Registry**: [src/hooks.js](src/hooks.js) - Stores before/after hooks in Maps
-**Integration**: [src/orm-request.js](src/orm-request.js) - `_withHooks()` wrapper executes hooks
-**Exports**: [src/index.js](src/index.js) - Exports `beforeHook`, `afterHook`, `clearHook`, `clearAllHooks`
-
-## API
-
-### `beforeHook(operation, model, handler)`
-
-Register a before hook that runs before the operation executes.
-
-```javascript
-import { beforeHook } from '@stonyx/orm';
-
-beforeHook('create', 'animal', (context) => {
-  // Validate, transform, authorize...
-  if (invalid) {
-    return 400; // Halt with status code
-  }
-  // Return undefined to continue
-});
-```
-
-**Handler return values:**
-- `undefined` / no return - Operation continues
-- **Any other value** - Halts operation and returns that value:
-  - Integer (e.g., `403`) - HTTP status code
-  - Object - JSON response body
-
-**Returns:** Unregister function
-
-### `afterHook(operation, model, handler)`
-
-Register an after hook that runs after the operation completes.
-
-```javascript
-import { afterHook } from '@stonyx/orm';
-
-afterHook('update', 'animal', (context) => {
-  console.log(`Updated animal ${context.record.id}`);
-  // After hooks cannot halt (operation already complete)
-});
-```
-
-**Returns:** Unregister function
-
-### `clearHook(operation, model, [type])`
-
-Clear registered hooks for a specific operation:model.
-
-```javascript
-import { clearHook } from '@stonyx/orm';
-
-clearHook('create', 'animal');           // Clear both before and after
-clearHook('create', 'animal', 'before'); // Clear only before hooks
-clearHook('create', 'animal', 'after');  // Clear only after hooks
-```
-
-### `clearAllHooks()`
-
-Clear all registered hooks (useful for testing).
-
-```javascript
-import { clearAllHooks } from '@stonyx/orm';
-
-afterEach(() => {
-  clearAllHooks();
-});
-```
-
-## Operations
-
-- `list` - GET collection (`/animals`)
-- `get` - GET single record (`/animals/1`)
-- `create` - POST new record (`/animals`)
-- `update` - PATCH existing record (`/animals/1`)
-- `delete` - DELETE record (`/animals/1`)
-
-## Context Object
-
-Each hook receives a context object:
-
-```javascript
-{
-  model: 'animal',           // Model name
-  operation: 'create',       // Operation type
-  request,                   // Express request object
-  params,                    // URL params (e.g., { id: 5 })
-  body,                      // Request body (POST/PATCH)
-  query,                     // Query parameters
-  state,                     // Request state (includes filter for access control)
-
-  // For update/delete operations:
-  oldState,                  // Deep copy of record BEFORE operation
-
-  // For after hooks only:
-  response,                  // Handler response
-  record,                    // Affected record (create/update/get)
-  records,                   // All records (list)
-  recordId,                  // Record ID (delete only, since record no longer exists)
-}
-```
-
-**Notes:**
-- `oldState` is captured via `JSON.parse(JSON.stringify())` before operation executes
-- For delete operations, `recordId` is available since the record may no longer exist
-- `oldState` enables precise field-level change detection
-
-## Implementation Details
-
-**Hook Wrapper** (`src/orm-request.js`):
-
-```javascript
-_withHooks(operation, handler) {
-  return async (request, state) => {
-    const context = { model, operation, request, params, body, query, state };
-
-    // Capture old state for update/delete
-    if (operation === 'update' || operation === 'delete') {
-      const existingRecord = store.get(this.model, getId(request.params));
-      if (existingRecord) {
-        context.oldState = JSON.parse(JSON.stringify(existingRecord.__data || existingRecord));
-      }
-    }
-
-    // Run before hooks sequentially (can halt by returning a value)
-    for (const hook of getBeforeHooks(operation, this.model)) {
-      const result = await hook(context);
-      if (result !== undefined) {
-        return result;  // Halt - return status/response
-      }
-    }
-
-    // Execute main handler
-    const response = await handler(request, state);
-
-    // Enrich context for after hooks
-    context.response = response;
-    context.record = /* fetched from store */;
-    context.records = /* for list operations */;
-    context.recordId = /* for delete operations */;
-
-    // Run after hooks sequentially
-    for (const hook of getAfterHooks(operation, this.model)) {
-      await hook(context);
-    }
-
-    return response;
-  };
-}
-```
-
-## Usage Examples
-
-### Validation (Halting)
-
-```javascript
-beforeHook('create', 'animal', (context) => {
-  const { age } = context.body.data.attributes;
-  if (age < 0) {
-    return 400; // Halt with Bad Request
-  }
-});
-```
-
-### Custom Error Response
-
-```javascript
-beforeHook('delete', 'animal', (context) => {
-  const animal = store.get('animal', context.params.id);
-  if (animal.protected) {
-    return { errors: [{ detail: 'Cannot delete protected animals' }] };
-  }
-});
-```
-
-### Change Detection with oldState
-
-```javascript
-afterHook('update', 'animal', (context) => {
-  if (!context.oldState) return;
-
-  // Detect specific field changes
-  if (context.oldState.owner !== context.record.owner) {
-    console.log(`Owner changed from ${context.oldState.owner} to ${context.record.owner}`);
-  }
-});
-```
-
-### Audit Logging
-
-```javascript
-afterHook('update', 'animal', async (context) => {
-  const changes = {};
-  if (context.oldState) {
-    for (const [key, newValue] of Object.entries(context.record.__data)) {
-      if (context.oldState[key] !== newValue) {
-        changes[key] = { from: context.oldState[key], to: newValue };
-      }
-    }
-  }
-
-  await auditLog.create({
-    operation: 'update',
-    model: context.model,
-    recordId: context.record.id,
-    changes // { age: { from: 2, to: 3 } }
-  });
-});
-```
-
-### Delete Auditing
-
-```javascript
-afterHook('delete', 'animal', async (context) => {
-  await auditLog.create({
-    operation: 'delete',
-    model: context.model,
-    recordId: context.recordId,
-    deletedData: context.oldState // Full snapshot
-  });
-});
-```
-
-## Key Differences from Event-Based System
-
-| Feature | Event-Based (Old) | Middleware-Based (Current) |
-|---------|-------------------|---------------------------|
-| Execution | Parallel (fire-and-forget) | Sequential |
-| Can halt operation | No | Yes (return any value) |
-| Error handling | Isolated (logged) | Propagated (halts operation) |
-| Middleware order | Not guaranteed | Registration order |
-| Context modification | Not reliable | Reliable (sequential) |
-| API | `subscribe('before:create:animal')` | `beforeHook('create', 'animal')` |
-
-## Testing
-
-**Location**: `test/integration/orm-test.js`
-**Coverage**: Comprehensive hook tests including:
-- Before/after hooks for all operations
-- Halting with status codes
-- Halting with custom response objects
-- Sequential execution order
-- Unsubscribe functionality
-- clearHook functionality