@acodeninja/persist 2.2.1 → 2.2.3

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,14 +241,24 @@ 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]+/)
+                new RegExp(/[A-Za-z]+\/[A-Z0-9]+/).test(possibleDryModel.id)
             );
-        } catch (_) {
+        } catch (_error) {
             return false;
         }
     }
 }
+
+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;

package/src/type/complex/CustomType.js

@@ -1,15 +1,49 @@
 import Type from '../Type.js';
 import ajv from 'ajv';
 
-export default class CustomType {
+/**
+ * Represents a custom type definition, allowing the specification of a type based on a given schema.
+ * This class uses AJV (Another JSON Schema Validator) to validate schemas and create type definitions.
+ *
+ * @class CustomType
+ */
+class CustomType {
+    /**
+     * Creates a new custom type definition based on the provided JSON schema.
+     *
+     * The `of` method allows defining a custom object type using a JSON schema. It validates the schema
+     * using AJV to ensure correctness and returns a class representing the custom type.
+     *
+     * @param {Object} schema - The JSON schema that defines the structure and validation rules for the custom type.
+     * @returns {Type} A new class representing the custom type based on the provided schema.
+     *
+     * @example
+     * const customSchema = {
+     *   type: 'object',
+     *   properties: { name: { type: 'string' }, age: { type: 'number' } },
+     *   required: ['name'],
+     * };
+     * const CustomModel = CustomType.of(customSchema);
+     */
     static of(schema) {
+        // Compiles and validates the schema using AJV
         new ajv().compile(schema);
 
+        /**
+         * @class Custom
+         * @extends Type
+         * Represents a custom type defined by a JSON schema.
+         */
         class Custom extends Type {
+            /** @type {string} The data type, which is 'object' */
             static _type = 'object';
+
+            /** @type {Object} The JSON schema that defines the structure and validation rules */
             static _schema = schema;
         }
 
         return Custom;
     }
 }
+
+export default CustomType;

package/src/type/resolved/ResolvedType.js

@@ -1,14 +1,50 @@
 import Type from '../Type.js';
 
-export default class ResolvedType extends Type {
+/**
+ * Class representing a resolved type.
+ *
+ * The `ResolvedType` class extends the base `Type` class and marks the type as resolved.
+ * It provides additional functionality for resolving types and allows creating resolved types based on properties.
+ *
+ * @class ResolvedType
+ * @extends Type
+ */
+class ResolvedType extends Type {
+    /**
+     * @static
+     * @property {boolean} _resolved - Indicates if the type is resolved. Always set to `true` for this class.
+     */
     static _resolved = true;
 
+    /**
+     * Resolves the type based on the provided model.
+     *
+     * This method should be overridden in subclasses to provide specific resolution logic.
+     * Throws an error if not implemented.
+     *
+     * @param {*} _model - The model used to resolve the type.
+     * @throws {Error} If the method is not implemented in a subclass.
+     */
     static resolve(_model) {
         throw new Error(`${this.name} does not implement resolve(model)`);
     }
 
+    /**
+     * Creates a subclass of `ResolvedType` that is based on the provided property.
+     *
+     * The returned class inherits from `ResolvedType` and customizes its `toString` method
+     * to reflect the resolved property.
+     *
+     * @param {*} property - The property to base the resolved type on.
+     * @returns {ResolvedType} A subclass of `ResolvedType` customized for the provided property.
+     */
     static of(property) {
         class ResolvedTypeOf extends ResolvedType {
+            /**
+             * Converts the resolved type to a string, displaying the resolved property.
+             *
+             * @returns {string} A string representing the resolved type, including the property.
+             */
             static toString() {
                 return `ResolvedTypeOf(${property})`;
             }
@@ -17,3 +53,5 @@ export default class ResolvedType extends Type {
         return ResolvedTypeOf;
     }
 }
+
+export default ResolvedType;

package/src/type/resolved/SlugType.js

@@ -1,15 +1,53 @@
 import ResolvedType from './ResolvedType.js';
 import slugify from 'slugify';
 
-export default class SlugType extends ResolvedType {
+/**
+ * Class representing a slug type.
+ *
+ * The `SlugType` class extends the `ResolvedType` and provides functionality for generating
+ * slugified strings based on a specified property of a model. It allows for the creation of
+ * types that resolve into slugs from specific properties.
+ *
+ * @class SlugType
+ * @extends ResolvedType
+ */
+class SlugType extends ResolvedType {
+    /**
+     * Creates a subclass of `ResolvedType` that generates slugs based on the provided property.
+     *
+     * The returned class inherits from `ResolvedType` and resolves the property into a slugified
+     * string using the `slugify` function. It also customizes the `toString` method to reflect
+     * the resolved property.
+     *
+     * @param {string} property - The property to base the slug on.
+     * @returns {ResolvedType} A subclass of `ResolvedType` that generates slugs from the provided property.
+     */
     static of(property) {
         class SlugOf extends ResolvedType {
+            /**
+             * @static
+             * @property {string} _type - The type of the resolved value, always set to 'string' for slug types.
+             */
             static _type = 'string';
 
+            /**
+             * Converts the slug type to a string, displaying the resolved property.
+             *
+             * @returns {string} A string representing the slug type, including the property.
+             */
             static toString() {
                 return `SlugOf(${property})`;
             }
 
+            /**
+             * Resolves the slug from the given model by extracting the specified property and slugifying it.
+             *
+             * If the specified property in the model is not a string, an empty string is returned.
+             * Uses the `slugify` function to convert the property value into a slug (lowercase, hyphen-separated).
+             *
+             * @param {Object} model - The model from which to extract and slugify the property.
+             * @returns {string} The slugified version of the model's property, or an empty string if not valid.
+             */
             static resolve(model) {
                 if (typeof model?.[property] !== 'string') return '';
 
@@ -22,3 +60,5 @@ export default class SlugType extends ResolvedType {
         return SlugOf;
     }
 }
+
+export default SlugType;

package/src/type/simple/BooleanType.js

@@ -1,5 +1,20 @@
 import SimpleType from './SimpleType.js';
 
-export default class BooleanType extends SimpleType {
+/**
+ * Class representing a boolean type.
+ *
+ * This class is used to define and handle data of the boolean type.
+ * It extends the {@link SimpleType} class to represent string-specific behavior.
+ *
+ * @class BooleanType
+ * @extends SimpleType
+ */
+class BooleanType extends SimpleType {
+    /**
+     * @static
+     * @property {string} _type - The type identifier for BooleanType, set to `'boolean'`.
+     */
     static _type = 'boolean';
 }
+
+export default BooleanType;

package/src/type/simple/DateType.js

@@ -1,10 +1,37 @@
 import SimpleType from './SimpleType.js';
 
-export default class DateType extends SimpleType {
+/**
+ * Class representing a date type with ISO date-time format.
+ *
+ * This class is used to define and handle data of the date type.
+ * It extends the {@link SimpleType} class to represent string-specific behavior.
+ *
+ * @class DateType
+ * @extends SimpleType
+ */
+class DateType extends SimpleType {
+    /**
+     * @static
+     * @property {string} _type - The type identifier for DateType, set to `'string'`.
+     */
     static _type = 'string';
+
+    /**
+     * @static
+     * @property {string} _format - The format for DateType, set to `'iso-date-time'`.
+     */
     static _format = 'iso-date-time';
 
+    /**
+     * Checks if the given value is a valid date.
+     *
+     * @static
+     * @param {*} possibleDate - The value to check for a valid date.
+     * @returns {boolean} Returns `true` if the value is a valid date or a date string, otherwise `false`.
+     */
     static isDate(possibleDate) {
         return possibleDate instanceof Date || !isNaN(new Date(possibleDate));
     }
 }
+
+export default DateType;

package/src/type/simple/NumberType.js

@@ -1,5 +1,20 @@
 import SimpleType from './SimpleType.js';
 
-export default class NumberType extends SimpleType {
+/**
+ * Class representing a number type.
+ *
+ * This class is used to define and handle data of the number type.
+ * It extends the {@link SimpleType} class to represent string-specific behavior.
+ *
+ * @class NumberType
+ * @extends SimpleType
+ */
+class NumberType extends SimpleType {
+    /**
+     * @static
+     * @property {string} _type - The type identifier for NumberType, set to `'number'`.
+     */
     static _type = 'number';
 }
+
+export default NumberType;

package/src/type/simple/SimpleType.js

@@ -1,4 +1,14 @@
 import Type from '../Type.js';
 
-export default class SimpleType extends Type {
+/**
+ * Class representing a simple type.
+ *
+ * This serves as a base class for primitive or simple types such as string, number, or boolean.
+ *
+ * @class SimpleType
+ * @extends Type
+ */
+class SimpleType extends Type {
 }
+
+export default SimpleType;

package/src/type/simple/StringType.js

@@ -1,5 +1,20 @@
 import SimpleType from './SimpleType.js';
 
-export default class StringType extends SimpleType {
+/**
+ * Class representing a string type.
+ *
+ * This class is used to define and handle data of the string type.
+ * It extends the {@link SimpleType} class to represent string-specific behavior.
+ *
+ * @class StringType
+ * @extends SimpleType
+ */
+class StringType extends SimpleType {
+    /**
+     * @static
+     * @property {string} _type - The type identifier for the string type.
+     */
     static _type = 'string';
 }
+
+export default StringType;