@drarzter/kafka-client 0.9.3 → 0.10.0

package/dist/cli/index.mjs

@@ -0,0 +1,355 @@
+#!/usr/bin/env node
+import {
+  ConfluentTransport,
+  KafkaClient
+} from "../chunk-CMO7SMVK.mjs";
+import "../chunk-EQQGB2QZ.mjs";
+
+// src/cli/dlq.ts
+var DLQ_SUFFIX = ".dlq";
+var DlqUsageError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "DlqUsageError";
+  }
+};
+var USAGE = `kafka-client-dlq \u2014 dead-letter queue operations
+
+Usage:
+  kafka-client-dlq ls     --brokers <b1,b2> [--prefix <name>]
+  kafka-client-dlq peek   --brokers <b1,b2> --topic <name> [--limit <n>]
+  kafka-client-dlq replay --brokers <b1,b2> --topic <name> [--target <t>] [--dry-run] [--from-beginning | --incremental]
+
+Commands:
+  ls       List DLQ topics (ending in .dlq) with per-topic message counts.
+  peek     Print up to N messages from <topic>.dlq (offset, x-dlq-* headers, value).
+  replay   Re-publish <topic>.dlq messages to their original topic (or --target).
+
+Options:
+  --brokers <list>    Comma-separated broker addresses (required).       e.g. localhost:9092
+  --prefix <name>     ls: only show DLQ topics whose base name starts with <name>.
+  --topic <name>      peek/replay: base topic name (the CLI uses <name>.dlq).
+  --limit <n>         peek: max messages to print (default 10).
+  --target <t>        replay: override destination topic.
+  --dry-run           replay: log without publishing.
+  --from-beginning    replay: full replay every call (default).
+  --incremental       replay: only messages added since the previous replay.
+  -h, --help          Show this help.
+
+Examples:
+  kafka-client-dlq ls --brokers localhost:9092
+  kafka-client-dlq ls --brokers localhost:9092 --prefix orders
+  kafka-client-dlq peek --brokers localhost:9092 --topic orders.created --limit 5
+  kafka-client-dlq replay --brokers localhost:9092 --topic orders.created --dry-run
+  kafka-client-dlq replay --brokers localhost:9092 --topic orders.created --target orders.manual --incremental
+`;
+var VALUE_FLAGS = /* @__PURE__ */ new Set([
+  "--brokers",
+  "--prefix",
+  "--topic",
+  "--limit",
+  "--target"
+]);
+var BOOL_FLAGS = /* @__PURE__ */ new Set(["--dry-run", "--from-beginning", "--incremental"]);
+function parseFlags(args) {
+  const values = {};
+  const bools = /* @__PURE__ */ new Set();
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (!arg.startsWith("--")) {
+      throw new DlqUsageError(`Unexpected argument: "${arg}"`);
+    }
+    if (VALUE_FLAGS.has(arg)) {
+      const value = args[i + 1];
+      if (value === void 0 || value.startsWith("--")) {
+        throw new DlqUsageError(`Flag "${arg}" requires a value.`);
+      }
+      values[arg] = value;
+      i++;
+    } else if (BOOL_FLAGS.has(arg)) {
+      bools.add(arg);
+    } else {
+      throw new DlqUsageError(`Unknown flag: "${arg}"`);
+    }
+  }
+  return { values, bools };
+}
+function requireBrokers(flags) {
+  const raw = flags.values["--brokers"];
+  if (raw === void 0) {
+    throw new DlqUsageError("Missing required flag: --brokers");
+  }
+  const brokers = raw.split(",").map((b) => b.trim()).filter((b) => b.length > 0);
+  if (brokers.length === 0) {
+    throw new DlqUsageError("--brokers must list at least one broker address.");
+  }
+  return brokers;
+}
+function requireTopic(flags) {
+  const topic = flags.values["--topic"];
+  if (topic === void 0 || topic.length === 0) {
+    throw new DlqUsageError("Missing required flag: --topic");
+  }
+  return topic;
+}
+function parseArgs(argv) {
+  const [command, ...rest] = argv;
+  if (command === void 0 || command === "-h" || command === "--help" || command === "help") {
+    return { command: "help" };
+  }
+  switch (command) {
+    case "ls": {
+      const flags = parseFlags(rest);
+      const brokers = requireBrokers(flags);
+      const prefix = flags.values["--prefix"];
+      return { command: "ls", brokers, prefix };
+    }
+    case "peek": {
+      const flags = parseFlags(rest);
+      const brokers = requireBrokers(flags);
+      const topic = requireTopic(flags);
+      const limit = parseLimit(flags.values["--limit"]);
+      return { command: "peek", brokers, topic, limit };
+    }
+    case "replay": {
+      const flags = parseFlags(rest);
+      const brokers = requireBrokers(flags);
+      const topic = requireTopic(flags);
+      const target = flags.values["--target"];
+      const dryRun = flags.bools.has("--dry-run");
+      if (flags.bools.has("--from-beginning") && flags.bools.has("--incremental")) {
+        throw new DlqUsageError(
+          "--from-beginning and --incremental are mutually exclusive."
+        );
+      }
+      const fromBeginning = !flags.bools.has("--incremental");
+      return { command: "replay", brokers, topic, target, dryRun, fromBeginning };
+    }
+    default:
+      throw new DlqUsageError(`Unknown command: "${command}"`);
+  }
+}
+function parseLimit(raw) {
+  if (raw === void 0) return 10;
+  const n = Number(raw);
+  if (!Number.isInteger(n) || n <= 0) {
+    throw new DlqUsageError(`--limit must be a positive integer, got "${raw}".`);
+  }
+  return n;
+}
+function countFromWatermarks(watermarks) {
+  let total = 0;
+  for (const { low, high } of watermarks) {
+    const width = Number(high) - Number(low);
+    total += width > 0 ? width : 0;
+  }
+  return total;
+}
+function truncate(value, max = 200) {
+  if (value.length <= max) return value;
+  return `${value.slice(0, max)}\u2026 (${value.length} chars)`;
+}
+async function runDlqCommand(cmd, deps) {
+  if (cmd.command === "help") {
+    deps.out(USAGE);
+    return { command: "help" };
+  }
+  const client = await deps.createClient(cmd.brokers);
+  try {
+    switch (cmd.command) {
+      case "ls":
+        return await runLs(cmd, client, deps);
+      case "peek":
+        return await runPeek(cmd, client, deps);
+      case "replay":
+        return await runReplay(cmd, client, deps);
+    }
+  } finally {
+    await client.close();
+  }
+}
+async function runLs(cmd, client, deps) {
+  const allTopics = await client.listTopics();
+  let dlqTopics = allTopics.filter((t) => t.endsWith(DLQ_SUFFIX));
+  if (cmd.prefix) {
+    const prefix = cmd.prefix;
+    dlqTopics = dlqTopics.filter(
+      (t) => t.slice(0, -DLQ_SUFFIX.length).startsWith(prefix)
+    );
+  }
+  dlqTopics.sort();
+  const counts = [];
+  for (const dlqTopic of dlqTopics) {
+    const watermarks = await client.fetchTopicOffsets(dlqTopic);
+    counts.push({
+      dlqTopic,
+      baseTopic: dlqTopic.slice(0, -DLQ_SUFFIX.length),
+      count: countFromWatermarks(watermarks)
+    });
+  }
+  if (counts.length === 0) {
+    deps.out(
+      cmd.prefix ? `No DLQ topics found matching prefix "${cmd.prefix}".` : "No DLQ topics found."
+    );
+  } else {
+    const width = Math.max(...counts.map((c) => c.dlqTopic.length));
+    deps.out(`${"TOPIC".padEnd(width)}  MESSAGES`);
+    for (const c of counts) {
+      deps.out(`${c.dlqTopic.padEnd(width)}  ${c.count}`);
+    }
+    const total = counts.reduce((s, c) => s + c.count, 0);
+    deps.out(`${counts.length} DLQ topic(s), ${total} message(s) total.`);
+  }
+  return { command: "ls", topics: counts };
+}
+async function runPeek(cmd, client, deps) {
+  const dlqTopic = `${cmd.topic}${DLQ_SUFFIX}`;
+  const messages = await client.peekMessages(dlqTopic, cmd.limit);
+  if (messages.length === 0) {
+    deps.out(`No messages in ${dlqTopic}.`);
+    return { command: "peek", printed: 0 };
+  }
+  deps.out(`Peeking up to ${cmd.limit} message(s) from ${dlqTopic}:`);
+  let printed = 0;
+  for (const env of messages) {
+    if (printed >= cmd.limit) break;
+    deps.out("");
+    deps.out(
+      `\u2500 offset ${env.offset} \xB7 partition ${env.partition} \xB7 ${env.timestamp}`
+    );
+    const dlqHeaders = Object.entries(env.headers).filter(([k]) => k.startsWith("x-dlq-")).sort(([a], [b]) => a.localeCompare(b));
+    for (const [k, v] of dlqHeaders) {
+      deps.out(`    ${k}: ${truncate(String(v), 500)}`);
+    }
+    deps.out(`    value: ${truncate(JSON.stringify(env.payload))}`);
+    printed++;
+  }
+  deps.out("");
+  deps.out(`Printed ${printed} message(s).`);
+  return { command: "peek", printed };
+}
+async function runReplay(cmd, client, deps) {
+  const options = {
+    dryRun: cmd.dryRun,
+    fromBeginning: cmd.fromBeginning
+  };
+  if (cmd.target !== void 0) options.targetTopic = cmd.target;
+  const mode = cmd.fromBeginning ? "full" : "incremental";
+  const targetDesc = cmd.target ? ` \u2192 ${cmd.target}` : " \u2192 original topic";
+  deps.out(
+    `Replaying ${cmd.topic}${DLQ_SUFFIX}${targetDesc} (${mode}${cmd.dryRun ? ", dry-run" : ""})\u2026`
+  );
+  const { replayed, skipped } = await client.replayDlq(cmd.topic, options);
+  deps.out(
+    cmd.dryRun ? `Dry-run: ${replayed} message(s) would be replayed, ${skipped} skipped.` : `Replayed ${replayed} message(s), ${skipped} skipped.`
+  );
+  return { command: "replay", replayed, skipped, dryRun: cmd.dryRun };
+}
+
+// src/cli/index.ts
+var CLIENT_ID = `dlq-cli-${process.pid}`;
+var GROUP_ID = `${CLIENT_ID}-peek`;
+function createRealClient(brokers) {
+  const transport = new ConfluentTransport(CLIENT_ID, brokers);
+  const kafka = new KafkaClient(
+    CLIENT_ID,
+    GROUP_ID,
+    brokers,
+    { transport, autoCreateTopics: false, strictSchemas: false }
+  );
+  const admin = transport.admin();
+  let adminConnected = false;
+  async function ensureAdmin() {
+    if (!adminConnected) {
+      await admin.connect();
+      adminConnected = true;
+    }
+  }
+  return {
+    async listTopics() {
+      const status = await kafka.checkStatus();
+      if (status.status === "down") {
+        throw new Error(`Broker unreachable: ${status.error}`);
+      }
+      return status.topics;
+    },
+    async fetchTopicOffsets(topic) {
+      await ensureAdmin();
+      return admin.fetchTopicOffsets(topic);
+    },
+    async peekMessages(dlqTopic, limit) {
+      const collected = [];
+      const iterator = kafka.consume(dlqTopic, {
+        groupId: `${dlqTopic}.dlq-peek-${Date.now()}`,
+        fromBeginning: true
+      });
+      await ensureAdmin();
+      const watermarks = await admin.fetchTopicOffsets(dlqTopic);
+      const available = watermarks.reduce(
+        (sum, w) => sum + Math.max(0, Number(w.high) - Number(w.low)),
+        0
+      );
+      const target = Math.min(limit, available);
+      if (target === 0) {
+        await iterator.return?.();
+        return collected;
+      }
+      try {
+        for await (const env of iterator) {
+          collected.push(env);
+          if (collected.length >= target) break;
+        }
+      } finally {
+        await iterator.return?.();
+      }
+      return collected;
+    },
+    replayDlq(topic, options) {
+      return kafka.replayDlq(topic, options);
+    },
+    async close() {
+      if (adminConnected) {
+        await admin.disconnect().catch(() => {
+        });
+      }
+      await kafka.disconnect().catch(() => {
+      });
+    }
+  };
+}
+async function main() {
+  let cmd;
+  try {
+    cmd = parseArgs(process.argv.slice(2));
+  } catch (err) {
+    if (err instanceof DlqUsageError) {
+      process.stderr.write(`Error: ${err.message}
+
+`);
+      process.stderr.write(USAGE);
+      return 2;
+    }
+    throw err;
+  }
+  try {
+    await runDlqCommand(cmd, {
+      createClient: createRealClient,
+      out: (line) => process.stdout.write(`${line}
+`)
+    });
+    return 0;
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    process.stderr.write(`Error: ${message}
+`);
+    return 1;
+  }
+}
+main().then((code) => {
+  process.exitCode = code;
+}).catch((err) => {
+  process.stderr.write(`Fatal: ${err?.stack ?? err}
+`);
+  process.exitCode = 1;
+});
+//# sourceMappingURL=index.mjs.map

