@acodeninja/persist 3.0.0-next.8 → 3.0.0

package/README.md

@@ -9,18 +9,74 @@ A JSON based data modelling and persistence library with alternate storage mecha
 
 [![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/)
+![CodeRabbit PR Reviews](https://img.shields.io/coderabbit/prs/github/acodeninja/persist?utm_source=oss&utm_medium=github&utm_campaign=acodeninja%2Fpersist&labelColor=171717&color=FF570A&link=https%3A%2F%2Fcoderabbit.ai&label=CodeRabbit+Reviews)
 
 ## Features
 
 - 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 {
+        Person.name = Persist.Property.String.required;
+        Person.dateOfBirth = Persist.Property.Date.required;
+        Person.height = Persist.Property.Number.required;
+        Person.isStudent = Persist.Property.Boolean.required;
+    }
+}
+```
+
+### Storage
+
+```javascript
+import Persist from '@acodeninja/persist';
+import {S3Client} from "@aws-sdk/client-s3";
+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.md)
 - [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,15 +9,15 @@ 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 {
+export class Person extends Persist.Model {
     static {
-        this.setMinifiedName('Person');
-        this.name = Persist.Type.String.required;
+        Person.withName('Person');
+        Person.name = Persist.Property.String.required;
     }
 }
 ```
@@ -37,17 +37,17 @@ To avoid these errors, always define model relationships using arrow functions.
 ```javascript
 import Persist from "@acodeninja/persist";
 
-export class Person extends Persist.Type.Model {
+export class Person extends Persist.Model {
     static {
-        this.address = () => Address;
+        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;
     }
 }
 ```
@@ -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 {
+        Person.name = Persist.Property.String.required;
+        Person.dateOfBirth = Persist.Property.Date.required;
+        Person.height = Persist.Property.Number.required;
+        Person.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 {
+        Address.address = Persist.Property.String.required;
+        Address.postcode = Persist.Property.String.required;
+    }
+}
+
+class Person extends Persist.Model {
+    static {
+        Person.name = Persist.Property.String.required;
+        Person.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;
+        Person.firstName = Persist.Property.String;
+        Person.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;
+        Person.firstName = Persist.Property.String;
+        Person.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;
+        Person.marketingEmailsActive = Persist.Property.Boolean;
+        Person.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;
+        Person.loginToken = Persist.Property.Number;
+        Person.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;
+        Person.lastLogin = Persist.Property.Date;
+        Person.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;
+        Person.failedLoginAttempts = Persist.Property.Array.of(Persist.Property.Date);
+        Person.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({
+        Person.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');
+        Page.title = Persist.Property.String;
+        Page.slug = Persist.Property.Resolved.Slug.of('title');
     }
 }
 
@@ -158,16 +160,47 @@ 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;
-        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;
+        RequiredStringModel.requiredString = Persist.Property.String.required;
+        RequiredStringModel.requiredNumber = Persist.Property.Number.required;
+        RequiredStringModel.requiredBoolean = Persist.Property.Boolean.required;
+        RequiredStringModel.requiredDate = Persist.Property.Date.required;
+        RequiredStringModel.requiredArrayOfString = Persist.Property.Array.of(Persist.Property.String).required;
+        RequiredStringModel.requiredArrayOfNumber = Persist.Property.Array.of(Persist.Property.Number).required;
+        RequiredStringModel.requiredArrayOfBoolean = Persist.Property.Array.of(Persist.Property.Boolean).required;
+        RequiredStringModel.requiredArrayOfDate = Persist.Property.Array.of(Persist.Property.Date).required;
     }
 }
 ```
+
+## Custom Property Types
+
+Under the hood, model validation uses the [ajv](https://ajv.js.org/) library with [ajv-formats](https://ajv.js.org/packages/ajv-formats.html) included. Because of this, you can create your own property types.
+
+Say you want to attach an IPv4 address to your models. The following type class can accomplish this.
+
+```javascript
+import Persist from '@acodeninja/persist';
+
+class IPv4Type extends Persist.Property.Type {
+    static {
+        // Set the type of the property to string
+        IPv4Type._type = 'string';
+        // Use the ajv extended format "ipv4"
+        IPv4Type._format = 'ipv4';
+        // Ensure that even when minified, the name of the constructor is IPv4
+        Object.defineProperty(IPv4Type, 'name', {value: 'IPv4'});
+    }
+}
+```
+
+This type can then be used in any model as needed.
+
+```javascript
+import Persist from '@acodeninja/persist';
+
+class StaticIP extends Persist.Model {
+    static ip = IPv4Type.required;
+}
+```