@aws-sdk/lib-sqs 0.0.0-stage → 3.1158.0

package/dist-types/SQSPoller.d.ts

@@ -0,0 +1,92 @@
+import type { PollerConfig, PollerStats, SerializablePollerStats, SQSPollerEvents, SQSPollerEventName, PollerMessage } from "./types";
+/**
+ * Managed long-polling loop for SQS queues with auto-delete, backoff,
+ * visibility heartbeat, and graceful shutdown.
+ *
+ * Two consumption models (mutually exclusive):
+ * 1. Event-based: `poller.on("message", handler); poller.start();`
+ * 2. Async iteration: `for await (const msg of poller) { ... }`
+ *
+ * In async iteration, each message is auto-deleted when the loop advances. Exiting
+ * early (`break`, `return`, or a throw) leaves the current message undeleted; call
+ * `msg.enqueueDelete()` first if it was processed.
+ *
+ * @public
+ */
+export declare class SQSPoller implements AsyncIterable<PollerMessage> {
+    private readonly _client;
+    private readonly _config;
+    private readonly _stats;
+    private _run;
+    private readonly _externalSignal?;
+    private _deleteBatch;
+    private _deleteTimer;
+    private _pendingFlushes;
+    private readonly _heartbeatTimers;
+    private readonly _heartbeatsInFlight;
+    private readonly _listeners;
+    constructor(config: PollerConfig);
+    get running(): boolean;
+    get inFlight(): number;
+    getStats(): Readonly<PollerStats>;
+    toJSON(): SerializablePollerStats;
+    toString(): string;
+    /** Register a listener. Returns a function that removes it. */
+    on<K extends SQSPollerEventName>(event: K, listener: SQSPollerEvents[K]): () => void;
+    /** Remove a listener, or all listeners for an event if `listener` is omitted. */
+    off<K extends SQSPollerEventName>(event: K, listener?: SQSPollerEvents[K]): this;
+    /** Start polling. Non-blocking. */
+    start(): void;
+    /**
+     * Stop polling, and resolve once this run has shut down.
+     *
+     * @param graceful - When `true`, waits up to `shutdownTimeoutMs` for in-flight work (handlers
+     *   in event mode, or the current loop body in async iteration), then flushes pending deletes.
+     *   When `false`, stops without waiting; calling it during a graceful shutdown cuts that short.
+     *   Don't `await` this from inside a `message` handler or a `for await` body, since shutdown
+     *   waits for that work to finish. Use `void poller.stop()`, or `break`, instead.
+     * @returns The final stats. Does nothing if the poller isn't running.
+     */
+    stop(graceful?: boolean): Promise<PollerStats>;
+    /**
+     * Exiting the loop early (`break`, `return`, or a throw) does not auto-delete the
+     * current message, since the three are indistinguishable here. Call
+     * `msg.enqueueDelete()` before exiting if the message was processed.
+     */
+    [Symbol.asyncIterator](): AsyncGenerator<PollerMessage, void, undefined>;
+    private _iterate;
+    private _assertCanStart;
+    /** A run started while the previous one is still shutting down waits for it to finish. */
+    private _beginRun;
+    private _teardown;
+    /** Resolves with how `work` ended: finished, timed out after shutdownTimeoutMs, or cut short by stop(false). */
+    private _waitFor;
+    private _waitForDrain;
+    private _emitShutdownTimeout;
+    private _pollLoop;
+    private _processMessage;
+    /** Returns false if `beforeRequest` threw or rejected, which stops the run. */
+    private _runBeforeRequest;
+    /** Returns true if the idle timeout was reached, which stops the run. */
+    private _handleEmpty;
+    private _handlePollError;
+    private _recordReceived;
+    private _receiveMessages;
+    private _enqueueDelete;
+    private _flushDeleteBatch;
+    private _trackFlush;
+    private _awaitPendingFlushes;
+    private _startHeartbeat;
+    /** Resolves once any extension request already in flight for this message settles. */
+    private _stopHeartbeat;
+    /** Stops this run's heartbeats only, and waits out their in-flight extensions so none land after `stopped`. */
+    private _stopHeartbeats;
+    private _wrapMessage;
+    private _isAborted;
+    private _checkIdleTimeout;
+    private _effectiveIdlePollInterval;
+    private _backoff;
+    private _delay;
+    private _emit;
+    private _emitAsync;
+}

