braid-text 0.0.9 → 0.0.12

package/README.md

@@ -8,11 +8,16 @@ 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!
+
+Check out the [**demo video**](https://braid.org/video/https://invisiblecollege.s3.us-west-1.amazonaws.com/braid-meeting-86.mp4#4755) 📺 from the Braid 86 release!
+
 ### Demo: a Wiki!
 
 This will run a collaboratively-editable wiki:
@@ -26,8 +31,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 +65,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 +78,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

@@ -1273,29 +1273,23 @@ function codePoints_to_index(str, codePoints) {
 }
 
 function encode_filename(filename) {
-  // Replace all '!' with '%21'
-  let encoded = filename.replace(/!/g, '%21');
-  
-  // Encode the filename using encodeURIComponent()
-  encoded = encodeURIComponent(encoded);
-  
-  // Replace all '%2F' (for '/') with '!'
-  encoded = encoded.replace(/%2F/g, '!');
-  
-  return encoded;
+    // Swap all "!" and "/" characters
+    let swapped = filename.replace(/[!/]/g, (match) => (match === "!" ? "/" : "!"))
+
+    // Encode the filename using encodeURIComponent()
+    let encoded = encodeURIComponent(swapped)
+
+    return encoded
 }
 
 function decode_filename(encodedFilename) {
-  // Replace all '!' with '%2F'
-  let decoded = encodedFilename.replace(/!/g, '%2F');
-  
-  // Decode the filename using decodeURIComponent()
-  decoded = decodeURIComponent(decoded);
-  
-  // Replace all '%21' with '!'
-  decoded = decoded.replace(/%21/g, '!');
-  
-  return decoded;
+    // Decode the filename using decodeURIComponent()
+    let decoded = decodeURIComponent(encodedFilename)
+
+    // Swap all "/" and "!" characters
+    decoded = decoded.replace(/[!/]/g, (match) => (match === "/" ? "!" : "/"))
+
+    return decoded
 }
 
 module.exports = braid_text

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "braid-text",
-  "version": "0.0.9",
+  "version": "0.0.12",
   "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")
 
@@ -11,6 +11,11 @@ var braid_text = require("./index.js")
 var server = require("http").createServer(async (req, res) => {
     console.log(`${req.method} ${req.url}`)
 
+    // Free the CORS
+    free_the_cors(req, res)
+    if (req.method === 'OPTIONS') return
+
+
     if (req.url.endsWith("?editor")) {
         res.writeHead(200, { "Content-Type": "text/html", "Cache-Control": "no-cache" })
         require("fs").createReadStream("./editor.html").pipe(res)
@@ -30,9 +35,6 @@ var server = require("http").createServer(async (req, res) => {
     //     var pages = await braid_text.list()
     //     res.writeHead(200, {
     //         "Content-Type": "application/json",
-    //         "Access-Control-Allow-Origin": "*",
-    //         "Access-Control-Allow-Methods": "*",
-    //         "Access-Control-Allow-Headers": "*",
     //         "Access-Control-Expose-Headers": "*"
     //     })
     //     res.end(JSON.stringify(pages))
@@ -73,3 +75,21 @@ var server = require("http").createServer(async (req, res) => {
 server.listen(port, () => {
     console.log(`server started on port ${port}`)
 })
+
+
+// Free the CORS!
+function free_the_cors (req, res) {
+    res.setHeader('Range-Request-Allow-Methods', 'PATCH, PUT')
+    res.setHeader('Range-Request-Allow-Units', 'json')
+    res.setHeader("Patches", "OK")
+    var free_the_cors = {
+        "Access-Control-Allow-Origin": "*",
+        "Access-Control-Allow-Methods": "OPTIONS, HEAD, GET, PUT, UNSUBSCRIBE",
+        "Access-Control-Allow-Headers": "subscribe, client, version, parents, merge-type, content-type, content-range, patches, cache-control, peer"
+    }
+    Object.entries(free_the_cors).forEach(x => res.setHeader(x[0], x[1]))
+    if (req.method === 'OPTIONS') {
+        res.writeHead(200)
+        res.end()
+    }
+}