braid-webindex

⚠️ Under construction. The Webindex spec is still in flux — expect breaking changes.

A Braid-HTTP compatible index server for web resources. It maintains a sorted, hierarchical tree of paths and lets clients subscribe to real-time updates using the Braid protocol.

Install

npm install braid-webindex

Usage

var braid_webindex = require('braid-webindex')

var index = braid_webindex()

// Add some paths
index.add('/docs/intro')
index.add('/docs/api')
index.add('/blog/hello-world')

// Or set them all at once
index.set(['/docs/intro', '/docs/api', '/blog/hello-world'])

As HTTP middleware

The serve method works as middleware with Node's http server, Express, or any framework that provides (req, res, next):

var http = require('http')
var braid_webindex = require('braid-webindex')

var index = braid_webindex()
index.set(['/foo', '/bar', '/a/b/c'])

http.createServer((req, res) => {
    index.serve(req, res, () => {
        res.statusCode = 404
        res.end('Not found')
    })
}).listen(4444)

With Express:

app.all('/*', index.serve)

Clients request the index by sending Accept: application/webindex+linked+json. If the header is missing, serve calls next() so other handlers can process the request.

Subscribing to changes

Clients can subscribe to any path to receive real-time updates:

index.subscribe('/docs', (children) => {
    console.log(children)
    // [{link: 'api'}, {link: 'intro'}]
}, abortSignal)

The callback fires immediately with the current state (the full sorted children array), then again with the new full state whenever children are added or removed. Pass an AbortSignal to unsubscribe.

Over HTTP, clients subscribe using the Subscribe header per the Braid-HTTP spec and receive the full state as the body of each update.

API

braid_webindex()

Creates a new index instance. Returns an object with the methods below.

index.serve(req, res, next)

HTTP middleware. Handles GET, HEAD, and OPTIONS requests with Accept: application/webindex+linked+json. Sets CORS headers and supports Braid-HTTP subscriptions.

Responds with Content-Type: application/webindex+linked+json. For non-subscription requests, the body is the full JSON array of children. For subscriptions, each update sends the full state as the body.

index.add(path)

Adds a path to the index. Intermediate resources are created automatically (e.g., adding /a/b/c creates /a and /a/b as resources with webindex representations). Subscribers are notified of changes.

index.remove(path)

Removes a path from the index. Empty parent resources are cleaned up automatically. Subscribers are notified.

index.set(paths)

Convenience method that calls add() for each path in the array.

index.subscribe(path, callback, abortSignal)

Subscribes to changes at path. The callback receives the full sorted children array each time:

[
    { link: 'name' },
    { link: 'other', 'content-type': 'application/webindex+linked+json' },
    ...
]

Each entry is a Linked JSON link to a resource. A resource may have multiple representations at the same URL. A plain {link: 'name'} links to a resource with an unspecified content-type. A link with "content-type": "application/webindex+linked+json" indicates that the resource has a webindex representation (i.e. it has children). When a resource has both a webindex representation and another representation, it appears as two separate entries — one for each representation.

The callback fires immediately with the current state, then again with the new full state on every change. Pass an AbortSignal to unsubscribe later.

License

Invisible Property License