@gravito/stream 1.0.3 → 2.0.1

package/dist/index.d.ts

@@ -1,4 +1,6 @@
+import { EventEmitter } from 'node:events';
 import { GravitoOrbit, PlanetCore } from '@gravito/core';
+import { ConnectionContract } from '@gravito/atlas';
 
 /**
  * Represents a job that has been serialized for storage in a queue.
@@ -8,7 +10,7 @@ interface SerializedJob {
     /** Unique job identifier */
     id: string;
     /** Serializer type: 'json' for plain objects or 'class' for instances */
-    type: 'json' | 'class';
+    type: 'json' | 'class' | 'msgpack';
     /** Serialized data string */
     data: string;
     /** Fully qualified class name (only used for 'class' type) */
@@ -34,6 +36,24 @@ interface SerializedJob {
     /** Optional priority for the job (string or numeric) */
     priority?: string | number;
 }
+/**
+ * Statistics for a single queue.
+ * @public
+ */
+interface QueueStats {
+    /** Queue name */
+    queue: string;
+    /** Number of pending jobs */
+    size: number;
+    /** Number of delayed jobs (if supported) */
+    delayed?: number;
+    /** Number of reserved/in-flight jobs (if supported) */
+    reserved?: number;
+    /** Number of failed jobs in DLQ (if supported) */
+    failed?: number;
+    /** Additional custom metrics */
+    metrics?: Record<string, number>;
+}
 /**
  * Advanced topic options for distributed queues (e.g., Kafka).
  * @public
@@ -46,16 +66,73 @@ interface TopicOptions {
     /** Additional driver-specific configurations */
     config?: Record<string, string>;
 }
+/**
+ * Database driver configuration.
+ * @public
+ */
+interface DatabaseDriverConfig$1 {
+    driver: 'database';
+    /** Database service implementation for executing queries */
+    dbService: any;
+    /** Optional table name for job storage */
+    table?: string;
+}
+/**
+ * Redis driver configuration.
+ * @public
+ */
+interface RedisDriverConfig$1 {
+    driver: 'redis';
+    /** Redis client instance (ioredis or node-redis compatible) */
+    client: any;
+    /** Optional prefix for all Redis keys */
+    prefix?: string;
+}
+/**
+ * Kafka driver configuration.
+ */
+interface KafkaDriverConfig$1 {
+    driver: 'kafka';
+    client: any;
+    consumerGroupId?: string;
+}
+/**
+ * SQS driver configuration.
+ * @public
+ */
+interface SQSDriverConfig$1 {
+    driver: 'sqs';
+    /** Amazon SQS client instance */
+    client: any;
+    /** Optional prefix for queue URLs */
+    queueUrlPrefix?: string;
+    /** The duration (in seconds) that the received messages are hidden from subsequent retrieve requests after being retrieved by a ReceiveMessage request. */
+    visibilityTimeout?: number;
+    /** The duration (in seconds) for which the call waits for a message to arrive in the queue before returning. */
+    waitTimeSeconds?: number;
+}
+/**
+ * RabbitMQ driver configuration.
+ */
+interface RabbitMQDriverConfig$1 {
+    driver: 'rabbitmq';
+    client: any;
+    exchange?: string;
+    exchangeType?: string;
+}
 /**
  * Configuration for a specific queue connection.
  * @public
  */
-interface QueueConnectionConfig {
-    /** The driver type to use for this connection */
-    driver: 'memory' | 'database' | 'redis' | 'kafka' | 'sqs' | 'rabbitmq' | 'nats';
-    /** Driver-specific settings (e.g., connection string, table name) */
+type QueueConnectionConfig = {
+    driver: 'memory';
+} | DatabaseDriverConfig$1 | RedisDriverConfig$1 | KafkaDriverConfig$1 | SQSDriverConfig$1 | RabbitMQDriverConfig$1 | {
+    driver: 'nats';
     [key: string]: unknown;
-}
+} | {
+    driver: string;
+    [key: string]: unknown;
+};
 /**
  * Queue manager config.
  */
