rasti 3.0.1 → 4.0.0-alpha.0

package/lib/Emitter.cjs

@@ -1,11 +1,40 @@
 'use strict';
 
+var utils_validateListener = require('./utils/validateListener.cjs');
+
 /**
  * `Emitter` is a class that provides an easy way to implement the observer pattern 
  * in your applications.  
  * It can be extended to create new classes that have the ability to emit and bind custom named events.   
  * Emitter is used by `Model` and `View` classes, which inherit from it to implement 
  * event-driven functionality.
+ * 
+ * ## Inverse of Control Pattern
+ * 
+ * The Emitter class includes "inverse of control" methods (`listenTo`, `listenToOnce`, `stopListening`) 
+ * that allow an object to manage its own listening relationships. Instead of:
+ * 
+ * ```javascript
+ * // Traditional approach - harder to clean up
+ * otherObject.on('change', this.myHandler);
+ * otherObject.on('destroy', this.cleanup);
+ * // Later you need to remember to clean up each listener
+ * otherObject.off('change', this.myHandler);
+ * otherObject.off('destroy', this.cleanup);
+ * ```
+ * 
+ * You can use:
+ * 
+ * ```javascript
+ * // Inverse of control - easier cleanup
+ * this.listenTo(otherObject, 'change', this.myHandler);
+ * this.listenTo(otherObject, 'destroy', this.cleanup);
+ * // Later, clean up ALL listeners at once
+ * this.stopListening(); // Removes all listening relationships
+ * ```
+ * 
+ * This pattern is particularly useful for preventing memory leaks and simplifying cleanup
+ * in component lifecycle management.
  *
  * @module
  * @example
@@ -41,20 +70,20 @@ class Emitter {
     /**
      * Adds event listener.
      * @param {string} type Type of the event (e.g. `change`).
-     * @param {function} listener Callback function to be called when the event is emitted.
+     * @param {Function} listener Callback function to be called when the event is emitted.
+     * @return {Function} A function to remove the listener.
      * @example
      * // Re render when model changes.
      * this.model.on('change', this.render.bind(this));
      */
     on(type, listener) {
         // Validate listener.
-        if (typeof listener !== 'function') {
-            throw new TypeError('Listener must be a function');
-        }
+        utils_validateListener(listener);
         // Create listeners object if it doesn't exist.
         if (!this.listeners) this.listeners = {};
+        // Every type must have an array of listeners.
         if (!this.listeners[type]) this.listeners[type] = [];
-        // Add listener.
+        // Add listener to the array of listeners.
         this.listeners[type].push(listener);
         // Return a function to remove the listener.
         return () => this.off(type, listener);
@@ -63,33 +92,47 @@ class Emitter {
     /**
      * Adds event listener that executes once.
      * @param {string} type Type of the event (e.g. `change`).
-     * @param {function} listener Callback function to be called when the event is emitted.
+     * @param {Function} listener Callback function to be called when the event is emitted.
+     * @return {Function} A function to remove the listener.
      * @example
      * // Log a message once when model changes.
      * this.model.once('change', () => console.log('This will happen once'));
      */
     once(type, listener) {
-        // If listener is a function, wrap it to remove it after it is called.
-        if (typeof listener === 'function') {
-            const self = this;
-            const originalListener = listener;
-
-            listener = function(...args) {
-                originalListener(...args);
-                self.off(type, listener);
-            };
-        }
+        // Validate listener.
+        utils_validateListener(listener);
+        // Wrap listener to remove it after it is called.
+        const wrapper = (...args) => {
+            listener(...args);
+            this.off(type, wrapper);
+        };
         // Add listener.
-        return this.on(type, listener);
+        return this.on(type, wrapper);
     }
 
     /**
-     * Removes event listeners.
-     * @param {string} [type] Type of the event (e.g. `change`). If is not provided, it removes all listeners.
-     * @param {function} [listener] Callback function to be called when the event is emitted. If listener is not provided, it removes all listeners for specified type.
+     * Removes event listeners with flexible parameter combinations.
+     * @param {string} [type] Type of the event (e.g. `change`). If not provided, removes ALL listeners from this emitter.
+     * @param {Function} [listener] Specific callback function to remove. If not provided, removes all listeners for the specified type.
+     * 
+     * **Behavior based on parameters:**
+     * - `off()` - Removes ALL listeners from this emitter
+     * - `off(type)` - Removes all listeners for the specified event type
+     * - `off(type, listener)` - Removes the specific listener for the specified event type
+     * 
+     * @example
+     * // Remove all listeners from this emitter
+     * this.model.off();
+     * 
      * @example
-     * // Stop listening to changes.
+     * // Remove all 'change' event listeners
      * this.model.off('change');
+     * 
+     * @example
+     * // Remove specific listener for 'change' events
+     * const myListener = () => console.log('changed');
+     * this.model.on('change', myListener);
+     * this.model.off('change', myListener);
      */
     off(type, listener) {
         // No listeners.
@@ -116,21 +159,132 @@ class Emitter {
     /**
      * Emits event of specified type. Listeners will receive specified arguments.
      * @param {string} type Type of the event (e.g. `change`).
-     * @param {any} [...args] Arguments to be passed to listener.
+     * @param {...any} [args] Optional arguments to be passed to listeners.
      * @example
-     * // Emit validation error event.
+     * // Emit validation error event with no arguments
      * this.emit('invalid');
+     * 
+     * @example
+     * // Emit change event with data
+     * this.emit('change', { field : 'name', value : 'John' });
      */
     emit(type, ...args) {
         // No listeners.
         if (!this.listeners || !this.listeners[type]) return;
         // Call listeners. Use `slice` to make a copy and prevent errors when 
         // removing listeners inside a listener.
-        this.listeners[type]
-            .slice()
-            .forEach(function(fn) {
-                fn(...args);
-            });
+        this.listeners[type].slice().forEach(fn => fn(...args));
+    }
+
+    /**
+     * Listen to an event of another emitter (Inverse of Control pattern).
+     * 
+     * This method allows this object to manage its own listening relationships,
+     * making cleanup easier and preventing memory leaks. Instead of calling
+     * `otherEmitter.on()`, you call `this.listenTo(otherEmitter, ...)` which
+     * allows this object to track and clean up all its listeners at once.
+     * 
+     * @param {Emitter} emitter The emitter to listen to.
+     * @param {string} type The type of the event to listen to.
+     * @param {Function} listener The listener to call when the event is emitted.
+     * @return {Function} A function to stop listening to the event.
+     * 
+     * @example
+     * // Instead of: otherModel.on('change', this.render.bind(this));
+     * // Use: this.listenTo(otherModel, 'change', this.render.bind(this));
+     * // This way you can later call this.stopListening() to clean up all listeners
+     */
+    listenTo(emitter, type, listener) {
+        // Add listener to the emitter.
+        emitter.on(type, listener);
+        // Create listeningTo array if it doesn't exist.
+        if (!this.listeningTo) this.listeningTo = [];
+        // Add listener to the array of listeners.
+        this.listeningTo.push({ emitter, type, listener });
+        // Return a function to stop listening to the event.
+        return () => this.stopListening(emitter, type, listener);
+    }
+
+    /**
+     * Listen to an event of another emitter and remove the listener after it is called (Inverse of Control pattern).
+     * 
+     * Similar to `listenTo()` but automatically removes the listener after the first execution,
+     * like `once()` but with the inverse of control benefits for cleanup management.
+     * 
+     * @param {Emitter} emitter The emitter to listen to.
+     * @param {string} type The type of the event to listen to.
+     * @param {Function} listener The listener to call when the event is emitted.
+     * @return {Function} A function to stop listening to the event.
+     * 
+     * @example
+     * // Listen once to another emitter's initialization event
+     * this.listenToOnce(otherModel, 'initialized', () => {
+     *     console.log('Other model initialized');
+     * });
+     */
+    listenToOnce(emitter, type, listener) {
+        utils_validateListener(listener);
+        // Wrap listener to remove it after it is called.
+        const wrapper = (...args) => {
+            listener(...args);
+            this.stopListening(emitter, type, wrapper);
+        };
+        // Add listener.
+        return this.listenTo(emitter, type, wrapper);
+    }
+
+    /**
+     * Stop listening to events from other emitters (Inverse of Control pattern).
+     * 
+     * This method provides flexible cleanup of listening relationships established with `listenTo()`.
+     * All parameters are optional, allowing different levels of cleanup granularity.
+     * 
+     * @param {Emitter} [emitter] The emitter to stop listening to. If not provided, stops listening to ALL emitters.
+     * @param {string} [type] The type of event to stop listening to. If not provided, stops listening to all event types from the specified emitter.
+     * @param {Function} [listener] The specific listener to remove. If not provided, removes all listeners for the specified event type from the specified emitter.
+     * 
+     * **Behavior based on parameters:**
+     * - `stopListening()` - Stops listening to ALL events from ALL emitters
+     * - `stopListening(emitter)` - Stops listening to all events from the specified emitter
+     * - `stopListening(emitter, type)` - Stops listening to the specified event type from the specified emitter
+     * - `stopListening(emitter, type, listener)` - Stops listening to the specific listener for the specific event from the specific emitter
+     * 
+     * @example
+     * // Stop listening to all events from all emitters (complete cleanup)
+     * this.stopListening();
+     * 
+     * @example
+     * // Stop listening to all events from a specific emitter
+     * this.stopListening(otherModel);
+     * 
+     * @example
+     * // Stop listening to 'change' events from a specific emitter
+     * this.stopListening(otherModel, 'change');
+     * 
+     * @example
+     * // Stop listening to a specific listener
+     * const myListener = () => console.log('changed');
+     * this.listenTo(otherModel, 'change', myListener);
+     * this.stopListening(otherModel, 'change', myListener);
+     */
+    stopListening(emitter, type, listener) {
+        // No listeningTo object.
+        if (!this.listeningTo) return;
+        // Remove listener from the array of listeners.
+        this.listeningTo = this.listeningTo.filter(item => {
+            if (
+                !emitter ||
+                (emitter === item.emitter && !type) ||
+                (emitter === item.emitter && type === item.type && !listener) ||
+                (emitter === item.emitter && type === item.type && listener === item.listener)
+            ) {
+                item.emitter.off(item.type, item.listener);
+                return false;
+            }
+            return true;
+        });
+        // Remove listeningTo object if it's empty.
+        if (!this.listeningTo.length) delete this.listeningTo;
     }
 }
 

package/lib/Model.cjs

@@ -2,6 +2,7 @@
 
 var Emitter = require('./Emitter.cjs');
 var utils_getResult = require('./utils/getResult.cjs');
+require('./utils/validateListener.cjs');
 
 /**
  * - Orchestrates data and business logic.
@@ -10,55 +11,113 @@ var utils_getResult = require('./utils/getResult.cjs');
  * A `Model` manages an internal table of data attributes and triggers change events when any of its data is modified.  
  * Models may handle syncing data with a persistence layer. To design your models, create atomic, reusable objects 
  * that contain all the necessary functions for manipulating their specific data.  
- * Models should be easily passed throughout your app and used anywhere the corresponding data is needed.  
- * Rasti models store their attributes in `this.attributes`, which is extended from `this.defaults` and the 
- * constructor `attributes` parameter. For every attribute, a getter is generated to retrieve the model property 
- * from `this.attributes`, and a setter is created to set the model property in `this.attributes` and emit `change` 
- * and `change:attribute` events.
+ * Models should be easily passed throughout your app and used anywhere the corresponding data is needed.
+ * 
+ * ## Construction Flow
+ * 1. `preinitialize()` is called with all constructor arguments
+ * 2. `this.defaults` are resolved (if function, it's called and bound to the model)
+ * 3. `parse()` is called with all constructor arguments to process the data
+ * 4. `this.attributes` is built by merging defaults and parsed data
+ * 5. Getters/setters are generated for each attribute to emit change events
+ * 
  * @module
- * @extends Rasti.Emitter
- * @param {object} attributes Object containing model attributes to extend `this.attributes`. Getters and setters are generated for `this.attributes`, in order to emit `change` events.
- * @property {object|function} defaults Object containing default attributes for the model. It will extend `this.attributes`. If a function is passed, it will be called to get the defaults. It will be bound to the model instance.
+ * @extends Emitter
+ * @param {object} [attributes={}] Primary data object containing model attributes
+ * @param {...*} [args] Additional arguments passed to `preinitialize` and `parse` methods
+ * @property {object|Function} defaults Default attributes for the model. If a function, it's called bound to the model instance to get defaults.
  * @property {object} previous Object containing previous attributes when a change occurs.
+ * @property {string} attributePrefix Static property that defines a prefix for generated getters/setters. Defaults to empty string.
  * @example
  * import { Model } from 'rasti';
- * // Product model
- * class ProductModel extends Model {
+ * 
+ * // User model
+ * class User extends Model {
  *     preinitialize() {
- *         // The Product model has `name` and `price` default attributes.
- *         // `defaults` will extend `this.attributes`.
- *         // Getters and setters are generated for `this.attributes`,
- *         // in order to emit `change` events.
+ *         this.defaults = { name : '', email : '', role : 'user' };
+ *     }
+ * }
+ * // Order model with nested User and custom methods
+ * class Order extends Model {
+ *     preinitialize(attributes, options = {}) {
  *         this.defaults = {
- *             name: '',
- *             price: 0
+ *             id : null,
+ *             total : 0,
+ *             status : 'pending',
+ *             user : null
  *         };
+ * 
+ *         this.apiUrl = options.apiUrl || '/api/orders';
  *     }
  *
- *     setDiscount(discountPercentage) {
- *         // Apply a discount to the price property.
- *         // This will call a setter that will update `price` in `this.attributes`,
- *         // and emit `change` and `change:price` events.
- *         const discount = this.price * (discountPercentage / 100);
- *         this.price -= discount;
+ *     parse(data, options = {}) {
+ *         const parsed = { ...data };
+ *         
+ *         // Convert user object to User model instance
+ *         if (data.user && !(data.user instanceof User)) {
+ *             parsed.user = new User(data.user);
+ *         }
+ * 
+ *         return parsed;
+ *     }
+ * 
+ *     toJSON() {
+ *         const result = {};
+ *         for (const [key, value] of Object.entries(this.attributes)) {
+ *             if (value instanceof Model) {
+ *                 result[key] = value.toJSON();
+ *             } else {
+ *                 result[key] = value;
+ *             }
+ *         }
+ *         return result;
+ *     }
+ * 
+ *     async fetch() {
+ *         try {
+ *             const response = await fetch(`${this.apiUrl}/${this.id}`);
+ *             const data = await response.json();
+ *             
+ *             // Parse the fetched data and update model
+ *             const parsed = this.parse(data);
+ *             this.set(parsed, { source : 'fetch' });
+ * 
+ *             return this;
+ *         } catch (error) {
+ *             console.error('Failed to fetch order:', error);
+ *             throw error;
+ *         }
  *     }
  * }
- * // Create a product instance with a name and price.
- * const product = new ProductModel({ name: 'Smartphone', price: 1000 });
- * // Listen to the `change:price` event.
- * product.on('change:price', () => console.log('New Price:', product.price));
- * // Apply a 10% discount to the product.
- * product.setDiscount(10); // Output: "New Price: 900"
+ * 
+ * // Create order with nested user data
+ * const order = new Order({
+ *     id : 123,
+ *     total : 99.99,
+ *     user : { name : 'Alice', email : 'alice@example.com' }
+ * });
+ * 
+ * console.log(order.user instanceof User); // true
+ * // Serialize with nested models
+ * const json = order.toJSON();
+ * console.log(json); // { id: 123, total: 99.99, status: 'pending', user: { name: 'Alice', email: 'alice@example.com', role: 'user' } }
+ * 
+ * // Listen to fetch updates
+ * order.on('change', (model, changed, options) => {
+ *     if (options?.source === 'fetch') {
+ *         console.log('Order updated from server:', changed);
+ *     }
+ * });
+ * 
+ * // Fetch latest data from server
+ * await order.fetch();
  */
 class Model extends Emitter {
-    constructor(attributes = {}) {
+    constructor() {
         super();
         // Call preinitialize.
         this.preinitialize.apply(this, arguments);
-        // Get defaults. If `this.defaults` is a function, call it.
-        const defaults = utils_getResult(this.defaults, this) || {};
         // Set attributes object with defaults and passed attributes.
-        this.attributes = Object.assign({}, defaults, attributes);
+        this.attributes = Object.assign({}, utils_getResult(this.defaults, this), this.parse.apply(this, arguments));
         // Object to store previous attributes when a change occurs.
         this.previous = {};
         // Generate getters/setters for every attribute.
@@ -66,21 +125,53 @@ class Model extends Emitter {
     }
 
     /**
-     * If you define a preinitialize method, it will be invoked when the Model is first created, before any instantiation logic is run for the Model.
-     * @param {object} attributes Object containing model attributes to extend `this.attributes`.
+     * Called before any instantiation logic runs for the Model.
+     * Receives all constructor arguments, allowing for flexible initialization patterns.
+     * Use this to set up `defaults`, configure the model, or handle custom constructor arguments.
+     * @param {object} [attributes={}] Primary data object containing model attributes
+     * @param {...*} [args] Additional arguments passed from the constructor
+     * @example
+     * class User extends Model {
+     *     preinitialize(attributes, options = {}) {
+     *         this.defaults = { name : '', role : options.defaultRole || 'user' };
+     *         this.apiEndpoint = options.apiEndpoint || '/users';
+     *     }
+     * }
+     * const user = new User({ name : 'Alice' }, { defaultRole : 'admin', apiEndpoint : '/api/users' });
      */
     preinitialize() {}
 
     /**
-     * Generate getter/setter for the given key. In order to emit `change` events.
-     * This method is called internally by the constructor
-     * for `this.attributes`.
-     * @param {string} key Attribute key.
+     * Generate getter/setter for the given attribute key to emit `change` events.
+     * The property name uses `attributePrefix` + key (e.g., with prefix 'attr_', key 'name' becomes 'attr_name').
+     * Called internally by the constructor for each key in `this.attributes`.
+     * Override with an empty method if you don't want automatic getters/setters.
+     * 
+     * @param {string} key Attribute key from `this.attributes`
+     * @example
+     * // Custom prefix for all attributes
+     * class PrefixedModel extends Model {
+     *     static attributePrefix = 'attr_';
+     * }
+     * const model = new PrefixedModel({ name: 'Alice' });
+     * console.log(model.attr_name); // 'Alice'
+     * 
+     * // Disable automatic getters/setters
+     * class ManualModel extends Model {
+     *     defineAttribute() {
+     *         // Empty - no getters/setters generated
+     *     }
+     *     
+     *     getName() {
+     *         return this.get('name'); // Manual getter
+     *     }
+     * }
      */
     defineAttribute(key) {
         Object.defineProperty(
             this,
-            key, {
+            `${this.constructor.attributePrefix}${key}`,
+            {
                 get : () => this.get(key),
                 set : (value) => { this.set(key, value); }
             }
@@ -98,18 +189,28 @@ class Model extends Emitter {
     }
 
     /**
-     * Set an attribute into `this.attributes`.  
-     * Emit `change` and `change:attribute` if a value changes.  
-     * Could be called in two forms, `this.set('key', value)` and
-     * `this.set({ key : value })`.  
-     * This method is called internally by generated setters.  
-     * The `change` event listener will receive the model instance, an object containing the changed attributes, and the rest of the arguments passed to `set` method.  
-     * The `change:attribute` event listener will receive the model instance, the new attribute value, and the rest of the arguments passed to `set` method.
-     * @param {string} key Attribute key or object containing keys/values.
-     * @param [value] Attribute value.
-     * @return {this} This model.
-     * @emits change
-     * @emits change:attribute
+     * Set one or more attributes into `this.attributes` and emit change events.
+     * Supports two call signatures: `set(key, value, ...args)` or `set(object, ...args)`.
+     * Additional arguments are passed to change event listeners, enabling custom behavior.
+     * 
+     * @param {string|object} key Attribute key (string) or object containing key-value pairs
+     * @param {*} [value] Attribute value (when key is string)
+     * @param {...*} [args] Additional arguments passed to event listeners
+     * @return {Model} This model instance for chaining
+     * @emits change Emitted when any attribute changes. Listeners receive `(model, changedAttributes, ...args)`
+     * @emits change:attribute Emitted for each changed attribute. Listeners receive `(model, newValue, ...args)`
+     * @example
+     * // Basic usage
+     * model.set('name', 'Alice');
+     * model.set({ name : 'Alice', age : 30 });
+     * 
+     * // With options for listeners
+     * model.set('name', 'Bob', { silent : false, validate : true });
+     * model.on('change:name', (model, value, options) => {
+     *     if (options?.validate) {
+     *         // Custom validation logic
+     *     }
+     * });
      */
     set(key, value, ...rest) {
         let attrs, args;
@@ -163,14 +264,99 @@ class Model extends Emitter {
         return this;
     }
 
+    /**
+     * Transforms and validates data before it becomes model attributes.
+     * Called during construction with all constructor arguments, allowing flexible data processing.
+     * Override this method to transform incoming data, create nested models, or handle different data formats.
+     * 
+     * @param {object} [data={}] Primary data object to be parsed into attributes
+     * @param {...*} [args] Additional arguments from constructor, useful for parsing options
+     * @return {object} Processed data that will become the model's attributes
+     * @example
+     * // Transform nested objects into models
+     * class User extends Model {}
+     * class Order extends Model {
+     *     parse(data, options = {}) {
+     *         // Skip parsing if requested
+     *         if (options.raw) return data;
+     *         // Transform user data into User model
+     *         const parsed = { ...data };
+     *         if (data.user && !(data.user instanceof User)) {
+     *             parsed.user = new User(data.user);
+     *         }
+     *         return parsed;
+     *     }
+     * }
+     * 
+     * // Usage with parsing options
+     * const order1 = new Order({ id : 1, user : { name : 'Alice' } }); // user becomes User model
+     * const order2 = new Order({ id : 2, user : { name : 'Bob' } }, { raw : true }); // user stays plain object
+     */
+    parse(data) {
+        return data;
+    }
+
     /**
      * Return object representation of the model to be used for JSON serialization.
      * By default returns a copy of `this.attributes`.
+     * You can override this method to customize serialization behavior, such as calling `toJSON` recursively on nested Model instances.
      * @return {object} Object representation of the model to be used for JSON serialization.
+     * @example
+     * // Basic usage - returns a copy of model attributes:
+     * const user = new Model({ name : 'Alice', age : 30 });
+     * const json = user.toJSON();
+     * console.log(json); // { name : 'Alice', age : 30 }
+     * 
+     * // Override toJSON for recursive serialization of nested models:
+     * class User extends Model {}
+     * class Order extends Model {
+     *     parse(data) {
+     *         // Ensure user is always a User model
+     *         return { ...data, user : data.user instanceof User ? data.user : new User(data.user) };
+     *     }
+     * 
+     *     toJSON() {
+     *         const result = {};
+     *         for (const [key, value] of Object.entries(this.attributes)) {
+     *             if (value instanceof Model) {
+     *                 result[key] = value.toJSON();
+     *             } else {
+     *                 result[key] = value;
+     *             }
+     *         }
+     *         return result;
+     *     }
+     * }
+     * const order = new Order({ id : 1, user : { name : 'Alice' } });
+     * const json = order.toJSON();
+     * console.log(json); // { id : 1, user : { name : 'Alice' } }
      */
     toJSON() {
         return Object.assign({}, this.attributes);
     }
 }
 
+/**
+ * Static property that defines a prefix for generated getters/setters.
+ * When set, all attribute properties will be prefixed (e.g., 'attr_name' instead of 'name').
+ * Useful for avoiding naming conflicts or creating a consistent property naming convention.
+ * @type {string}
+ * @default ''
+ * @example
+ * // Set prefix for all models of this class
+ * class ApiModel extends Model {
+ *     static attributePrefix = 'attr_';
+ * }
+ * 
+ * const user = new ApiModel({ name : 'Alice', email : 'alice@example.com' });
+ * console.log(user.attr_name);  // 'Alice'
+ * console.log(user.attr_email); // 'alice@example.com'
+ * 
+ * // Still access via get/set methods without prefix
+ * console.log(user.get('name')); // 'Alice'
+ * user.set('name', 'Bob');
+ * console.log(user.attr_name); // 'Bob'
+ */
+Model.attributePrefix = '';
+
 module.exports = Model;