flashq 0.1.0

package/dist/client/index.js

@@ -0,0 +1,829 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FlashQ = void 0;
+/**
+ * FlashQ Client - High-performance job queue client
+ *
+ * @example
+ * ```typescript
+ * import { FlashQ } from 'flashq';
+ *
+ * const client = new FlashQ();
+ *
+ * // Add a job (auto-connects!)
+ * const job = await client.add('emails', { to: 'user@example.com' });
+ *
+ * // That's it! No connect() needed.
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With options
+ * const client = new FlashQ({
+ *   host: 'localhost',
+ *   port: 6789,
+ *   token: 'secret'
+ * });
+ *
+ * // Add with job options
+ * await client.add('emails', { to: 'user@example.com' }, {
+ *   priority: 10,
+ *   delay: 5000,
+ *   max_attempts: 3
+ * });
+ * ```
+ */
+const connection_1 = require("./connection");
+const core = __importStar(require("./core"));
+const jobs = __importStar(require("./jobs"));
+const queue = __importStar(require("./queue"));
+const dlq = __importStar(require("./dlq"));
+const cron = __importStar(require("./cron"));
+const metrics = __importStar(require("./metrics"));
+const flows = __importStar(require("./flows"));
+const advanced = __importStar(require("./advanced"));
+const kv = __importStar(require("./kv"));
+const pubsub = __importStar(require("./pubsub"));
+/**
+ * FlashQ Client - High-performance job queue client with auto-connect.
+ */
+class FlashQ extends connection_1.FlashQConnection {
+    // ============== Core Operations ==============
+    /**
+     * Push a job to a queue.
+     *
+     * @param queue - Queue name
+     * @param data - Job data payload
+     * @param options - Push options (priority, delay, ttl, etc.)
+     * @returns Created job
+     *
+     * @example
+     * ```typescript
+     * const job = await client.push('emails', { to: 'user@example.com' });
+     * ```
+     */
+    push(queueName, data, options = {}) {
+        return core.push(this, queueName, data, options);
+    }
+    /**
+     * Add a job to a queue (alias for push).
+     *
+     * @param queue - Queue name
+     * @param data - Job data payload
+     * @param options - Push options
+     * @returns Created job
+     */
+    add(queueName, data, options = {}) {
+        return this.push(queueName, data, options);
+    }
+    /**
+     * Push multiple jobs to a queue in a single batch.
+     *
+     * @param queue - Queue name
+     * @param jobs - Array of jobs with data and options
+     * @returns Array of created job IDs
+     */
+    pushBatch(queueName, jobList) {
+        return core.pushBatch(this, queueName, jobList);
+    }
+    /**
+     * Add multiple jobs to a queue (alias for pushBatch).
+     */
+    addBulk(queueName, jobList) {
+        return this.pushBatch(queueName, jobList);
+    }
+    /**
+     * Pull a job from a queue (blocking with server-side timeout).
+     *
+     * @param queue - Queue name
+     * @param timeout - Server-side timeout in ms (default: 60s)
+     * @returns Job or null if timeout
+     */
+    pull(queueName, timeout) {
+        return core.pull(this, queueName, timeout);
+    }
+    /**
+     * Pull multiple jobs from a queue.
+     *
+     * @param queue - Queue name
+     * @param count - Number of jobs to pull
+     * @param timeout - Server-side timeout in ms (default: 60s)
+     * @returns Array of jobs
+     */
+    pullBatch(queueName, count, timeout) {
+        return core.pullBatch(this, queueName, count, timeout);
+    }
+    /**
+     * Acknowledge a job as completed.
+     *
+     * @param jobId - Job ID
+     * @param result - Optional result data
+     */
+    ack(jobId, result) {
+        return core.ack(this, jobId, result);
+    }
+    /**
+     * Acknowledge multiple jobs at once.
+     *
+     * @param jobIds - Array of job IDs
+     * @returns Number of jobs acknowledged
+     */
+    ackBatch(jobIds) {
+        return core.ackBatch(this, jobIds);
+    }
+    /**
+     * Fail a job (will retry or move to DLQ).
+     *
+     * @param jobId - Job ID
+     * @param error - Optional error message
+     */
+    fail(jobId, error) {
+        return core.fail(this, jobId, error);
+    }
+    // ============== Job Management ==============
+    /**
+     * Get a job with its current state.
+     *
+     * @param jobId - Job ID
+     * @returns Job with state, or null if not found
+     */
+    getJob(jobId) {
+        return jobs.getJob(this, jobId);
+    }
+    /**
+     * Get job state only.
+     *
+     * @param jobId - Job ID
+     * @returns Job state or null if not found
+     */
+    getState(jobId) {
+        return jobs.getState(this, jobId);
+    }
+    /**
+     * Get job result.
+     *
+     * @param jobId - Job ID
+     * @returns Job result or null
+     */
+    getResult(jobId) {
+        return jobs.getResult(this, jobId);
+    }
+    /**
+     * Wait for a job to complete and return its result.
+     *
+     * @param jobId - Job ID
+     * @param timeout - Timeout in ms (default: 30000)
+     * @returns Job result or null
+     * @throws Error if job fails or times out
+     */
+    finished(jobId, timeout) {
+        return jobs.finished(this, jobId, timeout);
+    }
+    /**
+     * Get a job by its custom ID.
+     *
+     * @param customId - Custom job ID
+     * @returns Job with state or null
+     */
+    getJobByCustomId(customId) {
+        return jobs.getJobByCustomId(this, customId);
+    }
+    /**
+     * Get multiple jobs by their IDs in a single call.
+     *
+     * @param jobIds - Array of job IDs
+     * @returns Array of jobs with states
+     */
+    getJobsBatch(jobIds) {
+        return jobs.getJobsBatch(this, jobIds);
+    }
+    /**
+     * Cancel a pending job.
+     *
+     * @param jobId - Job ID
+     */
+    cancel(jobId) {
+        return jobs.cancel(this, jobId);
+    }
+    /**
+     * Update job progress.
+     *
+     * @param jobId - Job ID
+     * @param progress - Progress value (0-100)
+     * @param message - Optional progress message
+     */
+    progress(jobId, progressValue, message) {
+        return jobs.progress(this, jobId, progressValue, message);
+    }
+    /**
+     * Get job progress.
+     *
+     * @param jobId - Job ID
+     * @returns Progress value and message
+     */
+    getProgress(jobId) {
+        return jobs.getProgress(this, jobId);
+    }
+    /**
+     * Add a log entry to a job.
+     *
+     * @param jobId - Job ID
+     * @param message - Log message
+     * @param level - Log level (info, warn, error)
+     */
+    log(jobId, message, level = 'info') {
+        return jobs.log(this, jobId, message, level);
+    }
+    /**
+     * Get log entries for a job.
+     *
+     * @param jobId - Job ID
+     * @returns Array of log entries
+     */
+    getLogs(jobId) {
+        return jobs.getLogs(this, jobId);
+    }
+    /**
+     * Send a heartbeat for a long-running job.
+     *
+     * @param jobId - Job ID
+     */
+    heartbeat(jobId) {
+        return jobs.heartbeat(this, jobId);
+    }
+    // ============== Queue Control ==============
+    /**
+     * Pause a queue.
+     *
+     * @param queue - Queue name
+     */
+    pause(queueName) {
+        return queue.pause(this, queueName);
+    }
+    /**
+     * Resume a paused queue.
+     *
+     * @param queue - Queue name
+     */
+    resume(queueName) {
+        return queue.resume(this, queueName);
+    }
+    /**
+     * Check if a queue is paused.
+     *
+     * @param queue - Queue name
+     * @returns true if paused
+     */
+    isPaused(queueName) {
+        return queue.isPaused(this, queueName);
+    }
+    /**
+     * Set rate limit for a queue (jobs per second).
+     *
+     * @param queue - Queue name
+     * @param limit - Jobs per second
+     */
+    setRateLimit(queueName, limit) {
+        return queue.setRateLimit(this, queueName, limit);
+    }
+    /**
+     * Clear rate limit for a queue.
+     *
+     * @param queue - Queue name
+     */
+    clearRateLimit(queueName) {
+        return queue.clearRateLimit(this, queueName);
+    }
+    /**
+     * Set concurrency limit for a queue.
+     *
+     * @param queue - Queue name
+     * @param limit - Max concurrent jobs
+     */
+    setConcurrency(queueName, limit) {
+        return queue.setConcurrency(this, queueName, limit);
+    }
+    /**
+     * Clear concurrency limit for a queue.
+     *
+     * @param queue - Queue name
+     */
+    clearConcurrency(queueName) {
+        return queue.clearConcurrency(this, queueName);
+    }
+    /**
+     * List all queues.
+     *
+     * @returns Array of queue info
+     */
+    listQueues() {
+        return queue.listQueues(this);
+    }
+    // ============== Dead Letter Queue ==============
+    /**
+     * Get jobs from the dead letter queue.
+     *
+     * @param queue - Queue name
+     * @param count - Max jobs to return (default: 100)
+     * @returns Array of failed jobs
+     */
+    getDlq(queueName, count = 100) {
+        return dlq.getDlq(this, queueName, count);
+    }
+    /**
+     * Retry jobs from the dead letter queue.
+     *
+     * @param queue - Queue name
+     * @param jobId - Optional specific job ID to retry
+     * @returns Number of jobs retried
+     */
+    retryDlq(queueName, jobId) {
+        return dlq.retryDlq(this, queueName, jobId);
+    }
+    /**
+     * Purge all jobs from the dead letter queue.
+     *
+     * @param queue - Queue name
+     * @returns Number of jobs purged
+     */
+    purgeDlq(queueName) {
+        return dlq.purgeDlq(this, queueName);
+    }
+    // ============== Cron Jobs ==============
+    /**
+     * Add a cron job for scheduled recurring tasks.
+     *
+     * @param name - Unique cron job name
+     * @param options - Cron options
+     */
+    addCron(name, options) {
+        return cron.addCron(this, name, options);
+    }
+    /**
+     * Delete a cron job.
+     *
+     * @param name - Cron job name
+     * @returns true if deleted
+     */
+    deleteCron(name) {
+        return cron.deleteCron(this, name);
+    }
+    /**
+     * List all cron jobs.
+     *
+     * @returns Array of cron jobs
+     */
+    listCrons() {
+        return cron.listCrons(this);
+    }
+    // ============== Stats & Metrics ==============
+    /**
+     * Get queue statistics.
+     *
+     * @returns Queue stats
+     */
+    stats() {
+        return metrics.stats(this);
+    }
+    /**
+     * Get detailed metrics.
+     *
+     * @returns Detailed metrics object
+     */
+    metrics() {
+        return metrics.metrics(this);
+    }
+    // ============== Flows ==============
+    /**
+     * Push a flow (parent job with children).
+     *
+     * @param queue - Parent queue name
+     * @param parentData - Parent job data
+     * @param children - Array of child jobs
+     * @param options - Flow options
+     * @returns Parent and children IDs
+     */
+    pushFlow(queueName, parentData, children, options = {}) {
+        return flows.pushFlow(this, queueName, parentData, children, options);
+    }
+    /**
+     * Get children job IDs for a parent job in a flow.
+     *
+     * @param jobId - Parent job ID
+     * @returns Array of children job IDs
+     */
+    getChildren(jobId) {
+        return flows.getChildren(this, jobId);
+    }
+    // ============== BullMQ Advanced Features ==============
+    /**
+     * Get jobs filtered by queue and/or state with pagination.
+     *
+     * @param options - Filter options
+     * @returns Jobs and total count
+     */
+    getJobs(options = {}) {
+        return advanced.getJobs(this, options);
+    }
+    /**
+     * Get job counts by state for a queue.
+     *
+     * @param queue - Queue name
+     * @returns Counts by state
+     */
+    getJobCounts(queueName) {
+        return advanced.getJobCounts(this, queueName);
+    }
+    /**
+     * Get total count of jobs in a queue (waiting + delayed).
+     *
+     * @param queue - Queue name
+     * @returns Total job count
+     */
+    count(queueName) {
+        return advanced.count(this, queueName);
+    }
+    /**
+     * Clean jobs older than grace period by state.
+     *
+     * @param queue - Queue name
+     * @param grace - Grace period in ms
+     * @param state - Job state to clean
+     * @param limit - Optional max jobs to clean
+     * @returns Number of jobs cleaned
+     */
+    clean(queueName, grace, state, limit) {
+        return advanced.clean(this, queueName, grace, state, limit);
+    }
+    /**
+     * Drain all waiting jobs from a queue.
+     *
+     * @param queue - Queue name
+     * @returns Number of jobs drained
+     */
+    drain(queueName) {
+        return advanced.drain(this, queueName);
+    }
+    /**
+     * Remove ALL data for a queue.
+     *
+     * @param queue - Queue name
+     * @returns Total items removed
+     */
+    obliterate(queueName) {
+        return advanced.obliterate(this, queueName);
+    }
+    /**
+     * Change job priority.
+     *
+     * @param jobId - Job ID
+     * @param priority - New priority
+     */
+    changePriority(jobId, priority) {
+        return advanced.changePriority(this, jobId, priority);
+    }
+    /**
+     * Move job from processing back to delayed.
+     *
+     * @param jobId - Job ID
+     * @param delay - Delay in ms
+     */
+    moveToDelayed(jobId, delay) {
+        return advanced.moveToDelayed(this, jobId, delay);
+    }
+    /**
+     * Promote delayed job to waiting immediately.
+     *
+     * @param jobId - Job ID
+     */
+    promote(jobId) {
+        return advanced.promote(this, jobId);
+    }
+    /**
+     * Update job data.
+     *
+     * @param jobId - Job ID
+     * @param data - New data payload
+     */
+    update(jobId, data) {
+        return advanced.update(this, jobId, data);
+    }
+    /**
+     * Discard job - move directly to DLQ.
+     *
+     * @param jobId - Job ID
+     */
+    discard(jobId) {
+        return advanced.discard(this, jobId);
+    }
+    // ============== Event Subscriptions ==============
+    /**
+     * Subscribe to real-time events via SSE.
+     *
+     * @param queue - Optional queue to filter events
+     * @returns EventSubscriber instance
+     *
+     * @example
+     * ```typescript
+     * const events = client.subscribe();
+     * events.on('completed', (e) => console.log(`Job ${e.jobId} completed`));
+     * await events.connect();
+     * ```
+     */
+    subscribe(queueName) {
+        const { EventSubscriber } = require('../events');
+        return new EventSubscriber({
+            host: this.options.host,
+            httpPort: this.options.httpPort,
+            token: this.options.token,
+            queue: queueName,
+            type: 'sse',
+        });
+    }
+    /**
+     * Subscribe to real-time events via WebSocket.
+     *
+     * @param queue - Optional queue to filter events
+     * @returns EventSubscriber instance
+     */
+    subscribeWs(queueName) {
+        const { EventSubscriber } = require('../events');
+        return new EventSubscriber({
+            host: this.options.host,
+            httpPort: this.options.httpPort,
+            token: this.options.token,
+            queue: queueName,
+            type: 'websocket',
+        });
+    }
+    // ============== Key-Value Storage (Redis-like) ==============
+    /**
+     * Set a key-value pair.
+     *
+     * @param key - Key name
+     * @param value - Value (any JSON-serializable data)
+     * @param options - Optional TTL settings
+     *
+     * @example
+     * ```typescript
+     * await client.kvSet('user:123', { name: 'John' });
+     * await client.kvSet('session:abc', { token: 'xyz' }, { ttl: 3600000 }); // 1 hour TTL
+     * ```
+     */
+    kvSet(key, value, options = {}) {
+        return kv.set(this, key, value, options);
+    }
+    /**
+     * Get a value by key.
+     *
+     * @param key - Key name
+     * @returns Value or null if not found/expired
+     *
+     * @example
+     * ```typescript
+     * const user = await client.kvGet<User>('user:123');
+     * ```
+     */
+    kvGet(key) {
+        return kv.get(this, key);
+    }
+    /**
+     * Delete a key.
+     *
+     * @param key - Key name
+     * @returns true if key existed
+     */
+    kvDel(key) {
+        return kv.del(this, key);
+    }
+    /**
+     * Check if a key exists.
+     *
+     * @param key - Key name
+     * @returns true if key exists and not expired
+     */
+    kvExists(key) {
+        return kv.exists(this, key);
+    }
+    /**
+     * Set TTL on an existing key.
+     *
+     * @param key - Key name
+     * @param ttl - Time-to-live in milliseconds
+     * @returns true if key existed
+     */
+    kvExpire(key, ttl) {
+        return kv.expire(this, key, ttl);
+    }
+    /**
+     * Get remaining TTL for a key.
+     *
+     * @param key - Key name
+     * @returns ms remaining, -1 if no TTL, -2 if key doesn't exist
+     */
+    kvTtl(key) {
+        return kv.ttl(this, key);
+    }
+    /**
+     * Get multiple values by keys (batch operation).
+     *
+     * @param keys - Array of keys
+     * @returns Array of values (null for missing keys)
+     *
+     * @example
+     * ```typescript
+     * const [user1, user2, user3] = await client.kvMget<User>(['user:1', 'user:2', 'user:3']);
+     * ```
+     */
+    kvMget(keys) {
+        return kv.mget(this, keys);
+    }
+    /**
+     * Set multiple key-value pairs (batch operation).
+     *
+     * @param entries - Array of {key, value, ttl?}
+     * @returns Number of keys set
+     *
+     * @example
+     * ```typescript
+     * await client.kvMset([
+     *   { key: 'user:1', value: { name: 'Alice' } },
+     *   { key: 'user:2', value: { name: 'Bob' }, ttl: 60000 },
+     * ]);
+     * ```
+     */
+    kvMset(entries) {
+        return kv.mset(this, entries);
+    }
+    /**
+     * List keys matching a pattern.
+     *
+     * @param pattern - Glob pattern (* = any, ? = one char)
+     * @returns Array of matching keys
+     *
+     * @example
+     * ```typescript
+     * const userKeys = await client.kvKeys('user:*');
+     * const sessionKeys = await client.kvKeys('session:???');
+     * ```
+     */
+    kvKeys(pattern) {
+        return kv.keys(this, pattern);
+    }
+    /**
+     * Increment a numeric value atomically.
+     *
+     * @param key - Key name
+     * @param by - Amount to increment (default: 1)
+     * @returns New value
+     *
+     * @example
+     * ```typescript
+     * const views = await client.kvIncr('page:views');
+     * const score = await client.kvIncr('user:123:score', 10);
+     * ```
+     */
+    kvIncr(key, by = 1) {
+        return kv.incr(this, key, by);
+    }
+    /**
+     * Decrement a numeric value atomically.
+     *
+     * @param key - Key name
+     * @param by - Amount to decrement (default: 1)
+     * @returns New value
+     */
+    kvDecr(key, by = 1) {
+        return kv.decr(this, key, by);
+    }
+    // ============== Pub/Sub (Redis-like) ==============
+    /**
+     * Publish a message to a channel.
+     *
+     * @param channel - Channel name
+     * @param message - Message data (any JSON-serializable data)
+     * @returns Number of subscribers that received the message
+     *
+     * @example
+     * ```typescript
+     * const receivers = await client.publish('notifications', { type: 'alert', text: 'Hello!' });
+     * console.log(`Message sent to ${receivers} subscribers`);
+     * ```
+     */
+    publish(channel, message) {
+        return pubsub.publish(this, channel, message);
+    }
+    /**
+     * Subscribe to channels.
+     * Note: For real-time message delivery, use WebSocket/SSE connections.
+     *
+     * @param channels - Array of channel names
+     * @returns List of subscribed channels
+     *
+     * @example
+     * ```typescript
+     * await client.pubsubSubscribe(['notifications', 'alerts']);
+     * ```
+     */
+    pubsubSubscribe(channels) {
+        return pubsub.subscribe(this, channels);
+    }
+    /**
+     * Subscribe to channels matching patterns (e.g., "events:*").
+     *
+     * @param patterns - Array of glob patterns
+     * @returns List of subscribed patterns
+     *
+     * @example
+     * ```typescript
+     * await client.pubsubPsubscribe(['events:*', 'logs:*']);
+     * ```
+     */
+    pubsubPsubscribe(patterns) {
+        return pubsub.psubscribe(this, patterns);
+    }
+    /**
+     * Unsubscribe from channels.
+     *
+     * @param channels - Array of channel names
+     * @returns List of unsubscribed channels
+     */
+    pubsubUnsubscribe(channels) {
+        return pubsub.unsubscribe(this, channels);
+    }
+    /**
+     * Unsubscribe from patterns.
+     *
+     * @param patterns - Array of patterns
+     * @returns List of unsubscribed patterns
+     */
+    pubsubPunsubscribe(patterns) {
+        return pubsub.punsubscribe(this, patterns);
+    }
+    /**
+     * List active channels (optionally matching a pattern).
+     *
+     * @param pattern - Optional glob pattern
+     * @returns Array of active channel names
+     *
+     * @example
+     * ```typescript
+     * const allChannels = await client.pubsubChannels();
+     * const eventChannels = await client.pubsubChannels('events:*');
+     * ```
+     */
+    pubsubChannels(pattern) {
+        return pubsub.channels(this, pattern);
+    }
+    /**
+     * Get subscriber counts for channels.
+     *
+     * @param channels - Array of channel names
+     * @returns Array of [channel, count] tuples
+     *
+     * @example
+     * ```typescript
+     * const counts = await client.pubsubNumsub(['notifications', 'alerts']);
+     * // [['notifications', 5], ['alerts', 2]]
+     * ```
+     */
+    pubsubNumsub(channels) {
+        return pubsub.numsub(this, channels);
+    }
+}
+exports.FlashQ = FlashQ;
+exports.default = FlashQ;
+//# sourceMappingURL=index.js.map