docs: adding Pluto readme (#314)

Signed-off-by: Curtish <ch@curtish.me>

README.md

@@ -74,11 +74,14 @@ npm run dev
 ```
 
 ### Implementing storage for the SDK
-This SDK exposes Pluto, which manages data schemas, migrations for you, but requires a Pluto.Store which needs to be implemented by the user, as this is particular to your use case.
+Pluto, the SDK storage layer, is not a complete solution and requires some work. To make this as simple as possible there are multiple options of different complexity provided. These options are discussed in more detail in the Pluto module.
+[Read more here.](./src/pluto/README.md)
 
-Provided demo implementations are intentionally oversimplified and **should not** be used in production.
+> [!WARNING]  
+> Provided demo implementations are intentionally oversimplified and **should not** be used in production.
 
-Example community implementations:
+
+#### Example community implementations:
 - [atala-community-projects/pluto-encrypted](https://github.com/atala-community-projects/pluto-encrypted): InMemory, IndexDB, LevelDB, as well as a test-suite to help you build your own.
 
 

src/pluto/Pluto.ts

@@ -52,7 +52,7 @@ export namespace Pluto {
     /**
      * Run a query to fetch data from the Store
      * 
-     * @param name Model name
+     * @param table table name
      * @param query a MangoQuery object, a set of values and operators defining the query
      * 
      * properties within an object will be AND'ed
@@ -76,15 +76,15 @@ export namespace Pluto {
      * 
      * @returns relevant Models
      */
-    query<T extends Models.Model>(name: string, query?: MangoQuery<T>): Promise<T[]>;
+    query<T extends Models.Model>(table: string, query?: MangoQuery<T>): Promise<T[]>;
 
     /**
      * Persist new data in the Store.
      * 
-     * @param name table name
+     * @param table table name
      * @param model object to save
      */
-    insert<T extends Models.Model>(name: string, model: T): Promise<void>;
+    insert<T extends Models.Model>(table: string, model: T): Promise<void>;
 
     /**
      * Updating a new row in the Store
@@ -227,7 +227,7 @@ export class Pluto implements Domain.Pluto {
     for (const did of dids) {
       const dbDids = await this.getPrismDIDS(did.uuid);
       for (const prismDID of dbDids) {
-        prismDIDS.push(prismDID)
+        prismDIDS.push(prismDID);
       }
     }
     return prismDIDS;
@@ -245,7 +245,7 @@ export class Pluto implements Domain.Pluto {
         const prismDID = new Domain.PrismDID(did, key, link.alias);
         return prismDID;
       })
-    )
+    );
   }
 
 

src/pluto/README.md

@@ -0,0 +1,102 @@
+# Pluto
+
+
+Pluto is the SDK storage layer, responsible for the saving and retrieval of data within the SDK.
+As storage is a complex issue Pluto has been designed to try and enable maximum flexibility balanced with ease-of-use. Multiple levels of abstraction are provided so an implementation can be curated specifically to the use-case.
+In an effort to reduce the minimum amount of work required to get started with the SDK, implementations of the top-most abstractions are provided, but the underlying data layer is not and will require some work.
+
+The levels of abstraction are described below:
+
+
+## Top level interface
+An SDK specific interface, detailing all the necessary storage functions for operation.
+
+This interface defines the specific functions requried by the SDK, and while it's input and output are all Domain classes, it provides no opinion on how they are handled internally.
+This approach allows for maximum customisation, constrained only by the interface contract.
+
+The top level interface can be found at [SDK.Domain.Pluto](../domain/buildingBlocks/Pluto.ts) alongside our other top level interfaces.
+
+
+```TS
+  import SDK from "@hyperledger/identus-edge-agent-sdk";
+
+  class CustomPluto implements SDK.Domain.Pluto {
+    storeMessage(message: SDK.Domain.Message): Promise<void> {
+      // implementation
+    }
+
+    getAllMessages(): Promise<SDK.Domain.Message[]> {
+      // implementation
+    }
+
+    // ...etc
+  }
+
+  const pluto = new CustomPluto();
+  const agent = Agent.initialize({ pluto, ...etc });
+```
+
+
+## Store
+A general purpose CRUD interface, with a pre-designed Table structure and significantly smaller footprint than the top level interface.
+
+Designed to be used with the existing Pluto implementation, where Pluto handles the logic and orchestration from Domain classes to Storable models, and the Store handles the persistence of those models.
+
+The Store revolves around a storable object, which is an arbitrary object with a `uuid` property that uniquely identifies the object. 
+The interface can be found at [SDK.Pluto.Store](./Pluto.ts)
+
+```TS
+  import SDK from "@hyperledger/identus-edge-agent-sdk";
+
+  class CustomStore implements SDK.Pluto.Store {
+    insert<T extends SDK.Domain.Pluto.Storable>(table: string, model: T): Promise<void> {
+      // implementation
+    }
+
+    query<T extends SDK.Domain.Pluto.Storable>(table: string, query?: MangoQuery<T>): Promise<T[]> {
+      // implementation
+    }
+
+    update<T extends SDK.Domain.Pluto.Storable>(table: string, model: T): Promise<void> {
+      // implementation
+    }
+
+    delete(table: string, uuid: string): Promise<void> {
+      // implementation
+    }
+  }
+
+  const store = new CustomStore();
+  const pluto = new SDK.Pluto(store, apollo);
+  const agent = Agent.initialize({ pluto, apollo, ...etc });
+```
+
+## RxDB storage
+
+An implementation of the [RxStorage](https://rxdb.info/rx-storage.html) interface, allowing the choice and customisation of data layer using RxDB implementations.
+The SDK exports an [implementation](./rxdb/Store.ts) of the Store interface using RxDB, which only requires the storage, name and password to run.
+
+> Note: the composed storage requires encryption capabilities.
+
+
+```TS
+  import SDK from "@hyperledger/identus-edge-agent-sdk";
+  import { getRxStorageMemory } from 'rxdb/plugins/storage-memory';
+  import { wrappedKeyEncryptionCryptoJsStorage } from 'rxdb/plugins/encryption-crypto-js';
+
+  // custom RxDB inMemory storage
+  const customStorage = wrappedKeyEncryptionCryptoJsStorage({
+    storage: getRxStorageMemory()
+  });
+
+  const store = new SDK.Store({
+    name: `exampledb`,
+    password: 'examplepass',
+    storage: customStorage,
+  });
+  const pluto = new SDK.Pluto(store, apollo);
+  const agent = Agent.initialize({ pluto, apollo, ...etc });
+```
+
+> Read more about RxStorage in the RxDB docs https://rxdb.info/rx-storage.html
+