@acodeninja/persist 3.0.0-next.9 → 3.0.0

package/docs/models-as-properties.md

@@ -1,22 +1,22 @@
 # 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).
+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-properties.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 {
+export class Person extends Persist.Model {
     static {
-        this.name = Persist.Type.String.required;
+        Person.name = Persist.Property.String.required;
     }
 }
 
-export class Address extends Persist.Type.Model {
+export class Address extends Persist.Model {
     static {
-        this.address = Persist.Type.String.required;
-        this.postcode = Persist.Type.String.required;
+        Address.address = Persist.Property.String.required;
+        Address.postcode = Persist.Property.String.required;
     }
 }
 ```
@@ -28,17 +28,17 @@ To define a **one-to-one** relationship between two models, set a static propert
 ```javascript
 import Persist from "@acodeninja/persist";
 
-export class Person extends Persist.Type.Model {
+export class Person extends Persist.Model {
     static {
-        this.name = Persist.Type.String.required;
-        this.address = () => Address;
+        Person.name = Persist.Property.String.required;
+        Person.address = () => Address;
     }
 }
 
-export class Address extends Persist.Type.Model {
+export class Address extends Persist.Model {
     static {
-        this.address = Persist.Type.String.required;
-        this.postcode = Persist.Type.String.required;
+        Address.address = Persist.Property.String.required;
+        Address.postcode = Persist.Property.String.required;
     }
 }
 ```
@@ -46,7 +46,7 @@ export class Address extends Persist.Type.Model {
 > [!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`.
+> 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`. See [Reference Errors](./code-quirks.md#reference-errors).
 
 ### Circular One-to-One Relationships
 
@@ -55,41 +55,41 @@ You can extend the previous example by allowing both models to reference each ot
 ```javascript
 import Persist from "@acodeninja/persist";
 
-export class Person extends Persist.Type.Model {
+export class Person extends Persist.Model {
     static {
-        this.name = Persist.Type.String.required;
-        this.address = () => Address;
+        Person.name = Persist.Property.String.required;
+        Person.address = () => Address;
     }
 }
 
-export class Address extends Persist.Type.Model {
+export class Address extends Persist.Model {
     static {
-        this.person = () => Person;
-        this.address = Persist.Type.String.required;
-        this.postcode = Persist.Type.String.required;
+        Address.person = () => Person;
+        Address.address = Persist.Property.String.required;
+        Address.postcode = Persist.Property.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:
+To model a **one-to-many** relationship, use `Persist.Property.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 {
+export class Person extends Persist.Model {
     static {
-        this.name = Persist.Type.String.required;
-        this.addresses = () => Persist.Type.Array.of(Address);
+        Person.name = Persist.Property.String.required;
+        Person.addresses = () => Persist.Property.Array.of(Address);
     }
 }
 
-export class Address extends Persist.Type.Model {
+export class Address extends Persist.Model {
     static {
-        this.person = () => Person;
-        this.address = Persist.Type.String.required;
-        this.postcode = Persist.Type.String.required;
+        Address.person = () => Person;
+        Address.address = Persist.Property.String.required;
+        Address.postcode = Persist.Property.String.required;
     }
 }
 ```
@@ -103,18 +103,18 @@ In some cases, you may want to model a many-to-many relationship. For example, i
 ```javascript
 import Persist from "@acodeninja/persist";
 
-export class Person extends Persist.Type.Model {
+export class Person extends Persist.Model {
     static {
-        this.name = Persist.Type.String.required;
-        this.addresses = () => Persist.Type.Array.of(Address);
+        Person.name = Persist.Property.String.required;
+        Person.addresses = () => Persist.Property.Array.of(Address);
     }
 }
 
-export class Address extends Persist.Type.Model {
+export class Address extends Persist.Model {
     static {
-        this.people = () => Persist.Type.Array.of(Person);
-        this.address = Persist.Type.String.required;
-        this.postcode = Persist.Type.String.required;
+        Address.people = () => Persist.Property.Array.of(Person);
+        Address.address = Persist.Property.String.required;
+        Address.postcode = Persist.Property.String.required;
     }
 }
 ```
@@ -128,26 +128,26 @@ In more complex scenarios, you may want to capture additional information about
 ```javascript
 import Persist from "@acodeninja/persist";
 
-export class Person extends Persist.Type.Model {
+export class Person extends Persist.Model {
     static {
-        this.name = Persist.Type.String.required;
-        this.addresses = () => Persist.Type.Array.of(Abode);
+        Person.name = Persist.Property.String.required;
+        Person.addresses = () => Persist.Property.Array.of(Abode);
     }
 }
 
-export class Abode extends Persist.Type.Model {
+export class Abode extends Persist.Model {
     static {
-        this.moveInDate = Persist.Type.Date.required;
-        this.address = () => Address;
-        this.person = () => Person;
+        Abode.moveInDate = Persist.Property.Date.required;
+        Abode.address = () => Address;
+        Abode.person = () => Person;
     }
 }
 
-export class Address extends Persist.Type.Model {
+export class Address extends Persist.Model {
     static {
-        this.people = () => Persist.Type.Array.of(Person);
-        this.address = Persist.Type.String.required;
-        this.postcode = Persist.Type.String.required;
+        Address.people = () => Persist.Property.Array.of(Person);
+        Address.address = Persist.Property.String.required;
+        Address.postcode = Persist.Property.String.required;
     }
 }
 ```

package/docs/search-queries.md

@@ -11,19 +11,19 @@ Let's consider the following models:
 ```javascript
 import Persist from "@acodeninja/persist";
 
-export class Person extends Persist.Type.Model {
+export class Person extends Persist.Model {
     static {
-        this.name = Persist.Type.String.required;
-        this.address = () => Address;
-        this.searchProperties = () => ['name', 'address.address'];
+        Person.name = Persist.Property.String.required;
+        Person.address = () => Address;
+        Person.searchProperties = () => ['name', 'address.address'];
     }
 }
 
-export class Address extends Persist.Type.Model {
+export class Address extends Persist.Model {
     static {
-        this.address = Persist.Type.String.required;
-        this.postcode = Persist.Type.String.required;
-        this.searchProperties = () => ['address', 'postcode'];
+        Address.address = Persist.Property.String.required;
+        Address.postcode = Persist.Property.String.required;
+        Address.searchProperties = () => ['address', 'postcode'];
     }
 }
 ```
@@ -36,12 +36,10 @@ To search for any `Person` who lives on station road, the following search query
 
 ```javascript
 import Persist from "@acodeninja/persist";
-import Person from "./Person";
-import FileStorageEngine from "@acodeninja/persist/engine/storage/file"
 
-FileStorageEngine
-    .configure(configuration)
-    .search(Person, 'station road');
+const connection = Persist.getConnections('people');
+
+await connection.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

@@ -2,23 +2,25 @@
 
 Persist makes several storage engines available for use with the library
 
-## Filesystem Storage StorageEngine
+## S3 Storage StorageEngine
 
-To store models using the local file system, use the `File` 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 FileStorageEngine from "@acodeninja/persist/engine/storage/file";
+import {S3Client} from "@aws-sdk/client-s3";
+import S3StorageEngine from "@acodeninja/persist/storage/s3";
 
-Persist.addEngine('local', FileStorageEngine, {
-    path: '/app/storage',
-});
+const connection = Persist.registerConnection('remote', new S3StorageEngine({
+    bucket: 'test-bucket',
+    client: new S3Client(),
+}));
 
-export class Tag extends Persist.Type.Model {
-    static tag = Persist.Type.String.required;
+export class Tag extends Persist.Model {
+    static tag = Persist.Property.String.required;
 }
 
-await Persist.getEngine('local', FileStorageEngine).put(new Tag({tag: 'documentation'}));
+await connection.put(new Tag({tag: 'documentation'}));
 ```
 
 ## HTTP Storage StorageEngine
@@ -27,35 +29,17 @@ To store models using an HTTP server, use the `HTTP` storage engine. When using
 
 ```javascript
 import Persist from "@acodeninja/persist";
-import HTTPStorageEngine from "@acodeninja/persist/engine/storage/http";
+import HTTPStorageEngine from "@acodeninja/persist/storage/http";
 
-Persist.addEngine('remote', HTTPStorageEngine, {
-    host: 'https://api.example.com',
-});
+const connection = Persist.registerConnection('remote', new HTTPStorageEngine({
+    baseUrl: 'https://api.example.com',
+}));
 
-export class Tag extends Persist.Type.Model {
-    static tag = Persist.Type.String.required;
+export class Tag extends Persist.Model {
+    static tag = Persist.Property.String.required;
 }
 
-await Persist.getEngine('remote', HTTPStorageEngine).put(new Tag({tag: 'documentation'}));
+await connection.put(new Tag({tag: 'documentation'}));
 ```
 
-## S3 Storage StorageEngine
-
-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 S3StorageEngine from "@acodeninja/persist/engine/storage/s3";
-
-Persist.addEngine('remote', S3StorageEngine, {
-    bucket: 'test-bucket',
-    client: new S3Client(),
-});
-
-export class Tag extends Persist.Type.Model {
-    static tag = Persist.Type.String.required;
-}
-
-await Persist.getEngine('remote', S3StorageEngine).put(new Tag({tag: 'documentation'}));
-```
+A generic Open API specification for an HTTP server integration with `Persist` can be found [here](./http.openapi.yml).

package/docs/structured-queries.md

@@ -4,26 +4,27 @@ Use structured queries when you need to filter a collection of models using a se
 
 ## 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.
+To set index properties on a model, define the static function `indexedProperties` 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 {
+export class Person extends Persist.Model {
     static {
-        this.name = Persist.Type.String.required;
-        this.address = () => Address;
-        this.indexProperties = () => ['name', 'address.postcode'];
+        Person.name = Persist.Property.String.required;
+        Person.address = () => Address;
+        Person.indexedProperties = () => ['name', 'address.postcode'];
     }
 }
 
-export class Address extends Persist.Type.Model {
+export class Address extends Persist.Model {
     static {
-        this.address = Persist.Type.String.required;
-        this.postcode = Persist.Type.String.required;
-        this.indexProperties = () => ['postcode'];
+        Address.address = Persist.Property.String.required;
+        Address.postcode = Persist.Property.String.required;
+        Address.people = () => Persist.Property.Array.of(Person)
+        Address.indexedProperties = () => ['postcode', 'people.[*].name'];
     }
 }
 ```
@@ -39,14 +40,12 @@ 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 FileStorageEngine from "@acodeninja/persist/engine/storage/file"
-
-FileStorageEngine
-    .configure(configuration)
-    .find(Person, {
-        name: {$is: 'Joe Bloggs'},
-    });
+
+const connection = Persist.getConnection('people');
+
+await connection.find(Person, {
+    name: {$is: 'Joe Bloggs'},
+});
 ```
 
 ## Querying Partial Matches
@@ -55,14 +54,30 @@ 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 FileStorageEngine from "@acodeninja/persist/engine/storage/file"
-
-FileStorageEngine
-    .configure(configuration)
-    .find(Person, {
-        name: {$contains: 'Joe'},
-    });
+
+const connection = Persist.getConnection('people');
+
+await connection.find(Person, {
+    name: {$contains: 'Joe'},
+});
+```
+
+## Querying One-to-Many Model links
+
+To query for all instances of `Address` with a linked `Person` with a name that contains `Joe` you can write:
+
+```javascript
+import Persist from "@acodeninja/persist";
+
+const connection = Persist.getConnection('people');
+
+await connection.find(Address, {
+    people: {
+        $contains: {
+            name: {$contains: 'Joe'},
+        },
+    },
+});
 ```
 
 ## Querying Combination Matches
@@ -71,18 +86,16 @@ To query for a `Person` who lives at `SW1 1AA` a combination of contains and exa
 
 ```javascript
 import Persist from "@acodeninja/persist";
-import Person from "./Person";
-import FileStorageEngine from "@acodeninja/persist/engine/storage/file"
-
-FileStorageEngine
-    .configure(configuration)
-    .find(Person, {
-        address: {
-            $contains: {
-                postcode: {$is: 'SW1 1AA'},
-            },
+
+const connection = Persist.getConnection('people');
+
+await connection.find(Person, {
+    address: {
+        $contains: {
+            postcode: {$is: 'SW1 1AA'},
         },
-    });
+    },
+});
 ```
 
 ## Multiple Queries
@@ -91,17 +104,15 @@ To query for anyone called `Joe Bloggs` who lives in the `SW1` postcode area, we
 
 ```javascript
 import Persist from "@acodeninja/persist";
-import Person from "./Person";
-import FileStorageEngine from "@acodeninja/persist/engine/storage/file"
-
-FileStorageEngine
-    .configure(configuration)
-    .find(Person, {
-        name: {$is: 'Joe Bloggs'},
-        address: {
-            $contains: {
-                postcode: {$contains: 'SW1'},
-            },
+
+const connection = Persist.getConnection('people');
+
+await connection.find(Person, {
+    name: {$is: 'Joe Bloggs'},
+    address: {
+        $contains: {
+            postcode: {$contains: 'SW1'},
         },
-    });
+    },
+});
 ```

package/docs/transactions.md

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

package/exports/storage/http.js

@@ -0,0 +1,3 @@
+import HTTPStorageEngine from '../../src/engine/storage/HTTPStorageEngine.js';
+
+export default HTTPStorageEngine;

package/exports/storage/s3.js

@@ -0,0 +1,3 @@
+import S3StorageEngine from '../../src/engine/storage/S3StorageEngine.js';
+
+export default S3StorageEngine;

package/jest.config.cjs

@@ -1,10 +1,11 @@
 /** @type {import('jest').Config} */
 const config = {
-    coveragePathIgnorePatterns: [
-        'node_modules',
-        'test/fixtures',
-        'test/mocks',
-        'test/scripts',
+    collectCoverage: true,
+    coveragePathIgnorePatterns: ['test/fixtures/minified/'],
+    collectCoverageFrom: [
+        '**/*.js',
+        '!{node_modules,coverage,exports}/**',
+        '!*.config.js',
     ],
     coverageThreshold: {
         global: {
@@ -14,13 +15,8 @@ const config = {
             statements: 100,
         },
     },
-    testMatch: [
-        '**/*.test.js',
-    ],
-    watchPathIgnorePatterns: [
-        'coverage/',
-        'test/fixtures/minified',
-    ],
+    testMatch: ['**/*.test.js'],
+    watchPathIgnorePatterns: ['coverage/', 'test/fixtures/minified'],
 };
 
 module.exports = config;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@acodeninja/persist",
-  "version": "3.0.0-next.9",
+  "version": "3.0.0",
   "description": "A JSON based data modelling and persistence module with alternate storage mechanisms.",
   "type": "module",
   "scripts": {
@@ -12,7 +12,7 @@
   },
   "exports": {
     ".": "./exports/default.js",
-    "./engine/*": "./exports/engine/*.js"
+    "./storage/*": "./exports/storage/*.js"
   },
   "repository": {
     "url": "https://github.com/acodeninja/persist"