@acodeninja/persist 3.0.0-next.14 → 3.0.0-next.16

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@acodeninja/persist",
-  "version": "3.0.0-next.14",
+  "version": "3.0.0-next.16",
   "description": "A JSON based data modelling and persistence module with alternate storage mechanisms.",
   "type": "module",
   "scripts": {

package/src/Connection.js

@@ -7,6 +7,14 @@ import Model from './data/Model.js';
 import SearchIndex from './data/SearchIndex.js';
 import _ from 'lodash';
 
+/**
+ * Represents a transactional operation to be executed, typically queued and later committed.
+ *
+ * Stores the method to invoke, the arguments to apply, and tracks the result or error state
+ * of the transaction once it's processed.
+ *
+ * @class Transaction
+ */
 export class Transaction {
     constructor(method, ...args) {
         this.method = method;
@@ -81,6 +89,12 @@ export default class Connection {
     async hydrate(dryModel) {
         const hydratedModels = {};
 
+        /**
+         * Recursively hydrates a single model and its nested properties.
+         *
+         * @param {Object|Model} modelToProcess - The model instance to hydrate.
+         * @returns {Promise<Model>} The hydrated model instance.
+         */
         const hydrateModel = async (modelToProcess) => {
             hydratedModels[modelToProcess.id] = modelToProcess;
 
@@ -97,6 +111,12 @@ export default class Connection {
             return modelToProcess;
         };
 
+        /**
+         * Hydrates a nested sub-model if it hasn't already been hydrated.
+         *
+         * @param {Object} property - The sub-model with a known ID but incomplete data.
+         * @returns {Promise<Model>} The fully hydrated sub-model.
+         */
         const hydrateSubModel = async (property) => {
             if (hydratedModels[property.id]) {
                 return hydratedModels[property.id];
@@ -109,6 +129,12 @@ export default class Connection {
             return hydratedSubModel;
         };
 
+        /**
+         * Hydrates a list of related sub-models.
+         *
+         * @param {Array<Object>} property - Array of dry sub-models.
+         * @returns {Promise<Array<Model>>} Array of hydrated sub-models.
+         */
         const hydrateModelList = async (property) => {
             const newModelList = await Promise.all(property.map(subModel => {
                 if (hydratedModels[subModel.id]) {
@@ -165,7 +191,7 @@ export default class Connection {
 
             if (
                 Boolean(modelToProcess.constructor.indexedProperties().length) &&
-                this.#indexedFieldsHaveChanged(currentModel, modelToProcess)
+                (!currentModel || JSON.stringify(currentModel.toIndexData()) !== JSON.stringify(modelToProcess.toIndexData()))
             ) {
                 const modelToProcessConstructor = this.#getModelConstructorFromId(modelToProcess.id);
                 modelsToReindex[modelToProcessConstructor] = modelsToReindex[modelToProcessConstructor] || [];
@@ -174,7 +200,7 @@ export default class Connection {
 
             if (
                 Boolean(modelToProcess.constructor.searchProperties().length) &&
-                this.#searchableFieldsHaveChanged(currentModel, modelToProcess)
+                (!currentModel || JSON.stringify(currentModel.toSearchData()) !== JSON.stringify(modelToProcess.toSearchData()))
             ) {
                 const modelToProcessConstructor = this.#getModelConstructorFromId(modelToProcess.id);
                 modelsToReindexSearch[modelToProcessConstructor] = modelsToReindexSearch[modelToProcessConstructor] || [];
@@ -458,28 +484,6 @@ export default class Connection {
         return constructor;
     }
 
-    /**
-     * Decide if two models indexable fields are different
-     * @param {Model} currentModel
-     * @param {Model} modelToProcess
-     * @return {boolean}
-     * @private
-     */
-    #indexedFieldsHaveChanged(currentModel, modelToProcess) {
-        return !currentModel || JSON.stringify(currentModel.toIndexData()) !== JSON.stringify(modelToProcess.toIndexData());
-    }
-
-    /**
-     * Decide if two models searchable fields have changed
-     * @param {Model} currentModel
-     * @param {Model} modelToProcess
-     * @return {boolean}
-     * @private
-     */
-    #searchableFieldsHaveChanged(currentModel, modelToProcess) {
-        return !currentModel || JSON.stringify(currentModel.toSearchData()) !== JSON.stringify(modelToProcess.toSearchData());
-    }
-
     /**
      * Get model classes that are directly linked to the given model in either direction
      * @param {Model.constructor} model
@@ -560,22 +564,26 @@ export default class Connection {
 }
 
 /**
+ * Base class for errors that occur during connection operations.
+ *
  * @class ConnectionError
  * @extends Error
  */
 export class ConnectionError extends Error {
-    /**
-     * @param {String} message
-     */
-    constructor(message) {
-        super(message);
-    }
 }
 
+/**
+ * Thrown when a connection is created with missing arguments.
+ *
+ * @class MissingArgumentsConnectionError
+ * @extends ConnectionError
+ */
 export class MissingArgumentsConnectionError extends ConnectionError {
 }
 
 /**
+ * Thrown when a model class is not registered.
+ *
  * @class ModelNotRegisteredConnectionError
  * @extends ConnectionError
  */
@@ -590,12 +598,23 @@ export class ModelNotRegisteredConnectionError extends ConnectionError {
     }
 }
 
+/**
+ * Base class for errors that occur during transactions.
+ *
+ * @class TransactionError
+ * @extends {Error}
+ */
 class TransactionError extends Error {
-    constructor(message) {
-        super(message);
-    }
 }
 
+/**
+ * Thrown when a transaction fails to commit.
+ *
+ * Contains the original error and the list of transactions involved.
+ *
+ * @class CommitFailedTransactionError
+ * @extends {TransactionError}
+ */
 export class CommitFailedTransactionError extends TransactionError {
     /**
      *

package/src/Schema.js

@@ -26,6 +26,15 @@ class Schema {
         ajvErrors(validation);
         ajvFormats(validation);
 
+        /**
+         * Recursively builds a JSON-schema-like object from a model or schema segment.
+         *
+         * Handles both `Model` instances and schema property definitions,
+         * including nested models and required property rules.
+         *
+         * @param {Object|Model|Type} schemaSegment - A model or a property descriptor.
+         * @returns {Object} A JSON schema representation of the input segment.
+         */
         function BuildSchema(schemaSegment) {
             const thisSchema = {};
 

package/src/data/Model.js

@@ -151,6 +151,14 @@ class Model {
      * @static
      */
     static get required() {
+        /**
+         * A subclass of the current model with the `_required` flag set to `true`.
+         * Used to indicate that the property is required during validation or schema generation.
+         *
+         * @class
+         * @extends {Model}
+         * @private
+         */
         class Required extends this {
             static _required = true;
         }

package/src/data/SearchIndex.js

@@ -1,5 +1,10 @@
 import lunr from 'lunr';
 
+/**
+ * Represents a single search result with the associated model instance and its relevance score.
+ *
+ * @class SearchResult
+ */
 export class SearchResult {
     constructor(model, score) {
         this.model = model;
@@ -7,11 +12,24 @@ export class SearchResult {
     }
 }
 
+/**
+ * A full-text search index wrapper using Lunr.js for a given model.
+ * Supports indexing and querying model data.
+ *
+ * @class SearchIndex
+ */
 export default class SearchIndex {
     #index;
     #model;
     #compiledIndex;
 
+    /**
+     * Initializes the search index for the provided model.
+     *
+     * @param {Model} model - The model definition to use for indexing.
+     * @param {Object.<string, Object>} index - A dictionary of model data, keyed by ID.
+     * @throws {NoIndexAvailableSearchIndexError} If the model has no searchable properties.
+     */
     constructor(model, index) {
         this.#index = index;
         this.#model = model;
@@ -21,9 +39,10 @@ export default class SearchIndex {
     }
 
     /**
+     * Performs a search query on the compiled Lunr index.
      *
-     * @param {string} query
-     * @return {Array<SearchResult>}
+     * @param {string} query - The search string.
+     * @return {Array<SearchResult>} An array of search results with model instances and scores.
      */
     search(query) {
         return this.searchIndex
@@ -31,10 +50,21 @@ export default class SearchIndex {
             .map(doc => new SearchResult(this.#model.fromData(this.#index[doc.ref]), doc.score));
     }
 
+    /**
+     * Lazily compiles and returns the Lunr index instance.
+     *
+     * @return {lunr.Index} The compiled Lunr index.
+     */
     get searchIndex() {
         return this.#compiledIndex ?? this.#compileIndex();
     }
 
+    /**
+     * Compiles the Lunr index using the model's search properties.
+     *
+     * @return {lunr.Index} The compiled Lunr index.
+     * @private
+     */
     #compileIndex() {
         const model = this.#model;
         const index = this.#index;
@@ -54,9 +84,21 @@ export default class SearchIndex {
     }
 }
 
+/**
+ * Base error class for search index-related exceptions.
+ *
+ * @class SearchIndexError
+ * @extends {Error}
+ */
 export class SearchIndexError extends Error {
 }
 
+/**
+ * Thrown when a model does not have any properties defined for indexing.
+ *
+ * @class NoIndexAvailableSearchIndexError
+ * @extends {SearchIndexError}
+ */
 export class NoIndexAvailableSearchIndexError extends SearchIndexError {
     constructor(model) {
         super(`The model ${model.name} has no search properties`);

package/src/data/properties/Type.js

@@ -53,6 +53,14 @@ class Type {
      * @returns {Type} A subclass of the current type with `_required` set to `true`.
      */
     static get required() {
+        /**
+         * A subclass of the current type with the `_required` flag set to `true`.
+         * Used to indicate that the property is required during validation or schema generation.
+         *
+         * @class
+         * @extends {Type}
+         * @private
+         */
         class Required extends this {
             static _required = true;
         }