@@ -71,7 +148,18 @@ interface QueueConfig {
     /**
      * Default serializer type.
      */
-    defaultSerializer?: 'json' | 'class';
+    defaultSerializer?: 'json' | 'class' | 'msgpack';
+    /**
+     * Whether to enable serialization caching.
+     * If true, re-queuing the same Job instance will use the cached serialized data.
+     * @default false
+     */
+    useSerializationCache?: boolean;
+    /**
+     * Enable verbose debug logging for QueueManager and Consumer.
+     * @default false
+     */
+    debug?: boolean;
     /**
      * Persistence configuration (SQL Archive).
      */
@@ -93,6 +181,16 @@ interface QueueConfig {
          * @default false
          */
         archiveEnqueued?: boolean;
+        /**
+         * Buffer size for batched writes.
+         * If set, wraps the adapter in BufferedPersistence.
+         */
+        bufferSize?: number;
+        /**
+         * Flush interval in ms for batched writes.
+         * If set, wraps the adapter in BufferedPersistence.
+         */
+        flushInterval?: number;
     };
 }
 /**
@@ -108,9 +206,6 @@ interface PersistenceAdapter {
      * Find a job in the archive.
      */
     find(queue: string, id: string): Promise<SerializedJob | null>;
-    /**
-     * List jobs from the archive.
-     */
     /**
      * List jobs from the archive.
      */
@@ -122,10 +217,22 @@ interface PersistenceAdapter {
         startTime?: Date;
         endTime?: Date;
     }): Promise<SerializedJob[]>;
+    /**
+     * Archive multiple jobs (batch write).
+     */
+    archiveMany?(jobs: Array<{
+        queue: string;
+        job: SerializedJob;
+        status: 'completed' | 'failed' | 'waiting' | string;
+    }>): Promise<void>;
     /**
      * Remove old data from the archive.
      */
     cleanup(days: number): Promise<number>;
+    /**
+     * Flush any buffered data.
+     */
+    flush?(): Promise<void>;
     /**
      * Count jobs in the archive.
      */
@@ -145,6 +252,16 @@ interface PersistenceAdapter {
         queue?: string;
         timestamp: Date;
     }): Promise<void>;
+    /**
+     * Archive multiple log messages (batch write).
+     */
+    archiveLogMany?(logs: Array<{
+        level: string;
+        message: string;
+        workerId: string;
+        queue?: string;
+        timestamp: Date;
+    }>): Promise<void>;
     /**
      * List system logs from the archive.
      */
