Braid-HTTP

1.3.125 verified Sat Apr 25 auth: no javascript

A ponyfill library extending browser and Node.js HTTP implementations to support Braid-HTTP, turning state transfer into state synchronization. Currently at version 1.3.125, with regular releases. Key differentiators: drop-in replacement for fetch() in browsers, adds capabilities to Node.js http/https/http2 modules, conforms to Braid-HTTP v04 spec with HTTP Multiresponse and Multiplexing extensions. Compared to alternatives, this is the primary implementation of the Braid protocol, providing subscription-based real-time updates and automatic reconnection.

Common errors

error Cannot find module 'braid-http' ↓

cause Package not installed or incorrectly imported.

fix

Run 'npm install braid-http' and ensure import path is correct.

error TypeError: braid_http.fetch is not a function ↓

cause Using default import instead of named import.

fix

Use 'import { fetch } from 'braid-http'' instead of 'import braid_http from 'braid-http''.

error Uncaught ReferenceError: braid_fetch is not defined ↓

cause Script tag missing or not loaded before execution.

fix

Include <script src='https://unpkg.com/braid-http/braid-http-client.js'></script> before calling braid_fetch.

error Failed to fetch: The 'subscribe' option is not supported by this version of fetch ↓

cause Using native browser fetch instead of braid-http's fetch.

fix

Ensure you are using the braid-http fetch: 'import { fetch } from 'braid-http''.

Warnings

gotcha The 'braid-http' module does not export a default; always use named imports. ↓

fix Use 'import { fetch } from 'braid-http'' instead of 'import braidFetch from 'braid-http''.

gotcha Browser usage requires a script tag with unpkg. The global 'braid_fetch' is the replacement for window.fetch. ↓

fix Use <script src='https://unpkg.com/braid-http/braid-http-client.js'></script> then window.fetch = braid_fetch.

gotcha The 'response.subscribe' callback receives an update object that may contain 'patches' or 'body', but not both. Check for existence of 'patches' to differentiate. ↓

fix Use 'if (update.patches) { ... } else { ... }' to handle patches vs. full body.

gotcha The 'parents' option in fetch can be a function returning current parents, not just a static array. ↓

fix Set 'parents: () => current_parents' to dynamically update version on reconnect.

gotcha Node.js usage requires installing the package and importing via require or ESM. ↓

fix Use 'const { fetch } = require('braid-http')' for CJS or 'import { fetch } from 'braid-http'' for ESM.

Install

npm install braid-http

yarn add braid-http

pnpm add braid-http

Imports

fetch
wrong
```
const braid = require('braid-http'); braid.fetch()
```
correct
```
import { fetch } from 'braid-http'
```
Default export not available; named import required. In CJS, use destructuring.

http_client

wrong

import http_client from 'braid-http'

correct

import { http_client } from 'braid-http'

Not a default export; always named import.

http_server

wrong

const { http_server } = require('braid-http')

correct

import { http_server } from 'braid-http'

Also works with require destructuring.

Quickstart

Demonstrates subscribing to a resource with automatic reconnection.

import { fetch } from 'braid-http'

async function subscribeToChat() {
  const response = await fetch('https://braid.org/chat', {
    subscribe: true,
    retry: true
  })
  response.subscribe((update) => {
    console.log('New update:', update)
  })
}

subscribeToChat()