felix-client 0.5.0 → 0.6.0-preview.2

package/README.md

@@ -10,6 +10,19 @@ the places that matter. Here they exist once, in `felix-client`, and every
 language binds to them. The Python binding is built on the same reasoning and
 exposes the same surface.
 
+```bash
+npm install felix-client
+```
+
+The binary ships as one package per platform, declared as optional
+dependencies, so npm fetches only the one your machine needs. Nothing is
+compiled at install time. Linux (x86-64 and arm64, glibc 2.28 or newer, so
+Debian bookworm, RHEL 8 and Amazon Linux 2023), macOS (Intel and Apple silicon)
+and Windows x86-64 are covered. Alpine and other musl systems are not. Node 18
+or newer.
+
+Full documentation: https://docs.getfelix.dev/clients/typescript/
+
 ## One surface, and it is asynchronous
 
 Python offers two surfaces because its sync one is the older idiom. Node has no
@@ -40,14 +53,15 @@ Everything the Python binding wraps, with one exception noted below.
 
 | | |
 |---|---|
-| Publish | `publish(tenant, ns, stream, payload, key?, ack?, atLeastOnce?)` |
+| Publish | `publish(tenant, ns, stream, payload, key?, ack?, atLeastOnce?)` → the record's offset, or `null` when the broker acked before writing it |
 | Subscribe | `subscribe(...)` → `nextEvent()`, `close()`, `closed` |
 | Sharded subscribe | `subscribeSharded(..., start?, resume?)` → `nextEvent()`, `positions()`, `shards` |
 | Stream shape | `streamShards(...)`, `endpoints()` |
 | Cache | `cachePut` (with TTL), `cacheGet`, `cacheDelete` |
 | Counters | `counterAdd`, `counterGet` |
 | Cache watches | `watchCache(..., key?, prefix?, start?, retained?)` → `recv()`, `retainedCount` |
-| Consumer groups | `groupPoll`, `groupAck`, `groupNack`, `groupDeadLetters`, `groupDiscard`, `groupRedrive` |
+| Consumer groups | `groupPoll`, `groupAck`, `groupNack`, `groupDeadLetters`, `groupDiscard`, `groupRedrive` (each follows the broker's redirect to the shard's leader) |
+| Atomic commits | `commit(tenant, ns, entityKey, [CommitOp.publish \| enqueue, put, delete])` → `{ offset }`, `stateGet(tenant, ns, stream, entityKey, key)` → `{ value, version, asOf }`; `NotOnOwningShardError` and `EventCountError` refuse a commit that is not one record. See [atomic commits](../../../docs/atomic-commit.md) |
 
 Every handle has an idempotent `close()` and implements `Symbol.asyncDispose`,
 so on Node 24 and newer a `throw` releases it on the way out:
@@ -76,9 +90,11 @@ shard.
 
 Subscriber queues shed under the default policy rather than blocking the
 publisher, so a subscriber can silently miss records. On a durable stream each
-delivered event carries its log offset, and a jump in them is exactly a drop —
+delivered event carries its log offset, and a jump in them is a drop —
 which is why `event.offset` is worth reading even when you do not resume from
-it.
+it. The one gap that is not a drop is a new leader's generation-start
+record, and the event after it says so: `offset - previous - 1n - skippedBefore`
+records were dropped.
 
 ### A sharded subscription surfaces shard trouble rather than hiding it
 
