@pingpolls/redisq 1.0.3 → 1.0.4

package/dist/app.d.ts

@@ -1,57 +1,149 @@
 import { RedisClient as BunRedisClient } from "bun";
+/**
+ * Options for initializing the RedisQ client.
+ * You can either provide a Redis client instance or connection details.
+ */
 export type QueueOptions = {
+    /** A Bun Redis client instance. */
     redis: BunRedisClient;
 } | {
+    /** Redis server host. */
     host: string;
+    /** Redis server port. */
     port: string;
+    /** Redis server user. */
     user?: string;
+    /** Redis server password. */
     password?: string;
+    /** Namespace for all Redis keys. */
     namespace?: string;
+    /** Whether to use TLS for the connection. */
     tls?: boolean;
 };
+/**
+ * Options for creating a new queue.
+ * The options are different for regular and batch queues.
+ */
 export type CreateQueueOptions<QueueName extends string = string> = QueueName extends `${string}:batch` ? {
+    /**
+     * The name of the queue. Must end with `:batch` for batch queues.
+     * @example "my-queue:batch"
+     */
     qname: QueueName;
+    /** Maximum message size in bytes.
+     * @default 65536
+     */
     maxsize?: number;
+    /**
+     * Maximum number of retries for a message.
+     * `0` = no retry, `-1` = unlimited, `n` = max retries.
+     * @default 0
+     */
     maxRetries?: number;
+    /**
+     * Maximum backoff time in seconds for exponential backoff.
+     * @default 30
+     */
     maxBackoffSeconds?: number;
+    /**
+     * Batch processing interval in seconds.
+     * @default 60
+     */
     every?: number;
 } : {
+    /**
+     * The name of the queue.
+     * @example "my-queue"
+     */
     qname: QueueName;
+    /** Maximum message size in bytes.
+     * @default 65536
+     */
     maxsize?: number;
+    /**
+     * Maximum number of retries for a message.
+     * `0` = no retry, `-1` = unlimited, `n` = max retries.
+     * @default 0
+     */
     maxRetries?: number;
+    /**
+     * Maximum backoff time in seconds for exponential backoff.
+     * @default 30
+     */
     maxBackoffSeconds?: number;
 };
+/**
+ * Attributes of a queue.
+ */
 export interface QueueAttributes {
+    /** Maximum message size in bytes. */
     maxsize: number;
+    /** Timestamp when the queue was created. */
     created: number;
+    /** Number of pending messages in the queue. */
     msgs: number;
+    /** Whether the queue is a batch queue. */
     isBatch: boolean;
+    /** Maximum number of retries for a message. */
     maxRetries: number;
+    /** Maximum backoff time in seconds for exponential backoff. */
     maxBackoffSeconds: number;
+    /** Batch processing interval in seconds (for batch queues only). */
     every?: number;
 }
+/**
+ * Options for sending a message to a regular queue.
+ */
 export interface SendMessageOptions {
+    /** The name of the queue. */
     qname: string;
+    /** The message content. */
     message: string;
+    /** Optional delay in milliseconds before the message is processed. */
     delay?: number;
 }
+/**
+ * Options for sending a message to a batch queue.
+ */
 export interface SendBatchMessageOptions {
+    /** The name of the batch queue. */
     qname: string;
+    /**
+     * The ID of the batch. Messages with the same `batchId` are processed together.
+     */
     batchId: string;
+    /** The message content. */
     message: string;
 }
+/**
+ * A message received from a regular queue.
+ */
 export interface Message {
+    /** The unique ID of the message. */
     id: string;
+    /** The message content. */
     message: string;
+    /** Timestamp when the message was sent. */
     sent: number;
+    /** The current attempt number (1-based). */
     attempt: number;
 }
+/**
+ * A batch of messages received from a batch queue.
+ */
 export interface BatchMessage {
+    /** The ID of the batch. */
     batchId: string;
+    /** Array of messages in the batch. */
     messages: Omit<Message, "attempt">[];
+    /** Timestamp when the batch was created. */
     sent: number;
+    /** The current attempt number for the batch (1-based). */
     attempt: number;
 }
