@acodeninja/persist 2.2.1 → 2.2.3

package/src/engine/Engine.js

@@ -3,43 +3,120 @@ 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;
-
-    static async getById(_id) {
-        throw new NotImplementedError(`${this.name} must implement .getById()`);
+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.
+     * @returns {Promise<Object>} - Returns a promise resolving to the raw data of the requested model.
+     * @abstract
+     */
+    static getById(_id) {
+        return Promise.reject(new NotImplementedError(`${this.name} must implement .getById()`));
     }
 
-    static async putModel(_data) {
-        throw new NotImplementedError(`${this.name} must implement .putModel()`);
+    /**
+     * 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.
+     * @returns {Promise<void>}
+     * @abstract
+     */
+    static putModel(_data) {
+        return Promise.reject(new NotImplementedError(`${this.name} must implement .putModel()`));
     }
 
-    static async getIndex(_model) {
-        throw new NotImplementedError(`${this.name} does not implement .getIndex()`);
+    /**
+     * 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.
+     * @returns {Promise<Object>} - Returns a promise resolving to the model index.
+     * @abstract
+     */
+    static getIndex(_model) {
+        return Promise.reject(new NotImplementedError(`${this.name} does not implement .getIndex()`));
     }
 
-    static async putIndex(_index) {
-        throw new NotImplementedError(`${this.name} does not implement .putIndex()`);
+    /**
+     * 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.
+     * @returns {Promise<void>}
+     * @abstract
+     */
+    static putIndex(_index) {
+        return Promise.reject(new NotImplementedError(`${this.name} does not implement .putIndex()`));
     }
 
-    static async getSearchIndexCompiled(_model) {
-        throw new NotImplementedError(`${this.name} does not implement .getSearchIndexCompiled()`);
+    /**
+     * 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.
+     * @returns {Promise<Object>} - Returns a promise resolving to the compiled search index.
+     * @abstract
+     */
+    static getSearchIndexCompiled(_model) {
+        return Promise.reject(new NotImplementedError(`${this.name} does not implement .getSearchIndexCompiled()`));
     }
 
-    static async getSearchIndexRaw(_model) {
-        throw new NotImplementedError(`${this.name} does not implement .getSearchIndexRaw()`);
+    /**
+     * 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.
+     * @returns {Promise<Object>} - Returns a promise resolving to the raw search index.
+     * @abstract
+     */
+    static getSearchIndexRaw(_model) {
+        return Promise.reject(new NotImplementedError(`${this.name} does not implement .getSearchIndexRaw()`));
     }
 
-    static async putSearchIndexCompiled(_model, _compiledIndex) {
-        throw new NotImplementedError(`${this.name} does not implement .putSearchIndexCompiled()`);
+    /**
+     * 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.
+     * @returns {Promise<void>}
+     * @abstract
+     */
+    static putSearchIndexCompiled(_model, _compiledIndex) {
+        return Promise.reject(new NotImplementedError(`${this.name} does not implement .putSearchIndexCompiled()`));
     }
 
-    static async putSearchIndexRaw(_model, _rawIndex) {
-        throw new NotImplementedError(`${this.name} does not implement .putSearchIndexRaw()`);
+    /**
+     * 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.
+     * @returns {Promise<void>}
+     * @abstract
+     */
+    static putSearchIndexRaw(_model, _rawIndex) {
+        return Promise.reject(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 +132,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 +140,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 +154,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 +214,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 +234,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 +295,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() {
-
+      // Implemented in extending Engine class
     }
 
+    /**
+     * 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;

package/src/engine/FileEngine.js

@@ -1,16 +1,36 @@
-import Engine, {EngineError, MissConfiguredError} from './Engine.js';
-import {dirname, join} from 'node:path';
+import Engine, { EngineError, MissConfiguredError } from './Engine.js';
+import { dirname, join } from 'node:path';
 import fs from 'node:fs/promises';
 
+/**
+ * Custom error class for FileEngine-related errors.
+ * Extends the base `EngineError` class.
+ */
 class FileEngineError extends EngineError {}
 
+/**
+ * Error thrown when writing to a file fails in `FileEngine`.
+ * Extends the `FileEngineError` class.
+ */
 class FailedWriteFileEngineError extends FileEngineError {}
 
 /**
+ * `FileEngine` class extends the base `Engine` class to implement
+ * file system-based storage and retrieval of model data.
+ *
  * @class FileEngine
  * @extends Engine
  */
-export default class FileEngine extends Engine {
+class FileEngine extends Engine {
+    /**
+     * Configures the FileEngine with a given configuration object.
+     * Adds default `filesystem` configuration if not provided.
+     *
+     * @param {Object} configuration - Configuration settings for FileEngine.
+     * @param {Object} [configuration.filesystem] - Custom filesystem module (default: Node.js fs/promises).
+     * @param {Object} [configuration.path] - The absolute path on the filesystem to write models to.
+     * @returns {FileEngine} A configured instance of FileEngine.
+     */
     static configure(configuration) {
         if (!configuration.filesystem) {
             configuration.filesystem = fs;
@@ -18,42 +38,77 @@ export default class FileEngine extends Engine {
         return super.configure(configuration);
     }
 
+    /**
+     * Checks if the FileEngine has been configured correctly.
+     * Ensures that `path` and `filesystem` settings are present.
+     *
+     * @throws {MissConfiguredError} Throws if required configuration is missing.
+     */
     static checkConfiguration() {
-        if (
-            !this._configuration?.path ||
-            !this._configuration?.filesystem
-        ) throw new MissConfiguredError(this._configuration);
+        if (!this.configuration?.path || !this.configuration?.filesystem) {
+            throw new MissConfiguredError(this.configuration);
+        }
     }
 
-    static async getById(id) {
-        const filePath = join(this._configuration.path, `${id}.json`);
-
-        return JSON.parse(await this._configuration.filesystem.readFile(filePath).then(f => f.toString()));
+    /**
+     * Retrieves a model by its ID from the file system.
+     *
+     * @param {string} id - The ID of the model to retrieve.
+     * @returns {Promise<Object>} The parsed model data.
+     * @throws {Error} Throws if the file cannot be read or parsed.
+     */
+    static getById(id) {
+        return this.configuration.filesystem
+            .readFile(join(this.configuration.path, `${id}.json`))
+            .then((b) => b.toString())
+            .then(JSON.parse);
     }
 
-    static async getIndex(model) {
-        return JSON.parse((await this._configuration.filesystem.readFile(join(this._configuration.path, model.name, '_index.json')).catch(() => '{}')).toString());
+    /**
+     * Retrieves the index for a given model from the file system.
+     *
+     * @param {Model.constructor?} model - The model for which the index is retrieved.
+     * @returns {Promise<Object>} The parsed index data.
+     * @throws {Error} Throws if the file cannot be read.
+     */
+    static getIndex(model) {
+        return this.configuration.filesystem
+            .readFile(join(this.configuration.path, model.toString(), '_index.json'))
+            .then((b) => b.toString())
+            .catch(() => '{}')
+            .then(JSON.parse);
     }
 
+    /**
+     * Saves a model to the file system.
+     *
+     * @param {Model} model - The model to save.
+     * @throws {FailedWriteFileEngineError} Throws if the model cannot be written to the file system.
+     */
     static async putModel(model) {
-        const filePath = join(this._configuration.path, `${model.id}.json`);
-
+        const filePath = join(this.configuration.path, `${model.id}.json`);
         try {
-            await this._configuration.filesystem.mkdir(dirname(filePath), {recursive: true});
-            await this._configuration.filesystem.writeFile(filePath, JSON.stringify(model.toData()));
+            await this.configuration.filesystem.mkdir(dirname(filePath), { recursive: true });
+            await this.configuration.filesystem.writeFile(filePath, JSON.stringify(model.toData()));
         } catch (error) {
             throw new FailedWriteFileEngineError(`Failed to put file://${filePath}`, error);
         }
     }
 
+    /**
+     * Saves the index for multiple models to the file system.
+     *
+     * @param {Object} index - An object where keys are locations and values are arrays of models.
+     * @throws {FailedWriteFileEngineError} Throws if the index cannot be written to the file system.
+     */
     static async putIndex(index) {
         const processIndex = async (location, models) => {
-            const modelIndex = Object.fromEntries(models.map(m => [m.id, m.toIndexData()]));
-            const filePath = join(this._configuration.path, location, '_index.json');
-            const currentIndex = JSON.parse((await this._configuration.filesystem.readFile(filePath).catch(() => '{}')).toString());
+            const modelIndex = Object.fromEntries(models.map((m) => [m.id, m.toIndexData()]));
+            const filePath = join(this.configuration.path, location, '_index.json');
+            const currentIndex = JSON.parse((await this.configuration.filesystem.readFile(filePath).catch(() => '{}')).toString());
 
             try {
-                await this._configuration.filesystem.writeFile(filePath, JSON.stringify({
+                await this.configuration.filesystem.writeFile(filePath, JSON.stringify({
                     ...currentIndex,
                     ...modelIndex,
                 }));
@@ -69,35 +124,66 @@ export default class FileEngine extends Engine {
         await processIndex('', Object.values(index).flat());
     }
 
-    static async getSearchIndexCompiled(model) {
-        return await this._configuration.filesystem.readFile(join(this._configuration.path, model.name, '_search_index.json'))
-            .then(b => b.toString())
+    /**
+     * Retrieves the compiled search index for a model from the file system.
+     *
+     * @param {Model.constructor} model - The model for which the search index is retrieved.
+     * @returns {Promise<Object>} The parsed compiled search index.
+     * @throws {Error} Throws if the file cannot be read.
+     */
+    static getSearchIndexCompiled(model) {
+        return this.configuration.filesystem
+            .readFile(join(this.configuration.path, model.toString(), '_search_index.json'))
+            .then((b) => b.toString())
             .then(JSON.parse);
     }
 
-    static async getSearchIndexRaw(model) {
-        return await this._configuration.filesystem.readFile(join(this._configuration.path, model.name, '_search_index_raw.json'))
-            .then(b => b.toString())
+    /**
+     * Retrieves the raw search index for a model from the file system.
+     *
+     * @param {Model.constructor} model - The model for which the raw search index is retrieved.
+     * @returns {Promise<Object>} The parsed raw search index.
+     * @throws {Error} Throws if the file cannot be read.
+     */
+    static getSearchIndexRaw(model) {
+        return this.configuration.filesystem
+            .readFile(join(this.configuration.path, model.toString(), '_search_index_raw.json'))
+            .then((b) => b.toString())
             .then(JSON.parse)
             .catch(() => ({}));
     }
 
+    /**
+     * Saves the compiled search index for a model to the file system.
+     *
+     * @param {Model.constructor} model - The model for which the compiled search index is saved.
+     * @param {Object} compiledIndex - The compiled search index to save.
+     * @throws {FailedWriteFileEngineError} Throws if the compiled index cannot be written to the file system.
+     */
     static async putSearchIndexCompiled(model, compiledIndex) {
-        const filePath = join(this._configuration.path, model.name, '_search_index.json');
-
+        const filePath = join(this.configuration.path, model.toString(), '_search_index.json');
         try {
-            await this._configuration.filesystem.writeFile(filePath, JSON.stringify(compiledIndex));
+            await this.configuration.filesystem.writeFile(filePath, JSON.stringify(compiledIndex));
         } catch (error) {
             throw new FailedWriteFileEngineError(`Failed to put file://${filePath}`, error);
         }
     }
 
+    /**
+     * Saves the raw search index for a model to the file system.
+     *
+     * @param {Model.constructor} model - The model for which the raw search index is saved.
+     * @param {Object} rawIndex - The raw search index to save.
+     * @throws {FailedWriteFileEngineError} Throws if the raw index cannot be written to the file system.
+     */
     static async putSearchIndexRaw(model, rawIndex) {
-        const filePath = join(this._configuration.path, model.name, '_search_index_raw.json');
+        const filePath = join(this.configuration.path, model.toString(), '_search_index_raw.json');
         try {
-            await this._configuration.filesystem.writeFile(filePath, JSON.stringify(rawIndex));
+            await this.configuration.filesystem.writeFile(filePath, JSON.stringify(rawIndex));
         } catch (error) {
             throw new FailedWriteFileEngineError(`Failed to put file://${filePath}`, error);
         }
     }
 }
+
+export default FileEngine;