braid-text 0.3.22 → 0.3.24

package/README.md

@@ -69,11 +69,13 @@ http_server.on("request", (req, res) => {
   - `res`: Outgoing HTTP response object.
   - `options`: <small style="color:lightgrey">[optional]</small> An object containing additional options:
     - `key`:  <small style="color:lightgrey">[optional]</small> ID of text resource to sync with.  Defaults to `req.url`.
-    - `put_cb`: <small style="color:lightgrey">[optional]</small> Callback invoked after a PUT changes a resource. Signature: `(key, val, old_val, patches)` where:
+    - `put_cb`: <small style="color:lightgrey">[optional]</small> Callback invoked after a PUT changes a resource. Signature: `(key, val, {old_val, patches, version, parents})` where:
       - `key` - The resource key
       - `val` - The new document text after the PUT
       - `old_val` - The document text before the PUT
       - `patches` - Array of patches applied (each `{unit, range, content}`), or `null` for full-body replacements
+      - `version` - The version after the PUT
+      - `parents` - The version prior to the PUT
   - 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)`

package/client/cursor-highlights.js

@@ -297,7 +297,7 @@ function peer_bg_color(peer_id) {
 //   cursors.on_edit(patches)      // call after local edit; patches optional
 //   cursors.destroy()
 //
-function cursor_highlights(textarea, url) {
+function cursor_highlights(textarea, url, options) {
     var peer = Math.random().toString(36).slice(2)
     var hl = textarea_highlights(textarea)
     var applying_remote = false
@@ -307,6 +307,7 @@ function cursor_highlights(textarea, url) {
 
     cursor_client(url, {
         peer,
+        headers: options?.headers,
         get_text: () => textarea.value,
         on_change: (sels) => {
             for (var [id, ranges] of Object.entries(sels)) {

package/client/cursor-sync.js

@@ -15,12 +15,12 @@
 //   cursors.changed(patches)
 //   cursors.destroy()
 //
-async function cursor_client(url, { peer, get_text, on_change }) {
+async function cursor_client(url, { peer, get_text, on_change, headers: user_headers }) {
     // --- feature detection: HEAD probe ---
     try {
         var head_res = await braid_fetch(url, {
             method: 'HEAD',
-            headers: { 'Accept': 'application/text-cursors+json' }
+            headers: { ...user_headers, 'Accept': 'application/text-cursors+json' }
         })
         var ct = head_res.headers.get('content-type') || ''
         if (!ct.includes('application/text-cursors+json')) return null
@@ -124,6 +124,7 @@ async function cursor_client(url, { peer, get_text, on_change }) {
         braid_fetch(url, {
             method: 'PUT',
             headers: {
+                ...user_headers,
                 'Content-Type': 'application/text-cursors+json',
                 Peer: peer,
                 'Content-Range': 'json [' + JSON.stringify(peer) + ']',
@@ -155,6 +156,7 @@ async function cursor_client(url, { peer, get_text, on_change }) {
         }},
         peer,
         headers: {
+            ...user_headers,
             Accept: 'application/text-cursors+json',
             Heartbeats: '10',
         },

package/client/simpleton-sync.js

@@ -12,6 +12,8 @@
 //
 // url: resource endpoint
 //
+// headers:  custom headers that get forwarded through into the fetch
+//
 // on_patches?: (patches) => void
 //     processes incoming patches by applying them to the UI/textarea.
 //     Patches are guaranteed to be in-order and non-overlapping.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "braid-text",
-  "version": "0.3.22",
+  "version": "0.3.24",
   "description": "Library for collaborative text over http using braid.",
   "author": "Braid Working Group",
   "repository": "braid-org/braid-text",
@@ -9,8 +9,10 @@
     "test": "node test/test.js"
   },
   "main": "server.js",
+  "types": "server.d.ts",
   "files": [
     "server.js",
+    "server.d.ts",
     "simpleton-client.js",
     "client/simpleton-sync.js",
     "client/cursor-sync.js",

package/server.d.ts

@@ -0,0 +1,44 @@
+import { IncomingMessage, ServerResponse } from 'http'
+
+interface PutCallbackParams {
+  old_val: string
+  patches: Array<{ unit: string; range: string; content: string }> | null
+  version: string[]
+  parents: string[]
+}
+
+interface ServeOptions {
+  key?: string
+  put_cb?: (key: string, val: string, params: PutCallbackParams) => void
+}
+
+interface GetResult {
+  version: string[]
+  body: string | Uint8Array
+}
+
+interface Resource {
+  key: string
+  val: string
+  version: string[]
+}
+
+interface BraidText {
+  verbose: boolean
+  db_folder: string | null
+  cors: boolean
+  cache: Record<string, Promise<Resource>>
+
+  serve(req: IncomingMessage, res: ServerResponse, options?: ServeOptions): Promise<void>
+  get(key: string): Promise<string | null>
+  get(key: string, options: Record<string, any>): Promise<GetResult>
+  put(key: string, options: Record<string, any>): Promise<{ change_count: number }>
+  delete(key: string): Promise<void>
+  list(): Promise<string[]>
+  sync(a: string, b: string | URL, options?: Record<string, any>): Promise<void>
+  free_cors(res: ServerResponse): void
+  create_braid_text(): BraidText
+}
+
+declare const braidText: BraidText
+export = braidText

package/server.js

@@ -345,7 +345,7 @@ function create_braid_text() {
     braid_text.serve = async (req, res, options = {}) => {
         options = {
             key: req.url.split('?')[0], // Default key
-            put_cb: (key, val, old_val, patches) => { },  // Default callback when a PUT changes a key
+            put_cb: (key, val, params) => { },  // Default callback when a PUT changes a key
             ...options                  // Override with all options passed in
         }
 
@@ -556,6 +556,7 @@ function create_braid_text() {
                 }
 
                 var old_val = resource.val
+                var old_version = resource.version
                 var put_patches = patches ? patches.map(p => ({unit: p.unit, range: p.range, content: p.content})) : null
                 var {change_count} = await braid_text.put(resource, { peer, version: req.version, parents: req.parents, patches, body, merge_type })
 
@@ -577,7 +578,9 @@ function create_braid_text() {
             
                 res.setHeader("Version", get_current_version())
 
-                options.put_cb(options.key, resource.val, old_val, put_patches)
+                options.put_cb(options.key, resource.val,
+                               {old_val, patches: put_patches,
+                                version: resource.version, parents: old_version})
             } catch (e) {
                 console.log(`${req.method} ERROR: ${e.stack}`)
                 return done_my_turn(500, "The server failed to apply this version. The error generated was: " + e)
@@ -3113,12 +3116,17 @@ async function handle_cursors(resource, req, res) {
             res.sendUpdate({ body: JSON.stringify(cursors.snapshot()) })
         }
     } else if (req.method === 'PUT' || req.method === 'POST' || req.method === 'PATCH') {
-        var raw_body = await new Promise((resolve, reject) => {
-            var chunks = []
-            req.on('data', chunk => chunks.push(chunk))
-            req.on('end', () => resolve(Buffer.concat(chunks).toString()))
-            req.on('error', reject)
-        })
+        var raw_body
+        if (req.already_buffered_body != null) {
+            raw_body = req.already_buffered_body.toString()
+        } else {
+            raw_body = await new Promise((resolve, reject) => {
+                var chunks = []
+                req.on('data', chunk => chunks.push(chunk))
+                req.on('end', () => resolve(Buffer.concat(chunks).toString()))
+                req.on('error', reject)
+            })
+        }
         var range = req.headers['content-range']
         if (!range || !range.startsWith('json ')) {
             res.writeHead(400)