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

package/dist-es/index.js

@@ -0,0 +1,3 @@
+export { SQSPoller } from "./SQSPoller";
+export { Message } from "./Message";
+export { PollerError, DeleteError, TimeoutError, VisibilityExtensionError } from "./errors";

package/dist-es/types.js

@@ -0,0 +1 @@
+export {};

package/dist-types/Message.d.ts

@@ -0,0 +1,52 @@
+import type { Message as SQSMessage, MessageAttributeValue, MessageSystemAttributeName } from "@aws-sdk/client-sqs";
+import type { PollerMessage } from "./types";
+/**
+ * Callbacks the poller injects so Message can perform SQS operations
+ * without holding a reference to the client.
+ * @internal
+ */
+export interface MessageCallbacks {
+    enqueueDelete: (msg: Message) => void;
+    keep: (receiptHandle: string) => void;
+    release: (receiptHandle: string) => Promise<void>;
+    changeVisibility: (receiptHandle: string, timeoutMs: number) => Promise<void>;
+}
+/**
+ * Wrapper around an SQS `Message` with convenience methods.
+ *
+ * Instances are created internally by {@link SQSPoller}. Consumers
+ * should not instantiate this class directly.
+ *
+ * @public
+ */
+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;
+    /**
+     * @internal
+     */
+    constructor(raw: SQSMessage, callbacks: MessageCallbacks);
+    /**
+     * Whether `enqueueDelete`, `keep`, or `release` has already run.
+     * @internal
+     */
+    get handled(): boolean;
+    /** Queue this message for batch deletion. */
+    enqueueDelete(): void;
+    /** Acknowledge the message without deleting it from the queue. */
+    keep(): void;
+    /** Release the message back to the queue immediately (visibility → 0). */
+    release(): Promise<void>;
+    /**
+     * Change the visibility timeout of this message. Stops automatic extension for it.
+     * @param timeoutMs - New visibility timeout, rounded up to whole seconds for SQS.
+     */
+    changeVisibility(timeoutMs: number): Promise<void>;
+}

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>;
+}