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

package/src/engine/StorageEngine.js

@@ -0,0 +1,517 @@
+import Type from '../type/index.js';
+import _ from 'lodash';
+
+export default class StorageEngine {
+    /**
+     * @param {Object} configuration
+     * @param {Array<Type.Model.constructor>?} models
+     */
+    constructor(configuration = {}, models = null) {
+        this.configuration = configuration;
+        this.models = Object.fromEntries((models ?? []).map(model => [model.name, model]));
+    }
+
+    /**
+     * Persists a model if it has changed, and updates all related models and their indexes
+     * @param {Type.Model} model
+     * @return {Promise<void>}
+     */
+    async put(model) {
+        const processedModels = [];
+        const modelsToPut = [];
+        const modelsToReindex = {};
+        const modelsToReindexSearch = {};
+
+        /**
+         * @param {Type.Model} modelToProcess
+         * @return {Promise<void>}
+         */
+        const processModel = async (modelToProcess) => {
+            if (processedModels.includes(modelToProcess.id))
+                return;
+
+            processedModels.push(modelToProcess.id);
+
+            if (!Object.keys(this.models).includes(modelToProcess.constructor.name))
+                throw new ModelNotRegisteredStorageEngineError(modelToProcess, this);
+
+            modelToProcess.validate();
+            const currentModel = await this.get(modelToProcess.id).catch(() => null);
+
+            const modelToProcessHasChanged = JSON.stringify(currentModel?.toData() || {}) !== JSON.stringify(modelToProcess.toData());
+
+            if (modelToProcessHasChanged) modelsToPut.push(modelToProcess);
+
+            if (
+                Boolean(modelToProcess.constructor.indexedProperties().length) &&
+                indexedFieldsHaveChanged(currentModel, modelToProcess)
+            ) {
+                const modelToProcessConstructor = this.getModelConstructorFromId(modelToProcess.id);
+                modelsToReindex[modelToProcessConstructor] = modelsToReindex[modelToProcessConstructor] || [];
+                modelsToReindex[modelToProcessConstructor].push(modelToProcess);
+            }
+
+            if (
+                Boolean(modelToProcess.constructor.searchProperties().length) &&
+                searchableFieldsHaveChanged(currentModel, modelToProcess)
+            ) {
+                const modelToProcessConstructor = this.getModelConstructorFromId(modelToProcess.id);
+                modelsToReindexSearch[modelToProcessConstructor] = modelsToReindexSearch[modelToProcessConstructor] || [];
+                modelsToReindexSearch[modelToProcessConstructor].push(modelToProcess);
+            }
+
+            for (const [field, value] of Object.entries(modelToProcess)) {
+                if (Type.Model.isModel(value)) {
+                    await processModel(modelToProcess[field]);
+                }
+            }
+        };
+
+        await processModel(model);
+
+        await Promise.all([
+            Promise.all(modelsToPut.map(m => this._putModel(m.toData()))),
+            Promise.all(Object.entries(modelsToReindex).map(async ([constructorName, models]) => {
+                const modelConstructor = this.models[constructorName];
+                const index = await this._getIndex(modelConstructor);
+
+                await this._putIndex(modelConstructor, {
+                    ...index || {},
+                    ...Object.fromEntries(models.map(m => [m.id, m.toIndexData()])),
+                });
+            })),
+            Promise.all(Object.entries(modelsToReindexSearch).map(async ([constructorName, models]) => {
+                const modelConstructor = this.models[constructorName];
+                const index = await this._getSearchIndex(modelConstructor);
+
+                await this._putSearchIndex(modelConstructor, {
+                    ...index || {},
+                    ...Object.fromEntries(models.map(m => [m.id, m.toSearchData()])),
+                });
+            })),
+        ]);
+    }
+
+    /**
+     * Get a model by its id
+     * @param {string} modelId
+     * @throws {ModelNotFoundStorageEngineError}
+     * @return {Promise<Type.Model>}
+     */
+    get(modelId) {
+        try {
+            this.getModelConstructorFromId(modelId);
+        } catch (e) {
+            return Promise.reject(e);
+        }
+        return this._getModel(modelId);
+    }
+
+    /**
+     * Delete a model and update indexes that reference it
+     * @param {Type.Model} model
+     * @param {Array<string>} propagateTo - List of model ids that are expected to be deleted
+     * @throws {ModelNotRegisteredStorageEngineError}
+     * @throws {ModelNotFoundStorageEngineError}
+     */
+    async delete(model, propagateTo = []) {
+        const processedModels = [];
+        const modelsToDelete = [];
+        const modelsToPut = [];
+        const indexCache = {};
+        const indexActions = {};
+        const searchIndexCache = {};
+        const searchIndexActions = {};
+        const modelCache = {};
+
+        propagateTo.push(model.id);
+
+        /**
+         * Process a model for deletion
+         * @param {Type.Model} modelToProcess
+         * @return {Promise<void>}
+         */
+        const processModel = async (modelToProcess) => {
+            if (processedModels.includes(modelToProcess.id)) return;
+            processedModels.push(modelToProcess.id);
+
+            const modelsToProcess = [];
+            if (!Object.keys(this.models).includes(modelToProcess.constructor.name))
+                throw new ModelNotRegisteredStorageEngineError(modelToProcess, this);
+
+            const currentModel = modelCache[model.id] ?? await this.get(model.id);
+            modelCache[currentModel.id] = currentModel;
+
+            if (!modelsToDelete.includes(currentModel.id)) modelsToDelete.push(currentModel.id);
+
+            const modelToProcessConstructor = this.getModelConstructorFromId(modelToProcess.id);
+            indexActions[modelToProcessConstructor] = indexActions[modelToProcessConstructor] ?? [];
+            searchIndexActions[modelToProcessConstructor] = searchIndexActions[modelToProcessConstructor] ?? [];
+
+            if (currentModel.constructor.indexedPropertiesResolved().length) {
+                indexActions[modelToProcessConstructor].push(['delete', modelToProcess]);
+            }
+
+            if (currentModel.constructor.searchProperties().length) {
+                searchIndexActions[modelToProcessConstructor].push(['delete', modelToProcess]);
+            }
+
+            const linkedModels = await this.getInstancesLinkedTo(modelToProcess, indexCache);
+            const links = this.getLinksFor(modelToProcess.constructor);
+            Object.values(Object.fromEntries(await Promise.all(
+                Object.entries(linkedModels)
+                    .map(async ([constructor, updatableModels]) => [
+                        constructor,
+                        await Promise.all(updatableModels.map(async m => {
+                            const currentModel = modelCache[m.id] ?? await this.get(m.id);
+                            modelCache[currentModel.id] = currentModel;
+                            return currentModel;
+                        })),
+                    ]),
+            ))).flat(1)
+                .forEach(m =>
+                    Object.entries(links[m.constructor.name])
+                        .forEach(([linkName, modelConstructor]) => {
+                            if ((
+                                typeof modelConstructor[linkName] === 'function' &&
+                                !/^class/.test(Function.prototype.toString.call(modelConstructor[linkName])) &&
+                                !Type.Model.isModel(modelConstructor[linkName]) ?
+                                    modelConstructor[linkName]() : modelConstructor
+                            )._required) {
+                                if (!modelsToDelete.includes(m.id)) modelsToDelete.push(m.id);
+                                modelsToProcess.push(m);
+                            } else {
+                                m[linkName] = undefined;
+                                modelsToPut.push(m);
+
+                                indexActions[this.getModelConstructorFromId(m.id)].push(['reindex', m]);
+
+                                if (m.constructor.searchProperties().length) {
+                                    searchIndexActions[this.getModelConstructorFromId(m.id)].push(['reindex', m]);
+                                }
+                            }
+                        }),
+                );
+
+            for (const model of modelsToProcess) {
+                await processModel(model);
+            }
+        };
+
+        await processModel(model);
+
+        const unrequestedDeletions = modelsToDelete.filter(m => !propagateTo.includes(m));
+        if (unrequestedDeletions.length) {
+           throw new DeleteHasUnintendedConsequencesStorageEngineError(model.id, {
+               willDelete: unrequestedDeletions,
+           });
+        }
+
+        await Promise.all([
+            Promise.all(Object.entries(indexActions).map(async ([constructorName, actions]) => {
+                const modelConstructor = this.models[constructorName];
+                indexCache[modelConstructor] = indexCache[modelConstructor] ?? await this._getIndex(modelConstructor);
+
+                actions.forEach(([action, actionModel]) => {
+                    if (action === 'delete') {
+                        indexCache[modelConstructor] = _.omit(indexCache[modelConstructor], [actionModel.id]);
+                    }
+                    if (action === 'reindex') {
+                        indexCache[modelConstructor] = {
+                            ...indexCache[modelConstructor],
+                            [actionModel.id]: actionModel.toIndexData(),
+                        };
+                    }
+                });
+            })),
+            Promise.all(Object.entries(searchIndexActions).map(async ([constructorName, actions]) => {
+                const modelConstructor = this.models[constructorName];
+                searchIndexCache[modelConstructor] = searchIndexCache[modelConstructor] ?? await this._getSearchIndex(modelConstructor);
+
+                actions.forEach(([action, actionModel]) => {
+                    if (action === 'delete') {
+                        searchIndexCache[modelConstructor] = _.omit(searchIndexCache[modelConstructor], [actionModel.id]);
+                    }
+                    if (action === 'reindex') {
+                        searchIndexCache[modelConstructor] = {
+                            ...searchIndexCache[modelConstructor],
+                            [actionModel.id]: actionModel.toSearchData(),
+                        };
+                    }
+                });
+            })),
+        ]);
+
+        await Promise.all([
+            Promise.all(modelsToDelete.map(m => this._deleteModel(m))),
+            Promise.all(modelsToPut.map(m => this._putModel(m))),
+            Promise.all(
+                Object.entries(indexCache)
+                    .map(([constructorName, index]) => this._putIndex(this.models[constructorName], index)),
+            ),
+            Promise.all(
+                Object.entries(searchIndexCache)
+                    .map(([constructorName, index]) => this._putSearchIndex(this.models[constructorName], index)),
+            ),
+        ]);
+    }
+
+    /**
+     * Get the model constructor from a model id
+     * @param {string} modelId
+     * @return {Model.constructor}
+     */
+    getModelConstructorFromId(modelId) {
+        const modelName = modelId.split('/')[0];
+        const constructor = this.models[modelName];
+
+        if (!constructor) throw new ModelNotRegisteredStorageEngineError(modelName, this);
+
+        return constructor;
+    }
+
+    /**
+     * Get model instance that are directly linked to the given model in either direction
+     * @param {Type.Model} model
+     * @param {object} cache
+     * @return {Record<string, Record<string, Type.Model>>}
+     */
+    async getInstancesLinkedTo(model, cache = {}) {
+        return Object.fromEntries(
+            Object.entries(
+                await Promise.all(
+                    Object.entries(this.getLinksFor(model.constructor))
+                        .map(([name, _index]) =>
+                            cache[name] ? Promise.resolve([name, Object.values(cache[name])]) :
+                                this._getIndex(this.models[name])
+                                    .then(i => {
+                                        cache[name] = i;
+                                        return [name, Object.values(i)];
+                                    }),
+                        ),
+                ).then(Object.fromEntries),
+            ).map(([name, index]) => [
+                name,
+                index.map(item => Object.fromEntries(
+                    Object.entries(item)
+                        .filter(([propertyName, property]) => propertyName === 'id' || property?.id === model.id),
+                )).filter(item => Object.keys(item).length > 1),
+            ]),
+        );
+    }
+
+    /**
+     * Get model classes that are directly linked to the given model in either direction
+     * @param {Type.Model.constructor} model
+     * @return {Record<string, Record<string, Type.Model.constructor>>}
+     */
+    getLinksFor(model) {
+        return Object.fromEntries(
+            Object.entries(this.getAllModelLinks())
+                .filter(([modelName, links]) =>
+                    model.name === modelName ||
+                    Object.values(links).some((link) => link.name === model.name),
+                ),
+        );
+    }
+
+    /**
+     * Get all model links
+     * @return {Record<string, Record<string, Type.Model.constructor>>}
+     */
+    getAllModelLinks() {
+        return Object.entries(this.models)
+            .map(([registeredModelName, registeredModelClass]) =>
+                Object.entries(registeredModelClass)
+                    .map(([propertyName, propertyType]) => [
+                        registeredModelName,
+                        propertyName,
+                        typeof propertyType === 'function' &&
+                        !/^class/.test(Function.prototype.toString.call(propertyType)) &&
+                        !Type.Model.isModel(propertyType) ?
+                            propertyType() : propertyType,
+                    ])
+                    .filter(([_m, _p, type]) => Type.Model.isModel(type))
+                    .map(([containingModel, propertyName, propertyType]) => ({
+                        containingModel,
+                        propertyName,
+                        propertyType,
+                    })),
+            )
+            .flat()
+            .reduce((accumulator, {containingModel, propertyName, propertyType}) => ({
+                ...accumulator,
+                [containingModel]: {
+                    ...accumulator[containingModel] || {},
+                    [propertyName]: propertyType,
+                },
+            }), {});
+    }
+
+    /**
+     * Update a model
+     * @param {Model} _model
+     * @throws MethodNotImplementedStorageEngineError
+     * @return Promise<void>
+     */
+    _putModel(_model) {
+        return Promise.reject(new MethodNotImplementedStorageEngineError('_putModel', this));
+    }
+
+    /**
+     * Get a model
+     * @param {string} _id
+     * @throws MethodNotImplementedStorageEngineError
+     * @throws ModelNotFoundStorageEngineError
+     * @return Promise<Model>
+     */
+    _getModel(_id) {
+        return Promise.reject(new MethodNotImplementedStorageEngineError('_getModel', this));
+    }
+
+    /**
+     * Delete a model
+     * @param {string} _id
+     * @throws MethodNotImplementedStorageEngineError
+     * @throws ModelNotFoundStorageEngineError
+     * @return Promise<void>
+     */
+    _deleteModel(_id) {
+        return Promise.reject(new MethodNotImplementedStorageEngineError('_deleteModel', this));
+    }
+
+    /**
+     * Get a model's index data
+     * @param {Model.constructor} _modelConstructor
+     * @throws MethodNotImplementedStorageEngineError
+     * @return Promise<void>
+     */
+    _getIndex(_modelConstructor) {
+        return Promise.reject(new MethodNotImplementedStorageEngineError('_getIndex', this));
+    }
+
+    /**
+     * Put a model's index data
+     * @param {Model.constructor} _modelConstructor
+     * @param {object} _data
+     * @throws MethodNotImplementedStorageEngineError
+     * @return Promise<void>
+     */
+    _putIndex(_modelConstructor, _data) {
+        return Promise.reject(new MethodNotImplementedStorageEngineError('_putIndex', this));
+    }
+
+    /**
+     * Get a model's raw search index data
+     * @param {Model.constructor} _modelConstructor
+     * @throws MethodNotImplementedStorageEngineError
+     * @return Promise<void>
+     */
+    _getSearchIndex(_modelConstructor) {
+        return Promise.reject(new MethodNotImplementedStorageEngineError('_getSearchIndex', this));
+    }
+
+    /**
+     * Get a model's raw search index data
+     * @param {Model.constructor} _modelConstructor
+     * @throws MethodNotImplementedStorageEngineError
+     * @return Promise<void>
+     */
+    _getSearchIndexCompiled(_modelConstructor) {
+        return Promise.reject(new MethodNotImplementedStorageEngineError('_getSearchIndexCompiled', this));
+    }
+
+    /**
+     * Put a model's raw and compiled search index data
+     * @param {Model.constructor} _modelConstructor
+     * @param {object} _data
+     * @throws MethodNotImplementedStorageEngineError
+     * @return Promise<void>
+     */
+    _putSearchIndex(_modelConstructor, _data) {
+        return Promise.reject(new MethodNotImplementedStorageEngineError('_putSearchIndex', this));
+    }
+}
+
+
+/**
+ * Decide if two models indexable fields are different
+ * @param {Type.Model} currentModel
+ * @param {Type.Model} modelToProcess
+ * @return {boolean}
+ * @private
+ */
+function indexedFieldsHaveChanged(currentModel, modelToProcess) {
+    return !currentModel || JSON.stringify(currentModel.toIndexData()) !== JSON.stringify(modelToProcess.toIndexData());
+}
+
+/**
+ * Decide if two models searchable fields have changed
+ * @param {Type.Model} currentModel
+ * @param {Type.Model} modelToProcess
+ * @return {boolean}
+ * @private
+ */
+function searchableFieldsHaveChanged(currentModel, modelToProcess) {
+    return !currentModel || JSON.stringify(currentModel.toSearchData()) !== JSON.stringify(modelToProcess.toSearchData());
+}
+
+/**
+ * @class StorageEngineError
+ * @extends Error
+ */
+export class StorageEngineError extends Error {
+}
+
+/**
+ * @class ModelNotRegisteredStorageEngineError
+ * @extends StorageEngineError
+ */
+export class ModelNotRegisteredStorageEngineError extends StorageEngineError {
+    /**
+     * @param {Type.Model} model
+     * @param {StorageEngine} storageEngine
+     */
+    constructor(model, storageEngine) {
+        const modelName = typeof model === 'string' ? model : model.constructor.name;
+        super(`The model ${modelName} is not registered in the storage engine ${storageEngine.constructor.name}`);
+    }
+}
+
+/**
+ * @class MethodNotImplementedStorageEngineError
+ * @extends StorageEngineError
+ */
+export class MethodNotImplementedStorageEngineError extends StorageEngineError {
+    /**
+     * @param {string} method
+     * @param {StorageEngine} storageEngine
+     */
+    constructor(method, storageEngine) {
+        super(`The method ${method} is not implemented in the storage engine ${storageEngine.constructor.name}`);
+    }
+}
+
+/**
+ * @class ModelNotFoundStorageEngineError
+ * @extends StorageEngineError
+ */
+export class ModelNotFoundStorageEngineError extends StorageEngineError {
+    /**
+     * @param {string} modelId
+     */
+    constructor(modelId) {
+        super(`The model ${modelId} was not found`);
+    }
+}
+
+export class DeleteHasUnintendedConsequencesStorageEngineError extends StorageEngineError {
+    /**
+     * @param {string} modelId
+     * @param {object} consequences
+     */
+    constructor(modelId, consequences) {
+        super(`Deleting ${modelId} has unintended consequences`);
+        this.consequences = consequences;
+    }
+}