package/dist/cli/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/cli/dlq.ts","../../src/cli/index.ts"],"sourcesContent":["import type { EventEnvelope } from \"../core\";\nimport type { DlqReplayOptions } from \"../core\";\n\n// ── Parsed command shapes ─────────────────────────────────────────────────────\n\n/** DLQ topic suffix — the CLI operates on `<topic>.dlq`. */\nexport const DLQ_SUFFIX = \".dlq\";\n\n/** `ls` — list DLQ topics with message counts. */\nexport interface LsCommand {\n  command: \"ls\";\n  brokers: string[];\n  /** Optional topic-name prefix filter (matched against the base topic). */\n  prefix?: string;\n}\n\n/** `peek` — print the first N messages of `<topic>.dlq`. */\nexport interface PeekCommand {\n  command: \"peek\";\n  brokers: string[];\n  /** Base topic name — the CLI reads from `<topic>.dlq`. */\n  topic: string;\n  /** Maximum number of messages to print. Default: 10. */\n  limit: number;\n}\n\n/** `replay` — re-publish `<topic>.dlq` messages via `KafkaClient.replayDlq`. */\nexport interface ReplayCommand {\n  command: \"replay\";\n  brokers: string[];\n  /** Base topic name — the CLI replays `<topic>.dlq`. */\n  topic: string;\n  /** Override destination topic (default: read from `x-dlq-original-topic`). */\n  target?: string;\n  /** Log what would be replayed without publishing. */\n  dryRun: boolean;\n  /**\n   * `true`  → full replay of all DLQ messages on every call (ephemeral group).\n   * `false` → incremental — only messages since the previous replay (stable group).\n   */\n  fromBeginning: boolean;\n}\n\n/** `help` — print usage. */\nexport interface HelpCommand {\n  command: \"help\";\n}\n\n/** Discriminated union of every parsed CLI invocation. */\nexport type ParsedCommand = LsCommand | PeekCommand | ReplayCommand | HelpCommand;\n\n/** Thrown by `parseArgs` when the argv is invalid. Carries the usage text. */\nexport class DlqUsageError extends Error {\n  constructor(message: string) {\n    super(message);\n    this.name = \"DlqUsageError\";\n  }\n}\n\n// ── Usage text ────────────────────────────────────────────────────────────────\n\nexport const USAGE = `kafka-client-dlq — dead-letter queue operations\n\nUsage:\n  kafka-client-dlq ls     --brokers <b1,b2> [--prefix <name>]\n  kafka-client-dlq peek   --brokers <b1,b2> --topic <name> [--limit <n>]\n  kafka-client-dlq replay --brokers <b1,b2> --topic <name> [--target <t>] [--dry-run] [--from-beginning | --incremental]\n\nCommands:\n  ls       List DLQ topics (ending in .dlq) with per-topic message counts.\n  peek     Print up to N messages from <topic>.dlq (offset, x-dlq-* headers, value).\n  replay   Re-publish <topic>.dlq messages to their original topic (or --target).\n\nOptions:\n  --brokers <list>    Comma-separated broker addresses (required).       e.g. localhost:9092\n  --prefix <name>     ls: only show DLQ topics whose base name starts with <name>.\n  --topic <name>      peek/replay: base topic name (the CLI uses <name>.dlq).\n  --limit <n>         peek: max messages to print (default 10).\n  --target <t>        replay: override destination topic.\n  --dry-run           replay: log without publishing.\n  --from-beginning    replay: full replay every call (default).\n  --incremental       replay: only messages added since the previous replay.\n  -h, --help          Show this help.\n\nExamples:\n  kafka-client-dlq ls --brokers localhost:9092\n  kafka-client-dlq ls --brokers localhost:9092 --prefix orders\n  kafka-client-dlq peek --brokers localhost:9092 --topic orders.created --limit 5\n  kafka-client-dlq replay --brokers localhost:9092 --topic orders.created --dry-run\n  kafka-client-dlq replay --brokers localhost:9092 --topic orders.created --target orders.manual --incremental\n`;\n\n// ── Argument parsing ────────────────────────────────────────────────────────────\n\n/** Flags that take a value (`--flag value`). */\nconst VALUE_FLAGS = new Set([\n  \"--brokers\",\n  \"--prefix\",\n  \"--topic\",\n  \"--limit\",\n  \"--target\",\n]);\n/** Boolean flags (no value). */\nconst BOOL_FLAGS = new Set([\"--dry-run\", \"--from-beginning\", \"--incremental\"]);\n\ninterface RawFlags {\n  values: Record<string, string>;\n  bools: Set<string>;\n}\n\n/** Split the flag portion of argv into value flags and boolean flags. */\nfunction parseFlags(args: string[]): RawFlags {\n  const values: Record<string, string> = {};\n  const bools = new Set<string>();\n\n  for (let i = 0; i < args.length; i++) {\n    const arg = args[i];\n    if (!arg.startsWith(\"--\")) {\n      throw new DlqUsageError(`Unexpected argument: \"${arg}\"`);\n    }\n    if (VALUE_FLAGS.has(arg)) {\n      const value = args[i + 1];\n      if (value === undefined || value.startsWith(\"--\")) {\n        throw new DlqUsageError(`Flag \"${arg}\" requires a value.`);\n      }\n      values[arg] = value;\n      i++; // consume the value\n    } else if (BOOL_FLAGS.has(arg)) {\n      bools.add(arg);\n    } else {\n      throw new DlqUsageError(`Unknown flag: \"${arg}\"`);\n    }\n  }\n\n  return { values, bools };\n}\n\n/** Parse comma-separated brokers, requiring at least one non-empty entry. */\nfunction requireBrokers(flags: RawFlags): string[] {\n  const raw = flags.values[\"--brokers\"];\n  if (raw === undefined) {\n    throw new DlqUsageError(\"Missing required flag: --brokers\");\n  }\n  const brokers = raw\n    .split(\",\")\n    .map((b) => b.trim())\n    .filter((b) => b.length > 0);\n  if (brokers.length === 0) {\n    throw new DlqUsageError(\"--brokers must list at least one broker address.\");\n  }\n  return brokers;\n}\n\nfunction requireTopic(flags: RawFlags): string {\n  const topic = flags.values[\"--topic\"];\n  if (topic === undefined || topic.length === 0) {\n    throw new DlqUsageError(\"Missing required flag: --topic\");\n  }\n  return topic;\n}\n\n/**\n * Parse the process argv (already sliced past `node <script>`) into a\n * `ParsedCommand`. Pure and synchronous — no I/O — so it is fully unit-testable.\n *\n * @throws {DlqUsageError} on unknown commands, missing/invalid flags.\n */\nexport function parseArgs(argv: string[]): ParsedCommand {\n  const [command, ...rest] = argv;\n\n  if (\n    command === undefined ||\n    command === \"-h\" ||\n    command === \"--help\" ||\n    command === \"help\"\n  ) {\n    return { command: \"help\" };\n  }\n\n  switch (command) {\n    case \"ls\": {\n      const flags = parseFlags(rest);\n      const brokers = requireBrokers(flags);\n      const prefix = flags.values[\"--prefix\"];\n      return { command: \"ls\", brokers, prefix };\n    }\n    case \"peek\": {\n      const flags = parseFlags(rest);\n      const brokers = requireBrokers(flags);\n      const topic = requireTopic(flags);\n      const limit = parseLimit(flags.values[\"--limit\"]);\n      return { command: \"peek\", brokers, topic, limit };\n    }\n    case \"replay\": {\n      const flags = parseFlags(rest);\n      const brokers = requireBrokers(flags);\n      const topic = requireTopic(flags);\n      const target = flags.values[\"--target\"];\n      const dryRun = flags.bools.has(\"--dry-run\");\n      if (\n        flags.bools.has(\"--from-beginning\") &&\n        flags.bools.has(\"--incremental\")\n      ) {\n        throw new DlqUsageError(\n          \"--from-beginning and --incremental are mutually exclusive.\",\n        );\n      }\n      // Default is full replay (fromBeginning: true); --incremental opts out.\n      const fromBeginning = !flags.bools.has(\"--incremental\");\n      return { command: \"replay\", brokers, topic, target, dryRun, fromBeginning };\n    }\n    default:\n      throw new DlqUsageError(`Unknown command: \"${command}\"`);\n  }\n}\n\nfunction parseLimit(raw: string | undefined): number {\n  if (raw === undefined) return 10;\n  const n = Number(raw);\n  if (!Number.isInteger(n) || n <= 0) {\n    throw new DlqUsageError(`--limit must be a positive integer, got \"${raw}\".`);\n  }\n  return n;\n}\n\n// ── Runtime deps (injected — tests pass a fake) ──────────────────────────────────\n\n/** Per-partition low/high watermarks for a topic. */\nexport interface PartitionWatermarks {\n  partition: number;\n  low: string;\n  high: string;\n}\n\n/**\n * Minimal client surface the CLI needs. The production factory backs this with\n * a real `KafkaClient` plus its transport admin; tests inject a fake.\n */\nexport interface DlqCliClient {\n  /** List all topics visible to the broker (via `checkStatus`). */\n  listTopics(): Promise<string[]>;\n  /** Per-partition low/high watermarks for a single topic. */\n  fetchTopicOffsets(topic: string): Promise<PartitionWatermarks[]>;\n  /** Read up to `limit` messages from `dlqTopic`, from the earliest offset. */\n  peekMessages(\n    dlqTopic: string,\n    limit: number,\n  ): Promise<Array<EventEnvelope<unknown>>>;\n  /** Delegate to `KafkaClient.replayDlq`. */\n  replayDlq(\n    topic: string,\n    options: DlqReplayOptions,\n  ): Promise<{ replayed: number; skipped: number }>;\n  /** Release all connections. */\n  close(): Promise<void>;\n}\n\n/** Injected dependencies for `runDlqCommand`. */\nexport interface RunDeps {\n  /** Build a connected client for the given brokers. */\n  createClient(brokers: string[]): DlqCliClient | Promise<DlqCliClient>;\n  /** Sink for human-readable output. Defaults are wired by the bin entrypoint. */\n  out: (line: string) => void;\n}\n\n// ── Result shapes (returned so the entrypoint / tests can assert) ────────────────\n\nexport interface DlqTopicCount {\n  /** The `<name>.dlq` topic. */\n  dlqTopic: string;\n  /** The base topic (`dlqTopic` without the `.dlq` suffix). */\n  baseTopic: string;\n  /** Sum over partitions of (high − low). */\n  count: number;\n}\n\nexport type RunResult =\n  | { command: \"ls\"; topics: DlqTopicCount[] }\n  | { command: \"peek\"; printed: number }\n  | { command: \"replay\"; replayed: number; skipped: number; dryRun: boolean }\n  | { command: \"help\" };\n\n// ── Command runner ───────────────────────────────────────────────────────────\n\n/** Sum (high − low) across a topic's partitions. Negative widths clamp to 0. */\nexport function countFromWatermarks(watermarks: PartitionWatermarks[]): number {\n  let total = 0;\n  for (const { low, high } of watermarks) {\n    const width = Number(high) - Number(low);\n    total += width > 0 ? width : 0;\n  }\n  return total;\n}\n\n/** Truncate a value for display, appending an ellipsis marker when cut. */\nexport function truncate(value: string, max = 200): string {\n  if (value.length <= max) return value;\n  return `${value.slice(0, max)}… (${value.length} chars)`;\n}\n\n/**\n * Execute a parsed command against injected deps.\n * Returns a structured result; all human-readable output goes through `deps.out`.\n * The client is always closed in a `finally` block.\n */\nexport async function runDlqCommand(\n  cmd: ParsedCommand,\n  deps: RunDeps,\n): Promise<RunResult> {\n  if (cmd.command === \"help\") {\n    deps.out(USAGE);\n    return { command: \"help\" };\n  }\n\n  const client = await deps.createClient(cmd.brokers);\n  try {\n    switch (cmd.command) {\n      case \"ls\":\n        return await runLs(cmd, client, deps);\n      case \"peek\":\n        return await runPeek(cmd, client, deps);\n      case \"replay\":\n        return await runReplay(cmd, client, deps);\n    }\n  } finally {\n    await client.close();\n  }\n}\n\nasync function runLs(\n  cmd: LsCommand,\n  client: DlqCliClient,\n  deps: RunDeps,\n): Promise<RunResult> {\n  const allTopics = await client.listTopics();\n  let dlqTopics = allTopics.filter((t) => t.endsWith(DLQ_SUFFIX));\n  if (cmd.prefix) {\n    const prefix = cmd.prefix;\n    dlqTopics = dlqTopics.filter((t) =>\n      t.slice(0, -DLQ_SUFFIX.length).startsWith(prefix),\n    );\n  }\n  dlqTopics.sort();\n\n  const counts: DlqTopicCount[] = [];\n  for (const dlqTopic of dlqTopics) {\n    const watermarks = await client.fetchTopicOffsets(dlqTopic);\n    counts.push({\n      dlqTopic,\n      baseTopic: dlqTopic.slice(0, -DLQ_SUFFIX.length),\n      count: countFromWatermarks(watermarks),\n    });\n  }\n\n  if (counts.length === 0) {\n    deps.out(\n      cmd.prefix\n        ? `No DLQ topics found matching prefix \"${cmd.prefix}\".`\n        : \"No DLQ topics found.\",\n    );\n  } else {\n    const width = Math.max(...counts.map((c) => c.dlqTopic.length));\n    deps.out(`${\"TOPIC\".padEnd(width)}  MESSAGES`);\n    for (const c of counts) {\n      deps.out(`${c.dlqTopic.padEnd(width)}  ${c.count}`);\n    }\n    const total = counts.reduce((s, c) => s + c.count, 0);\n    deps.out(`${counts.length} DLQ topic(s), ${total} message(s) total.`);\n  }\n\n  return { command: \"ls\", topics: counts };\n}\n\nasync function runPeek(\n  cmd: PeekCommand,\n  client: DlqCliClient,\n  deps: RunDeps,\n): Promise<RunResult> {\n  const dlqTopic = `${cmd.topic}${DLQ_SUFFIX}`;\n  const messages = await client.peekMessages(dlqTopic, cmd.limit);\n\n  if (messages.length === 0) {\n    deps.out(`No messages in ${dlqTopic}.`);\n    return { command: \"peek\", printed: 0 };\n  }\n\n  deps.out(`Peeking up to ${cmd.limit} message(s) from ${dlqTopic}:`);\n  let printed = 0;\n  for (const env of messages) {\n    if (printed >= cmd.limit) break;\n    deps.out(\"\");\n    deps.out(\n      `─ offset ${env.offset} · partition ${env.partition} · ${env.timestamp}`,\n    );\n    const dlqHeaders = Object.entries(env.headers)\n      .filter(([k]) => k.startsWith(\"x-dlq-\"))\n      .sort(([a], [b]) => a.localeCompare(b));\n    for (const [k, v] of dlqHeaders) {\n      deps.out(`    ${k}: ${truncate(String(v), 500)}`);\n    }\n    deps.out(`    value: ${truncate(JSON.stringify(env.payload))}`);\n    printed++;\n  }\n\n  deps.out(\"\");\n  deps.out(`Printed ${printed} message(s).`);\n  return { command: \"peek\", printed };\n}\n\nasync function runReplay(\n  cmd: ReplayCommand,\n  client: DlqCliClient,\n  deps: RunDeps,\n): Promise<RunResult> {\n  const options: DlqReplayOptions = {\n    dryRun: cmd.dryRun,\n    fromBeginning: cmd.fromBeginning,\n  };\n  if (cmd.target !== undefined) options.targetTopic = cmd.target;\n\n  const mode = cmd.fromBeginning ? \"full\" : \"incremental\";\n  const targetDesc = cmd.target ? ` → ${cmd.target}` : \" → original topic\";\n  deps.out(\n    `Replaying ${cmd.topic}${DLQ_SUFFIX}${targetDesc} (${mode}${\n      cmd.dryRun ? \", dry-run\" : \"\"\n    })…`,\n  );\n\n  const { replayed, skipped } = await client.replayDlq(cmd.topic, options);\n\n  deps.out(\n    cmd.dryRun\n      ? `Dry-run: ${replayed} message(s) would be replayed, ${skipped} skipped.`\n      : `Replayed ${replayed} message(s), ${skipped} skipped.`,\n  );\n  return { command: \"replay\", replayed, skipped, dryRun: cmd.dryRun };\n}\n","#!/usr/bin/env node\nimport { KafkaClient } from \"../core\";\nimport type { EventEnvelope } from \"../core\";\nimport { ConfluentTransport } from \"../client/transport/confluent.transport\";\nimport type { KafkaTransport } from \"../client/transport/transport.interface\";\nimport {\n  DlqUsageError,\n  USAGE,\n  parseArgs,\n  runDlqCommand,\n  type DlqCliClient,\n  type PartitionWatermarks,\n} from \"./dlq\";\n\n/** Unique-per-process client id so concurrent invocations don't collide. */\nconst CLIENT_ID = `dlq-cli-${process.pid}`;\nconst GROUP_ID = `${CLIENT_ID}-peek`;\n\n/**\n * Production `DlqCliClient` factory. Shares a single `ConfluentTransport`\n * between the `KafkaClient` (for `replayDlq` / `consume`) and a standalone\n * admin (for topic listing and per-partition watermarks used by `ls`).\n */\nfunction createRealClient(brokers: string[]): DlqCliClient {\n  const transport: KafkaTransport = new ConfluentTransport(CLIENT_ID, brokers);\n  const kafka = new KafkaClient<Record<string, Record<string, unknown>>>(\n    CLIENT_ID,\n    GROUP_ID,\n    brokers,\n    { transport, autoCreateTopics: false, strictSchemas: false },\n  );\n  const admin = transport.admin();\n  let adminConnected = false;\n\n  async function ensureAdmin() {\n    if (!adminConnected) {\n      await admin.connect();\n      adminConnected = true;\n    }\n  }\n\n  return {\n    async listTopics(): Promise<string[]> {\n      const status = await kafka.checkStatus();\n      if (status.status === \"down\") {\n        throw new Error(`Broker unreachable: ${status.error}`);\n      }\n      return status.topics;\n    },\n\n    async fetchTopicOffsets(topic: string): Promise<PartitionWatermarks[]> {\n      await ensureAdmin();\n      return admin.fetchTopicOffsets(topic);\n    },\n\n    async peekMessages(\n      dlqTopic: string,\n      limit: number,\n    ): Promise<Array<EventEnvelope<unknown>>> {\n      const collected: Array<EventEnvelope<unknown>> = [];\n      // Ephemeral group so peeking never disturbs a real consumer's offsets.\n      const iterator = kafka.consume(dlqTopic as never, {\n        groupId: `${dlqTopic}.dlq-peek-${Date.now()}`,\n        fromBeginning: true,\n      });\n      // Guard against an empty topic hanging the iterator forever: if the topic\n      // has no messages, stop once the high watermark says there's nothing to read.\n      await ensureAdmin();\n      const watermarks = await admin.fetchTopicOffsets(dlqTopic);\n      const available = watermarks.reduce(\n        (sum, w) => sum + Math.max(0, Number(w.high) - Number(w.low)),\n        0,\n      );\n      const target = Math.min(limit, available);\n      if (target === 0) {\n        await iterator.return?.();\n        return collected;\n      }\n      try {\n        for await (const env of iterator) {\n          collected.push(env as EventEnvelope<unknown>);\n          if (collected.length >= target) break;\n        }\n      } finally {\n        await iterator.return?.();\n      }\n      return collected;\n    },\n\n    replayDlq(topic, options) {\n      return kafka.replayDlq(topic, options);\n    },\n\n    async close(): Promise<void> {\n      if (adminConnected) {\n        await admin.disconnect().catch(() => {});\n      }\n      await kafka.disconnect().catch(() => {});\n    },\n  };\n}\n\nasync function main(): Promise<number> {\n  let cmd;\n  try {\n    cmd = parseArgs(process.argv.slice(2));\n  } catch (err) {\n    if (err instanceof DlqUsageError) {\n      process.stderr.write(`Error: ${err.message}\\n\\n`);\n      process.stderr.write(USAGE);\n      return 2;\n    }\n    throw err;\n  }\n\n  try {\n    await runDlqCommand(cmd, {\n      createClient: createRealClient,\n      out: (line) => process.stdout.write(`${line}\\n`),\n    });\n    return 0;\n  } catch (err) {\n    const message = err instanceof Error ? err.message : String(err);\n    process.stderr.write(`Error: ${message}\\n`);\n    return 1;\n  }\n}\n\nmain()\n  .then((code) => {\n    process.exitCode = code;\n  })\n  .catch((err) => {\n    process.stderr.write(`Fatal: ${err?.stack ?? err}\\n`);\n    process.exitCode = 1;\n  });\n"],"mappings":"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","names":[]}

