@acodeninja/persist 2.4.1-next.2 → 3.0.0-next.10

package/src/engine/{HTTPEngine.js → storage/HTTPStorageEngine.js}

@@ -1,22 +1,22 @@
-import Engine, {EngineError, MissConfiguredError} from './Engine.js';
+import StorageEngine, {EngineError, MissConfiguredError} from './StorageEngine.js';
 
 /**
  * Represents an error specific to HTTP engine operations.
- * @class HTTPEngineError
+ * @class HTTPStorageEngineError
  * @extends EngineError
  */
-export class HTTPEngineError extends EngineError {}
+export class HTTPStorageEngineError extends EngineError {}
 
 /**
  * Error indicating a failed HTTP request.
  * @class HTTPRequestFailedError
- * @extends HTTPEngineError
+ * @extends HTTPStorageEngineError
  *
  * @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 {
+export class HTTPRequestFailedError extends HTTPStorageEngineError {
     constructor(url, options, response) {
         const method = options.method?.toLowerCase() || 'get';
         super(`Failed to ${method} ${url}`);
@@ -27,13 +27,13 @@ export class HTTPRequestFailedError extends HTTPEngineError {
 }
 
 /**
- * HTTPEngine is an extension of the Engine class that provides methods for interacting with HTTP-based APIs.
+ * HTTPStorageEngine is an extension of the StorageEngine 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 HTTPStorageEngine
+ * @extends StorageEngine
  */
-class HTTPEngine extends Engine {
+class HTTPStorageEngine extends StorageEngine {
 
     /**
      * Configures the HTTP engine with additional fetch options.
@@ -186,6 +186,12 @@ class HTTPEngine extends Engine {
      * @throws {HTTPRequestFailedError} Thrown if the PUT request fails.
      */
     static async putIndex(index) {
+        /**
+         * Process an index of models
+         * @param {string} location
+         * @param {Array<Model>} models
+         * @return {Promise<void>}
+         */
         const processIndex = async (location, models) => {
             const url = new URL([
                 this.configuration.host,
@@ -315,4 +321,4 @@ class HTTPEngine extends Engine {
     }
 }
 
-export default HTTPEngine;
+export default HTTPStorageEngine;

package/src/engine/{S3Engine.js → storage/S3StorageEngine.js}

@@ -1,28 +1,28 @@
 import {DeleteObjectCommand, GetObjectCommand, PutObjectCommand} from '@aws-sdk/client-s3';
-import Engine, {EngineError, MissConfiguredError} from './Engine.js';
+import StorageEngine, {EngineError, MissConfiguredError} from './StorageEngine.js';
 
 /**
  * Represents an error specific to the S3 engine operations.
- * @class S3EngineError
+ * @class S3StorageEngineError
  * @extends EngineError
  */
-class S3EngineError extends EngineError {}
+class S3StorageEngineError extends EngineError {}
 
 /**
  * Error indicating a failure when putting an object to S3.
- * @class FailedPutS3EngineError
- * @extends S3EngineError
+ * @class FailedPutS3StorageEngineError
+ * @extends S3StorageEngineError
  */
-class FailedPutS3EngineError extends S3EngineError {}
+class FailedPutS3StorageEngineError extends S3StorageEngineError {}
 
 /**
- * S3Engine is an extension of the Engine class that provides methods for interacting with AWS S3.
+ * S3StorageEngine is an extension of the StorageEngine 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 S3StorageEngine
+ * @extends StorageEngine
  */
-class S3Engine extends Engine {
+class S3StorageEngine extends StorageEngine {
     /**
      * Configures the S3 engine with additional options.
      *
@@ -92,7 +92,7 @@ class S3Engine extends Engine {
      * @param {Model} model - The model object to upload.
      * @returns {Promise<void>}
      *
-     * @throws {FailedPutS3EngineError} Thrown if there is an error during the S3 PutObject operation.
+     * @throws {FailedPutS3StorageEngineError} Thrown if there is an error during the S3 PutObject operation.
      */
     static async putModel(model) {
         const Key = [this.configuration.prefix, `${model.id}.json`].join('/');
@@ -105,7 +105,7 @@ class S3Engine extends Engine {
                 ContentType: 'application/json',
             }));
         } catch (error) {
-            throw new FailedPutS3EngineError(`Failed to put s3://${this.configuration.bucket}/${Key}`, error);
+            throw new FailedPutS3StorageEngineError(`Failed to put s3://${this.configuration.bucket}/${Key}`, error);
         }
     }
 
@@ -133,9 +133,16 @@ class S3Engine extends Engine {
      *
      * @param {Object} index - An object where keys are locations and values are key value pairs of models and their ids.
      * @returns {Promise<void>}
-     * @throws {FailedPutS3EngineError} Thrown if there is an error during the S3 PutObject operation.
+     * @throws {FailedPutS3StorageEngineError} Thrown if there is an error during the S3 PutObject operation.
      */
     static async putIndex(index) {
+        /**
+         * Process an index of models
+         * @param {string} location
+         * @param {Array<Model>} models
+         * @throws FailedPutS3StorageEngineError
+         * @return {Promise<void>}
+         */
         const processIndex = async (location, models) => {
             const Key = [this.configuration.prefix, location, '_index.json'].filter(e => Boolean(e)).join('/');
             const currentIndex = await this.getIndex(location);
@@ -153,7 +160,7 @@ class S3Engine extends Engine {
                     }),
                 }));
             } catch (error) {
-                throw new FailedPutS3EngineError(`Failed to put s3://${this.configuration.bucket}/${Key}`, error);
+                throw new FailedPutS3StorageEngineError(`Failed to put s3://${this.configuration.bucket}/${Key}`, error);
             }
         };
 
@@ -205,7 +212,7 @@ class S3Engine extends Engine {
      * @param {Object} compiledIndex - The compiled search index data.
      * @returns {Promise<void>}
      *
-     * @throws {FailedPutS3EngineError} Thrown if there is an error during the S3 PutObject operation.
+     * @throws {FailedPutS3StorageEngineError} Thrown if there is an error during the S3 PutObject operation.
      */
     static async putSearchIndexCompiled(model, compiledIndex) {
         const Key = [this.configuration.prefix, model.toString(), '_search_index.json'].join('/');
@@ -218,7 +225,7 @@ class S3Engine extends Engine {
                 ContentType: 'application/json',
             }));
         } catch (error) {
-            throw new FailedPutS3EngineError(`Failed to put s3://${this.configuration.bucket}/${Key}`, error);
+            throw new FailedPutS3StorageEngineError(`Failed to put s3://${this.configuration.bucket}/${Key}`, error);
         }
     }
 
