@gravito/stream 1.0.2 → 1.0.3

package/dist/index.cjs

@@ -2198,6 +2198,7 @@ var OrbitStream = class _OrbitStream {
    */
   install(core) {
     this.queueManager = new QueueManager(this.options);
+    core.container.instance("queue", this.queueManager);
     core.adapter.use("*", async (c, next) => {
       if (this.queueManager && this.options.connections) {
         for (const [name, config] of Object.entries(this.options.connections)) {
@@ -2371,9 +2372,15 @@ var MySQLPersistence = class {
    */
   async listLogs(options = {}) {
     let query = this.db.table(this.logsTable);
-    if (options.level) query = query.where("level", options.level);
-    if (options.workerId) query = query.where("worker_id", options.workerId);
-    if (options.queue) query = query.where("queue", options.queue);
+    if (options.level) {
+      query = query.where("level", options.level);
+    }
+    if (options.workerId) {
+      query = query.where("worker_id", options.workerId);
+    }
+    if (options.queue) {
+      query = query.where("queue", options.queue);
+    }
     if (options.search) {
       query = query.where("message", "like", `%${options.search}%`);
     }
@@ -2390,9 +2397,15 @@ var MySQLPersistence = class {
    */
   async countLogs(options = {}) {
     let query = this.db.table(this.logsTable);
-    if (options.level) query = query.where("level", options.level);
-    if (options.workerId) query = query.where("worker_id", options.workerId);
-    if (options.queue) query = query.where("queue", options.queue);
+    if (options.level) {
+      query = query.where("level", options.level);
+    }
+    if (options.workerId) {
+      query = query.where("worker_id", options.workerId);
+    }
+    if (options.queue) {
+      query = query.where("queue", options.queue);
+    }
     if (options.search) {
       query = query.where("message", "like", `%${options.search}%`);
     }
@@ -2445,7 +2458,9 @@ var MySQLPersistence = class {
   }
   async setupJobsTable() {
     const exists = await import_atlas.Schema.hasTable(this.table);
-    if (exists) return;
+    if (exists) {
+      return;
+    }
     await import_atlas.Schema.create(this.table, (table) => {
       table.id();
       table.string("job_id", 64);
@@ -2464,7 +2479,9 @@ var MySQLPersistence = class {
   }
   async setupLogsTable() {
     const exists = await import_atlas.Schema.hasTable(this.logsTable);
-    if (exists) return;
+    if (exists) {
+      return;
+    }
     await import_atlas.Schema.create(this.logsTable, (table) => {
       table.id();
       table.string("level", 20);
@@ -2594,9 +2611,15 @@ var SQLitePersistence = class {
    */
   async listLogs(options = {}) {
     let query = this.db.table(this.logsTable);
-    if (options.level) query = query.where("level", options.level);
-    if (options.workerId) query = query.where("worker_id", options.workerId);
-    if (options.queue) query = query.where("queue", options.queue);
+    if (options.level) {
+      query = query.where("level", options.level);
+    }
+    if (options.workerId) {
+      query = query.where("worker_id", options.workerId);
+    }
+    if (options.queue) {
+      query = query.where("queue", options.queue);
+    }
     if (options.search) {
       query = query.where("message", "like", `%${options.search}%`);
     }
@@ -2613,9 +2636,15 @@ var SQLitePersistence = class {
    */
   async countLogs(options = {}) {
     let query = this.db.table(this.logsTable);
-    if (options.level) query = query.where("level", options.level);
-    if (options.workerId) query = query.where("worker_id", options.workerId);
-    if (options.queue) query = query.where("queue", options.queue);
+    if (options.level) {
+      query = query.where("level", options.level);
+    }
+    if (options.workerId) {
+      query = query.where("worker_id", options.workerId);
+    }
+    if (options.queue) {
+      query = query.where("queue", options.queue);
+    }
     if (options.search) {
       query = query.where("message", "like", `%${options.search}%`);
     }
@@ -2668,7 +2697,9 @@ var SQLitePersistence = class {
   }
   async setupJobsTable() {
     const exists = await import_atlas2.Schema.hasTable(this.table);
-    if (exists) return;
+    if (exists) {
+      return;
+    }
     await import_atlas2.Schema.create(this.table, (table) => {
       table.id();
       table.string("job_id", 64);
@@ -2685,7 +2716,9 @@ var SQLitePersistence = class {
   }
   async setupLogsTable() {
     const exists = await import_atlas2.Schema.hasTable(this.logsTable);
-    if (exists) return;
+    if (exists) {
+      return;
+    }
     await import_atlas2.Schema.create(this.logsTable, (table) => {
       table.id();
       table.string("level", 20);

package/dist/index.d.cts

@@ -1,94 +1,59 @@
 import { GravitoOrbit, PlanetCore } from '@gravito/core';
 
 /**
- * Serialized job payload.
+ * Represents a job that has been serialized for storage in a queue.
+ * @public
  */
 interface SerializedJob {
-    /**
-     * Unique job identifier.
-     */
+    /** Unique job identifier */
     id: string;
-    /**
-     * Serializer type: `'json'` or `'class'`.
-     */
+    /** Serializer type: 'json' for plain objects or 'class' for instances */
     type: 'json' | 'class';
-    /**
-     * Serialized data.
-     */
+    /** Serialized data string */
     data: string;
-    /**
-     * Class name (only for `type === 'class'`).
-     */
+    /** Fully qualified class name (only used for 'class' type) */
     className?: string;
-    /**
-     * Created timestamp.
-     */
+    /** Timestamp when the job was created */
     createdAt: number;
-    /**
-     * Delay before execution (seconds).
-     */
+    /** Optional delay in seconds before the job becomes available for processing */
     delaySeconds?: number;
-    /**
-     * Current attempt number.
-     */
+    /** Number of times the job has been attempted */
     attempts?: number;
-    /**
-     * Maximum attempts.
-     */
+    /** Maximum number of retry attempts before the job is marked as failed */
     maxAttempts?: number;
-    /**
-     * Group ID for FIFO ordering.
-     */
+    /** Group ID for FIFO (strictly sequential) processing */
     groupId?: string;
-    /**
-     * Initial retry delay (seconds).
-     */
+    /** Initial delay in seconds before first retry attempt */
     retryAfterSeconds?: number;
-    /**
-     * Retry delay multiplier.
-     */
+    /** Multiplier for exponential backoff on retries */
     retryMultiplier?: number;
-    /**
-     * Last error message.
-     */
+    /** Last error message if the job failed */
     error?: string;
-    /**
-     * Timestamp when the job failed permanently.
-     */
+    /** Timestamp when the job finally failed after max attempts */
     failedAt?: number;
-    /**
-     * Job priority.
-     */
+    /** Optional priority for the job (string or numeric) */
     priority?: string | number;
 }
 /**
- * Topic options (for Kafka, etc.).
+ * Advanced topic options for distributed queues (e.g., Kafka).
+ * @public
  */
 interface TopicOptions {
-    /**
-     * Number of partitions.
-     */
+    /** Number of partitions for the topic */
     partitions?: number;
-    /**
-     * Replication factor.
-     */
+    /** Number of replicas for each partition */
     replicationFactor?: number;
-    /**
-     * Additional config.
-     */
+    /** Additional driver-specific configurations */
     config?: Record<string, string>;
 }
 /**
- * Queue connection config.
+ * Configuration for a specific queue connection.
+ * @public
  */
 interface QueueConnectionConfig {
-    /**
-     * Driver type.
-     */
+    /** The driver type to use for this connection */
     driver: 'memory' | 'database' | 'redis' | 'kafka' | 'sqs' | 'rabbitmq' | 'nats';
-    /**
-     * Driver-specific config.
-     */
+    /** Driver-specific settings (e.g., connection string, table name) */
     [key: string]: unknown;
 }
 /**
@@ -1434,41 +1399,36 @@ declare class SQSDriver implements QueueDriver {
 }
 
 /**
- * Orbit Queue configuration options.
+ * Options for configuring OrbitStream (Queue Orbit).
+ * @public
  */
 interface OrbitStreamOptions extends QueueConfig {
     /**
-     * Whether to auto-start an embedded worker in development.
+     * Whether to automatically start an embedded worker in development mode.
+     * Useful for simple local testing without running a separate worker process.
      */
     autoStartWorker?: boolean;
     /**
-     * Embedded worker options.
+     * Configuration for the embedded worker/consumer.
      */
     workerOptions?: ConsumerOptions;
 }
 /**
- * Orbit Queue
- *
- * Gravito Orbit implementation providing queue functionality.
- * Integrates with PlanetCore and injects a `queue` service into the Photon Context.
+ * OrbitStream provides a powerful, multi-driver queue system for Gravito.
+ * It integrates with various backends (Redis, Database, SQS, RabbitMQ)
+ * and supports job serialization, delayed jobs, and FIFO processing.
  *
  * @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'))
+ * const stream = new OrbitStream({
+ *   default: 'redis',
+ *   connections: {
+ *     redis: { driver: 'redis', host: 'localhost' }
+ *   }
+ * });
+ * core.addOrbit(stream);
  * ```
+ * @public
  */
 declare class OrbitStream implements GravitoOrbit {
     private options;
@@ -1695,19 +1655,47 @@ 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
+ * 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()
+ * });
+ * ```
  *
- * Manages recurring (cron) jobs.
+ * @public
+ * @since 3.0.0
  */
 declare class Scheduler {
     private manager;

package/dist/index.d.ts

@@ -1,94 +1,59 @@
 import { GravitoOrbit, PlanetCore } from '@gravito/core';
 
 /**
- * Serialized job payload.
+ * Represents a job that has been serialized for storage in a queue.
+ * @public
  */
 interface SerializedJob {
-    /**
-     * Unique job identifier.
-     */
+    /** Unique job identifier */
     id: string;
-    /**
-     * Serializer type: `'json'` or `'class'`.
-     */
+    /** Serializer type: 'json' for plain objects or 'class' for instances */
     type: 'json' | 'class';
-    /**
-     * Serialized data.
-     */
+    /** Serialized data string */
     data: string;
-    /**
-     * Class name (only for `type === 'class'`).
-     */
+    /** Fully qualified class name (only used for 'class' type) */
     className?: string;
-    /**
-     * Created timestamp.
-     */
+    /** Timestamp when the job was created */
     createdAt: number;
-    /**
-     * Delay before execution (seconds).
-     */
+    /** Optional delay in seconds before the job becomes available for processing */
     delaySeconds?: number;
-    /**
-     * Current attempt number.
-     */
+    /** Number of times the job has been attempted */
     attempts?: number;
-    /**
-     * Maximum attempts.
-     */
+    /** Maximum number of retry attempts before the job is marked as failed */
     maxAttempts?: number;
-    /**
-     * Group ID for FIFO ordering.
-     */
+    /** Group ID for FIFO (strictly sequential) processing */
     groupId?: string;
-    /**
-     * Initial retry delay (seconds).
-     */
+    /** Initial delay in seconds before first retry attempt */
     retryAfterSeconds?: number;
-    /**
-     * Retry delay multiplier.
-     */
+    /** Multiplier for exponential backoff on retries */
     retryMultiplier?: number;
-    /**
-     * Last error message.
-     */
+    /** Last error message if the job failed */
     error?: string;
-    /**
-     * Timestamp when the job failed permanently.
-     */
+    /** Timestamp when the job finally failed after max attempts */
     failedAt?: number;
-    /**
-     * Job priority.
-     */
+    /** Optional priority for the job (string or numeric) */
     priority?: string | number;
 }
 /**
- * Topic options (for Kafka, etc.).
+ * Advanced topic options for distributed queues (e.g., Kafka).
+ * @public
  */
 interface TopicOptions {
-    /**
-     * Number of partitions.
-     */
+    /** Number of partitions for the topic */
     partitions?: number;
-    /**
-     * Replication factor.
-     */
+    /** Number of replicas for each partition */
     replicationFactor?: number;
-    /**
-     * Additional config.
-     */
+    /** Additional driver-specific configurations */
     config?: Record<string, string>;
 }
 /**
- * Queue connection config.
+ * Configuration for a specific queue connection.
+ * @public
  */
 interface QueueConnectionConfig {
-    /**
-     * Driver type.
-     */
+    /** The driver type to use for this connection */
     driver: 'memory' | 'database' | 'redis' | 'kafka' | 'sqs' | 'rabbitmq' | 'nats';
-    /**
-     * Driver-specific config.
-     */
+    /** Driver-specific settings (e.g., connection string, table name) */
     [key: string]: unknown;
 }
 /**
@@ -1434,41 +1399,36 @@ declare class SQSDriver implements QueueDriver {
 }
 
 /**
- * Orbit Queue configuration options.
+ * Options for configuring OrbitStream (Queue Orbit).
+ * @public
  */
 interface OrbitStreamOptions extends QueueConfig {
     /**
-     * Whether to auto-start an embedded worker in development.
+     * Whether to automatically start an embedded worker in development mode.
+     * Useful for simple local testing without running a separate worker process.
      */
     autoStartWorker?: boolean;
     /**
-     * Embedded worker options.
+     * Configuration for the embedded worker/consumer.
      */
     workerOptions?: ConsumerOptions;
 }
 /**
- * Orbit Queue
- *
- * Gravito Orbit implementation providing queue functionality.
- * Integrates with PlanetCore and injects a `queue` service into the Photon Context.
+ * OrbitStream provides a powerful, multi-driver queue system for Gravito.
+ * It integrates with various backends (Redis, Database, SQS, RabbitMQ)
+ * and supports job serialization, delayed jobs, and FIFO processing.
  *
  * @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'))
+ * const stream = new OrbitStream({
+ *   default: 'redis',
+ *   connections: {
+ *     redis: { driver: 'redis', host: 'localhost' }
+ *   }
+ * });
+ * core.addOrbit(stream);
  * ```
+ * @public
  */
 declare class OrbitStream implements GravitoOrbit {
     private options;
@@ -1695,19 +1655,47 @@ 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
+ * 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()
+ * });
+ * ```
  *
- * Manages recurring (cron) jobs.
+ * @public
+ * @since 3.0.0
  */
 declare class Scheduler {
     private manager;

package/dist/index.js

@@ -2171,6 +2171,7 @@ var OrbitStream = class _OrbitStream {
    */
   install(core) {
     this.queueManager = new QueueManager(this.options);
+    core.container.instance("queue", this.queueManager);
     core.adapter.use("*", async (c, next) => {
       if (this.queueManager && this.options.connections) {
         for (const [name, config] of Object.entries(this.options.connections)) {
@@ -2344,9 +2345,15 @@ var MySQLPersistence = class {
    */
   async listLogs(options = {}) {
     let query = this.db.table(this.logsTable);
-    if (options.level) query = query.where("level", options.level);
-    if (options.workerId) query = query.where("worker_id", options.workerId);
-    if (options.queue) query = query.where("queue", options.queue);
+    if (options.level) {
+      query = query.where("level", options.level);
+    }
+    if (options.workerId) {
+      query = query.where("worker_id", options.workerId);
+    }
+    if (options.queue) {
+      query = query.where("queue", options.queue);
+    }
     if (options.search) {
       query = query.where("message", "like", `%${options.search}%`);
     }
@@ -2363,9 +2370,15 @@ var MySQLPersistence = class {
    */
   async countLogs(options = {}) {
     let query = this.db.table(this.logsTable);
-    if (options.level) query = query.where("level", options.level);
-    if (options.workerId) query = query.where("worker_id", options.workerId);
-    if (options.queue) query = query.where("queue", options.queue);
+    if (options.level) {
+      query = query.where("level", options.level);
+    }
+    if (options.workerId) {
+      query = query.where("worker_id", options.workerId);
+    }
+    if (options.queue) {
+      query = query.where("queue", options.queue);
+    }
     if (options.search) {
       query = query.where("message", "like", `%${options.search}%`);
     }
@@ -2418,7 +2431,9 @@ var MySQLPersistence = class {
   }
   async setupJobsTable() {
     const exists = await Schema.hasTable(this.table);
-    if (exists) return;
+    if (exists) {
+      return;
+    }
     await Schema.create(this.table, (table) => {
       table.id();
       table.string("job_id", 64);
@@ -2437,7 +2452,9 @@ var MySQLPersistence = class {
   }
   async setupLogsTable() {
     const exists = await Schema.hasTable(this.logsTable);
-    if (exists) return;
+    if (exists) {
+      return;
+    }
     await Schema.create(this.logsTable, (table) => {
       table.id();
       table.string("level", 20);
@@ -2567,9 +2584,15 @@ var SQLitePersistence = class {
    */
   async listLogs(options = {}) {
     let query = this.db.table(this.logsTable);
-    if (options.level) query = query.where("level", options.level);
-    if (options.workerId) query = query.where("worker_id", options.workerId);
-    if (options.queue) query = query.where("queue", options.queue);
+    if (options.level) {
+      query = query.where("level", options.level);
+    }
+    if (options.workerId) {
+      query = query.where("worker_id", options.workerId);
+    }
+    if (options.queue) {
+      query = query.where("queue", options.queue);
+    }
     if (options.search) {
       query = query.where("message", "like", `%${options.search}%`);
     }
@@ -2586,9 +2609,15 @@ var SQLitePersistence = class {
    */
   async countLogs(options = {}) {
     let query = this.db.table(this.logsTable);
-    if (options.level) query = query.where("level", options.level);
-    if (options.workerId) query = query.where("worker_id", options.workerId);
-    if (options.queue) query = query.where("queue", options.queue);
+    if (options.level) {
+      query = query.where("level", options.level);
+    }
+    if (options.workerId) {
+      query = query.where("worker_id", options.workerId);
+    }
+    if (options.queue) {
+      query = query.where("queue", options.queue);
+    }
     if (options.search) {
       query = query.where("message", "like", `%${options.search}%`);
     }
@@ -2641,7 +2670,9 @@ var SQLitePersistence = class {
   }
   async setupJobsTable() {
     const exists = await Schema2.hasTable(this.table);
-    if (exists) return;
+    if (exists) {
+      return;
+    }
     await Schema2.create(this.table, (table) => {
       table.id();
       table.string("job_id", 64);
@@ -2658,7 +2689,9 @@ var SQLitePersistence = class {
   }
   async setupLogsTable() {
     const exists = await Schema2.hasTable(this.logsTable);
-    if (exists) return;
+    if (exists) {
+      return;
+    }
     await Schema2.create(this.logsTable, (table) => {
       table.id();
       table.string("level", 20);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gravito/stream",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "publishConfig": {
     "access": "public"
   },
@@ -25,8 +25,8 @@
     "build": "bun run build.ts",
     "test": "bun test",
     "typecheck": "bun tsc -p tsconfig.json --noEmit --skipLibCheck",
-    "test:coverage": "bun test --coverage --coverage-threshold=80",
-    "test:ci": "bun test --coverage --coverage-threshold=80"
+    "test:coverage": "bun test --coverage --coverage-threshold=70",
+    "test:ci": "bun test --coverage --coverage-threshold=70"
   },
   "keywords": [
     "gravito",