@acodeninja/persist 2.2.1 → 2.2.3

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 {
         };
     }
 
-    static async _processFetch(url, options, defaultValue = undefined) {
-        return this._configuration.fetch(url, options)
+    /**
+     * 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 _processFetch(url, options, defaultValue = undefined) {
+        return this.configuration.fetch(url, options)
             .then(response => {
                 if (!response.ok) {
                     if (defaultValue !== undefined) {
@@ -63,40 +118,64 @@ 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('/'));
+        ].filter(e => Boolean(e)).join('/'));
 
         return await this._processFetch(url, this._getReadOptions());
     }
 
-    static async putModel(model) {
+    /**
+     * 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 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('/'));
+        ].filter(e => Boolean(e)).join('/'));
 
-        return await this._processFetch(url, {
+        return this._processFetch(url, {
             ...this._getWriteOptions(),
             body: JSON.stringify(model.toData()),
         });
     }
 
+    /**
+     * 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('/'));
+            ].filter(e => Boolean(e)).join('/'));
 
             return await this._processFetch(url, {
                 ...this._getWriteOptions(),
@@ -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,13 +244,22 @@ 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('/'));
+        ].filter(e => Boolean(e)).join('/'));
 
         return this._processFetch(url, {
             ...this._getWriteOptions(),
@@ -156,13 +267,22 @@ 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('/'));
+        ].filter(e => Boolean(e)).join('/'));
 
         return await this._processFetch(url, {
             ...this._getWriteOptions(),
@@ -170,3 +290,5 @@ export default class HTTPEngine extends Engine {
         });
     }
 }
+
+export default HTTPEngine;

package/src/engine/S3Engine.js

@@ -1,68 +1,134 @@
 import Engine, {EngineError, MissConfiguredError} from './Engine.js';
 import {GetObjectCommand, PutObjectCommand} from '@aws-sdk/client-s3';
 
+/**
+ * Represents an error specific to the S3 engine operations.
+ * @class S3EngineError
+ * @extends EngineError
+ */
 class S3EngineError extends EngineError {}
 
+/**
+ * Error indicating a failure when putting an object to S3.
+ * @class FailedPutS3EngineError
+ * @extends S3EngineError
+ */
 class FailedPutS3EngineError extends S3EngineError {}
 
-export default class S3Engine extends Engine {
+/**
+ * S3Engine is an extension of the Engine class that provides methods for interacting with AWS S3.
+ * It allows for storing, retrieving, and managing model data in an S3 bucket.
+ *
+ * @class S3Engine
+ * @extends Engine
+ */
+class S3Engine extends Engine {
+    /**
+     * Configures the S3 engine with additional options.
+     *
+     * @param {Object} configuration - Configuration object.
+     * @param {S3Client} [configuration.client] - An S3 client used to process operations.
+     * @param {string} [configuration.bucket] - The S3 bucket to perform operations against.
+     * @param {string?} [configuration.prefix] - The optional prefix in the bucket to perform operations against.
+     * @returns {Object} The configured settings for the HTTP engine.
+     */
+    static configure(configuration = {}) {
+        return super.configure(configuration);
+    }
+
+    /**
+     * Validates the S3 engine configuration to ensure necessary parameters (bucket and client) are present.
+     * Throws an error if the configuration is invalid.
+     *
+     * @throws {MissConfiguredError} Thrown when the configuration is missing required parameters.
+     */
     static checkConfiguration() {
         if (
-            !this._configuration?.bucket ||
-            !this._configuration?.client
-        ) throw new MissConfiguredError(this._configuration);
+            !this.configuration?.bucket ||
+            !this.configuration?.client
+        ) throw new MissConfiguredError(this.configuration);
     }
 
+    /**
+     * Retrieves an object from S3 by its ID.
+     *
+     * @param {string} id - The ID of the object to retrieve.
+     * @returns {Promise<Object>} The parsed JSON object retrieved from S3.
+     *
+     * @throws {Error} Thrown if there is an issue with the S3 client request.
+     */
     static async getById(id) {
-        const objectPath = [this._configuration.prefix, `${id}.json`].join('/');
+        const objectPath = [this.configuration.prefix, `${id}.json`].join('/');
 
-        const data = await this._configuration.client.send(new GetObjectCommand({
-            Bucket: this._configuration.bucket,
+        const data = await this.configuration.client.send(new GetObjectCommand({
+            Bucket: this.configuration.bucket,
             Key: objectPath,
         }));
 
         return JSON.parse(await data.Body.transformToString());
     }
 
+    /**
+     * Puts (uploads) a model object to S3.
+     *
+     * @param {Model} model - The model object to upload.
+     * @returns {Promise<void>}
+     *
+     * @throws {FailedPutS3EngineError} Thrown if there is an error during the S3 PutObject operation.
+     */
     static async putModel(model) {
-        const Key = [this._configuration.prefix, `${model.id}.json`].join('/');
+        const Key = [this.configuration.prefix, `${model.id}.json`].join('/');
 
         try {
-            await this._configuration.client.send(new PutObjectCommand({
+            await this.configuration.client.send(new PutObjectCommand({
                 Key,
                 Body: JSON.stringify(model.toData()),
-                Bucket: this._configuration.bucket,
+                Bucket: this.configuration.bucket,
                 ContentType: 'application/json',
             }));
         } catch (error) {
-            throw new FailedPutS3EngineError(`Failed to put s3://${this._configuration.bucket}/${Key}`, error);
+            throw new FailedPutS3EngineError(`Failed to put s3://${this.configuration.bucket}/${Key}`, error);
         }
     }
 
-    static async getIndex(location) {
+    /**
+     * Retrieves the index object from S3 at the specified location.
+     *
+     * @param {Model.constructor?} model - The model in the bucket where the index is stored.
+     * @returns {Promise<Object>} The parsed index object.
+     */
+    static async getIndex(model) {
         try {
-            const data = await this._configuration.client.send(new GetObjectCommand({
-                Key: [this._configuration.prefix, location, '_index.json'].filter(e => !!e).join('/'),
-                Bucket: this._configuration.bucket,
+            const data = await this.configuration.client.send(new GetObjectCommand({
+                Key: [this.configuration.prefix, model?.toString(), '_index.json'].filter(e => Boolean(e)).join('/'),
+                Bucket: this.configuration.bucket,
             }));
 
             return JSON.parse(await data.Body.transformToString());
-        } catch (_) {
+        } catch (_error) {
             return {};
         }
     }
 
+    /**
+     * Puts (uploads) an index object to S3.
+     *
+     * @param {Object} index - The index data to upload, organized by location.
+     * @returns {Promise<void>}
+     *
+     * @throws {FailedPutS3EngineError} Thrown if there is an error during the S3 PutObject operation.
+     */
     static async putIndex(index) {
         const processIndex = async (location, models) => {
             const modelIndex = Object.fromEntries(models.map(m => [m.id, m.toIndexData()]));
-            const Key = [this._configuration.prefix, location, '_index.json'].filter(e => !!e).join('/');
+            const Key = [this.configuration.prefix, location, '_index.json'].filter(e => Boolean(e)).join('/');
 
             const currentIndex = await this.getIndex(location);
 
             try {
-                await this._configuration.client.send(new PutObjectCommand({
+                await this.configuration.client.send(new PutObjectCommand({
                     Key,
-                    Bucket: this._configuration.bucket,
+                    Bucket: this.configuration.bucket,
                     ContentType: 'application/json',
                     Body: JSON.stringify({
                         ...currentIndex,
@@ -70,7 +136,7 @@ export default class S3Engine extends Engine {
                     }),
                 }));
             } catch (error) {
-                throw new FailedPutS3EngineError(`Failed to put s3://${this._configuration.bucket}/${Key}`, error);
+                throw new FailedPutS3EngineError(`Failed to put s3://${this.configuration.bucket}/${Key}`, error);
             }
         };
 
@@ -81,50 +147,82 @@ export default class S3Engine extends Engine {
         await processIndex(null, Object.values(index).flat());
     }
 
+    /**
+     * Retrieves the compiled search index for a specific model from S3.
+     *
+     * @param {Model.constructor} model - The model whose search index to retrieve.
+     * @returns {Promise<Object>} The compiled search index.
+     */
     static async getSearchIndexCompiled(model) {
-        return await this._configuration.client.send(new GetObjectCommand({
-            Key: [this._configuration.prefix, model.name, '_search_index.json'].join('/'),
-            Bucket: this._configuration.bucket,
+        return await this.configuration.client.send(new GetObjectCommand({
+            Key: [this.configuration.prefix, model.name, '_search_index.json'].join('/'),
+            Bucket: this.configuration.bucket,
         })).then(data => data.Body.transformToString())
             .then(JSON.parse);
     }
 
+    /**
+     * Retrieves the raw (uncompiled) search index for a specific model from S3.
+     *
+     * @param {Model.constructor} model - The model whose raw search index to retrieve.
+     * @returns {Promise<Object>} The raw search index, or an empty object if not found.
+     */
     static async getSearchIndexRaw(model) {
-        return await this._configuration.client.send(new GetObjectCommand({
-            Key: [this._configuration.prefix, model.name, '_search_index_raw.json'].join('/'),
-            Bucket: this._configuration.bucket,
+        return await this.configuration.client.send(new GetObjectCommand({
+            Key: [this.configuration.prefix, model.toString(), '_search_index_raw.json'].join('/'),
+            Bucket: this.configuration.bucket,
         })).then(data => data.Body.transformToString())
             .then(JSON.parse)
             .catch(() => ({}));
     }
 
+    /**
+     * Puts (uploads) a compiled search index for a specific model to S3.
+     *
+     * @param {Model.constructor} model - The model whose compiled search index to upload.
+     * @param {Object} compiledIndex - The compiled search index data.
+     * @returns {Promise<void>}
+     *
+     * @throws {FailedPutS3EngineError} Thrown if there is an error during the S3 PutObject operation.
+     */
     static async putSearchIndexCompiled(model, compiledIndex) {
-        const Key = [this._configuration.prefix, model.name, '_search_index.json'].join('/');
+        const Key = [this.configuration.prefix, model.toString(), '_search_index.json'].join('/');
 
         try {
-            await this._configuration.client.send(new PutObjectCommand({
+            await this.configuration.client.send(new PutObjectCommand({
                 Key,
                 Body: JSON.stringify(compiledIndex),
-                Bucket: this._configuration.bucket,
+                Bucket: this.configuration.bucket,
                 ContentType: 'application/json',
             }));
         } catch (error) {
-            throw new FailedPutS3EngineError(`Failed to put s3://${this._configuration.bucket}/${Key}`, error);
+            throw new FailedPutS3EngineError(`Failed to put s3://${this.configuration.bucket}/${Key}`, error);
         }
     }
 
+    /**
+     * Puts (uploads) a raw search index for a specific model to S3.
+     *
+     * @param {Model.constructor} model - The model whose raw search index to upload.
+     * @param {Object} rawIndex - The raw search index data.
+     * @returns {Promise<void>}
+     *
+     * @throws {FailedPutS3EngineError} Thrown if there is an error during the S3 PutObject operation.
+     */
     static async putSearchIndexRaw(model, rawIndex) {
-        const Key = [this._configuration.prefix, model.name, '_search_index_raw.json'].join('/');
+        const Key = [this.configuration.prefix, model.toString(), '_search_index_raw.json'].join('/');
 
         try {
-            await this._configuration.client.send(new PutObjectCommand({
+            await this.configuration.client.send(new PutObjectCommand({
                 Key,
                 Body: JSON.stringify(rawIndex),
-                Bucket: this._configuration.bucket,
+                Bucket: this.configuration.bucket,
                 ContentType: 'application/json',
             }));
         } catch (error) {
-            throw new FailedPutS3EngineError(`Failed to put s3://${this._configuration.bucket}/${Key}`, error);
+            throw new FailedPutS3EngineError(`Failed to put s3://${this.configuration.bucket}/${Key}`, error);
         }
     }
 }
+
+export default S3Engine;