Address review comments

Author: kibertoad

README.md

@@ -244,34 +244,36 @@ Both publishers and consumers accept a queue name and configuration as parameter
 
 If you do not want to create a new queue/topic, you can set `queueLocator` field for `queueConfiguration`. In that case `message-queue-toolkit` will not attempt to create a new queue or topic, and instead throw an error if they don't already exist.
 
-## Resource Availability Polling (Eventual Consistency Mode)
+## Startup Resource Polling (Eventual Consistency Mode)
 
 When using `locatorConfig` to reference existing queues or topics, the default behavior is to fail immediately if the resource doesn't exist. However, in some deployment scenarios (especially with cross-service dependencies), resources may not be available at startup time.
 
-The `resourceAvailabilityConfig` option enables "eventual consistency mode" where consumers poll for resources to become available instead of failing immediately.
+The `startupResourcePolling` option within `locatorConfig` enables "eventual consistency mode" where consumers poll for resources to become available instead of failing immediately.
 
 ### Use Case: Cross-Service Dependencies
 
 Consider two services that need to subscribe to each other's topics:
 - **Service A** needs to subscribe to **Service B's** topic
 - **Service B** needs to subscribe to **Service A's** topic
 
-Without eventual consistency mode, neither service can deploy first because the other's topic doesn't exist yet. With `resourceAvailabilityConfig`, both services can start simultaneously and wait for the other's resources to appear.
+Without eventual consistency mode, neither service can deploy first because the other's topic doesn't exist yet. With `startupResourcePolling`, both services can start simultaneously and wait for the other's resources to appear.
 
 ### Configuration
 
 ```typescript
+import { NO_TIMEOUT } from '@message-queue-toolkit/core'
+
 const consumer = new MySnsSqsConsumer(dependencies, {
   locatorConfig: {
     topicArn: 'arn:aws:sns:...',
     queueUrl: 'https://sqs...',
-    subscriptionArn: '...'
-  },
-  // Enable eventual consistency mode
-  resourceAvailabilityConfig: {
-    enabled: true,           // Enable polling for resource availability
-    pollingIntervalMs: 5000, // Check every 5 seconds (default: 5000)
-    timeoutMs: 300000,       // Fail after 5 minutes (optional, default: no timeout)
+    subscriptionArn: '...',
+    // Enable eventual consistency mode
+    startupResourcePolling: {
+      enabled: true,           // Enable polling for resource availability
+      pollingIntervalMs: 5000, // Check every 5 seconds (default: 5000)
+      timeoutMs: 300000,       // Fail after 5 minutes (required)
+    }
   }
 })
 ```
