lonnymq 0.0.27 → 0.0.29

package/README.md

@@ -1,6 +1,6 @@
 # LonnyMQ
 
-A high-performance, multi-tenant PostgreSQL message queue implementation for Node.js/TypeScript.
+A high-performance, multi-tenant PostgreSQL message queue implementation for Node.js/TypeScript. Docs can be found [here](https://tlonny.github.io/lonnymq)
 
 ## Features
 
@@ -35,14 +35,16 @@ for (const sql of queue.install()) {
 for (let ix = 0; ix < 500; ix += 1) {
     await queue.message.create({ 
         databaseClient,
-        content: Buffer.from("Hello"),
-        lockMs: 30_000 
+        content: Buffer.from("Hello")
     })
 }
 
 // Process messages
 while (true) {
-    const dequeueResult = await queue.dequeue({ databaseClient })
+    const dequeueResult = await queue.dequeue({ 
+        databaseClient,
+        lockMs: 30_000 
+    })
     if (dequeueResult.resultType === "MESSAGE_NOT_AVAILABLE") {
         break
     }
@@ -87,18 +89,16 @@ await queue
 
 ## Message Creation
 
-You can add a message to the queue using the `create` function. By default, messages are assigned to a random channel, ensuring fair distribution:
+You can add a message to the queue using the `create` function. By default, messages are assigned to a unique channel, resulting in basic FIFO behaviour.
 
 ```typescript
 await queue.message.create({
     databaseClient,
     content: Buffer.from("Hello, world"),
-    lockMs: 30000,
-    delayMs: 5000
 })
 ```
 
-If you need to assign messages to specific channels (for example, to take advantage of concurrency or rate limiting features), you can specify the channel explicitly:
+If you need to assign messages to specific channels (for example, to take advantage of fairness, concurrency or rate limiting features), you can specify the channel explicitly:
 
 ```typescript
 await queue
@@ -106,22 +106,21 @@ await queue
     .message
     .create({
         databaseClient,
-        content: Buffer.from("Hello, world"),
-        lockMs: 30000,
-        delayMs: 5000
+        content: Buffer.from("Hello, world")
     })
 ```
 
-The `lockMs` parameter is required and specifies how long a message will remain exclusively locked after being dequeued. While locked, the message is **not available** for subsequent `dequeue()` calls, preventing duplicate processing. If your process crashes or takes longer than expected, the message will automatically become available for dequeue again after the lock expires.
-
 The `delayMs` parameter is optional and allows you to delay when the message becomes available for processing.
 
 ## Message Processing
 
-Messages can be fetched for processing by calling `dequeue` on the `Queue` - this locks the message. Once processing is complete, messages must be "finalized" via **deletion** or **deferral** (for further processing in the future).
+Messages can be fetched for processing by calling `dequeue` on the `Queue` - this locks the message for a specified duration. Once processing is complete, messages must be "finalized" via **deletion** or **deferral** (for further processing in the future).
 
 ```typescript
-const dequeueResult = await queue.dequeue({ databaseClient })
+const dequeueResult = await queue.dequeue({ 
+    databaseClient,
+    lockMs: 60_000
+})
 
 if (dequeueResult.resultType === "MESSAGE_DEQUEUED") {
     const { message } = dequeueResult
@@ -157,15 +156,50 @@ if (dequeueResult.resultType === "MESSAGE_DEQUEUED") {
 }
 ```
 
+The `lockMs` parameter on `dequeue()` specifies how long a message will remain exclusively locked after being dequeued. While locked, the message is **not available** for subsequent `dequeue()` calls, preventing duplicate processing. If your process crashes or takes longer than expected, the message will automatically become available for dequeue again after the lock expires.
+
 When deferring a message, you can optionally specify `delayMs` and `state` arguments. The `delayMs` parameter tells the queue how long to wait before making the message available for reprocessing, and `state` allows you to "save your work" and implement durable and/or repeating/scheduled tasks.
 
 **Note:** The above shows just one processing pattern (defer on failure with retry limits). You have complete flexibility in how you handle message processing - you might delete messages immediately, defer them unconditionally, implement different retry strategies based on error types, or use the message metadata (attempts, state, channel) to make sophisticated routing decisions.
 
-### Graceful Shutdowns and Message Recovery
+### Extending Message Locks with Heartbeats
 
-If your program ends unexpectedly, messages that are currently being processed may become "orphaned" in a locked state - causing channel blockages and reducing throughput. To mitigate this problem, it's essential that you shut down gracefully by catching unhandled exceptions and signals (i.e., `SIGINT`/`SIGTERM`) and finalize all outstanding messages before exiting.
+For messages that take a long time to process, setting a large initial lock is far from ideal. A crash shortly after message dequeue will result in channel throughput being degraded for a significant time (if the channel is concurrency-constrained). To mitigate this, you can set a short initial lock time that can be periodically renewed during message processing via a heartbeat:
+
+```typescript
+const dequeueResult = await queue.dequeue({ 
+    databaseClient,
+    lockMs: 30_000 
+})
 
-That said, despite our best efforts, if we run out of memory, suffer a power loss, or receive a `SIGKILL`, we will be unable to finalize messages that are currently locked. To mitigate this, we set a `lockMs` during message creation (by default this is 1 hour) which limits the maximum amount of time a message can be locked before becoming available again for dequeue. This facility ensures that regardless of the nature of the shutdown, the queue will always recover automatically.
+if (dequeueResult.resultType === "MESSAGE_DEQUEUED") {
+    const { message } = dequeueResult
+    
+    // Start long-running process
+    const longTask = processLongRunningTask(message.content)
+    
+    // Set up heartbeat to extend lock every 20 seconds
+    const heartbeatInterval = setInterval(async () => {
+        await message.heartbeat({ 
+            databaseClient,
+            lockMs: 30_000
+        })
+    }, 20_000)
+    
+    try {
+        await longTask
+        await message.delete({ databaseClient })
+    } catch (error) {
+        await message.defer({ databaseClient, delayMs: 60_000 })
+    } finally {
+        clearInterval(heartbeatInterval)
+    }
+}
+```
+
+### Graceful Shutdowns and Message Recovery
+
+If your program ends unexpectedly, messages that are currently being processed may become "orphaned" in a locked state - causing channel blockages and reducing throughput until the lock expires. To mitigate this problem, it's essential that you shut down gracefully by catching unhandled exceptions and signals (i.e., `SIGINT`/`SIGTERM`) and finalize all outstanding messages before exiting.
 
 ## Events
 
@@ -185,21 +219,37 @@ const install = queue.install({ eventChannel: "EVENTS"})
 
 The simplest approach for processing messages is to call `dequeue` in a loop, backing off with a sleep when no messages are available. The downside of this approach is that we lose reactivity as we increase the polling timeout interval.
 
-To improve reactivity, you can use the `retryMs` returned when failing to dequeue a message. This will either be `null` or tell you how long until the next message becomes available for processing (a message might be deferred for a period of time). Thus, you can tune your sleep to use the minimum of your `retryMs` and a default poll timeout.
+```typescript
+// Basic polling approach
+while (true) {
+    const result = await queue.dequeue({ databaseClient, lockMs: 30_000 })
+    
+    if (result.resultType === "MESSAGE_NOT_AVAILABLE") {
+        await sleep(5_000) 
+        continue
+    }
+    
+    // Process message...
+    await processMessage(result.message)
+    await result.message.delete({ databaseClient })
+}
+```
 
-Unfortunately, this doesn't help in situations where a message is created or deferred while a worker is sleeping. However, by tracking the `delayMs` provided by the `MESSAGE_CREATED` and `MESSAGE_DEFERRED` events, we can determine the minimum amount of time to sleep until a message becomes available.
+To improve reactivity, you can use the events system to track when new messages become available. By listening for `MESSAGE_CREATED` and `MESSAGE_DEFERRED` events and tracking their `delayMs`, you can determine the optimal time to retry dequeuing:
 
 ```typescript
 // LISTEN/NOTIFY only works with a single connection - not on a connection pool.
 const client = await databaseClient.connect()
 await client.query(`LISTEN "EVENTS"`)
+
+let nextWakeTime = Date.now()
+
 client.on("notification", (msg) => {
-    if (msg.channel === "EVENTS") {}
+    if (msg.channel === "EVENTS") {
         const event = queueEventDecode(msg.payload as string)
-        if(event.eventType === "MESSAGE_CREATED") {
-            console.log(`Should wake in ${event.delayMs} ms`)
-        } else if(event.eventType === "MESSAGE_DEFERRED") {
-            console.log(`Should wake in ${event.delayMs} ms`)
+        if (event.eventType === "MESSAGE_CREATED" || event.eventType === "MESSAGE_DEFERRED") {
+            const messageAvailableAt = Date.now() + event.delayMs
+            nextWakeTime = Math.min(nextWakeTime, messageAvailableAt)
         }
     }
 })
@@ -209,28 +259,6 @@ client.on("notification", (msg) => {
 
 The `MESSAGE_DELETED` event can be used to create coordination patterns where one part of your application waits for an unrelated job to complete. By listening for deletion events on specific message IDs, you can implement blocking operations that wait for background work to finish.
 
-```typescript
-const client = await databaseClient.connect()
-await client.query(`LISTEN "EVENTS"`)
-
-const wait = (messageId: string) : Promise<void> => {
-    return new Promise((resolve) => {
-        const handler = (msg) => {
-            if (msg.channel === "EVENTS") {
-                const event = queueEventDecode(msg.payload as string)
-                if (event.eventType === "MESSAGE_DELETED" && event.id === messageId) {
-                    client.off("notification", handler)
-                    resolve()
-                }
-            }
-        }
-        client.on("notification", handler)
-    })
-}
-
-await wait(messageId)
-```
-
 ## Deadlocks
 
 If all queue actions are isolated to their own transaction, there is zero risk of deadlocks occurring. That being said, it is *possible* to safely bulk-perform the following actions within a single transaction if we ensure they are performed in a consistent ordering with respect to the target channel name:
@@ -244,6 +272,7 @@ Beyond the actions specified above, it is manifestly **unsafe** to bulk-perform
 - Message dequeue
 - Message defer
 - Message delete
+- Message heartbeat
 
 ## Database Clients
 
@@ -263,12 +292,10 @@ For database clients that don't match the expected interface exactly, LonnyMQ pr
 
 ```typescript
 import { Queue } from "lonnymq"
-import { Pool } from "pg"
 
-const customClient = new SomeOtherPostgresClient()
-const queue = new Queue({ 
+const queue = new Queue<NonCompliantDatabaseClient>({ 
     schema: "lonny",
-    adaptor: (client) => ({
+    adaptor: (client : NonCompliantDatabaseClient) => ({
         query: async (sql, params) => {
             // Adapt the client's interface to match DatabaseClient
             const result = await client.executeQuery(sql, params)