package/dist/client/config/from-env.d.ts

@@ -0,0 +1,188 @@
+import type { TTopicMessageMap } from "../types/common";
+import type { KafkaClientOptions } from "../types/config.types";
+import type { ConsumerOptions } from "../types/consumer.types";
+/**
+ * Structured result of {@link kafkaClientConfigFromEnv}.
+ *
+ * The three positional `KafkaClient` constructor arguments (`clientId`,
+ * `groupId`, `brokers`) are surfaced separately from {@link options} so callers
+ * can supply their own fallbacks with `??`:
+ *
+ * ```ts
+ * const { clientId, groupId, brokers, options } = kafkaClientConfigFromEnv();
+ * const kafka = new KafkaClient(
+ *   clientId ?? 'my-svc',
+ *   groupId ?? 'my-grp',
+ *   brokers ?? ['localhost:9092'],
+ *   options,
+ * );
+ * ```
+ *
+ * Any of `clientId`, `groupId`, or `brokers` is `undefined` when its variable is
+ * unset, so the caller's fallback (not an empty string / empty array) is used.
+ * {@link options} only carries the keys whose variables were present — unset
+ * variables never appear, so library defaults and any code-level values you spread
+ * afterwards remain untouched.
+ */
+export interface EnvClientConfig {
+    /** `KAFKA_CLIENT_ID` — first `KafkaClient` constructor argument. */
+    clientId?: string;
+    /** `KAFKA_GROUP_ID` — second `KafkaClient` constructor argument. */
+    groupId?: string;
+    /** `KAFKA_BROKERS` (comma-separated) — third `KafkaClient` constructor argument. */
+    brokers?: string[];
+    /** Partial {@link KafkaClientOptions} — only keys whose env vars were present. */
+    options: KafkaClientOptions;
+}
+/**
+ * Build partial `KafkaClient` constructor arguments from environment variables.
+ *
+ * **Precedence — read this carefully.** These helpers only *feed* the constructor
+ * arguments; they never override anything. The effective precedence is:
+ *
+ * > **explicit code options > env vars > built-in library defaults**
+ *
+ * Env vars fill in what the developer did not hard-code; anything you spread
+ * *after* `...options` wins over the env value, and any key absent from the
+ * environment leaves the library default in place. The library never reads a
+ * `.env` file itself — load one with `node --env-file=.env` (Node 20.6+) or the
+ * `dotenv` package **before** constructing the client.
+ *
+ * ### Supported variables (default prefix `KAFKA_`)
+ *
+ * | Variable | Type | Maps to |
+ * |---|---|---|
+ * | `CLIENT_ID` | string | `clientId` (arg) |
+ * | `GROUP_ID` | string | `groupId` (arg) |
+ * | `BROKERS` | list | `brokers` (arg) |
+ * | `AUTO_CREATE_TOPICS` | boolean | `autoCreateTopics` |
+ * | `STRICT_SCHEMAS` | boolean | `strictSchemas` |
+ * | `NUM_PARTITIONS` | number | `numPartitions` |
+ * | `TRANSACTIONAL_ID` | string | `transactionalId` |
+ * | `CLOCK_RECOVERY_TOPICS` | list | `clockRecovery.topics` |
+ * | `CLOCK_RECOVERY_TIMEOUT_MS` | number | `clockRecovery.timeoutMs` |
+ * | `LAG_THROTTLE_MAX_LAG` | number | `lagThrottle.maxLag` (enables the block) |
+ * | `LAG_THROTTLE_GROUP_ID` | string | `lagThrottle.groupId` |
+ * | `LAG_THROTTLE_POLL_INTERVAL_MS` | number | `lagThrottle.pollIntervalMs` |
+ * | `LAG_THROTTLE_MAX_WAIT_MS` | number | `lagThrottle.maxWaitMs` |
+ * | `SSL` | boolean | `security.ssl` |
+ * | `SASL_MECHANISM` | `plain`\|`scram-sha-256`\|`scram-sha-512` | `security.sasl.mechanism` |
+ * | `SASL_USERNAME` | string | `security.sasl.username` |
+ * | `SASL_PASSWORD` | string | `security.sasl.password` |
+ * | `ALLOW_INSECURE` | boolean | `security.allowInsecure` |
+ *
+ * `lagThrottle` is only present when `LAG_THROTTLE_MAX_LAG` is set (it is the
+ * only required field). `clockRecovery` is only present when
+ * `CLOCK_RECOVERY_TOPICS` is set. `security` is only present when at least one of
+ * its variables is set.
+ *
+ * **`oauthbearer` cannot come from env.** Token providers
+ * (`awsMskIamProvider`, `gcpAccessTokenProvider`, custom async factories) are
+ * functions — configure them in code, not via environment variables. Only the
+ * username/password SASL mechanisms are env-configurable.
+ *
+ * @param env    Environment source. Defaults to `process.env`. Pass an explicit
+ *               object in tests to avoid mutating the real environment.
+ * @param prefix Variable prefix. Defaults to `"KAFKA_"`.
+ *
+ * @throws {Error} when a boolean/number/enum value is malformed (the message
+ *                 names the offending variable).
+ *
+ * @example Basic usage with fallbacks — code always wins / extends
+ * ```ts
+ * import { KafkaClient } from '@drarzter/kafka-client/core';
+ * import { kafkaClientConfigFromEnv } from '@drarzter/kafka-client/core';
+ *
+ * const { clientId, groupId, brokers, options } = kafkaClientConfigFromEnv();
+ * const kafka = new KafkaClient(
+ *   clientId ?? 'my-svc',
+ *   groupId ?? 'my-grp',
+ *   brokers ?? ['localhost:9092'],
+ *   {
+ *     ...options,
+ *     onMessageLost: alerting, // code-level value: not env-configurable, always applied
+ *   },
+ * );
+ * ```
+ */
+export declare function kafkaClientConfigFromEnv(env?: NodeJS.ProcessEnv, prefix?: string): EnvClientConfig;
+/**
+ * Build a partial {@link ConsumerOptions} from environment variables.
+ *
+ * Intended as a base layer of defaults that you merge with code-level per-consumer
+ * options via {@link mergeConsumerOptions}. As with {@link kafkaClientConfigFromEnv},
+ * unset variables emit no key, and env values never override code — merge order
+ * decides precedence.
+ *
+ * ### Supported variables (default prefix `KAFKA_CONSUMER_`)
+ *
+ * | Variable | Type | Maps to |
+ * |---|---|---|
+ * | `GROUP_ID` | string | `groupId` |
+ * | `FROM_BEGINNING` | boolean | `fromBeginning` |
+ * | `AUTO_COMMIT` | boolean | `autoCommit` |
+ * | `DLQ` | boolean | `dlq` |
+ * | `RETRY_MAX_RETRIES` | number | `retry.maxRetries` (enables `retry`) |
+ * | `RETRY_BACKOFF_MS` | number | `retry.backoffMs` |
+ * | `RETRY_MAX_BACKOFF_MS` | number | `retry.maxBackoffMs` |
+ * | `RETRY_TOPICS` | boolean | `retryTopics` |
+ * | `RETRY_TOPIC_ASSIGNMENT_TIMEOUT_MS` | number | `retryTopicAssignmentTimeoutMs` |
+ * | `HANDLER_TIMEOUT_MS` | number | `handlerTimeoutMs` |
+ * | `MESSAGE_TTL_MS` | number | `messageTtlMs` |
+ * | `DEDUPLICATION_STRATEGY` | `drop`\|`dlq`\|`topic` | `deduplication.strategy` (enables `deduplication`) |
+ * | `DEDUPLICATION_TOPIC` | string | `deduplication.duplicatesTopic` |
+ * | `CIRCUIT_BREAKER_THRESHOLD` | number | `circuitBreaker.threshold` (enables `circuitBreaker`) |
+ * | `CIRCUIT_BREAKER_RECOVERY_MS` | number | `circuitBreaker.recoveryMs` |
+ * | `CIRCUIT_BREAKER_WINDOW_SIZE` | number | `circuitBreaker.windowSize` |
+ * | `CIRCUIT_BREAKER_HALF_OPEN_SUCCESSES` | number | `circuitBreaker.halfOpenSuccesses` |
+ * | `QUEUE_HIGH_WATER_MARK` | number | `queueHighWaterMark` |
+ * | `PARTITION_ASSIGNER` | `roundrobin`\|`range`\|`cooperative-sticky` | `partitionAssigner` |
+ * | `GROUP_INSTANCE_ID` | string | `groupInstanceId` |
+ * | `SUBSCRIBE_RETRY_RETRIES` | number | `subscribeRetry.retries` (enables `subscribeRetry`) |
+ * | `SUBSCRIBE_RETRY_DELAY_MS` | number | `subscribeRetry.backoffMs` |
+ *
+ * `retry` is only present when `RETRY_MAX_RETRIES` is set (it is the only required
+ * field). `circuitBreaker` is only present when `CIRCUIT_BREAKER_THRESHOLD` is set.
+ * `deduplication` is only present when `DEDUPLICATION_STRATEGY` is set.
+ * `subscribeRetry` is only present when `SUBSCRIBE_RETRY_RETRIES` is set.
+ *
+ * @param env    Environment source. Defaults to `process.env`.
+ * @param prefix Variable prefix. Defaults to `"KAFKA_CONSUMER_"`.
+ *
+ * @throws {Error} when a boolean/number/enum value is malformed.
+ *
+ * @example
+ * ```ts
+ * const envDefaults = consumerOptionsFromEnv();
+ * await kafka.startConsumer(
+ *   ['orders'],
+ *   handler,
+ *   mergeConsumerOptions(envDefaults, { dlq: true }), // code layer wins
+ * );
+ * ```
+ */
+export declare function consumerOptionsFromEnv<T extends TTopicMessageMap = TTopicMessageMap>(env?: NodeJS.ProcessEnv, prefix?: string): Partial<ConsumerOptions<T>>;
+/**
+ * Merge several partial {@link ConsumerOptions} layers into one, **later layers
+ * winning** on conflict. This is the mechanism that implements the
+ * *code > env > defaults* precedence rule — pass the env layer first and the
+ * code layer last.
+ *
+ * Top-level keys are replaced by the last defined value. The nested option
+ * objects — `retry`, `deduplication`, `circuitBreaker`, and `subscribeRetry` —
+ * are **deep-merged** so a later layer can override a single nested field (e.g.
+ * bump `retry.maxRetries`) without discarding the other fields set by an earlier
+ * layer. `undefined` values never overwrite a previously set value, and
+ * `undefined` layers are skipped entirely.
+ *
+ * @example Env base overridden by code
+ * ```ts
+ * const env  = { retry: { maxRetries: 3, backoffMs: 500 }, dlq: false };
+ * const code = { retry: { maxRetries: 5 }, dlq: true };
+ * mergeConsumerOptions(env, code);
+ * // → { retry: { maxRetries: 5, backoffMs: 500 }, dlq: true }
+ * //   maxRetries overridden, backoffMs preserved, dlq overridden
+ * ```
+ */
+export declare function mergeConsumerOptions<T extends TTopicMessageMap = TTopicMessageMap>(...layers: Array<Partial<ConsumerOptions<T>> | undefined>): ConsumerOptions<T>;
+//# sourceMappingURL=from-env.d.ts.map