package/src/engine/{FileEngine.js → storage/FileStorageEngine.js}

@@ -1,35 +1,35 @@
-import Engine, { EngineError, MissConfiguredError } from './Engine.js';
+import StorageEngine, { EngineError, MissConfiguredError } from './StorageEngine.js';
 import { dirname, join } from 'node:path';
 import fs from 'node:fs/promises';
 
 /**
- * Custom error class for FileEngine-related errors.
+ * Custom error class for FileStorageEngine-related errors.
  * Extends the base `EngineError` class.
  */
-class FileEngineError extends EngineError {}
+class FileStorageEngineError extends EngineError {}
 
 /**
- * Error thrown when writing to a file fails in `FileEngine`.
- * Extends the `FileEngineError` class.
+ * Error thrown when writing to a file fails in `FileStorageEngine`.
+ * Extends the `FileStorageEngineError` class.
  */
-class FailedWriteFileEngineError extends FileEngineError {}
+class FailedWriteFileStorageEngineError extends FileStorageEngineError {}
 
 /**
- * `FileEngine` class extends the base `Engine` class to implement
+ * `FileStorageEngine` class extends the base `StorageEngine` class to implement
  * file system-based storage and retrieval of model data.
  *
- * @class FileEngine
- * @extends Engine
+ * @class FileStorageEngine
+ * @extends StorageEngine
  */
