@acodeninja/persist 2.2.0 → 2.2.2

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;

package/src/engine/HTTPEngine.js

@@ -1,8 +1,21 @@
 import Engine, {EngineError, MissConfiguredError} from './Engine.js';
 
-export class HTTPEngineError extends EngineError {
-}
+/**
+ * Represents an error specific to HTTP engine operations.
+ * @class HTTPEngineError
+ * @extends EngineError
+ */
+export class HTTPEngineError extends EngineError {}
 
+/**
+ * Error indicating a failed HTTP request.
+ * @class HTTPRequestFailedError
+ * @extends HTTPEngineError
+ *
+ * @param {string} url - The URL of the failed request.
+ * @param {Object} options - The options used in the fetch request.
+ * @param {Response} response - The HTTP response object.
+ */
 export class HTTPRequestFailedError extends HTTPEngineError {
     constructor(url, options, response) {
         const method = options.method?.toLowerCase() || 'get';
@@ -13,7 +26,25 @@ export class HTTPRequestFailedError extends HTTPEngineError {
     }
 }
 
-export default class HTTPEngine extends Engine {
+/**
+ * HTTPEngine is an extension of the Engine class that provides methods for interacting with HTTP-based APIs.
+ * It uses the Fetch API for sending and receiving data.
+ *
+ * @class HTTPEngine
+ * @extends Engine
+ */
+class HTTPEngine extends Engine {
+
+    /**
+     * Configures the HTTP engine with additional fetch options.
+     * Sets the Accept header to 'application/json' by default.
+     *
+     * @param {Object} configuration - Configuration object containing fetch options and other settings.
+     * @param {string} [configuration.host] - Hostname and protocol of the HTTP service to use (ie: https://example.com).
+     * @param {string?} [configuration.prefix] - The prefix on the host to perform operations against.
+     * @param {Object} [configuration.fetchOptions] - Fetch overrides to attach to all requests sent to the HTTP service.
+     * @returns {Object} The configured settings for the HTTP engine.
+     */
     static configure(configuration = {}) {
         configuration.fetchOptions = {
             ...(configuration.fetchOptions ?? {}),
@@ -26,16 +57,30 @@ export default class HTTPEngine extends Engine {
         return super.configure(configuration);
     }
 
+    /**
+     * Validates the engine's configuration, ensuring that the host is defined.
+     *
+     * @throws {MissConfiguredError} Thrown if the configuration is missing a host.
+     */
     static checkConfiguration() {
-        if (
-            !this._configuration?.host
-        ) throw new MissConfiguredError(this._configuration);
+        if (!this.configuration?.host) throw new MissConfiguredError(this.configuration);
     }
 
+    /**
+     * Returns the fetch options for reading operations.
+     *
+     * @returns {Object} The fetch options for reading.
+     */
     static _getReadOptions() {
-        return this._configuration.fetchOptions;
+        return this.configuration.fetchOptions;
     }
 
+    /**
+     * Returns the fetch options for writing (PUT) operations.
+     * Sets the method to PUT and adds a Content-Type header of 'application/json'.
+     *
+     * @returns {Object} The fetch options for writing.
+     */
     static _getWriteOptions() {
         return {
             ...this._getReadOptions(),
@@ -47,8 +92,18 @@ export default class HTTPEngine extends Engine {
         };
     }
 
+    /**
+     * Processes a fetch request with error handling. Throws an error if the response is not successful.
+     *
+     * @param {string|URL} url - The URL to fetch.
+     * @param {Object} options - The fetch options.
+     * @param {*} [defaultValue] - A default value to return if the fetch fails.
+     * @returns {Promise<Object>} The parsed JSON response.
+     *
+     * @throws {HTTPRequestFailedError} Thrown if the fetch request fails.
+     */
     static async _processFetch(url, options, defaultValue = undefined) {
-        return this._configuration.fetch(url, options)
+        return this.configuration.fetch(url, options)
             .then(response => {
                 if (!response.ok) {
                     if (defaultValue !== undefined) {
@@ -63,22 +118,38 @@ export default class HTTPEngine extends Engine {
             .then(r => r.json());
     }
 
+    /**
+     * Retrieves an object by its ID from the server.
+     *
+     * @param {string} id - The ID of the object to retrieve.
+     * @returns {Promise<Object>} The retrieved object in JSON format.
+     *
+     * @throws {HTTPRequestFailedError} Thrown if the fetch request fails.
+     */
     static async getById(id) {
         this.checkConfiguration();
 
         const url = new URL([
-            this._configuration.host,
-            this._configuration.prefix,
+            this.configuration.host,
+            this.configuration.prefix,
             `${id}.json`,
         ].filter(e => !!e).join('/'));
 
         return await this._processFetch(url, this._getReadOptions());
     }
 
+    /**
+     * Uploads (puts) a model object to the server.
+     *
+     * @param {Model} model - The model object to upload.
+     * @returns {Promise<Object>} The response from the server.
+     *
+     * @throws {HTTPRequestFailedError} Thrown if the PUT request fails.
+     */
     static async putModel(model) {
         const url = new URL([
-            this._configuration.host,
-            this._configuration.prefix,
+            this.configuration.host,
+            this.configuration.prefix,
             `${model.id}.json`,
         ].filter(e => !!e).join('/'));
 
@@ -88,12 +159,20 @@ export default class HTTPEngine extends Engine {
         });
     }
 
+    /**
+     * Uploads (puts) an index object to the server.
+     *
+     * @param {Object} index - The index data to upload, organized by location.
+     * @returns {Promise<void>}
+     *
+     * @throws {HTTPRequestFailedError} Thrown if the PUT request fails.
+     */
     static async putIndex(index) {
         const processIndex = async (location, models) => {
             const modelIndex = Object.fromEntries(models.map(m => [m.id, m.toIndexData()]));
             const url = new URL([
-                this._configuration.host,
-                this._configuration.prefix,
+                this.configuration.host,
+                this.configuration.prefix,
                 location,
                 '_index.json',
             ].filter(e => !!e).join('/'));
@@ -114,16 +193,33 @@ export default class HTTPEngine extends Engine {
         await processIndex(null, Object.values(index).flat());
     }
 
-    static async getIndex(location) {
-        const url = new URL([this._configuration.host, this._configuration.prefix, location, '_index.json'].filter(e => !!e).join('/'));
+    /**
+     * Retrieves the index object from the server for the specified location.
+     *
+     * @param {Model.constructor?} model - The model in the host where the index is stored.
+     * @returns {Promise<Object>} The index data in JSON format.
+     */
+    static async getIndex(model) {
+        const url = new URL([
+            this.configuration.host,
+            this.configuration.prefix,
+            model?.toString(),
+            '_index.json',
+        ].filter(e => Boolean(e)).join('/'));
 
         return await this._processFetch(url, this._getReadOptions(), {});
     }
 
+    /**
+     * Retrieves the compiled search index for a model from the server.
+     *
+     * @param {Model.constructor} model - The model whose compiled search index to retrieve.
+     * @returns {Promise<Object>} The compiled search index in JSON format.
+     */
     static async getSearchIndexCompiled(model) {
         const url = new URL([
-            this._configuration.host,
-            this._configuration.prefix,
+            this.configuration.host,
+            this.configuration.prefix,
             model.toString(),
             '_search_index.json',
         ].join('/'));
@@ -131,10 +227,16 @@ export default class HTTPEngine extends Engine {
         return await this._processFetch(url, this._getReadOptions());
     }
 
+    /**
+     * Retrieves the raw (uncompiled) search index for a model from the server.
+     *
+     * @param {Model.constructor} model - The model whose raw search index to retrieve.
+     * @returns {Promise<Object>} The raw search index in JSON format, or an empty object if not found.
+     */
     static async getSearchIndexRaw(model) {
         const url = new URL([
-            this._configuration.host,
-            this._configuration.prefix,
+            this.configuration.host,
+            this.configuration.prefix,
             model.toString(),
             '_search_index_raw.json',
         ].join('/'));
@@ -142,11 +244,20 @@ export default class HTTPEngine extends Engine {
         return await this._processFetch(url, this._getReadOptions()).catch(() => ({}));
     }
 
+    /**
+     * Uploads (puts) a compiled search index for a model to the server.
+     *
+     * @param {Model.constructor} model - The model whose compiled search index to upload.
+     * @param {Object} compiledIndex - The compiled search index data.
+     * @returns {Promise<Object>} The response from the server.
+     *
+     * @throws {HTTPRequestFailedError} Thrown if the PUT request fails.
+     */
     static async putSearchIndexCompiled(model, compiledIndex) {
         const url = new URL([
-            this._configuration.host,
-            this._configuration.prefix,
-            model.name,
+            this.configuration.host,
+            this.configuration.prefix,
+            model.toString(),
             '_search_index.json',
         ].filter(e => !!e).join('/'));
 
@@ -156,11 +267,20 @@ export default class HTTPEngine extends Engine {
         });
     }
 
+    /**
+     * Uploads (puts) a raw search index for a model to the server.
+     *
+     * @param {Model.constructor} model - The model whose raw search index to upload.
+     * @param {Object} rawIndex - The raw search index data.
+     * @returns {Promise<Object>} The response from the server.
+     *
+     * @throws {HTTPRequestFailedError} Thrown if the PUT request fails.
+     */
     static async putSearchIndexRaw(model, rawIndex) {
         const url = new URL([
-            this._configuration.host,
-            this._configuration.prefix,
-            model.name,
+            this.configuration.host,
+            this.configuration.prefix,
+            model.toString(),
             '_search_index_raw.json',
         ].filter(e => !!e).join('/'));
 
@@ -170,3 +290,5 @@ export default class HTTPEngine extends Engine {
         });
     }
 }
+
+export default HTTPEngine;