@aellopus/client

The official Node.js and Bun client for Aellopus, a key–value server speaking the Aellopus Wire Protocol (AWP/1) over TCP.

• Zero runtime dependencies — only Node/Bun built-ins (node:net).
• ESM-only, TypeScript-first — ships type declarations; runs on Node 18+ and Bun.
• Binary-safe — values are bytes; keys and values may contain CR, LF, or NUL.
• Promise-based with per-call timeouts and AbortSignal cancellation.
• Pipelining-safe — one connection is shared across concurrent callers, replies correlated in FIFO order.

Validated against the AWP/1 conformance vectors and end-to-end against the reference Rust server.

Install

npm install @aellopus/client
# or: pnpm add @aellopus/client / yarn add @aellopus/client / bun add @aellopus/client

Quick start

import { connect, NotFoundError } from '@aellopus/client';

const client = await connect('127.0.0.1:6969');
try {
  await client.set('greeting', 'hello world');
  console.log(await client.getString('greeting')); // "hello world"

  await client.set('session:42', 'token', { expiresSeconds: 60 });
  console.log((await client.ttl('session:42')).seconds); // ~60

  try {
    await client.get('missing');
  } catch (err) {
    if (err instanceof NotFoundError) console.log('no such key');
  }
} finally {
  await client.close();
}

A Client is safe to share across concurrent work — hold one rather than pooling.

Running a server

The client talks to an Aellopus server. The quickest way to get one for local development:

docker run --rm -p 6969:6969 adibhauzan/aellopus:latest

The server listens on 127.0.0.1:6969 by default. See the server repository for other options.

API

connect(addr, options?): Promise<Client>

Opens a client to addr, a host:port TCP address with no scheme (IPv6 hosts are bracketed, e.g. [::1]:6969). options ({ timeoutMs?, signal? }) bound establishing the connection only.

Values

| Method | Returns | Notes | | --- | --- | --- | | get(key) | Promise<Uint8Array> | Throws NotFoundError on a miss. An empty value is a present zero-length array. | | getString(key) | Promise<string> | UTF-8 convenience over get. | | set(key, value, options?) | Promise<void> | value is Uint8Array \| string; options.expiresSeconds attaches a TTL. | | del(key) | Promise<boolean> | true if the key existed. | | exists(key) | Promise<boolean> | | | incr(key) / decr(key) | Promise<number> | Post-operation value. |

TTL

| Method | Returns | Notes | | --- | --- | --- | | ttl(key) | Promise<TTL> | Throws NotFoundError if the key is absent. | | expire(key, seconds) | Promise<boolean> | true if the key existed. |

TTL exposes hasExpiry: boolean and seconds: number \| undefined (undefined when the key persists with no expiry).

Keys & scanning

| Method | Returns | Notes | | --- | --- | --- | | keys(pattern) | Promise<string[]> | Glob match; may block the server on a large keyspace. | | scanPage(cursor, options?) | Promise<ScanResult> | One page. Pass '' to begin; options accepts match / count. | | scan(options?) | AsyncIterableIterator<string> | Incremental walk; hides cursor bookkeeping. |

for await (const key of client.scan({ match: 'user:*' })) {
  console.log(key);
}

Health & metadata

| Method | Returns | | --- | --- | | ping() | Promise<void> | | version() | Promise<string> — server semver | | stats() | Promise<string> — server stats text |

Maintenance & lifecycle

| Method | Returns | | --- | --- | | flushAll() | Promise<void> — remove every key | | close() | Promise<void> — idempotent |

Per-call options

Every method takes an optional final options argument:

const ac = new AbortController();
const value = await client.get('key', { timeoutMs: 250, signal: ac.signal });

A timed-out or aborted call rejects but leaves the connection usable — its eventual reply is discarded and later calls stay correctly correlated.

Errors

All thrown errors extend AellopusError, so you can catch the family and discriminate the case:

| Error | Meaning | Recoverable? | | --- | --- | --- | | NotFoundError | Key absent (get, getString, ttl) | Yes | | ServerError | Well-formed server error; has .code (e.g. NOTINT, TTLRANGE) | Yes | | TimeoutError | Call exceeded timeoutMs | Yes | | ProtocolError | Malformed or wrong-shaped reply | No — connection is closed | | ClosedError | Client closed or connection ended | No — reconnect |

A cancelled call rejects with a Web-standard DOMException named AbortError.

Compatibility

• Runtimes: Node.js 18+ and Bun. ESM only.
• Protocol: AWP/1. Tested against Aellopus server 0.1.0.

License

Apache-2.0