package/dist-types/errors.d.ts

@@ -0,0 +1,45 @@
+import type { BatchResultErrorEntry } from "@aws-sdk/client-sqs";
+/**
+ * Base error class for all poller errors.
+ * @public
+ */
+export declare class PollerError extends Error {
+    readonly name: string;
+    constructor(message: string, options?: {
+        cause?: Error;
+    });
+}
+/**
+ * Thrown when a poller operation exceeds its time limit.
+ * @public
+ */
+export declare class TimeoutError extends PollerError {
+    readonly name: string;
+    readonly timeoutMs: number;
+    constructor(message: string, timeoutMs: number, options?: {
+        cause?: Error;
+    });
+}
+/**
+ * Thrown when `DeleteMessageBatch` reports failures.
+ * @public
+ */
+export declare class DeleteError extends PollerError {
+    readonly name: string;
+    readonly failures: BatchResultErrorEntry[];
+    readonly messageIds: string[];
+    constructor(message: string, failures: BatchResultErrorEntry[], messageIds?: string[], options?: {
+        cause?: Error;
+    });
+}
+/**
+ * Thrown when extending a message's visibility timeout fails.
+ * @public
+ */
+export declare class VisibilityExtensionError extends PollerError {
+    readonly name: string;
+    readonly messageId: string;
+    constructor(message: string, messageId: string, options?: {
+        cause?: Error;
+    });
+}

package/dist-types/index.d.ts

@@ -0,0 +1,28 @@
+/**
+ * SQS message poller with auto-delete, backoff, and graceful shutdown.
+ *
+ * @example Event-based
+ * ```typescript
+ * const poller = new SQSPoller({ queueUrl: "https://sqs.us-east-1.amazonaws.com/1/q" });
+ * const unsub = poller.on("message", async (msg) => console.log(msg.body));
+ * poller.on("error", (err) => console.error(err));
+ * poller.start();
+ * ```
+ *
+ * @example Async iteration
+ * ```typescript
+ * for await (const msg of poller) {
+ *   console.log(msg.body);
+ *   if (msg.body === "last") {
+ *     msg.enqueueDelete(); // exiting early skips auto-delete for this message
+ *     break;
+ *   }
+ * }
+ * ```
+ *
+ * @packageDocumentation
+ */
+export { SQSPoller } from "./SQSPoller";
+export { Message } from "./Message";
+export { PollerError, DeleteError, TimeoutError, VisibilityExtensionError } from "./errors";
+export type { PollerConfig, PollerStats, SerializablePollerStats, SQSPollerEvents, SQSPollerEventName, PollerMessage, } from "./types";

package/dist-types/ts3.4/Message.d.ts

@@ -0,0 +1,29 @@
+import {
+  Message as SQSMessage,
+  MessageAttributeValue,
+  MessageSystemAttributeName,
+} from "@aws-sdk/client-sqs";
+import { PollerMessage } from "./types";
+export interface MessageCallbacks {
+  enqueueDelete: (msg: Message) => void;
+  keep: (receiptHandle: string) => void;
+  release: (receiptHandle: string) => Promise<void>;
+  changeVisibility: (receiptHandle: string, timeoutMs: number) => Promise<void>;
+}
+export declare class Message implements PollerMessage {
+  readonly raw: SQSMessage;
+  readonly body: string | undefined;
+  readonly messageId: string;
+  readonly receiptHandle: string;
+  readonly attributes: Partial<Record<MessageSystemAttributeName, string>>;
+  readonly messageAttributes: Record<string, MessageAttributeValue>;
+  readonly receivedAt: Date;
+  private readonly _callbacks;
+  private _handled;
+  constructor(raw: SQSMessage, callbacks: MessageCallbacks);
+  readonly handled: boolean;
+  enqueueDelete(): void;
+  keep(): void;
+  release(): Promise<void>;
+  changeVisibility(timeoutMs: number): Promise<void>;
+}

