Add non-blocking mode

Author: kibertoad

README.md

@@ -285,13 +285,14 @@ const consumer = new MySnsSqsConsumer(dependencies, {
 | `enabled` | `boolean` | - | Must be set to `true` to enable polling |
 | `pollingIntervalMs` | `number` | `5000` | Interval between availability checks (ms) |
 | `timeoutMs` | `number \| NO_TIMEOUT` | - (required) | Maximum wait time before throwing `StartupResourcePollingTimeoutError`. Use `NO_TIMEOUT` to poll indefinitely |
+| `throwOnTimeout` | `boolean` | `true` | When `true`, throws error on timeout. When `false`, reports error via errorReporter, resets timeout counter, and continues polling |
 
 ### Environment-Specific Configuration
 
 ```typescript
 import { NO_TIMEOUT } from '@message-queue-toolkit/core'
 
-// Production - with timeout
+// Production - with timeout (throws error when timeout reached)
 {
   locatorConfig: {
     queueUrl: '...',
@@ -302,6 +303,19 @@ import { NO_TIMEOUT } from '@message-queue-toolkit/core'
   }
 }
 
+// Production - report timeout but keep trying
+// Useful when you want visibility into prolonged unavailability without failing
+{
+  locatorConfig: {
+    queueUrl: '...',
+    startupResourcePolling: {
+      enabled: true,
+      timeoutMs: 5 * 60 * 1000, // Report every 5 minutes
+      throwOnTimeout: false,    // Don't throw, just report and continue
+    }
+  }
+}
+
 // Development/Staging - poll indefinitely
 {
   locatorConfig: {

packages/core/lib/types/MessageQueueTypes.ts

@@ -1,4 +1,8 @@
-import type { CommonLogger, TransactionObservabilityManager } from '@lokalise/node-core'
+import type {
+  CommonLogger,
+  ErrorReporter,
+  TransactionObservabilityManager,
+} from '@lokalise/node-core'
 import type { ZodSchema } from 'zod/v4'
 
 import type { PublicHandlerSpy } from '../queues/HandlerSpy.ts'
@@ -38,6 +42,7 @@ export type { TransactionObservabilityManager }
 
 export type ExtraParams = {
   logger?: CommonLogger
+  errorReporter?: ErrorReporter
 }
 
 export type SchemaMap<SupportedMessageTypes extends string> = Record<

packages/core/lib/types/queueOptionsTypes.ts

@@ -213,6 +213,28 @@ export type StartupResourcePollingConfig = {
    * Default: 5000 (5 seconds)
    */
   pollingIntervalMs?: number
+
+  /**
+   * Whether to throw an error when timeout is reached.
+   * - `true` (default): Throws `StartupResourcePollingTimeoutError` when timeout is reached
+   * - `false`: Reports the error via errorReporter, resets the timeout counter, and continues polling
+   *
+   * Use `false` when you want to be notified about prolonged unavailability but don't want to fail.
+   * Default: true
+   */
+  throwOnTimeout?: boolean
+
+  /**
+   * Whether to run polling in non-blocking mode.
+   * - `false` (default): init() waits for the resource to become available before resolving
+   * - `true`: If resource is not immediately available, init() resolves immediately and
+   *   polling continues in the background. When the resource becomes available,
+   *   the `onResourceAvailable` callback is invoked.
+   *
+   * Use `true` when you want the service to start quickly without waiting for dependencies.
+   * Default: false
+   */
+  nonBlocking?: boolean
 }
 
 /**

packages/core/lib/utils/startupResourcePollingUtils.spec.ts

@@ -156,6 +156,234 @@ describe('startupResourcePollingUtils', () => {
       expect(result).toBe('test-result')
       expect(checkFn).toHaveBeenCalledTimes(5)
     })
+
+    it('throws by default when throwOnTimeout is not specified', async () => {
+      const checkFn = vi.fn().mockResolvedValue({ isAvailable: false })
+
+      await expect(
+        waitForResource({
+          config: { enabled: true, pollingIntervalMs: 10, timeoutMs: 50 },
+          checkFn,
+          resourceName: 'test-resource',
+        }),
+      ).rejects.toThrow(StartupResourcePollingTimeoutError)
+    })
+
+    it('throws when throwOnTimeout is true', async () => {
+      const checkFn = vi.fn().mockResolvedValue({ isAvailable: false })
+
+      await expect(
+        waitForResource({
+          config: { enabled: true, pollingIntervalMs: 10, timeoutMs: 50, throwOnTimeout: true },
+          checkFn,
+          resourceName: 'test-resource',
+        }),
+      ).rejects.toThrow(StartupResourcePollingTimeoutError)
+    })
+
+    it('reports error and continues polling when throwOnTimeout is false', async () => {
+      let callCount = 0
+      const checkFn = vi.fn().mockImplementation(() => {
+        callCount++
+        // Become available after what would be 2 timeout cycles
+        if (callCount < 8) {
+          return Promise.resolve({ isAvailable: false })
+        }
+        return Promise.resolve({ isAvailable: true, result: 'test-result' })
+      })
+
+      const errorReporter = {
+        report: vi.fn(),
+      }
+
+      const result = await waitForResource({
+        config: {
+          enabled: true,
+          pollingIntervalMs: 10,
+          timeoutMs: 35, // Will timeout around every 3-4 calls
+          throwOnTimeout: false,
+        },
+        checkFn,
+        resourceName: 'test-resource',
+        errorReporter,
+      })
+
+      expect(result).toBe('test-result')
+      // Should have reported at least one timeout error
+      expect(errorReporter.report).toHaveBeenCalled()
+      expect(errorReporter.report).toHaveBeenCalledWith(
+        expect.objectContaining({
+          error: expect.any(StartupResourcePollingTimeoutError),
+          context: expect.objectContaining({
+            resourceName: 'test-resource',
+            timeoutMs: 35,
+          }),
+        }),
+      )
+    })
+
+    it('logs warning when throwOnTimeout is false and timeout is reached', async () => {
+      let callCount = 0
+      const checkFn = vi.fn().mockImplementation(() => {
+        callCount++
+        if (callCount < 5) {
+          return Promise.resolve({ isAvailable: false })
+        }
+        return Promise.resolve({ isAvailable: true, result: 'test-result' })
+      })
+
+      const logger = {
+        info: vi.fn(),
+        debug: vi.fn(),
+        error: vi.fn(),
+        warn: vi.fn(),
+      }
+
+      await waitForResource({
+        config: {
+          enabled: true,
+          pollingIntervalMs: 10,
+          timeoutMs: 25,
+          throwOnTimeout: false,
+        },
+        checkFn,
+        resourceName: 'test-resource',
+        // @ts-expect-error - partial logger for testing
+        logger,
+      })
+
+      expect(logger.warn).toHaveBeenCalledWith(
+        expect.objectContaining({
+          message: expect.stringContaining('resetting timeout counter'),
+          resourceName: 'test-resource',
+        }),
+      )
+    })
+
+    it('tracks timeout count when throwOnTimeout is false', async () => {
+      let callCount = 0
+      const checkFn = vi.fn().mockImplementation(() => {
+        callCount++
+        // Become available after multiple timeout cycles
+        if (callCount < 12) {
+          return Promise.resolve({ isAvailable: false })
+        }
+        return Promise.resolve({ isAvailable: true, result: 'test-result' })
+      })
+
+      const errorReporter = {
+        report: vi.fn(),
+      }
+
+      await waitForResource({
+        config: {
+          enabled: true,
+          pollingIntervalMs: 5,
+          timeoutMs: 20, // Will timeout every ~4 calls
+          throwOnTimeout: false,
+        },
+        checkFn,
+        resourceName: 'test-resource',
+        errorReporter,
+      })
+
+      // Should have reported multiple timeout errors with increasing timeoutCount
+      expect(errorReporter.report.mock.calls.length).toBeGreaterThan(1)
+
+      // Verify timeoutCount increments
+      const firstCall = errorReporter.report.mock.calls[0]?.[0] as {
+        context: { timeoutCount: number }
+      }
+      const secondCall = errorReporter.report.mock.calls[1]?.[0] as {
+        context: { timeoutCount: number }
+      }
+      expect(firstCall.context.timeoutCount).toBe(1)
+      expect(secondCall.context.timeoutCount).toBe(2)
+    })
+
+    describe('nonBlocking mode', () => {
+      it('returns result immediately when resource is available on first check', async () => {
+        const checkFn = vi.fn().mockResolvedValue({ isAvailable: true, result: 'test-result' })
+        const onResourceAvailable = vi.fn()
+
+        const result = await waitForResource({
+          config: { enabled: true, pollingIntervalMs: 100, timeoutMs: 5000, nonBlocking: true },
+          checkFn,
+          resourceName: 'test-resource',
+          onResourceAvailable,
+        })
+
+        expect(result).toBe('test-result')
+        expect(checkFn).toHaveBeenCalledTimes(1)
+        expect(onResourceAvailable).not.toHaveBeenCalled()
+      })
+
+      it('returns undefined immediately when resource is not available and starts background polling', async () => {
+        const checkFn = vi.fn().mockResolvedValue({ isAvailable: false })
+        const onResourceAvailable = vi.fn()
+
+        const result = await waitForResource({
+          config: { enabled: true, pollingIntervalMs: 100, timeoutMs: 5000, nonBlocking: true },
+          checkFn,
+          resourceName: 'test-resource',
+          onResourceAvailable,
+        })
+
+        expect(result).toBeUndefined()
+        expect(checkFn).toHaveBeenCalledTimes(1)
+      })
+
+      it('calls onResourceAvailable when resource becomes available in background', async () => {
+        let callCount = 0
+        const checkFn = vi.fn().mockImplementation(() => {
+          callCount++
+          if (callCount < 3) {
+            return Promise.resolve({ isAvailable: false })
+          }
+          return Promise.resolve({ isAvailable: true, result: 'test-result' })
+        })
+        const onResourceAvailable = vi.fn()
+
+        const result = await waitForResource({
+          config: { enabled: true, pollingIntervalMs: 10, timeoutMs: 5000, nonBlocking: true },
+          checkFn,
+          resourceName: 'test-resource',
+          onResourceAvailable,
+        })
+
+        expect(result).toBeUndefined()
+
+        // Wait for background polling to complete
+        await new Promise((resolve) => globalThis.setTimeout(resolve, 100))
+
+        expect(onResourceAvailable).toHaveBeenCalledWith('test-result')
+      })
+
+      it('logs info message when starting background polling', async () => {
+        const checkFn = vi.fn().mockResolvedValue({ isAvailable: false })
+        const logger = {
+          info: vi.fn(),
+          debug: vi.fn(),
+          error: vi.fn(),
+          warn: vi.fn(),
+        }
+
+        await waitForResource({
+          config: { enabled: true, pollingIntervalMs: 100, timeoutMs: 5000, nonBlocking: true },
+          checkFn,
+          resourceName: 'test-resource',
+          // @ts-expect-error - partial logger for testing
+          logger,
+        })
+
+        expect(logger.info).toHaveBeenCalledWith(
+          expect.objectContaining({
+            message: expect.stringContaining('starting background polling'),
+            resourceName: 'test-resource',
+          }),
+        )
+      })
+    })
   })
 
   describe('StartupResourcePollingTimeoutError', () => {