braid-text 0.0.1 → 0.0.4

package/README.md

@@ -12,7 +12,25 @@ This library provides a simple http route handler, along with client code, enabl
   - Fast / Robust / Extensively fuzz-tested 
 - Developed in [braid.org](https://braid.org)
 
-## Use the Library on the Server
+### Demo: a Wiki!
+
+This will run a collaboratively-editable wiki:
+
+```shell
+npm install
+node server-demo.js
+```
+
+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)
+
+Or try opening the URL in [Braid-Chrome](https://github.com/braid-org/braid-chrome), or another Braid client, 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.
+
+## General Use on Server
 
 Install it in your project:
 ```shell
@@ -32,25 +50,7 @@ server.on("request", (req, res) => {
 })
 ```
 
-## Run the Demo
-
-This will run a collaboratively-editable wiki:
-
-```shell
-npm install
-node server-demo.js
-```
-
-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)
-
-Or try opening the URL in [Braid-Chrome](https://github.com/braid-org/braid-chrome), or another Braid client, 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.
-
-## Full Server Library API
+## Server API
 
 `braid_text.db_folder = './braid-text-db' // <-- this is the default`
   - This is where the Diamond-Types history files will be stored for each resource.
@@ -88,35 +88,78 @@ Check out the `server-demo.js` file to see examples for how to add access contro
     - `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`.
     - `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.
 
-## Use the Library on the Client
+## General Use on Client
 
-    <script src="https://unpkg.com/braid-text/client.js"></script>
-    
-    ...
-    // connect to the server
-    let braid_text = braid_text_client(SERVER_URL, {
-      apply_remote_update: ({ state, patches }) => {
-        // apply incoming state / return new state
-      },
-      generate_local_diff_update: (prev_state) => {
-        // report changes between prev_state and the current state
-      },
-    });
+```html
+<script src="https://unpkg.com/braid-text/simpleton-client.js"></script>
+<script>
+
+  // connect to the server
+  let simpleton = simpleton_client('https://example.org/some-resource', {
+    apply_remote_update: ({ state, patches }) => {
+
+      // Apply the incoming state or patches to local text here.
+
+      // Then return the new state of textarea as a string:
+      return new_state
+    },
+    generate_local_diff_update: (prev_state) => {
+
+      // Compute diff between prev_state ^ and the current textarea string...
+
+      // Then return the new state (as a string) and the diff (as `patches`)
+      return {new_state, patches}
+    },
+  })
     
-    ...
+  ...
     
-    // when changes are made, let braid-text know
-    braid_text.changed()
+  // When changes occur in client's textarea, let simpleton know,
+  // so that it can call generate_local_diff_update() to ask for them.
+  simpleton.changed()
+
+</script>
+```
 
 See [editor.html](https://raw.githubusercontent.com/braid-org/braid-text/master/editor.html) for a simple working example.
 
-## Full Client Library API
+## Client API
+
+```javascript
+simpleton = simpleton_client(url, options)
+```
+
+- `url`: The URL of the resource to synchronize with.
+- `options`: An object containing the following properties:
+  - `apply_remote_update`: A function that will be called whenever an update is received from the server. It should have the following signature:
+
+    ```javascript
+    ({state, patches}) => {...}
+    ```
+
+    - `state`: If present, represents the new value of the text.
+    - `patches`: If present, an array of patch objects, each representing a string-replace operation. Each patch object has the following properties:
+      - `range`: An array of two numbers, `[start, end]`, specifying the start and end positions of the characters to be deleted.
+      - `content`: The text to be inserted in place of the deleted characters.
+
+    Note that patches will always be in order, but the range positions of each patch reference the original string, i.e., the second patch's range values do not take into account the application of the first patch.
+
+    The function should apply the `state` or `patches` to the local text and return the new state.
+
+  - `generate_local_diff_update`: A function that will be called whenever a local update occurs, but may be delayed if the network is congested. It should have the following signature:
+
+    ```javascript
+    (prev_state) => {...}
+    ```
+
+    The function should calculate the difference between `prev_state` and the current state, and express this difference as an array of patches (similar to the ones described in `apply_remote_update`).
+
+    If a difference is detected, the function should return an object with the following properties:
+    - `new_state`: The current state of the text.
+    - `patches`: An array of patch objects representing the changes.
+
+    If no difference is detected, the function should return `undefined` or `null`.
 
-    braid_text = braid_text_client(url, {
-      apply_remote_update,
-      generate_local_diff_update}
+  - `content_type`: <small style="color:lightgrey">[optional]</small> If set, this value will be sent in the `Accept` and `Content-Type` headers to the server.
 
-  - `url`: The url of the resource to synchronize with.
-  - `apply_remote_update`: This function will be called whenever an update is received from the server. The function should look like `({state, patches}) => {...}`. Only one of `state` or `patches` will be set. If it is `state`, then this is the new value of the text. If it is `patches`, then patches is an array of values like `{range: [1, 3], content: "Hi"}`. Each such value represents a string-replace operation; the `range` specifies a start and end position — these characters will be deleted — and `content` says what text to put in its place. Note that these patches will always be in order, but that the range positions of each patch always reference the original string, e.g., the second patch's range values do not take into account applying the first patch. Finally, this function returns the new state, after the application of the `state` or `patches`.
-  - `generate_local_diff_update`: This function will often be called whenever an update happens locally, but the system may delay calling it if the network is congested. The function should look like `(prev_state) => {...}`. The function should basically do a diff between `prev_state` and the current state, and express this diff as an array of patches similar to the ones discussed above. Finally, if there is an actual difference detected, this function should return an object `{state, patches}`, otherwise it should return nothing.
-  - `braid_text.changed()`: Call this to report local updates whenever they occur, e.g., in the `oninput` handler of a textarea being synchronized.
+- `simpleton.changed()`: Call this function to report local updates whenever they occur, e.g., in the `oninput` event handler of a textarea being synchronized.

package/editor.html

@@ -6,9 +6,9 @@
 </body>
 <script src="https://braid.org/code/myers-diff1.js"></script>
 <script src="https://unpkg.com/braid-http@~0.3/braid-http-client.js"></script>
-<script src="https://unpkg.com/braid-text/client.js"></script>
+<script src="https://unpkg.com/braid-text/simpleton-client.js"></script>
 <script>
-  let braid_text = braid_text_client(location.pathname, {
+  let simpleton = simpleton_client(location.pathname, {
     apply_remote_update: ({ state, patches }) => {
       if (state !== undefined) texty.value = state;
       else apply_patches_and_update_selection(texty, patches);
@@ -17,12 +17,12 @@
     generate_local_diff_update: (prev_state) => {
       var patches = diff(prev_state, texty.value);
       if (patches.length === 0) return null;
-      return { patches, state: texty.value };
+      return { patches, new_state: texty.value };
     },
   });
 
   texty.value = "";
-  texty.oninput = (e) => braid_text.changed();
+  texty.oninput = (e) => simpleton.changed();
 
   function diff(before, after) {
     let diff = diff_main(before, after);

package/markdown-editor.html

@@ -16,19 +16,17 @@ dom.BODY = -> DIV(WIKI())
 <script>
     window.fetch = window.statebus_fetch
 </script>
-<script src="https://unpkg.com/braid-text/client.js"></script>
+<script src="https://unpkg.com/braid-text/simpleton-client.js"></script>
 
 <script>
 
-var apply_patches_and_update_selection, diff, first_time, i, j, render_delay, scroll, braid_text_key, t, timer, ting, toggle_editor, update_markdown, update_markdown_later;
-
-braid_text_key = location.pathname;
+var apply_patches_and_update_selection, diff, first_time, i, j, render_delay, scroll, t, timer, ting, toggle_editor, update_markdown, update_markdown_later;
 
 t = function() {
   return document.getElementById('the editor');
 };
 
-var braid_text = braid_text_client(braid_text_key, {
+var simpleton = simpleton_client(location.pathname, {
   apply_remote_update: function(x) {
     if (x.state !== void 0) {
       t().value = x.state;
@@ -47,7 +45,7 @@ var braid_text = braid_text_client(braid_text_key, {
     }
     return {
       patches: patches,
-      state: t().value
+      new_state: t().value
     };
   }
 });
@@ -188,7 +186,7 @@ dom.WIKI = function() {
       }
       // Bail on edits that try to wipe us out
       state.source = e.target.value;
-      braid_text.changed();
+      simpleton.changed();
       return update_markdown_later();
     },
     defaultValue: state.source

package/package.json

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

package/{client.js → simpleton-client.js}

@@ -9,15 +9,15 @@
 //
 // generate_local_diff_update: (prev_state) => {...}
 //     this is to generate outgoing changes,
-//     and if there are changes, returns { patches, state }
+//     and if there are changes, returns { patches, new_state }
 //
-// content_type: overrides the Accept and Content-Type headers
+// content_type: used for Accept and Content-Type headers
 //
 // returns { changed(): (diff_function) => {...} }
 //     this is for outgoing changes;
 //     diff_function = () => ({patches, new_version}).
 //
-function braid_text_client(url, { apply_remote_update, generate_local_diff_update, content_type }) {
+function simpleton_client(url, { apply_remote_update, generate_local_diff_update, content_type }) {
     var peer = Math.random().toString(36).substr(2)
     var current_version = []
     var prev_state = ""
@@ -74,7 +74,7 @@ function braid_text_client(url, { apply_remote_update, generate_local_diff_updat
         while (true) {
             var update = generate_local_diff_update(prev_state)
             if (!update) return   // Stop if there wasn't a change!
-            var {patches, state} = update
+            var {patches, new_state} = update
 
             // convert from js-indicies to code-points
             let c = 0
@@ -103,7 +103,7 @@ function braid_text_client(url, { apply_remote_update, generate_local_diff_updat
 
             var parents = current_version
             current_version = version
-            prev_state = state
+            prev_state = new_state
 
             outstanding_changes++
             await braid_fetch_wrapper(url, {