@acodeninja/persist 2.3.2 → 2.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@acodeninja/persist",
-  "version": "2.3.2",
+  "version": "2.4.0",
   "description": "A JSON based data modelling and persistence module with alternate storage mechanisms.",
   "type": "module",
   "scripts": {

package/src/engine/Engine.js

@@ -24,6 +24,18 @@ class Engine {
         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()`));
+    }
+
     /**
      * Saves a model to the data store. This method must be implemented by subclasses.
      *
@@ -181,7 +193,10 @@ class Engine {
                 await this.putModel(m);
 
                 uploadedModels.push(m.id);
-                indexUpdates[m.constructor.name] = (indexUpdates[m.constructor.name] ?? []).concat([m]);
+                indexUpdates[m.constructor.name] = {
+                    ...indexUpdates[m.constructor.name] || {},
+                    [m.id]: m,
+                };
 
                 if (m.constructor.searchProperties().length > 0) {
                     const rawSearchIndex = {
@@ -243,6 +258,127 @@ class Engine {
         }
     }
 
+    /**
+     * 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.
      *
@@ -389,6 +525,19 @@ export class NotFoundEngineError extends EngineError {
      */
 }
 
+/**
+ * Represents an error that occurs when a requested resource or item cannot be deleted by the engine.
+ * Extends the `EngineError` class.
+ */
+export class CannotDeleteEngineError extends EngineError {
+    /**
+     * Creates an instance of `CannotDeleteEngineError`.
+     *
+     * @param {string} message - The error message.
+     * @param {Error} [error] - An optional underlying error that caused this error.
+     */
+}
+
 /**
  * Represents an error indicating that a certain method or functionality is not implemented in the engine.
  * Extends the `EngineError` class.

package/src/engine/FileEngine.js

@@ -64,6 +64,17 @@ class FileEngine extends Engine {
             .then(JSON.parse);
     }
 
+    /**
+     * Deletes a model by its ID from the file system.
+     *
+     * @param {string} id - The ID of the model to delete.
+     * @returns {Promise<void>} Resolves when the model has been deleted.
+     * @throws {Error} Throws if the file cannot be deleted.
+     */
+    static deleteById(id) {
+        return this.configuration.filesystem.rm(join(this.configuration.path, `${id}.json`));
+    }
+
     /**
      * Retrieves the index for a given model from the file system.
      *
@@ -98,19 +109,20 @@ 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 arrays of models.
+     * @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.
      */
     static async putIndex(index) {
         const processIndex = async (location, models) => {
-            const modelIndex = Object.fromEntries(models.map((m) => [m.id, m.toIndexData()]));
             const filePath = join(this.configuration.path, location, '_index.json');
             const currentIndex = JSON.parse((await this.configuration.filesystem.readFile(filePath).catch(() => '{}')).toString());
 
             try {
                 await this.configuration.filesystem.writeFile(filePath, JSON.stringify({
                     ...currentIndex,
-                    ...modelIndex,
+                    ...Object.fromEntries(
+                        Object.entries(models).map(([k, v]) => [k, v?.toIndexData?.() || v]),
+                    ),
                 }));
             } catch (error) {
                 throw new FailedWriteFileEngineError(`Failed to put file://${filePath}`, error);
@@ -121,7 +133,12 @@ class FileEngine extends Engine {
             await processIndex(location, models);
         }
 
-        await processIndex('', Object.values(index).flat());
+        await processIndex('', Object.values(index).reduce((accumulator, currentValue) => {
+            Object.keys(currentValue).forEach(key => {
+                accumulator[key] = currentValue[key];
+            });
+            return accumulator;
+        }, {}));
     }
 
     /**

package/src/engine/HTTPEngine.js

@@ -138,6 +138,25 @@ class HTTPEngine extends Engine {
         return this._processFetch(url, this._getReadOptions());
     }
 
+    /**
+     * Deletes a model by its ID from an HTTP server.
+     *
+     * @param {string} id - The ID of the model to delete.
+     * @returns {Promise<void>} Resolves when the model has been deleted.
+     * @throws {Error} Throws if the file cannot be deleted.
+     */
+    static deleteById(id) {
+        this.checkConfiguration();
+
+        const url = new URL([
+            this.configuration.host,
+            this.configuration.prefix,
+            `${id}.json`,
+        ].filter(e => Boolean(e)).join('/'));
+
+        return this._processFetch(url, {...this._getReadOptions(), method: 'DELETE'});
+    }
+
     /**
      * Uploads (puts) a model object to the server.
      *
@@ -162,14 +181,12 @@ class HTTPEngine extends Engine {
     /**
      * Uploads (puts) an index object to the server.
      *
-     * @param {Object} index - The index data to upload, organized by location.
+     * @param {Object} index - An object where keys are locations and values are key value pairs of models and their ids.
      * @returns {Promise<void>}
-     *
      * @throws {HTTPRequestFailedError} Thrown if the PUT request fails.
      */
     static async putIndex(index) {
         const processIndex = async (location, models) => {
-            const modelIndex = Object.fromEntries(models.map(m => [m.id, m.toIndexData()]));
             const url = new URL([
                 this.configuration.host,
                 this.configuration.prefix,
@@ -181,7 +198,9 @@ class HTTPEngine extends Engine {
                 ...this._getWriteOptions(),
                 body: JSON.stringify({
                     ...await this.getIndex(location),
-                    ...modelIndex,
+                    ...Object.fromEntries(
+                        Object.entries(models).map(([k, v]) => [k, v?.toIndexData?.() || v]),
+                    ),
                 }),
             });
         };
@@ -190,7 +209,12 @@ class HTTPEngine extends Engine {
             await processIndex(location, models);
         }
 
-        await processIndex(null, Object.values(index).flat());
+        await processIndex(null, Object.values(index).reduce((accumulator, currentValue) => {
+            Object.keys(currentValue).forEach(key => {
+                accumulator[key] = currentValue[key];
+            });
+            return accumulator;
+        }, {}));
     }
 
     /**

package/src/engine/S3Engine.js

@@ -1,5 +1,5 @@
+import {DeleteObjectCommand, GetObjectCommand, PutObjectCommand} from '@aws-sdk/client-s3';
 import Engine, {EngineError, MissConfiguredError} from './Engine.js';
-import {GetObjectCommand, PutObjectCommand} from '@aws-sdk/client-s3';
 
 /**
  * Represents an error specific to the S3 engine operations.
@@ -68,6 +68,24 @@ class S3Engine extends Engine {
         return JSON.parse(await data.Body.transformToString());
     }
 
+    /**
+     * Deletes a model by its ID from theS3 bucket.
+     *
+     * @param {string} id - The ID of the model to delete.
+     * @returns {Promise<void>} Resolves when the model has been deleted.
+     * @throws {Error} Throws if the model cannot be deleted.
+     */
+    static async deleteById(id) {
+        const objectPath = [this.configuration.prefix, `${id}.json`].join('/');
+
+        await this.configuration.client.send(new DeleteObjectCommand({
+            Bucket: this.configuration.bucket,
+            Key: objectPath,
+        }));
+
+        return undefined;
+    }
+
     /**
      * Puts (uploads) a model object to S3.
      *
@@ -113,16 +131,13 @@ class S3Engine extends Engine {
     /**
      * Puts (uploads) an index object to S3.
      *
-     * @param {Object} index - The index data to upload, organized by location.
+     * @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.
      */
     static async putIndex(index) {
         const processIndex = async (location, models) => {
-            const modelIndex = Object.fromEntries(models.map(m => [m.id, m.toIndexData()]));
             const Key = [this.configuration.prefix, location, '_index.json'].filter(e => Boolean(e)).join('/');
-
             const currentIndex = await this.getIndex(location);
 
             try {
@@ -132,7 +147,9 @@ class S3Engine extends Engine {
                     ContentType: 'application/json',
                     Body: JSON.stringify({
                         ...currentIndex,
-                        ...modelIndex,
+                        ...Object.fromEntries(
+                            Object.entries(models).map(([k, v]) => [k, v?.toIndexData?.() || v]),
+                        ),
                     }),
                 }));
             } catch (error) {
@@ -144,7 +161,12 @@ class S3Engine extends Engine {
             await processIndex(location, models);
         }
 
-        await processIndex(null, Object.values(index).flat());
+        await processIndex(null, Object.values(index).reduce((accumulator, currentValue) => {
+            Object.keys(currentValue).forEach(key => {
+                accumulator[key] = currentValue[key];
+            });
+            return accumulator;
+        }, {}));
     }
 
     /**