braid-text 0.0.8 → 0.0.10

package/README.md

@@ -8,11 +8,14 @@ This library provides a simple http route handler, along with client code, enabl
     - As little as 50 lines of code!
     - With zero history overhead on client
   - Supports [backpressure](https://braid.org/meeting-81/simpleton) to run smoothly on constrained servers
-  - Sever merges with Diamond-Types
+  - Server merges with Diamond-Types
 - Supports [Diamond Types](https://github.com/josephg/diamond-types) merge-type
-  - Fast / Robust / Extensively fuzz-tested 
+  - Fully peer-to-peer CRDT
+  - Fast / Robust / Extensively fuzz-tested
 - Developed in [braid.org](https://braid.org)
 
+This library makes it safe, easy & efficient to add collaborative text editing to every user-editable string in your web app.  Make your app multiplayer!
+
 ### Demo: a Wiki!
 
 This will run a collaboratively-editable wiki:
@@ -26,8 +29,9 @@ Now open these URLs in your browser:
   - http://localhost:8888/demo (to see the demo text)
   - http://localhost:8888/demo?editor (to edit the text)
   - http://localhost:8888/demo?markdown-editor (to edit it as markdown)
+  - http://localhost:8888/any-other-path?editor (to create a new page, just go to its URL, and then start editing)
 
-Or try opening the URL in [Braid-Chrome](https://github.com/braid-org/braid-chrome), or another Braid client, to edit it directly!
+Or try opening the URL in [Braid-Chrome](https://github.com/braid-org/braid-chrome), or [another Braid client](https://bloop.monster/simpleditor), to edit it directly!
 
 Check out the `server-demo.js` file to see examples for how to add access control, and a `/pages` endpoint to show all the edited pages.
 
@@ -59,8 +63,8 @@ http_server.on("request", (req, res) => {
   - The files for a resource will all be prefixed with a url-encoding of `key` within this folder.
 
 `braid_text.serve(req, res, options)`
-  - `req`: The incoming HTTP request object.
-  - `res`: The HTTP response object to send the response.
+  - `req`: Incoming HTTP request object.
+  - `res`: Outgoing HTTP response object.
   - `options`: <small style="color:lightgrey">[optional]</small> An object containing additional options:
     - `key`:  <small style="color:lightgrey">[optional]</small> ID of text resource to sync with.  Defaults to `req.url`.
   - This is the main method of this library, and does all the work to handle Braid-HTTP `GET` and `PUT` requests concerned with a specific text resource.
@@ -72,21 +76,20 @@ http_server.on("request", (req, res) => {
 `await braid_text.get(key, options)`
   - `key`: ID of text resource.
   - `options`: An object containing additional options, like http headers:
-    - `version`:  <small style="color:lightgrey">[optional]</small> The version to get.
-    - `subscribe: cb`:  <small style="color:lightgrey">[optional]</small> Transforms `get` into a subscription that calls `cb` with each update. The function `cb` is called with the argument `{version, parents, body, patches}` with each update to the text.
-    - `parents`:  <small style="color:lightgrey">[optional]</small> Array of parents — the subscription will only send newer updates than these.
-    - `merge_type`: <small style="color:lightgrey">[optional]</small> When subscribing, identifies the synchronization protocol. Defaults to `simpleton`, but can be set to `dt`.
-    - `peer`: <small style="color:lightgrey">[optional]</small> When subscribing, identifies this peer. Mutations will not be echoed back to the same peer that puts them, if that put also sets the same `peer` header.
-
-  - If we are NOT subscribing, returns `{version, body}`, with the `version` being returned, and the text as `body`. If we are subscribing, this returns nothing.
+    - `version`:  <small style="color:lightgrey">[optional]</small> The [version](https://datatracker.ietf.org/doc/html/draft-toomim-httpbis-braid-http#section-2) to get, as an array of strings.  (The array is typically length 1.)
+    - `parents`:  <small style="color:lightgrey">[optional]</small> The version to start the subscription at, as an array of strings.
+    - `subscribe: cb`:  <small style="color:lightgrey">[optional]</small> Instead of returning the state; [subscribes](https://datatracker.ietf.org/doc/html/draft-toomim-httpbis-braid-http#section-4) to the state, and calls `cb` with the initial state and each update. The function `cb` will be called with a Braid [update](https://datatracker.ietf.org/doc/html/draft-toomim-httpbis-braid-http#section-3) of the form `cb({version, parents, body, patches})`.
+    - `merge_type`: <small style="color:lightgrey">[optional]</small> The CRDT/OT [merge-type](https://raw.githubusercontent.com/braid-org/braid-spec/master/draft-toomim-httpbis-merge-types-00.txt) algorithm to emulate.  Currently supports `"simpleton"` (default) and `"dt"`.
+    - `peer`: <small style="color:lightgrey">[optional]</small> Unique string ID that identifies the peer making the subscription. Mutations will not be echoed back to the same peer that `PUT`s them, for any `PUT` setting the same `peer` header.
+  - If NOT subscribing, returns `{version: <current_version>, body: <current-text>}`. If subscribing, returns nothing.
 
 `await braid_text.put(key, options)`
   - `key`: ID of text resource.
   - `options`: An object containing additional options, like http headers:
-    - `version`:  <small style="color:lightgrey">[optional]</small> The version being supplied. Will be randomly generated if not supplied.
-    - `parents`:  <small style="color:lightgrey">[optional]</small> Array of versions this update depends on. Defaults to the server’s current version.
-    - `body`: <small style="color:lightgrey">[optional]</small> Use this to completely replace the existing text with this new text.
-    - `patches`: <small style="color:lightgrey">[optional]</small> Array of patches, each of the form `{unit: 'text', range: '[1:3]', content: 'hi'}`, which would replace the second and third unicode code-points in the text with `hi`.
+    - `version`:  <small style="color:lightgrey">[optional]</small> The [version](https://datatracker.ietf.org/doc/html/draft-toomim-httpbis-braid-http#section-2) being `PUT`, as an array of strings. Will be generated if not provided.
+    - `parents`:  <small style="color:lightgrey">[optional]</small> The previous version being updated, as array of strings. Defaults to the server’s current version.
+    - `body`: <small style="color:lightgrey">[optional]</small> Use this to completely replace the existing text with this new text.  See Braid [updates](https://datatracker.ietf.org/doc/html/draft-toomim-httpbis-braid-http#section-3).
+    - `patches`: <small style="color:lightgrey">[optional]</small> Array of patches, each of the form `{unit: 'text', range: '[1:3]', content: 'hi'}`, which would replace the second and third unicode code-points in the text with `hi`.  See Braid [Range-Patches](https://github.com/braid-org/braid-spec/blob/master/draft-toomim-httpbis-range-patch-01.txt).
     - `peer`: <small style="color:lightgrey">[optional]</small> Identifies this peer. This mutation will not be echoed back to `get` subscriptions that use this same `peer` header.
 
 ## General Use on Client

package/index.js

@@ -261,7 +261,7 @@ braid_text.get = async (key, options) => {
                 let local_version = OpLog_remote_to_local(resource.doc, x.parents)
                 if (local_version) {
                     x.patches = get_xf_patches(resource.doc, local_version)
-                    if (x.patches.length) options.subscribe(x)
+                    options.subscribe(x)
                 }
             }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "braid-text",
-  "version": "0.0.8",
+  "version": "0.0.10",
   "description": "Library for collaborative text over http using braid.",
   "author": "Braid Working Group",
   "repository": "braid-org/braidjs",

package/server-demo.js

@@ -1,5 +1,5 @@
 
-var port = 8888
+var port = process.argv[2] || 8888
 
 var braid_text = require("./index.js")