lonnymq 0.0.29 → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Tim Lonsdale
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -6,52 +6,70 @@ A high-performance, multi-tenant PostgreSQL message queue implementation for Nod
 
 - High throughput message processing
 - Multi-tenant concurrency and rate limits
-- Durable message processing with automatic recovery
-- Flexible message processing retries and deferrals
+- Durable message processing
+- Support for retries, recovery and custom back-off strategies
+- Message prioritisation
 - Queue operations as part of *existing* database transactions
 - Database client agnostic with optional adapters
-- Granular events via PostgreSQL `NOTIFY`
+- Granular events via PostgreSQL `NOTIFY` (Avoid relying on polling to fetch new messages)
 - Zero dependencies
 
 **Note:** Unlike other queue implementations, LonnyMQ provides direct access to queue methods rather than providing batteries-included Worker/Processor daemons.
 
+### Benchmarking
+
+With the following parameters:
+ - Everything running in a single Bun instance
+ - A locally hosted postgres database
+ - The code as-is below in "Quick Look", but with 8 producers and 8 consumers
+
+A message throughput of **~1,800** messages per second is observed.
+
 ## Quick Look
 
 ```typescript
-import { Queue, type DatabaseClient } from "lonnymq"
+import { Queue } from "lonnymq"
 import { Pool } from "pg"
 
 const databaseClient = new Pool({ connectionString: process.env.DATABASE_URL })
-databaseClient satisfies DatabaseClient
-
 const queue = new Queue({ schema: "lonny" })
+const content = Buffer.from("hello world")
 
-// Install the queue
-for (const sql of queue.install()) {
-    await databaseClient.query(sql, [])
-}
+const produce = async () => {
+    while (true) {
+        const result = await queue.message.create({
+            databaseClient: pool,
+            content: content
+        })
 
-// Create messages
-for (let ix = 0; ix < 500; ix += 1) {
-    await queue.message.create({ 
-        databaseClient,
-        content: Buffer.from("Hello")
-    })
-}
+        if (result.resultType !== "MESSAGE_CREATED") {
+            continue
+        }
 
-// Process messages
-while (true) {
-    const dequeueResult = await queue.dequeue({ 
-        databaseClient,
-        lockMs: 30_000 
-    })
-    if (dequeueResult.resultType === "MESSAGE_NOT_AVAILABLE") {
-        break
+        if (result.channelSize > 1_000) {
+            await sleep(result.channelSize)
+        }
     }
+}
+
+const consume = async () => {
+    while (true) {
+        const result = await queue.dequeue({
+            databaseClient: pool,
+            lockMs: 1_000
+        })
 
-    console.log(dequeueResult.message.content.toString())
-    await dequeueResult.message.delete({ databaseClient })
+        if (result.resultType === "MESSAGE_DEQUEUED") {
+            await result.message.delete({ databaseClient: pool })
+        }
+    }
 }
+
+// Kick off producer loop
+produce()
+
+// Kick off consumer loop
+consume()
 ```
 
 ## Setup & Installation
@@ -62,13 +80,26 @@ LonnyMQ can be installed from npm:
 npm install lonnymq
 ```
 
-Once the package is installed, the queue needs to be "installed" to a postgres schema. The requisite SQL for this can be generated via: `queue.install()`.
+Once the package is installed, the queue needs to be "installed" to a postgres schema. The requisite SQL for this can be generated via: 
+
+```typescript
+const sqlCommands = queue.install({
+    eventChannel: "lonnymq-events",
+
+for(const sql of sqlCommands) {
+    await pool
+}
+})
+```
+
+_Optional_ parameters can be passed in to alter default queue behaviour/semantics. If an `eventChannel` is provided, LonnyMQ will publish queue events to the channel provided via `NOTIFY`.
+
 
 ## Channels
 
 Channels provide LonnyMQ's multi-tenancy support. They can be considered lightweight sub-queues that are read from in round-robin fashion. There is no performance penalty for using large numbers of channels, so they can be assigned on a highly granular basis (e.g., per-user) to ensure work is scheduled fairly.
 
-Channels can be configured with concurrency and rate limits by setting their "channel policy":
+Channels can be configured with rate limiting, concurrency and capacity constraints by setting their _channel policy_:
 
 ```typescript
 await queue
@@ -77,7 +108,8 @@ await queue
     .set({ 
         databaseClient,
         maxConcurrency: 1,
-        releaseIntervalMs: 1000
+        releaseIntervalMs: 1000,
+        maxSize: 1_000
     })
 
 // Remove all constraints:
