@acodeninja/persist 2.2.0 → 2.2.2

package/.deepsource.toml

@@ -0,0 +1,10 @@
+version = 1
+
+[[analyzers]]
+name = "javascript"
+
+  [analyzers.meta]
+  environment = [
+    "nodejs",
+    "browser"
+  ]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@acodeninja/persist",
-  "version": "2.2.0",
+  "version": "2.2.2",
   "description": "A JSON based data modelling and persistence module with alternate storage mechanisms.",
   "type": "module",
   "scripts": {
@@ -26,6 +26,7 @@
     "ajv": "^8.16.0",
     "ajv-errors": "^3.0.0",
     "ajv-formats": "^3.0.1",
+    "lodash": "^4.17.21",
     "lunr": "^2.3.9",
     "slugify": "^1.6.6",
     "ulid": "^2.3.0"
@@ -43,7 +44,6 @@
     "eslint": "^9.6.0",
     "globals": "^15.8.0",
     "husky": "^9.1.1",
-    "lodash": "^4.17.21",
     "monocart-coverage-reports": "^2.10.2",
     "semantic-release": "^24.0.0",
     "sinon": "^18.0.0"

package/src/Persist.js

@@ -4,7 +4,7 @@ import enableTransactions from './Transactions.js';
 /**
  * @class Persist
  */
-export default class Persist {
+class Persist {
     static _engine = {};
     /**
      * @memberof Persist
@@ -42,3 +42,5 @@ export default class Persist {
                 engine.configure(configuration);
     }
 }
+
+export default Persist;

package/src/Query.js

@@ -1,39 +1,60 @@
 /**
- * persist query language features:
- * - value match {title: 'test'} or {title: {$is: 'test'}}
- * - contains match {list: {$contains: 'test'}} or {string: {$contains: 'es'}}
- * - nested query {list: {$contains: {slug: 'test'}}}
- * - deep nesting queries {list: {$contains: {string: {$contains: 'test'}}}}
- */
-
-/**
- * @class Query
+ * The `Query` class is responsible for executing searches on an indexed dataset
+ * based on a structured query. It supports various query types including value matches,
+ * contains matches, and nested queries.
+ *
+ * @example
+ * // The object has the property `title` witch exactly equals `test`.
+ * const query = new Query({title: 'test'});
+ * const query = new Query({title: {$is: 'test'}});
+ *
+ * // The object has the property `list` witch contains the string `test`.
+ * const query = new Query({list: {$contains: 'test'}});
+ *
+ * // The object has the property `string` witch contains the string `es`.
+ * const query = new Query({string: {$contains: 'es'}});
+ *
+ * // The object has the property `list` contains an object
+ * // with a property `string` that contains the string `test`.
+ * const query = new Query({
+ *   list: {
+ *     $contains: {
+ *       string: {
+ *         $contains: 'test'
+ *       }
+ *     }
+ *   }
+ * });
  */
 class Query {
+    /**
+     * The query object that defines the search criteria.
+     * @type {Object}
+     */
     query;
 
     /**
+     * Constructs a new `Query` instance with the provided query object.
      *
-     * @param {object} query
+     * @param {Object} query - The structured query object defining the search criteria.
      */
     constructor(query) {
         this.query = query;
     }
 
     /**
-     * Using the input query, find records in an index that match
+     * Executes the query against a model's index and returns the matching results.
      *
-     * @param {typeof Model} model
-     * @param {object} index
+     * @param {Model.constructor} model - The model class that contains the `fromData` method for constructing models from data.
+     * @param {Object<string, Model>} index - The index dataset to search through.
+     * @returns {Array<Model>} The models that match the query.
      */
     execute(model, index) {
-        const matchIs = (query) => !!query?.$is;
+        const matchIs = (query) => query?.$is !== undefined;
         const matchPrimitive = (query) => ['string', 'number', 'boolean'].includes(typeof query);
         const matchContains = (query) => !!query?.$contains;
 
         const matchesQuery = (subject, inputQuery = this.query) => {
-            if (!subject || !inputQuery) return false;
-
             if (matchPrimitive(inputQuery)) return subject === inputQuery;
 
             if (matchIs(inputQuery))

package/src/SchemaCompiler.js

@@ -4,13 +4,21 @@ import ajvErrors from 'ajv-errors';
 import ajvFormats from 'ajv-formats';
 
 /**
- * @class SchemaCompiler
+ * A class responsible for compiling raw schema definitions into a format that can be validated using the AJV (Another JSON Validator) library.
  */
-export default class SchemaCompiler {
+class SchemaCompiler {
     /**
-     * @method compile
-     * @param {Model|object} rawSchema
-     * @return {CompiledSchema}
+     * Compiles a raw schema into a validation-ready schema, and returns a class that extends `CompiledSchema`.
+     *
+     * This method converts a given schema into a JSON schema-like format, setting up properties, types, formats, and validation rules.
+     * It uses AJV for the validation process and integrates with model types and their specific validation rules.
+     *
+     * @param {Object|Model} rawSchema - The raw schema or model definition to be compiled.
+     * @returns {CompiledSchema} - A class that extends `CompiledSchema`, with the compiled schema and validator attached.
+     *
+     * @example
+     * const schemaClass = SchemaCompiler.compile(MyModelSchema);
+     * const isValid = schemaClass.validate(data); // Throws ValidationError if data is invalid.
      */
     static compile(rawSchema) {
         const validation = new ajv({allErrors: true});
@@ -27,7 +35,7 @@ export default class SchemaCompiler {
 
         if (Type.Model.isModel(rawSchema)) {
             schema.required.push('id');
-            schema.properties['id'] = {type: 'string'};
+            schema.properties.id = {type: 'string'};
         }
 
         for (const [name, type] of Object.entries(rawSchema)) {
@@ -88,7 +96,20 @@ export default class SchemaCompiler {
         }
 
         class Schema extends CompiledSchema {
+            /**
+             * The compiled schema definition.
+             * @type {Object}
+             * @static
+             * @private
+             */
             static _schema = schema;
+
+            /**
+             * The AJV validator function compiled from the schema.
+             * @type {Function}
+             * @static
+             * @private
+             */
             static _validator = validation.compile(schema);
         }
 
@@ -96,20 +117,36 @@ export default class SchemaCompiler {
     }
 }
 
+
 /**
- * @class CompiledSchema
- * @property {object} _schema
- * @property {Function} _validator
+ * Represents a compiled schema used for validating data models.
+ * This class provides a mechanism to validate data using a precompiled schema and a validator function.
  */
 export class CompiledSchema {
+    /**
+     * The schema definition for validation, typically a precompiled JSON schema or similar.
+     * @type {?Object}
+     * @static
+     * @private
+     */
     static _schema = null;
+
+    /**
+     * The validator function used to validate data against the schema.
+     * @type {?Function}
+     * @static
+     * @private
+     */
     static _validator = null;
 
     /**
-     * @method validate
-     * @param data
-     * @return {boolean}
-     * @throws {ValidationError}
+     * Validates the given data against the compiled schema.
+     *
+     * If the data is an instance of a model, it will be converted to a plain object via `toData()` before validation.
+     *
+     * @param {Object|Model} data - The data or model instance to be validated.
+     * @returns {boolean} - Returns `true` if the data is valid according to the schema.
+     * @throws {ValidationError} - Throws a `ValidationError` if the data is invalid.
      */
     static validate(data) {
         let inputData = Object.assign({}, data);
@@ -127,15 +164,29 @@ export class CompiledSchema {
 }
 
 /**
- * @class ValidationError
- * @extends Error
- * @property {object[]} errors
- * @property {object} data
+ * Represents a validation error that occurs when a model or data fails validation.
+ * Extends the built-in JavaScript `Error` class.
  */
 export class ValidationError extends Error {
+    /**
+     * Creates an instance of `ValidationError`.
+     *
+     * @param {Object} data - The data that failed validation.
+     * @param {Array<Object>} errors - A list of validation errors, each typically containing details about what failed.
+     */
     constructor(data, errors) {
         super('Validation failed');
+        /**
+         * An array of validation errors, containing details about each failed validation.
+         * @type {Array<Object>}
+         */
         this.errors = errors;
+        /**
+         * The data that caused the validation error.
+         * @type {Object}
+         */
         this.data = data;
     }
 }
+
+export default SchemaCompiler;

package/src/engine/Engine.js

@@ -3,43 +3,112 @@ import Type from '../type/index.js';
 import lunr from 'lunr';
 
 /**
+ * The `Engine` class provides a base interface for implementing data storage and retrieval engines.
+ * It includes methods for handling models, indexes, and search functionality.
+ *
  * @class Engine
  */
-export default class Engine {
-    static _configuration = undefined;
-
+class Engine {
+    static configuration = undefined;
+
+    /**
+     * Retrieves a model by its ID. This method must be implemented by subclasses.
+     *
+     * @param {string} _id - The ID of the model to retrieve.
+     * @throws {NotImplementedError} Throws if the method is not implemented.
+     * @abstract
+     */
     static async getById(_id) {
         throw new NotImplementedError(`${this.name} must implement .getById()`);
     }
 
+    /**
+     * Saves a model to the data store. This method must be implemented by subclasses.
+     *
+     * @param {Model} _data - The model data to save.
+     * @throws {NotImplementedError} Throws if the method is not implemented.
+     * @abstract
+     */
     static async putModel(_data) {
         throw new NotImplementedError(`${this.name} must implement .putModel()`);
     }
 
+    /**
+     * Retrieves the index for a given model. This method must be implemented by subclasses.
+     *
+     * @param {Model.constructor} _model - The model to retrieve the index for.
+     * @throws {NotImplementedError} Throws if the method is not implemented.
+     * @abstract
+     */
     static async getIndex(_model) {
         throw new NotImplementedError(`${this.name} does not implement .getIndex()`);
     }
 
+    /**
+     * Saves the index for a given model. This method must be implemented by subclasses.
+     *
+     * @param {Object} _index - The index data to save.
+     * @throws {NotImplementedError} Throws if the method is not implemented.
+     * @abstract
+     */
     static async putIndex(_index) {
         throw new NotImplementedError(`${this.name} does not implement .putIndex()`);
     }
 
+    /**
+     * Retrieves the compiled search index for a model. This method must be implemented by subclasses.
+     *
+     * @param {Model.constructor} _model - The model to retrieve the compiled search index for.
+     * @throws {NotImplementedError} Throws if the method is not implemented.
+     * @abstract
+     */
     static async getSearchIndexCompiled(_model) {
         throw new NotImplementedError(`${this.name} does not implement .getSearchIndexCompiled()`);
     }
 
+    /**
+     * Retrieves the raw search index for a model. This method must be implemented by subclasses.
+     *
+     * @param {Model.constructor} _model - The model to retrieve the raw search index for.
+     * @throws {NotImplementedError} Throws if the method is not implemented.
+     * @abstract
+     */
     static async getSearchIndexRaw(_model) {
         throw new NotImplementedError(`${this.name} does not implement .getSearchIndexRaw()`);
     }
 
+    /**
+     * Saves the compiled search index for a model. This method must be implemented by subclasses.
+     *
+     * @param {Model.constructor} _model - The model for which the compiled search index is saved.
+     * @param {Object} _compiledIndex - The compiled search index data.
+     * @throws {NotImplementedError} Throws if the method is not implemented.
+     * @abstract
+     */
     static async putSearchIndexCompiled(_model, _compiledIndex) {
         throw new NotImplementedError(`${this.name} does not implement .putSearchIndexCompiled()`);
     }
 
+    /**
+     * Saves the raw search index for a model. This method must be implemented by subclasses.
+     *
+     * @param {Model.constructor} _model - The model for which the raw search index is saved.
+     * @param {Object} _rawIndex - The raw search index data.
+     * @throws {NotImplementedError} Throws if the method is not implemented.
+     * @abstract
+     */
     static async putSearchIndexRaw(_model, _rawIndex) {
         throw new NotImplementedError(`${this.name} does not implement .putSearchIndexRaw()`);
     }
 
+    /**
+     * Performs a search query on a model's index and returns the matching models.
+     *
+     * @param {Model.constructor} model - The model class.
+     * @param {object} query - The search query string.
+     * @returns {Array<Model>} An array of models matching the search query.
+     * @throws {EngineError} Throws if the search index is not available for the model.
+     */
     static async search(model, query) {
         this.checkConfiguration();
 
@@ -55,6 +124,7 @@ export default class Engine {
         for (const result of results) {
             output.push({
                 ...result,
+                score: Number(result.score.toFixed(4)),
                 model: await this.get(model, result.ref),
             });
         }
@@ -62,6 +132,13 @@ export default class Engine {
         return output;
     }
 
+    /**
+     * Finds models that match a query in the model's index.
+     *
+     * @param {Model.constructor} model - The model class to search.
+     * @param {object} query - The query object containing search criteria.
+     * @returns {Array<Model>} An array of models matching the query.
+     */
     static async find(model, query) {
         this.checkConfiguration();
         const index = await this.getIndex(model);
@@ -69,50 +146,57 @@ export default class Engine {
         return new Query(query).execute(model, index);
     }
 
+    /**
+     * Stores a model and its associated index data into the system.
+     *
+     * @param {Model} model - The model to store.
+     * @throws {EngineError} Throws if the model fails to validate or index fails to save.
+     */
     static async put(model) {
         this.checkConfiguration();
         const uploadedModels = [];
         const indexUpdates = {};
 
-        const processModel = async (model) => {
-            if (uploadedModels.includes(model.id)) return false;
-            model.validate();
+        const processModel = async (m) => {
+            if (!uploadedModels.includes(m.id)) {
+                m.validate();
 
-            await this.putModel(model);
+                await this.putModel(m);
 
-            uploadedModels.push(model.id);
-            indexUpdates[model.constructor.name] = (indexUpdates[model.constructor.name] ?? []).concat([model]);
+                uploadedModels.push(m.id);
+                indexUpdates[m.constructor.name] = (indexUpdates[m.constructor.name] ?? []).concat([m]);
 
-            if (model.constructor.searchProperties().length > 0) {
-                const rawSearchIndex = {
-                    ...await this.getSearchIndexRaw(model.constructor),
-                    [model.id]: model.toSearchData(),
-                };
+                if (m.constructor.searchProperties().length > 0) {
+                    const rawSearchIndex = {
+                        ...await this.getSearchIndexRaw(m.constructor),
+                        [m.id]: m.toSearchData(),
+                    };
 
-                await this.putSearchIndexRaw(model.constructor, rawSearchIndex);
+                    await this.putSearchIndexRaw(m.constructor, rawSearchIndex);
 
-                const compiledIndex = lunr(function () {
-                    this.ref('id');
+                    const compiledIndex = lunr(function () {
+                        this.ref('id');
 
-                    for (const field of model.constructor.searchProperties()) {
-                        this.field(field);
-                    }
+                        for (const field of m.constructor.searchProperties()) {
+                            this.field(field);
+                        }
 
-                    Object.values(rawSearchIndex).forEach(function (doc) {
-                        this.add(doc);
-                    }, this);
-                });
+                        Object.values(rawSearchIndex).forEach(function (doc) {
+                            this.add(doc);
+                        }, this);
+                    });
 
-                await this.putSearchIndexCompiled(model.constructor, compiledIndex);
-            }
-
-            for (const [_, property] of Object.entries(model)) {
-                if (Type.Model.isModel(property)) {
-                    await processModel(property);
+                    await this.putSearchIndexCompiled(m.constructor, compiledIndex);
                 }
-                if (Array.isArray(property) && Type.Model.isModel(property[0])) {
-                    for (const subModel of property) {
-                        await processModel(subModel);
+
+                for (const [_, property] of Object.entries(m)) {
+                    if (Type.Model.isModel(property)) {
+                        await processModel(property);
+                    }
+                    if (Array.isArray(property) && Type.Model.isModel(property[0])) {
+                        for (const subModel of property) {
+                            await processModel(subModel);
+                        }
                     }
                 }
             }
@@ -122,6 +206,14 @@ export default class Engine {
         await this.putIndex(indexUpdates);
     }
 
+    /**
+     * Retrieves a model by its ID and converts it to its data representation.
+     *
+     * @param {Model.constructor} model - The model class to retrieve.
+     * @param {string} id - The ID of the model to retrieve.
+     * @returns {Model} The found model.
+     * @throws {NotFoundEngineError} Throws if the model is not found.
+     */
     static async get(model, id) {
         this.checkConfiguration();
 
@@ -134,6 +226,12 @@ export default class Engine {
         }
     }
 
+    /**
+     * Hydrates a model by populating its related properties (e.g., submodels) from stored data.
+     *
+     * @param {Model} model - The model to hydrate.
+     * @returns {Model} The hydrated model.
+     */
     static async hydrate(model) {
         this.checkConfiguration();
         const hydratedModels = {};
@@ -189,53 +287,122 @@ export default class Engine {
 
         function getSubModelClass(modelToProcess, name, isArray = false) {
             const constructorField = modelToProcess.constructor[name];
+
             if (constructorField instanceof Function && !constructorField.prototype) {
                 return isArray ? constructorField()._items : constructorField();
             }
+
             return isArray ? constructorField._items : constructorField;
         }
 
         return await hydrateModel(await this.get(model.constructor, model.id));
     }
 
+    /**
+     * Configures the engine with specific settings.
+     *
+     * @param {Object} configuration - The configuration settings for the engine.
+     * @returns {Engine} A new engine instance with the applied configuration.
+     */
     static configure(configuration) {
         class ConfiguredStore extends this {
-            static _configuration = configuration;
+            static configuration = configuration;
         }
 
-        Object.defineProperty(ConfiguredStore, 'name', {value: `${this.toString()}`});
+        Object.defineProperty(ConfiguredStore, 'name', { value: `${this.toString()}` });
 
         return ConfiguredStore;
     }
 
+    /**
+     * Checks if the engine is properly configured.
+     *
+     * @throws {MissConfiguredError} Throws if the engine is misconfigured.
+     * @abstract
+     */
     static checkConfiguration() {
 
     }
 
+    /**
+     * Returns the name of the engine class.
+     *
+     * @returns {string} The name of the engine class.
+     */
     static toString() {
         return this.name;
     }
-};
+}
 
+/**
+ * Represents a general error that occurs within the engine.
+ * Extends the built-in `Error` class.
+ */
 export class EngineError extends Error {
+    /**
+     * The underlying error that caused this engine error, if available.
+     * @type {Error|undefined}
+     */
     underlyingError;
+
+    /**
+     * Creates an instance of `EngineError`.
+     *
+     * @param {string} message - The error message.
+     * @param {Error} [error] - An optional underlying error that caused this error.
+     */
     constructor(message, error = undefined) {
         super(message);
         this.underlyingError = error;
     }
 }
 
+/**
+ * Represents an error that occurs when a requested resource or item is not found in the engine.
+ * Extends the `EngineError` class.
+ */
 export class NotFoundEngineError extends EngineError {
+    /**
+     * Creates an instance of `NotFoundEngineError`.
+     *
+     * @param {string} message - The error message.
+     * @param {Error} [error] - An optional underlying error that caused this error.
+     */
 }
 
+/**
+ * Represents an error indicating that a certain method or functionality is not implemented in the engine.
+ * Extends the `EngineError` class.
+ */
 export class NotImplementedError extends EngineError {
+    /**
+     * Creates an instance of `NotImplementedError`.
+     *
+     * @param {string} message - The error message.
+     * @param {Error} [error] - An optional underlying error that caused this error.
+     */
 }
 
+/**
+ * Represents an error indicating that the engine is misconfigured.
+ * Extends the `EngineError` class.
+ */
 export class MissConfiguredError extends EngineError {
+    /**
+     * The configuration that led to the misconfiguration error.
+     * @type {Object}
+     */
     configuration;
 
+    /**
+     * Creates an instance of `MissConfiguredError`.
+     *
+     * @param {Object} configuration - The configuration object that caused the misconfiguration.
+     */
     constructor(configuration) {
         super('Engine is miss-configured');
         this.configuration = configuration;
     }
 }
+
+export default Engine;