@acodeninja/persist 3.0.0-next.12 → 3.0.0-next.14

package/README.md

@@ -14,13 +14,67 @@ A JSON based data modelling and persistence library with alternate storage mecha
 
 - Data modelling with relationships
 - Data validation
-- Data querying
-- Fuzzy search
-- Storage with: S3, HTTP and Filesystem
+- Data queries and fuzzy search
+- Store data using AWS S3 or HTTP APIs
+
+## Terms
+
+`model`
+: Defines the shape of an entity's data within your application.
+
+`property`
+: Analogous to a data type, allows defining the type of properties associated with a `model`.
+
+`connection`
+: Abstraction layer that establishes a connection to the configured storage engine and supports CRUD and query functionality.
+
+`engine`
+: An engine allows a connection to send instructions to a given service, it may support anything from a RESTFul HTTP API to a cloud service like S3 or DynamoDB.
+
+## Usage
+
+### Models
+
+```javascript
+import Persist from '@acodeninja/persist';
+
+class Person extends Persist.Model {
+    static {
+        this.name = Persist.Property.String.required;
+        this.dateOfBirth = Persist.Property.Date.required;
+        this.height = Persist.Property.Number.required;
+        this.isStudent = Persist.Property.Boolean.required;
+    }
+}
+```
+
+### Storage
+
+```javascript
+import Persist from '@acodeninja/persist';
+import S3StorageEngine from '@acodeninja/persist/storage/s3';
+
+const engine = new S3StorageEngine({
+    bucket: 'person-storage',
+    client: new S3Client(),
+});
+
+const connection = Persist.registerConnection('people', engine, [Person]);
+
+const person = new Person({
+    name: 'Joe Bloggs',
+    dateOfBirth: new Date('1993-04-02T00:00:00.000Z'),
+    height: 1.85,
+    isStudent: true,
+});
+
+await connection.put(person);
+```
 
 ## Find out more
 
-- [Model Property Types](./docs/model-property-types.md)
+- [Defining Models](./docs/defining-models.md)
+- [Model Property Types](./docs/model-properties)
 - [Models as Properties](./docs/models-as-properties.md)
 - [Structured Queries](./docs/structured-queries.md)
 - [Search Queries](./docs/search-queries.md)

package/docs/code-quirks.md

@@ -9,14 +9,14 @@ When you bundle or minify JavaScript code for production, class names are often
 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.
+2. Use `this.withName(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.withName('Person');
         this.name = Persist.Type.String.required;
     }
 }
@@ -60,12 +60,12 @@ When implementing thee `HTTP` engine for code that runs in the web browser, you
 
 ```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',
