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 Sever merges with Diamond-Types
Supports Diamond Types merge-type Fast / Robust / Extensively fuzz-tested
Developed in braid.org
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)
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 : The incoming HTTP request object.
: The incoming HTTP request object. res : The HTTP response object to send the response.
: The HTTP response object to send the response. options : [optional] An object containing additional options: key : [optional] ID of text resource to sync with. Defaults to req.url .
: [optional] An object containing additional options: 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.
await braid_text.get(key)
key : ID of text resource.
: 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. subscribe: cb : [optional] 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 : [optional] Array of parents — the subscription will only send newer updates than these. merge_type : [optional] When subscribing, identifies the synchronization protocol. Defaults to simpleton , but can be set to dt . peer : [optional] 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.
await braid_text.put(key, options)
key : ID of text resource.
: ID of text resource. options : An object containing additional options, like http headers: version : [optional] The version being supplied. Will be randomly generated if not supplied. parents : [optional] Array of versions this update depends on. Defaults to the server’s current version. body : [optional] Use this to completely replace the existing text with this new text. 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 with hi . peer : [optional] Identifies this peer. This mutation will not be echoed back to get subscriptions that use this same peer header.
: An object containing additional options, like http headers:
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 )