+/**
+ * A lightweight, type-safe Redis-based message queue for Bun.
+ */
 export declare class RedisQ {
     private redis;
     private redisUrl;
@@ -59,14 +151,47 @@ export declare class RedisQ {
     private workers;
     private batchJobs;
     private isClosing;
+    /**
+     * Initializes the RedisQ client.
+     * @param options - Options for initializing the client.
+     */
     constructor(options: QueueOptions);
     private getKey;
     private isBatchQueue;
+    /**
+     * Creates a new queue with the specified options.
+     * @param options - Options for creating the queue.
+     * @returns `true` if the queue was created, `false` if it already exists.
+     */
     createQueue<QueueName extends string>(options: CreateQueueOptions<QueueName>): Promise<boolean>;
+    /**
+     * Lists all queue names.
+     * @returns An array of queue names.
+     */
     listQueues(): Promise<string[]>;
+    /**
+     * Gets the attributes of a queue.
+     * @param qname - The name of the queue.
+     * @returns The queue attributes, or `null` if the queue does not exist.
+     */
     getQueue(qname: string): Promise<QueueAttributes | null>;
+    /**
+     * Deletes a queue and all its data.
+     * @param qname - The name of the queue to delete.
+     * @returns `true` if the queue was deleted, `false` if it did not exist.
+     */
     deleteQueue(qname: string): Promise<boolean>;
+    /**
+     * Sends a message to a regular queue.
+     * @param options - Options for sending the message.
+     * @returns The unique ID of the message.
+     */
     sendMessage(options: SendMessageOptions): Promise<string>;
+    /**
+     * Sends a message to a batch queue.
+     * @param options - Options for sending the batch message.
+     * @returns The unique ID of the message.
+     */
     sendBatchMessage(options: SendBatchMessageOptions): Promise<string>;
     private encodeMessage;
     private decodeMessage;
@@ -74,12 +199,24 @@ export declare class RedisQ {
     private decodeBatchMeta;
     private fetchMessages;
     private fetchBatchMessage;
+    /**
+     * Manually deletes a message from the queue.
+     * @param qname - The name of the queue.
+     * @param id - The ID of the message to delete.
+     * @returns `true` if the message was deleted, `false` otherwise.
+     */
     deleteMessage(qname: string, id: string): Promise<boolean>;
     private deleteBatch;
     private retryMessage;
     private retryBatch;
     private processDelayedMessages;
     private processBatches;
+    /**
+     * Starts a worker to process messages from a queue.
+     * @param qname - The name of the queue.
+     * @param handler - The function to process messages.
+     * @param options - Options for the worker.
+     */
     startWorker<QueueName extends `${string}:batch` | (string & {})>(qname: QueueName, handler: (received: QueueName extends `${string}:batch` ? BatchMessage : Message) => Promise<{
         success: boolean;
     }>, options?: {
@@ -87,6 +224,13 @@ export declare class RedisQ {
         silent?: boolean;
     }): Promise<void>;
     private runWorker;
+    /**
+     * Stops a specific worker.
+     * @param qname - The name of the queue for which to stop the worker.
+     */
     stopWorker(qname: string): void;
+    /**
+     * Closes all workers and the Redis connection gracefully.
+     */
     close(): Promise<void>;
 }

package/dist/app.js

@@ -1,5 +1,8 @@
 import { RedisClient as BunRedisClient } from "bun";
 import { Cron } from "croner";
+/**
+ * A lightweight, type-safe Redis-based message queue for Bun.
+ */
 export class RedisQ {
     redis;
     redisUrl;
@@ -7,6 +10,10 @@ export class RedisQ {
     workers = new Map();
     batchJobs = new Map();
     isClosing = false;
+    /**
+     * Initializes the RedisQ client.
+     * @param options - Options for initializing the client.
+     */
     constructor(options) {
         if ("redis" in options) {
             this.redis = options.redis;
@@ -34,6 +41,11 @@ export class RedisQ {
     isBatchQueue(qname) {
         return qname.endsWith(":batch");
     }
+    /**
+     * Creates a new queue with the specified options.
+     * @param options - Options for creating the queue.
+     * @returns `true` if the queue was created, `false` if it already exists.
+     */
     async createQueue(options) {
         const { qname, maxsize = 65536, maxRetries = 0, maxBackoffSeconds = 30, } = options;
         if (!/^[a-zA-Z0-9_:-]{1,160}$/.test(qname)) {
@@ -58,6 +70,10 @@ export class RedisQ {
         await this.redis.hset(key, attrs);
         return true;
     }
+    /**
+     * Lists all queue names.
+     * @returns An array of queue names.
+     */
     async listQueues() {
         const pattern = `${this.ns}:*`;
         const keys = await this.redis.keys(pattern);
@@ -65,6 +81,11 @@ export class RedisQ {
             .map((k) => k.replace(`${this.ns}:`, ""))
             .filter((k) => !k.includes(":") || k.endsWith(":batch"));
     }
+    /**
+     * Gets the attributes of a queue.
+     * @param qname - The name of the queue.
+     * @returns The queue attributes, or `null` if the queue does not exist.
+     */
     async getQueue(qname) {
         const key = this.getKey(qname);
         const attrs = await this.redis.hgetall(key);
@@ -91,6 +112,11 @@ export class RedisQ {
         }
         return result;
     }
+    /**
+     * Deletes a queue and all its data.
+     * @param qname - The name of the queue to delete.
+     * @returns `true` if the queue was deleted, `false` if it did not exist.
+     */
     async deleteQueue(qname) {
         const pattern = `${this.ns}:${qname}*`;
         let cursor = "0";
@@ -105,6 +131,11 @@ export class RedisQ {
         } while (cursor !== "0");
         return keysFound;
     }
+    /**
+     * Sends a message to a regular queue.
+     * @param options - Options for sending the message.
+     * @returns The unique ID of the message.
+     */
     async sendMessage(options) {
         const { qname, message, delay } = options;
         if (this.isBatchQueue(qname)) {
@@ -147,6 +178,11 @@ export class RedisQ {
         }
         return id;
     }
+    /**
+     * Sends a message to a batch queue.
+     * @param options - Options for sending the batch message.
+     * @returns The unique ID of the message.
+     */
     async sendBatchMessage(options) {
         const { qname, batchId, message } = options;
         if (!this.isBatchQueue(qname)) {
@@ -256,6 +292,12 @@ export class RedisQ {
             sent: meta.sent,
         };
     }
+    /**
+     * Manually deletes a message from the queue.
+     * @param qname - The name of the queue.
+     * @param id - The ID of the message to delete.
+     * @returns `true` if the message was deleted, `false` otherwise.
+     */
     async deleteMessage(qname, id) {
         const messagesKey = this.getKey(qname, "messages");
         const deleted = await this.redis.hdel(messagesKey, id);
@@ -388,6 +430,12 @@ export class RedisQ {
         });
         await Promise.all(batchPromises);
     }
+    /**
+     * Starts a worker to process messages from a queue.
+     * @param qname - The name of the queue.
+     * @param handler - The function to process messages.
+     * @param options - Options for the worker.
+     */
     async startWorker(qname, handler, options = {}) {
         const { concurrency = 1, silent = false } = options;
         if (this.workers.has(qname)) {
@@ -462,6 +510,10 @@ export class RedisQ {
             }
         }
     }
+    /**
+     * Stops a specific worker.
+     * @param qname - The name of the queue for which to stop the worker.
+     */
     stopWorker(qname) {
         const controller = this.workers.get(qname);
         if (controller) {
@@ -474,6 +526,9 @@ export class RedisQ {
             this.batchJobs.delete(qname);
         }
     }
+    /**
+     * Closes all workers and the Redis connection gracefully.
+     */
     async close() {
         this.isClosing = true;
         for (const qname of this.workers.keys()) {

package/package.json

@@ -43,5 +43,5 @@
     },
     "type": "module",
     "types": "./dist/app.d.ts",
-    "version": "1.0.3"
+    "version": "1.0.4"
 }