-class FileEngine extends Engine {
+class FileStorageEngine extends StorageEngine {
     /**
-     * Configures the FileEngine with a given configuration object.
+     * Configures the FileStorageEngine with a given configuration object.
      * Adds default `filesystem` configuration if not provided.
      *
-     * @param {Object} configuration - Configuration settings for FileEngine.
+     * @param {Object} configuration - Configuration settings for FileStorageEngine.
      * @param {Object} [configuration.filesystem] - Custom filesystem module (default: Node.js fs/promises).
      * @param {Object} [configuration.path] - The absolute path on the filesystem to write models to.
-     * @returns {FileEngine} A configured instance of FileEngine.
+     * @returns {FileStorageEngine} A configured instance of FileStorageEngine.
      */
     static configure(configuration) {
         if (!configuration.filesystem) {
@@ -39,7 +39,7 @@ class FileEngine extends Engine {
     }
 
     /**
-     * Checks if the FileEngine has been configured correctly.
+     * Checks if the FileStorageEngine has been configured correctly.
      * Ensures that `path` and `filesystem` settings are present.
      *
      * @throws {MissConfiguredError} Throws if required configuration is missing.
@@ -94,7 +94,7 @@ class FileEngine extends Engine {
      * Saves a model to the file system.
      *
      * @param {Model} model - The model to save.
-     * @throws {FailedWriteFileEngineError} Throws if the model cannot be written to the file system.
+     * @throws {FailedWriteFileStorageEngineError} Throws if the model cannot be written to the file system.
      */
     static async putModel(model) {
         const filePath = join(this.configuration.path, `${model.id}.json`);
@@ -102,7 +102,7 @@ class FileEngine extends Engine {
             await this.configuration.filesystem.mkdir(dirname(filePath), { recursive: true });
             await this.configuration.filesystem.writeFile(filePath, JSON.stringify(model.toData()));
         } catch (error) {
-            throw new FailedWriteFileEngineError(`Failed to put file://${filePath}`, error);
+            throw new FailedWriteFileStorageEngineError(`Failed to put file://${filePath}`, error);
         }
     }
 
@@ -110,9 +110,16 @@ class FileEngine extends Engine {
      * Saves the index for multiple models to the file system.
      *
      * @param {Object} index - An object where keys are locations and values are key value pairs of models and their ids.
-     * @throws {FailedWriteFileEngineError} Throws if the index cannot be written to the file system.
+     * @throws {FailedWriteFileStorageEngineError} Throws if the index cannot be written to the file system.
      */
     static async putIndex(index) {
+        /**
+         * Process an index of models
+         * @param {string} location
+         * @param {Array<Model>} models
+         * @throws FailedWriteFileStorageEngineError
+         * @return {Promise<void>}
+         */
         const processIndex = async (location, models) => {
             const filePath = join(this.configuration.path, location, '_index.json');
             const currentIndex = JSON.parse((await this.configuration.filesystem.readFile(filePath).catch(() => '{}')).toString());
@@ -125,7 +132,7 @@ class FileEngine extends Engine {
                     ),
                 }));
             } catch (error) {
-                throw new FailedWriteFileEngineError(`Failed to put file://${filePath}`, error);
+                throw new FailedWriteFileStorageEngineError(`Failed to put file://${filePath}`, error);
             }
         };
 
@@ -175,14 +182,14 @@ class FileEngine extends Engine {
      *
      * @param {Model.constructor} model - The model for which the compiled search index is saved.
      * @param {Object} compiledIndex - The compiled search index to save.
-     * @throws {FailedWriteFileEngineError} Throws if the compiled index cannot be written to the file system.
+     * @throws {FailedWriteFileStorageEngineError} Throws if the compiled index cannot be written to the file system.
      */
     static async putSearchIndexCompiled(model, compiledIndex) {
         const filePath = join(this.configuration.path, model.toString(), '_search_index.json');
         try {
             await this.configuration.filesystem.writeFile(filePath, JSON.stringify(compiledIndex));
         } catch (error) {
-            throw new FailedWriteFileEngineError(`Failed to put file://${filePath}`, error);
+            throw new FailedWriteFileStorageEngineError(`Failed to put file://${filePath}`, error);
         }
     }
 
@@ -191,16 +198,16 @@ class FileEngine extends Engine {
      *
      * @param {Model.constructor} model - The model for which the raw search index is saved.
      * @param {Object} rawIndex - The raw search index to save.
-     * @throws {FailedWriteFileEngineError} Throws if the raw index cannot be written to the file system.
+     * @throws {FailedWriteFileStorageEngineError} Throws if the raw index cannot be written to the file system.
      */
     static async putSearchIndexRaw(model, rawIndex) {
         const filePath = join(this.configuration.path, model.toString(), '_search_index_raw.json');
         try {
             await this.configuration.filesystem.writeFile(filePath, JSON.stringify(rawIndex));
         } catch (error) {
-            throw new FailedWriteFileEngineError(`Failed to put file://${filePath}`, error);
+            throw new FailedWriteFileStorageEngineError(`Failed to put file://${filePath}`, error);
         }
     }
 }
 
-export default FileEngine;
+export default FileStorageEngine;