Address code review comments

Author: kibertoad

README.md

@@ -354,6 +354,80 @@ import { NO_TIMEOUT } from '@message-queue-toolkit/core'
 }
 ```
 
+### Non-Blocking Mode
+
+When `nonBlocking: true` is set, `init()` returns immediately if the resource is not available on the first check. Polling continues in the background, and you can use callbacks to be notified when resources become available.
+
+**Important behaviors:**
+- If the resource IS immediately available, `init()` returns normally with the resource ready
+- If the resource is NOT immediately available, `init()` returns with `resourcesReady: false` (for SNS/SQS) or `queueArn: undefined` (for SQS)
+- Background polling continues and invokes the callback when the resource becomes available
+- For SNS+SQS consumers, the callback is only invoked when BOTH topic and queue are available
+
+```typescript
+// SQS non-blocking with callback
+import { initSqs } from '@message-queue-toolkit/sqs'
+
+const result = await initSqs(
+  sqsClient,
+  {
+    queueUrl: '...',
+    startupResourcePolling: {
+      enabled: true,
+      timeoutMs: 5 * 60 * 1000,
+      nonBlocking: true,
+    },
+  },
+  undefined,
+  undefined,
+  {
+    onQueueReady: ({ queueArn }) => {
+      console.log(`Queue is now available: ${queueArn}`)
+      // Start consuming messages, update health checks, etc.
+    },
+  },
+)
+
+if (result.queueArn) {
+  console.log('Queue was immediately available')
+} else {
+  console.log('Queue not yet available, will be notified via callback')
+}
+
+// SNS+SQS non-blocking with callback
+import { initSnsSqs } from '@message-queue-toolkit/sns'
+
+const result = await initSnsSqs(
+  sqsClient,
+  snsClient,
+  stsClient,
+  {
+    topicArn: '...',
+    queueUrl: '...',
+    subscriptionArn: '...',
+    startupResourcePolling: {
+      enabled: true,
+      timeoutMs: 5 * 60 * 1000,
+      nonBlocking: true,
+    },
+  },
+  undefined,
+  undefined,
+  {
+    onResourcesReady: ({ topicArn, queueUrl }) => {
+      // Called only when BOTH topic and queue are available
+      console.log(`Resources ready: topic=${topicArn}, queue=${queueUrl}`)
+    },
+  },
+)
+
+if (result.resourcesReady) {
+  console.log('All resources were immediately available')
+} else {
+  console.log('Resources not yet available, will be notified via callback')
+}
+```
+
 ### Error Handling
 
 When `timeoutMs` is configured and the resource doesn't become available within the specified time, a `StartupResourcePollingTimeoutError` is thrown:

packages/sns/lib/utils/snsInitter.ts

@@ -122,17 +122,25 @@ export async function initSnsSqs(
   if (isStartupResourcePollingEnabled(startupResourcePolling)) {
     const nonBlocking = startupResourcePolling.nonBlocking === true
 
+    // Track availability for non-blocking mode coordination
+    let topicAvailable = false
+    let queueAvailable = false
+
+    const notifyIfBothReady = () => {
+      if (nonBlocking && topicAvailable && queueAvailable) {
+        extraParams?.onResourcesReady?.({ topicArn: subscriptionTopicArn, queueUrl })
+      }
+    }
+
     // Wait for topic to become available
     const topicResult = await waitForResource({
       config: startupResourcePolling,
       resourceName: `SNS topic ${subscriptionTopicArn}`,
       logger: extraParams?.logger,
       errorReporter: extraParams?.errorReporter,
       onResourceAvailable: () => {
-        // In non-blocking mode, when topic becomes available, notify caller
-        if (nonBlocking) {
-          extraParams?.onResourcesReady?.({ topicArn: subscriptionTopicArn, queueUrl })
-        }
+        topicAvailable = true
+        notifyIfBothReady()
       },
       checkFn: async () => {
         const result = await getTopicAttributes(snsClient, subscriptionTopicArn)
@@ -143,12 +151,43 @@ export async function initSnsSqs(
       },
     })
 
+    // If topic was immediately available, mark it
+    if (topicResult !== undefined) {
+      topicAvailable = true
+    }
+
     // If non-blocking and topic wasn't immediately available, return early
+    // Background polling will continue and call notifyIfBothReady when topic is available
     if (nonBlocking && topicResult === undefined) {
       const splitUrl = queueUrl.split('/')
       // biome-ignore lint/style/noNonNullAssertion: It's ok
       const queueName = splitUrl[splitUrl.length - 1]!
 
+      // Also start polling for queue in background so we can notify when both are ready
+      waitForResource({
+        config: startupResourcePolling,
+        resourceName: `SQS queue ${queueUrl}`,
+        logger: extraParams?.logger,
+        errorReporter: extraParams?.errorReporter,
+        onResourceAvailable: () => {
+          queueAvailable = true
+          notifyIfBothReady()
+        },
+        checkFn: async () => {
+          const result = await getQueueAttributes(sqsClient, queueUrl)
+          if (result.error === 'not_found') {
+            return { isAvailable: false }
+          }
+          return { isAvailable: true, result: result.result }
+        },
+      }).catch((error) => {
+        extraParams?.logger?.error({
+          message: 'Background polling for SQS queue failed',
+          queueUrl,
+          error,
+        })
+      })
+
       return {
         subscriptionArn: locatorConfig.subscriptionArn,
         topicArn: subscriptionTopicArn,
@@ -165,10 +204,8 @@ export async function initSnsSqs(
       logger: extraParams?.logger,
       errorReporter: extraParams?.errorReporter,
       onResourceAvailable: () => {
-        // In non-blocking mode, when queue becomes available, notify caller
-        if (nonBlocking) {
-          extraParams?.onResourcesReady?.({ topicArn: subscriptionTopicArn, queueUrl })
-        }
+        queueAvailable = true
+        notifyIfBothReady()
       },
       checkFn: async () => {
         const result = await getQueueAttributes(sqsClient, queueUrl)
@@ -179,6 +216,11 @@ export async function initSnsSqs(
       },
     })
 
+    // If queue was immediately available, mark it
+    if (queueResult !== undefined) {
+      queueAvailable = true
+    }
+
     // If non-blocking and queue wasn't immediately available, return early
     if (nonBlocking && queueResult === undefined) {
       const splitUrl = queueUrl.split('/')

packages/sqs/test/consumers/SqsPermissionConsumer.startupResourcePolling.spec.ts

@@ -226,7 +226,15 @@ describe('SqsPermissionConsumer - startupResourcePollingConfig', () => {
       // Start init without queue existing
       const initPromise = initSqs(
         sqsClient,
-        { queueUrl, startupResourcePolling: { enabled: true, pollingIntervalMs: 50, timeoutMs: 5000, nonBlocking: true } },
+        {
+          queueUrl,
+          startupResourcePolling: {
+            enabled: true,
+            pollingIntervalMs: 50,
+            timeoutMs: 5000,
+            nonBlocking: true,
+          },
+        },
         undefined,
         undefined,
         {