@@ -232,6 +349,13 @@ interface QueueDriver {
      * @returns Serialized job, or `null` if the queue is empty
      */
     pop(queue: string): Promise<SerializedJob | null>;
+    /**
+     * Pop a job from a queue (blocking).
+     * @param queues - Queue name or array of queue names
+     * @param timeout - Timeout in seconds
+     * @returns Serialized job, or `null` if timeout reached
+     */
+    popBlocking?(queues: string | string[], timeout: number): Promise<SerializedJob | null>;
     /**
      * Mark a job as completed (used for FIFO/Group handling).
      * @param queue - Queue name
@@ -255,6 +379,11 @@ interface QueueDriver {
      * @param job - Serialized job with error info
      */
     fail?(queue: string, job: SerializedJob): Promise<void>;
+    /**
+     * Get queue statistics including pending, delayed, and failed job counts.
+     * @param queue - Queue name
+     */
+    stats?(queue: string): Promise<QueueStats>;
     /**
      * Push multiple jobs (optional, higher throughput).
      * @param queue - Queue name
@@ -295,13 +424,30 @@ interface QueueDriver {
      * @param workerInfo - Worker information
      * @param prefix - Optional prefix for monitoring keys
      */
-    reportHeartbeat?(workerInfo: any, prefix?: string): Promise<void>;
+    reportHeartbeat?(workerInfo: {
+        id: string;
+        status: string;
+        hostname: string;
+        pid: number;
+        uptime: number;
+        last_ping: string;
+        queues: string[];
+        metrics?: Record<string, any>;
+        [key: string]: any;
+    }, prefix?: string): Promise<void>;
     /**
      * Publish a log message for monitoring.
      * @param logPayload - Log payload
      * @param prefix - Optional prefix for monitoring channels/keys
      */
-    publishLog?(logPayload: any, prefix?: string): Promise<void>;
+    publishLog?(logPayload: {
+        level: string;
+        message: string;
+        workerId: string;
+        jobId?: string;
+        timestamp: string;
+        [key: string]: any;
+    }, prefix?: string): Promise<void>;
     /**
      * Check if a queue is rate limited.
      * @param queue - Queue name
@@ -431,6 +577,7 @@ interface Queueable {
  *   .onQueue('emails')
  *   .delay(60)
  * ```
+ * @public
  */
 declare abstract class Job implements Queueable {
     /**
@@ -519,6 +666,78 @@ declare abstract class Job implements Queueable {
     failed(_error: Error): Promise<void>;
 }
 
+/**
+ * Configuration for a recurring scheduled job.
+ *
+ * @public
+ * @since 3.0.0
+ */
+interface ScheduledJobConfig {
+    /** Unique identifier for the scheduled task. */
+    id: string;
+    /** Cron expression defining the schedule (e.g., '* * * * *'). */
+    cron: string;
+    /** The target queue name where the job should be pushed. */
+    queue: string;
+    /** The serialized job data. */
+    job: SerializedJob;
+    /** Timestamp of the last successful execution in milliseconds. */
+    lastRun?: number;
+    /** Timestamp of the next scheduled execution in milliseconds. */
+    nextRun?: number;
+    /** Whether the scheduled job is active. */
+    enabled: boolean;
+}
+/**
+ * Scheduler manages recurring (cron) jobs in Gravito.
+ *
+ * It uses Redis to store schedule metadata and coordinates distributed
+ * execution using locks to ensure jobs are triggered exactly once per interval.
+ *
+ * @example
+ * ```typescript
+ * const scheduler = new Scheduler(queueManager);
+ * await scheduler.register({
+ *   id: 'daily-cleanup',
+ *   cron: '0 0 * * *',
+ *   queue: 'default',
+ *   job: myJob.serialize()
+ * });
+ * ```
+ *
+ * @public
+ * @since 3.0.0
+ */
+declare class Scheduler {
+    private manager;
+    private prefix;
+    constructor(manager: QueueManager, options?: {
+        prefix?: string;
+    });
+    private get client();
+    /**
+     * Register a scheduled job.
+     */
+    register(config: Omit<ScheduledJobConfig, 'nextRun' | 'enabled'>): Promise<void>;
+    /**
+     * Remove a scheduled job.
+     */
+    remove(id: string): Promise<void>;
+    /**
+     * List all scheduled jobs.
+     */
+    list(): Promise<ScheduledJobConfig[]>;
+    /**
+     * Run a scheduled job immediately (out of schedule).
+     */
+    runNow(id: string): Promise<void>;
+    /**
+     * Process due tasks (TICK).
+     * This should be called periodically (e.g. every minute).
+     */
+    tick(): Promise<number>;
+}
+
 /**
  * Job serializer interface.
  *
@@ -579,13 +798,18 @@ declare class QueueManager {
     private defaultSerializer;
     private persistence?;
     private scheduler?;
+    private debug;
     constructor(config?: QueueConfig);
+    /**
+     * Log debug message.
+     */
+    private log;
     /**
      * Register a connection.
      * @param name - Connection name
      * @param config - Connection config
      */
-    registerConnection(name: string, config: unknown): void;
+    registerConnection(name: string, config: QueueConnectionConfig): void;
     /**
      * Get a driver for a connection.
      * @param connection - Connection name
@@ -627,13 +851,17 @@ declare class QueueManager {
      *
      * @template T - The type of the jobs.
      * @param jobs - Array of job instances.
+     * @param options - Bulk push options.
      *
      * @example
      * ```typescript
-     * await manager.pushMany([new JobA(), new JobB()]);
+     * await manager.pushMany(jobs, { batchSize: 500, concurrency: 2 });
      * ```
      */
-    pushMany<T extends Job & Queueable>(jobs: T[]): Promise<void>;
+    pushMany<T extends Job & Queueable>(jobs: T[], options?: {
+        batchSize?: number;
+        concurrency?: number;
+    }): Promise<void>;
     /**
      * Pop a job from the queue.
      *
@@ -648,6 +876,15 @@ declare class QueueManager {
      * ```
      */
     pop(queue?: string, connection?: string): Promise<Job | null>;
+    /**
+     * Pop multiple jobs from the queue.
+     *
+     * @param queue - Queue name (default: 'default').
+     * @param count - Number of jobs to pop (default: 10).
+     * @param connection - Connection name (optional).
+     * @returns Array of Job instances.
+     */
+    popMany(queue?: string, count?: number, connection?: string): Promise<Job[]>;
     /**
      * Get queue size.
      *
@@ -656,6 +893,14 @@ declare class QueueManager {
      * @returns Number of jobs in the queue.
      */
     size(queue?: string, connection?: string): Promise<number>;
+    /**
+     * Pop a job from the queue (blocking).
+     *
+     * @param queue - Queue name (default: 'default').
+     * @param timeout - Timeout in seconds (default: 0, wait forever).
+     * @param connection - Connection name (optional).
+     */
+    popBlocking(queues?: string | string[], timeout?: number, connection?: string): Promise<Job | null>;
     /**
      * Clear all jobs from a queue.
      *
@@ -663,6 +908,14 @@ declare class QueueManager {
      * @param connection - Connection name (optional).
      */
     clear(queue?: string, connection?: string): Promise<void>;
+    /**
+     * Get queue statistics including size, delayed, and failed job counts.
+     *
+     * @param queue - Queue name (default: 'default').
+     * @param connection - Connection name (optional).
+     * @returns Queue statistics object.
+     */
+    stats(queue?: string, connection?: string): Promise<QueueStats>;
     /**
      * Mark a job as completed.
      * @param job - Job instance
@@ -677,11 +930,11 @@ declare class QueueManager {
     /**
      * Get the persistence adapter if configured.
      */
-    getPersistence(): any;
+    getPersistence(): PersistenceAdapter | undefined;
     /**
      * Get the scheduler if configured.
      */
-    getScheduler(): any;
+    getScheduler(): Scheduler;
     /**
      * Get failed jobs from DLQ (if driver supports it).
      */
@@ -778,7 +1031,7 @@ interface ConsumerOptions {
         /**
          * Extra info to report with heartbeat.
          */
-        extraInfo?: Record<string, any>;
+        extraInfo?: Record<string, unknown>;
         /**
          * Prefix for monitoring keys/channels.
          */
@@ -792,6 +1045,54 @@ interface ConsumerOptions {
         max: number;
         duration: number;
     }>;
+    /**
+     * Max concurrent jobs to process. Default: 1.
+     */
+    concurrency?: number;
+    /**
+     * Whether to process jobs with the same groupId sequentially.
+     * If true, jobs with the same groupId will never run concurrently,
+     * regardless of the global concurrency setting.
+     * @default true
+     */
+    groupJobsSequential?: boolean;
+    /**
+     * Minimum polling interval in ms (for adaptive polling).
+     * @default 100
+     */
+    minPollInterval?: number;
+    /**
+     * Maximum polling interval in ms (for adaptive polling).
+     * @default 5000
+     */
+    maxPollInterval?: number;
+    /**
+     * Backoff multiplier for adaptive polling.
+     * @default 1.5
+     */
+    backoffMultiplier?: number;
+    /**
+     * Batch size for consuming jobs.
+     * If > 1, tries to fetch multiple jobs at once.
+     * @default 1
+     */
+    batchSize?: number;
+    /**
+     * Whether to use blocking pop (BLPOP/long-polling) if supported by driver.
+     * Only applies when batchSize is 1.
+     * @default true
+     */
+    useBlocking?: boolean;
+    /**
+     * Timeout in seconds for blocking pop.
+     * @default 5
+     */
+    blockingTimeout?: number;
+    /**
+     * Enable verbose debug logging.
+     * @default false
+     */
+    debug?: boolean;
 }
 /**
  * Consumer
@@ -812,20 +1113,40 @@ interface ConsumerOptions {
  * // Standalone mode (CLI)
  * // Start via CLI tooling with graceful shutdown
  * ```
+ *
+ * @emits job:started - When a job begins processing. Payload: { job: Job, queue: string }
+ * @emits job:processed - When a job completes successfully. Payload: { job: Job, duration: number, queue: string }
+ * @emits job:failed - When a job fails an attempt. Payload: { job: Job, error: Error, duration: number, queue: string }
+ * @emits job:retried - When a job is scheduled for a retry. Payload: { job: Job, attempt: number, delay: number }
+ * @emits job:failed_permanently - When a job fails all attempts and is moved to DLQ. Payload: { job: Job, error: Error }
  */
-declare class Consumer {
+declare class Consumer extends EventEmitter {
     private queueManager;
     private options;
     private running;
     private stopRequested;
     private workerId;
     private heartbeatTimer;
+    private groupLimiters;
+    private stats;
     constructor(queueManager: QueueManager, options: ConsumerOptions);
     private get connectionName();
+    /**
+     * Log debug message.
+     */
+    private log;
     /**
      * Start the consumer loop.
      */
     start(): Promise<void>;
+    /**
+     * Run a job with concurrency controls.
+     */
+    private runJob;
+    /**
+     * Handle a single job.
+     */
+    private handleJob;
     private startHeartbeat;
     private stopHeartbeat;
     private publishLog;
@@ -837,6 +1158,19 @@ declare class Consumer {
      * Check whether the consumer is running.
      */
     isRunning(): boolean;
+    /**
+     * Get current consumer statistics.
+     */
+    getStats(): {
+        processed: number;
+        failed: number;
+        retried: number;
+        active: number;
+    };
+    /**
+     * Reset statistics counters.
+     */
+    resetStats(): void;
 }
 
 /**
@@ -899,6 +1233,14 @@ declare class DatabaseDriver implements QueueDriver {
      * Pop a job from the queue (FIFO, with delay support).
      */
     pop(queue: string): Promise<SerializedJob | null>;
+    /**
+     * Pop multiple jobs from the queue.
+     */
+    popMany(queue: string, count: number): Promise<SerializedJob[]>;
+    /**
+     * Get queue statistics.
+     */
+    stats(queue: string): Promise<QueueStats>;
     /**
      * Get queue size.
      */
@@ -907,8 +1249,14 @@ declare class DatabaseDriver implements QueueDriver {
      * Clear a queue.
      */
     clear(queue: string): Promise<void>;
+    /**
+     * Pop a job from the queue (blocking).
+     * Simple polling fallback for databases.
+     */
+    popBlocking(queue: string, timeout: number): Promise<SerializedJob | null>;
     /**
      * Push multiple jobs.
+     * Optimizes by using a single multi-row insert if possible.
      */
     pushMany(queue: string, jobs: SerializedJob[]): Promise<void>;
     /**
@@ -1053,6 +1401,13 @@ declare class KafkaDriver implements QueueDriver {
     subscribe(queue: string, callback: (job: SerializedJob) => Promise<void>): Promise<void>;
 }
 
+interface MemoryDriverConfig {
+    /**
+     * Maximum number of jobs per queue.
+     * @default Infinity
+     */
+    maxSize?: number;
+}
 /**
  * Memory Driver
  *
@@ -1063,13 +1418,15 @@ declare class KafkaDriver implements QueueDriver {
  *
  * @example
  * ```typescript
- * const driver = new MemoryDriver()
+ * const driver = new MemoryDriver({ maxSize: 1000 })
  * await driver.push('default', serializedJob)
  * const job = await driver.pop('default')
  * ```
  */
 declare class MemoryDriver implements QueueDriver {
     private queues;
+    private maxSize;
+    constructor(config?: MemoryDriverConfig);
     /**
      * Push a job to a queue.
      */
@@ -1086,6 +1443,14 @@ declare class MemoryDriver implements QueueDriver {
      * Clear a queue.
      */
     clear(queue: string): Promise<void>;
+    /**
+     * Mark a job as permanently failed.
+     */
+    fail(queue: string, job: SerializedJob): Promise<void>;
+    /**
+     * Get queue statistics.
+     */
+    stats(queue: string): Promise<QueueStats>;
     /**
      * Push multiple jobs.
      */
@@ -1154,6 +1519,11 @@ declare class RabbitMQDriver implements QueueDriver {
      * Pop a job (get).
      */
     pop(queue: string): Promise<SerializedJob | null>;
+    /**
+     * Pop multiple jobs.
+     * Uses channel.get() in a loop (no native batch get in AMQP).
+     */
+    popMany(queue: string, count: number): Promise<SerializedJob[]>;
     /**
      * Acknowledge a message.
      */
@@ -1171,6 +1541,7 @@ declare class RabbitMQDriver implements QueueDriver {
      */
     subscribe(queue: string, callback: (job: SerializedJob) => Promise<void>, options?: {
         autoAck?: boolean;
+        prefetch?: number;
     }): Promise<void>;
     /**
      * Get queue size.
@@ -1182,6 +1553,34 @@ declare class RabbitMQDriver implements QueueDriver {
     clear(queue: string): Promise<void>;
 }
 
+/**
+ * Interface for Redis clients (compatible with ioredis and node-redis).
+ */
+interface RedisClient {
+    lpush(key: string, ...values: string[]): Promise<number>;
+    rpop(key: string, count?: number): Promise<string | string[] | null>;
+    llen(key: string): Promise<number>;
+    del(key: string, ...keys: string[]): Promise<number>;
+    lpushx?(key: string, ...values: string[]): Promise<number>;
+    rpoplpush?(src: string, dst: string): Promise<string | null>;
+    zadd?(key: string, score: number, member: string): Promise<number>;
+    zrange?(key: string, start: number, end: number, ...args: string[]): Promise<string[]>;
+    zrem?(key: string, ...members: string[]): Promise<number>;
+    get?(key: string): Promise<string | null>;
+    set?(key: string, value: string, ...args: any[]): Promise<'OK' | null>;
+    ltrim?(key: string, start: number, stop: number): Promise<'OK'>;
+    lrange?(key: string, start: number, stop: number): Promise<string[]>;
+    publish?(channel: string, message: string): Promise<number>;
+    pipeline?(): any;
+    defineCommand?(name: string, options: {
+        numberOfKeys: number;
+        lua: string;
+    }): void;
+    incr?(key: string): Promise<number>;
+    expire?(key: string, seconds: number): Promise<number>;
+    eval(script: string, numKeys: number, ...args: (string | number)[]): Promise<any>;
+    [key: string]: any;
+}
 /**
  * Redis driver configuration.
  */
@@ -1189,15 +1588,7 @@ interface RedisDriverConfig {
     /**
      * Redis client instance (ioredis or node-redis).
      */
-    client: {
-        lpush: (key: string, ...values: string[]) => Promise<number>;
-        rpop: (key: string) => Promise<string | null>;
-        llen: (key: string) => Promise<number>;
-        del: (key: string) => Promise<number>;
-        lpushx?: (key: string, ...values: string[]) => Promise<number>;
-        rpoplpush?: (src: string, dst: string) => Promise<string | null>;
-        [key: string]: unknown;
-    };
+    client: RedisClient;
     /**
      * Key prefix (default: `queue:`).
      */
@@ -1227,6 +1618,7 @@ declare class RedisDriver implements QueueDriver {
     private client;
     private static PUSH_SCRIPT;
     private static COMPLETE_SCRIPT;
+    private static POP_MANY_SCRIPT;
     constructor(config: RedisDriverConfig);
     /**
      * Get full Redis key for a queue.
@@ -1241,10 +1633,19 @@ declare class RedisDriver implements QueueDriver {
      */
     complete(queue: string, job: SerializedJob): Promise<void>;
     /**
-     * Pop a job (RPOP, FIFO).
-     * Supports implicit priority polling (critical -> high -> default -> low).
+     * Pop a job from a queue (non-blocking).
+     * Optimized with Lua script for atomic priority polling.
      */
     pop(queue: string): Promise<SerializedJob | null>;
+    /**
+     * Manual fallback for pop if Lua fails.
+     */
+    private popManualFallback;
+    /**
+     * Pop a job from the queue (blocking).
+     * Uses BRPOP for efficiency. Supports multiple queues and priorities.
+     */
+    popBlocking(queues: string | string[], timeout: number): Promise<SerializedJob | null>;
     /**
      * Parse Redis payload.
      */
@@ -1261,12 +1662,18 @@ declare class RedisDriver implements QueueDriver {
      * Clear a queue.
      */
     clear(queue: string): Promise<void>;
+    /**
+     * Get queue statistics.
+     * Optimized with Redis Pipeline to fetch all priorities and DLQ stats in one trip.
+     */
+    stats(queue: string): Promise<QueueStats>;
     /**
      * Push multiple jobs.
      */
     pushMany(queue: string, jobs: SerializedJob[]): Promise<void>;
     /**
      * Pop multiple jobs.
+     * Atomic operation across multiple priority levels.
      */
     popMany(queue: string, count: number): Promise<SerializedJob[]>;
     /**
@@ -1373,6 +1780,11 @@ declare class SQSDriver implements QueueDriver {
      * Pop a job (long polling).
      */
     pop(queue: string): Promise<SerializedJob | null>;
+    /**
+     * Pop multiple jobs.
+     * Leverages SQS MaxNumberOfMessages (up to 10).
+     */
+    popMany(queue: string, count: number): Promise<SerializedJob[]>;
     /**
      * Get queue size (approximate).
      */
@@ -1465,6 +1877,79 @@ declare module '@gravito/core' {
     }
 }
 
+/**
+ * Buffered Persistence Wrapper.
+ * Wraps any PersistenceAdapter to add buffering and batch writing capabilities.
+ */
+declare class BufferedPersistence implements PersistenceAdapter {
+    private adapter;
+    private jobBuffer;
+    private logBuffer;
+    private flushTimer;
+    private maxBufferSize;
+    private flushInterval;
+    constructor(adapter: PersistenceAdapter, options?: {
+        maxBufferSize?: number;
+        flushInterval?: number;
+    });
+    archive(queue: string, job: SerializedJob, status: 'completed' | 'failed' | 'waiting' | string): Promise<void>;
+    find(queue: string, id: string): Promise<SerializedJob | null>;
+    list(queue: string, options?: {
+        limit?: number;
+        offset?: number;
+        status?: 'completed' | 'failed' | 'waiting' | string;
+        jobId?: string;
+        startTime?: Date;
+        endTime?: Date;
+    }): Promise<SerializedJob[]>;
+    archiveMany(jobs: Array<{
+        queue: string;
+        job: SerializedJob;
+        status: 'completed' | 'failed' | 'waiting' | string;
+    }>): Promise<void>;
+    cleanup(days: number): Promise<number>;
+    flush(): Promise<void>;
+    count(queue: string, options?: {
+        status?: 'completed' | 'failed' | 'waiting' | string;
+        jobId?: string;
+        startTime?: Date;
+        endTime?: Date;
+    }): Promise<number>;
+    archiveLog(log: {
+        level: string;
+        message: string;
+        workerId: string;
+        queue?: string;
+        timestamp: Date;
+    }): Promise<void>;
+    archiveLogMany(logs: Array<{
+        level: string;
+        message: string;
+        workerId: string;
+        queue?: string;
+        timestamp: Date;
+    }>): Promise<void>;
+    listLogs(options?: {
+        limit?: number;
+        offset?: number;
+        level?: string;
+        workerId?: string;
+        queue?: string;
+        search?: string;
+        startTime?: Date;
+        endTime?: Date;
+    }): Promise<any[]>;
+    countLogs(options?: {
+        level?: string;
+        workerId?: string;
+        queue?: string;
+        search?: string;
+        startTime?: Date;
+        endTime?: Date;
+    }): Promise<number>;
+    private ensureFlushTimer;
+}
+
 /**
  * MySQL Persistence Adapter.
  * Archives jobs into a MySQL table for long-term auditing.
@@ -1476,15 +1961,20 @@ declare class MySQLPersistence implements PersistenceAdapter {
     /**
      * @param db - An Atlas DB instance or compatible QueryBuilder.
      * @param table - The name of the table to store archived jobs.
+     * @param logsTable - The name of the table to store system logs.
+     * @param options - Buffering options (Deprecated: Use BufferedPersistence wrapper instead).
      */
-    constructor(db: any, table?: string, logsTable?: string);
-    /**
-     * Archive a job.
-     */
+    constructor(db: ConnectionContract, table?: string, logsTable?: string, _options?: {
+        maxBufferSize?: number;
+        flushInterval?: number;
+    });
     archive(queue: string, job: SerializedJob, status: 'completed' | 'failed' | 'waiting' | string): Promise<void>;
-    /**
-     * Find a specific job in the archive.
-     */
+    archiveMany(jobs: Array<{
+        queue: string;
+        job: SerializedJob;
+        status: 'completed' | 'failed' | 'waiting' | string;
+    }>): Promise<void>;
+    flush(): Promise<void>;
     find(queue: string, id: string): Promise<SerializedJob | null>;
     /**
      * List jobs from the archive.
@@ -1506,7 +1996,7 @@ declare class MySQLPersistence implements PersistenceAdapter {
         queue?: string;
     }): Promise<SerializedJob[]>;
     /**
-     * Archive a system log message.
+     * Archive a system log message (buffered).
      */
     archiveLog(log: {
         level: string;
@@ -1515,6 +2005,16 @@ declare class MySQLPersistence implements PersistenceAdapter {
         queue?: string;
         timestamp: Date;
     }): Promise<void>;
+    /**
+     * Archive multiple log messages (direct batch write).
+     */
+    archiveLogMany(logs: Array<{
+        level: string;
+        message: string;
+        workerId: string;
+        queue?: string;
+        timestamp: Date;
+    }>): Promise<void>;
     /**
      * List system logs from the archive.
      */
@@ -1571,15 +2071,20 @@ declare class SQLitePersistence implements PersistenceAdapter {
     /**
      * @param db - An Atlas DB instance (SQLite driver).
      * @param table - The name of the table to store archived jobs.
+     * @param logsTable - The name of the table to store system logs.
+     * @param options - Buffering options (Deprecated: Use BufferedPersistence wrapper instead).
      */
-    constructor(db: any, table?: string, logsTable?: string);
-    /**
-     * Archive a job.
-     */
+    constructor(db: ConnectionContract, table?: string, logsTable?: string, _options?: {
+        maxBufferSize?: number;
+        flushInterval?: number;
+    });
     archive(queue: string, job: SerializedJob, status: 'completed' | 'failed' | 'waiting' | string): Promise<void>;
-    /**
-     * Find a specific job in the archive.
-     */
+    archiveMany(jobs: Array<{
+        queue: string;
+        job: SerializedJob;
+        status: 'completed' | 'failed' | 'waiting' | string;
+    }>): Promise<void>;
+    flush(): Promise<void>;
     find(queue: string, id: string): Promise<SerializedJob | null>;
     /**
      * List jobs from the archive.
@@ -1601,7 +2106,7 @@ declare class SQLitePersistence implements PersistenceAdapter {
         queue?: string;
     }): Promise<SerializedJob[]>;
     /**
-     * Archive a system log message.
+     * Archive a system log message (buffered).
      */
     archiveLog(log: {
         level: string;
@@ -1610,6 +2115,16 @@ declare class SQLitePersistence implements PersistenceAdapter {
         queue?: string;
         timestamp: Date;
     }): Promise<void>;
+    /**
+     * Archive multiple log messages (direct batch write).
+     */
+    archiveLogMany(logs: Array<{
+        level: string;
+        message: string;
+        workerId: string;
+        queue?: string;
+        timestamp: Date;
+    }>): Promise<void>;
     /**
      * List system logs from the archive.
      */
@@ -1655,78 +2170,6 @@ declare class SQLitePersistence implements PersistenceAdapter {
     private setupLogsTable;
 }
 
-/**
- * Configuration for a recurring scheduled job.
- *
- * @public
- * @since 3.0.0
- */
-interface ScheduledJobConfig {
-    /** Unique identifier for the scheduled task. */
-    id: string;
-    /** Cron expression defining the schedule (e.g., '* * * * *'). */
-    cron: string;
-    /** The target queue name where the job should be pushed. */
-    queue: string;
-    /** The serialized job data. */
-    job: SerializedJob;
-    /** Timestamp of the last successful execution in milliseconds. */
-    lastRun?: number;
-    /** Timestamp of the next scheduled execution in milliseconds. */
-    nextRun?: number;
-    /** Whether the scheduled job is active. */
-    enabled: boolean;
-}
-/**
- * Scheduler manages recurring (cron) jobs in Gravito.
- *
- * It uses Redis to store schedule metadata and coordinates distributed
- * execution using locks to ensure jobs are triggered exactly once per interval.
- *
- * @example
- * ```typescript
- * const scheduler = new Scheduler(queueManager);
- * await scheduler.register({
- *   id: 'daily-cleanup',
- *   cron: '0 0 * * *',
- *   queue: 'default',
- *   job: myJob.serialize()
- * });
- * ```
- *
- * @public
- * @since 3.0.0
- */
-declare class Scheduler {
-    private manager;
-    private prefix;
-    constructor(manager: QueueManager, options?: {
-        prefix?: string;
-    });
-    private get client();
-    /**
-     * Register a scheduled job.
-     */
-    register(config: Omit<ScheduledJobConfig, 'nextRun' | 'enabled'>): Promise<void>;
-    /**
-     * Remove a scheduled job.
-     */
-    remove(id: string): Promise<void>;
-    /**
-     * List all scheduled jobs.
-     */
-    list(): Promise<ScheduledJobConfig[]>;
-    /**
-     * Run a scheduled job immediately (out of schedule).
-     */
-    runNow(id: string): Promise<void>;
-    /**
-     * Process due tasks (TICK).
-     * This should be called periodically (e.g. every minute).
-     */
-    tick(): Promise<number>;
-}
-
 /**
  * Class name serializer (Laravel-style).
  *
@@ -1792,11 +2235,8 @@ declare class JsonSerializer implements JobSerializer {
     serialize(job: Job): SerializedJob;
     /**
      * Deserialize a job.
-     *
-     * Note: this implementation only restores properties and does not recreate class instances.
-     * For class instances, use `ClassNameSerializer`.
      */
     deserialize(serialized: SerializedJob): Job;
 }
 
-export { ClassNameSerializer, Consumer, type ConsumerOptions, DatabaseDriver, type DatabaseDriverConfig, Job, type JobSerializer, JsonSerializer, KafkaDriver, type KafkaDriverConfig, MemoryDriver, MySQLPersistence, OrbitStream, type OrbitStreamOptions, type PersistenceAdapter, type QueueConfig, type QueueConnectionConfig, type QueueDriver, QueueManager, type Queueable, RabbitMQDriver, type RabbitMQDriverConfig, RedisDriver, type RedisDriverConfig, SQLitePersistence, SQSDriver, type SQSDriverConfig, Scheduler, type SerializedJob, type TopicOptions, Worker, type WorkerOptions };
+export { BufferedPersistence, ClassNameSerializer, Consumer, type ConsumerOptions, DatabaseDriver, type DatabaseDriverConfig, Job, type JobSerializer, JsonSerializer, KafkaDriver, type KafkaDriverConfig, MemoryDriver, MySQLPersistence, OrbitStream, type OrbitStreamOptions, type PersistenceAdapter, type QueueConfig, type QueueConnectionConfig, type QueueDriver, QueueManager, type Queueable, RabbitMQDriver, type RabbitMQDriverConfig, RedisDriver, type RedisDriverConfig, SQLitePersistence, SQSDriver, type SQSDriverConfig, Scheduler, type SerializedJob, type TopicOptions, Worker, type WorkerOptions };