@@ -229,7 +236,7 @@ class S3Engine extends Engine {
      * @param {Object} rawIndex - The raw search index data.
      * @returns {Promise<void>}
      *
-     * @throws {FailedPutS3EngineError} Thrown if there is an error during the S3 PutObject operation.
+     * @throws {FailedPutS3StorageEngineError} Thrown if there is an error during the S3 PutObject operation.
      */
     static async putSearchIndexRaw(model, rawIndex) {
         const Key = [this.configuration.prefix, model.toString(), '_search_index_raw.json'].join('/');
@@ -242,9 +249,9 @@ class S3Engine extends Engine {
                 ContentType: 'application/json',
             }));
         } catch (error) {
-            throw new FailedPutS3EngineError(`Failed to put s3://${this.configuration.bucket}/${Key}`, error);
+            throw new FailedPutS3StorageEngineError(`Failed to put s3://${this.configuration.bucket}/${Key}`, error);
         }
     }
 }
 
-export default S3Engine;
+export default S3StorageEngine;

package/src/engine/{Engine.js → storage/StorageEngine.js}

@@ -1,14 +1,14 @@
-import Query from '../Query.js';
-import Type from '../type/index.js';
+import Query from '../../Query.js';
+import Type from '../../type/index.js';
 import lunr from 'lunr';
 
 /**
- * The `Engine` class provides a base interface for implementing data storage and retrieval engines.
+ * The `StorageEngine` class provides a base interface for implementing data storage and retrieval engines.
  * It includes methods for handling models, indexes, and search functionality.
  *
- * @class Engine
+ * @class StorageEngine
  */
