@acodeninja/persist 2.3.0 → 2.3.2

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.