@acodeninja/persist 2.2.2 → 2.2.3

package/package.json

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

package/src/Query.js

@@ -50,33 +50,68 @@ class Query {
      * @returns {Array<Model>} The models that match the query.
      */
     execute(model, index) {
-        const matchIs = (query) => query?.$is !== undefined;
-        const matchPrimitive = (query) => ['string', 'number', 'boolean'].includes(typeof query);
-        const matchContains = (query) => !!query?.$contains;
+        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));
+    }
 
-        const matchesQuery = (subject, inputQuery = this.query) => {
-            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/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;
                         }
 

package/src/engine/Engine.js

@@ -16,10 +16,11 @@ class Engine {
      *
      * @param {string} _id - The ID of the model to retrieve.
      * @throws {NotImplementedError} Throws if the method is not implemented.
+     * @returns {Promise<Object>} - Returns a promise resolving to the raw data of the requested model.
      * @abstract
      */
-    static async getById(_id) {
-        throw new NotImplementedError(`${this.name} must implement .getById()`);
+    static getById(_id) {
+        return Promise.reject(new NotImplementedError(`${this.name} must implement .getById()`));
     }
 
     /**
@@ -27,10 +28,11 @@ class Engine {
      *
      * @param {Model} _data - The model data to save.
      * @throws {NotImplementedError} Throws if the method is not implemented.
+     * @returns {Promise<void>}
      * @abstract
      */
-    static async putModel(_data) {
-        throw new NotImplementedError(`${this.name} must implement .putModel()`);
+    static putModel(_data) {
+        return Promise.reject(new NotImplementedError(`${this.name} must implement .putModel()`));
     }
 
     /**
@@ -38,10 +40,11 @@ class Engine {
      *
      * @param {Model.constructor} _model - The model to retrieve the index for.
      * @throws {NotImplementedError} Throws if the method is not implemented.
+     * @returns {Promise<Object>} - Returns a promise resolving to the model index.
      * @abstract
      */
-    static async getIndex(_model) {
-        throw new NotImplementedError(`${this.name} does not implement .getIndex()`);
+    static getIndex(_model) {
+        return Promise.reject(new NotImplementedError(`${this.name} does not implement .getIndex()`));
     }
 
     /**
@@ -49,10 +52,11 @@ class Engine {
      *
      * @param {Object} _index - The index data to save.
      * @throws {NotImplementedError} Throws if the method is not implemented.
+     * @returns {Promise<void>}
      * @abstract
      */
-    static async putIndex(_index) {
-        throw new NotImplementedError(`${this.name} does not implement .putIndex()`);
+    static putIndex(_index) {
+        return Promise.reject(new NotImplementedError(`${this.name} does not implement .putIndex()`));
     }
 
     /**
@@ -60,10 +64,11 @@ class Engine {
      *
      * @param {Model.constructor} _model - The model to retrieve the compiled search index for.
      * @throws {NotImplementedError} Throws if the method is not implemented.
+     * @returns {Promise<Object>} - Returns a promise resolving to the compiled search index.
      * @abstract
      */
-    static async getSearchIndexCompiled(_model) {
-        throw new NotImplementedError(`${this.name} does not implement .getSearchIndexCompiled()`);
+    static getSearchIndexCompiled(_model) {
+        return Promise.reject(new NotImplementedError(`${this.name} does not implement .getSearchIndexCompiled()`));
     }
 
     /**
@@ -71,10 +76,11 @@ class Engine {
      *
      * @param {Model.constructor} _model - The model to retrieve the raw search index for.
      * @throws {NotImplementedError} Throws if the method is not implemented.
+     * @returns {Promise<Object>} - Returns a promise resolving to the raw search index.
      * @abstract
      */
-    static async getSearchIndexRaw(_model) {
-        throw new NotImplementedError(`${this.name} does not implement .getSearchIndexRaw()`);
+    static getSearchIndexRaw(_model) {
+        return Promise.reject(new NotImplementedError(`${this.name} does not implement .getSearchIndexRaw()`));
     }
 
     /**
@@ -83,10 +89,11 @@ class Engine {
      * @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.
+     * @returns {Promise<void>}
      * @abstract
      */
-    static async putSearchIndexCompiled(_model, _compiledIndex) {
-        throw new NotImplementedError(`${this.name} does not implement .putSearchIndexCompiled()`);
+    static putSearchIndexCompiled(_model, _compiledIndex) {
+        return Promise.reject(new NotImplementedError(`${this.name} does not implement .putSearchIndexCompiled()`));
     }
 
     /**
@@ -95,10 +102,11 @@ class Engine {
      * @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.
+     * @returns {Promise<void>}
      * @abstract
      */
-    static async putSearchIndexRaw(_model, _rawIndex) {
-        throw new NotImplementedError(`${this.name} does not implement .putSearchIndexRaw()`);
+    static putSearchIndexRaw(_model, _rawIndex) {
+        return Promise.reject(new NotImplementedError(`${this.name} does not implement .putSearchIndexRaw()`));
     }
 
     /**
@@ -321,7 +329,7 @@ class Engine {
      * @abstract
      */
     static checkConfiguration() {
-
+      // Implemented in extending Engine class
     }
 
     /**

package/src/engine/HTTPEngine.js

@@ -102,7 +102,7 @@ class HTTPEngine extends Engine {
      *
      * @throws {HTTPRequestFailedError} Thrown if the fetch request fails.
      */
-    static async _processFetch(url, options, defaultValue = undefined) {
+    static _processFetch(url, options, defaultValue = undefined) {
         return this.configuration.fetch(url, options)
             .then(response => {
                 if (!response.ok) {
@@ -133,7 +133,7 @@ class HTTPEngine extends Engine {
             this.configuration.host,
             this.configuration.prefix,
             `${id}.json`,
-        ].filter(e => !!e).join('/'));
+        ].filter(e => Boolean(e)).join('/'));
 
         return await this._processFetch(url, this._getReadOptions());
     }
@@ -146,14 +146,14 @@ class HTTPEngine extends Engine {
      *
      * @throws {HTTPRequestFailedError} Thrown if the PUT request fails.
      */
-    static async putModel(model) {
+    static putModel(model) {
         const url = new URL([
             this.configuration.host,
             this.configuration.prefix,
             `${model.id}.json`,
-        ].filter(e => !!e).join('/'));
+        ].filter(e => Boolean(e)).join('/'));
 
-        return await this._processFetch(url, {
+        return this._processFetch(url, {
             ...this._getWriteOptions(),
             body: JSON.stringify(model.toData()),
         });
@@ -175,7 +175,7 @@ class HTTPEngine extends Engine {
                 this.configuration.prefix,
                 location,
                 '_index.json',
-            ].filter(e => !!e).join('/'));
+            ].filter(e => Boolean(e)).join('/'));
 
             return await this._processFetch(url, {
                 ...this._getWriteOptions(),
@@ -259,7 +259,7 @@ class HTTPEngine extends Engine {
             this.configuration.prefix,
             model.toString(),
             '_search_index.json',
-        ].filter(e => !!e).join('/'));
+        ].filter(e => Boolean(e)).join('/'));
 
         return this._processFetch(url, {
             ...this._getWriteOptions(),
@@ -282,7 +282,7 @@ class HTTPEngine extends Engine {
             this.configuration.prefix,
             model.toString(),
             '_search_index_raw.json',
-        ].filter(e => !!e).join('/'));
+        ].filter(e => Boolean(e)).join('/'));
 
         return await this._processFetch(url, {
             ...this._getWriteOptions(),

package/src/engine/S3Engine.js

@@ -105,7 +105,7 @@ class S3Engine extends Engine {
             }));
 
             return JSON.parse(await data.Body.transformToString());
-        } catch (_) {
+        } catch (_error) {
             return {};
         }
     }

package/src/type/Model.js

@@ -253,9 +253,9 @@ class Model {
             return (
                 !this.isModel(possibleDryModel) &&
                 Object.keys(possibleDryModel).includes('id') &&
-                !!possibleDryModel.id.match(/[A-Za-z]+\/[A-Z0-9]+/)
+                new RegExp(/[A-Za-z]+\/[A-Z0-9]+/).test(possibleDryModel.id)
             );
-        } catch (_) {
+        } catch (_error) {
             return false;
         }
     }