-class Engine {
+class StorageEngine {
     static configuration = undefined;
     static _searchCache = undefined;
 
@@ -186,6 +186,11 @@ class Engine {
         const uploadedModels = [];
         const indexUpdates = {};
 
+        /**
+         * Process a model, putting updates to the model and all linked models.
+         * @param {Model} m
+         * @return {Promise<void>}
+         */
         const processModel = async (m) => {
             if (!uploadedModels.includes(m.id)) {
                 m.validate();
@@ -389,6 +394,11 @@ class Engine {
         this.checkConfiguration();
         const hydratedModels = {};
 
+        /**
+         * Hydrate a model
+         * @param {Model} modelToProcess
+         * @return {Promise<Model>}
+         */
         const hydrateModel = async (modelToProcess) => {
             hydratedModels[modelToProcess.id] = modelToProcess;
 
@@ -405,6 +415,13 @@ class Engine {
             return modelToProcess;
         };
 
+        /**
+         * Hydrate a dry sub model
+         * @param property
+         * @param modelToProcess
+         * @param name
+         * @return {Promise<Model>}
+         */
         const hydrateSubModel = async (property, modelToProcess, name) => {
             if (hydratedModels[property.id]) {
                 return hydratedModels[property.id];
@@ -418,6 +435,13 @@ class Engine {
             return hydratedSubModel;
         };
 
+        /**
+         * Hydrate an array of dry models
+         * @param property
+         * @param modelToProcess
+         * @param name
+         * @return {Promise<Awaited<*>[]>}
+         */
         const hydrateModelList = async (property, modelToProcess, name) => {
             const subModelClass = getSubModelClass(modelToProcess, name, true);
 
@@ -440,6 +464,13 @@ class Engine {
             }));
         };
 
+        /**
+         * Get the class of a sub model
+         * @param modelToProcess
+         * @param name
+         * @param isArray
+         * @return {Model.constructor|Type}
+         */
         function getSubModelClass(modelToProcess, name, isArray = false) {
             const constructorField = modelToProcess.constructor[name];
 
@@ -457,9 +488,13 @@ class Engine {
      * 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.
+     * @returns {StorageEngine} A new engine instance with the applied configuration.
      */
     static configure(configuration) {
+        /**
+         * @class ConfiguredStore
+         * @extends StorageEngine
+         */
         class ConfiguredStore extends this {
             static configuration = configuration;
         }
@@ -476,7 +511,7 @@ class Engine {
      * @abstract
      */
     static checkConfiguration() {
-        // Implemented in extending Engine class
+        // Implemented in extending StorageEngine class
     }
 
     /**
@@ -568,9 +603,9 @@ export class MissConfiguredError extends EngineError {
      * @param {Object} configuration - The configuration object that caused the misconfiguration.
      */
     constructor(configuration) {
-        super('Engine is miss-configured');
+        super('StorageEngine is miss-configured');
         this.configuration = configuration;
     }
 }
 
-export default Engine;
+export default StorageEngine;

package/src/type/Model.js

@@ -100,11 +100,11 @@ class Model {
 
     /**
      * Extracts data from the model based on the indexed properties defined in the class.
-     *
+     * Includes the ID of any linked models.
      * @returns {Object} - A representation of the model's indexed data.
      */
     toIndexData() {
-        return this._extractData(this.constructor.indexedProperties());
+        return this._extractData(this.constructor.indexedPropertiesResolved());
     }
 
     /**
@@ -187,6 +187,39 @@ class Model {
         return [];
     }
 
+    /**
+     * Returns a list of properties that are indexed including links to other models.
+     *
+     * @returns {Array<string>} - The indexed properties.
+     * @abstract
+     * @static
+     */
+    static indexedPropertiesResolved() {
+        return []
+            .concat(
+                Object.entries(this)
+                    .filter(([_name, type]) =>
+                        this.isModel(
+                            typeof type === 'function' &&
+                            !/^class/.test(Function.prototype.toString.call(type)) ?
+                                type() : type,
+                        ),
+                    )
+                    .map(([name, _type]) => `${name}.id`),
+            )
+            .concat(
+                Object.entries(this)
+                    .filter(([_name, type]) =>
+                            type?._type === 'array' && this.isModel(
+                                typeof type._items === 'function' &&
+                                !/^class/.test(Function.prototype.toString.call(type._items)) ?
+                                    type._items() : type._items,
+                            ),
+                    ).map(([name, _type]) => `${name}.[*].id`),
+            )
+            .concat(this.indexedProperties());
+    }
+
     /**
      * Returns a list of properties used for search.
      *

package/src/type/index.js

@@ -15,23 +15,18 @@ import StringType from './simple/StringType.js';
  * @property {DateType} Date
  * @property {ArrayType} Array
  * @property {CustomType} Custom
- * @property {ResolvedType} Resolved
+ * @property {{Slug: SlugType}} Resolved
  * @property {Model} Model
  */
-const Type = {};
-
-Type.String = StringType;
-Type.Number = NumberType;
-Type.Boolean = BooleanType;
-Type.Date = DateType;
-Type.Array = ArrayType;
-Type.Custom = CustomType;
-
-/**
- * @class ResolvedType
- * @property {SlugType} Slug
- */
-Type.Resolved = {Slug: SlugType};
-Type.Model = Model;
+class Type {
+    static Model = Model;
+    static String = StringType;
+    static Number = NumberType;
+    static Boolean = BooleanType;
+    static Date = DateType;
+    static Array = ArrayType;
+    static Custom = CustomType;
+    static Resolved = {Slug: SlugType};
+}
 
 export default Type;

package/src/type/simple/BooleanType.js

@@ -1,15 +1,15 @@
-import SimpleType from './SimpleType.js';
+import Type from '../Type.js';
 
 /**
  * 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.
+ * It extends the {@link Type} class to represent string-specific behavior.
  *
  * @class BooleanType
- * @extends SimpleType
+ * @extends Type
  */
-class BooleanType extends SimpleType {
+class BooleanType extends Type {
     static {
         /**
          * @static

package/src/type/simple/DateType.js

@@ -1,15 +1,15 @@
-import SimpleType from './SimpleType.js';
+import Type from '../Type.js';
 
 /**
  * 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.
+ * It extends the {@link Type} class to represent string-specific behavior.
  *
  * @class DateType
- * @extends SimpleType
+ * @extends Type
  */
-class DateType extends SimpleType {
+class DateType extends Type {
     static {
         /**
          * @static

package/src/type/simple/NumberType.js

@@ -1,15 +1,15 @@
-import SimpleType from './SimpleType.js';
+import Type from '../Type.js';
 
 /**
  * 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.
+ * It extends the {@link Type} class to represent string-specific behavior.
  *
  * @class NumberType
- * @extends SimpleType
+ * @extends Type
  */
-class NumberType extends SimpleType {
+class NumberType extends Type {
     static {
         /**
          * @static

package/src/type/simple/StringType.js

@@ -1,15 +1,15 @@
-import SimpleType from './SimpleType.js';
+import Type from '../Type.js';
 
 /**
  * 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.
+ * It extends the {@link Type} class to represent string-specific behavior.
  *
  * @class StringType
- * @extends SimpleType
+ * @extends Type
  */
-class StringType extends SimpleType {
+class StringType extends Type {
     static {
         /**
          * @static

package/exports/engine/file.js

@@ -1,3 +0,0 @@
-import FileEngine from '../../src/engine/FileEngine.js';
-
-export default FileEngine;

package/exports/engine/http.js

@@ -1,3 +0,0 @@
-import HTTPEngine from '../../src/engine/HTTPEngine.js';
-
-export default HTTPEngine;

package/exports/engine/s3.js

@@ -1,3 +0,0 @@
-import S3Engine from '../../src/engine/S3Engine.js';
-
-export default S3Engine;

package/src/type/simple/SimpleType.js

@@ -1,14 +0,0 @@
-import Type from '../Type.js';
-
-/**
- * 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;