@acodeninja/persist 3.0.0-next.2 → 3.0.0-next.20

package/src/{type/resolved → data/properties}/ResolvedType.js

@@ -1,4 +1,4 @@
-import Type from '../Type.js';
+import Type from './Type.js';
 
 /**
  * Class representing a resolved type.
@@ -39,6 +39,7 @@ class ResolvedType extends Type {
      * @returns {ResolvedType} A subclass of `ResolvedType` customized for the provided property.
      */
     static of(property) {
+        const that = this;
         class ResolvedTypeOf extends ResolvedType {
             /**
              * Converts the resolved type to a string, displaying the resolved property.
@@ -46,7 +47,7 @@ class ResolvedType extends Type {
              * @returns {string} A string representing the resolved type, including the property.
              */
             static toString() {
-                return `ResolvedTypeOf(${property})`;
+                return `${that.toString()}Of(${property})`;
             }
         }
 

package/src/{type/simple → data/properties}/StringType.js

@@ -1,4 +1,4 @@
-import Type from '../Type.js';
+import Type from './Type.js';
 
 /**
  * Class representing a string type.

package/src/{type → data/properties}/Type.js

@@ -53,6 +53,14 @@ class Type {
      * @returns {Type} A subclass of the current type with `_required` set to `true`.
      */
     static get required() {
+        /**
+         * A subclass of the current type with the `_required` flag set to `true`.
+         * Used to indicate that the property is required during validation or schema generation.
+         *
+         * @class
+         * @extends {Type}
+         * @private
+         */
         class Required extends this {
             static _required = true;
         }

package/src/engine/storage/HTTPStorageEngine.js

@@ -1,69 +1,130 @@
-import StorageEngine, {EngineError, MissConfiguredError} from './StorageEngine.js';
-
-/**
- * Represents an error specific to HTTP engine operations.
- * @class HTTPStorageEngineError
- * @extends EngineError
- */
-export class HTTPStorageEngineError extends EngineError {}
-
-/**
- * Error indicating a failed HTTP request.
- * @class HTTPRequestFailedError
- * @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 HTTPStorageEngineError {
-    constructor(url, options, response) {
-        const method = options.method?.toLowerCase() || 'get';
-        super(`Failed to ${method} ${url}`);
-        this.response = response;
-        this.url = url;
-        this.options = options;
-    }
-}
-
-/**
- * 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 HTTPStorageEngine
- * @extends StorageEngine
- */
-class HTTPStorageEngine extends StorageEngine {
+import StorageEngine, {
+    MisconfiguredStorageEngineError, ModelNotFoundStorageEngineError, StorageEngineError,
+} from './StorageEngine.js';
 
+export default class HTTPStorageEngine extends StorageEngine {
     /**
-     * Configures the HTTP engine with additional fetch options.
-     * Sets the Accept header to 'application/json' by default.
-     *
      * @param {Object} configuration - Configuration object containing fetch options and other settings.
-     * @param {string} [configuration.host] - Hostname and protocol of the HTTP service to use (ie: https://example.com).
+     * @param {string} [configuration.baseURL] - Hostname and protocol of the HTTP service to use (ie: https://example.com).
      * @param {string?} [configuration.prefix] - The prefix on the host to perform operations against.
-     * @param {Object} [configuration.fetchOptions] - Fetch overrides to attach to all requests sent to the HTTP service.
-     * @returns {Object} The configured settings for the HTTP engine.
+     * @param {Object?} [configuration.fetchOptions] - Fetch overrides to attach to all requests sent to the HTTP service.
+     * @param {fetch} [configuration.fetch] - The http client that implements fetch.
+     * @param {Array<Model.constructor>} models
      */
-    static configure(configuration = {}) {
-        configuration.fetchOptions = {
+    constructor(configuration, models) {
+        super(configuration, models);
+        if (!this.configuration?.baseURL || !this.configuration?.fetch)
+            throw new MisconfiguredStorageEngineError('both baseURL and fetch must be provided', this);
+
+        this.configuration.fetchOptions = {
             ...(configuration.fetchOptions ?? {}),
             headers: {
                 ...(configuration.fetchOptions?.headers ?? {}),
                 Accept: 'application/json',
             },
         };
+    }
 
-        return super.configure(configuration);
+    /**
+     * Get a model
+     * @param {string} id
+     * @throws ModelNotFoundStorageEngineError
+     * @return Promise<Model>
+     */
+    getModel(id) {
+        return this.#processFetch(this.#generateURL([id]), this.#getReadOptions())
+            .catch(error => {
+                if (error.response.status === 404) {
+                    throw new ModelNotFoundStorageEngineError(id);
+                }
+                throw error;
+            });
     }
 
     /**
-     * Validates the engine's configuration, ensuring that the host is defined.
-     *
-     * @throws {MissConfiguredError} Thrown if the configuration is missing a host.
+     * Update a model
+     * @param {object} model
+     * @throws HTTPRequestFailedError
+     * @return Promise<void>
      */
-    static checkConfiguration() {
-        if (!this.configuration?.host) throw new MissConfiguredError(this.configuration);
+    putModel(model) {
+        return this.#processFetch(this.#generateURL([model.id]), {
+            ...this.#getWriteOptions(),
+            body: JSON.stringify(model),
+        });
+    }
+
+    /**
+     * Delete a model
+     * @param {string} id
+     * @throws HTTPRequestFailedError
+     * @return Promise<void>
+     */
+    deleteModel(id) {
+        return this.#processFetch(this.#generateURL([id]), {
+            ...this.#getReadOptions(),
+            method: 'DELETE',
+        }).catch(error => {
+            if (error.response.status === 404) {
+                throw new ModelNotFoundStorageEngineError(id);
+            }
+            throw error;
+        });
+    }
+
+    /**
+     * Get a model's index data
+     * @param {Model.constructor} modelConstructor
+     * @return Promise<void>
+     */
+    getIndex(modelConstructor) {
+        return this.#processFetch(
+            this.#generateURL([modelConstructor.name]),
+            this.#getReadOptions(),
+            {},
+        );
+    }
+
+    /**
+     * Put a model's index data
+     * @param {Model.constructor} modelConstructor
+     * @param {object} index
+     * @throws MethodNotImplementedStorageEngineError
+     * @return Promise<void>
+     */
+    putIndex(modelConstructor, index) {
+        return this.#processFetch(this.#generateURL([modelConstructor.name]), {
+            ...this.#getWriteOptions(),
+            body: JSON.stringify(index),
+        });
+    }
+
+    /**
+     * Get a model's raw search index data
+     * @param {Model.constructor} modelConstructor
+     * @throws MethodNotImplementedStorageEngineError
+     * @return Promise<object>
+     */
+    getSearchIndex(modelConstructor) {
+        return this.#processFetch(
+            this.#generateURL([modelConstructor.name, 'search']),
+            this.#getReadOptions(),
+            {},
+        );
+    }
+
+    /**
+     * Put a model's raw and compiled search index data
+     * @param {Model.constructor} modelConstructor
+     * @param {Record<string, object>} index
+     * @throws MethodNotImplementedStorageEngineError
+     * @return Promise<void>
+     */
+    putSearchIndex(modelConstructor, index) {
+        return this.#processFetch(this.#generateURL([modelConstructor.name, 'search']), {
+            ...this.#getWriteOptions(),
+            body: JSON.stringify(index),
+        });
     }
 
     /**
@@ -71,7 +132,7 @@ class HTTPStorageEngine extends StorageEngine {
      *
      * @returns {Object} The fetch options for reading.
      */