@@ -280,42 +282,61 @@ const consumer = new MySnsSqsConsumer(dependencies, {
 
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
-| `enabled` | `boolean` | `false` | Enable eventual consistency mode |
+| `enabled` | `boolean` | - | Must be set to `true` to enable polling |
 | `pollingIntervalMs` | `number` | `5000` | Interval between availability checks (ms) |
-| `timeoutMs` | `number` | `undefined` | Maximum wait time before throwing `ResourceAvailabilityTimeoutError`. If not set, polls indefinitely |
+| `timeoutMs` | `number \| NO_TIMEOUT` | - (required) | Maximum wait time before throwing `StartupResourcePollingTimeoutError`. Use `NO_TIMEOUT` to poll indefinitely |
 
 ### Environment-Specific Configuration
 
 ```typescript
+import { NO_TIMEOUT } from '@message-queue-toolkit/core'
+
+// Production - with timeout
+{
+  locatorConfig: {
+    queueUrl: '...',
+    startupResourcePolling: {
+      enabled: true,
+      timeoutMs: 5 * 60 * 1000, // 5 minutes
+    }
+  }
+}
+
 // Development/Staging - poll indefinitely
 {
-  resourceAvailabilityConfig: {
-    enabled: true,
-    pollingIntervalMs: 5000,
+  locatorConfig: {
+    queueUrl: '...',
+    startupResourcePolling: {
+      enabled: true,
+      timeoutMs: NO_TIMEOUT,
+    }
   }
 }
 
-// Production - poll with timeout to catch misconfigurations
+// Custom timeout and interval
 {
-  resourceAvailabilityConfig: {
-    enabled: true,
-    pollingIntervalMs: 10000,
-    timeoutMs: 5 * 60 * 1000, // 5 minutes
+  locatorConfig: {
+    queueUrl: '...',
+    startupResourcePolling: {
+      enabled: true,
+      pollingIntervalMs: 10000,
+      timeoutMs: 10 * 60 * 1000, // 10 minutes
+    }
   }
 }
 ```
 
 ### Error Handling
 
-When `timeoutMs` is configured and the resource doesn't become available within the specified time, a `ResourceAvailabilityTimeoutError` is thrown:
+When `timeoutMs` is configured and the resource doesn't become available within the specified time, a `StartupResourcePollingTimeoutError` is thrown:
 
 ```typescript
-import { ResourceAvailabilityTimeoutError } from '@message-queue-toolkit/core'
+import { StartupResourcePollingTimeoutError } from '@message-queue-toolkit/core'
 
 try {
   await consumer.init()
 } catch (error) {
-  if (error instanceof ResourceAvailabilityTimeoutError) {
+  if (error instanceof StartupResourcePollingTimeoutError) {
     console.error(`Resource ${error.resourceName} not available after ${error.timeoutMs}ms`)
   }
 }

packages/core/lib/index.ts

@@ -106,11 +106,11 @@ export { isShallowSubset, objectMatches } from './utils/matchUtils.ts'
 export { type ParseMessageResult, parseMessage } from './utils/parseUtils.ts'
 export { objectToBuffer } from './utils/queueUtils.ts'
 export {
-  isResourceAvailabilityWaitingEnabled,
-  type ResourceAvailabilityCheckResult,
-  ResourceAvailabilityTimeoutError,
+  isStartupResourcePollingEnabled,
+  type StartupResourcePollingCheckResult,
+  StartupResourcePollingTimeoutError,
   type WaitForResourceOptions,
   waitForResource,
-} from './utils/resourceAvailabilityUtils.ts'
+} from './utils/startupResourcePollingUtils.ts'
 export { toDatePreprocessor } from './utils/toDateProcessor.ts'
 export { waitAndRetry } from './utils/waitUtils.ts'

packages/core/lib/queues/AbstractQueueService.ts

@@ -46,7 +46,6 @@ import type {
   ProcessedMessageMetadata,
   QueueDependencies,
   QueueOptions,
-  ResourceAvailabilityConfig,
 } from '../types/queueOptionsTypes.ts'
 import { isRetryDateExceeded } from '../utils/dateUtils.ts'
 import { streamWithKnownSizeToString } from '../utils/streamUtils.ts'
@@ -126,7 +125,6 @@ export abstract class AbstractQueueService<
   protected readonly creationConfig?: QueueConfiguration
   protected readonly locatorConfig?: QueueLocatorType
   protected readonly deletionConfig?: DeletionConfig
-  protected readonly resourceAvailabilityConfig?: ResourceAvailabilityConfig
   protected readonly payloadStoreConfig?:
     | MakeRequired<SinglePayloadStoreConfig, 'serializer'>
     | MakeRequired<MultiPayloadStoreConfig, 'serializer'>
@@ -162,7 +160,6 @@ export abstract class AbstractQueueService<
     this.creationConfig = options.creationConfig
     this.locatorConfig = options.locatorConfig
     this.deletionConfig = options.deletionConfig
-    this.resourceAvailabilityConfig = options.resourceAvailabilityConfig
     this.payloadStoreConfig = options.payloadStoreConfig
       ? {
           serializer: jsonStreamStringifySerializer,

packages/core/lib/types/queueOptionsTypes.ts

@@ -118,13 +118,6 @@ export type CommonQueueOptions = {
   deletionConfig?: DeletionConfig
   payloadStoreConfig?: PayloadStoreConfig
   messageDeduplicationConfig?: MessageDeduplicationConfig
-  /**
-   * Configuration for eventual consistency mode.
-   * When enabled, the consumer will poll for the topic/queue to become available
-   * instead of failing immediately when using locatorConfig.
-   * This is useful for handling cross-service dependencies during deployment.
-   */
-  resourceAvailabilityConfig?: ResourceAvailabilityConfig
 }
 
 export type CommonCreationConfigType = {
@@ -138,57 +131,82 @@ export type DeletionConfig = {
 }
 
 /**
- * Configuration for eventual consistency mode when resources may not exist at startup.
+ * Symbol to indicate no timeout - polling will continue indefinitely.
+ * Use this for dev/staging environments where you want to wait indefinitely for resources.
+ *
+ * @example
+ * {
+ *   locatorConfig: {
+ *     queueUrl: '...',
+ *     startupResourcePolling: {
+ *       enabled: true,
+ *       timeoutMs: NO_TIMEOUT,
+ *     }
+ *   }
+ * }
+ */
+export const NO_TIMEOUT = Symbol('NO_TIMEOUT')
+
+/**
+ * Configuration for startup resource polling mode when resources may not exist at startup.
  *
  * This is useful in scenarios where services have cross-dependencies:
  * - Service A needs to subscribe to Service B's topic
  * - Service B needs to subscribe to Service A's topic
  * - Neither can deploy first without the other's topic existing
  *
- * When `resourceAvailabilityConfig` is provided, the consumer will poll for the
- * topic/queue to become available instead of failing immediately.
+ * When `startupResourcePolling` is provided with `enabled: true` inside `locatorConfig`,
+ * the consumer will poll for the topic/queue to become available instead of failing immediately.
  *
  * @example
- * // Development/staging - poll indefinitely
+ * // Enable with 5 minute timeout
  * {
- *   resourceAvailabilityConfig: {
- *     pollingIntervalMs: 5000,
+ *   locatorConfig: {
+ *     queueUrl: '...',
+ *     startupResourcePolling: {
+ *       enabled: true,
+ *       timeoutMs: 5 * 60 * 1000,
+ *     }
  *   }
  * }
  *
  * @example
- * // Production - poll with timeout to catch misconfigurations
+ * // Poll indefinitely (useful for dev/staging environments)
  * {
- *   resourceAvailabilityConfig: {
- *     timeoutMs: 5 * 60 * 1000, // 5 minutes
- *     pollingIntervalMs: 10000,
+ *   locatorConfig: {
+ *     queueUrl: '...',
+ *     startupResourcePolling: {
+ *       enabled: true,
+ *       timeoutMs: NO_TIMEOUT,
+ *     }
  *   }
  * }
  *
  * @example
- * // Temporarily disable without removing config
+ * // Custom timeout and interval
  * {
- *   resourceAvailabilityConfig: {
- *     enabled: false,
- *     timeoutMs: 5 * 60 * 1000,
+ *   locatorConfig: {
+ *     queueUrl: '...',
+ *     startupResourcePolling: {
+ *       enabled: true,
+ *       timeoutMs: 10 * 60 * 1000, // 10 minutes
+ *       pollingIntervalMs: 10000,
+ *     }
  *   }
  * }
  */
-export type ResourceAvailabilityConfig = {
+export type StartupResourcePollingConfig = {
   /**
    * Controls whether polling is enabled.
-   * Default: true (when resourceAvailabilityConfig is provided)
-   * Set to false to temporarily disable polling without removing the config.
+   * Must be set to true to enable polling.
    */
   enabled?: boolean
 
   /**
    * Maximum time in milliseconds to wait for the resource to become available.
-   * If not set or set to 0, will poll indefinitely (useful for dev/staging environments).
-   * For production, it's recommended to set a reasonable timeout (e.g., 5 minutes).
-   * Default: undefined (no timeout - poll indefinitely)
+   * Use `NO_TIMEOUT` to disable timeout and poll indefinitely.
    */
-  timeoutMs?: number
+  timeoutMs: number | typeof NO_TIMEOUT
 
   /**
    * Interval in milliseconds between polling attempts.
@@ -197,6 +215,19 @@ export type ResourceAvailabilityConfig = {
   pollingIntervalMs?: number
 }
 
+/**
+ * Base type for queue locator configurations that includes startup resource polling.
+ * Protocol-specific locator types should extend this.
+ */
+export type BaseQueueLocatorType = {
+  /**
+   * Configuration for startup resource polling mode.
+   * When enabled, the consumer will poll for the resource to become available
+   * instead of failing immediately.
+   */
+  startupResourcePolling?: StartupResourcePollingConfig
+}
+
 type NewQueueOptions<CreationConfigType extends CommonCreationConfigType> = {
   creationConfig?: CreationConfigType
 }