@acodeninja/persist 2.2.1 → 2.2.3

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.1",
+  "version": "2.2.3",
   "description": "A JSON based data modelling and persistence module with alternate storage mechanisms.",
   "type": "module",
   "scripts": {

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,61 +1,117 @@
 /**
- * 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 matchPrimitive = (query) => ['string', 'number', 'boolean'].includes(typeof query);
-        const matchContains = (query) => !!query?.$contains;
-
-        const matchesQuery = (subject, inputQuery = this.query) => {
-            if (!subject || !inputQuery) return false;
+        return Object.values(index)
+            .filter(m =>
+                this._splitQuery(this.query)
+                    .map(query => Boolean(this._matchesQuery(m, query)))
+                    .every(c => c),
+            )
+            .map(m => model.fromData(m));
+    }
 
-            if (matchPrimitive(inputQuery)) return subject === inputQuery;
+    /**
+     * Recursively checks if a subject matches a given query.
+     *
+     * This function supports matching:
+     * - Primitive values directly (`string`, `number`, `boolean`)
+     * - The `$is` property for exact matches
+     * - The `$contains` property for substring or array element matches
+     *
+     * @private
+     * @param {*} subject - The subject to be matched.
+     * @param {Object} [inputQuery=this.query] - The query to match against. Defaults to `this.query` if not provided.
+     * @returns {boolean} True if the subject matches the query, otherwise false.
+     */
+    _matchesQuery(subject, inputQuery = this.query) {
+        if (['string', 'number', 'boolean'].includes(typeof inputQuery)) return subject === inputQuery;
 
-            if (matchIs(inputQuery))
-                if (subject === inputQuery.$is) return true;
+        if (inputQuery?.$is !== undefined && subject === inputQuery.$is) return true;
 
-            if (matchContains(inputQuery)) {
-                if (subject.includes?.(inputQuery.$contains)) return true;
+        if (inputQuery?.$contains !== undefined) {
+            if (subject.includes?.(inputQuery.$contains)) return true;
 
-                for (const value of subject) {
-                    if (matchesQuery(value, inputQuery.$contains)) return true;
-                }
+            for (const value of subject) {
+                if (this._matchesQuery(value, inputQuery.$contains)) return true;
             }
+        }
 
-            for (const key of Object.keys(inputQuery)) {
-                if (!['$is', '$contains'].includes(key))
-                    if (matchesQuery(subject[key], inputQuery[key])) return true;
-            }
-        };
+        for (const key of Object.keys(inputQuery)) {
+            if (!['$is', '$contains'].includes(key))
+                if (this._matchesQuery(subject[key], inputQuery[key])) return true;
+        }
 
-        return Object.values(index)
-            .filter(m => matchesQuery(m))
-            .map(m => model.fromData(m));
+        return false;
+    };
+
+    /**
+     * Recursively splits an object into an array of objects,
+     * where each key-value pair from the input query becomes a separate object.
+     *
+     * If the value of a key is a nested object (and not an array),
+     * the function recursively splits it, preserving the parent key.
+     *
+     * @private
+     * @param {Object} query - The input object to be split into individual key-value pairs.
+     * @returns {Array<Object>} An array of objects, where each object contains a single key-value pair
+     *                         from the original query or its nested objects.
+     */
+    _splitQuery(query) {
+        return Object.entries(query)
+            .flatMap(([key, value]) =>
+                typeof value === 'object' && value !== null && !Array.isArray(value)
+                    ? this._splitQuery(value).map(nestedObj => ({[key]: nestedObj}))
+                    : {[key]: value},
+            );
     }
 }
 

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/Transactions.js

@@ -1,32 +1,110 @@
+/**
+ * Class representing a transaction-related error.
+ *
+ * @class TransactionError
+ * @extends Error
+ */
 class TransactionError extends Error {
 }
 
+/**
+ * Error thrown when a transaction is already committed.
+ *
+ * @class TransactionCommittedError
+ * @extends TransactionError
+ */
 export class TransactionCommittedError extends TransactionError {
+    /**
+     * Creates an instance of TransactionCommittedError.
+     * This error is thrown when attempting to commit an already committed transaction.
+     * @property {string} message - The error message.
+     */
     message = 'Transaction was already committed.';
 }
 
+/**
+ * Enables transaction support for the provided engine.
+ *
+ * This function enhances an engine class with transaction capabilities, allowing multiple
+ * changes to be grouped into a single transaction that can be committed or rolled back.
+ *
+ * @param {Engine.constructor} engine - The base engine class to be enhanced with transaction support.
+ * @returns {TransactionalEngine.constructor} TransactionalEngine - The enhanced engine class with transaction functionality.
+ */
 export default function enableTransactions(engine) {
+    /**
+     * A class representing an engine with transaction capabilities.
+     * @class TransactionalEngine
+     * @extends {engine}
+     */
     class TransactionalEngine extends engine {
     }
 
+    /**
+     * Starts a transaction on the engine. Returns a Transaction class that can handle
+     * put, commit, and rollback actions for the transaction.
+     *
+     * @returns {Transaction.constructor} Transaction - A class that manages the transaction's operations.
+     */
     TransactionalEngine.start = () => {
+        /**
+         * A class representing an active transaction on the engine.
+         * Contains methods to put changes, commit the transaction, or roll back in case of failure.
+         *
+         * @class Transaction
+         */
         class Transaction extends TransactionalEngine {
+            /**
+             * @property {Array<Object>} transactions - An array storing all the operations within the transaction.
+             * @static
+             */
             static transactions = [];
+
+            /**
+             * @property {boolean} committed - Indicates if the transaction has been committed.
+             * @static
+             */
             static committed = false;
+
+            /**
+             * @property {boolean} failed - Indicates if the transaction has failed.
+             * @static
+             */
             static failed = false;
 
-            static async put(model) {
+            /**
+             * Adds a model to the transaction queue.
+             *
+             * @param {Object} model - The model to be added to the transaction.
+             * @returns {Promise<void>} A promise that resolves once the model is added.
+             */
+            static put(model) {
                 this.transactions.push({
                     hasRun: false,
                     hasRolledBack: false,
                     model,
                 });
+
+                return Promise.resolve();
             }
 
+            /**
+             * Checks if the transaction has already been committed. If true, throws a TransactionCommittedError.
+             *
+             * @throws {TransactionCommittedError} If the transaction has already been committed.
+             * @private
+             */
             static _checkCommitted() {
                 if (this.committed) throw new TransactionCommittedError();
             }
 
+            /**
+             * Commits the transaction, applying all the changes to the engine.
+             * Rolls back if any part of the transaction fails.
+             *
+             * @returns {Promise<void>} A promise that resolves once the transaction is committed, or rejects if an error occurs.
+             * @throws {Error} If any operation in the transaction fails.
+             */
             static async commit() {
                 this._checkCommitted();
 
@@ -34,7 +112,7 @@ export default function enableTransactions(engine) {
                     for (const [index, {model}] of this.transactions.entries()) {
                         try {
                             this.transactions[index].original = await engine.get(model.constructor, model.id);
-                        } catch (_) {
+                        } catch (_error) {
                             this.transactions[index].original = null;
                         }