@@ -119,16 +135,21 @@ resolved.
 try {
   await client.publish("t1", "default", "events", payload);
 } catch (err) {
-  if (err instanceof ConnectionError) retry();   // err.retryable === true
-  else if (err instanceof AuthError) giveUp();   // no amount of retrying grants a permission
+  if (err instanceof OutcomeUnknownError) reconcile(); // it may have been written
+  else if (err.retryable) retry();                     // nothing was written
+  else if (err instanceof AuthError) giveUp();         // no amount of retrying grants a permission
 }
 ```
 
-`FelixError` is the base; `ConnectionError`, `AuthError`, `NotFoundError`,
+`FelixError` is the base; `ConnectionError`, `ShardUnavailableError`,
+`OverloadedError`, `OutcomeUnknownError`, `AuthError`, `NotFoundError`,
 `CursorError` and `InvalidArgumentError` are the branches, mirroring the Python
-binding's exceptions. Each carries a stable `code` as well, for code that would
-rather switch than test `instanceof`. Never match on the message — it is prose,
-and it will be reworded.
+binding's exceptions. A broker that sends error codes picks the class, and the
+error carries its `code`, `retry` class and `detail`, as the Python exceptions
+do; from an older broker they are `undefined` and the class comes from the
+message. Each also carries a stable `kind` (`FELIX_AUTH`, …) for code that
+would rather switch than test `instanceof`. Never match on the message — it is prose, and it will be
+reworded.
 
 ## What is not wrapped
 

package/errors.js

@@ -0,0 +1,189 @@
+// The error classes, and turning a native error into one of them.
+//
+// The native layer cannot set properties on its errors: napi errors carry only
+// a status from napi's own fixed enum and a message. So it prefixes the message
+// with a kind, and with the broker's code, retry class and detail when the
+// broker sent them:
+//
+//   FELIX_AUTH: <text>
+//   FELIX_SHARD_UNAVAILABLE {"code":"shard_unavailable","retry":"retry"}\n<text>
+//
+// and this file lifts that onto a typed error. Compact JSON never holds a raw
+// newline, which is what makes the second form safe to split. Both halves ship
+// as one package, so the prefix is an internal detail rather than something a
+// caller parses. Kept apart from `index.js` so it can be tested without the
+// addon.
+//
+// The class hierarchy mirrors the Python binding's exceptions, because the
+// distinction is the same one in both languages: what an application can
+// *decide* from a failure.
+
+"use strict";
+
+/** Retry classes under which sending the request again cannot duplicate it. */
+const SAFE_TO_RETRY = new Set(["retry", "retry_after", "redirect"]);
+
+/** Base class for every error this client raises. */
+class FelixError extends Error {
+  constructor(kind, message, meta = null) {
+    super(message);
+    this.name = new.target.name;
+    /**
+     * Which kind of failure this is (`FELIX_AUTH`, `FELIX_SHARD_UNAVAILABLE`,
+     * ...), the same thing the class says. Always set.
+     */
+    this.kind = kind;
+    /**
+     * The broker's error code, such as `shard_unavailable`. `undefined` when
+     * the broker sent none: an older broker, or a failure in the client.
+     */
+    this.code = meta?.code;
+    /**
+     * What the broker says the caller may do: `retry`, `retry_after`,
+     * `redirect`, `outcome_unknown` or `fatal`. `undefined` without a code.
+     */
+    this.retry = meta?.retry;
+    /** Extra facts, such as `reason` or `retry_after_ms`, or `undefined`. */
+    this.detail = meta?.detail;
+  }
+
+  /**
+   * Whether sending the same request again could succeed without applying
+   * it twice.
+   *
+   * The broker's retry class decides when it sent one. Otherwise the class
+   * does: only a connection failure, an unavailable shard and an overloaded
+   * broker say yes.
+   */
+  get retryable() {
+    if (this.retry !== undefined) return SAFE_TO_RETRY.has(this.retry);
+    return this.constructor.retryableByDefault;
+  }
+
+  static get retryableByDefault() {
+    return false;
+  }
+}
+
+/**
+ * The broker could not be reached, the connection was lost mid-call, or the
+ * broker is shutting down.
+ */
+class ConnectionError extends FelixError {
+  static get retryableByDefault() {
+    return true;
+  }
+}
+
+/** The token was rejected, or lacks the permission this call needs. */
+class AuthError extends FelixError {}
+
+/** The tenant, namespace, stream or cache does not exist on the broker. */
+class NotFoundError extends FelixError {}
+
+/** The requested start offset is gone — retention discarded it. */
+class CursorError extends FelixError {}
+
+/** A bad argument to this client, rather than a failure of the call. */
+class InvalidArgumentError extends FelixError {}
+
+/**
+ * Nobody can serve the shard right now, typically while it moves. Nothing was
+ * applied.
+ */
+class ShardUnavailableError extends FelixError {
+  static get retryableByDefault() {
+    return true;
+  }
+}
+
+/** The broker is shedding load. Nothing was applied; retry after a pause. */
+class OverloadedError extends FelixError {
+  static get retryableByDefault() {
+    return true;
+  }
+}
+
+/**
+ * The write may or may not have been applied. Only an idempotent request is
+ * safe to send again.
+ */
+class OutcomeUnknownError extends FelixError {}
+
+/** A commit was refused before it was sent. Nothing was written. */
+class CommitError extends FelixError {}
+
+/**
+ * An op names a stream other than the commit's. A different stream is a
+ * different log, and a commit writes one. `index` is the op, `stream` what it
+ * named, `owner` the commit's stream.
+ */
+class NotOnOwningShardError extends CommitError {
+  constructor(kind, message, meta = null) {
+    super(kind, message, null);
+    this.index = meta?.index;
+    this.stream = meta?.stream;
+    this.owner = meta?.owner;
+  }
+}
+
+/** A commit carries exactly one event (publish or enqueue); this had `count`. */
+class EventCountError extends CommitError {
+  constructor(kind, message, meta = null) {
+    super(kind, message, null);
+    this.count = meta?.count;
+  }
+}
+
+const CLASSES = new Map([
+  ["FELIX_CONNECTION", ConnectionError],
+  ["FELIX_AUTH", AuthError],
+  ["FELIX_NOT_FOUND", NotFoundError],
+  ["FELIX_CURSOR", CursorError],
+  ["FELIX_INVALID", InvalidArgumentError],
+  ["FELIX_SHARD_UNAVAILABLE", ShardUnavailableError],
+  ["FELIX_OVERLOADED", OverloadedError],
+  ["FELIX_OUTCOME_UNKNOWN", OutcomeUnknownError],
+  ["FELIX_COMMIT", CommitError],
+  ["FELIX_NOT_ON_OWNING_SHARD", NotOnOwningShardError],
+  ["FELIX_EVENT_COUNT", EventCountError],
+  ["FELIX_ERROR", FelixError],
+]);
+
+const PREFIX = /^(FELIX_[A-Z_]+)(?:: | (\{[^\n]*\})\n)/;
+
+/** Lift a native error into a typed one, leaving anything else alone. */
+function typed(err) {
+  const message = err && typeof err.message === "string" ? err.message : "";
+  const match = PREFIX.exec(message);
+  const Class = match && CLASSES.get(match[1]);
+  if (!Class) return err;
+  let meta = null;
+  if (match[2]) {
+    try {
+      meta = JSON.parse(match[2]);
+    } catch {
+      return err;
+    }
+  }
+  const out = new Class(match[1], message.slice(match[0].length), meta);
+  // Keep the native stack: it names the call that failed.
+  if (err.stack) out.stack = err.stack.replace(message, out.message);
+  return out;
+}
+
+module.exports = {
+  FelixError,
+  ConnectionError,
+  AuthError,
+  NotFoundError,
+  CursorError,
+  InvalidArgumentError,
+  ShardUnavailableError,
+  OverloadedError,
+  OutcomeUnknownError,
+  CommitError,
+  NotOnOwningShardError,
+  EventCountError,
+  typed,
+};

package/index.d.ts

@@ -13,11 +13,17 @@ export interface Event {
   /**
    * The record's log offset on a durable stream, absent on an ephemeral one.
    *
-   * A jump in these is exactly a drop: subscriber queues shed under the
-   * default policy rather than blocking the publisher, so a gap here is the
-   * signal that it happened.
+   * Subscriber queues shed under the default policy rather than blocking the
+   * publisher, so a gap here is the signal that it happened:
+   * `offset - previous - 1n - skippedBefore` records were dropped.
    */
   offset: bigint | null;
+  /**
+   * How many offsets just before `offset` hold no event. Non-zero only on the
+   * first event after a leader change, whose generation-start record took an
+   * offset; `0n` from a broker that predates it.
+   */
+  skippedBefore: bigint;
 }
 
 /** One record handed out by a consumer group. */
@@ -31,6 +37,12 @@ export interface GroupRecord {
    * treat a retry differently. `0` means the broker did not report it.
    */
   attempts: number;
+  /**
+   * How many offsets directly below this one were settled without being
+   * delivered (generation starts, records retention removed). A hole with this
+   * count will not fill. `0n` from a broker that predates it.
+   */
+  skippedBefore: bigint;
 }
 
 /** One change observed by a cache watch. */
@@ -58,21 +70,39 @@ export interface CacheWatchItem {
    * `start = laggedResumeFrom` is gapless.
    */
   laggedResumeFrom: bigint | null;
+  /**
+   * Set when the watch's shard moved to another broker. The watch follows it
+   * there on its own and carries on where it left off.
+   */
+  shardMoved: ShardMoved | null;
+}
+
+/**
+ * Where a shard went when it moved to another broker. Cache watches and
+ * sharded subscriptions follow it on their own; this is a notice.
+ */
+export interface ShardMoved {
+  resumeFrom: bigint | null;
+  nodeId: string | null;
+  addr: string | null;
+  generation: bigint;
 }
 
 /**
  * An item from a sharded subscription.
  *
- * Exactly one of `event`, `lostError` and `recovered` is set, and `shard` says
- * which shard it concerns. A lost shard does not affect the others: they keep
- * delivering while that one is re-established, and it resumes from its own
- * last offset so nothing is skipped.
+ * Exactly one of `event`, `lostError`, `recovered` and `shardMoved` is set, and
+ * `shard` says which shard it concerns. A lost shard does not affect the
+ * others: they keep delivering while that one is re-established, and it
+ * resumes from its own last offset so nothing is skipped. A moved shard is
+ * followed: its records carry on from the new owner, or a loss comes next.
  */
 export interface ShardEvent {
   shard: number;
   event: Event | null;
   lostError: string | null;
   recovered: boolean | null;
+  shardMoved: ShardMoved | null;
 }
 
 /** How much the broker must have done before a publish resolves. */
@@ -84,19 +114,55 @@ export type StartPosition = "latest" | "earliest" | bigint;
 /** Per-shard offsets, keyed by shard number. */
 export type ShardPositions = Record<string, bigint>;
 
+/**
+ * What the broker says a caller may do after an error. `retry`, `retry_after`
+ * and `redirect` mean nothing was applied; `outcome_unknown` means it may have
+ * been, so only an idempotent request is safe to send again.
+ */
+export type RetryClass = "retry" | "retry_after" | "redirect" | "outcome_unknown" | "fatal";
+
+/** Extra facts the broker sent with an error. Every field is optional. */
+export interface ErrorDetail {
+  /**
+   * For `shard_unavailable`: `not_assigned`, `owner_unavailable`, `not_ready`,
+   * `stale`, `fenced` or `moving`.
+   */
+  reason?: string;
+  /**
+   * How long the broker suggests waiting: for `retry_after`, and as a hint with
+   * `retry` for a shard that is `moving`.
+   */
+  retry_after_ms?: number;
+}
+
 /** Base class for every error this client raises. */
 export declare class FelixError extends Error {
   /**
-   * A stable identifier for *why* this failed. Branch on this, or on the
-   * class, rather than on the message — the message is prose and will be
-   * reworded.
+   * Which kind of failure this is (`FELIX_AUTH`, `FELIX_SHARD_UNAVAILABLE`,
+   * ...), the same thing the class says. Always set.
+   */
+  readonly kind: string;
+  /**
+   * The broker's error code, such as `shard_unavailable` or `quorum_timeout`.
+   * `undefined` when the broker predates error codes or the failure was local.
+   */
+  readonly code: string | undefined;
+  /** The broker's retry class, or `undefined` when it sent no code. */
+  readonly retry: RetryClass | undefined;
+  /** Extra facts from the broker, or `undefined`. */
+  readonly detail: ErrorDetail | undefined;
+  /**
+   * Whether sending the same request again could succeed without applying it
+   * twice. Decided by `retry` when the broker sent one, and otherwise by the
+   * class: `ConnectionError`, `ShardUnavailableError` and `OverloadedError`.
    */
-  readonly code: string;
-  /** Whether retrying could plausibly succeed. Only `ConnectionError` says yes. */
   readonly retryable: boolean;
 }
 
-/** The broker could not be reached, or the connection was lost mid-call. */
+/**
+ * The broker could not be reached, the connection was lost mid-call, or the
+ * broker is shutting down (`draining`).
+ */
 export declare class ConnectionError extends FelixError {}
 /** The token was rejected, or lacks the permission this call needs. */
 export declare class AuthError extends FelixError {}
@@ -106,6 +172,73 @@ export declare class NotFoundError extends FelixError {}
 export declare class CursorError extends FelixError {}
 /** A bad argument to this client, rather than a failure of the call. */
 export declare class InvalidArgumentError extends FelixError {}
+/**
+ * Nobody can serve the shard right now, typically while it moves
+ * (`shard_unavailable`), or another broker owns it (`not_leader`). Nothing was
+ * applied; retrying is safe.
+ */
+export declare class ShardUnavailableError extends FelixError {}
+/** The broker is shedding load (`overloaded`). Nothing was applied. */
+export declare class OverloadedError extends FelixError {}
+/**
+ * The write may or may not have been applied: `quorum_timeout`,
+ * `leadership_lost`, `unacknowledged`, or any error whose retry class is
+ * `outcome_unknown`. Only an idempotent request is safe to send again.
+ */
+export declare class OutcomeUnknownError extends FelixError {}
+
+/** A commit was refused before it was sent. Nothing was written. */
+export declare class CommitError extends FelixError {}
+/**
+ * An op names a stream other than the commit's: a different stream is a
+ * different log, and a commit writes one.
+ */
+export declare class NotOnOwningShardError extends CommitError {
+  /** Which op, counting from 0. */
+  readonly index: number;
+  /** The stream that op named. */
+  readonly stream: string;
+  /** The commit's own stream. */
+  readonly owner: string;
+}
+/** A commit carries exactly one event (publish or enqueue). */
+export declare class EventCountError extends CommitError {
+  readonly count: number;
+}
+
+/**
+ * One part of an atomic commit. Exactly one op per commit is an event
+ * (`publish` or `enqueue`); every op names the same stream.
+ */
+export type CommitOp =
+  | { op: "publish"; stream: string; payload: Buffer }
+  | { op: "enqueue"; queue: string; payload: Buffer }
+  | { op: "put"; stream: string; key: string; value: Buffer }
+  | { op: "delete"; stream: string; key: string };
+
+/** Builders for `CommitOp`s; each returns the plain object. */
+export declare const CommitOp: {
+  publish(stream: string, payload: Buffer | string): CommitOp;
+  enqueue(queue: string, payload: Buffer | string): CommitOp;
+  put(stream: string, key: string, value: Buffer | string): CommitOp;
+  delete(stream: string, key: string): CommitOp;
+};
+
+/** A commit the broker made durable. */
+export interface CommitReceipt {
+  /** Where the event is read, and the version of every key the commit wrote. */
+  offset: bigint;
+}
+
+/** A key in a stream shard's state. */
+export interface StateValue {
+  /** Absent when the key was never written or was deleted. */
+  value: Buffer | null;
+  /** Offset of the commit that wrote `value`. */
+  version: bigint | null;
+  /** Offset of the last commit the answer reflects. */
+  asOf: bigint | null;
+}
 
 /** A live subscription. Read it with `nextEvent`, and `close` it when done. */
 export declare class SubscriptionHandle {
@@ -180,6 +313,10 @@ export declare class Client {
    * TLS is not optional — QUIC has no unencrypted mode. Pass `caFile` to trust
    * a specific CA (what a self-signed development broker needs), or omit it to
    * use the operating system's trust store.
+   *
+   * `offerAlpn` offers the `felix/1` ALPN. A broker with
+   * `FELIX_TLS_REQUIRE_ALPN=true` serves only clients that do; a broker older
+   * than ALPN support refuses them, which is why it is off by default.
    */
   static connect(
     addrs: string | string[],
@@ -187,6 +324,7 @@ export declare class Client {
     token: string,
     serverName?: string,
     caFile?: string,
+    offerAlpn?: boolean,
   ): Promise<Client>;
 
   /**
@@ -204,6 +342,10 @@ export declare class Client {
    * certain to land, and may land twice. That is a delivery guarantee you
    * choose, never one this client assumes — and it cannot be combined with
    * `key`, which the re-send path does not yet carry.
+   *
+   * Resolves to the record's log offset, or `null` when the broker
+   * acknowledged before writing it, the stream has no log, the broker is too
+   * old to say, or `ack` is `"none"`.
    */
   publish(
     tenantId: string,
@@ -213,7 +355,7 @@ export declare class Client {
     key?: Buffer,
     ack?: AckMode,
     atLeastOnce?: boolean,
-  ): Promise<void>;
+  ): Promise<bigint | null>;
 
   /**
    * Subscribe to a stream.
@@ -293,6 +435,28 @@ export declare class Client {
     key: string,
   ): Promise<Buffer | null>;
 
+  /**
+   * Commit `ops` as one record on the shard `entityKey` routes to. Every
+   * reader sees all of it or none of it. Rejects with `EventCountError` or
+   * `NotOnOwningShardError` before anything is sent when `ops` does not carry
+   * exactly one event or names two streams. See docs/atomic-commit.md.
+   */
+  commit(
+    tenantId: string,
+    namespace: string,
+    entityKey: Buffer,
+    ops: CommitOp[],
+  ): Promise<CommitReceipt>;
+
+  /** `key` in the state of `stream`'s shard that `entityKey` routes to. */
+  stateGet(
+    tenantId: string,
+    namespace: string,
+    stream: string,
+    entityKey: Buffer,
+    key: string,
+  ): Promise<StateValue>;
+
   /** Add to a counter and return its new value. `delta` may be negative. */
   counterAdd(
     tenantId: string,
@@ -354,6 +518,14 @@ export declare class Client {
     group: string,
     maxRecords?: number,
     waitMs?: number,
+    /**
+     * This member's name, stable across its restarts, 1 to 128 bytes. With
+     * `reclaim`, the records a previous process under the same name still
+     * held come back first, instead of after the visibility timeout. Only a
+     * connection's first such poll reclaims, so it is safe to leave set.
+     */
+    consumer?: string,
+    reclaim?: boolean,
   ): Promise<GroupRecord[]>;
 
   /** Finish a record: it will not be handed out again. */

package/index.js

@@ -1,91 +1,15 @@
 // The package's JavaScript half: load the addon, and give its errors an
-// identity a caller can branch on.
-//
-// The native layer cannot set `err.code` itself — napi puts an error's status
-// there and `#[napi]` requires that status to be napi's own fixed enum. So it
-// prefixes the message with a Felix code and this file lifts it onto a typed
-// error. Both halves ship as one package, so that prefix is an internal detail
-// rather than something a caller parses.
-//
-// The class hierarchy mirrors the Python binding's exceptions, because the
-// distinction is the same one in both languages: what an application can
-// *decide* from a failure. A connection failure is worth another attempt
-// against another broker; an authorization failure, a missing stream, or a
-// discarded offset will fail the same way every time.
+// identity a caller can branch on. The error classes and how a native error
+// becomes one are in `errors.js`.
 
 "use strict";
 
 const { existsSync } = require("node:fs");
 const { join } = require("node:path");
 