-    static _getReadOptions() {
+    #getReadOptions() {
         return this.configuration.fetchOptions;
     }
 
@@ -81,11 +142,11 @@ class HTTPStorageEngine extends StorageEngine {
      *
      * @returns {Object} The fetch options for writing.
      */
-    static _getWriteOptions() {
+    #getWriteOptions() {
         return {
-            ...this._getReadOptions(),
+            ...this.#getReadOptions(),
             headers: {
-                ...this._getReadOptions().headers,
+                ...this.#getReadOptions().headers,
                 'Content-Type': 'application/json',
             },
             method: 'PUT',
@@ -99,10 +160,9 @@ class HTTPStorageEngine extends StorageEngine {
      * @param {Object} options - The fetch options.
      * @param {*} [defaultValue] - A default value to return if the fetch fails.
      * @returns {Promise<Object>} The parsed JSON response.
-     *
      * @throws {HTTPRequestFailedError} Thrown if the fetch request fails.
      */
-    static _processFetch(url, options, defaultValue = undefined) {
+    #processFetch(url, options, defaultValue = undefined) {
         return this.configuration.fetch(url, options)
             .then(response => {
                 if (!response.ok) {
@@ -119,206 +179,42 @@ class HTTPStorageEngine extends StorageEngine {
     }
 
     /**
-     * Retrieves an object by its ID from the server.
-     *
-     * @param {string} id - The ID of the object to retrieve.
-     * @returns {Promise<Object>} The retrieved object in JSON format.
-     *
-     * @throws {HTTPRequestFailedError} Thrown if the fetch request fails.
-     */
-    static getById(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());
-    }
-
-    /**
-     * 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.
+     * Creates a URL object based on the input path
+     * @param {Array<string>} input
+     * @return {module:url.URL}
      */
-    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.
-     *
-     * @param {Model} model - The model object to upload.
-     * @returns {Promise<Object>} The response from the server.
-     *
-     * @throws {HTTPRequestFailedError} Thrown if the PUT request fails.
-     */
-    static putModel(model) {
-        const url = new URL([
-            this.configuration.host,
-            this.configuration.prefix,
-            `${model.id}.json`,
-        ].filter(e => Boolean(e)).join('/'));
-
-        return this._processFetch(url, {
-            ...this._getWriteOptions(),
-            body: JSON.stringify(model.toData()),
-        });
-    }
-
-    /**
-     * Uploads (puts) an index object to the server.
-     *
-     * @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) {
-        /**
-         * 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,
-                this.configuration.prefix,
-                location,
-                '_index.json',
-            ].filter(e => Boolean(e)).join('/'));
-
-            return this._processFetch(url, {
-                ...this._getWriteOptions(),
-                body: JSON.stringify({
-                    ...await this.getIndex(location),
-                    ...Object.fromEntries(
-                        Object.entries(models).map(([k, v]) => [k, v?.toIndexData?.() || v]),
-                    ),
-                }),
-            });
-        };
-
-        for (const [location, models] of Object.entries(index)) {
-            await processIndex(location, models);
-        }
-
-        await processIndex(null, Object.values(index).reduce((accumulator, currentValue) => {
-            Object.keys(currentValue).forEach(key => {
-                accumulator[key] = currentValue[key];
-            });
-            return accumulator;
-        }, {}));
-    }
-
-    /**
-     * Retrieves the index object from the server for the specified location.
-     *
-     * @param {Model.constructor?} model - The model in the host where the index is stored.
-     * @returns {Promise<Object>} The index data in JSON format.
-     */
-    static getIndex(model) {
-        const url = new URL([
-            this.configuration.host,
-            this.configuration.prefix,
-            model?.toString(),
-            '_index.json',
-        ].filter(e => Boolean(e)).join('/'));
-
-        return this._processFetch(url, this._getReadOptions(), {});
-    }
-
-    /**
-     * Retrieves the compiled search index for a model from the server.
-     *
-     * @param {Model.constructor} model - The model whose compiled search index to retrieve.
-     * @returns {Promise<Object>} The compiled search index in JSON format.
-     */
-    static getSearchIndexCompiled(model) {
-        const url = new URL([
-            this.configuration.host,
-            this.configuration.prefix,
-            model.toString(),
-            '_search_index.json',
-        ].join('/'));
-
-        return this._processFetch(url, this._getReadOptions());
-    }
-
-    /**
-     * Retrieves the raw (uncompiled) search index for a model from the server.
-     *
-     * @param {Model.constructor} model - The model whose raw search index to retrieve.
-     * @returns {Promise<Object>} The raw search index in JSON format, or an empty object if not found.
-     */
-    static getSearchIndexRaw(model) {
-        const url = new URL([
-            this.configuration.host,
-            this.configuration.prefix,
-            model.toString(),
-            '_search_index_raw.json',
-        ].join('/'));
-
-        return this._processFetch(url, this._getReadOptions()).catch(() => ({}));
-    }
-
-    /**
-     * Uploads (puts) a compiled search index for a model to the server.
-     *
-     * @param {Model.constructor} model - The model whose compiled search index to upload.
-     * @param {Object} compiledIndex - The compiled search index data.
-     * @returns {Promise<Object>} The response from the server.
-     *
-     * @throws {HTTPRequestFailedError} Thrown if the PUT request fails.
-     */
-    static putSearchIndexCompiled(model, compiledIndex) {
-        const url = new URL([
-            this.configuration.host,
-            this.configuration.prefix,
-            model.toString(),
-            '_search_index.json',
-        ].filter(e => Boolean(e)).join('/'));
-
-        return this._processFetch(url, {
-            ...this._getWriteOptions(),
-            body: JSON.stringify(compiledIndex),
-        });
+    #generateURL(input) {
+        return new URL(
+            [this.configuration.baseURL, this.configuration.prefix]
+                .concat(input)
+                .filter(Boolean)
+                .join('/'),
+        );
     }
+}
 
-    /**
-     * Uploads (puts) a raw search index for a model to the server.
-     *
-     * @param {Model.constructor} model - The model whose raw search index to upload.
-     * @param {Object} rawIndex - The raw search index data.
-     * @returns {Promise<Object>} The response from the server.
-     *
-     * @throws {HTTPRequestFailedError} Thrown if the PUT request fails.
-     */
-    static putSearchIndexRaw(model, rawIndex) {
-        const url = new URL([
-            this.configuration.host,
-            this.configuration.prefix,
-            model.toString(),
-            '_search_index_raw.json',
-        ].filter(e => Boolean(e)).join('/'));
+/**
+ * Represents an error specific to HTTP engine operations.
+ * @class HTTPStorageEngineError
+ * @extends StorageEngineError
+ */
+export class HTTPStorageEngineError extends StorageEngineError {}
 
-        return this._processFetch(url, {
-            ...this._getWriteOptions(),
-            body: JSON.stringify(rawIndex),
-        });
+/**
+ * Error indicating a failed HTTP request.
+ * @class HTTPRequestFailedError
+ * @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 HTTPStorageEngineError {
+    constructor(url, options, response) {
+        const method = options.method?.toLowerCase() || 'get';
+        super(`Failed to ${method} ${url}`);
+        this.response = response;
+        this.url = url;
+        this.options = options;
     }
 }
-
-export default HTTPStorageEngine;