miolo-model 3.0.0-beta.222 → 3.0.0-beta.225

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "miolo-model",
-  "version": "3.0.0-beta.222",
+  "version": "3.0.0-beta.225",
   "description": "Data models for miolo world",
   "author": "Donato Lorenzo <donato@afialapis.com>",
   "contributors": [

package/src/CacheMixin.mjs

@@ -1,11 +1,25 @@
 export default (BaseClass = class {}) =>
   class extends BaseClass {
+    /**
+     * Reset the model's cache.
+     * @public
+     */
     reset_cache() {
       this.__cache__ = {}
     }
 
+    /**
+     * Reset the model's cache.
+     * @public
+     */
     resetCache = this.reset_cache
 
+    /**
+     * Get a value from the model's cache.
+     * @param {string} key - The key to get the value from.
+     * @returns {any} The value from the cache.
+     * @public
+     */
     get_from_cache(key) {
       if (this.__cache__ === undefined) {
         return undefined
@@ -13,8 +27,20 @@ export default (BaseClass = class {}) =>
       return this.__cache__[key]
     }
 
+    /**
+     * Get a value from the model's cache.
+     * @param {string} key - The key to get the value from.
+     * @returns {any} The value from the cache.
+     * @public
+     */
     getFromCache = this.get_from_cache
 
+    /**
+     * Set a value in the model's cache.
+     * @param {string} key - The key to set the value to.
+     * @param {any} value - The value to set.
+     * @public
+     */
     set_to_cache(key, value) {
       if (this.__cache__ === undefined) {
         this.__cache__ = {}
@@ -22,8 +48,21 @@ export default (BaseClass = class {}) =>
       this.__cache__[key] = value
     }
 
+    /**
+     * Set a value in the model's cache.
+     * @param {string} key - The key to set the value to.
+     * @param {any} value - The value to set.
+     * @public
+     */
     setToCache = this.set_to_cache
 
+    /**
+     * Get a value from the model's cache or make it if it doesn't exist.
+     * @param {string} cache_key - The key to get the value from.
+     * @param {Function} make_callback - The function to make the value if it doesn't exist.
+     * @returns {any} The value from the cache.
+     * @public
+     */
     get_from_cache_or_make(cache_key, make_callback) {
       if (this.__cache__ === undefined) {
         this.__cache__ = {}
@@ -35,13 +74,30 @@ export default (BaseClass = class {}) =>
       return this.__cache__[cache_key]
     }
 
+    /**
+     * Get a value from the model's cache or make it if it doesn't exist.
+     * @param {string} cache_key - The key to get the value from.
+     * @param {Function} make_callback - The function to make the value if it doesn't exist.
+     * @returns {any} The value from the cache.
+     * @public
+     */
     getFromCacheOrMake = this.get_from_cache_or_make
 
+    /**
+     * Invalidate a value in the model's cache.
+     * @param {string} cache_key - The key to invalidate.
+     * @public
+     */
     invalidate_cache(cache_key) {
       if (this.__cache__ !== undefined) {
         delete this.__cache__[cache_key]
       }
     }
 
+    /**
+     * Invalidate a value in the model's cache.
+     * @param {string} cache_key - The key to invalidate.
+     * @public
+     */
     invalidateCache = this.invalidate_cache
   }

package/src/MioloArray.mjs

@@ -1,6 +1,19 @@
 import CacheMixin from "./CacheMixin.mjs"
 
+/**
+ * Represents an array of MioloModel instances.
+ * Inherits all native JS Array methods.
+ *
+ * @template T
+ * @extends {Array<T>}
+ */
 export default class MioloArray extends CacheMixin(Array) {
+  /**
+   * Create a new MioloArray.
+   * @param {Function} itemClass - The class of the items in the array.
+   * @param {Array<MioloModel> | Array<Object>} items - The items to initialize the array with.
+   * @param {...any} extra - Extra parameters to pass to the item class constructor.
+   */
   constructor(itemClass, items = [], ...extra) {
     // Arrays can be inited with a number
     if (typeof items === "number") {
@@ -25,18 +38,46 @@ export default class MioloArray extends CacheMixin(Array) {
     })
   }
 
+  /**
+   * Returns the last item in the array.
+   * @returns {MioloModel} The last item in the array.
+   * @public
+   */
   last() {
     return this[this.length - 1]
   }
 
+  /**
+   * Returns an Object data containing both:
+   *   - the instance inner data
+   *   - data from attriobutes of type MioloModel or MioloArray
+   *       (attributes with prefix "__" are ignored).
+   * @returns {Object} All the data of the instance.
+   * @public
+   */
   get_data() {
     return [...this].map((i) => i.get_data())
   }
 
+  /**
+   * Returns an Object data containing both:
+   *   - the instance inner data
+   *   - data from attriobutes of type MioloModel or MioloArray
+   *       (attributes with prefix "__" are ignored).
+   * @returns {Object} All the data of the instance.
+   * @public
+   */
   getData() {
     return [...this].map((i) => i.getData())
   }
 
+  /**
+   * Find the index of the first item in the array that has the given field and value.
+   * @param {string} field - The field to search for.
+   * @param {any} value - The value to search for.
+   * @returns {number} The index of the first item that has the given field and value, or -1 if not found.
+   * @public
+   */
   find_index_by_field(field, value) {
     if (this.length >= 0) {
       const fidx = this.findIndex((elem) => {
@@ -50,10 +91,24 @@ export default class MioloArray extends CacheMixin(Array) {
     return -1
   }
 
+  /**
+   * Find the index of the first item in the array that has the given field and value.
+   * @param {string} field - The field to search for.
+   * @param {any} value - The value to search for.
+   * @returns {number} The index of the first item that has the given field and value, or -1 if not found.
+   * @public
+   */
   findIndexByField(field, value) {
     return this.find_index_by_field(field, value)
   }
 
+  /**
+   * Find the first item in the array that has the given field and value.
+   * @param {string} field - The field to search for.
+   * @param {any} value - The value to search for.
+   * @returns {MioloModel} The first item in the array that has the given field and value, or undefined if not found.
+   * @public
+   */
   find_by_field(field, value) {
     if (this.length >= 0) {
       const filt = this.filter((elem) => {
@@ -67,18 +122,43 @@ export default class MioloArray extends CacheMixin(Array) {
     return undefined
   }
 
+  /**
+   * Find the first item in the array that has the given field and value.
+   * @param {string} field - The field to search for.
+   * @param {any} value - The value to search for.
+   * @returns {MioloModel} The first item in the array that has the given field and value, or undefined if not found.
+   * @public
+   */
   findByField(field, value) {
     return this.find_by_field(field, value)
   }
 
+  /**
+   * Find the first item in the array that has the given id.
+   * @param {string} id - The id to search for.
+   * @returns {MioloModel} The first item in the array that has the given id, or undefined if not found.
+   * @public
+   */
   find_by_id(id) {
     return this.find_by_field("id", id)
   }
 
+  /**
+   * Find the first item in the array that has the given id.
+   * @param {string} id - The id to search for.
+   * @returns {MioloModel} The first item in the array that has the given id, or undefined if not found.
+   * @public
+   */
   findById(id) {
     return this.find_by_id(id)
   }
 
+  /**
+   * Remove the first item in the array that has the given field and value.
+   * @param {string} field - The field to search for.
+   * @param {any} value - The value to search for.
+   * @public
+   */
   remove_by_field(field, value) {
     const fidx = this.find_index_by_field(field, value)
     if (fidx >= 0) {
@@ -86,10 +166,22 @@ export default class MioloArray extends CacheMixin(Array) {
     }
   }
 
+  /**
+   * Remove the first item in the array that has the given field and value.
+   * @param {string} field - The field to search for.
+   * @param {any} value - The value to search for.
+   * @public
+   */
   removeByField(field, value) {
     return this.remove_by_field(field, value)
   }
 
+  /**
+   * Push a new item to the end of the array.
+   * @param {Object} data - The data to push to the array.
+   * @returns {MioloModel | Object} The new item.
+   * @public
+   */
   push(data) {
     const item =
       data !== undefined && data instanceof this.itemClass ? data : new this.itemClass(data)
@@ -97,6 +189,11 @@ export default class MioloArray extends CacheMixin(Array) {
     return item
   }
 
+  /**
+   * Creates a shallow clone of the model.
+   * @returns {MioloArray} A shallow clone of the model.
+   * @public
+   */
   clone() {
     const currentData = this.getData()
     const clonedData = JSON.parse(JSON.stringify(currentData))

package/src/MioloModel.mjs

@@ -2,13 +2,27 @@ import CacheMixin from "./CacheMixin.mjs"
 import MioloArray from "./MioloArray.mjs"
 
 export default class MioloModel extends CacheMixin() {
+  /**
+   * Initialize a new MioloModel.
+   * Notice the attributes you set to your instance may be handled by MioloModel:
+   *   - if you set an attribute of type MioloModel or MioloArray, it will be taken by get_data() / getData() methods
+   *   - if you want an attribute of type MioloModel or MioloArray to be ignored by get_data() / getData() methods, you can prefix it with "__" (e.g. __my_attr)
+   * @param {Object} data - The data to initialize the model with.
+   */
   constructor(data) {
     super()
     this.data = data
     this.reset_cache()
   }
 
-  _get(field, def) {
+  /**
+   * Get a value from the model's data.
+   * @param {string} field - The field to get the value from.
+   * @param {any} def - The default value to return if the field is not found.
+   * @returns {any} The value from the model's data.
+   * @public
+   */
+  get_value(field, def) {
     if (this.data !== undefined) {
       if (this.data[field] !== undefined && this.data[field] !== null) {
         return this.data[field]
@@ -17,14 +31,49 @@ export default class MioloModel extends CacheMixin() {
     return def
   }
 
-  _set(field, val) {
+  /**
+   * Get a value from the model's data.
+   * @param {string} field - The field to get the value from.
+   * @param {any} def - The default value to return if the field is not found.
+   * @returns {any} The value from the model's data.
+   * @public
+   * @deprecated Use get_value() instead.
+   */
+  _get(field, def) {
+    return this.get_value(field, def)
+  }
+
+  /**
+   * Set a value in the model's data.
+   * @param {string} field - The field to set the value to.
+   * @param {any} val - The value to set.
+   * @public
+   */
+  set_value(field, val) {
     if (this.data === undefined) {
       this.data = {}
     }
     this.data[field] = val
   }
 
-  get_extra_data() {
+  /**
+   * Set a value in the model's data.
+   * @param {string} field - The field to set the value to.
+   * @param {any} val - The value to set.
+   * @public
+   * @deprecated Use set_value() instead.
+   */
+  _set(field, val) {
+    this.set_value(field, val)
+  }
+
+  /**
+   * Returns an Object data corresponding to MioloModel and MioloArray instances attributes of this instance.
+   * Attributes with prefix "__" are ignored.
+   * @returns {Object} The extra data from the model.
+   * @private
+   */
+  _get_extra_data() {
     const data = {}
     for (const [key, value] of Object.entries(this)) {
       if (key.startsWith("__")) {
@@ -39,7 +88,13 @@ export default class MioloModel extends CacheMixin() {
     return data
   }
 
-  getExtraData() {
+  /**
+   * Returns an Object data corresponding to MioloModel and MioloArray instances attributes of this instance.
+   * Attributes with prefix "__" are ignored.
+   * @returns {Object} The extra data from the model.
+   * @private
+   */
+  _getExtraData() {
     const data = {}
     for (const [key, value] of Object.entries(this)) {
       if (key.startsWith("__")) {
@@ -54,22 +109,46 @@ export default class MioloModel extends CacheMixin() {
     return data
   }
 
+  /**
+   * Returns an Object data containing both:
+   *   - the instance inner data
+   *   - data from attriobutes of type MioloModel or MioloArray
+   *       (attributes with prefix "__" are ignored).
+   * @returns {Object} All the data of the instance.
+   * @public
+   */
   get_data() {
-    const extra = this.get_extra_data() || {}
+    const extra = this._get_extra_data() || {}
     return {
       ...this.data,
       ...extra
     }
   }
 
+  /**
+   * Returns an Object data containing both:
+   *   - the instance inner data
+   *   - data from attriobutes of type MioloModel or MioloArray
+   *       (attributes with prefix "__" are ignored).
+   * @returns {Object} All the data of the instance.
+   * @public
+   */
   getData() {
-    const extra = this.getExtraData() || {}
+    const extra = this._getExtraData() || {}
     return {
       ...this.data,
       ...extra
     }
   }
 
+  /**
+   * Update the model's inner data with changes.
+   * It resetes model's inner cache.
+   * Does the same (updating data and resetting cache) for nested MioloModel or MioloArray attributes
+   *  (ignoring those prefixed with "__").
+   * @param {Object} changes - The changes to apply to the model.
+   * @public
+   */
   update(changes) {
     this.reset_cache()
 
@@ -93,6 +172,14 @@ export default class MioloModel extends CacheMixin() {
     }
   }
 
+  /**
+   * Update the model's inner data by merging another model's data with it.
+   * It resetes model's inner cache.
+   * Does the same (updating data and resetting cache) for nested MioloModel or MioloArray attributes
+   *  (ignoring those prefixed with "__").
+   * @param {Object} model - The model to merge with.
+   * @public
+   */
   merge(model) {
     this.update(model.getData())
     for (const [key, value] of Object.entries(model)) {
@@ -107,6 +194,11 @@ export default class MioloModel extends CacheMixin() {
     }
   }
 
+  /**
+   * Creates a shallow clone of the model.
+   * @returns {MioloModel} A shallow clone of the model.
+   * @public
+   */
   clone() {
     const currentData = this.getData()
     const clonedData = JSON.parse(JSON.stringify(currentData))