@pingpolls/redisq 0.2.0 → 1.0.0

package/README.md

@@ -26,10 +26,10 @@ bun install @pingpolls/redisq
 ## Quick Start
 
 ```typescript
-import RedisQueue from '@pingpolls/redisq';
+import { RedisQ } from '@pingpolls/redisq';
 
 // Initialize the queue
-const queue = new RedisQueue({
+const queue = new RedisQ({
   host: '127.0.0.1',
   port: '6379',
   namespace: 'myapp'
@@ -45,8 +45,8 @@ await queue.sendMessage({
 });
 
 // Start a worker to process messages
-await queue.startWorker('emails', async (message) => {
-  const email = JSON.parse(message.message);
+await queue.startWorker('emails', async (received) => {
+  const email = JSON.parse(received.message);
   console.log(`Sending email to ${email.to}`);
   
   // Process your message here
@@ -70,14 +70,12 @@ Batch queues (suffix `:batch`) collect messages over a time period and process t
 
 ### SvelteKit
 
-#### Option 1: Direct Import (Recommended for Simple Apps)
-
 Create a queue service in `src/lib/server/queue.ts`:
 
 ```typescript
-import RedisQueue from '@pingpolls/redisq';
+import { RedisQ } from '@pingpolls/redisq';
 
-export const queue = new RedisQueue({
+export const queue = new RedisQ({
   host: import.meta.env.REDIS_HOST || '127.0.0.1',
   port: import.meta.env.REDIS_PORT || '6379',
   namespace: 'sveltekit-app'
@@ -102,8 +100,8 @@ import { queue, initQueues } from '$lib/server/queue';
 await initQueues();
 
 // Start email worker
-queue.startWorker('emails', async (message) => {
-  const data = JSON.parse(message.message);
+queue.startWorker('emails', async (received) => {
+  const data = JSON.parse(received.message);
   await sendEmail(data);
   return { success: true };
 }, { silent: false });
@@ -160,148 +158,14 @@ export async function load() {
 }
 ```
 
-#### Option 2: Using event.locals (Recommended for Larger Apps)
-
-This approach provides better dependency injection and testing capabilities with SvelteKit 5.
-
-Create the queue service in `src/lib/server/queue.ts`:
-
-```typescript
-import RedisQueue from '@pingpolls/redisq';
-
-export function createQueue() {
-  return new RedisQueue({
-    host: import.meta.env.REDIS_HOST || '127.0.0.1',
-    port: import.meta.env.REDIS_PORT || '6379',
-    namespace: 'sveltekit-app'
-  });
-}
-
-export async function initQueues(queue: RedisQueue) {
-  await queue.createQueue({ qname: 'emails', maxRetries: 3 });
-  await queue.createQueue({ 
-    qname: 'analytics:batch', 
-    every: 60,
-    maxRetries: 2 
-  });
-}
-```
-
-Setup in `src/hooks.server.ts`:
-
-```typescript
-import type { Handle } from '@sveltejs/kit';
-import { createQueue, initQueues } from '$lib/server/queue';
-
-// Create single queue instance
-const queue = createQueue();
-await initQueues(queue);
-
-// Start workers
-queue.startWorker('emails', async (message) => {
-  const data = JSON.parse(message.message);
-  await sendEmail(data);
-  return { success: true };
-});
-
-queue.startWorker('analytics:batch', async (batch) => {
-  await saveToDB(batch.messages);
-  return { success: true };
-});
-
-export const handle: Handle = async ({ event, resolve }) => {
-  // Attach queue to event.locals
-  event.locals.queue = queue;
-  
-  return resolve(event);
-};
-```
-
-Add TypeScript types in `src/app.d.ts`:
-
-```typescript
-import type RedisQueue from '@pingpolls/redisq';
-
-declare global {
-  namespace App {
-    interface Locals {
-      queue: RedisQueue;
-    }
-  }
-}
-
-export {};
-```
-
-Now use `event.locals.queue` in your routes:
-
-```typescript
-// src/routes/api/signup/+server.ts
-import { json } from '@sveltejs/kit';
-import type { RequestHandler } from './$types';
-
-export const POST: RequestHandler = async ({ request, locals }) => {
-  const { email, name } = await request.json();
-  
-  // Access queue from locals
-  await locals.queue.sendMessage({
-    qname: 'emails',
-    message: JSON.stringify({ to: email, template: 'welcome', name })
-  });
-  
-  await locals.queue.sendBatchMessage({
-    qname: 'analytics:batch',
-    batchId: 'signups',
-    message: JSON.stringify({ event: 'signup', email, timestamp: Date.now() })
-  });
-  
-  return json({ success: true });
-};
-```
-
-```typescript
-// src/routes/orders/[id]/+page.server.ts
-import type { PageServerLoad, Actions } from './$types';
-
-export const load: PageServerLoad = async ({ params, locals }) => {
-  // Queue background task
-  await locals.queue.sendMessage({
-    qname: 'emails',
-    message: JSON.stringify({ type: 'order-confirmation', orderId: params.id })
-  });
-  
-  return {
-    orderId: params.id
-  };
-};
-
-export const actions: Actions = {
-  cancel: async ({ params, locals }) => {
-    await locals.queue.sendMessage({
-      qname: 'emails',
-      message: JSON.stringify({ type: 'order-cancellation', orderId: params.id })
-    });
-    
-    return { success: true };
-  }
-};
-```
-
-**Benefits of using `event.locals`:**
-- Single queue instance across your app
-- Better for dependency injection and testing
-- Cleaner imports in routes
-- Type-safe access with TypeScript
-- Follows SvelteKit 5 best practices
-
 ### Next.js (App Router)
 
 Create queue in `lib/queue.ts`:
 
 ```typescript
-import RedisQueue from '@pingpolls/redisq';
+import { RedisQ } from '@pingpolls/redisq';
 
-export const queue = new RedisQueue({
+export const queue = new RedisQ({
   host: process.env.REDIS_HOST!,
   port: process.env.REDIS_PORT!,
   namespace: 'nextjs-app'
@@ -317,8 +181,8 @@ import { queue } from '@/lib/queue';
 await queue.createQueue({ qname: 'notifications', maxRetries: 3 });
 
 // Start worker
-queue.startWorker('notifications', async (message) => {
-  const notification = JSON.parse(message.message);
+queue.startWorker('notifications', async (received) => {
+  const notification = JSON.parse(received.message);
   await sendPushNotification(notification);
   return { success: true };
 });
@@ -353,10 +217,10 @@ export async function POST(request: Request) {
 Create queue plugin in `server/plugins/queue.ts`:
 
 ```typescript
-import RedisQueue from '@pingpolls/redisq';
+import { RedisQ } from '@pingpolls/redisq';
 
 export default defineNitroPlugin(async (nitroApp) => {
-  const queue = new RedisQueue({
+  const queue = new RedisQ({
     host: process.env.REDIS_HOST || '127.0.0.1',
     port: process.env.REDIS_PORT || '6379',
     namespace: 'nuxt-app'
@@ -365,8 +229,8 @@ export default defineNitroPlugin(async (nitroApp) => {
   await queue.createQueue({ qname: 'tasks', maxRetries: 3 });
 
   // Start worker
-  queue.startWorker('tasks', async (message) => {
-    const task = JSON.parse(message.message);
+  queue.startWorker('tasks', async (received) => {
+    const task = JSON.parse(received.message);
     await processTask(task);
     return { success: true };
   });
@@ -396,11 +260,11 @@ export default defineEventHandler(async (event) => {
 
 ```typescript
 import { Hono } from 'hono';
-import RedisQueue from '@pingpolls/redisq';
+import { RedisQ } from '@pingpolls/redisq';
 
 const app = new Hono();
 
-const queue = new RedisQueue({
+const queue = new RedisQ({
   host: '127.0.0.1',
   port: '6379',
   namespace: 'hono-app'
@@ -415,8 +279,8 @@ await queue.createQueue({
 });
 
 // Start regular queue worker
-queue.startWorker('webhooks', async (message) => {
-  const webhook = JSON.parse(message.message);
+queue.startWorker('webhooks', async (received) => {
+  const webhook = JSON.parse(received.message);
   await fetch(webhook.url, {
     method: 'POST',
     body: JSON.stringify(webhook.data),
@@ -465,7 +329,7 @@ export default app;
 ### Constructor
 
 ```typescript
-new RedisQueue(options: QueueOptions)
+new RedisQ(options: QueueOptions)
 ```
 
 **Options:**
@@ -543,11 +407,11 @@ Starts a worker to process messages.
 
 ```typescript
 // Regular queue worker
-await queue.startWorker('my-queue', async (message) => {
-  console.log(message.id);
-  console.log(message.message);
-  console.log(message.attempt);
-  console.log(message.sent);
+await queue.startWorker('my-queue', async (received) => {
+  console.log(received.id);
+  console.log(received.message);
+  console.log(received.attempt);
+  console.log(received.sent);
   
   return { success: true }; // or { success: false } to retry
 }, {
@@ -722,11 +586,11 @@ REDIS_TLS=false
 
 ```typescript
 import { describe, test, expect } from 'bun:test';
-import RedisQueue from '@pingpolls/redisq';
+import { RedisQ } from '@pingpolls/redisq';
 
 describe('Queue Tests', () => {
   test('processes messages', async () => {
-    const queue = new RedisQueue({ host: '127.0.0.1', port: '6379' });
+    const queue = new RedisQ({ host: '127.0.0.1', port: '6379' });
     
     await queue.createQueue({ qname: 'test' });
     
@@ -757,16 +621,16 @@ Run the stress test to benchmark on your hardware:
 bun stress
 ```
 
-Individual Queue Performance:
-  - **Tiny messages (100B)**:   47181 msg/s (p50: 49.97ms)
-  - **Small messages (1KB)**:   33709 msg/s (p50: 69.05ms)
-  - **Medium messages (10KB)**:  4056 msg/s (p50: 261.32ms)
-  
-Overall:
-  - **Throughput**: ~28,315 messages/second
-  - **Latency (p50)**: 126.78 ms
-  - **Latency (p95)**: 299.27 ms
-  - **Latency (p99)**: 383.86 ms
+✅ Individual Queue Performance:
+  - **Tiny messages (100B)**:   49,302 msg/s (p50: 49.75ms)
+  - **Small messages (1KB)**:   35,061 msg/s (p50: 74.34ms)
+  - **Medium messages (10KB)**:  9,437 msg/s (p50: 213.58ms)
+
+💡 Overall (Averaged across all tests):
+  - **Throughput**: ~31,267 messages/second
+  - **Latency (p50)**: 112.56 ms
+  - **Latency (p95)**: 312.11 ms
+  - **Latency (p99)**: 676.23 ms
 
 Tested on Dockerized `redis:alpine` through WSL2 with 1 CPU and 1GB instance.
 

package/app.test.ts

@@ -1,5 +1,5 @@
 import { afterAll, describe, expect, test } from "bun:test";
-import RedisQueue from "./app";
+import { RedisQ } from "./app";
 
 const redisConfig = {
     host: process.env.REDIS_HOST || "127.0.0.1",
@@ -16,9 +16,9 @@ const workerConfig = {
  */
 const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
 
-describe("RedisQueue Tests", () => {
+describe("RedisQ Tests", () => {
     test("1. Can send and receive single message", async () => {
-        const queue = new RedisQueue(redisConfig);
+        const queue = new RedisQ(redisConfig);
 
         await queue.createQueue({ qname: "test-basic" });
 
@@ -51,7 +51,7 @@ describe("RedisQueue Tests", () => {
     });
 
     test("2. Can send and receive delayed message", async () => {
-        const queue = new RedisQueue(redisConfig);
+        const queue = new RedisQ(redisConfig);
 
         await queue.createQueue({ qname: "test-delayed" });
 
@@ -97,7 +97,7 @@ describe("RedisQueue Tests", () => {
     });
 
     test("3. Can retry send and receive single message", async () => {
-        const queue = new RedisQueue(redisConfig);
+        const queue = new RedisQ(redisConfig);
 
         await queue.createQueue({
             maxBackoffSeconds: 1,
@@ -141,7 +141,7 @@ describe("RedisQueue Tests", () => {
     });
 
     test("4. Can retry send and receive delayed message", async () => {
-        const queue = new RedisQueue(redisConfig);
+        const queue = new RedisQ(redisConfig);
 
         await queue.createQueue({
             maxBackoffSeconds: 1,
@@ -198,7 +198,7 @@ describe("RedisQueue Tests", () => {
     });
 
     test("5. Can send and receive batched messages (multiple batches in same period)", async () => {
-        const queue = new RedisQueue(redisConfig);
+        const queue = new RedisQ(redisConfig);
 
         /**
          * Create batch queue with 3-second interval
@@ -328,7 +328,7 @@ describe("RedisQueue Tests", () => {
     });
 
     test("6. Can send and receive batched messages with selective retry", async () => {
-        const queue = new RedisQueue(redisConfig);
+        const queue = new RedisQ(redisConfig);
 
         /**
          * Create batch queue with 2-second interval and retry enabled
@@ -509,7 +509,7 @@ describe("RedisQueue Tests", () => {
     test("7. Can handle high volume and concurrency", async () => {
         const totalMessages = 10_000;
 
-        const queue = new RedisQueue(redisConfig);
+        const queue = new RedisQ(redisConfig);
 
         await queue.createQueue({ qname: "test-concurrency" });
 

package/app.ts

@@ -79,7 +79,7 @@ interface StoredBatchMeta {
     attempt: number;
 }
 
-export class RedisQueue {
+export class RedisQ {
     private redis: BunRedisClient;
     private redisUrl: string;
     private ns: string;
@@ -550,7 +550,7 @@ export class RedisQueue {
 
     private async processBatches(
         qname: string,
-        handler: (message: BatchMessage) => Promise<{ success: boolean }>,
+        handler: (batch: BatchMessage) => Promise<{ success: boolean }>,
         silent: boolean,
     ): Promise<void> {
         if (this.isClosing) return;
@@ -600,7 +600,7 @@ export class RedisQueue {
     async startWorker<QueueName extends `${string}:batch` | (string & {})>(
         qname: QueueName,
         handler: (
-            message: QueueName extends `${string}:batch`
+            received: QueueName extends `${string}:batch`
                 ? BatchMessage
                 : Message,
         ) => Promise<{ success: boolean }>,
@@ -630,7 +630,7 @@ export class RedisQueue {
                     await this.processBatches(
                         qname,
                         handler as (
-                            message: BatchMessage,
+                            received: BatchMessage,
                         ) => Promise<{ success: boolean }>,
                         silent,
                     );
@@ -653,7 +653,7 @@ export class RedisQueue {
                 this.runWorker(
                     qname,
                     handler as (
-                        message: Message,
+                        received: Message,
                     ) => Promise<{ success: boolean }>,
                     controller.signal,
                     i,
@@ -667,7 +667,7 @@ export class RedisQueue {
 
     private async runWorker(
         qname: string,
-        handler: (message: Message) => Promise<{ success: boolean }>,
+        handler: (received: Message) => Promise<{ success: boolean }>,
         signal: AbortSignal,
         workerId: number,
         silent: boolean,
@@ -687,13 +687,16 @@ export class RedisQueue {
                         ids as string[],
                     );
 
-                    const processingPromises = messages.map((message) =>
-                        handler(message)
+                    const processingPromises = messages.map((received) =>
+                        handler(received)
                             .then(async ({ success }) => {
                                 if (success) {
-                                    await this.deleteMessage(qname, message.id);
+                                    await this.deleteMessage(
+                                        qname,
+                                        received.id,
+                                    );
                                 } else {
-                                    await this.retryMessage(qname, message.id);
+                                    await this.retryMessage(qname, received.id);
                                 }
                             })
                             .catch(async (error) => {
@@ -703,7 +706,7 @@ export class RedisQueue {
                                         (error as Error).message,
                                     );
                                 }
-                                await this.retryMessage(qname, message.id);
+                                await this.retryMessage(qname, received.id);
                             }),
                     );
                     await Promise.all(processingPromises);
@@ -763,4 +766,4 @@ export class RedisQueue {
     }
 }
 
-export default RedisQueue;
+export default { RedisQ };

package/benchmark/stress-worker.ts

@@ -1,4 +1,5 @@
-import RedisQueue from "../app";
+import { RedisQ } from "../app";
+
 declare var self: Worker;
 
 interface WorkerMessage {
@@ -22,7 +23,7 @@ self.addEventListener("message", async (event: MessageEvent<WorkerMessage>) => {
             event.data.data;
 
         try {
-            const queue = new RedisQueue(redisConfig);
+            const queue = new RedisQ(redisConfig);
             const latencies: number[] = [];
             const CHUNK_SIZE = 1000;
 

package/benchmark/stress.ts

@@ -1,7 +1,7 @@
 #!/usr/bin/env bun
 
 import type { Worker } from "bun";
-import RedisQueue from "../app";
+import { RedisQ } from "../app";
 import mediumMsg from "./medium.txt";
 import smallMsg from "./small.txt";
 import tinyMsg from "./tiny.txt";
@@ -108,7 +108,7 @@ function printResults(testName: string, results: TestResults) {
 async function testRegularQueueParallel(
     config: StressTestConfig,
 ): Promise<TestResults> {
-    const queue = new RedisQueue({
+    const queue = new RedisQ({
         host: process.env.REDIS_HOST || "127.0.0.1",
         namespace: "stress-test",
         port: process.env.REDIS_PORT || "6379",

package/package.json

@@ -27,5 +27,5 @@
         "stress": "bun benchmark/stress.ts"
     },
     "type": "module",
-    "version": "0.2.0"
+    "version": "1.0.0"
 }

package/tsconfig.json

@@ -1,29 +1,29 @@
 {
-  "compilerOptions": {
-    // Environment setup & latest features
-    "lib": ["ESNext"],
-    "target": "ESNext",
-    "module": "Preserve",
-    "moduleDetection": "force",
-    "jsx": "react-jsx",
-    "allowJs": true,
+    "compilerOptions": {
+        "allowImportingTsExtensions": true,
+        "allowJs": true,
+        "jsx": "react-jsx",
+        // Environment setup & latest features
+        "lib": ["ESNext"],
+        "module": "Preserve",
+        "moduleDetection": "force",
 
-    // Bundler mode
-    "moduleResolution": "bundler",
-    "allowImportingTsExtensions": true,
-    "verbatimModuleSyntax": true,
-    "noEmit": true,
+        // Bundler mode
+        "moduleResolution": "bundler",
+        "noEmit": true,
+        "noFallthroughCasesInSwitch": true,
+        "noImplicitOverride": true,
+        "noPropertyAccessFromIndexSignature": false,
+        "noUncheckedIndexedAccess": true,
 
-    // Best practices
-    "strict": true,
-    "skipLibCheck": true,
-    "noFallthroughCasesInSwitch": true,
-    "noUncheckedIndexedAccess": true,
-    "noImplicitOverride": true,
+        // Some stricter flags (disabled by default)
+        "noUnusedLocals": false,
+        "noUnusedParameters": false,
+        "skipLibCheck": true,
 
-    // Some stricter flags (disabled by default)
-    "noUnusedLocals": false,
-    "noUnusedParameters": false,
-    "noPropertyAccessFromIndexSignature": false
-  }
+        // Best practices
+        "strict": true,
+        "target": "ESNext",
+        "verbatimModuleSyntax": true
+    }
 }