@acodeninja/persist 2.3.0 → 2.3.2

package/docs/search-queries.md

@@ -0,0 +1,47 @@
+# Search Queries
+
+In addition to [structured queries](./structured-queries.md), persist also supports fuzzy search across fields indexed for search.
+
+## Indexing Data for Search
+
+To set index properties on a model for search, define the static function `searchProperties` as an arrow function that returns an array of fields that should be indexed for search.
+
+Let's consider the following models:
+
+```javascript
+import Persist from "@acodeninja/persist";
+
+export class Person extends Persist.Type.Model {
+    static {
+        this.name = Persist.Type.String.required;
+        this.address = () => Address;
+        this.searchProperties = () => ['name', 'address.address'];
+    }
+}
+
+export class Address extends Persist.Type.Model {
+    static {
+        this.address = Persist.Type.String.required;
+        this.postcode = Persist.Type.String.required;
+        this.searchProperties = () => ['address', 'postcode'];
+    }
+}
+```
+
+Every time a `Person` model is put to a storage engine, the person's name and address are saved to the search index and can be queried.
+
+## Searching
+
+To search for any `Person` who lives on station road, the following search query can be run:
+
+```javascript
+import Persist from "@acodeninja/persist";
+import Person from "./Person";
+import FileEngine from "@acodeninja/persist/engine/file"
+
+FileEngine
+    .configure(configuration)
+    .search(Person, 'station road');
+```
+
+This will find all matches for people who live at any address that includes `station road`.

package/docs/storage-engines.md

