@gravito/stream 1.0.0-alpha.5 → 1.0.0-beta.1

package/dist/index.d.cts

@@ -0,0 +1,1132 @@
+import { GravitoOrbit, PlanetCore } from 'gravito-core';
+
+/**
+ * Serialized job payload.
+ */
+interface SerializedJob {
+    /**
+     * Unique job identifier.
+     */
+    id: string;
+    /**
+     * Serializer type: `'json'` or `'class'`.
+     */
+    type: 'json' | 'class';
+    /**
+     * Serialized data.
+     */
+    data: string;
+    /**
+     * Class name (only for `type === 'class'`).
+     */
+    className?: string;
+    /**
+     * Created timestamp.
+     */
+    createdAt: number;
+    /**
+     * Delay before execution (seconds).
+     */
+    delaySeconds?: number;
+    /**
+     * Current attempt number.
+     */
+    attempts?: number;
+    /**
+     * Maximum attempts.
+     */
+    maxAttempts?: number;
+}
+/**
+ * Topic options (for Kafka, etc.).
+ */
+interface TopicOptions {
+    /**
+     * Number of partitions.
+     */
+    partitions?: number;
+    /**
+     * Replication factor.
+     */
+    replicationFactor?: number;
+    /**
+     * Additional config.
+     */
+    config?: Record<string, string>;
+}
+/**
+ * Queue connection config.
+ */
+interface QueueConnectionConfig {
+    /**
+     * Driver type.
+     */
+    driver: 'memory' | 'database' | 'redis' | 'kafka' | 'sqs' | 'rabbitmq' | 'nats';
+    /**
+     * Driver-specific config.
+     */
+    [key: string]: unknown;
+}
+/**
+ * Queue manager config.
+ */
+interface QueueConfig {
+    /**
+     * Default connection name.
+     */
+    default?: string;
+    /**
+     * Connection configs.
+     */
+    connections?: Record<string, QueueConnectionConfig>;
+    /**
+     * Default serializer type.
+     */
+    defaultSerializer?: 'json' | 'class';
+}
+
+/**
+ * Queue driver interface.
+ *
+ * All queue drivers must implement this interface.
+ * Defines basic queue operations plus optional enterprise-grade capabilities.
+ *
+ * @example
+ * ```typescript
+ * class MyDriver implements QueueDriver {
+ *   async push(queue: string, job: SerializedJob): Promise<void> {
+ *     // push a job
+ *   }
+ *
+ *   async pop(queue: string): Promise<SerializedJob | null> {
+ *     // pop a job
+ *   }
+ *
+ *   async size(queue: string): Promise<number> {
+ *     // queue size
+ *   }
+ *
+ *   async clear(queue: string): Promise<void> {
+ *     // clear queue
+ *   }
+ * }
+ * ```
+ */
+interface QueueDriver {
+    /**
+     * Push a job to a queue.
+     * @param queue - Queue name
+     * @param job - Serialized job
+     */
+    push(queue: string, job: SerializedJob): Promise<void>;
+    /**
+     * Pop a job from a queue (non-blocking).
+     * @param queue - Queue name
+     * @returns Serialized job, or `null` if the queue is empty
+     */
+    pop(queue: string): Promise<SerializedJob | null>;
+    /**
+     * Get queue size.
+     * @param queue - Queue name
+     * @returns Number of jobs in the queue
+     */
+    size(queue: string): Promise<number>;
+    /**
+     * Clear a queue.
+     * @param queue - Queue name
+     */
+    clear(queue: string): Promise<void>;
+    /**
+     * Push multiple jobs (optional, higher throughput).
+     * @param queue - Queue name
+     * @param jobs - Serialized job array
+     */
+    pushMany?(queue: string, jobs: SerializedJob[]): Promise<void>;
+    /**
+     * Pop multiple jobs (optional, higher throughput).
+     * @param queue - Queue name
+     * @param count - Max number of jobs to pop
+     * @returns Serialized job array
+     */
+    popMany?(queue: string, count: number): Promise<SerializedJob[]>;
+    /**
+     * Acknowledge a message (enterprise capability, e.g. Kafka/SQS).
+     * @param messageId - Message ID
+     */
+    acknowledge?(messageId: string): Promise<void>;
+    /**
+     * Subscribe to a queue (push-based model, e.g. Kafka/SQS).
+     * @param queue - Queue name
+     * @param callback - Callback to process jobs
+     */
+    subscribe?(queue: string, callback: (job: SerializedJob) => Promise<void>): Promise<void>;
+    /**
+     * Create a topic (Kafka, etc.).
+     * @param topic - Topic name
+     * @param options - Topic options
+     */
+    createTopic?(topic: string, options?: TopicOptions): Promise<void>;
+    /**
+     * Delete a topic (Kafka, etc.).
+     * @param topic - Topic name
+     */
+    deleteTopic?(topic: string): Promise<void>;
+}
+
+/**
+ * Queueable interface.
+ *
+ * Classes implementing this interface can be pushed to a queue for execution.
+ * Provides a fluent API for queue/connection/delay configuration.
+ *
+ * @example
+ * ```typescript
+ * class MyJob implements Queueable {
+ *   queueName?: string
+ *   connectionName?: string
+ *   delaySeconds?: number
+ *
+ *   onQueue(queue: string): this {
+ *     this.queueName = queue
+ *     return this
+ *   }
+ *
+ *   onConnection(connection: string): this {
+ *     this.connectionName = connection
+ *     return this
+ *   }
+ *
+ *   delay(seconds: number): this {
+ *     this.delaySeconds = seconds
+ *     return this
+ *   }
+ * }
+ * ```
+ */
+interface Queueable {
+    /**
+     * Queue name where the job should be pushed.
+     */
+    queueName?: string;
+    /**
+     * Connection name the job should use.
+     */
+    connectionName?: string;
+    /**
+     * Delay before execution (seconds).
+     */
+    delaySeconds?: number;
+    /**
+     * Set target queue.
+     * @param queue - Queue name
+     * @returns Self for fluent chaining
+     */
+    onQueue(queue: string): this;
+    /**
+     * Set target connection.
+     * @param connection - Connection name
+     * @returns Self for fluent chaining
+     */
+    onConnection(connection: string): this;
+    /**
+     * Set delay (seconds).
+     * @param delay - Delay seconds
+     * @returns Self for fluent chaining
+     */
+    delay(delay: number): this;
+}
+
+/**
+ * Base Job.
+ *
+ * All tasks that should be pushed to a queue should extend this class.
+ * Implements the `Queueable` interface, providing a fluent API for queue/connection/delay.
+ *
+ * @example
+ * ```typescript
+ * class SendWelcomeEmail extends Job {
+ *   constructor(private userId: string) {
+ *     super()
+ *   }
+ *
+ *   async handle(): Promise<void> {
+ *     const user = await User.find(this.userId)
+ *     await mail.send(new WelcomeEmail(user))
+ *   }
+ * }
+ *
+ * // Usage
+ * await queue.push(new SendWelcomeEmail('123'))
+ *   .onQueue('emails')
+ *   .delay(60)
+ * ```
+ */
+declare abstract class Job implements Queueable {
+    /**
+     * Queue name.
+     */
+    queueName?: string;
+    /**
+     * Connection name.
+     */
+    connectionName?: string;
+    /**
+     * Delay before execution (seconds).
+     */
+    delaySeconds?: number;
+    /**
+     * Current attempt number.
+     */
+    attempts?: number;
+    /**
+     * Maximum attempts.
+     */
+    maxAttempts?: number;
+    /**
+     * Set target queue.
+     */
+    onQueue(queue: string): this;
+    /**
+     * Set target connection.
+     */
+    onConnection(connection: string): this;
+    /**
+     * Set delay (seconds).
+     */
+    delay(delay: number): this;
+    /**
+     * Job handler logic.
+     *
+     * Subclasses must implement this method.
+     */
+    abstract handle(): Promise<void>;
+    /**
+     * Failure handler (optional).
+     *
+     * Called when the job fails and reaches the maximum number of attempts.
+     * Subclasses can override to implement custom failure handling.
+     *
+     * @param error - Error instance
+     */
+    failed(_error: Error): Promise<void>;
+}
+
+/**
+ * Job serializer interface.
+ *
+ * Responsible for serializing and deserializing jobs.
+ * Supports multiple strategies (JSON, class-name, etc.).
+ *
+ * @example
+ * ```typescript
+ * class MySerializer implements JobSerializer {
+ *   serialize(job: Job): SerializedJob {
+ *     // serialization logic
+ *   }
+ *
+ *   deserialize(serialized: SerializedJob): Job {
+ *     // deserialization logic
+ *   }
+ * }
+ * ```
+ */
+interface JobSerializer {
+    /**
+     * Serialize a job.
+     * @param job - Job instance
+     * @returns Serialized job payload
+     */
+    serialize(job: Job): SerializedJob;
+    /**
+     * Deserialize a job.
+     * @param serialized - Serialized job payload
+     * @returns Job instance
+     */
+    deserialize(serialized: SerializedJob): Job;
+}
+
+/**
+ * Queue Manager
+ *
+ * Manages multiple queue connections and drivers, exposing a unified API for pushing and consuming jobs.
+ * Supports lazy-loading drivers to keep the core lightweight.
+ *
+ * @example
+ * ```typescript
+ * const manager = new QueueManager({
+ *   default: 'database',
+ *   connections: {
+ *     database: { driver: 'database', table: 'jobs' },
+ *     redis: { driver: 'redis', url: 'redis://...' }
+ *   }
+ * })
+ *
+ * await manager.push(new SendEmail('user@example.com'))
+ * ```
+ */
+declare class QueueManager {
+    private drivers;
+    private serializers;
+    private defaultConnection;
+    private defaultSerializer;
+    constructor(config?: QueueConfig);
+    /**
+     * Register a connection.
+     * @param name - Connection name
+     * @param config - Connection config
+     */
+    registerConnection(name: string, config: unknown): void;
+    /**
+     * Get a driver for a connection.
+     * @param connection - Connection name
+     * @returns Driver instance
+     */
+    getDriver(connection: string): QueueDriver;
+    /**
+     * Get a serializer.
+     * @param type - Serializer type
+     * @returns Serializer instance
+     */
+    getSerializer(type?: string): JobSerializer;
+    /**
+     * Register Job classes (used by ClassNameSerializer).
+     * @param jobClasses - Job class array
+     */
+    registerJobClasses(jobClasses: Array<new (...args: unknown[]) => Job>): void;
+    /**
+     * Push a Job to the queue.
+     *
+     * @template T - The type of the job.
+     * @param job - Job instance to push.
+     * @returns The same job instance (for fluent chaining).
+     *
+     * @example
+     * ```typescript
+     * await manager.push(new SendEmailJob('user@example.com'));
+     * ```
+     */
+    push<T extends Job & Queueable>(job: T): Promise<T>;
+    /**
+     * Push multiple jobs to the queue.
+     *
+     * @template T - The type of the jobs.
+     * @param jobs - Array of job instances.
+     *
+     * @example
+     * ```typescript
+     * await manager.pushMany([new JobA(), new JobB()]);
+     * ```
+     */
+    pushMany<T extends Job & Queueable>(jobs: T[]): Promise<void>;
+    /**
+     * Pop a job from the queue.
+     *
+     * @param queue - Queue name (default: 'default').
+     * @param connection - Connection name (optional).
+     * @returns Job instance or null if queue is empty.
+     *
+     * @example
+     * ```typescript
+     * const job = await manager.pop('emails');
+     * if (job) await job.handle();
+     * ```
+     */
+    pop(queue?: string, connection?: string): Promise<Job | null>;
+    /**
+     * Get queue size.
+     *
+     * @param queue - Queue name (default: 'default').
+     * @param connection - Connection name (optional).
+     * @returns Number of jobs in the queue.
+     */
+    size(queue?: string, connection?: string): Promise<number>;
+    /**
+     * Clear all jobs from a queue.
+     *
+     * @param queue - Queue name (default: 'default').
+     * @param connection - Connection name (optional).
+     */
+    clear(queue?: string, connection?: string): Promise<void>;
+}
+
+/**
+ * Worker options.
+ */
+interface WorkerOptions {
+    /**
+     * Maximum retry attempts.
+     */
+    maxAttempts?: number;
+    /**
+     * Job timeout (seconds).
+     */
+    timeout?: number;
+    /**
+     * Failure callback.
+     */
+    onFailed?: (job: Job, error: Error) => Promise<void>;
+}
+/**
+ * Base Worker.
+ *
+ * Responsible for executing `Job` instances.
+ * Provides error handling, retry logic, and timeout support.
+ *
+ * @example
+ * ```typescript
+ * const worker = new Worker({
+ *   maxAttempts: 3,
+ *   timeout: 60
+ * })
+ *
+ * await worker.process(job)
+ * ```
+ */
+declare class Worker {
+    private options;
+    constructor(options?: WorkerOptions);
+    /**
+     * Process a Job.
+     * @param job - Job instance
+     */
+    process(job: Job): Promise<void>;
+    /**
+     * Handle failure.
+     */
+    private handleFailure;
+}
+
+/**
+ * Consumer options.
+ */
+interface ConsumerOptions {
+    /**
+     * Queues to listen on.
+     */
+    queues: string[];
+    /**
+     * Connection name.
+     */
+    connection?: string;
+    /**
+     * Worker options.
+     */
+    workerOptions?: WorkerOptions;
+    /**
+     * Polling interval (milliseconds).
+     */
+    pollInterval?: number;
+    /**
+     * Whether to keep polling when queues are empty.
+     */
+    keepAlive?: boolean;
+}
+/**
+ * Consumer
+ *
+ * Consumes and executes jobs from queues.
+ * Supports embedded mode (inside the main app) and standalone mode (as a worker service).
+ *
+ * @example
+ * ```typescript
+ * // Embedded mode
+ * const consumer = new Consumer(queueManager, {
+ *   queues: ['default', 'emails'],
+ *   pollInterval: 1000
+ * })
+ *
+ * consumer.start()
+ *
+ * // Standalone mode (CLI)
+ * // Start via CLI tooling with graceful shutdown
+ * ```
+ */
+declare class Consumer {
+    private queueManager;
+    private options;
+    private running;
+    private stopRequested;
+    constructor(queueManager: QueueManager, options: ConsumerOptions);
+    /**
+     * Start the consumer loop.
+     */
+    start(): Promise<void>;
+    /**
+     * Stop the consumer loop (graceful shutdown).
+     */
+    stop(): Promise<void>;
+    /**
+     * Check whether the consumer is running.
+     */
+    isRunning(): boolean;
+}
+
+/**
+ * Generic database service interface.
+ * Users should implement this interface with their preferred ORM/database client.
+ */
+interface DatabaseService {
+    /**
+     * Execute a raw SQL query.
+     * @param sql - The SQL query string with placeholders ($1, $2, etc.)
+     * @param bindings - The values to bind to placeholders
+     */
+    execute<T = unknown>(sql: string, bindings?: unknown[]): Promise<T[] | T>;
+    /**
+     * Execute multiple queries within a transaction.
+     * @param callback - The callback to execute within the transaction
+     */
+    transaction<T>(callback: (tx: DatabaseService) => Promise<T>): Promise<T>;
+}
+/**
+ * Database driver configuration.
+ */
+interface DatabaseDriverConfig {
+    /**
+     * Table name (default: `jobs`).
+     */
+    table?: string;
+    /**
+     * Database service instance that implements DatabaseService interface.
+     */
+    dbService?: DatabaseService;
+}
+/**
+ * Database Driver
+ *
+ * Uses a database as the queue backend.
+ * Works with any database service that implements the DatabaseService interface.
+ *
+ * @example
+ * ```typescript
+ * // Create a database service adapter
+ * const dbService = {
+ *   execute: async (sql, bindings) => yourDbClient.query(sql, bindings),
+ *   transaction: async (callback) => yourDbClient.transaction(callback),
+ * }
+ *
+ * const driver = new DatabaseDriver({ dbService, table: 'jobs' })
+ * await driver.push('default', serializedJob)
+ * ```
+ */
+declare class DatabaseDriver implements QueueDriver {
+    private tableName;
+    private dbService;
+    constructor(config: DatabaseDriverConfig);
+    /**
+     * Push a job to a queue.
+     */
+    push(queue: string, job: SerializedJob): Promise<void>;
+    /**
+     * Pop a job from the queue (FIFO, with delay support).
+     */
+    pop(queue: string): Promise<SerializedJob | null>;
+    /**
+     * Get queue size.
+     */
+    size(queue: string): Promise<number>;
+    /**
+     * Clear a queue.
+     */
+    clear(queue: string): Promise<void>;
+    /**
+     * Push multiple jobs.
+     */
+    pushMany(queue: string, jobs: SerializedJob[]): Promise<void>;
+}
+
+/**
+ * Kafka driver configuration.
+ */
+interface KafkaDriverConfig {
+    /**
+     * Kafka client instance (kafkajs).
+     */
+    client: {
+        producer: () => {
+            connect: () => Promise<void>;
+            send: (args: {
+                topic: string;
+                messages: Array<{
+                    key?: string;
+                    value: string;
+                }>;
+            }) => Promise<void>;
+            disconnect: () => Promise<void>;
+        };
+        admin: () => {
+            connect: () => Promise<void>;
+            createTopics: (args: {
+                topics: Array<{
+                    topic: string;
+                    numPartitions?: number;
+                    replicationFactor?: number;
+                }>;
+            }) => Promise<void>;
+            deleteTopics: (args: {
+                topics: string[];
+            }) => Promise<void>;
+            disconnect: () => Promise<void>;
+        };
+        consumer: (args: {
+            groupId: string;
+        }) => {
+            connect: () => Promise<void>;
+            subscribe: (args: {
+                topics: string[];
+            }) => Promise<void>;
+            run: (args: {
+                eachMessage: (args: {
+                    topic: string;
+                    partition: number;
+                    message: {
+                        key?: Buffer;
+                        value: Buffer;
+                        offset: string;
+                    };
+                }) => Promise<void>;
+            }) => Promise<void>;
+            disconnect: () => Promise<void>;
+        };
+    };
+    /**
+     * Consumer group ID (for consuming messages).
+     */
+    consumerGroupId?: string;
+}
+/**
+ * Kafka Driver
+ *
+ * Uses Apache Kafka as the queue backend.
+ * Supports topic management, consumer groups, and batch operations.
+ *
+ * Requires `kafkajs`.
+ *
+ * @example
+ * ```typescript
+ * import { Kafka } from 'kafkajs'
+ *
+ * const kafka = new Kafka({
+ *   brokers: ['localhost:9092'],
+ *   clientId: 'gravito-app'
+ * })
+ *
+ * const driver = new KafkaDriver({ client: kafka, consumerGroupId: 'workers' })
+ * await driver.push('default', serializedJob)
+ * ```
+ */
+declare class KafkaDriver implements QueueDriver {
+    private client;
+    private consumerGroupId;
+    private producer?;
+    private admin?;
+    constructor(config: KafkaDriverConfig);
+    /**
+     * Ensure the producer is connected.
+     */
+    private ensureProducer;
+    /**
+     * Ensure the admin client is connected.
+     */
+    private ensureAdmin;
+    /**
+     * Push a job to a topic.
+     */
+    push(queue: string, job: SerializedJob): Promise<void>;
+    /**
+     * Pop is not supported for Kafka.
+     *
+     * Note: Kafka uses a push-based model, so you should use `subscribe()`.
+     */
+    pop(_queue: string): Promise<SerializedJob | null>;
+    /**
+     * Kafka does not provide a direct queue size.
+     *
+     * Returns 0; use Kafka tooling/metrics for lag/size insights.
+     */
+    size(_queue: string): Promise<number>;
+    /**
+     * Clear a queue by deleting the topic.
+     */
+    clear(queue: string): Promise<void>;
+    /**
+     * Push multiple jobs.
+     */
+    pushMany(queue: string, jobs: SerializedJob[]): Promise<void>;
+    /**
+     * Create a topic.
+     */
+    createTopic(topic: string, options?: TopicOptions): Promise<void>;
+    /**
+     * Delete a topic.
+     */
+    deleteTopic(topic: string): Promise<void>;
+    /**
+     * Subscribe to a topic (push-based model).
+     */
+    subscribe(queue: string, callback: (job: SerializedJob) => Promise<void>): Promise<void>;
+}
+
+/**
+ * Memory Driver
+ *
+ * In-memory driver for development and testing.
+ * All data is stored in memory and will be lost when the process restarts.
+ *
+ * Zero-config: works out of the box.
+ *
+ * @example
+ * ```typescript
+ * const driver = new MemoryDriver()
+ * await driver.push('default', serializedJob)
+ * const job = await driver.pop('default')
+ * ```
+ */
+declare class MemoryDriver implements QueueDriver {
+    private queues;
+    /**
+     * Push a job to a queue.
+     */
+    push(queue: string, job: SerializedJob): Promise<void>;
+    /**
+     * Pop a job from a queue (FIFO).
+     */
+    pop(queue: string): Promise<SerializedJob | null>;
+    /**
+     * Get queue size.
+     */
+    size(queue: string): Promise<number>;
+    /**
+     * Clear a queue.
+     */
+    clear(queue: string): Promise<void>;
+    /**
+     * Push multiple jobs.
+     */
+    pushMany(queue: string, jobs: SerializedJob[]): Promise<void>;
+    /**
+     * Pop multiple jobs.
+     */
+    popMany(queue: string, count: number): Promise<SerializedJob[]>;
+}
+
+/**
+ * Redis driver configuration.
+ */
+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;
+    };
+    /**
+     * Key prefix (default: `queue:`).
+     */
+    prefix?: string;
+}
+/**
+ * Redis Driver
+ *
+ * Uses Redis as the queue backend.
+ * Implements FIFO via Redis Lists (LPUSH/RPOP).
+ *
+ * Requires `ioredis` or `redis`.
+ *
+ * @example
+ * ```typescript
+ * import Redis from 'ioredis'
+ *
+ * const redis = new Redis('redis://localhost:6379')
+ * const driver = new RedisDriver({ client: redis })
+ *
+ * await driver.push('default', serializedJob)
+ * ```
+ */
+declare class RedisDriver implements QueueDriver {
+    private prefix;
+    private client;
+    constructor(config: RedisDriverConfig);
+    /**
+     * Get full Redis key for a queue.
+     */
+    private getKey;
+    /**
+     * Push a job (LPUSH).
+     */
+    push(queue: string, job: SerializedJob): Promise<void>;
+    /**
+     * Pop a job (RPOP, FIFO).
+     */
+    pop(queue: string): Promise<SerializedJob | null>;
+    /**
+     * Parse Redis payload.
+     */
+    private parsePayload;
+    /**
+     * Get queue size.
+     */
+    size(queue: string): Promise<number>;
+    /**
+     * Clear a queue.
+     */
+    clear(queue: string): Promise<void>;
+    /**
+     * Push multiple jobs.
+     */
+    pushMany(queue: string, jobs: SerializedJob[]): Promise<void>;
+    /**
+     * Pop multiple jobs.
+     */
+    popMany(queue: string, count: number): Promise<SerializedJob[]>;
+}
+
+/**
+ * SQS driver configuration.
+ */
+interface SQSDriverConfig {
+    /**
+     * SQS client instance (`@aws-sdk/client-sqs`).
+     */
+    client: {
+        send: (command: unknown) => Promise<{
+            MessageId?: string;
+            Messages?: Array<{
+                MessageId?: string;
+                ReceiptHandle?: string;
+                Body?: string;
+            }>;
+        }>;
+    };
+    /**
+     * Queue URL prefix (used to build full queue URLs).
+     */
+    queueUrlPrefix?: string;
+    /**
+     * Visibility timeout (seconds, default: 30).
+     */
+    visibilityTimeout?: number;
+    /**
+     * Long-polling duration (seconds, default: 20).
+     */
+    waitTimeSeconds?: number;
+}
+/**
+ * SQS Driver
+ *
+ * Uses AWS SQS as the queue backend.
+ * Supports standard/FIFO queues, long polling, DLQ setups, etc.
+ *
+ * Requires `@aws-sdk/client-sqs`.
+ *
+ * @example
+ * ```typescript
+ * import { SQSClient } from '@aws-sdk/client-sqs'
+ *
+ * const sqs = new SQSClient({
+ *   region: 'us-east-1',
+ *   credentials: {
+ *     accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
+ *     secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
+ *   }
+ * })
+ *
+ * const driver = new SQSDriver({ client: sqs })
+ * await driver.push('default', serializedJob)
+ * ```
+ */
+declare class SQSDriver implements QueueDriver {
+    private client;
+    private queueUrlPrefix;
+    private visibilityTimeout;
+    private waitTimeSeconds;
+    private queueUrls;
+    constructor(config: SQSDriverConfig);
+    /**
+     * Resolve the full queue URL.
+     */
+    private getQueueUrl;
+    /**
+     * Push a job to SQS.
+     */
+    push(queue: string, job: SerializedJob): Promise<void>;
+    /**
+     * Pop a job (long polling).
+     */
+    pop(queue: string): Promise<SerializedJob | null>;
+    /**
+     * Get queue size (approximate).
+     */
+    size(queue: string): Promise<number>;
+    /**
+     * Clear a queue by receiving and deleting messages.
+     *
+     * Note: SQS does not provide a direct "purge" API via this wrapper. This method will
+     * keep receiving and deleting messages until the queue is empty.
+     */
+    clear(queue: string): Promise<void>;
+    /**
+     * Push multiple jobs.
+     */
+    pushMany(queue: string, jobs: SerializedJob[]): Promise<void>;
+    /**
+     * Acknowledge is not supported via messageId.
+     */
+    acknowledge(_messageId: string): Promise<void>;
+    /**
+     * Delete a message (acknowledge processing completion).
+     */
+    deleteMessage(queue: string, receiptHandle: string): Promise<void>;
+}
+
+/**
+ * Orbit Queue configuration options.
+ */
+interface OrbitStreamOptions extends QueueConfig {
+    /**
+     * Whether to auto-start an embedded worker in development.
+     */
+    autoStartWorker?: boolean;
+    /**
+     * Embedded worker options.
+     */
+    workerOptions?: ConsumerOptions;
+}
+/**
+ * Orbit Queue
+ *
+ * Gravito Orbit implementation providing queue functionality.
+ * Integrates with PlanetCore and injects a `queue` service into the Photon Context.
+ *
+ * @example
+ * ```typescript
+ * const core = await PlanetCore.boot({
+ *   orbits: [
+ *     OrbitStream.configure({
+ *       default: 'database',
+ *       connections: {
+ *         database: { driver: 'database', table: 'jobs' }
+ *       }
+ *     })
+ *   ]
+ * })
+ *
+ * // Use in a controller/handler
+ * const queue = c.get('queue')
+ * await queue.push(new SendEmail('user@example.com'))
+ * ```
+ */
+declare class OrbitStream implements GravitoOrbit {
+    private options;
+    private queueManager?;
+    private consumer?;
+    constructor(options?: OrbitStreamOptions);
+    /**
+     * Static configuration helper.
+     */
+    static configure(options: OrbitStreamOptions): OrbitStream;
+    /**
+     * Install into PlanetCore.
+     */
+    install(core: PlanetCore): void;
+    /**
+     * Start embedded worker.
+     */
+    startWorker(options: ConsumerOptions): void;
+    /**
+     * Stop embedded worker.
+     */
+    stopWorker(): Promise<void>;
+    /**
+     * Get QueueManager instance.
+     */
+    getQueueManager(): QueueManager | undefined;
+}
+declare module 'gravito-core' {
+    interface GravitoVariables {
+        /** Queue manager for job processing */
+        queue?: QueueManager;
+        /** Database service (from orbit-db) */
+        db?: unknown;
+    }
+}
+
+/**
+ * Class name serializer (Laravel-style).
+ *
+ * Stores the class name and properties, then recreates an instance at runtime.
+ * This is the recommended serializer because it can restore class instances correctly.
+ *
+ * Requirement: Job classes must be dynamically loadable (by class name).
+ *
+ * @example
+ * ```typescript
+ * const serializer = new ClassNameSerializer()
+ * const serialized = serializer.serialize(new SendEmail('user@example.com'))
+ * // serialized.data contains class name and properties
+ *
+ * const job = serializer.deserialize(serialized)
+ * // job is an instance of SendEmail
+ * ```
+ */
+declare class ClassNameSerializer implements JobSerializer {
+    /**
+     * Job class registry (for resolving classes by name).
+     */
+    private jobClasses;
+    /**
+     * Register a Job class.
+     * @param jobClass - Job class
+     */
+    register(jobClass: new (...args: unknown[]) => Job): void;
+    /**
+     * Register multiple Job classes.
+     * @param jobClasses - Job class array
+     */
+    registerMany(jobClasses: Array<new (...args: unknown[]) => Job>): void;
+    /**
+     * Serialize a Job.
+     */
+    serialize(job: Job): SerializedJob;
+    /**
+     * Deserialize a Job.
+     */
+    deserialize(serialized: SerializedJob): Job;
+}
+
+/**
+ * JSON Serializer
+ *
+ * Serializes jobs using JSON.
+ * Suitable for simple scenarios where you only need to persist plain properties.
+ *
+ * Limitation: cannot restore class instances, functions, or complex objects.
+ *
+ * @example
+ * ```typescript
+ * const serializer = new JsonSerializer()
+ * const serialized = serializer.serialize(job)
+ * const job = serializer.deserialize(serialized)
+ * ```
+ */
+declare class JsonSerializer implements JobSerializer {
+    /**
+     * Serialize a job.
+     */
+    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, OrbitStream, type OrbitStreamOptions, type QueueConfig, type QueueConnectionConfig, type QueueDriver, QueueManager, type Queueable, RedisDriver, type RedisDriverConfig, SQSDriver, type SQSDriverConfig, type SerializedJob, type TopicOptions, Worker, type WorkerOptions };