braid-text 0.2.47 → 0.2.49

package/README.md

@@ -37,7 +37,7 @@ Or try opening the URL in [Braid-Chrome](https://github.com/braid-org/braid-chro
 
 Check out the `server-demo.js` file to see examples for how to add simple access control, where a user need only enter a password into a cookie in the javascript console like: `document.cookie = 'password'`; and a `/pages` endpoint to show all the edited pages.
 
-## General Use on Server
+## General Use as Server
 
 Install it in your project:
 ```shell
@@ -94,51 +94,52 @@ http_server.on("request", (req, res) => {
     - `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
+## General Use as Client
+
+Here's a basic running example to start:
 
 ```html
+<!-- 1. Your textarea -->
+<textarea id="my_textarea"></textarea>
+
+<!-- 2. Include the library -->
+<script src="https://unpkg.com/braid-http@~1.3/braid-http-client.js"></script>
 <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.
-      //
-      // Example data:
-      //   state: "Hello World"                               // The new text
-      //   patches: [{ range: [5, 5], content: " World" }]    // Patches that create the new text
-      //
-      // 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, such as:
-      //
-      //   var patches = [{
-      //     range: [5, 5],      // The range from position 5 to position 5
-      //     content: " World"   // is replaced with the string " World"
-      //   }]
-      //
-      // ...to insert something after a prev_state of "Hello".
-
-      // Then return the new state (as a string) and the diff (as `patches`)
-      return {new_state, patches}
-    },
+<!-- 3. Wire it up -->
+<script>
+  // Connect to server
+  var simpleton = simpleton_client('https://braid.org/simpleton_example', {
+    on_state: state => my_textarea.value = state,  // incoming changes
+    get_state: () => my_textarea.value             // outgoing changes
   })
-    
-  ...
-    
-  // 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()
 
+  // Tell simpleton when user types
+  my_textarea.oninput = () => simpleton.changed()
 </script>
 ```
 
-See [editor.html](https://raw.githubusercontent.com/braid-org/braid-text/master/editor.html) for a simple working example.
+You should see something if you run this (though the server in that example will likely ignore your changes). 
+
+The basic idea is that you create a simpleton_client and tell it to connect to a url. Any incoming changes trigger the `on_state` callback. For outgoing changes, you'd think we would tell simpleton the new state when we get the `oninput` event — however, the network may be backed up, and simpleton wants to hold off on sending more updates. So instead, we just inform simpleton that a change has occurred and let it handle when to actually send the change to the server. 
+
+This decoupling between `simpleton.changed` and `get_state` is especially helpful when disconnecting from the server for extended periods (like getting on a plane for a couple hours). Without it, simpleton would have queued up a message for every change made during those two hours and try to send them all upon reconnection. With the decoupling, simpleton can wait until reconnection and then request a single diff to the new final state.
+
+### Finer-Grained Integration
+
+There are a couple ways to do a more fine-grained integration:
+
+**1. Receiving patches instead of full state**
+
+Rather than receiving a completely new state in `on_state`, you can receive just changes to the current state in `on_patches`, as an array of patches. This can be more efficient, especially if you're integrating with an editor that has an API for making edits (rather than needing to set the whole string, as with an HTML textarea). Even with a textarea though, getting patches can be helpful for updating the cursor or selection position.
+
+**2. Supplying custom patch generation**
+
+Rather than only supplying `get_state`, you can also supply `get_patches` — a function that accepts a string representing the document at some point in the past and returns an array of patches to get from there to the current state. 
+
+Simpleton has a default simple way of computing this (scanning for a common prefix and suffix), but you may have a better function that handles complex cases. For example, when a user pastes in what seems like a large change that replaces the entire document, proper diff analysis might reveal it's just a few edits here and there. Also, with some editors, the analogous `oninput` event may provide patches for free, making `get_patches` more efficient.
+
+You can see an example of both these finer-grained integration techniques here: [editor.html](https://raw.githubusercontent.com/braid-org/braid-text/master/editor.html).
 
 ## Client API
 
@@ -148,38 +149,59 @@ 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:
+
+  ### Incoming Updates
+
+  - `on_patches`: <small style="color:lightgrey">[optional]</small> A function called when patches are received from the server:
 
     ```javascript
-    ({state, patches}) => {...}
+    (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:
+    - `patches`: An array of patch objects, each representing a string-replace operation. Each patch object has:
       - `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.
+  - `on_state`: <small style="color:lightgrey">[optional]</small> A function called when a complete state update is received from the server:
+
+    ```javascript
+    (state) => {...}
+    ```
+
+    - `state`: The new complete value of the text.
+
+  ### Local State Management
 
-  - `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:
+  - `get_state`: **[required]** A function that returns the current state of the text:
 
     ```javascript
-    (prev_state) => {...}
+    () => current_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`).
+  - `get_patches`: <small style="color:lightgrey">[optional]</small> A function that generates patches representing changes between a previous state and the current state:
 
-    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.
+    ```javascript
+    (prev_state) => patches
+    ```
 
-    If no difference is detected, the function should return `undefined` or `null`.
+    Returns an array of patch objects representing the changes. The default implementation finds a common prefix and suffix for a simple diff, but you can provide a more sophisticated implementation or track patches directly from your editor.
+
+  ### Other Options
 
   - `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.
 
-- `simpleton.changed()`: Call this function to report local updates whenever they occur, e.g., in the `oninput` event handler of a textarea being synchronized.
+### Methods
+
+- `simpleton.changed()`: Call this function to report local updates whenever they occur, e.g., in the `oninput` event handler of a textarea being synchronized. The system will call `get_patches` when it needs to send updates to the server.
+
+### Deprecated Options
+
+The following options are deprecated and should be replaced with the new API:
+
+- ~~`apply_remote_update`~~ → Use `on_patches` and `on_state` instead
+- ~~`generate_local_diff_update`~~ → Use `get_patches` and `get_state` instead
 
 ## Testing
 

package/editor.html

@@ -9,16 +9,9 @@
 <script src="/simpleton-client.js"></script>
 <script>
   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);
-      return texty.value;
-    },
-    generate_local_diff_update: (prev_state) => {
-      var patches = diff(prev_state, texty.value);
-      if (patches.length === 0) return null;
-      return { patches, new_state: texty.value };
-    },
+    on_patches: (patches) => apply_patches_and_update_selection(texty, patches),
+    get_patches: (prev_state) => diff(prev_state, texty.value),
+    get_state: () => texty.value,
     on_error: (e) => {
       texty.disabled = true
       texty.style.background = '#fee'

package/markdown-editor.html

@@ -27,27 +27,14 @@ t = function() {
 };
 
 var simpleton = simpleton_client(location.pathname, {
-  apply_remote_update: function(x) {
-    if (x.state !== void 0) {
-      t().value = x.state;
-    } else {
-      apply_patches_and_update_selection(t(), x.patches);
-    }
+  on_patches: (patches) => {
+    apply_patches_and_update_selection(t(), patches);
     state.source = t().value;
     update_markdown_later();
-    return t().value;
-  },
-  generate_local_diff_update: function(prev_state) {
-    var patches;
-    patches = diff(prev_state, t().value);
-    if (patches.length === 0) {
-      return null;
-    }
-    return {
-      patches: patches,
-      new_state: t().value
-    };
   },
+  get_patches: (prev_state) => diff(prev_state, t().value),
+  get_state: () => t().value,
+
   on_error: (e) => {
     t().disabled = true
     t().style.background = '#fee'

package/package.json

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

package/simpleton-client.js

@@ -2,22 +2,51 @@
 // 
 // url: resource endpoint
 //
-// apply_remote_update: ({patches, state}) => {...}
+// on_patches?: (patches) => void
+//     processes incoming patches
+//
+// on_state?: (state) => void
+//     processes incoming state
+//
+// get_patches?: (prev_state) => patches
+//     returns patches representing diff
+//       between prev_state and current state,
+//     which are guaranteed to be different
+//       if this method is being called
+//     (the default does this in a fast/simple way,
+//      finding a common prefix and suffix,
+//      but you can supply something better,
+//      or possibly keep track of patches as they come from your editor)
+//
+// get_state: () => current_state
+//     returns the current state
+//
+// [DEPRECATED] apply_remote_update: ({patches, state}) => {...}
 //     this is for incoming changes;
 //     one of these will be non-null,
 //     and can be applied to the current state.
 //
-// generate_local_diff_update: (prev_state) => {...}
+// [DEPRECATED] generate_local_diff_update: (prev_state) => {...}
 //     this is to generate outgoing changes,
 //     and if there are changes, returns { patches, new_state }
 //
 // content_type: used for Accept and Content-Type headers
 //
-// returns { changed(): (diff_function) => {...} }
-//     this is for outgoing changes;
-//     diff_function = () => ({patches, new_version}).
+// returns { changed }
+//     call changed whenever there is a local change,
+//     and the system will call get_patches when it needs to.
 //
-function simpleton_client(url, { apply_remote_update, generate_local_diff_update, content_type, on_error, on_res }) {
+function simpleton_client(url, {
+    on_patches,
+    on_state,
+    get_patches,
+    get_state,
+    apply_remote_update, // DEPRECATED
+    generate_local_diff_update, // DEPRECATED
+    content_type,
+    on_error,
+    on_res
+}) {
     var peer = Math.random().toString(36).substr(2)
     var current_version = []
     var prev_state = ""
@@ -69,7 +98,19 @@ function simpleton_client(url, { apply_remote_update, generate_local_diff_update
                     }
                 }
 
-                prev_state = apply_remote_update(update)
+                if (apply_remote_update) {
+                    // DEPRECATED
+                    prev_state = apply_remote_update(update)
+                } else {
+                    var patches = update.patches ||
+                        [{range: [0, 0], content: update.state}]
+                    if (on_patches) {
+                        on_patches(patches)
+                        prev_state = get_state()
+                    } else prev_state = apply_patches(prev_state, patches)
+                }
+
+                if (on_state) on_state(prev_state)
             }
         }, on_error)
     }).catch(on_error)
@@ -81,9 +122,17 @@ function simpleton_client(url, { apply_remote_update, generate_local_diff_update
       changed: async () => {
         if (outstanding_changes >= max_outstanding_changes) return
         while (true) {
-            var update = generate_local_diff_update(prev_state)
-            if (!update) return   // Stop if there wasn't a change!
-            var {patches, new_state} = update
+            if (generate_local_diff_update) {
+                // DEPRECATED
+                var update = generate_local_diff_update(prev_state)
+                if (!update) return   // Stop if there wasn't a change!
+                var {patches, new_state} = update
+            } else {
+                var new_state = get_state()
+                if (new_state === prev_state) return // Stop if there wasn't a change!
+                var patches = get_patches ? get_patches(prev_state) :
+                    [simple_diff(prev_state, new_state)]
+            }
 
             // convert from js-indicies to code-points
             let c = 0
@@ -133,18 +182,42 @@ function simpleton_client(url, { apply_remote_update, generate_local_diff_update
         }
       }
     }
-}
 
-function get_char_size(s, i) {
-    const charCode = s.charCodeAt(i)
-    return (charCode >= 0xd800 && charCode <= 0xdbff) ? 2 : 1
-}
+    function get_char_size(s, i) {
+        const charCode = s.charCodeAt(i)
+        return (charCode >= 0xd800 && charCode <= 0xdbff) ? 2 : 1
+    }
+
+    function count_code_points(str) {
+        let code_points = 0
+        for (let i = 0; i < str.length; i++) {
+            if (str.charCodeAt(i) >= 0xd800 && str.charCodeAt(i) <= 0xdbff) i++
+            code_points++
+        }
+        return code_points
+    }
+
+    function simple_diff(a, b) {
+        // Find common prefix
+        var p = 0
+        var len = Math.min(a.length, b.length)
+        while (p < len && a[p] === b[p]) p++
 
-function count_code_points(str) {
-    let code_points = 0
-    for (let i = 0; i < str.length; i++) {
-        if (str.charCodeAt(i) >= 0xd800 && str.charCodeAt(i) <= 0xdbff) i++
-        code_points++
+        // Find common suffix (from what remains after prefix)
+        var s = 0
+        len -= p
+        while (s < len && a[a.length - s - 1] === b[b.length - s - 1]) s++
+
+        return {range: [p, a.length - s], content: b.slice(p, b.length - s)}
+    }
+
+    function apply_patches(state, patches) {
+        var offset = 0
+        for (var p of patches) {
+            state = state.substring(0, p.range[0] + offset) + p.content + 
+                    state.substring(p.range[1] + offset)
+            offset += p.content.length - (p.range[1] - p.range[0])
+        }
+        return state
     }
-    return code_points
 }