@drarzter/kafka-client 0.9.3 → 0.10.0

package/dist/cli/dlq.d.ts

@@ -0,0 +1,119 @@
+import type { EventEnvelope } from "../core";
+import type { DlqReplayOptions } from "../core";
+/** DLQ topic suffix — the CLI operates on `<topic>.dlq`. */
+export declare const DLQ_SUFFIX = ".dlq";
+/** `ls` — list DLQ topics with message counts. */
+export interface LsCommand {
+    command: "ls";
+    brokers: string[];
+    /** Optional topic-name prefix filter (matched against the base topic). */
+    prefix?: string;
+}
+/** `peek` — print the first N messages of `<topic>.dlq`. */
+export interface PeekCommand {
+    command: "peek";
+    brokers: string[];
+    /** Base topic name — the CLI reads from `<topic>.dlq`. */
+    topic: string;
+    /** Maximum number of messages to print. Default: 10. */
+    limit: number;
+}
+/** `replay` — re-publish `<topic>.dlq` messages via `KafkaClient.replayDlq`. */
+export interface ReplayCommand {
+    command: "replay";
+    brokers: string[];
+    /** Base topic name — the CLI replays `<topic>.dlq`. */
+    topic: string;
+    /** Override destination topic (default: read from `x-dlq-original-topic`). */
+    target?: string;
+    /** Log what would be replayed without publishing. */
+    dryRun: boolean;
+    /**
+     * `true`  → full replay of all DLQ messages on every call (ephemeral group).
+     * `false` → incremental — only messages since the previous replay (stable group).
+     */
+    fromBeginning: boolean;
+}
+/** `help` — print usage. */
+export interface HelpCommand {
+    command: "help";
+}
+/** Discriminated union of every parsed CLI invocation. */
+export type ParsedCommand = LsCommand | PeekCommand | ReplayCommand | HelpCommand;
+/** Thrown by `parseArgs` when the argv is invalid. Carries the usage text. */
+export declare class DlqUsageError extends Error {
+    constructor(message: string);
+}
+export declare const USAGE = "kafka-client-dlq \u2014 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";
+/**
+ * Parse the process argv (already sliced past `node <script>`) into a
+ * `ParsedCommand`. Pure and synchronous — no I/O — so it is fully unit-testable.
+ *
+ * @throws {DlqUsageError} on unknown commands, missing/invalid flags.
+ */
+export declare function parseArgs(argv: string[]): ParsedCommand;
+/** Per-partition low/high watermarks for a topic. */
+export interface PartitionWatermarks {
+    partition: number;
+    low: string;
+    high: string;
+}
+/**
+ * Minimal client surface the CLI needs. The production factory backs this with
+ * a real `KafkaClient` plus its transport admin; tests inject a fake.
+ */
+export interface DlqCliClient {
+    /** List all topics visible to the broker (via `checkStatus`). */
+    listTopics(): Promise<string[]>;
+    /** Per-partition low/high watermarks for a single topic. */
+    fetchTopicOffsets(topic: string): Promise<PartitionWatermarks[]>;
+    /** Read up to `limit` messages from `dlqTopic`, from the earliest offset. */
+    peekMessages(dlqTopic: string, limit: number): Promise<Array<EventEnvelope<unknown>>>;
+    /** Delegate to `KafkaClient.replayDlq`. */
+    replayDlq(topic: string, options: DlqReplayOptions): Promise<{
+        replayed: number;
+        skipped: number;
+    }>;
+    /** Release all connections. */
+    close(): Promise<void>;
+}
+/** Injected dependencies for `runDlqCommand`. */
+export interface RunDeps {
+    /** Build a connected client for the given brokers. */
+    createClient(brokers: string[]): DlqCliClient | Promise<DlqCliClient>;
+    /** Sink for human-readable output. Defaults are wired by the bin entrypoint. */
+    out: (line: string) => void;
+}
+export interface DlqTopicCount {
+    /** The `<name>.dlq` topic. */
+    dlqTopic: string;
+    /** The base topic (`dlqTopic` without the `.dlq` suffix). */
+    baseTopic: string;
+    /** Sum over partitions of (high − low). */
+    count: number;
+}
+export type RunResult = {
+    command: "ls";
+    topics: DlqTopicCount[];
+} | {
+    command: "peek";
+    printed: number;
+} | {
+    command: "replay";
+    replayed: number;
+    skipped: number;
+    dryRun: boolean;
+} | {
+    command: "help";
+};
+/** Sum (high − low) across a topic's partitions. Negative widths clamp to 0. */
+export declare function countFromWatermarks(watermarks: PartitionWatermarks[]): number;
+/** Truncate a value for display, appending an ellipsis marker when cut. */
+export declare function truncate(value: string, max?: number): string;
+/**
+ * Execute a parsed command against injected deps.
+ * Returns a structured result; all human-readable output goes through `deps.out`.
+ * The client is always closed in a `finally` block.
+ */
+export declare function runDlqCommand(cmd: ParsedCommand, deps: RunDeps): Promise<RunResult>;
+//# sourceMappingURL=dlq.d.ts.map

package/dist/cli/dlq.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dlq.d.ts","sourceRoot":"","sources":["../../src/cli/dlq.ts"],"names":[],"mappings":"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"}

package/dist/cli/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/cli/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":""}