@@ -110,7 +142,25 @@ await queue
     })
 ```
 
-The `delayMs` parameter is optional and allows you to delay when the message becomes available for processing.
+By default, created messages are immediately available for processing. To delay availability you can pass a `dequeueAt` unix timestamp (in milliseconds) that specifies the earliest time the message may be dequeued.
+
+```typescript
+await queue.message.create({
+    databaseClient,
+    content: Buffer.from("Hello, world"),
+    dequeueAt: Date.now() + 5_000 // 5s in the future
+})
+```
+
+N.B. `dequeueAt` is compared against the _database_ clock.
+
+### Message Prioritization
+
+LonnyMQ doesn't use an explicit message priority field for performance reasons. In short, there is no way to find the highest priority message that is also available for dequeue for a particular channel without some degree of linear scanning in the worst case vs. simply using a logarithmic index lookup. 
+
+However, messages that _are_ available for processing are dequeued from their channels in order of their `dequeueAt` values (oldest first). Thus, by overloading the semantics of the `dequeueAt` field and using _historic_ unix timestamps (i.e. `0`, `1`, `2`, etc.) - messages can trivially be prioritized within a channel.
+
+N.B. there is no way to _globally_ prioritize a message - channels will _always_ be accessed in a round-robin fashion.
 
 ## Message Processing
 
@@ -140,10 +190,10 @@ if (dequeueResult.resultType === "MESSAGE_DEQUEUED") {
             await message.delete({ databaseClient })
         } else {
             // Defer for retry with exponential backoff and updated state
-            const backoffMs = Math.pow(2, message.numAttempts) * 1000
+            const backoffMs = Math.pow(2, message.numAttempts) * 1_000
             await message.defer({ 
                 databaseClient,
-                delayMs: backoffMs,
+                dequeueAt: Date.now() + backoffMs,
                 state: Buffer.from(JSON.stringify({ 
                     error: error.message,
                     lastAttempt: new Date().toISOString()
@@ -158,7 +208,7 @@ 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.
+When a message is deferred it becomes immediately available for re-processing unless you supply a `dequeueAt` timestamp.
 
 **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.
 
@@ -190,7 +240,10 @@ if (dequeueResult.resultType === "MESSAGE_DEQUEUED") {
         await longTask
         await message.delete({ databaseClient })
     } catch (error) {
-        await message.defer({ databaseClient, delayMs: 60_000 })
+        await message.defer({ 
+            databaseClient, 
+            dequeueAt: Date.now() + 60_000 
+        })
     } finally {
         clearInterval(heartbeatInterval)
     }
@@ -199,7 +252,7 @@ if (dequeueResult.resultType === "MESSAGE_DEQUEUED") {
 
 ### 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.
+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 locks expire. 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
 
@@ -209,8 +262,6 @@ Using PostgreSQL `NOTIFY`, we can receive a granular stream of queue events:
   2. `MESSAGE_DEFERRED`
   4. `MESSAGE_DELETED`
 
-To enable this feature, ensure the optional `eventChannel` is defined when generating the installation SQL.
-
 ```typescript
 const install = queue.install({ eventChannel: "EVENTS"})
 ```
@@ -235,7 +286,7 @@ while (true) {
 }
 ```
 
-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:
+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 `dequeueAt` values, you can determine the optimal time to retry dequeuing:
 
 ```typescript
 // LISTEN/NOTIFY only works with a single connection - not on a connection pool.
@@ -246,10 +297,9 @@ let nextWakeTime = Date.now()
 
 client.on("notification", (msg) => {
     if (msg.channel === "EVENTS") {
-        const event = queueEventDecode(msg.payload as string)
+        const event = Queue.decode(msg.payload as string)
         if (event.eventType === "MESSAGE_CREATED" || event.eventType === "MESSAGE_DEFERRED") {
-            const messageAvailableAt = Date.now() + event.delayMs
-            nextWakeTime = Math.min(nextWakeTime, messageAvailableAt)
+            nextWakeTime = Math.min(nextWakeTime, event.dequeueAt)
         }
     }
 })
@@ -261,13 +311,13 @@ The `MESSAGE_DELETED` event can be used to create coordination patterns where on
 
 ## 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:
+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:
 
 - Message create
 - Channel policy set  
 - Channel policy clear
 
-Beyond the actions specified above, it is manifestly **unsafe** to bulk-perform any of the remaining actions within a single transaction. Each of these actions should be isolated within their **own** transaction:
+Beyond the actions specified above, it is **unsafe** to bulk-perform any of the remaining actions within a single transaction. Each of these actions should be isolated within their **own** transaction:
 
 - Message dequeue
 - Message defer
@@ -303,4 +353,4 @@ const queue = new Queue<NonCompliantDatabaseClient>({
         }
     })
 })
-```
+```