beachcomber Node.js SDK

Node.js/TypeScript client for the beachcomber shell state daemon.

No external runtime dependencies — pure Node.js stdlib (net, fs, os, path).

Requirements

• Node.js 18+
• A running comb daemon

Installation

npm install beachcomber

Quick Start

import { Client } from 'beachcomber';

const client = new Client();

const result = await client.get('git.branch', '/path/to/repo');
if (result.isHit) {
  console.log(result.getString());  // e.g. "main"
  console.log(result.ageMs);        // e.g. 1234
  console.log(result.stale);        // false
}

API

Client

const client = new Client();
const client = new Client({ socketPath: '/custom/path' });
const client = new Client({ socketPath: '/custom/path', timeoutMs: 2000 });

client.get(key, path?)

Read a cached value.

const result = await client.get('git.branch', '/some/repo');
const result = await client.get('hostname');          // global provider, no path needed
const result = await client.get('git', '/some/repo'); // full provider (returns object)

Returns a CombResult.

client.refresh(key, path?)

Force the daemon to recompute a provider.

await client.refresh('git', '/some/repo');

client.status()

Return daemon status information.

const status = await client.status();

client.session()

Open a persistent connection. More efficient when querying multiple keys in sequence (one TCP round-trip per query instead of one connection per query).

const session = await client.session();
await session.setContext('/some/repo');   // optional — sets default path
const branch = await session.get('git.branch');
const dirty  = await session.get('git.dirty');
await session.refresh('git');
session.close();

CombResult

| Property / method | Type | Description | |---|---|---| | isHit | boolean | true when the cache had a value | | isMiss | boolean | true when the cache had no value | | data | unknown | Raw data (undefined on miss) | | ageMs | number | Cache age in milliseconds (0 on miss) | | stale | boolean | Whether the value is stale (false on miss) | | getString(field?) | string \| undefined | Data as a string; picks a named field from object results | | getNumber(field?) | number \| undefined | Data as a number | | getBool(field?) | boolean \| undefined | Data as a boolean |

For full provider queries (e.g. key = "git"), the data is an object. Use the field argument to pick a field:

const result = await client.get('git', '/repo');
result.getString('branch');   // "main"
result.getBool('dirty');      // false

Errors

| Class | When thrown | |---|---| | DaemonNotRunning | Socket does not exist or connection was refused | | ServerError | Daemon responded with {"ok":false,"error":"..."} | | ParseError | Response was not valid JSON or not an object |

All extend CombError which extends Error.

Socket discovery

The socket path is resolved in this order:

1. $BEACHCOMBER_SOCKET (if set and non-empty)
2. $XDG_RUNTIME_DIR/beachcomber/sock (if XDG_RUNTIME_DIR is set)
3. /tmp/beachcomber-<uid>/sock

This mirrors the daemon's bind path; $TMPDIR is not consulted. Override with the socketPath option.

Development

npm install
npm run build   # compile to dist/
npm test        # run tests with node:test