@@ -0,0 +1,61 @@
+# Storage Engines
+
+Persist makes several storage engines available for use with the library
+
+## Filesystem Storage Engine
+
+To store models using the local file system, use the `File` storage engine.
+
+```javascript
+import Persist from "@acodeninja/persist";
+import FileEngine from "@acodeninja/persist/engine/file";
+
+Persist.addEngine('local', FileEngine, {
+    path: '/app/storage',
+});
+
+export class Tag extends Persist.Type.Model {
+    static tag = Persist.Type.String.required;
+}
+
+await Persist.getEngine('local', FileEngine).put(new Tag({tag: 'documentation'}));
+```
+
+## HTTP Storage Engine
+
+To store models using an HTTP server, use the `HTTP` storage engine. When using the `HTTP` engine in the browser, refer to [code quirks](./code-quirks.md#using-http-engine-in-browser).
+
+```javascript
+import Persist from "@acodeninja/persist";
+import HTTPEngine from "@acodeninja/persist/engine/http";
+
+Persist.addEngine('remote', HTTPEngine, {
+    host: 'https://api.example.com',
+});
+
+export class Tag extends Persist.Type.Model {
+    static tag = Persist.Type.String.required;
+}
+
+await Persist.getEngine('remote', HTTPEngine).put(new Tag({tag: 'documentation'}));
+```
+
+## S3 Storage Engine
+
+To store models using an S3 Bucket, use the `S3` storage engine. To use the `S3` engine you must also add the `@aws-sdk/client-s3` dependency to your `package.json` file.
+
+```javascript
+import Persist from "@acodeninja/persist";
+import S3Engine from "@acodeninja/persist/engine/s3";
+
+Persist.addEngine('remote', S3Engine, {
+    bucket: 'test-bucket',
+    client: new S3Client(),
+});
+
+export class Tag extends Persist.Type.Model {
+    static tag = Persist.Type.String.required;
+}
+
+await Persist.getEngine('remote', S3Engine).put(new Tag({tag: 'documentation'}));
+```

package/docs/structured-queries.md

@@ -0,0 +1,107 @@
+# Structured Queries
+
+Use structured queries when you need to filter a collection of models using a series of exact and partial matching conditions.
+
+## Indexing Data
+
+To set index properties on a model, define the static function `indexProperties` as an arrow function that returns an array of fields that should be indexed for querying.
+
+Let's consider the following models:
+
+```javascript
+import Persist from "@acodeninja/persist";
+
+export class Person extends Persist.Type.Model {
+    static {
+        this.name = Persist.Type.String.required;
+        this.address = () => Address;
+        this.indexProperties = () => ['name', 'address.postcode'];
+    }
+}
+
+export class Address extends Persist.Type.Model {
+    static {
+        this.address = Persist.Type.String.required;
+        this.postcode = Persist.Type.String.required;
+        this.indexProperties = () => ['postcode'];
+    }
+}
+```
+
+Every time a `Person` model is put to a storage engine, the person's name and address postcode are saved to the index and can be queried.
+
+> [!NOTE]
+> All fields included in the model index will be stored in the same file so be careful not to index fields that contain a lot of data.
+
+## Querying Exact Matches
+
+To query for a `Person` called `Joe Bloggs` an exact query can be written:
+
+```javascript
+import Persist from "@acodeninja/persist";
+import Person from "./Person";
+import FileEngine from "@acodeninja/persist/engine/file"
+
+FileEngine
+    .configure(configuration)
+    .find(Person, {
+        name: {$is: 'Joe Bloggs'},
+    });
+```
+
+## Querying Partial Matches
+
+To query for a `Person` with name `Joe` a contains query can be written:
+
+```javascript
+import Persist from "@acodeninja/persist";
+import Person from "./Person";
+import FileEngine from "@acodeninja/persist/engine/file"
+
+FileEngine
+    .configure(configuration)
+    .find(Person, {
+        name: {$contains: 'Joe'},
+    });
+```
+
+## Querying Combination Matches
+
+To query for a `Person` who lives at `SW1 1AA` a combination of contains and exact queries can be written:
+
+```javascript
+import Persist from "@acodeninja/persist";
+import Person from "./Person";
+import FileEngine from "@acodeninja/persist/engine/file"
+
+FileEngine
+    .configure(configuration)
+    .find(Person, {
+        address: {
+            $contains: {
+                postcode: {$is: 'SW1 1AA'},
+            },
+        },
+    });
+```
+
+## Multiple Queries
+
+To query for anyone called `Joe Bloggs` who lives in the `SW1` postcode area, we can combine queries:
+
+```javascript
+import Persist from "@acodeninja/persist";
+import Person from "./Person";
+import FileEngine from "@acodeninja/persist/engine/file"
+
+FileEngine
+    .configure(configuration)
+    .find(Person, {
+        name: {$is: 'Joe Bloggs'},
+        address: {
+            $contains: {
+                postcode: {$contains: 'SW1'},
+            },
+        },
+    });
+```

package/docs/transactions.md

@@ -0,0 +1,23 @@
+## Transactions
+
+Create transactions to automatically roll back on failure.
+
+```javascript
+import Persist from "@acodeninja/persist";
+import S3Engine from "@acodeninja/persist/engine/s3";
+
+Persist.addEngine('remote', S3Engine, {
+    bucket: 'test-bucket',
+    client: new S3Client(),
+    transactions: true,
+});
+
+export class Tag extends Persist.Type.Model {
+    static tag = Persist.Type.String.required;
+}
+
+const transaction = Persist.getEngine('remote', S3Engine).start();
+
+await transaction.put(new Tag({tag: 'documentation'}));
+await transaction.commit();
+```

package/package.json

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

package/src/Persist.js

@@ -1,4 +1,4 @@
-import Type from '../src/type/index.js';
+import Type from './type/index.js';
 import enableTransactions from './Transactions.js';
 
 /**

package/src/engine/Engine.js

@@ -258,8 +258,10 @@ class Engine {
 
             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);
                 }
             }
@@ -283,15 +285,15 @@ class Engine {
         const hydrateModelList = async (property, modelToProcess, name) => {
             const subModelClass = getSubModelClass(modelToProcess, name, true);
 
-            const newModelList = await Promise.all(property.map(async subModel => {
+            const newModelList = await Promise.all(property.map(subModel => {
                 if (hydratedModels[subModel.id]) {
                     return hydratedModels[subModel.id];
                 }
 
-                return await this.get(subModelClass, subModel.id);
+                return this.get(subModelClass, subModel.id);
             }));
 
-            return await Promise.all(newModelList.map(async subModel => {
+            return Promise.all(newModelList.map(async subModel => {
                 if (hydratedModels[subModel.id]) {
                     return hydratedModels[subModel.id];
                 }
@@ -312,7 +314,7 @@ class Engine {
             return isArray ? constructorField._items : constructorField;
         }
 
-        return await hydrateModel(await this.get(model.constructor, model.id));
+        return hydrateModel(await this.get(model.constructor, model.id));
     }
 
     /**

package/src/engine/HTTPEngine.js

@@ -126,7 +126,7 @@ class HTTPEngine extends Engine {
      *
      * @throws {HTTPRequestFailedError} Thrown if the fetch request fails.
      */
-    static async getById(id) {
+    static getById(id) {
         this.checkConfiguration();
 
         const url = new URL([
@@ -135,7 +135,7 @@ class HTTPEngine extends Engine {
             `${id}.json`,
         ].filter(e => Boolean(e)).join('/'));
 
-        return await this._processFetch(url, this._getReadOptions());
+        return this._processFetch(url, this._getReadOptions());
     }
 
     /**
@@ -177,7 +177,7 @@ class HTTPEngine extends Engine {
                 '_index.json',
             ].filter(e => Boolean(e)).join('/'));
 
-            return await this._processFetch(url, {
+            return this._processFetch(url, {
                 ...this._getWriteOptions(),
                 body: JSON.stringify({
                     ...await this.getIndex(location),
@@ -199,7 +199,7 @@ class HTTPEngine extends Engine {
      * @param {Model.constructor?} model - The model in the host where the index is stored.
      * @returns {Promise<Object>} The index data in JSON format.
      */
-    static async getIndex(model) {
+    static getIndex(model) {
         const url = new URL([
             this.configuration.host,
             this.configuration.prefix,
@@ -207,7 +207,7 @@ class HTTPEngine extends Engine {
             '_index.json',
         ].filter(e => Boolean(e)).join('/'));
 
-        return await this._processFetch(url, this._getReadOptions(), {});
+        return this._processFetch(url, this._getReadOptions(), {});
     }
 
     /**
@@ -216,7 +216,7 @@ class HTTPEngine extends Engine {
      * @param {Model.constructor} model - The model whose compiled search index to retrieve.
      * @returns {Promise<Object>} The compiled search index in JSON format.
      */
-    static async getSearchIndexCompiled(model) {
+    static getSearchIndexCompiled(model) {
         const url = new URL([
             this.configuration.host,
             this.configuration.prefix,
@@ -224,7 +224,7 @@ class HTTPEngine extends Engine {
             '_search_index.json',
         ].join('/'));
 
-        return await this._processFetch(url, this._getReadOptions());
+        return this._processFetch(url, this._getReadOptions());
     }
 
     /**
@@ -233,7 +233,7 @@ class HTTPEngine extends Engine {
      * @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 async getSearchIndexRaw(model) {
+    static getSearchIndexRaw(model) {
         const url = new URL([
             this.configuration.host,
             this.configuration.prefix,
@@ -241,7 +241,7 @@ class HTTPEngine extends Engine {
             '_search_index_raw.json',
         ].join('/'));
 
-        return await this._processFetch(url, this._getReadOptions()).catch(() => ({}));
+        return this._processFetch(url, this._getReadOptions()).catch(() => ({}));
     }
 
     /**
@@ -253,7 +253,7 @@ class HTTPEngine extends Engine {
      *
      * @throws {HTTPRequestFailedError} Thrown if the PUT request fails.
      */
-    static async putSearchIndexCompiled(model, compiledIndex) {
+    static putSearchIndexCompiled(model, compiledIndex) {
         const url = new URL([
             this.configuration.host,
             this.configuration.prefix,
@@ -276,7 +276,7 @@ class HTTPEngine extends Engine {
      *
      * @throws {HTTPRequestFailedError} Thrown if the PUT request fails.
      */
-    static async putSearchIndexRaw(model, rawIndex) {
+    static putSearchIndexRaw(model, rawIndex) {
         const url = new URL([
             this.configuration.host,
             this.configuration.prefix,
@@ -284,7 +284,7 @@ class HTTPEngine extends Engine {
             '_search_index_raw.json',
         ].filter(e => Boolean(e)).join('/'));
 
-        return await this._processFetch(url, {
+        return this._processFetch(url, {
             ...this._getWriteOptions(),
             body: JSON.stringify(rawIndex),
         });

package/src/engine/S3Engine.js

@@ -153,9 +153,9 @@ class S3Engine extends Engine {
      * @param {Model.constructor} model - The model whose search index to retrieve.
      * @returns {Promise<Object>} The compiled search index.
      */
-    static async getSearchIndexCompiled(model) {
-        return await this.configuration.client.send(new GetObjectCommand({
-            Key: [this.configuration.prefix, model.name, '_search_index.json'].join('/'),
+    static getSearchIndexCompiled(model) {
+        return this.configuration.client.send(new GetObjectCommand({
+            Key: [this.configuration.prefix, model.toString(), '_search_index.json'].join('/'),
             Bucket: this.configuration.bucket,
         })).then(data => data.Body.transformToString())
             .then(JSON.parse);
@@ -167,8 +167,8 @@ class S3Engine extends Engine {
      * @param {Model.constructor} model - The model whose raw search index to retrieve.
      * @returns {Promise<Object>} The raw search index, or an empty object if not found.
      */
-    static async getSearchIndexRaw(model) {
-        return await this.configuration.client.send(new GetObjectCommand({
+    static getSearchIndexRaw(model) {
+        return this.configuration.client.send(new GetObjectCommand({
             Key: [this.configuration.prefix, model.toString(), '_search_index_raw.json'].join('/'),
             Bucket: this.configuration.bucket,
         })).then(data => data.Body.transformToString())

package/src/type/Model.js

@@ -40,7 +40,7 @@ class Model {
             }
             if (value?._resolved) {
                 Object.defineProperty(this, key, {
-                    get: function () {
+                    get() {
                         return value.resolve(this);
                     },
                 });
@@ -73,11 +73,11 @@ class Model {
             (key, value) => {
                 if (!simple) {
                     if (this.constructor[key]) {
-                        if (this.constructor[key].name.endsWith('DateType')) {
+                        if (this.constructor[key].name.endsWith('Date')) {
                             return new Date(value);
                         }
 
-                        if (this.constructor[key].name.endsWith('ArrayOf(Date)Type')) {
+                        if (this.constructor[key].name.endsWith('ArrayOf(Date)')) {
                             return value.map(d => new Date(d));
                         }
                     }
@@ -211,12 +211,12 @@ class Model {
         for (const [name, value] of Object.entries(data)) {
             if (this[name]?._resolved) continue;
 
-            if (this[name].name.endsWith('DateType')) {
+            if (this[name].name.endsWith('Date')) {
                 model[name] = new Date(value);
                 continue;
             }
 
-            if (this[name].name.endsWith('ArrayOf(Date)Type')) {
+            if (this[name].name.endsWith('ArrayOf(Date)')) {
                 model[name] = data[name].map(d => new Date(d));
                 continue;
             }
@@ -259,6 +259,26 @@ class Model {
             return false;
         }
     }
+
+    /**
+     * Set the name of the Model class
+     *
+     * Use this when your model might be minified to retain consistent class names.
+     *
+     * @param {string} name
+     * @static
+     *
+     * @example
+     * export default class TestModel {
+     *     static {
+     *         this.string = Persist.Type.String;
+     *         Object.defineProperty(this, 'name', {value: 'TestModel'});
+     *     }
+     * }
+     */
+    static setMinifiedName(name) {
+        Object.defineProperty(this, 'name', {value: name});
+    }
 }
 
 export default Model;

package/src/type/Type.js

@@ -38,12 +38,12 @@ class Type {
     static _schema = undefined;
 
     /**
-     * Converts the class name to a string, removing the "Type" suffix.
+     * Converts the class name to a string
      *
-     * @returns {string} The name of the type without the "Type" suffix.
+     * @returns {string} The name of the type.
      */
     static toString() {
-        return this.name?.replace(/Type$/, '');
+        return this.name;
     }
 
     /**
@@ -58,10 +58,14 @@ class Type {
         }
 
         // Define the class name as "Required<OriginalTypeName>"
-        Object.defineProperty(Required, 'name', {value: `Required${this.toString()}Type`});
+        Object.defineProperty(Required, 'name', {value: `Required${this.toString()}`});
 
         return Required;
     }
+
+    static {
+        Object.defineProperty(this, 'name', {value: 'Type'});
+    }
 }
 
 export default Type;

package/src/type/complex/ArrayType.js

@@ -66,17 +66,17 @@ class ArrayType {
                      * @returns {string} The string representation of the required array type.
                      */
                     static toString() {
-                        return `RequiredArrayOf(${type})`;
+                        return `RequiredArrayOf(${type.toString()})`;
                     }
                 }
 
-                Object.defineProperty(Required, 'name', {value: `Required${this.toString()}Type`});
+                Object.defineProperty(Required, 'name', {value: `Required${this.toString()}`});
 
                 return Required;
             }
         }
 
-        Object.defineProperty(ArrayOf, 'name', {value: `${ArrayOf.toString()}Type`});
+        Object.defineProperty(ArrayOf, 'name', {value: ArrayOf.toString()});
 
         return ArrayOf;
     }

package/src/type/complex/CustomType.js

@@ -35,15 +35,23 @@ class CustomType {
          * Represents a custom type defined by a JSON schema.
          */
         class Custom extends Type {
-            /** @type {string} The data type, which is 'object' */
-            static _type = 'object';
+            static {
+                /** @type {string} The data type, which is 'object' */
+                this._type = 'object';
 
-            /** @type {Object} The JSON schema that defines the structure and validation rules */
-            static _schema = schema;
+                /** @type {Object} The JSON schema that defines the structure and validation rules */
+                this._schema = schema;
+
+                Object.defineProperty(this, 'name', {value: 'Custom'});
+            }
         }
 
         return Custom;
     }
+
+    static {
+        Object.defineProperty(this, 'name', {value: 'Custom'});
+    }
 }
 
 export default CustomType;

package/src/type/resolved/SlugType.js

@@ -53,12 +53,20 @@ class SlugType extends ResolvedType {
 
                 return slugify(model?.[property], {
                     lower: true,
+                    strict: true,
+                    trim: true,
                 });
             }
         }
 
+        Object.defineProperty(SlugOf, 'name', {value: `SlugOf(${property})`});
+
         return SlugOf;
     }
+
+    static {
+        Object.defineProperty(this, 'name', {value: 'Slug'});
+    }
 }
 
 export default SlugType;

package/src/type/simple/BooleanType.js

@@ -10,11 +10,15 @@ import SimpleType from './SimpleType.js';
  * @extends SimpleType
  */
 class BooleanType extends SimpleType {
-    /**
-     * @static
-     * @property {string} _type - The type identifier for BooleanType, set to `'boolean'`.
-     */
-    static _type = 'boolean';
+    static {
+        /**
+         * @static
+         * @property {string} _type - The type identifier for BooleanType, set to `'boolean'`.
+         */
+        this._type = 'boolean';
+
+        Object.defineProperty(this, 'name', {value: 'Boolean'});
+    }
 }
 
 export default BooleanType;

package/src/type/simple/DateType.js

@@ -10,17 +10,21 @@ import SimpleType from './SimpleType.js';
  * @extends SimpleType
  */
 class DateType extends SimpleType {
-    /**
-     * @static
-     * @property {string} _type - The type identifier for DateType, set to `'string'`.
-     */
-    static _type = 'string';
+    static {
+        /**
+         * @static
+         * @property {string} _type - The type identifier for DateType, set to `'string'`.
+         */
+        this._type = 'string';
 
-    /**
-     * @static
-     * @property {string} _format - The format for DateType, set to `'iso-date-time'`.
-     */
-    static _format = 'iso-date-time';
+        /**
+         * @static
+         * @property {string} _format - The format for DateType, set to `'iso-date-time'`.
+         */
+        this._format = 'iso-date-time';
+
+        Object.defineProperty(this, 'name', {value: 'Date'});
+    }
 
     /**
      * Checks if the given value is a valid date.

package/src/type/simple/NumberType.js

@@ -10,11 +10,15 @@ import SimpleType from './SimpleType.js';
  * @extends SimpleType
  */
 class NumberType extends SimpleType {
-    /**
-     * @static
-     * @property {string} _type - The type identifier for NumberType, set to `'number'`.
-     */
-    static _type = 'number';
+    static {
+        /**
+         * @static
+         * @property {string} _type - The type identifier for NumberType, set to `'number'`.
+         */
+        this._type = 'number';
+
+        Object.defineProperty(this, 'name', {value: 'Number'});
+    }
 }
 
 export default NumberType;