package/dist-types/ts3.4/SQSPoller.d.ts

@@ -0,0 +1,61 @@
+import {
+  PollerConfig,
+  PollerStats,
+  SerializablePollerStats,
+  SQSPollerEvents,
+  SQSPollerEventName,
+  PollerMessage,
+} from "./types";
+export declare class SQSPoller implements AsyncIterable<PollerMessage> {
+  private readonly _client;
+  private readonly _config;
+  private readonly _stats;
+  private _run;
+  private readonly _externalSignal?;
+  private _deleteBatch;
+  private _deleteTimer;
+  private _pendingFlushes;
+  private readonly _heartbeatTimers;
+  private readonly _heartbeatsInFlight;
+  private readonly _listeners;
+  constructor(config: PollerConfig);
+  readonly running: boolean;
+  readonly inFlight: number;
+  getStats(): Readonly<PollerStats>;
+  toJSON(): SerializablePollerStats;
+  toString(): string;
+  on<K extends SQSPollerEventName>(event: K, listener: SQSPollerEvents[K]): () => void;
+  off<K extends SQSPollerEventName>(event: K, listener?: SQSPollerEvents[K]): this;
+  start(): void;
+  stop(graceful?: boolean): Promise<PollerStats>;
+  [Symbol.asyncIterator](): AsyncGenerator<PollerMessage, void, undefined>;
+  private _iterate;
+  private _assertCanStart;
+  private _beginRun;
+  private _teardown;
+  private _waitFor;
+  private _waitForDrain;
+  private _emitShutdownTimeout;
+  private _pollLoop;
+  private _processMessage;
+  private _runBeforeRequest;
+  private _handleEmpty;
+  private _handlePollError;
+  private _recordReceived;
+  private _receiveMessages;
+  private _enqueueDelete;
+  private _flushDeleteBatch;
+  private _trackFlush;
+  private _awaitPendingFlushes;
+  private _startHeartbeat;
+  private _stopHeartbeat;
+  private _stopHeartbeats;
+  private _wrapMessage;
+  private _isAborted;
+  private _checkIdleTimeout;
+  private _effectiveIdlePollInterval;
+  private _backoff;
+  private _delay;
+  private _emit;
+  private _emitAsync;
+}

package/dist-types/ts3.4/errors.d.ts

@@ -0,0 +1,45 @@
+import { BatchResultErrorEntry } from "@aws-sdk/client-sqs";
+export declare class PollerError extends Error {
+  readonly name: string;
+  constructor(
+    message: string,
+    options?: {
+      cause?: Error;
+    },
+  );
+}
+export declare class TimeoutError extends PollerError {
+  readonly name: string;
+  readonly timeoutMs: number;
+  constructor(
+    message: string,
+    timeoutMs: number,
+    options?: {
+      cause?: Error;
+    },
+  );
+}
+export declare class DeleteError extends PollerError {
+  readonly name: string;
+  readonly failures: BatchResultErrorEntry[];
+  readonly messageIds: string[];
+  constructor(
+    message: string,
+    failures: BatchResultErrorEntry[],
+    messageIds?: string[],
+    options?: {
+      cause?: Error;
+    },
+  );
+}
+export declare class VisibilityExtensionError extends PollerError {
+  readonly name: string;
+  readonly messageId: string;
+  constructor(
+    message: string,
+    messageId: string,
+    options?: {
+      cause?: Error;
+    },
+  );
+}

package/dist-types/ts3.4/index.d.ts

@@ -0,0 +1,11 @@
+export { SQSPoller } from "./SQSPoller";
+export { Message } from "./Message";
+export { PollerError, DeleteError, TimeoutError, VisibilityExtensionError } from "./errors";
+export {
+  PollerConfig,
+  PollerStats,
+  SerializablePollerStats,
+  SQSPollerEvents,
+  SQSPollerEventName,
+  PollerMessage,
+} from "./types";

