@stonyx/orm 0.2.1-beta.8 → 0.2.1-beta.81

package/src/standalone-db.js

@@ -0,0 +1,176 @@
+/**
+ * Standalone JSON database layer for CLI usage.
+ *
+ * Reads and writes directly to JSON files without requiring the Stonyx
+ * bootstrap, ORM init, or any framework dependencies. Supports both
+ * single-file and directory modes.
+ */
+
+import fs from 'fs/promises';
+import path from 'path';
+
+export default class StandaloneDB {
+  /**
+   * @param {Object} options
+   * @param {string} options.dbPath - Path to db.json (file mode) or parent of db dir (directory mode)
+   * @param {string} [options.mode='directory'] - 'file' or 'directory'
+   * @param {string} [options.directory='db'] - Directory name when mode is 'directory'
+   */
+  constructor(options = {}) {
+    this.mode = options.mode || 'directory';
+    this.dbPath = options.dbPath || 'db.json';
+    this.directory = options.directory || 'db';
+  }
+
+  /**
+   * Resolve the directory path for directory mode.
+   */
+  getDirPath() {
+    const dbDir = path.dirname(path.resolve(this.dbPath));
+    return path.join(dbDir, this.directory);
+  }
+
+  /**
+   * List available collections by inspecting either the db.json keys
+   * or the files in the db directory.
+   */
+  async getCollections() {
+    if (this.mode === 'directory') {
+      const dirPath = this.getDirPath();
+
+      try {
+        const files = await fs.readdir(dirPath);
+        return files
+          .filter(f => f.endsWith('.json'))
+          .map(f => f.replace('.json', ''));
+      } catch {
+        return [];
+      }
+    }
+
+    // File mode — read db.json and return its top-level keys
+    try {
+      const data = await this._readJSON(this.dbPath);
+      return Object.keys(data).filter(key => Array.isArray(data[key]));
+    } catch {
+      return [];
+    }
+  }
+
+  /**
+   * Read all records for a collection.
+   */
+  async readCollection(collection) {
+    if (this.mode === 'directory') {
+      const filePath = path.join(this.getDirPath(), `${collection}.json`);
+      return this._readJSON(filePath);
+    }
+
+    const data = await this._readJSON(this.dbPath);
+    return data[collection] || [];
+  }
+
+  /**
+   * Write all records for a collection.
+   */
+  async writeCollection(collection, records) {
+    if (this.mode === 'directory') {
+      const dirPath = this.getDirPath();
+      await fs.mkdir(dirPath, { recursive: true });
+
+      const filePath = path.join(dirPath, `${collection}.json`);
+      await this._writeJSON(filePath, records);
+      return;
+    }
+
+    // File mode — read full db, update collection, write back
+    let data;
+
+    try {
+      data = await this._readJSON(this.dbPath);
+    } catch {
+      data = {};
+    }
+
+    data[collection] = records;
+    await this._writeJSON(this.dbPath, data);
+  }
+
+  /**
+   * Get a single record by id.
+   */
+  async get(collection, id) {
+    const records = await this.readCollection(collection);
+    const numericId = Number(id);
+
+    return records.find(r =>
+      r.id === id || r.id === numericId
+    ) || null;
+  }
+
+  /**
+   * List all records in a collection.
+   */
+  async list(collection) {
+    return this.readCollection(collection);
+  }
+
+  /**
+   * Create a new record. Auto-assigns an integer id if none provided.
+   */
+  async create(collection, data) {
+    const records = await this.readCollection(collection);
+
+    if (!data.id) {
+      const maxId = records.reduce((max, r) => {
+        const rid = typeof r.id === 'number' ? r.id : 0;
+        return rid > max ? rid : max;
+      }, 0);
+
+      data.id = maxId + 1;
+    }
+
+    // Check for duplicate id
+    const existing = records.find(r => r.id === data.id);
+    if (existing) {
+      throw new Error(`Record with id ${data.id} already exists in '${collection}'`);
+    }
+
+    records.push(data);
+    await this.writeCollection(collection, records);
+
+    return data;
+  }
+
+  /**
+   * Delete a record by id.
+   */
+  async delete(collection, id) {
+    const records = await this.readCollection(collection);
+    const numericId = Number(id);
+
+    const index = records.findIndex(r =>
+      r.id === id || r.id === numericId
+    );
+
+    if (index === -1) {
+      throw new Error(`Record with id '${id}' not found in '${collection}'`);
+    }
+
+    const [removed] = records.splice(index, 1);
+    await this.writeCollection(collection, records);
+
+    return removed;
+  }
+
+  // -- Private helpers --
+
+  async _readJSON(filePath) {
+    const content = await fs.readFile(filePath, 'utf-8');
+    return JSON.parse(content);
+  }
+
+  async _writeJSON(filePath, data) {
+    await fs.writeFile(filePath, JSON.stringify(data, null, 2) + '\n', 'utf-8');
+  }
+}

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() {
@@ -9,17 +10,145 @@ export default class Store {
     this.data = new Map();
   }
 
+  /**
+   * Synchronous memory-only access.
+   * Returns the record if it exists in the in-memory store, undefined otherwise.
+   * Does NOT query the database. For memory:false models, use find() instead.
+   */
   get(key, id) {
     if (!id) return this.data.get(key);
 
     return this.data.get(key)?.get(id);
   }
 
+  /**
+   * Async authoritative read. Always queries the SQL database for memory: false models.
+   * For memory: true models, returns from store (already loaded on boot).
+   * @param {string} modelName - The model name
+   * @param {string|number} id - The record ID
+   * @returns {Promise<Record|undefined>}
+   */
+  async find(modelName, id) {
+    // For views in non-SQL mode, use view resolver
+    if (Orm.instance?.isView?.(modelName) && !this._sqlDb) {
+      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);
+    }
+
+    // For memory: false models, always query the SQL database
+    if (this._sqlDb) {
+      return this._sqlDb.findRecord(modelName, id);
+    }
+
+    // Fallback to store (JSON mode or no SQL adapter)
+    return this.get(modelName, id);
+  }
+
+  /**
+   * Async read for all records of a model. Always queries MySQL for memory: false models.
+   * For memory: true models, returns from store.
+   * @param {string} modelName - The model name
+   * @param {Object} [conditions] - Optional WHERE conditions
+   * @returns {Promise<Record[]>}
+   */
+  async findAll(modelName, conditions) {
+    // For views in non-SQL mode, use view resolver
+    if (Orm.instance?.isView?.(modelName) && !this._sqlDb) {
+      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);
+      return modelStore ? Array.from(modelStore.values()) : [];
+    }
+
+    // For memory: false models (or filtered queries), always query the SQL database
+    if (this._sqlDb) {
+      return this._sqlDb.findAll(modelName, conditions);
+    }
+
+    // Fallback to store (JSON mode) — apply conditions in-memory if provided
+    const modelStore = this.get(modelName);
+    if (!modelStore) return [];
+
+    const records = Array.from(modelStore.values());
+
+    if (!conditions || Object.keys(conditions).length === 0) return records;
+
+    return records.filter(record =>
+      Object.entries(conditions).every(([key, value]) => record.__data[key] === value)
+    );
+  }
+
+  /**
+   * Async query — always hits MySQL, never reads from memory cache.
+   * Use for complex queries, aggregations, or when you need guaranteed freshness.
+   * @param {string} modelName - The model name
+   * @param {Object} conditions - WHERE conditions
+   * @returns {Promise<Record[]>}
+   */
+  async query(modelName, conditions = {}) {
+    if (this._sqlDb) {
+      return this._sqlDb.findAll(modelName, conditions);
+    }
+
+    // Fallback: filter in-memory store
+    const modelStore = this.get(modelName);
+    if (!modelStore) return [];
+
+    const records = Array.from(modelStore.values());
+
+    if (Object.keys(conditions).length === 0) return records;
+
+    return records.filter(record =>
+      Object.entries(conditions).every(([key, value]) => record.__data[key] === value)
+    );
+  }
+
+  /**
+   * Set by Orm during init — resolves memory flag for a model name.
+   * @type {Function|null}
+   */
+  _memoryResolver = null;
+
+  /**
+   * Set by Orm during init — reference to the SQL adapter instance for on-demand queries.
+   * @type {object|null}
+   */
+  _sqlDb = null;
+
+  /**
+   * Check if a model is configured for in-memory storage.
+   * @private
+   */
+  _isMemoryModel(modelName) {
+    if (this._memoryResolver) return this._memoryResolver(modelName);
+    return false; // default to non-memory if resolver not set yet
+  }
+
   set(key, value) {
     this.data.set(key, value);
   }
 
   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,183 @@
+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 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) {
+      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;
+  }
+
+  _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 => {
+      return record.id === id || record.id == id;
+    });
+  }
+}

package/src/view.js

@@ -0,0 +1,21 @@
+import { attr } from '@stonyx/orm';
+
+export default class View {
+  static memory = false;
+  static readOnly = true;
+  static pluralName = undefined;
+  static source = undefined;
+  static groupBy = 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`);
+    }
+  }
+}

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)