tool-db 1.4.5 → 2.0.2

package/README.md

@@ -11,6 +11,12 @@ It is the mix of a lot of cool concepts into one;
 - Key-value/document storage.
 - Works in the Browser and Nodejs seamlessly.
 
+For a more detailed documentation head here;
+
+[https://github.com/Manwe-777/tool-db-docs](https://github.com/Manwe-777/tool-db-docs)
+
+_(No live version just yet!, until the protocol is more finalized)_
+
 We push towards of the concept of federated servers, where we set up a p2p mesh network between any servers who want to join the swarm, and have those servers manage the connection and data sharing between them, while allowing client peers to connect to them to push updates to the database.
 This setup IS NOT a requirement! It is just what I think is the best and most reliable way of creating a p2p network for dApps using both desktop and web compatible technologies. Any peer has the capability of connecting to any other peer trough websockets, and modifiying the code to allow webRtc connections between web peers is absolutely possible.
 
@@ -57,34 +63,34 @@ These are the options you can pass to the constructor:
 
 ```
 {
-  // Database name to use
+  // Database name to use (default "tooldb")
   db: string;
 
-  // Show debug console logs
+  // Show debug console logs (default false)
   debug: boolean;
 
   // Array of peers to connect to, each one in the form of { host: "127.0.0.1", port: 9000 }
   peers: { host: "127.0.0.1", port: 9000 }[];
 
-  // Max number of tries when a connection fails
+  // Max number of tries when a connection fails (default 5)
   maxRetries: number;
 
-  // How long to wait (max) for a debounced key listener recv
+  // How long to wait (max) for a debounced key listener recv (default 100)
   triggerDebouce: number;
 
-  // How long to wait between retries
+  // How long to wait between retries (default 2000)
   wait: number;
 
-  // If you want to force a Proof of Work on all messages, set how much (zero is no POW)
+  // If you want to force a Proof of Work on all messages, set how much (zero is no POW, default 0)
   pow: number;
 
-  // Weter we are a server or not
+  // Whether we are a server or not (default false)
   server: boolean;
 
   // Our hostname (server only)
   host: string
 
-  // Port to listen incoming connections (server only)
+  // Port to listen incoming connections (server only, default is 8080)
   port: number;
 
   // A server instance like Express (server only)
@@ -99,16 +105,8 @@ These are the options you can pass to the constructor:
   // A custom storage adapter function
   storageAdapter: ToolDbStorageAdapter;
 
-  // Our client ID (defaults to a random ID)
-  id: string;
-
-  // The namespace/topic of our app
+  // The namespace/topic of our app (default is "tool-db-default")
   topic: string;
-  
-  // Public and private (ECDSA) keys of our client. In the default network adapter these are used to sign
-  // our messages as we join and leave the network, public key should match the client ID (as a base64 exported string).
-  publicKey: CryptoKey | undefined;
-  privateKey: CryptoKey | undefined;
 }
 ```
 Notice you can use your own network and storage modules if you would like to implement custom solutions for peers discovery, connections, storage, etc, the default adapters will work both on nodejs and the browser.
@@ -121,11 +119,9 @@ client.signIn(user, pass).then(keys);
 client.anonSignIn().then();
 ```
 
-To retrieve your public key; (only if logged in)
+To retrieve your address; (only if logged in)
 ```
-client.getPubKey().then(pubKey);
-// or
-client.user?.pubKey
+client.getAddress();
 ```
 
 You can check if you are correctly logged in by checking if the user field exists or not;
@@ -149,7 +145,7 @@ You can use `client.getUserNamespacedKey(key)` to convert any key to a private n
 
 Note the third function (putCrdt); For p2p networks some times you want to have conflict resolution on certain documents, to do this we use [automerge](https://github.com/automerge/automerge). Please take a look at it to know how it works in detail! The only thing you need to know on Tool Db is that you have to send an `Automerge.BinaryChange[]` (you get it using `Automerge.change()`). The recieving peer will process the changes, compare it to its stored documents and generate a new document with JSON CRDT applied to it, then relay the final document back to you.
 
-To listen for a value changes you can set up a listener on a key. Beware the listener will check for all keys *starting with* the supplied key, so for example, if you use "value." as your listener if will execute on every key that starts with "value.". This is useful for checking against a public key or namespace.
+To listen for a value changes you can set up a listener on a key. Beware the listener will check for all keys *starting with* the supplied key, so for example, if you use "value." as your listener if will execute on every key that starts with "value.". This is useful for checking against an address or namespace.
 ```
 const listenerId = client.addKeyListener("value", console.log);
 client.removeKeyListener(listenerId);
@@ -181,7 +177,7 @@ client.queryKeys(keyPrefix, userNamespaced?, timeout?).then()
 ```
 
 Just like previous methods you can configure the namespace and timeout and returns a promise, but in this case the value is always an array with the found keys.
-Using for example ":" + publicKey as our prefix would return all keys stored for that specific user namespace; you can also create keys for very specific use cases like "post-1" and query again "post-" to get a list of all available posts.
+Using for example ":" + address as our prefix would return all keys stored for that specific user namespace; you can also create keys for very specific use cases like "post-1" and query again "post-" to get a list of all available posts.
 
 Keep in mind this can be an intensive thing to do if your indexes are too big, and not recommended to be used very frequently.
 
@@ -195,31 +191,11 @@ client.subscribeData("key", userNamespaced?);
 
 This will relay back to you all Put and CrdtPut messages on that key.
 
-When subscribing to a CRDT document you will need to load the data like so;
-```
-window.toolDb.addKeyListener("documentKey", handleDocumentKeyCrdt);
-function handleDocumentKeyCrdt(msg) {
-  if (msg && msg.type === "crdt") {
-    // Load the document from the message (msg.doc)
-    const incomingDocument = Automerge.load(
-      base64ToBinaryDocument(msg.doc)
-    );
-
-    if (globalData.myCrdtDocument) {
-      // Merge the local doc vs the incoming one and store it somewhere locally
-      globalData.myCrdtDocument = Automerge.merge(globalData.myCrdtDocument, incomingDocument);
-    } else {
-      // New document! Just store it
-      globalData.myCrdtDocument = incomingDocument;
-    }
-  }
-}
-```
-
 ## Events
 
 If you need to check when you are connected to a server peer or not you can use the following method replacements;
+
 ```
-client.onConnect = () => { /* Your code here */ };
+client.onConnect = (remotePeerId: string) => { /* Your code here */ };
 client.onDisconnect = () => { /* Your code here */ };
 ```