braid-blob 0.0.70 → 0.0.72

package/README.md

@@ -46,7 +46,7 @@ node server-demo.js
 
 Now open up http://localhost:8888 in your browser, to see the client.  Open two windows.  You can drag and drop images between them, and they will always stay synchronized.
 
-<video src="https://github.com/user-attachments/assets/9416e06b-143a-4b3a-a840-b6484f2571b1" controls width="600"></video>
+<video src="https://github.com/user-attachments/assets/24f7be18-87ec-417d-bab5-beee48c5c442" controls width="600"></video>
 
 ## Network API
 
@@ -56,8 +56,8 @@ Braid-blob speaks [Braid-HTTP](https://github.com/braid-org/braid-spec), an exte
 
 | Header | Description |
 |--------|-------------|
-| `Version` | Unique identifier for this version of the blob (e.g., `"1768467700000"`) |
-| `Version-Type` | How to interpret the structure of version strings (e.g., [`relative-wallclock`](https://braid.org/protocol/version-types/relative-wallclock)); see [Version-Type spec](https://github.com/braid-org/braid-spec/blob/master/draft-toomim-httpbis-versions-03.txt) |
+| `Version` | Unique identifier for this version of the blob (e.g., `"1768467700.000"`) |
+| `Version-Type` | How to interpret the structure of version strings (e.g., [`wallclockish`](https://braid.org/protocol/version-types/wallclockish)); see [Version-Type spec](https://github.com/braid-org/braid-spec/blob/master/draft-toomim-httpbis-versions-03.txt) |
 | `Parents` | The previous version |
 | `Merge-Type` | How conflicts resolve consistently (*e.g.* `aww` for [arbitrary-writer-wins](https://braid.org/protocol/merge-types/aww)) |
 | `Subscribe` | In GET, subscribes client to all future changes |
@@ -74,8 +74,8 @@ Response:
 
 ```http
 HTTP/1.1 200 OK
-Version: "1768467700000"
-Version-Type: relative-wallclock
+Version: "1768467700.000"
+Version-Type: wallclockish
 Content-Type: image/png
 Merge-Type: aww
 Accept-Subscribe: true
@@ -100,12 +100,12 @@ Response (keeps connection open, streams updates):
 ```http
 HTTP/1.1 209 Multiresponse
 Subscribe: true
-Current-Version: "1768467700000"
-Version-Type: relative-wallclock
+Current-Version: "1768467700.000"
+Version-Type: wallclockish
 
 HTTP 200 OK
-Version: "1768467700000"
-Version-Type: relative-wallclock
+Version: "1768467700.000"
+Version-Type: wallclockish
 Content-Type: image/png
 Merge-Type: aww
 Content-Length: 12345
@@ -113,8 +113,8 @@ Content-Length: 12345
 <binary data>
 
 HTTP 200 OK
-Version: "1768467701000"
-Version-Type: relative-wallclock
+Version: "1768467700.100"
+Version-Type: wallclockish
 Content-Type: image/png
 Merge-Type: aww
 Content-Length: 23456
@@ -129,8 +129,8 @@ If the blob doesn't exist yet, `Current-Version` will be blank and no initial up
 
 ```http
 PUT /blob.png HTTP/1.1
-Version: "1768467702000"
-Version-Type: relative-wallclock
+Version: "1768467700.200"
+Version-Type: wallclockish
 Content-Type: image/png
 Merge-Type: aww
 Content-Length: 34567
@@ -142,8 +142,8 @@ Response:
 
 ```http
 HTTP/1.1 200 OK
-Current-Version: "1768467702000"
-Version-Type: relative-wallclock
+Current-Version: "1768467700.200"
+Version-Type: wallclockish
 ```
 
 If the sent version is older or eclipsed by the server's current version, the returned `Current-Version` will be the server's version (not the one you sent).
@@ -168,9 +168,9 @@ Returns `200 OK` even if the blob didn't exist.
 
 Braid-blob uses two complementary mechanisms for distributed consistency:
 
-**Version-Type: [`relative-wallclock`](https://braid.org/protocol/version-types/relative-wallclock)** defines the format and interpretation of version identifiers:
-- Versions are millisecond timestamps (e.g., `"1768467700000"`)
-- If the current time is behind the latest known version, a small random number (1-1000) is added to the current version, providing entropy when multiple peers write simultaneously
+**Version-Type: [`wallclockish`](https://braid.org/protocol/version-types/wallclockish)** defines the format and interpretation of version identifiers:
+- Versions are seconds since the epoch with decimal precision (e.g., `"1768467700.000"`)
+- If the current time is behind the latest known version, a small random decimal is added to the current version, providing entropy when multiple peers write simultaneously
 - Versions are compared numerically—larger timestamps are newer
 
 **Merge-Type: [`aww`](https://braid.org/protocol/merge-types/aww)** (arbitrary-writer-wins) defines how conflicts are resolved:
@@ -205,7 +205,7 @@ var {body, version, content_type} = await braid_blob.get(new URL('https://foo.ba
 // Get a specific version of a remote blob:
 var {body} = await braid_blob.get(
     new URL('https://foo.bar/baz'),
-    {version: ['1768467700000']}
+    {version: ['1768467700.000']}
 )
 
 // To subscribe to a remote blob, without storing updates locally:
@@ -258,8 +258,8 @@ Retrieves a blob from local storage or a remote URL.
 Parameters:
 - `key` - The local blob (if string) or remote URL (if [URL object](https://nodejs.org/api/url.html#class-url)) to read from
 - `params` - Optional configuration object
-  - `version` - Retrieve a specific version instead of the latest (e.g., `['1768467700000']`)
-  - `parents` - When subscribing, only receive updates newer than this version (e.g., `['1768467700000']`)
+  - `version` - Retrieve a specific version instead of the latest (e.g., `['1768467700.000']`)
+  - `parents` - When subscribing, only receive updates newer than this version (e.g., `['1768467700.000']`)
   - `subscribe` - Callback `(update) => {}` called with each update; `update` has `{body, version, content_type}`
   - `head` - If `true`, returns only metadata (`{version, content_type}`) without the body—useful for checking if a blob exists or getting its current version
   - `content_type` - Expected content type (sent as Accept header for remote URLs)
@@ -275,7 +275,7 @@ Parameters:
 - `key` - The local blob (if string) or remote URL (if [URL object](https://nodejs.org/api/url.html#class-url)) to write to
 - `body` - The data to store (Buffer, ArrayBuffer, or Uint8Array)
 - `params` - Optional configuration object
-  - `version` - Specify a version ID for this write (e.g., `['1768467700000']`); if omitted, one is generated automatically
+  - `version` - Specify a version ID for this write (e.g., `['1768467700.000']`); if omitted, one is generated automatically
   - `content_type` - MIME type of the blob (e.g., `'image/png'`, `'application/json'`)
   - `signal` - AbortSignal to cancel the request
 
@@ -311,7 +311,7 @@ Parameters:
 
 ## Browser Client API
 
-A simple browser client is included for subscribing to blob updates.
+A simple browser client (`client.js`) is included for subscribing to blob updates. Here's how to use it:
 
 ```html
 <script src="https://unpkg.com/braid-http@~1.3/braid-http-client.js"></script>

package/client.js

@@ -70,78 +70,69 @@ function braid_blob_client(url, params = {}) {
         if (!a) a = ''
         if (!b) b = ''
 
-        var c = compare_seqs(get_event_seq(a), get_event_seq(b))
-        if (c) return c
+        // Check if values match wallclockish format
+        var re = compare_events.re || (compare_events.re = /^-?[0-9]*\.[0-9]*$/)
+        var a_match = re.test(a)
+        var b_match = re.test(b)
+
+        // If only one matches, it wins
+        if (a_match && !b_match) return 1
+        if (b_match && !a_match) return -1
+
+        // If neither matches, compare lexicographically
+        if (!a_match && !b_match) {
+            if (a < b) return -1
+            if (a > b) return 1
+            return 0
+        }
 
-        if (a < b) return -1
-        if (a > b) return 1
-        return 0
-    }
+        // Both match - compare as decimals using BigInt
+        // Add decimal point if missing
+        if (a.indexOf('.') === -1) a += '.'
+        if (b.indexOf('.') === -1) b += '.'
 
-    function create_event(current_event, max_entropy = 1000) {
-        var new_event = '' + Date.now()
+        // Pad the shorter fractional part with zeros
+        var diff = (a.length - a.indexOf('.')) - (b.length - b.indexOf('.'))
+        if (diff < 0) a += '0'.repeat(-diff)
+        else if (diff > 0) b += '0'.repeat(diff)
 
-        var current_seq = get_event_seq(current_event)
-        if (compare_seqs(new_event, current_seq) > 0) return new_event
+        // Remove decimal and parse as BigInt
+        var a_big = BigInt(a.replace('.', ''))
+        var b_big = BigInt(b.replace('.', ''))
 
-        // Find smallest base-10 integer where compare_seqs(int, current_seq) >= 0
-        var base = seq_to_int(current_seq)
-        return '' + (base + 1 + Math.floor(Math.random() * max_entropy))
+        if (a_big < b_big) return -1
+        if (a_big > b_big) return 1
+        return 0
     }
 
-    function get_event_seq(e) {
-        if (!e) return ''
+    function create_event(current_event, decimal_places=3, entropy_digits=4) {
+        var now = '' + Date.now() / 1000
+        if (compare_events(now, current_event) > 0)
+            return now
 
-        for (let i = e.length - 1; i >= 0; i--)
-            if (e[i] === '-') return i == 0 ? e : e.slice(i + 1)
-        return e
-    }
+        // Add smallest increment to current_event using BigInt
+        var e = current_event || '0'
+        if (e.indexOf('.') === -1) e += '.'
 
-    function compare_seqs(a, b) {
-        if (!a) a = ''
-        if (!b) b = ''
+        // Truncate or pad to exactly decimal_places decimal places
+        var dot = e.indexOf('.')
+        var frac = e.slice(dot + 1)
+        if (frac.length > decimal_places) e = e.slice(0, dot + 1 + decimal_places)
+        else if (frac.length < decimal_places) e += '0'.repeat(decimal_places - frac.length)
 
-        var a_neg = a[0] === '-'
-        var b_neg = b[0] === '-'
-        if (a_neg !== b_neg) return a_neg ? -1 : 1
+        var big = BigInt(e.replace('.', '')) + 1n
+        var str = String(big)
 
-        // Both negative: compare magnitudes (reversed)
-        if (a_neg) {
-            var swap = a.slice(1); a = b.slice(1); b = swap
-        }
+        // Reinsert decimal point
+        var result = str.slice(0, -decimal_places) + '.' + str.slice(-decimal_places)
 
-        if (a.length !== b.length) return a.length - b.length
-        if (a < b) return -1
-        if (a > b) return 1
-        return 0
+        return result + random_digits(entropy_digits)
     }
 
-    // Smallest base-10 integer n where compare_seqs(String(n), s) >= 0
-    function seq_to_int(s) {
-        if (!s || s[0] === '-') return 0
-
-        var len = s.length
-        var min_of_len = Math.pow(10, len - 1) // e.g., len=3 -> 100
-        var max_of_len = Math.pow(10, len) - 1 // e.g., len=3 -> 999
-
-        if (s < String(min_of_len)) return min_of_len
-        if (s > String(max_of_len)) return max_of_len + 1
-
-        // s is in the base-10 range for this length
-        // scan for first non-digit > '9', increment prefix and pad zeros
-        var n = 0
-        for (var i = 0; i < len; i++) {
-            var c = s.charCodeAt(i)
-            if (c >= 48 && c <= 57) {
-                n = n * 10 + (c - 48)
-            } else if (c > 57) {
-                // non-digit > '9': increment prefix, pad rest with zeros
-                return (n + 1) * Math.pow(10, len - i)
-            } else {
-                // non-digit < '0': just pad rest with zeros
-                return n * Math.pow(10, len - i)
-            }
-        }
-        return n
+    function random_digits(n) {
+        if (!n) return ''
+        var s = ''
+        for (var i = 0; i < n; i++) s += Math.floor(Math.random() * 10)
+        return s
     }
 }

package/index.js

@@ -152,7 +152,7 @@ function create_braid_blob() {
                     header_cb: (result) => {
                         res.setHeader((req.subscribe ? "Current-" : "") +
                             "Version", version_to_header(result.version))
-                        res.setHeader("Version-Type", "relative-wallclock")
+                        res.setHeader("Version-Type", "wallclockish")
                         if (result.content_type)
                             res.setHeader('Content-Type', result.content_type)
                     },
@@ -167,7 +167,7 @@ function create_braid_blob() {
                             delete update.content_type
                         }
                         update['Merge-Type'] = 'aww'
-                        update['Version-Type'] = 'relative-wallclock'
+                        update['Version-Type'] = 'wallclockish'
                         res.sendUpdate(update)
                     } : null
                 })
@@ -206,7 +206,7 @@ function create_braid_blob() {
                 peer: req.peer
             })
             res.setHeader("Current-Version", version_to_header(event != null ? [event] : []))
-            res.setHeader("Version-Type", "relative-wallclock")
+            res.setHeader("Version-Type", "wallclockish")
             res.end('')
         } else if (req.method === 'DELETE') {
             await braid_blob.delete(params.key, {
@@ -239,7 +239,7 @@ function create_braid_blob() {
                     'Accept': params.content_type }
             if (params.version || params.parents)
                 fetch_params.headers = { ...fetch_params.headers,
-                    'Version-Type': 'relative-wallclock' }
+                    'Version-Type': 'wallclockish' }
 
             var res = await braid_fetch(key.href, fetch_params)
 
@@ -353,7 +353,7 @@ function create_braid_blob() {
                     'Content-Type': params.content_type }
             if (params.version)
                 fetch_params.headers = { ...fetch_params.headers,
-                    'Version-Type': 'relative-wallclock' }
+                    'Version-Type': 'wallclockish' }
 
             return await braid_fetch(key.href, fetch_params)
         }
@@ -591,79 +591,70 @@ function create_braid_blob() {
         if (!a) a = ''
         if (!b) b = ''
 
-        var c = compare_seqs(get_event_seq(a), get_event_seq(b))
-        if (c) return c
+        // Check if values match wallclockish format
+        var re = compare_events.re || (compare_events.re = /^-?[0-9]*\.[0-9]*$/)
+        var a_match = re.test(a)
+        var b_match = re.test(b)
 
-        if (a < b) return -1
-        if (a > b) return 1
-        return 0
-    }
+        // If only one matches, it wins
+        if (a_match && !b_match) return 1
+        if (b_match && !a_match) return -1
 
-    function create_event(current_event, max_entropy = 1000) {
-        var new_event = '' + Date.now()
+        // If neither matches, compare lexicographically
+        if (!a_match && !b_match) {
+            if (a < b) return -1
+            if (a > b) return 1
+            return 0
+        }
 
-        var current_seq = get_event_seq(current_event)
-        if (compare_seqs(new_event, current_seq) > 0) return new_event
+        // Both match - compare as decimals using BigInt
+        // Add decimal point if missing
+        if (a.indexOf('.') === -1) a += '.'
+        if (b.indexOf('.') === -1) b += '.'
 
-        // Find smallest base-10 integer where compare_seqs(int, current_seq) >= 0
-        var base = seq_to_int(current_seq)
-        return '' + (base + 1 + Math.floor(Math.random() * max_entropy))
-    }
+        // Pad the shorter fractional part with zeros
+        var diff = (a.length - a.indexOf('.')) - (b.length - b.indexOf('.'))
+        if (diff < 0) a += '0'.repeat(-diff)
+        else if (diff > 0) b += '0'.repeat(diff)
 
-    function get_event_seq(e) {
-        if (!e) return ''
+        // Remove decimal and parse as BigInt
+        var a_big = BigInt(a.replace('.', ''))
+        var b_big = BigInt(b.replace('.', ''))
 
-        for (let i = e.length - 1; i >= 0; i--)
-            if (e[i] === '-') return i == 0 ? e : e.slice(i + 1)
-        return e
+        if (a_big < b_big) return -1
+        if (a_big > b_big) return 1
+        return 0
     }
 
-    function compare_seqs(a, b) {
-        if (!a) a = ''
-        if (!b) b = ''
+    function create_event(current_event, decimal_places=3, entropy_digits=4) {
+        var now = '' + Date.now() / 1000
+        if (compare_events(now, current_event) > 0)
+            return now
 
-        var a_neg = a[0] === '-'
-        var b_neg = b[0] === '-'
-        if (a_neg !== b_neg) return a_neg ? -1 : 1
+        // Add smallest increment to current_event using BigInt
+        var e = current_event || '0'
+        if (e.indexOf('.') === -1) e += '.'
 
-        // Both negative: compare magnitudes (reversed)
-        if (a_neg) {
-            var swap = a.slice(1); a = b.slice(1); b = swap
-        }
+        // Truncate or pad to exactly decimal_places decimal places
+        var dot = e.indexOf('.')
+        var frac = e.slice(dot + 1)
+        if (frac.length > decimal_places) e = e.slice(0, dot + 1 + decimal_places)
+        else if (frac.length < decimal_places) e += '0'.repeat(decimal_places - frac.length)
 
-        if (a.length !== b.length) return a.length - b.length
-        if (a < b) return -1
-        if (a > b) return 1
-        return 0
+        var big = BigInt(e.replace('.', '')) + 1n
+        var str = String(big)
+
+        // Reinsert decimal point
+        var result = str.slice(0, -decimal_places) + '.' + str.slice(-decimal_places)
+
+        return result + random_digits(entropy_digits)
     }
 
-    // Smallest base-10 integer n where compare_seqs(String(n), s) >= 0
-    function seq_to_int(s) {
-        if (!s || s[0] === '-') return 0
-
-        var len = s.length
-        var min_of_len = Math.pow(10, len - 1) // e.g., len=3 -> 100
-        var max_of_len = Math.pow(10, len) - 1 // e.g., len=3 -> 999
-
-        if (s < String(min_of_len)) return min_of_len
-        if (s > String(max_of_len)) return max_of_len + 1
-
-        // s is in the base-10 range for this length
-        // scan for first non-digit > '9', increment prefix and pad zeros
-        var n = 0
-        for (var i = 0; i < len; i++) {
-            var c = s.charCodeAt(i)
-            if (c >= 48 && c <= 57) {
-                n = n * 10 + (c - 48)
-            } else if (c > 57) {
-                // non-digit > '9': increment prefix, pad rest with zeros
-                return (n + 1) * Math.pow(10, len - i)
-            } else {
-                // non-digit < '0': just pad rest with zeros
-                return n * Math.pow(10, len - i)
-            }
-        }
-        return n
+    function random_digits(n) {
+        if (!n) return ''
+        var s = ''
+        for (var i = 0; i < n; i++) s += Math.floor(Math.random() * 10)
+        return s
     }
 
     function ascii_ify(s) {
@@ -791,7 +782,12 @@ function create_braid_blob() {
                 params.headers.entries() :
                 Object.entries(params.headers))) {
                 var s = normalize_params.special[k.toLowerCase()]
-                if (s) normalized[s] = v
+                if (s) {
+                    // Parse JSON-encoded header values for version/parents
+                    if ((s === 'version' || s === 'parents') && typeof v === 'string')
+                        try { v = JSON.parse(v) } catch (e) {}
+                    normalized[s] = v
+                }
                 else normalized.headers[k] = v
             }
         }

package/package.json

@@ -1,16 +1,21 @@
 {
   "name": "braid-blob",
-  "version": "0.0.70",
+  "version": "0.0.72",
   "description": "Library for collaborative blobs over http using braid.",
   "author": "Braid Working Group",
   "repository": "braid-org/braid-blob",
   "homepage": "https://braid.org",
+  "files": [
+    "index.js",
+    "client.js",
+    "img-live.js"
+  ],
   "scripts": {
     "test": "node test/test.js",
     "test:browser": "node test/test.js --browser"
   },
   "dependencies": {
-    "braid-http": "~1.3.87",
+    "braid-http": "~1.3.89",
     "better-sqlite3": "^11.7.0"
   }
 }