package/dist-types/ts3.4/types.d.ts

@@ -0,0 +1,83 @@
+import {
+  SQSClient,
+  SQSClientConfig,
+  Message as SQSMessage,
+  MessageAttributeValue,
+  MessageSystemAttributeName,
+  BatchResultErrorEntry,
+} from "@aws-sdk/client-sqs";
+export {
+  SQSClient,
+  SQSClientConfig,
+  SQSMessage,
+  MessageAttributeValue,
+  MessageSystemAttributeName,
+  BatchResultErrorEntry,
+};
+export interface PollerConfig {
+  queueUrl: string;
+  client?: SQSClient;
+  clientConfig?: SQSClientConfig;
+  receiveWaitTimeMs?: number;
+  receiveBatchSize?: number;
+  activePollIntervalMs?: number;
+  idlePollIntervalMs?: number;
+  idleTimeoutMs?: number;
+  maxConcurrency?: number;
+  visibilityTimeoutMs?: number;
+  extendTimeout?: boolean;
+  extendTimeoutAdvanceMs?: number;
+  maxTimeoutExtensionMs?: number;
+  deleteMessages?: boolean;
+  deleteBatchSize?: number;
+  deleteWaitMs?: number;
+  systemAttributeNames?: MessageSystemAttributeName[];
+  messageAttributeNames?: string[];
+  backoffMs?: number;
+  maxBackoffMs?: number;
+  abortSignal?: AbortSignal;
+  shutdownTimeoutMs?: number;
+  beforeRequest?: (stats: PollerStats) => void | Promise<void>;
+}
+export interface PollerStats {
+  requestCount: number;
+  receivedMessageCount: number;
+  deletedMessageCount: number;
+  errorCount: number;
+  lastMessageReceivedAt: Date | null;
+  pollingStartedAt: Date | null;
+  pollingStoppedAt: Date | null;
+}
+export interface SerializablePollerStats {
+  requestCount: number;
+  receivedMessageCount: number;
+  deletedMessageCount: number;
+  errorCount: number;
+  lastMessageReceivedAt: string | null;
+  pollingStartedAt: string | null;
+  pollingStoppedAt: string | null;
+  pollingDurationMs: number;
+}
+export interface SQSPollerEvents {
+  message: (message: PollerMessage) => void | Promise<void>;
+  empty: () => void;
+  idle: () => void;
+  stopped: (stats: PollerStats) => void;
+  error: (error: Error) => void;
+  timeoutExtended: (message: PollerMessage) => void;
+  heartbeatExpired: (message: PollerMessage) => void;
+}
+export type SQSPollerEventName = keyof SQSPollerEvents;
+export interface PollerMessage {
+  readonly raw: SQSMessage;
+  readonly body: string | undefined;
+  readonly messageId: string;
+  readonly receiptHandle: string;
+  readonly attributes: Partial<Record<MessageSystemAttributeName, string>>;
+  readonly messageAttributes: Record<string, MessageAttributeValue>;
+  readonly receivedAt: Date;
+  enqueueDelete(): void;
+  keep(): void;
+  release(): Promise<void>;
+  changeVisibility(timeoutMs: number): Promise<void>;
+}

package/dist-types/types.d.ts

