@arbitro/client 0.5.0 → 0.5.2

package/README.md

@@ -111,6 +111,11 @@ await client.upsertConsumer('orders', { name: 'workers', filter: 'orders.>' })
 await client.deleteConsumer('workers')
 await client.deleteStream('orders')                        // default: delete metadata + data
 await client.deleteStream('orders', { deleteData: false }) // preserve journal bytes
+
+// Per-message deletion (tombstones a single message by sequence number)
+await client.deleteMessage('orders', 42n)                  // true if deleted, false if not found/already deleted
+await stream.deleteMessage(42n)                            // convenience — delegates to client.deleteMessage
+await consumer.deleteMessage(42n)                          // convenience — delegates to client.deleteMessage
 ```
 
 ## Stream / consumer sugar
@@ -339,6 +344,10 @@ npm run test:integration   # requires Docker
 - `.agent/rules/*.md` — internal coding rules (hot-path discipline, wire protocol, etc.).
 - `CLAUDE.md` — index pointing at the rule files.
 
+## Replication
+
+Replication is transparent to the client -- `replicas` is set at `create_stream` time. The client publishes normally; the broker handles replication internally.
+
 ## License
 
 MIT — see [LICENSE](./LICENSE).

package/dist/{chunk-C2QLJBAC.mjs → chunk-3EHQPPLU.mjs}

@@ -62,6 +62,7 @@ var Action = /* @__PURE__ */ ((Action2) => {
   Action2[Action2["ListStreams"] = 1028] = "ListStreams";
   Action2[Action2["PurgeStream"] = 1029] = "PurgeStream";
   Action2[Action2["DrainSubject"] = 1030] = "DrainSubject";
+  Action2[Action2["DeleteMessage"] = 1031] = "DeleteMessage";
   Action2[Action2["CreateConsumer"] = 1281] = "CreateConsumer";
   Action2[Action2["DeleteConsumer"] = 1282] = "DeleteConsumer";
   Action2[Action2["GetConsumer"] = 1283] = "GetConsumer";
@@ -99,4 +100,4 @@ export {
   EntryFlag,
   Action
 };
-//# sourceMappingURL=chunk-C2QLJBAC.mjs.map
+//# sourceMappingURL=chunk-3EHQPPLU.mjs.map

package/dist/chunk-3EHQPPLU.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/proto/constants.ts"],"sourcesContent":["// V2 wire protocol constants — must match arbitro-proto/src/action.rs exactly.\n\n// ── Hello handshake (only frame without a Header) ───────────────────────\nexport const MAGIC_V2       = 0x32425241  // \"ARB2\" as u32 LE\nexport const HELLO_SIZE     = 8\nexport const CURRENT_VERSION = 2\n\nexport const enum Role {\n  Client = 0,\n  Server = 1,\n}\n\nexport const enum Cap {\n  Headers          = 1 << 0,\n  Reply            = 1 << 1,\n  BatchHeaders     = 1 << 2,\n  CompressedPayload = 1 << 3,\n}\n\n// ── Header (16 bytes, every frame after Hello) ──────────────────────────\nexport const HEADER_SIZE     = 16\n\n// Byte offsets within the 16-byte header\nexport const OFF_ACTION      = 0   // u16 LE\nexport const OFF_FLAGS       = 2   // u8\nexport const OFF_ENTRY_FLAGS = 3   // u8\nexport const OFF_MSG_LEN     = 4   // u32 LE\nexport const OFF_SEQ         = 8   // u64 LE\n\n// ── Transport flags (header.flags, offset 2) ────────────────────────────\nexport const enum Flag {\n  None         = 0x00,\n  AckReq       = 0x01,\n  Dup          = 0x02,\n  PriorityHigh = 0x04,\n}\n\n// ── Per-message flags (header.entry_flags, offset 3) ────────────────────\nexport const enum EntryFlag {\n  None           = 0x00,\n  Retain         = 0x01,\n  Compressed     = 0x02,\n  NoBackpressure = 0x04,\n}\n\n// ── Action codes (0xFFGG: FF=family, GG=variant) ────────────────────────\nexport const enum Action {\n  // 0x00xx — Handshake / control\n  Hello           = 0x0001,\n  Auth            = 0x0002,\n\n  // 0x01xx — Publish family\n  Publish                 = 0x0101,\n  PublishAccumulate       = 0x0102,\n  PublishBatch            = 0x0103,\n  PublishWithReply        = 0x0104,\n  PublishWithHeaders      = 0x0105,\n  PublishBatchWithHeaders = 0x0106,\n\n  // 0x02xx — Delivery / Ack\n  Deliver      = 0x0200,\n  Ack          = 0x0201,\n  Nack         = 0x0202,\n  RepOk        = 0x0203,\n  RepError     = 0x0204,\n  RepBatch     = 0x0205,\n  BatchAck     = 0x0206,\n  FanoutBatch  = 0x0207,\n  AckSync      = 0x0208,\n  BatchAckSync = 0x0209,\n  BatchNack    = 0x020A,\n\n  // 0x03xx — Subscription\n  Subscribe   = 0x0301,\n  Unsubscribe = 0x0302,\n\n  // 0x04xx — Stream management\n  CreateStream  = 0x0401,\n  DeleteStream  = 0x0402,\n  GetStream     = 0x0403,\n  ListStreams   = 0x0404,\n  PurgeStream   = 0x0405,\n  DrainSubject  = 0x0406,\n  DeleteMessage = 0x0407,\n\n  // 0x05xx — Consumer management\n  CreateConsumer = 0x0501,\n  DeleteConsumer = 0x0502,\n  GetConsumer    = 0x0503,\n  ListConsumers  = 0x0504,\n  ConsumerStats  = 0x0505,\n  PauseConsumer  = 0x0506,\n  ResumeConsumer = 0x0507,\n\n  // 0x08xx — Delayed publish\n  PublishDelayed = 0x0801,\n\n  // 0x06xx — System\n  Ping       = 0x0601,\n  Pong       = 0x0602,\n  Connect    = 0x0603,\n  Connected  = 0x0604,\n  Disconnect = 0x0605,\n\n  // 0x07xx — Cron scheduling\n  CreateCron = 0x0701,\n  DeleteCron = 0x0702,\n  ListCrons  = 0x0703,\n  CronFire   = 0x0704,\n  CronAck    = 0x0705,\n\n  // 0x09xx reserved (workflow removed — now a client-side library).\n}\n"],"mappings":"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","names":["Role","Cap","Flag","EntryFlag","Action"]}

package/dist/{chunk-GW36GP2C.mjs → chunk-BSPQZJHF.mjs}

@@ -8,7 +8,7 @@ import {
   OFF_FLAGS,
   OFF_MSG_LEN,
   OFF_SEQ
-} from "./chunk-C2QLJBAC.mjs";
+} from "./chunk-3EHQPPLU.mjs";
 
 // src/proto/frame.ts
 function frame(action, seq, bodyLen, flags = 0, entryFlags = 0) {
@@ -121,4 +121,4 @@ export {
   packPublishDelayed,
   packPublishBatch
 };
-//# sourceMappingURL=chunk-GW36GP2C.mjs.map
+//# sourceMappingURL=chunk-BSPQZJHF.mjs.map

package/dist/{constants-57DO6N3H.mjs → constants-LWTWKOBZ.mjs}

@@ -13,7 +13,7 @@ import {
   OFF_MSG_LEN,
   OFF_SEQ,
   Role
-} from "./chunk-C2QLJBAC.mjs";
+} from "./chunk-3EHQPPLU.mjs";
 export {
   Action,
   CURRENT_VERSION,
@@ -30,4 +30,4 @@ export {
   OFF_SEQ,
   Role
 };
-//# sourceMappingURL=constants-57DO6N3H.mjs.map
+//# sourceMappingURL=constants-LWTWKOBZ.mjs.map

package/dist/index.d.mts

@@ -463,6 +463,8 @@ declare class Consumer {
      * from `streamName + name`. Equivalent of NATS `num_ack_pending`.
      */
     getPendings(): Promise<number>;
+    /** Tombstone a single message by seq. Returns true if found. */
+    deleteMessage(seq: bigint): Promise<boolean>;
     subscribe(cb?: RawCallback, opts?: SubscribeOptions): Promise<Subscription>;
     subscribe<T extends Record<string, unknown>>(codec: Encoding<T>, cb: (msg: LazyMessage<T>) => void, opts?: SubscribeOptions): Promise<Subscription>;
 }
@@ -574,6 +576,14 @@ declare class ArbitroClient {
     streamExists(name: string): Promise<boolean>;
     purgeStream(name: string): Promise<number>;
     drainSubject(streamName: string, subject: string): Promise<number>;
+    /**
+     * Tombstone a single message by sequence number.
+     *
+     * The broker marks the entry as deleted — it will never be delivered
+     * to any consumer. Returns `true` if the message was found and
+     * tombstoned, `false` if not found or already tombstoned.
+     */
+    deleteMessage(streamName: string, seq: bigint): Promise<boolean>;
     createConsumer(streamName: string, config: ConsumerConfig): Promise<Consumer>;
     private createConsumerRaw;
     upsertConsumer(streamName: string, config: ConsumerConfig): Promise<Consumer>;
@@ -638,6 +648,8 @@ declare class Stream {
      *  with the broker; the caller decides whether to wait via `await`. */
     publishBatch(messages: BatchPublishEntry[]): Promise<bigint>;
     request(subject: string, data: Buffer, timeoutMs?: number): Promise<Buffer>;
+    /** Tombstone a single message by seq. Returns true if found. */
+    deleteMessage(seq: bigint): Promise<boolean>;
     consumer(overrides?: Partial<ConsumerConfig>): Consumer;
     topic<T extends Record<string, unknown>>(subject: string, codec: Encoding<T>): Topic<T>;
 }

package/dist/index.d.ts

@@ -463,6 +463,8 @@ declare class Consumer {
      * from `streamName + name`. Equivalent of NATS `num_ack_pending`.
      */
     getPendings(): Promise<number>;
+    /** Tombstone a single message by seq. Returns true if found. */
+    deleteMessage(seq: bigint): Promise<boolean>;
     subscribe(cb?: RawCallback, opts?: SubscribeOptions): Promise<Subscription>;
     subscribe<T extends Record<string, unknown>>(codec: Encoding<T>, cb: (msg: LazyMessage<T>) => void, opts?: SubscribeOptions): Promise<Subscription>;
 }
@@ -574,6 +576,14 @@ declare class ArbitroClient {
     streamExists(name: string): Promise<boolean>;
     purgeStream(name: string): Promise<number>;
     drainSubject(streamName: string, subject: string): Promise<number>;
+    /**
+     * Tombstone a single message by sequence number.
+     *
+     * The broker marks the entry as deleted — it will never be delivered
+     * to any consumer. Returns `true` if the message was found and
+     * tombstoned, `false` if not found or already tombstoned.
+     */
+    deleteMessage(streamName: string, seq: bigint): Promise<boolean>;
     createConsumer(streamName: string, config: ConsumerConfig): Promise<Consumer>;
     private createConsumerRaw;
     upsertConsumer(streamName: string, config: ConsumerConfig): Promise<Consumer>;
@@ -638,6 +648,8 @@ declare class Stream {
      *  with the broker; the caller decides whether to wait via `await`. */
     publishBatch(messages: BatchPublishEntry[]): Promise<bigint>;
     request(subject: string, data: Buffer, timeoutMs?: number): Promise<Buffer>;
+    /** Tombstone a single message by seq. Returns true if found. */
+    deleteMessage(seq: bigint): Promise<boolean>;
     consumer(overrides?: Partial<ConsumerConfig>): Consumer;
     topic<T extends Record<string, unknown>>(subject: string, codec: Encoding<T>): Topic<T>;
 }

package/dist/index.js

@@ -115,6 +115,7 @@ var init_constants = __esm({
       Action2[Action2["ListStreams"] = 1028] = "ListStreams";
       Action2[Action2["PurgeStream"] = 1029] = "PurgeStream";
       Action2[Action2["DrainSubject"] = 1030] = "DrainSubject";
+      Action2[Action2["DeleteMessage"] = 1031] = "DeleteMessage";
       Action2[Action2["CreateConsumer"] = 1281] = "CreateConsumer";
       Action2[Action2["DeleteConsumer"] = 1282] = "DeleteConsumer";
       Action2[Action2["GetConsumer"] = 1283] = "GetConsumer";
@@ -562,6 +563,7 @@ var packDrainSubject = (seq, name, subject) => packCold2(1030 /* DrainSubject */
   name: bytesArr(name),
   subject: bytesArr(subject)
 });
+var packDeleteMessage = (seq, name, msgSeq) => packCold2(1031 /* DeleteMessage */, seq, { name: bytesArr(name), seq: Number(msgSeq) });
 var packListStreams = (seq, offset = 0, limit = 1e3) => packCold2(1028 /* ListStreams */, seq, { offset: offset >>> 0, limit: limit >>> 0 });
 function packCreateConsumer(seq, opts) {
   const limits = (opts.subjectLimits ?? []).map((l) => ({
@@ -1225,6 +1227,10 @@ var Consumer = class {
     }
     return this.client.getPending(this.streamName, this.name);
   }
+  /** Tombstone a single message by seq. Returns true if found. */
+  deleteMessage(seq) {
+    return this.client.deleteMessage(this.streamName, seq);
+  }
   subscribe(codecOrCb, cbOrOpts, opts) {
     if (!codecOrCb || typeof codecOrCb === "function") {
       return this.client.subscribe(
@@ -1314,6 +1320,10 @@ var Stream = class {
   request(subject, data, timeoutMs) {
     return this.client.request(this.name, subject, data, timeoutMs);
   }
+  /** Tombstone a single message by seq. Returns true if found. */
+  deleteMessage(seq) {
+    return this.client.deleteMessage(this.name, seq);
+  }
   // ── Context factories ───────────────────────────────────────────────────
   consumer(overrides) {
     const config = {
@@ -1701,6 +1711,19 @@ var ArbitroClient = class {
     );
     return Number(refSeq);
   }
+  /**
+   * Tombstone a single message by sequence number.
+   *
+   * The broker marks the entry as deleted — it will never be delivered
+   * to any consumer. Returns `true` if the message was found and
+   * tombstoned, `false` if not found or already tombstoned.
+   */
+  async deleteMessage(streamName, seq) {
+    const refSeq = await this.conn.sendExpectReply(
+      packDeleteMessage(this.conn.nextSeq(), Buffer.from(streamName), seq)
+    );
+    return refSeq > 0n;
+  }
   // ── Consumer management ───────────────────────────────────────────────────
   async createConsumer(streamName, config) {
     const consumerId = await this.createConsumerRaw(streamName, config);