@acodeninja/persist 2.2.1 → 2.2.2

package/src/engine/S3Engine.js

@@ -1,49 +1,107 @@
 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());
@@ -52,17 +110,25 @@ export default class S3Engine extends Engine {
         }
     }
 
+    /**
+     * 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;

package/src/type/Model.js

@@ -5,10 +5,32 @@ import {monotonicFactory} from 'ulid';
 
 const createID = monotonicFactory();
 
-export default class Model {
+/**
+ * @class Model
+ */
+class Model {
+    /**
+     * Represents the model's ID field, defined as a required string.
+     *
+     * @type {StringType.required.constructor}
+     * @static
+     */
     static id = StringType.required;
+
+    /**
+     * Tracks whether the model is required in a schema.
+     *
+     * @type {boolean}
+     * @static
+     * @private
+     */
     static _required = false;
 
+    /**
+     * Creates a new instance of the model, initializing properties based on the provided data.
+     *
+     * @param {Object} [data={}] - The initial data to populate the model instance.
+     */
     constructor(data = {}) {
         this.id = `${this.constructor.name}/${createID()}`;
 
@@ -26,7 +48,13 @@ export default class Model {
         }
     }
 
-    toData() {
+    /**
+     * Serializes the model instance into an object, optionally retaining complex types.
+     *
+     * @param {boolean} [simple=true] - Determines whether to format the output using only JSON serialisable types.
+     * @returns {Object} - A serialized representation of the model.
+     */
+    toData(simple = true) {
         const model = {...this};
 
         for (const [name, property] of Object.entries(this.constructor)) {
@@ -35,23 +63,70 @@ export default class Model {
             }
         }
 
-        return JSON.parse(JSON.stringify(model, (key, value) => {
-            if (key && this.constructor.isModel(value)) {
-                return {id: value.id};
-            }
-            return value;
-        }));
+        return JSON.parse(
+            JSON.stringify(model, (key, value) => {
+                if (key && this.constructor.isModel(value)) {
+                    return {id: value.id};
+                }
+                return value;
+            }),
+            (key, value) => {
+                if (!simple) {
+                    if (this.constructor[key]) {
+                        if (this.constructor[key].name.endsWith('DateType')) {
+                            return new Date(value);
+                        }
+
+                        if (this.constructor[key].name.endsWith('ArrayOf(Date)Type')) {
+                            return value.map(d => new Date(d));
+                        }
+                    }
+                }
+
+                return value;
+            },
+        );
     }
 
+    /**
+     * Validates the current model instance against the defined schema.
+     *
+     * @returns {boolean} - Returns `true` if validation succeeds.
+     * @throws {ValidationError} - Throws this error if validation fails.
+     */
     validate() {
         return SchemaCompiler.compile(this.constructor).validate(this);
     }
 
+    /**
+     * Extracts data from the model based on the indexed properties defined in the class.
+     *
+     * @returns {Object} - A representation of the model's indexed data.
+     */
     toIndexData() {
-        const output = { id: this.id };
-        const index = this.constructor.indexedProperties();
+        return this._extractData(this.constructor.indexedProperties());
+    }
+
+    /**
+     * Extracts data from the model based on the search properties defined in the class.
+     *
+     * @returns {Object} - A representation of the model's search data.
+     */
+    toSearchData() {
+        return this._extractData(this.constructor.searchProperties());
+    }
 
-        for (const key of index) {
+    /**
+     * Extracts specific data fields from the model based on a set of keys.
+     *
+     * @param {Array<string>} keys - The keys to extract from the model.
+     * @returns {Object} - The extracted data.
+     * @private
+     */
+    _extractData(keys) {
+        const output = {id: this.id};
+
+        for (const key of keys) {
             if (_.has(this, key)) {
                 _.set(output, key, _.get(this, key));
             }
@@ -75,20 +150,22 @@ export default class Model {
         return output;
     }
 
-    toSearchData() {
-        const indexData = {id: this.id};
-
-        for (const name of this.constructor.searchProperties()) {
-            indexData[name] = this[name];
-        }
-
-        return indexData;
-    }
-
+    /**
+     * Returns the name of the model as a string.
+     *
+     * @returns {string} - The name of the model class.
+     * @static
+     */
     static toString() {
-        return this['name'];
+        return this.name;
     }
 
+    /**
+     * Returns a new required version of the current model class.
+     *
+     * @returns {this} - A required model subclass.
+     * @static
+     */
     static get required() {
         class Required extends this {
             static _required = true;
@@ -99,14 +176,35 @@ export default class Model {
         return Required;
     }
 
+    /**
+     * Returns a list of properties that are indexed.
+     *
+     * @returns {Array<string>} - The indexed properties.
+     * @abstract
+     * @static
+     */
     static indexedProperties() {
         return [];
     }
 
+    /**
+     * Returns a list of properties used for search.
+     *
+     * @returns {Array<string>} - The search properties.
+     * @abstract
+     * @static
+     */
     static searchProperties() {
         return [];
     }
 
+    /**
+     * Creates a model instance from raw data.
+     *
+     * @param {Object} data - The data to populate the model instance with.
+     * @returns {Model} - The populated model instance.
+     * @static
+     */
     static fromData(data) {
         const model = new this();
 
@@ -129,6 +227,13 @@ export default class Model {
         return model;
     }
 
+    /**
+     * Determines if a given object is a model instance.
+     *
+     * @param {Object} possibleModel - The object to check.
+     * @returns {boolean} - Returns `true` if the object is a model instance.
+     * @static
+     */
     static isModel(possibleModel) {
         return (
             possibleModel?.prototype instanceof Model ||
@@ -136,9 +241,17 @@ export default class Model {
         );
     }
 
+    /**
+     * Determines if a given object is a dry model (a simplified object with an ID).
+     *
+     * @param {Object} possibleDryModel - The object to check.
+     * @returns {boolean} - Returns `true` if the object is a valid dry model.
+     * @static
+     */
     static isDryModel(possibleDryModel) {
         try {
             return (
+                !this.isModel(possibleDryModel) &&
                 Object.keys(possibleDryModel).includes('id') &&
                 !!possibleDryModel.id.match(/[A-Za-z]+\/[A-Z0-9]+/)
             );
@@ -147,3 +260,5 @@ export default class Model {
         }
     }
 }
+
+export default Model;

package/src/type/Type.js

@@ -1,33 +1,67 @@
 /**
+ * Base class for all data types.
+ *
+ * The `Type` class is a foundational class used to define various data types.
+ * It contains common properties and methods that are inherited by more specific types like strings, numbers, and booleans.
+ *
  * @class Type
- * @property {string} _type
- * @property {boolean} _required
- * @property {boolean} _resolved
- * @property {map?} _properties
- * @property {map?} _items
- * @property {map?} _schema
  */
-export default class Type {
+class Type {
+    /**
+     * @static
+     * @property {boolean} _required - Indicates if the type is required. Default is `false`.
+     */
     static _required = false;
+
+    /**
+     * @static
+     * @property {boolean} _resolved - Indicates if the type has been resolved. Default is `false`.
+     */
     static _resolved = false;
+
+    /**
+     * @static
+     * @property {*} _properties - Properties for defining schemas. Default is `undefined`.
+     */
     static _properties = undefined;
+
+    /**
+     * @static
+     * @property {*} _items - Represents items in array types or collections. Default is `undefined`.
+     */
     static _items = undefined;
+
+    /**
+     * @static
+     * @property {*} _schema - The schema definition for the type. Default is `undefined`.
+     */
     static _schema = undefined;
 
+    /**
+     * Converts the class name to a string, removing the "Type" suffix.
+     *
+     * @returns {string} The name of the type without the "Type" suffix.
+     */
     static toString() {
         return this.name?.replace(/Type$/, '');
     }
 
     /**
-     * @return {Type}
+     * Returns a version of the type marked as required.
+     *
+     * @type {Type}
+     * @returns {Type} A subclass of the current type with `_required` set to `true`.
      */
     static get required() {
         class Required extends this {
             static _required = true;
         }
 
+        // Define the class name as "Required<OriginalTypeName>"
         Object.defineProperty(Required, 'name', {value: `Required${this.toString()}Type`});
 
         return Required;
     }
 }
+
+export default Type;

package/src/type/complex/ArrayType.js

@@ -1,19 +1,70 @@
 import Type from '../Type.js';
 
-export default class ArrayType {
+/**
+ * Represents an array type definition, allowing the specification of an array of a certain type.
+ * This class is used to create type definitions for arrays that can be validated and used in schemas.
+ *
+ * @class ArrayType
+ */
+class ArrayType {
+    /**
+     * Creates a new type definition for an array of the specified type.
+     *
+     * The `of` method defines an array where the items must be of the specified type. It returns a
+     * class representing this array type, which can further be marked as required using the `required` getter.
+     *
+     * @param {Type} type - The type of the items that the array will contain.
+     * @returns {Type} A new class representing an array of the specified type.
+     *
+     * @example
+     * const arrayOfStrings = ArrayType.of(StringType);
+     * const requiredArrayOfNumbers = ArrayType.of(NumberType).required;
+     */
     static of(type) {
+        /**
+         * @class ArrayOf
+         * @extends Type
+         * Represents an array of a specific type.
+         */
         class ArrayOf extends Type {
+            /** @type {string} The data type, which is 'array' */
             static _type = 'array';
+
+            /** @type {Type} The type of items contained in the array */
             static _items = type;
 
+            /**
+             * Returns the string representation of the array type.
+             *
+             * @returns {string} The string representation of the array type.
+             */
             static toString() {
                 return `ArrayOf(${type.toString()})`;
             }
 
+            /**
+             * Marks the array type as required.
+             *
+             * @returns {Type} A new class representing a required array of the specified type.
+             *
+             * @example
+             * const requiredArrayOfStrings = ArrayType.of(StringType).required;
+             */
             static get required() {
+                /**
+                 * @class RequiredArrayOf
+                 * @extends ArrayOf
+                 * Represents a required array of a specific type.
+                 */
                 class Required extends this {
+                    /** @type {boolean} Indicates that the array is required */
                     static _required = true;
 
+                    /**
+                     * Returns the string representation of the required array type.
+                     *
+                     * @returns {string} The string representation of the required array type.
+                     */
                     static toString() {
                         return `RequiredArrayOf(${type})`;
                     }
@@ -30,3 +81,5 @@ export default class ArrayType {
         return ArrayOf;
     }
 }
+
+export default ArrayType;