@acodeninja/persist 2.2.3 → 2.3.1

package/README.md

@@ -1,243 +1,29 @@
 # @acodeninja/persist
 
-A JSON based data modelling and persistence library with alternate storage mechanisms.
+A JSON based data modelling and persistence library with alternate storage mechanisms, designed with static site generation in mind.
 
-## Models
+![NPM Version](https://img.shields.io/npm/v/%40acodeninja%2Fpersist)
+![NPM Unpacked Size](https://img.shields.io/npm/unpacked-size/%40acodeninja%2Fpersist)
+![GitHub top language](https://img.shields.io/github/languages/top/acodeninja/persist)
+![NPM Downloads](https://img.shields.io/npm/dw/%40acodeninja%2Fpersist)
 
-The `Model` and `Type` classes allow creating representations of data objects
+[![DeepSource](https://app.deepsource.com/gh/acodeninja/persist.svg/?label=active+issues&show_trend=true&token=Vd8_PJuRwwoq4_uBJ0_ymc06)](https://app.deepsource.com/gh/acodeninja/persist/)
+[![DeepSource](https://app.deepsource.com/gh/acodeninja/persist.svg/?label=code+coverage&show_trend=true&token=Vd8_PJuRwwoq4_uBJ0_ymc06)](https://app.deepsource.com/gh/acodeninja/persist/)
 
-### Defining Models
+## Features
 
-##### A model using all available basic types
+- Data modelling with relationships
+- Data validation
+- Data querying
+- Fuzzy search
+- Storage with: S3, HTTP and Filesystem
 
-```javascript
-import Persist from "@acodeninja/persist";
+## Find out more
 
-export class SimpleModel extends Persist.Type.Model {
-    static boolean = Persist.Type.Boolean;
-    static string = Persist.Type.String;
-    static number = Persist.Type.Number;
-    static date = Persist.Type.Date;
-}
-```
-
-##### A simple model using required types
-
-```javascript
-import Persist from "@acodeninja/persist";
-
-export class SimpleModel extends Persist.Type.Model {
-    static requiredBoolean = Persist.Type.Boolean.required;
-    static requiredString = Persist.Type.String.required;
-    static requiredNumber = Persist.Type.Number.required;
-    static requiredDate = Persist.Type.Date.required;
-}
-```
-
-##### A simple model using arrays of basic types
-
-```javascript
-import Persist from "@acodeninja/persist";
-
-export class SimpleModel extends Persist.Type.Model {
-    static arrayOfBooleans = Persist.Type.Array.of(Type.Boolean);
-    static arrayOfStrings = Persist.Type.Array.of(Type.String);
-    static arrayOfNumbers = Persist.Type.Array.of(Type.Number);
-    static arrayOfDates = Persist.Type.Array.of(Type.Date);
-    static requiredArrayOfBooleans = Persist.Type.Array.of(Type.Boolean).required;
-    static requiredArrayOfStrings = Persist.Type.Array.of(Type.String).required;
-    static requiredArrayOfNumbers = Persist.Type.Array.of(Type.Number).required;
-    static requiredArrayOfDates = Persist.Type.Array.of(Type.Date).required;
-}
-```
-
-<details>
-  <summary>Complex relationships are also supported</summary>
-
-#### One-to-One Relationships
-
-##### A one-to-one relationship
-
-```javascript
-import Persist from "@acodeninja/persist";
-
-export class ModelB extends Persist.Type.Model {
-}
-
-export class ModelA extends Persist.Type.Model {
-    static linked = ModelB;
-}
-```
-
-##### A circular one-to-one relationship
-
-```javascript
-import Persist from "@acodeninja/persist";
-
-export class ModelA extends Persist.Type.Model {
-    static linked = () => ModelB;
-}
-
-export class ModelB extends Persist.Type.Model {
-    static linked = ModelA;
-}
-```
-
-#### One-to-Many Relationships
-
-##### A one-to-many relationship
-
-```javascript
-import Persist from "@acodeninja/persist";
-
-export class ModelB extends Persist.Type.Model {
-}
-
-export class ModelA extends Persist.Type.Model {
-    static linked = Persist.Type.Array.of(ModelB);
-}
-```
-
-##### A circular one-to-many relationship
-
-```javascript
-import Persist from "@acodeninja/persist";
-
-export class ModelA extends Persist.Type.Model {
-    static linked = () => Type.Array.of(ModelB);
-}
-
-export class ModelB extends Persist.Type.Model {
-    static linked = ModelA;
-}
-```
-
-#### Many-to-Many Relationships
-
-##### A many-to-many relationship
-
-```javascript
-import Persist from "@acodeninja/persist";
-
-export class ModelA extends Persist.Type.Model {
-    static linked = Persist.Type.Array.of(ModelB);
-}
-
-export class ModelB extends Persist.Type.Model {
-    static linked = Persist.Type.Array.of(ModelA);
-}
-```
-</details>
-
-## Find and Search
-
-Models may expose a `searchProperties()` and `indexProperties()` static method to indicate which 
-fields should be indexed for storage engine `find()` and `search()` methods.
-
-Use `find()` for a low usage exact string match on any indexed attribute of a model.
-
-Use `search()` for a medium usage fuzzy string match on any search indexed attribute of a model.
-
-```javascript
-import Persist from "@acodeninja/persist";
-import FileEngine from "@acodeninja/persist/engine/file";
-
-export class Tag extends Persist.Type.Model {
-    static tag = Persist.Type.String.required;
-    static description = Persist.Type.String;
-    static searchProperties = () => ['tag', 'description'];
-    static indexProperties = () => ['tag'];
-}
-
-const tag = new Tag({tag: 'documentation', description: 'How to use the persist library'});
-
-await FileEngine.find(Tag, {tag: 'documentation'});
-// [Tag {tag: 'documentation', description: 'How to use the persist library'}]
-
-await FileEngine.search(Tag, 'how to');
-// [Tag {tag: 'documentation', description: 'How to use the persist library'}]
-```
-
-## Storage
-
-### 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 S3 Bucket, use the `S3` storage engine.
-
-```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.
-
-```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'}));
-```
-
-## Transactions
-
-Create transactions to automatically roll back on failure to update.
-
-```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();
-```
+- [Model Property Types](./docs/model-property-types.md)
+- [Models as Properties](./docs/models-as-properties.md)
+- [Structured Queries](./docs/structured-queries.md)
+- [Search Queries](./docs/search-queries.md)
+- [Storage Engines](./docs/storage-engines.md)
+- [Transactions](./docs/transactions.md)
+- [Quirks](./docs/code-quirks.md)

package/docs/code-quirks.md

@@ -0,0 +1,71 @@
+# Code Quirks
+
+When using Persist in a minified or bundled codebase, it's important to be aware of two key quirks: handling class names during minification and managing reference errors when working with model relationships.
+
+## Class Names and Minification
+
+When you bundle or minify JavaScript code for production, class names are often altered, which can cause issues. Specifically, models may lose their original class names, which we rely on for storing data in the correct namespace.
+
+To avoid this problem, you have two options:
+
+1. Disable class name mangling in your minifier.
+2. Use `this.setMinifiedName(name)` to manually specify the model's name.
+
+```javascript
+import Persist from "@acodeninja/persist";
+
+export class Person extends Persist.Type.Model {
+    static {
+        this.setMinifiedName('Person');
+        this.name = Persist.Type.String.required;
+    }
+}
+```
+
+If you don't set the minified name, the wrong namespace may be used when saving models, leading to unexpected behavior.
+
+## Reference Errors
+
+When defining relationships between models, especially circular relationships (e.g., `Person` references `Address`, and `Address` references `Person`), the order of declarations matters. If the models are referenced before they are initialized, you'll encounter `ReferenceError` messages, like:
+
+```console
+ReferenceError: Cannot access 'Address' before initialization
+```
+
+To avoid these errors, always define model relationships using arrow functions. For example:
+
+```javascript
+import Persist from "@acodeninja/persist";
+
+export class Person extends Persist.Type.Model {
+    static {
+        this.address = () => Address;
+    }
+}
+
+export class Address extends Persist.Type.Model {
+    static {
+        this.person = () => Person;
+        this.address = Persist.Type.String.required;
+        this.postcode = Persist.Type.String.required;
+    }
+}
+```
+
+By doing this, you ensure that model references are evaluated lazily, after all models have been initialized, preventing `ReferenceError` issues.
+
+## Using `HTTP` Engine in Browser
+
+When implementing thee `HTTP` engine for code that runs in the web browser, you must pass `fetch` into the engine configuration and bind it to the `window` object.
+
+```javascript
+import Persist from "@acodeninja/persist";
+import HTTPEngine from "@acodeninja/persist/engine/http";
+
+Persist.addEngine('remote', HTTPEngine, {
+    host: 'https://api.example.com',
+    fetch: fetch.bind(window),
+});
+```
+
+This will ensure that `fetch` can access the window context which is required for it to function.

package/docs/model-property-types.md

@@ -0,0 +1,173 @@
+# Model Property Types
+
+Persist uses a type definition for the properties of each model, this allows for validation and type coercion when saving and retrieving data.
+
+Model properties can be assigned a `Type`, or another `Model`. For more information on see [Models as Properties](./models-as-properties.md).
+
+## Defining Model Properties
+
+Properties can be defined on a model by setting static properties to the value of a type on the class that describes the model.
+
+```javascript
+import Persist from '@acodeninja/persist';
+
+class Person extends Persist.Type.Model {
+    static {
+        this.firstName = Persist.Type.String;
+        this.lastName = Persist.Type.String;
+    }
+}
+```
+
+## Simple Types
+
+### `Persist.Type.String`
+
+Use the `String` type for model properties that should store a [string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String). The `String` type also supports the `.required` modifier to ensure that when the model is persisted a value must exist for it.
+
+```javascript
+import Persist from '@acodeninja/persist';
+
+class Person extends Persist.Type.Model {
+    static {
+        this.firstName = Persist.Type.String;
+        this.lastName = Persist.Type.String.required;
+    }
+}
+```
+
+### `Persist.Type.Boolean`
+
+Use the `Boolean` type for model properties that should store a [boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean). The `Boolean` type also supports the `.required` modifier to ensure that when the model is persisted a value must exist for it.
+
+```javascript
+import Persist from '@acodeninja/persist';
+
+class Person extends Persist.Type.Model {
+    static {
+        this.markettingEmailsActive = Persist.Type.Boolean;
+        this.accountActive = Persist.Type.Boolean.required;
+    }
+}
+```
+
+### `Persist.Type.Number`
+
+Use the `Number` type for model properties that should store a [number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number). The `Number` type also supports the `.required` modifier to ensure that when the model is persisted a value must exist for it.
+
+```javascript
+import Persist from '@acodeninja/persist';
+
+class Person extends Persist.Type.Model {
+    static {
+        this.loginToken = Persist.Type.Number;
+        this.accountId = Persist.Type.Number.required;
+    }
+}
+```
+
+### `Persist.Type.Date`
+
+Use the `Date` type for model properties that should store a [date](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date). The `Date` type also supports the `.required` modifier to ensure that when the model is persisted a value must exist for it.
+
+```javascript
+import Persist from '@acodeninja/persist';
+
+class Person extends Persist.Type.Model {
+    static {
+        this.lastLogin = Persist.Type.Date;
+        this.createdAt = Persist.Type.Date.required;
+    }
+}
+```
+
+## Complex Types
+
+### `Persist.Type.Array.of(type)`
+
+Use the `Array` type for model properties that should store an array of another type or model. The `Array` type also supports the `.required` modifier to ensure that when the model is persisted a value must exist for it.
+
+```javascript
+import Persist from '@acodeninja/persist';
+
+class Person extends Persist.Type.Model {
+    static {
+        this.failedLoginAttempts = Persist.Type.Array.of(Persist.Type.Date);
+        this.fullName = Persist.Type.Array.of(Persist.Type.String).required;
+    }
+}
+```
+
+### `Persist.Type.Custom.of(schema)`
+
+Use the `Custom` type for model properties that should store a custom [json-schema draft-07](https://json-schema.org/draft-07/json-schema-hypermedia) object. You can also use any formats defined by the [`avj-formats`](https://ajv.js.org/packages/ajv-formats.html) library. The `Custom` type also supports the `.required` modifier to ensure that when the model is persisted a value must exist for it.
+
+```javascript
+import Persist from '@acodeninja/persist';
+
+class Person extends Persist.Type.Model {
+    static {
+        this.address = Persist.Type.Custom.of({
+            type: 'object',
+            additionalProperties: false,
+            required: ['line1', 'city', 'postcode'],
+            properties: {
+                line1: {type: 'string'},
+                line2: {type: 'string'},
+                city: {type: 'string'},
+                postcode: {
+                    type: 'string',
+                    pattern: "^[A-Z]+[0-9]+\s[A-Z]+[0-9]+$",
+                },
+            },
+        }).required;
+    }
+}
+```
+
+## Resolved Types
+
+Resolved types are different from other types in that they do not directly store data themselves, rather they perform an action on another property of the model.
+
+### `Persist.Type.Resolved.Slug.of(property)`
+
+Use the `Slug` type for model properties that should have a slug version of another properties value. The `Custom` type also supports the `.required` modifier to ensure that when the model is persisted a value must exist for it.
+
+```javascript
+import Persist from '@acodeninja/persist';
+
+class Page extends Persist.Type.Model {
+    static {
+        this.title = Persist.Type.String;
+        this.slug = Persist.Type.Resolved.Slug.of('title');
+    }
+}
+
+const page = new Page({title: 'A really important article!'});
+const {slug} = page.toData();
+
+console.log(slug); // a-really-important-article
+```
+
+## Modifiers
+
+Models and most types support a modifier, this will alter the validation and persistence process based on the type of modifier used.
+
+### `.required`
+
+Most types support the `.required` modifier, which will alter validation to enforce the presence of the property when saving data.
+
+```javascript
+class RequiredStringModel extends Persist.Type.Model {
+    static {
+        this.requiredString = Type.String.required;
+        this.requiredNumber = Type.Number.required;
+        this.requiredBoolean = Type.Boolean.required;
+        this.requiredDate = Type.Date.required;
+        this.requiredArrayOfString = Type.Array.of(Type.String).required;
+        this.requiredArrayOfNumber = Type.Array.of(Type.Number).required;
+        this.requiredArrayOfBoolean = Type.Array.of(Type.Boolean).required;
+        this.requiredArrayOfDate = Type.Array.of(Type.Date).required;
+    }
+}
+```

package/docs/models-as-properties.md

@@ -0,0 +1,159 @@
+# Models as Properties
+
+In addition to assigning basic types to model properties, you can assign entire models as properties. This allows for the creation of complex relationships between models. For information on using basic types for properties, refer to [model property types](./model-property-types.md).
+
+We’ll explore different types of relationships between models using examples of `Person` and `Address` models, evolving the definition step by step.
+
+```javascript
+import Persist from "@acodeninja/persist";
+
+export class Person extends Persist.Type.Model {
+    static {
+        this.name = Persist.Type.String.required;
+    }
+}
+
+export class Address extends Persist.Type.Model {
+    static {
+        this.address = Persist.Type.String.required;
+        this.postcode = Persist.Type.String.required;
+    }
+}
+```
+
+## One-to-One Relationships
+
+To define a **one-to-one** relationship between two models, set a static property in one model as a function that returns the other model. This ensures that the models can be defined in any order, avoiding issues with initialization.
+
+```javascript
+import Persist from "@acodeninja/persist";
+
+export class Person extends Persist.Type.Model {
+    static {
+        this.name = Persist.Type.String.required;
+        this.address = () => Address;
+    }
+}
+
+export class Address extends Persist.Type.Model {
+    static {
+        this.address = Persist.Type.String.required;
+        this.postcode = Persist.Type.String.required;
+    }
+}
+```
+
+> [!IMPORTANT]
+> **Why Use an Arrow Function?**
+>
+> The arrow function allows the model to reference another model that may not have been defined yet. Without it, you might encounter an error like `ReferenceError: Cannot access 'Address' before initialization`.
+
+### Circular One-to-One Relationships
+
+You can extend the previous example by allowing both models to reference each other. This is useful for circular relationships, where querying one model (e.g., `Address`) should also allow access to the related model (e.g., `Person`).
+
+```javascript
+import Persist from "@acodeninja/persist";
+
+export class Person extends Persist.Type.Model {
+    static {
+        this.name = Persist.Type.String.required;
+        this.address = () => Address;
+    }
+}
+
+export class Address extends Persist.Type.Model {
+    static {
+        this.person = () => Person;
+        this.address = Persist.Type.String.required;
+        this.postcode = Persist.Type.String.required;
+    }
+}
+```
+
+## One-to-Many Relationships
+
+To model a **one-to-many** relationship, use `Persist.Type.Array` to store an array of related models. For instance, if a `Person` can have multiple addresses, this is how it would be defined:
+
+```javascript
+import Persist from "@acodeninja/persist";
+
+export class Person extends Persist.Type.Model {
+    static {
+        this.name = Persist.Type.String.required;
+        this.addresses = () => Persist.Type.Array.of(Address);
+    }
+}
+
+export class Address extends Persist.Type.Model {
+    static {
+        this.person = () => Person;
+        this.address = Persist.Type.String.required;
+        this.postcode = Persist.Type.String.required;
+    }
+}
+```
+
+This structure allows for querying both the Person and their multiple Address records, while maintaining the ability to retrieve the related person from any address.
+
+## Many-to-Many Relationships
+
+In some cases, you may want to model a many-to-many relationship. For example, if multiple people can live at the same address, this type of relationship is ideal.
+
+```javascript
+import Persist from "@acodeninja/persist";
+
+export class Person extends Persist.Type.Model {
+    static {
+        this.name = Persist.Type.String.required;
+        this.addresses = () => Persist.Type.Array.of(Address);
+    }
+}
+
+export class Address extends Persist.Type.Model {
+    static {
+        this.people = () => Persist.Type.Array.of(Person);
+        this.address = Persist.Type.String.required;
+        this.postcode = Persist.Type.String.required;
+    }
+}
+```
+
+This allows both `Person` and `Address` models to reference each other as arrays, establishing a many-to-many relationship.
+
+## Combining Relationships
+
+In more complex scenarios, you may want to capture additional information about the relationship itself. For example, when tracking when a person moved to a particular address, you can create an intermediary model (e.g., `Abode`) to store this information.
+
+```javascript
+import Persist from "@acodeninja/persist";
+
+export class Person extends Persist.Type.Model {
+    static {
+        this.name = Persist.Type.String.required;
+        this.addresses = () => Persist.Type.Array.of(Abode);
+    }
+}
+
+export class Abode extends Persist.Type.Model {
+    static {
+        this.moveInDate = Persist.Type.Date.required;
+        this.address = () => Address;
+        this.person = () => Person;
+    }
+}
+
+export class Address extends Persist.Type.Model {
+    static {
+        this.people = () => Persist.Type.Array.of(Person);
+        this.address = Persist.Type.String.required;
+        this.postcode = Persist.Type.String.required;
+    }
+}
+```
+
+In this setup:
+
+- A `Person` can have multiple `Abode` entries (i.e., where they lived and when they moved in).
+- Each `Abode` links a `Person` to an `Address`, while also recording the move-in date.
+- An `Address` can still reference multiple people, making this a flexible and more complex relationship model.

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.2.3",
+  "version": "2.3.1",
   "description": "A JSON based data modelling and persistence module with alternate storage mechanisms.",
   "type": "module",
   "scripts": {

package/src/engine/Engine.js

@@ -10,6 +10,7 @@ import lunr from 'lunr';
  */
 class Engine {
     static configuration = undefined;
+    static _searchCache = undefined;
 
     /**
      * Retrieves a model by its ID. This method must be implemented by subclasses.
@@ -113,16 +114,24 @@ class Engine {
      * Performs a search query on a model's index and returns the matching models.
      *
      * @param {Model.constructor} model - The model class.
-     * @param {object} query - The search query string.
-     * @returns {Array<Model>} An array of models matching the search query.
+     * @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.
      */
     static async search(model, query) {
         this.checkConfiguration();
 
-        const index = await this.getSearchIndexCompiled(model).catch(() => {
-            throw new EngineError(`The model ${model.toString()} does not have a search index available.`);
-        });
+        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);
 
@@ -317,7 +326,7 @@ class Engine {
             static configuration = configuration;
         }
 
-        Object.defineProperty(ConfiguredStore, 'name', { value: `${this.toString()}` });
+        Object.defineProperty(ConfiguredStore, 'name', {value: `${this.toString()}`});
 
         return ConfiguredStore;
     }
@@ -329,7 +338,7 @@ class Engine {
      * @abstract
      */
     static checkConfiguration() {
-      // Implemented in extending Engine class
+        // Implemented in extending Engine class
     }
 
     /**

package/src/type/Model.js

@@ -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

@@ -57,8 +57,14 @@ class SlugType extends ResolvedType {
             }
         }
 
+        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;

package/src/type/simple/StringType.js

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

package/.deepsource.toml

@@ -1,10 +0,0 @@
-version = 1
-
-[[analyzers]]
-name = "javascript"
-
-  [analyzers.meta]
-  environment = [
-    "nodejs",
-    "browser"
-  ]