braid-text v0.2.3
Collaborative text over Braid-HTTP
This library provides a simple http route handler, along with client code, enabling fast text synchronization over a standard protocol.
- Supports Braid-HTTP protocol
- Supports Simpleton merge-type
- Enables light clients
- As little as 50 lines of code!
- With zero history overhead on client
- Supports backpressure to run smoothly on constrained servers
- Server merges with Diamond-Types
- Enables light clients
- Supports Diamond Types merge-type
- Fully peer-to-peer CRDT
- Fast / Robust / Extensively fuzz-tested
- Developed in 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 📺 from the Braid 86 release!
Demo: a Wiki!
This will run a collaboratively-editable wiki:
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)
- 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, 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:
npm install braid-text
Import the request handler into your code, and use it to handle HTTP requests wherever you want:
var braid_text = require("braid-text")
http_server.on("request", (req, res) => {
// Your server logic...
// Whenever desired, serve braid text for this request/response:
braid_text.serve(req, res)
})
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.
- This folder will be created if it doesn't exist.
- 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
: Incoming HTTP request object.res
: Outgoing HTTP response object.options
: optional An object containing additional options:key
: optional ID of text resource to sync with. Defaults toreq.url
.
- This is the main method of this library, and does all the work to handle Braid-HTTP
GET
andPUT
requests concerned with a specific text resource.
await braid_text.get(key)
key
: ID of text resource.- Returns the text of the resource as a string.
await braid_text.get(key, options)
key
: ID of text resource.options
: An object containing additional options, like http headers:version
: optional The version to get, as an array of strings. (The array is typically length 1.)parents
: optional The version to start the subscription at, as an array of strings.subscribe: cb
: optional Instead of returning the state; subscribes to the state, and callscb
with the initial state and each update. The functioncb
will be called with a Braid update of the formcb({version, parents, body, patches})
.merge_type
: optional The CRDT/OT merge-type algorithm to emulate. Currently supports"simpleton"
(default) and"dt"
.peer
: optional Unique string ID that identifies the peer making the subscription. Mutations will not be echoed back to the same peer thatPUT
s them, for anyPUT
setting the samepeer
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
: optional The version beingPUT
, as an array of strings. Will be generated if not provided.parents
: optional The previous version being updated, as array of strings. Defaults to the server’s current version.body
: optional Use this to completely replace the existing text with this new text. See Braid updates.patches
: optional 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 withhi
. See Braid Range-Patches.peer
: optional Identifies this peer. This mutation will not be echoed back toget
subscriptions that use this samepeer
header.
General Use on Client
<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, such as:
//
// var patches = [{
// range: [5:5],
// content: " 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}
},
})
...
// 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 for a simple working example.
Client API
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:({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
orpatches
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:(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 inapply_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
ornull
.content_type
: optional If set, this value will be sent in theAccept
andContent-Type
headers to the server.
simpleton.changed()
: Call this function to report local updates whenever they occur, e.g., in theoninput
event handler of a textarea being synchronized.
Testing
to run unit tests:
first run the demo server as usual:
npm install
node server-demo.js
then open http://localhost:8888/test.html, and the boxes should turn green as the tests pass.
to run fuzz tests:
npm install
node test.js
if the last output line looks like this, good:
t = 9999, seed = 1397019, best_n = Infinity @ NaN
but it's bad if it looks like this:
t = 9999, seed = 1397019, best_n = 5 @ 1396791
the number at the end is the random seed that generated the simplest error example
11 days ago
10 days ago
10 days ago
11 days ago
21 days ago
24 days ago
2 months ago
2 months ago
3 months ago
3 months ago
2 months ago
3 months ago
3 months ago
3 months ago
4 months ago
4 months ago
4 months ago
4 months ago
4 months ago
4 months ago
4 months ago
5 months ago
5 months ago
5 months ago
5 months ago
6 months ago
6 months ago
6 months ago
6 months ago
6 months ago
6 months ago
6 months ago
6 months ago
6 months ago
6 months ago
6 months ago
6 months ago
6 months ago