braid-text 0.2.47 → 0.2.48

package/README.md

@@ -148,38 +148,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.48",
   "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
 }