@@ -0,0 +1,236 @@
+/**
+ * Timing options are milliseconds with an `Ms` suffix; the poller converts to
+ * seconds when calling SQS.
+ */
+import type { SQSClient, SQSClientConfig, Message as SQSMessage, MessageAttributeValue, MessageSystemAttributeName, BatchResultErrorEntry } from "@aws-sdk/client-sqs";
+export type { SQSClient, SQSClientConfig, SQSMessage, MessageAttributeValue, MessageSystemAttributeName, BatchResultErrorEntry, };
+/**
+ * Config options for {@link SQSPoller}.
+ * @public
+ */
+export interface PollerConfig {
+    /**
+     * The URL of the SQS queue to poll.
+     * @example "https://sqs.us-east-1.amazonaws.com/123456789/my-queue"
+     */
+    queueUrl: string;
+    /**
+     * Pre-configured SQS client instance.
+     * If provided, `clientConfig` is ignored.
+     */
+    client?: SQSClient;
+    /**
+     * Config forwarded to a new `SQSClient` when `client` is not provided.
+     * Uses the standard `SQSClientConfig` from `@aws-sdk/client-sqs`.
+     */
+    clientConfig?: SQSClientConfig;
+    /**
+     * Long-poll wait time (0–20_000).
+     * Converted to whole seconds for the SQS `ReceiveMessage` API.
+     * Use 0 for short polling (not recommended).
+     * @defaultValue 20_000
+     */
+    receiveWaitTimeMs?: number;
+    /**
+     * Messages to request per `ReceiveMessage` call (1–10).
+     * @defaultValue 10
+     */
+    receiveBatchSize?: number;
+    /**
+     * Extra delay between polls when the previous poll returned messages.
+     * 0 means the next poll starts immediately.
+     * @defaultValue 0
+     */
+    activePollIntervalMs?: number;
+    /**
+     * Extra delay between polls when the previous poll returned no messages.
+     * @defaultValue 0
+     */
+    idlePollIntervalMs?: number;
+    /**
+     * Stop polling after this long without receiving a message.
+     * `undefined` polls indefinitely.
+     * @defaultValue undefined
+     */
+    idleTimeoutMs?: number;
+    /**
+     * Max messages processed concurrently.
+     * The poller pauses `ReceiveMessage` calls when this limit is reached
+     * and resumes when in-flight count drops below it.
+     * @defaultValue 10
+     */
+    maxConcurrency?: number;
+    /**
+     * Visibility timeout override, rounded up to whole seconds for SQS.
+     * When omitted, the queue's default `VisibilityTimeout` applies.
+     */
+    visibilityTimeoutMs?: number;
+    /**
+     * Auto-extend the visibility timeout while a message is being processed.
+     * The call is made `extendTimeoutAdvanceMs` before the current timeout expires.
+     * @defaultValue false
+     */
+    extendTimeout?: boolean;
+    /**
+     * How far ahead of expiry to make the extension call.
+     * Only used when `extendTimeout` is `true`.
+     * @defaultValue 5_000
+     */
+    extendTimeoutAdvanceMs?: number;
+    /**
+     * Max total time to keep extending the visibility timeout.
+     * After this the poller stops extending.
+     * Only used when `extendTimeout` is `true`.
+     * @defaultValue 43_200_000 (12 hours)
+     */
+    maxTimeoutExtensionMs?: number;
+    /**
+     * When `true` (default), messages are deleted automatically after the
+     * `message` handler resolves.  Set to `false` for manual deletion via
+     * `message.enqueueDelete()`.
+     * @defaultValue true
+     */
+    deleteMessages?: boolean;
+    /**
+     * Batch size for `DeleteMessageBatch` calls (1–10).
+     * @defaultValue 10
+     */
+    deleteBatchSize?: number;
+    /**
+     * Max wait for a delete batch to fill before flushing.
+     * Lower reduces latency; higher improves batching.
+     * @defaultValue 2_000
+     */
+    deleteWaitMs?: number;
+    /**
+     * System attribute names to request with each message.
+     * @defaultValue []
+     * @example ["All"] or ["ApproximateReceiveCount", "SentTimestamp"]
+     */
+    systemAttributeNames?: MessageSystemAttributeName[];
+    /**
+     * Custom message attribute names to request.
+     * @defaultValue []
+     * @example ["All"] or ["myAttribute.*"]
+     */
+    messageAttributeNames?: string[];
+    /**
+     * Initial backoff delay after a `ReceiveMessage` error.
+     * Doubles on consecutive errors up to `maxBackoffMs`.
+     * @defaultValue 1_000
+     */
+    backoffMs?: number;
+    /**
+     * Max backoff ceiling.
+     * @defaultValue 30_000
+     */
+    maxBackoffMs?: number;
+    /**
+     * `AbortSignal` for graceful shutdown.  When aborted the poller
+     * finishes in-flight handlers, flushes pending deletes, then stops.
+     */
+    abortSignal?: AbortSignal;
+    /**
+     * Max wait for in-flight messages to complete during shutdown.
+     * @defaultValue 30_000
+     */
+    shutdownTimeoutMs?: number;
+    /**
+     * Callback invoked before each `ReceiveMessage` call. May be async.
+     * Throwing (or rejecting) stops the polling loop and emits the error via the
+     * `error` event.  The poller will not make another request.
+     */
+    beforeRequest?: (stats: PollerStats) => void | Promise<void>;
+}
+/**
+ * Live stats tracked by the poller.
+ * @public
+ */
+export interface PollerStats {
+    /** Total `ReceiveMessage` requests sent. */
+    requestCount: number;
+    /** Total messages received. */
+    receivedMessageCount: number;
+    /** Total messages successfully deleted. */
+    deletedMessageCount: number;
+    /** Total errors encountered (receive, delete, extend). */
+    errorCount: number;
+    /** Timestamp of last received message, or `null`. */
+    lastMessageReceivedAt: Date | null;
+    /** Timestamp when `start()` was called. */
+    pollingStartedAt: Date | null;
+    /** Timestamp when the poller stopped, or `null` if still running. */
+    pollingStoppedAt: Date | null;
+}
+/**
+ * JSON-serializable snapshot of {@link PollerStats}.
+ * Dates are converted to ISO-8601 strings.
+ * @public
+ */
+export interface SerializablePollerStats {
+    requestCount: number;
+    receivedMessageCount: number;
+    deletedMessageCount: number;
+    errorCount: number;
+    lastMessageReceivedAt: string | null;
+    pollingStartedAt: string | null;
+    pollingStoppedAt: string | null;
+    pollingDurationMs: number;
+}
+/**
+ * Events emitted by {@link SQSPoller}.
+ * @public
+ */
+export interface SQSPollerEvents {
+    /** A message was received. */
+    message: (message: PollerMessage) => void | Promise<void>;
+    /** The last `ReceiveMessage` returned no messages. */
+    empty: () => void;
+    /** The poller stopped due to `idleTimeoutMs` expiring. */
+    idle: () => void;
+    /** The poller finished shutting down. Fires once per run, however it stopped. */
+    stopped: (stats: PollerStats) => void;
+    /** A non-fatal error occurred (receive, delete, extend). */
+    error: (error: Error) => void;
+    /** A message's visibility timeout was extended. */
+    timeoutExtended: (message: PollerMessage) => void;
+    /** A message's heartbeat expired after `maxTimeoutExtensionMs`. The message may become visible to other consumers. */
+    heartbeatExpired: (message: PollerMessage) => void;
+}
+/**
+ * Event name literals for {@link SQSPollerEvents}.
+ * @public
+ */
+export type SQSPollerEventName = keyof SQSPollerEvents;
+/**
+ * A received SQS message with convenience methods.
+ *
+ * This interface describes the public surface.  The concrete class
+ * is in `./Message.ts`.
+ *
+ * @public
+ */
+export interface PollerMessage {
+    /** Raw SQS `Message` object. */
+    readonly raw: SQSMessage;
+    /** Message body string. */
+    readonly body: string | undefined;
+    /** Unique message ID. */
+    readonly messageId: string;
+    /** Receipt handle for delete / visibility operations. */
+    readonly receiptHandle: string;
+    /** System attributes (e.g. `ApproximateReceiveCount`). */
+    readonly attributes: Partial<Record<MessageSystemAttributeName, string>>;
+    /** Custom message attributes. */
+    readonly messageAttributes: Record<string, MessageAttributeValue>;
+    /** Timestamp when the poller received this message. */
+    readonly receivedAt: Date;
+    /** Queue this message for batch deletion. */
+    enqueueDelete(): void;
+    /** Acknowledge the message without deleting it. */
+    keep(): void;
+    /** Release the message back to the queue immediately (visibility → 0). */
+    release(): Promise<void>;
+    /** Change the visibility timeout of this message. */
+    changeVisibility(timeoutMs: number): Promise<void>;
+}