+Persist.registerConnection('people', new HTTPStorageEngine({
+    baseUrl: '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/defining-models.md

@@ -0,0 +1,61 @@
+# Defining Models
+
+Persist allows defining models as JavaScript classes and uses static attributes for the properties of each model, this allows for validation and type coercion when saving and retrieving data.
+
+## Defining a Model
+
+The most basic model is a JavaScript class that extends `Persist.Model`.
+
+```javascript
+class BasicModel extends Persist.Model {
+}
+```
+
+A model will always have an `id` property that is randomly generated using [ULID](https://github.com/ulid/spec).
+
+```javascript
+const basic = new BasicModel();
+
+console.log(basic.id) // BasicModel/01ARZ3NDEKTSV4RRFFQ69G5FAV
+```
+
+### Adding properties
+
+Model properties can be added to a model using `Persist.Property.*`.
+
+```javascript
+import Persist from '@acodeninja/persist';
+
+class Person extends Persist.Model {
+    static {
+        this.name = Persist.Property.String.required;
+        this.dateOfBirth = Persist.Property.Date.required;
+        this.height = Persist.Property.Number.required;
+        this.isStudent = Persist.Property.Boolean.required;
+    }
+}
+```
+
+For a full list of available property types see [Model Property Types](./model-properties).
+
+### Linking Models
+
+Models can be linked to other models by declaring them as properties.
+
+```javascript
+class Address extends Persist.Model {
+    static {
+        this.address = Persist.Property.String.required;
+        this.postcode = Persist.Property.String.required;
+    }
+}
+
+class Person extends Persist.Model {
+    static {
+        this.name = Persist.Property.String.required;
+        this.address = Address;
+    }
+}
+```
+
+For a look at the ways that models can be linked check out [Models as Properties](./models-as-properties.md).

package/docs/http.openapi.yml

@@ -0,0 +1,138 @@
+openapi: 3.1.0
+
+info:
+  title: Persist Generic HTTP API
+  version: 1.0.0
+
+paths:
+  /{model}/{id}:
+    get:
+      summary: Retrieve an existing model instance.
+      parameters:
+        - in: path
+          name: model
+          schema:
+            type: string
+          required: true
+          description: Name of the model
+        - in: path
+          name: id
+          schema:
+            type: string
+          required: true
+          description: Unique identifier for a model
+      responses:
+        '200':
+          description: Successful update operation
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Model'
+        '404':
+          description: Model not found
+    put:
+      summary: Create or update an existing model instance.
+      parameters:
+        - in: path
+          name: model
+          schema:
+            type: string
+          required: true
+          description: Name of the model
+        - in: path
+          name: id
+          schema:
+            type: string
+          required: true
+          description: Unique identifier for a model
+      requestBody:
+        description: Update or create a model instance.
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/Model'
+        required: true
+      responses:
+        '200':
+          description: Successful update operation
+        '201':
+          description: Successful create operation
+        '422':
+          description: Validation exception
+    delete:
+      summary: Delete an instance of a model
+      parameters:
+        - in: path
+          name: model
+          schema:
+            type: string
+          required: true
+          description: Name of the model
+        - in: path
+          name: id
+          schema:
+            type: string
+          required: true
+          description: Unique identifier for a model
+      responses:
+        '204':
+          description: Successful operation
+        '422':
+          description: Validation exception
+  /{model}:
+    get:
+      summary: Retrieve an index of the current models.
+      parameters:
+        - in: path
+          name: model
+          schema:
+            type: string
+          required: true
+          description: Name of the model
+      responses:
+        '200':
+          description: Successful update operation
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ModelIndex'
+        '404':
+          description: Model not found
+  /{model}/search:
+    get:
+      summary: Retrieve a search index of the current models.
+      parameters:
+        - in: path
+          name: model
+          schema:
+            type: string
+          required: true
+          description: Name of the model
+      responses:
+        '200':
+          description: Successful update operation
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ModelIndex'
+        '404':
+          description: Model not found
+
+components:
+  schemas:
+    Model:
+      required:
+        - id
+      type: object
+      additionalProperties: true
+      properties:
+        id:
+          type: string
+    ModelIndex:
+      properties:
+        "{model}/{id}":
+          type: object
+          additionalProperties: true
+          properties:
+            id:
+              type: string

package/docs/{model-property-types.md → model-properties.md}

@@ -1,4 +1,4 @@
-# Model Property Types
+# Model Properties
 
 Persist uses a type definition for the properties of each model, this allows for validation and type coercion when saving and retrieving data.
 
@@ -11,103 +11,105 @@ Properties can be defined on a model by setting static properties to the value o
 ```javascript
 import Persist from '@acodeninja/persist';
 
-class Person extends Persist.Type.Model {
+class Person extends Persist.Model {
     static {
-        this.firstName = Persist.Type.String;
-        this.lastName = Persist.Type.String;
+        this.firstName = Persist.Property.String;
+        this.lastName = Persist.Property.String;
     }
 }
 ```
 
-## Simple Types
+## Simple Properties
 
-### `Persist.Type.String`
+### `Persist.Property.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 {
+class Person extends Persist.Model {
     static {
-        this.firstName = Persist.Type.String;
-        this.lastName = Persist.Type.String.required;
+        this.firstName = Persist.Property.String;
+        this.lastName = Persist.Property.String.required;
     }
 }
 ```
 
-### `Persist.Type.Boolean`
+### `Persist.Property.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 {
+class Person extends Persist.Model {
     static {
-        this.markettingEmailsActive = Persist.Type.Boolean;
-        this.accountActive = Persist.Type.Boolean.required;
+        this.markettingEmailsActive = Persist.Property.Boolean;
+        this.accountActive = Persist.Property.Boolean.required;
     }
 }
 ```
 
-### `Persist.Type.Number`
+### `Persist.Property.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 {
+class Person extends Persist.Model {
     static {
-        this.loginToken = Persist.Type.Number;
-        this.accountId = Persist.Type.Number.required;
+        this.loginToken = Persist.Property.Number;
+        this.accountId = Persist.Property.Number.required;
     }
 }
 ```
 
-### `Persist.Type.Date`
+### `Persist.Property.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.
 
+A property of `Date` will serialise to an ISO 8601 date format like `2011-10-05T14:48:00.000Z` when `.toData` is called on a model.
+
 ```javascript
 import Persist from '@acodeninja/persist';
 
-class Person extends Persist.Type.Model {
+class Person extends Persist.Model {
     static {
-        this.lastLogin = Persist.Type.Date;
-        this.createdAt = Persist.Type.Date.required;
+        this.lastLogin = Persist.Property.Date;
+        this.createdAt = Persist.Property.Date.required;
     }
 }
 ```
 
-## Complex Types
+## Complex Properties
 
-### `Persist.Type.Array.of(type)`
+### `Persist.Property.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 {
+class Person extends Persist.Model {
     static {
-        this.failedLoginAttempts = Persist.Type.Array.of(Persist.Type.Date);
-        this.fullName = Persist.Type.Array.of(Persist.Type.String).required;
+        this.failedLoginAttempts = Persist.Property.Array.of(Persist.Property.Date);
+        this.fullName = Persist.Property.Array.of(Persist.Property.String).required;
     }
 }
 ```
 
-### `Persist.Type.Custom.of(schema)`
+### `Persist.Property.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 {
+class Person extends Persist.Model {
     static {
-        this.address = Persist.Type.Custom.of({
+        this.address = Persist.Property.Custom.of({
             type: 'object',
             additionalProperties: false,
             required: ['line1', 'city', 'postcode'],
@@ -125,21 +127,21 @@ class Person extends Persist.Type.Model {
 }
 ```
 
-## Resolved Types
+## Resolved Properties
 
 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)`
+### `Persist.Property.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 {
+class Page extends Persist.Model {
     static {
-        this.title = Persist.Type.String;
-        this.slug = Persist.Type.Resolved.Slug.of('title');
+        this.title = Persist.Property.String;
+        this.slug = Persist.Property.Resolved.Slug.of('title');
     }
 }
 
@@ -158,7 +160,7 @@ Models and most types support a modifier, this will alter the validation and per
 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 {
+class RequiredStringModel extends Persist.Model {
     static {
         this.requiredString = Type.String.required;
         this.requiredNumber = Type.Number.required;

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;
+        this.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;
+        this.address = Persist.Property.String.required;
+        this.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.name = Persist.Property.String.required;
         this.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.address = Persist.Property.String.required;
+        this.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.name = Persist.Property.String.required;
         this.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;
+        this.address = Persist.Property.String.required;
+        this.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);
+        this.name = Persist.Property.String.required;
+        this.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;
+        this.address = Persist.Property.String.required;
+        this.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);
+        this.name = Persist.Property.String.required;
+        this.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;
+        this.people = () => Persist.Property.Array.of(Person);
+        this.address = Persist.Property.String.required;
+        this.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);
+        this.name = Persist.Property.String.required;
+        this.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.moveInDate = Persist.Property.Date.required;
         this.address = () => Address;
         this.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;
+        this.people = () => Persist.Property.Array.of(Person);
+        this.address = Persist.Property.String.required;
+        this.postcode = Persist.Property.String.required;
     }
 }
 ```

package/docs/search-queries.md

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