-/** Base class for every error this client raises. */
-class FelixError extends Error {
-  constructor(code, message) {
-    super(message);
-    this.name = new.target.name;
-    /**
-     * A stable identifier for *why* this failed. Branch on this, or on the
-     * class, rather than on the message — the message is prose and will be
-     * reworded.
-     */
-    this.code = code;
-  }
-
-  /**
-   * Whether retrying could plausibly succeed.
-   *
-   * Only `ConnectionError` says yes. An authorization failure, a missing
-   * stream, or a discarded offset fails the same way every time — retrying
-   * them burns a budget on a call that cannot succeed.
-   */
-  get retryable() {
-    return false;
-  }
-}
-
-/** The broker could not be reached, or the connection was lost mid-call. */
-class ConnectionError extends FelixError {
-  get retryable() {
-    return true;
-  }
-}
-
-/** The token was rejected, or lacks the permission this call needs. */
-class AuthError extends FelixError {}
-
-/** The tenant, namespace, stream or cache does not exist on the broker. */
-class NotFoundError extends FelixError {}
-
-/** The requested start offset is gone — retention discarded it. */
-class CursorError extends FelixError {}
+const errors = require("./errors.js");
 
-/** A bad argument to this client, rather than a failure of the call. */
-class InvalidArgumentError extends FelixError {}
-
-const CLASSES = new Map([
-  ["FELIX_CONNECTION", ConnectionError],
-  ["FELIX_AUTH", AuthError],
-  ["FELIX_NOT_FOUND", NotFoundError],
-  ["FELIX_CURSOR", CursorError],
-  ["FELIX_INVALID", InvalidArgumentError],
-  ["FELIX_ERROR", FelixError],
-]);
-
-/** Lift a native error into a typed one, leaving anything else alone. */
-function typed(err) {
-  const message = err && typeof err.message === "string" ? err.message : "";
-  const at = message.indexOf(": ");
-  if (at > 0) {
-    const Class = CLASSES.get(message.slice(0, at));
-    if (Class) {
-      const out = new Class(message.slice(0, at), message.slice(at + 2));
-      // Keep the native stack: it names the call that failed.
-      if (err.stack) out.stack = err.stack.replace(message, out.message);
-      return out;
-    }
-  }
-  return err;
-}
+const { typed } = errors;
 
 /**
  * What this machine's binary is called, in napi's naming.
@@ -119,7 +43,7 @@ function loadAddon() {
   // The repository shares one target directory across every crate, this one
   // included (`.cargo/config.toml`), so a development build lands at the root
   // rather than beside this file.
-  const roots = [join(__dirname, "target"), join(__dirname, "..", "..", "target")];
+  const roots = [join(__dirname, "target"), join(__dirname, "..", "..", "..", "target")];
   const names = [
     "libfelix_typescript.dylib",
     "libfelix_typescript.so",
@@ -167,7 +91,7 @@ function loadAddon() {
     `felix-client: no native addon for ${tag}. Either this platform has no ` +
       `published binary, or the optional dependency ${pkg} did not install. ` +
       `From a checkout, build it with \`napi build --release\` or ` +
-      `\`cargo build --release\` in crates/felix-typescript.`,
+      `\`cargo build --release\` in crates/sdk/felix-typescript.`,
   );
 }
 
@@ -227,11 +151,22 @@ function wrap(value) {
   });
 }
 
+/**
+ * Builders for the ops `client.commit` takes. Each returns a plain object, so
+ * writing the object literal by hand works just as well.
+ */
+const CommitOp = {
+  publish: (stream, payload) => ({ op: "publish", stream, payload: Buffer.from(payload) }),
+  enqueue: (queue, payload) => ({ op: "enqueue", queue, payload: Buffer.from(payload) }),
+  put: (stream, key, value) => ({ op: "put", stream, key, value: Buffer.from(value) }),
+  delete: (stream, key) => ({ op: "delete", stream, key }),
+};
+
 /** The public `Client`: a façade over the native one that types its errors. */
 const Client = {
-  async connect(addrs, tenantId, token, serverName, caFile) {
+  async connect(addrs, tenantId, token, serverName, caFile, offerAlpn) {
     try {
-      const client = await native.Client.connect(addrs, tenantId, token, serverName, caFile);
+      const client = await native.Client.connect(addrs, tenantId, token, serverName, caFile, offerAlpn);
       return wrap(client);
     } catch (err) {
       throw typed(err);
@@ -241,12 +176,19 @@ const Client = {
 
 module.exports = {
   Client,
-  FelixError,
-  ConnectionError,
-  AuthError,
-  NotFoundError,
-  CursorError,
-  InvalidArgumentError,
+  FelixError: errors.FelixError,
+  ConnectionError: errors.ConnectionError,
+  AuthError: errors.AuthError,
+  NotFoundError: errors.NotFoundError,
+  CursorError: errors.CursorError,
+  InvalidArgumentError: errors.InvalidArgumentError,
+  ShardUnavailableError: errors.ShardUnavailableError,
+  OverloadedError: errors.OverloadedError,
+  OutcomeUnknownError: errors.OutcomeUnknownError,
+  CommitError: errors.CommitError,
+  NotOnOwningShardError: errors.NotOnOwningShardError,
+  EventCountError: errors.EventCountError,
+  CommitOp,
   /** The unwrapped addon, for anyone who wants it. Errors are untyped there. */
   native,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "felix-client",
-  "version": "0.5.0",
+  "version": "0.6.0-preview.2",
   "description": "Node.js/TypeScript bindings for the Felix client, over the Rust client rather than a reimplementation of it",
   "keywords": [
     "felix",
@@ -14,19 +14,20 @@
   ],
   "license": "Apache-2.0",
   "author": "Gabriel Loewen",
-  "homepage": "https://gabloe.github.io/felix/clients/typescript/",
+  "homepage": "https://docs.getfelix.dev/clients/typescript/",
   "repository": {
     "type": "git",
-    "url": "https://github.com/gabloe/felix.git",
-    "directory": "crates/felix-typescript"
+    "url": "https://github.com/GetFelix/felix.git",
+    "directory": "crates/sdk/felix-typescript"
   },
   "bugs": {
-    "url": "https://github.com/gabloe/felix/issues"
+    "url": "https://github.com/GetFelix/felix/issues"
   },
   "main": "index.js",
   "types": "index.d.ts",
   "files": [
     "index.js",
+    "errors.js",
     "index.d.ts",
     "README.md",
     "LICENSE"
@@ -50,13 +51,13 @@
   "scripts": {
     "build": "napi build --platform --release",
     "build:debug": "napi build --platform",
-    "test": "node --test test/conformance.test.mjs"
+    "test": "node --test test/errors.test.mjs test/conformance.test.mjs"
   },
   "optionalDependencies": {
-    "felix-client-darwin-arm64": "0.5.0",
-    "felix-client-darwin-x64": "0.5.0",
-    "felix-client-linux-arm64-gnu": "0.5.0",
-    "felix-client-linux-x64-gnu": "0.5.0",
-    "felix-client-win32-x64-msvc": "0.5.0"
+    "felix-client-darwin-arm64": "0.6.0-preview.2",
+    "felix-client-darwin-x64": "0.6.0-preview.2",
+    "felix-client-linux-arm64-gnu": "0.6.0-preview.2",
+    "felix-client-linux-x64-gnu": "0.6.0-preview.2",
+    "felix-client-win32-x64-msvc": "0.6.0-preview.2"
   }
 }