package/dist/client/config/from-env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"from-env.d.ts","sourceRoot":"","sources":["../../../src/client/config/from-env.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACxD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAChE,OAAO,KAAK,EACV,eAAe,EAKhB,MAAM,yBAAyB,CAAC;AAMjC;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,WAAW,eAAe;IAC9B,oEAAoE;IACpE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,oEAAoE;IACpE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,oFAAoF;IACpF,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,kFAAkF;IAClF,OAAO,EAAE,kBAAkB,CAAC;CAC7B;AAmFD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsEG;AACH,wBAAgB,wBAAwB,CACtC,GAAG,GAAE,MAAM,CAAC,UAAwB,EACpC,MAAM,SAAW,GAChB,eAAe,CAsEjB;AA+ED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AACH,wBAAgB,sBAAsB,CACpC,CAAC,SAAS,gBAAgB,GAAG,gBAAgB,EAE7C,GAAG,GAAE,MAAM,CAAC,UAAwB,EACpC,MAAM,SAAoB,GACzB,OAAO,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,CAiI7B;AAoBD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,oBAAoB,CAClC,CAAC,SAAS,gBAAgB,GAAG,gBAAgB,EAE7C,GAAG,MAAM,EAAE,KAAK,CAAC,OAAO,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC,GACxD,eAAe,CAAC,CAAC,CAAC,CAwBpB"}

package/dist/client/config/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./from-env";
+//# sourceMappingURL=index.d.ts.map

package/dist/client/config/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/client/config/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC"}