@acodeninja/persist 3.0.0-next.9 → 3.0.1-next.1

package/src/engine/storage/StorageEngine.js

@@ -1,611 +1,193 @@
-import Query from '../../Query.js';
-import Type from '../../type/index.js';
-import lunr from 'lunr';
-
-/**
- * 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 StorageEngine
- */
-class StorageEngine {
-    static configuration = undefined;
-    static _searchCache = undefined;
-
-    /**
-     * Retrieves a model by its ID. This method must be implemented by subclasses.
-     *
-     * @param {string} _id - The ID of the model to retrieve.
-     * @throws {NotImplementedError} Throws if the method is not implemented.
-     * @returns {Promise<Object>} - Returns a promise resolving to the raw data of the requested model.
-     * @abstract
-     */
-    static getById(_id) {
-        return Promise.reject(new NotImplementedError(`${this.name} must implement .getById()`));
-    }
-
-    /**
-     * Deletes a model by its ID. This method must be implemented by subclasses.
-     *
-     * @param {string} _id - The ID of the model to retrieve.
-     * @throws {NotImplementedError} Throws if the method is not implemented.
-     * @returns {Promise<void>} - Returns a promise resolving when the model has been deleted.
-     * @abstract
-     */
-    static deleteById(_id) {
-        return Promise.reject(new NotImplementedError(`${this.name} must implement .deleteById()`));
-    }
-
+export default class StorageEngine {
     /**
-     * Saves a model to the data store. This method must be implemented by subclasses.
-     *
-     * @param {Model} _data - The model data to save.
-     * @throws {NotImplementedError} Throws if the method is not implemented.
-     * @returns {Promise<void>}
-     * @abstract
+     * @param {Object} configuration
      */
-    static putModel(_data) {
-        return Promise.reject(new NotImplementedError(`${this.name} must implement .putModel()`));
-    }
-
-    /**
-     * Retrieves the index for a given model. This method must be implemented by subclasses.
-     *
-     * @param {Model.constructor} _model - The model to retrieve the index for.
-     * @throws {NotImplementedError} Throws if the method is not implemented.
-     * @returns {Promise<Object>} - Returns a promise resolving to the model index.
-     * @abstract
-     */
-    static getIndex(_model) {
-        return Promise.reject(new NotImplementedError(`${this.name} does not implement .getIndex()`));
+    constructor(configuration = {}) {
+        this.configuration = configuration;
     }
 
     /**
-     * Saves the index for a given model. This method must be implemented by subclasses.
-     *
-     * @param {Object} _index - The index data to save.
-     * @throws {NotImplementedError} Throws if the method is not implemented.
-     * @returns {Promise<void>}
-     * @abstract
+     * Get a model
+     * @param {string} _id
+     * @throws MethodNotImplementedStorageEngineError
+     * @throws ModelNotFoundStorageEngineError
+     * @return Promise<Object>
      */
-    static putIndex(_index) {
-        return Promise.reject(new NotImplementedError(`${this.name} does not implement .putIndex()`));
+    getModel(_id) {
+        return Promise.reject(new MethodNotImplementedStorageEngineError('getModel', this));
     }
 
     /**
-     * Retrieves the compiled search index for a model. This method must be implemented by subclasses.
-     *
-     * @param {Model.constructor} _model - The model to retrieve the compiled search index for.
-     * @throws {NotImplementedError} Throws if the method is not implemented.
-     * @returns {Promise<Object>} - Returns a promise resolving to the compiled search index.
-     * @abstract
+     * Update a model
+     * @param {Object} _model
+     * @throws MethodNotImplementedStorageEngineError
+     * @return Promise<void>
      */
-    static getSearchIndexCompiled(_model) {
-        return Promise.reject(new NotImplementedError(`${this.name} does not implement .getSearchIndexCompiled()`));
+    putModel(_model) {
+        return Promise.reject(new MethodNotImplementedStorageEngineError('putModel', this));
     }
 
     /**
-     * Retrieves the raw search index for a model. This method must be implemented by subclasses.
-     *
-     * @param {Model.constructor} _model - The model to retrieve the raw search index for.
-     * @throws {NotImplementedError} Throws if the method is not implemented.
-     * @returns {Promise<Object>} - Returns a promise resolving to the raw search index.
-     * @abstract
+     * Delete a model
+     * @param {string} _id
+     * @throws MethodNotImplementedStorageEngineError
+     * @throws ModelNotFoundStorageEngineError
+     * @return Promise<void>
      */
-    static getSearchIndexRaw(_model) {
-        return Promise.reject(new NotImplementedError(`${this.name} does not implement .getSearchIndexRaw()`));
+    deleteModel(_id) {
+        return Promise.reject(new MethodNotImplementedStorageEngineError('deleteModel', this));
     }
 
     /**
-     * Saves the compiled search index for a model. This method must be implemented by subclasses.
-     *
-     * @param {Model.constructor} _model - The model for which the compiled search index is saved.
-     * @param {Object} _compiledIndex - The compiled search index data.
-     * @throws {NotImplementedError} Throws if the method is not implemented.
-     * @returns {Promise<void>}
-     * @abstract
+     * Get a model's index data
+     * @param {Model.constructor} _modelConstructor
+     * @throws MethodNotImplementedStorageEngineError
+     * @return Promise<Record<String, Object>>
      */
-    static putSearchIndexCompiled(_model, _compiledIndex) {
-        return Promise.reject(new NotImplementedError(`${this.name} does not implement .putSearchIndexCompiled()`));
+    getIndex(_modelConstructor) {
+        return Promise.reject(new MethodNotImplementedStorageEngineError('getIndex', this));
     }
 
     /**
-     * Saves the raw search index for a model. This method must be implemented by subclasses.
-     *
-     * @param {Model.constructor} _model - The model for which the raw search index is saved.
-     * @param {Object} _rawIndex - The raw search index data.
-     * @throws {NotImplementedError} Throws if the method is not implemented.
-     * @returns {Promise<void>}
-     * @abstract
+     * Put a model's index data
+     * @param {Model.constructor} _modelConstructor
+     * @param {Record<String, Object>} _data
+     * @throws MethodNotImplementedStorageEngineError
+     * @return Promise<void>
      */
-    static putSearchIndexRaw(_model, _rawIndex) {
-        return Promise.reject(new NotImplementedError(`${this.name} does not implement .putSearchIndexRaw()`));
+    putIndex(_modelConstructor, _data) {
+        return Promise.reject(new MethodNotImplementedStorageEngineError('putIndex', this));
     }
 
     /**
-     * Performs a search query on a model's index and returns the matching models.
-     *
-     * @param {Model.constructor} model - The model class.
-     * @param {string} query - The search query string.
-     * @returns {Promise<Array<Model>>} An array of models matching the search query.
-     * @throws {EngineError} Throws if the search index is not available for the model.
+     * Get a model's raw search index data
+     * @param {Model.constructor} _modelConstructor
+     * @throws MethodNotImplementedStorageEngineError
+     * @return Promise<Record<String, Object>>
      */
-    static async search(model, query) {
-        this.checkConfiguration();
-
-        const index =
-            (this._searchCache && this.configuration?.cache?.search && Date.now() - this._searchCache[0] < this.configuration.cache.search) ?
-                this._searchCache[1] :
-                await this.getSearchIndexCompiled(model)
-                    .then(i => {
-                        this._searchCache = [Date.now(), i];
-                        return i;
-                    })
-                    .catch(error => {
-                        throw new EngineError(`The model ${model.toString()} does not have a search index available.`, error);
-                    });
-
-        const searchIndex = lunr.Index.load(index);
-
-        const results = searchIndex.search(`*${query}*`);
-
-        const output = [];
-        for (const result of results) {
-            output.push({
-                ...result,
-                score: Number(result.score.toFixed(4)),
-                model: await this.get(model, result.ref),
-            });
-        }
-
-        return output;
+    getSearchIndex(_modelConstructor) {
+        return Promise.reject(new MethodNotImplementedStorageEngineError('getSearchIndex', this));
     }
 
     /**
-     * Finds models that match a query in the model's index.
-     *
-     * @param {Model.constructor} model - The model class to search.
-     * @param {object} query - The query object containing search criteria.
-     * @returns {Array<Model>} An array of models matching the query.
+     * Put a model's raw and compiled search index data
+     * @param {Model.constructor} _constructor
+     * @param {Record<string, object>} _index
+     * @throws MethodNotImplementedStorageEngineError
+     * @return Promise<Record<String, Object>>
      */
-    static async find(model, query) {
-        this.checkConfiguration();
-        const index = await this.getIndex(model);
-
-        return new Query(query).execute(model, index);
-    }
-
-    /**
-     * Stores a model and its associated index data into the system.
-     *
-     * @param {Model} model - The model to store.
-     * @throws {EngineError} Throws if the model fails to validate or index fails to save.
-     */
-    static async put(model) {
-        this.checkConfiguration();
-        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();
-
-                await this.putModel(m);
-
-                uploadedModels.push(m.id);
-                indexUpdates[m.constructor.name] = {
-                    ...indexUpdates[m.constructor.name] || {},
-                    [m.id]: m,
-                };
-
-                if (m.constructor.searchProperties().length > 0) {
-                    const rawSearchIndex = {
-                        ...await this.getSearchIndexRaw(m.constructor),
-                        [m.id]: m.toSearchData(),
-                    };
-
-                    await this.putSearchIndexRaw(m.constructor, rawSearchIndex);
-
-                    const compiledIndex = lunr(function () {
-                        this.ref('id');
-
-                        for (const field of m.constructor.searchProperties()) {
-                            this.field(field);
-                        }
-
-                        Object.values(rawSearchIndex).forEach(function (doc) {
-                            this.add(doc);
-                        }, this);
-                    });
-
-                    await this.putSearchIndexCompiled(m.constructor, compiledIndex);
-                }
-
-                for (const [_, property] of Object.entries(m)) {
-                    if (Type.Model.isModel(property)) {
-                        await processModel(property);
-                    }
-                    if (Array.isArray(property) && Type.Model.isModel(property[0])) {
-                        for (const subModel of property) {
-                            await processModel(subModel);
-                        }
-                    }
-                }
-            }
-        };
-
-        await processModel(model);
-        await this.putIndex(indexUpdates);
-    }
-
-    /**
-     * Retrieves a model by its ID and converts it to its data representation.
-     *
-     * @param {Model.constructor} model - The model class to retrieve.
-     * @param {string} id - The ID of the model to retrieve.
-     * @returns {Model} The found model.
-     * @throws {NotFoundEngineError} Throws if the model is not found.
-     */
-    static async get(model, id) {
-        this.checkConfiguration();
-
-        try {
-            const found = await this.getById(id);
-            return model.fromData(found);
-        } catch (error) {
-            if (error.constructor === NotImplementedError) throw error;
-            throw new NotFoundEngineError(`${this.name}.get(${id}) model not found`, error);
-        }
-    }
-
-    /**
-     * Deletes a model
-     *
-     * @param {Model} model
-     * @return {Promise<void>}
-     * @throws {NotFoundEngineError} Throws if the model is not found.
-     */
-    static async delete(model) {
-        this.checkConfiguration();
-
-        const modelUpdates = [];
-        const processedModels = [];
-        const indexUpdates = {};
-        const additionalDeletions = [];
-        const deletedModels = [];
-
-        /**
-         * Delete the given model, updating search indexes as required.
-         * @param {Model} m - The model to be deleted.
-         * @return {Promise<void>}
-         */
-        const deleteModel = async (m) => {
-            if (deletedModels.includes(m.id)) return;
-            if (m.constructor.searchProperties().length > 0) {
-                const rawSearchIndex = await this.getSearchIndexRaw(m.constructor);
-
-                delete rawSearchIndex[m.id];
-
-                await this.putSearchIndexRaw(m.constructor, rawSearchIndex);
-
-                const compiledIndex = lunr(function () {
-                    this.ref('id');
-
-                    for (const field of m.constructor.searchProperties()) {
-                        this.field(field);
-                    }
-
-                    Object.values(rawSearchIndex).forEach(function (doc) {
-                        this.add(doc);
-                    }, this);
-                });
-
-                await this.putSearchIndexCompiled(m.constructor, compiledIndex);
-            }
-
-            if (m.constructor.indexedProperties().length > 0) {
-                indexUpdates[m.constructor.name] = {
-                    ...indexUpdates[m.constructor.name] || {},
-                    [m.id]: undefined,
-                };
-            }
-
-            await this.deleteById(m.id);
-            deletedModels.push(m.id);
-        };
-
-        /**
-         * Process updates to all sub-models of the given model.
-         * @param {Model} m - The model to process for updates.
-         * @return {Promise<void>}
-         */
-        const processModelUpdates = async (m) => {
-            if (!processedModels.includes(m.id)) {
-                processedModels.push(m.id);
-
-                for (const [key, property] of Object.entries(m)) {
-                    if (Type.Model.isModel(property)) {
-                        if (property.id === model.id) {
-                            m[key] = undefined;
-                            indexUpdates[m.constructor.name] = {
-                                ...indexUpdates[m.constructor.name] || {},
-                                [m.id]: m,
-                            };
-                            modelUpdates.push(m);
-                        }
-
-                        if (m.id !== model.id && (Type.Model.isModel(m.constructor[key]) ? m.constructor[key] : m.constructor[key]())._required) {
-                            additionalDeletions.push(m);
-                        }
-
-                        await processModelUpdates(property);
-                    }
-                    if (Array.isArray(property) && Type.Model.isModel(property[0])) {
-                        for (const [index, subModel] of property.entries()) {
-                            if (subModel.id === model.id) {
-                                m[key].splice(index, 1);
-                                indexUpdates[m.constructor.name] = {
-                                    ...indexUpdates[m.constructor.name] || {},
-                                    [m.id]: m,
-                                };
-                                modelUpdates.push(m);
-                            }
-                            await processModelUpdates(subModel);
-                        }
-                    }
-                }
-            }
-        };
-
-        try {
-            const hydrated = await this.hydrate(model);
-            await processModelUpdates(hydrated);
-            await deleteModel(hydrated);
-
-            for (const updatedModel of modelUpdates) {
-                if (!additionalDeletions.map(m => m.id).includes(updatedModel.id)) {
-                    await this.put(updatedModel);
-                }
-            }
-
-            for (const modelToBeDeleted of additionalDeletions) {
-                await deleteModel(modelToBeDeleted);
-            }
-
-            await this.putIndex(indexUpdates);
-        } catch (error) {
-            if (error.constructor === NotImplementedError) throw error;
-            throw new CannotDeleteEngineError(`${this.name}.delete(${model.id}) model cannot be deleted`, error);
-        }
-    }
-
-    /**
-     * Hydrates a model by populating its related properties (e.g., submodels) from stored data.
-     *
-     * @param {Model} model - The model to hydrate.
-     * @returns {Model} The hydrated model.
-     */
-    static async hydrate(model) {
-        this.checkConfiguration();
-        const hydratedModels = {};
-
-        /**
-         * Hydrate a model
-         * @param {Model} modelToProcess
-         * @return {Promise<Model>}
-         */
-        const hydrateModel = async (modelToProcess) => {
-            hydratedModels[modelToProcess.id] = modelToProcess;
-
-            for (const [name, property] of Object.entries(modelToProcess)) {
-                if (Type.Model.isDryModel(property)) {
-                    // skipcq: JS-0129
-                    modelToProcess[name] = await hydrateSubModel(property, modelToProcess, name);
-                } else if (Array.isArray(property) && Type.Model.isDryModel(property[0])) {
-                    // skipcq: JS-0129
-                    modelToProcess[name] = await hydrateModelList(property, modelToProcess, name);
-                }
-            }
-
-            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];
-            }
-
-            const subModelClass = getSubModelClass(modelToProcess, name);
-            const subModel = await this.get(subModelClass, property.id);
-
-            const hydratedSubModel = await hydrateModel(subModel);
-            hydratedModels[property.id] = hydratedSubModel;
-            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);
-
-            const newModelList = await Promise.all(property.map(subModel => {
-                if (hydratedModels[subModel.id]) {
-                    return hydratedModels[subModel.id];
-                }
-
-                return this.get(subModelClass, subModel.id);
-            }));
-
-            return Promise.all(newModelList.map(async subModel => {
-                if (hydratedModels[subModel.id]) {
-                    return hydratedModels[subModel.id];
-                }
-
-                const hydratedSubModel = await hydrateModel(subModel);
-                hydratedModels[hydratedSubModel.id] = hydratedSubModel;
-                return hydratedSubModel;
-            }));
-        };
-
-        /**
-         * 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];
-
-            if (constructorField instanceof Function && !constructorField.prototype) {
-                return isArray ? constructorField()._items : constructorField();
-            }
-
-            return isArray ? constructorField._items : constructorField;
-        }
-
-        return hydrateModel(await this.get(model.constructor, model.id));
-    }
-
-    /**
-     * Configures the engine with specific settings.
-     *
-     * @param {Object} configuration - The configuration settings for the engine.
-     * @returns {StorageEngine} A new engine instance with the applied configuration.
-     */
-    static configure(configuration) {
-        /**
-         * @class ConfiguredStore
-         * @extends StorageEngine
-         */
-        class ConfiguredStore extends this {
-            static configuration = configuration;
-        }
-
-        Object.defineProperty(ConfiguredStore, 'name', {value: `${this.toString()}`});
-
-        return ConfiguredStore;
-    }
-
-    /**
-     * Checks if the engine is properly configured.
-     *
-     * @throws {MissConfiguredError} Throws if the engine is misconfigured.
-     * @abstract
-     */
-    static checkConfiguration() {
-        // Implemented in extending StorageEngine class
-    }
-
-    /**
-     * Returns the name of the engine class.
-     *
-     * @returns {string} The name of the engine class.
-     */
-    static toString() {
-        return this.name;
+    putSearchIndex(_constructor, _index) {
+        return Promise.reject(new MethodNotImplementedStorageEngineError('putSearchIndex', this));
     }
 }
 
 /**
- * Represents a general error that occurs within the engine.
- * Extends the built-in `Error` class.
+ * @class StorageEngineError
+ * @extends Error
  */
-export class EngineError extends Error {
-    /**
-     * The underlying error that caused this engine error, if available.
-     * @type {Error|undefined}
-     */
-    underlyingError;
+export class StorageEngineError extends Error {
+}
 
+/**
+ * @class MisconfiguredStorageEngineError
+ * @extends StorageEngineError
+ */
+export class MisconfiguredStorageEngineError extends StorageEngineError {
     /**
-     * Creates an instance of `EngineError`.
-     *
-     * @param {string} message - The error message.
-     * @param {Error} [error] - An optional underlying error that caused this error.
+     * @param {string} message
+     * @param {StorageEngine} storageEngine
      */
-    constructor(message, error = undefined) {
-        super(message);
-        this.underlyingError = error;
+    constructor(message, storageEngine) {
+        super(`Incorrect configuration given for storage engine ${storageEngine.constructor.name}: ${message}`);
     }
 }
 
 /**
- * Represents an error that occurs when a requested resource or item is not found in the engine.
- * Extends the `EngineError` class.
+ * @class MethodNotImplementedStorageEngineError
+ * @extends StorageEngineError
  */
-export class NotFoundEngineError extends EngineError {
+export class MethodNotImplementedStorageEngineError extends StorageEngineError {
     /**
-     * Creates an instance of `NotFoundEngineError`.
-     *
-     * @param {string} message - The error message.
-     * @param {Error} [error] - An optional underlying error that caused this error.
+     * @param {string} method
+     * @param {StorageEngine} storageEngine
      */
+    constructor(method, storageEngine) {
+        super(`The method ${method} is not implemented in the storage engine ${storageEngine.constructor.name}`);
+    }
 }
 
 /**
- * Represents an error that occurs when a requested resource or item cannot be deleted by the engine.
- * Extends the `EngineError` class.
+ * @class ModelNotFoundStorageEngineError
+ * @extends StorageEngineError
  */
-export class CannotDeleteEngineError extends EngineError {
+export class ModelNotFoundStorageEngineError extends StorageEngineError {
     /**
-     * Creates an instance of `CannotDeleteEngineError`.
-     *
-     * @param {string} message - The error message.
-     * @param {Error} [error] - An optional underlying error that caused this error.
+     * @param {string} modelId
      */
+    constructor(modelId) {
+        super(`The model ${modelId} was not found`);
+    }
 }
 
-/**
- * Represents an error indicating that a certain method or functionality is not implemented in the engine.
- * Extends the `EngineError` class.
- */
-export class NotImplementedError extends EngineError {
+export class DeleteHasUnintendedConsequencesStorageEngineError extends StorageEngineError {
     /**
-     * Creates an instance of `NotImplementedError`.
-     *
-     * @param {string} message - The error message.
-     * @param {Error} [error] - An optional underlying error that caused this error.
+     * @param {string} modelId
+     * @param {Object} consequences
+     * @param {Array<String>?} consequences.willDelete
+     * @param {Array<String>?} consequences.willUpdate
      */
+    constructor(modelId, consequences) {
+        super(`Deleting ${modelId} has unintended consequences`);
+        this.consequences = consequences;
+    }
 }
 
 /**
- * Represents an error indicating that the engine is misconfigured.
- * Extends the `EngineError` class.
+ * Represents a transactional operation to be executed, typically queued and later committed.
+ *
+ * Stores the method to invoke, the arguments to apply, and tracks the result or error state
+ * of the transaction once it's processed.
+ *
+ * @class Operation
  */
-export class MissConfiguredError extends EngineError {
-    /**
-     * The configuration that led to the misconfiguration error.
-     * @type {Object}
-     */
-    configuration;
-
-    /**
-     * Creates an instance of `MissConfiguredError`.
-     *
-     * @param {Object} configuration - The configuration object that caused the misconfiguration.
-     */
-    constructor(configuration) {
-        super('StorageEngine is miss-configured');
-        this.configuration = configuration;
+export class Operation {
+    constructor(method, ...args) {
+        this.method = method;
+        this.args = args;
+        this.original = undefined;
+        this.error = undefined;
+        this.committed = false;
     }
 }
 
-export default StorageEngine;
+/**
+ *
+ * @param {Array<Operation>} transactions
+ * @param {StorageEngine} engine
+ * @return {StorageEngine}
+ */
+export function CreateTransactionalStorageEngine(operations, engine) {
+    const transactionalEngine = Object.create(engine);
+
+    transactionalEngine.putModel = (...args) => {
+        operations.push(new Operation('putModel', ...args));
+        return Promise.resolve();
+    };
+
+    transactionalEngine.deleteModel = (...args) => {
+        operations.push(new Operation('deleteModel', ...args));
+        return Promise.resolve();
+    };
+
+    transactionalEngine.putIndex = (...args) => {
+        operations.push(new Operation('putIndex', ...args));
+        return Promise.resolve();
+    };
+
+    transactionalEngine.putSearchIndex = (...args) => {
+        operations.push(new Operation('putSearchIndex', ...args));
+        return Promise.resolve();
+    };
+
+    return transactionalEngine;
+}