@igniter-js/jobs 0.1.14 → 0.1.15

package/AGENTS.md

@@ -27,6 +27,7 @@ In modern distributed systems, background processing is usually the first point
 2. **Resource-Aware Context:** The `withContext()` factory ensures that every job execution starts with a fresh, validated set of resources, exactly like a standard API request.
 3. **Multi-Platform Support (Adapters):** Whether using **BullMQ** for massive production scale or an **In-Memory** adapter for unit tests, the business logic remains identical.
 4. **Native Observability:** Telemetry and internal event publishing are "baked in," providing immediate visibility into enqueuing, execution times, failures, and retries without writing a single line of logging code.
+5. **Typed Job Streams:** Jobs can emit typed per-job stream events for live consumers and optional persisted replay.
 
 ---
 
@@ -55,6 +56,7 @@ Maintainers must respect the following directory structure and responsibilities:
   - `adapter.ts`: `IgniterJobsAdapter` interface.
   - `runtime.ts`: Accessor interfaces for the proxy API.
   - `job.ts`: authoritative types for job definitions, contexts, and hooks.
+  - `stream.ts`: typed per-job stream definitions, emit/read/subscribe contracts, and inference helpers.
 - **`src/utils/`**: Static helper library.
   - `events.utils.ts`: Pub/sub event helpers and channel composition.
   - `id-generator.ts`: Deterministic ID utilities for adapters.

package/README.md

@@ -25,6 +25,7 @@ Background processing is notoriously hard to keep reliable and observable. `@ign
 - ✅ **Runtime validation** — Zod or Standard Schema V1 input validation.
 - ✅ **Scoped jobs** — First-class multi-tenant support via `scope()`.
 - ✅ **Observability built-in** — Telemetry events and pub/sub job lifecycle events.
+- ✅ **Typed job streams** — Emit live per-job stream events with optional persistence and replay.
 - ✅ **Adapter-based backends** — In-memory for tests, SQLite for local, BullMQ for production.
 
 ---
@@ -636,7 +637,42 @@ const queue = IgniterQueue.create("import")
   .build();
 ```
 
-### 44) Job Logs Inspection
+### 44) Typed Job Streams
+
+```typescript
+const queue = IgniterQueue.create("ai")
+  .addJob("generate", {
+    stream: {
+      persistence: { enabled: true, maxEvents: 1000 },
+      events: {
+        "text-delta": z.string(),
+        status: z.object({ phase: z.string() }),
+        done: z.object({ finishReason: z.string() }),
+      },
+    },
+    handler: async ({ job }) => {
+      await job.stream.emit("status", { phase: "thinking" });
+      await job.stream.emit("text-delta", "Hello");
+      await job.stream.emit("done", { finishReason: "stop" });
+      return { ok: true };
+    },
+  })
+  .build();
+
+const jobId = await jobs.ai.generate.dispatch({ input: {} });
+
+const off = await jobs.ai.generate
+  .get(jobId)
+  .stream()
+  .subscribe((event) => {
+    console.log(event.type, event.data);
+  });
+
+const history = await jobs.ai.generate.get(jobId).stream().read({ limit: 100 });
+await off();
+```
+
+### 45) Job Logs Inspection
 
 ```typescript
 const logs = await jobs.email.sendWelcome.get("job-id").logs();
@@ -645,7 +681,7 @@ for (const entry of logs) {
 }
 ```
 
-### 45) Queue List with Paging
+### 46) Queue List with Paging
 
 ```typescript
 const jobsInQueue = await jobs.email.list({
@@ -655,7 +691,7 @@ const jobsInQueue = await jobs.email.list({
 });
 ```
 
-### 46) Worker Limiter Pattern
+### 47) Worker Limiter Pattern
 
 ```typescript
 const worker = await jobs.worker
@@ -665,14 +701,14 @@ const worker = await jobs.worker
   .start();
 ```
 
-### 47) Worker Sharding by Queue
+### 48) Worker Sharding by Queue
 
 ```typescript
 const workerA = await jobs.worker.create().addQueue("email").start();
 const workerB = await jobs.worker.create().addQueue("analytics").start();
 ```
 
-### 48) Graceful Shutdown in Process
+### 49) Graceful Shutdown in Process
 
 ```typescript
 process.on("SIGINT", async () => {

package/dist/{adapter-Cax_40HW.d.mts → adapter-DDyMVche.d.mts}

@@ -127,6 +127,62 @@ type IgniterJobsInferSchemaOutput<TSchema> = TSchema extends StandardSchemaV1 ?
     _output?: infer TOutput;
 } ? TOutput : unknown;
 
+type IgniterJobsJobStreamSchemaMap = Record<string, IgniterJobsSchema>;
+interface IgniterJobsJobStreamPersistenceConfig {
+    enabled: boolean;
+    maxEvents?: number;
+}
+interface IgniterJobsJobStreamDefinition<TEvents extends IgniterJobsJobStreamSchemaMap | undefined = undefined> {
+    persistence?: IgniterJobsJobStreamPersistenceConfig;
+    events?: TEvents;
+}
+interface IgniterJobsJobStreamEvent<TType extends string = string, TData = unknown> {
+    id: string;
+    type: TType;
+    data: TData;
+    timestamp: Date;
+    jobId: string;
+    jobName: string;
+    queue: string;
+    scope?: IgniterJobsScopeEntry;
+}
+interface IgniterJobsJobStreamReadParams {
+    after?: string;
+    limit?: number;
+}
+type IgniterJobsJobStreamReadResult<TEvent extends IgniterJobsJobStreamEvent = IgniterJobsJobStreamEvent> = {
+    items: TEvent[];
+    nextCursor?: string;
+    hasMore: boolean;
+};
+type IgniterJobsStreamEventsFromDefinition<TDef> = TDef extends {
+    stream?: {
+        events?: infer TEvents;
+    };
+} ? TEvents extends IgniterJobsJobStreamSchemaMap ? TEvents : {} : {};
+type IgniterJobsStreamEventKeys<TDef> = Extract<keyof IgniterJobsStreamEventsFromDefinition<TDef>, string>;
+type IgniterJobsInferStreamType<TDef> = [
+    IgniterJobsStreamEventKeys<TDef>
+] extends [never] ? string : IgniterJobsStreamEventKeys<TDef>;
+type IgniterJobsInferStreamEmitData<TDef, TType extends string> = [
+    IgniterJobsStreamEventKeys<TDef>
+] extends [never] ? unknown : TType extends IgniterJobsStreamEventKeys<TDef> ? IgniterJobsInferSchemaInput<IgniterJobsStreamEventsFromDefinition<TDef>[TType]> : unknown;
+type IgniterJobsInferStreamReadData<TDef, TType extends string> = [
+    IgniterJobsStreamEventKeys<TDef>
+] extends [never] ? unknown : TType extends IgniterJobsStreamEventKeys<TDef> ? IgniterJobsInferSchemaOutput<IgniterJobsStreamEventsFromDefinition<TDef>[TType]> : unknown;
+type IgniterJobsInferJobStreamEvent<TDef> = [
+    IgniterJobsStreamEventKeys<TDef>
+] extends [never] ? IgniterJobsJobStreamEvent<string, unknown> : {
+    [K in IgniterJobsStreamEventKeys<TDef>]: IgniterJobsJobStreamEvent<K, IgniterJobsInferStreamReadData<TDef, K>>;
+}[IgniterJobsStreamEventKeys<TDef>];
+interface IgniterJobsExecutionStreamEmitter<TDef = unknown, TType extends string = IgniterJobsInferStreamType<TDef>> {
+    emit<TEventType extends TType>(type: TEventType, data: IgniterJobsInferStreamEmitData<TDef, TEventType>): Promise<string>;
+}
+interface IgniterJobsJobStreamAccessor<TDef = unknown> {
+    subscribe(handler: (event: IgniterJobsInferJobStreamEvent<TDef>) => void | Promise<void>): Promise<() => Promise<void>>;
+    read(params?: IgniterJobsJobStreamReadParams): Promise<IgniterJobsJobStreamReadResult<IgniterJobsInferJobStreamEvent<TDef>>>;
+}
+
 /**
  * Rate limiter configuration applied to job dispatch or worker level.
  */
@@ -152,7 +208,7 @@ interface IgniterJobsInvokeOptions {
 /**
  * Runtime execution context passed to handlers.
  */
-interface IgniterJobsExecutionContext<TContext, TInput extends IgniterJobsSchema | unknown = unknown> {
+interface IgniterJobsExecutionContext<TContext, TInput extends IgniterJobsSchema | unknown = unknown, TStreamEvents extends IgniterJobsJobStreamSchemaMap | undefined = undefined> {
     input: IgniterJobsInferSchemaInput<TInput>;
     context: TContext;
     job: {
@@ -171,45 +227,51 @@ interface IgniterJobsExecutionContext<TContext, TInput extends IgniterJobsSchema
          * Reports job progress and triggers the public progress hook when supported by the adapter.
          */
         updateProgress?: (progress: number, message?: string) => Promise<void>;
+        /**
+         * Emits typed stream events for the current job execution.
+         */
+        stream: IgniterJobsExecutionStreamEmitter<IgniterJobDefinition<TContext, TInput, unknown, TStreamEvents>>;
     };
     scope?: IgniterJobsScopeEntry;
 }
 /**
  * Hook context shared by lifecycle handlers.
  */
-interface IgniterJobsHookContext<TContext, TInput extends IgniterJobsSchema | unknown = unknown> extends IgniterJobsExecutionContext<TContext, TInput> {
+interface IgniterJobsHookContext<TContext, TInput extends IgniterJobsSchema | unknown = unknown, TStreamEvents extends IgniterJobsJobStreamSchemaMap | undefined = undefined> extends IgniterJobsExecutionContext<TContext, TInput, TStreamEvents> {
     startedAt?: Date;
     duration?: number;
 }
-type IgniterJobsStartHook<TContext, TInput extends IgniterJobsSchema | unknown = unknown> = (context: IgniterJobsHookContext<TContext, TInput>) => void | Promise<void>;
-type IgniterJobsSuccessHook<TContext, TInput extends IgniterJobsSchema | unknown = unknown, TResult = unknown> = (context: IgniterJobsHookContext<TContext, TInput> & {
+type IgniterJobsStartHook<TContext, TInput extends IgniterJobsSchema | unknown = unknown, TStreamEvents extends IgniterJobsJobStreamSchemaMap | undefined = undefined> = (context: IgniterJobsHookContext<TContext, TInput, TStreamEvents>) => void | Promise<void>;
+type IgniterJobsSuccessHook<TContext, TInput extends IgniterJobsSchema | unknown = unknown, TResult = unknown, TStreamEvents extends IgniterJobsJobStreamSchemaMap | undefined = undefined> = (context: IgniterJobsHookContext<TContext, TInput, TStreamEvents> & {
     result: TResult;
 }) => void | Promise<void>;
-type IgniterJobsFailureHook<TContext, TInput extends IgniterJobsSchema | unknown = unknown> = (context: IgniterJobsHookContext<TContext, TInput> & {
+type IgniterJobsFailureHook<TContext, TInput extends IgniterJobsSchema | unknown = unknown, TStreamEvents extends IgniterJobsJobStreamSchemaMap | undefined = undefined> = (context: IgniterJobsHookContext<TContext, TInput, TStreamEvents> & {
     error: Error;
     isFinalAttempt: boolean;
 }) => void | Promise<void>;
-type IgniterJobsProgressHook<TContext, TInput extends IgniterJobsSchema | unknown = unknown> = (context: IgniterJobsHookContext<TContext, TInput> & {
+type IgniterJobsProgressHook<TContext, TInput extends IgniterJobsSchema | unknown = unknown, TStreamEvents extends IgniterJobsJobStreamSchemaMap | undefined = undefined> = (context: IgniterJobsHookContext<TContext, TInput, TStreamEvents> & {
     progress: number;
     message?: string;
 }) => void | Promise<void>;
 /**
  * Definition of a job registered on a queue.
  */
-interface IgniterJobDefinition<TContext, TInput extends IgniterJobsSchema | unknown = unknown, TResult = unknown> extends IgniterJobsInvokeOptions {
+interface IgniterJobDefinition<TContext, TInput extends IgniterJobsSchema | unknown = unknown, TResult = unknown, TStreamEvents extends IgniterJobsJobStreamSchemaMap | undefined = undefined> extends IgniterJobsInvokeOptions {
     /** Optional input schema for validation. */
     input?: TInput;
     /** Optional output schema (validation handled externally). */
     output?: IgniterJobsSchema;
     /** Optional queue override (creates child queue in adapters). */
     queue?: string;
+    /** Optional stream configuration for live and persisted per-job events. */
+    stream?: IgniterJobsJobStreamDefinition<TStreamEvents>;
     /** Job handler implementation. */
-    handler: (context: IgniterJobsExecutionContext<TContext, TInput>) => Promise<TResult> | TResult;
+    handler: (context: IgniterJobsExecutionContext<TContext, TInput, TStreamEvents>) => Promise<TResult> | TResult;
     /** Lifecycle hooks */
-    onStart?: IgniterJobsStartHook<TContext, TInput>;
-    onProgress?: IgniterJobsProgressHook<TContext, TInput>;
-    onSuccess?: IgniterJobsSuccessHook<TContext, TInput, TResult>;
-    onFailure?: IgniterJobsFailureHook<TContext, TInput>;
+    onStart?: IgniterJobsStartHook<TContext, TInput, TStreamEvents>;
+    onProgress?: IgniterJobsProgressHook<TContext, TInput, TStreamEvents>;
+    onSuccess?: IgniterJobsSuccessHook<TContext, TInput, TResult, TStreamEvents>;
+    onFailure?: IgniterJobsFailureHook<TContext, TInput, TStreamEvents>;
 }
 /**
  * Definition for cron-style recurring tasks.
@@ -303,11 +365,11 @@ type IgniterJobsScheduleParams<TInput = unknown> = IgniterJobsDispatchParams<TIn
 /**
  * Queue configuration produced by `IgniterQueueBuilder`.
  */
-interface IgniterJobsQueue<TContext, TJobs extends Record<string, IgniterJobDefinition<TContext, any, any>>, TCron extends Record<string, IgniterCronDefinition<TContext, any>>> {
+interface IgniterJobsQueue<TContext, TJobs extends Record<string, IgniterJobDefinition<TContext, any, any, any>>, TCron extends Record<string, IgniterCronDefinition<TContext, any>>> {
     name: string;
     jobs: TJobs;
     crons: TCron;
-    defaultJobOptions?: Partial<IgniterJobDefinition<TContext, any, any>>;
+    defaultJobOptions?: Partial<IgniterJobDefinition<TContext, any, any, any>>;
 }
 /**
  * Information about a queue used by management APIs.
@@ -481,6 +543,25 @@ interface IgniterJobsJobLog {
     message: string;
     level: "info" | "warn" | "error";
 }
+interface IgniterJobsAdapterJobStreamWriteParams {
+    queue: string;
+    jobName: string;
+    jobId: string;
+    scope?: IgniterJobsScopeEntry;
+    persistence?: IgniterJobsJobStreamPersistenceConfig;
+    event: Omit<IgniterJobsJobStreamEvent<string, unknown>, "id">;
+}
+interface IgniterJobsAdapterJobStreamReadParams {
+    queue: string;
+    jobId: string;
+    after?: string;
+    limit?: number;
+}
+interface IgniterJobsAdapterJobStreamSubscribeParams {
+    queue: string;
+    jobId: string;
+    handler: (event: IgniterJobsJobStreamEvent<string, unknown>) => void | Promise<void>;
+}
 /**
  * Adapter contract for jobs backends.
  */
@@ -517,6 +598,9 @@ interface IgniterJobsAdapter {
     getWorkers(): Map<string, IgniterJobsWorkerHandle>;
     publishEvent(channel: string, payload: unknown): Promise<void>;
     subscribeEvent(channel: string, handler: IgniterJobsEventHandler): Promise<() => Promise<void>>;
+    writeJobStreamEvent(params: IgniterJobsAdapterJobStreamWriteParams): Promise<string>;
+    readJobStream(params: IgniterJobsAdapterJobStreamReadParams): Promise<IgniterJobsJobStreamReadResult<IgniterJobsJobStreamEvent<string, unknown>>>;
+    subscribeJobStream(params: IgniterJobsAdapterJobStreamSubscribeParams): Promise<() => Promise<void>>;
     registerJob(queueName: string, jobName: string, definition: IgniterJobDefinition<any, any, any>): void;
     registerCron(queueName: string, cronName: string, definition: IgniterCronDefinition<any, any>): void;
     shutdown(): Promise<void>;
@@ -547,4 +631,4 @@ interface IgniterJobsBunSQLiteAdapterOptions {
     maxStalledCount?: number;
 }
 
-export type { IgniterJobsExecutionContext as A, IgniterJobsFailureHook as B, IgniterJobsHookContext as C, IgniterJobsInferSchemaOutput as D, IgniterJobsInvokeOptions as E, IgniterJobsJobLog as F, IgniterJobsProgressHook as G, IgniterJobsQueueManager as H, IgniterJobsQueue as I, IgniterJobsScheduleOptions as J, IgniterJobsStartHook as K, IgniterJobsSuccessHook as L, IgniterJobsWorkerMetrics as M, IgniterJobsAdapter as a, IgniterJobsScopeDefinition as b, IgniterJobDefinition as c, IgniterJobsWorkerBuilderConfig as d, IgniterJobsTelemetry as e, IgniterJobsEventHandler as f, IgniterJobSearchResult as g, IgniterJobsQueueInfo as h, IgniterJobsWorkerHandle as i, IgniterJobsLimiter as j, IgniterJobsWorkerHandlers as k, IgniterJobsQueueCleanOptions as l, IgniterJobStatus as m, IgniterJobsDispatchParams as n, IgniterJobsScheduleParams as o, IgniterJobsInferSchemaInput as p, IgniterCronDefinition as q, IgniterJobsScopeEntry as r, IgniterJobsSchema as s, IgniterJobsScopeOptions as t, IgniterJobCounts as u, IgniterJobsAdapterDispatchParams as v, IgniterJobsAdapterScheduleParams as w, IgniterJobsBullMQAdapterOptions as x, IgniterJobsBunSQLiteAdapterOptions as y, IgniterJobsEvent as z };
+export type { IgniterJobsSuccessHook as $, IgniterJobsAdapterJobStreamWriteParams as A, IgniterJobsAdapterScheduleParams as B, IgniterJobsBullMQAdapterOptions as C, IgniterJobsBunSQLiteAdapterOptions as D, IgniterJobsEvent as E, IgniterJobsExecutionContext as F, IgniterJobsExecutionStreamEmitter as G, IgniterJobsFailureHook as H, IgniterJobsQueue as I, IgniterJobsHookContext as J, IgniterJobsInferJobStreamEvent as K, IgniterJobsInferSchemaOutput as L, IgniterJobsInferStreamEmitData as M, IgniterJobsInferStreamReadData as N, IgniterJobsInferStreamType as O, IgniterJobsInvokeOptions as P, IgniterJobsJobLog as Q, IgniterJobsJobStreamDefinition as R, IgniterJobsJobStreamEvent as S, IgniterJobsJobStreamPersistenceConfig as T, IgniterJobsJobStreamReadParams as U, IgniterJobsJobStreamReadResult as V, IgniterJobsProgressHook as W, IgniterJobsQueueManager as X, IgniterJobsScheduleOptions as Y, IgniterJobsStartHook as Z, IgniterJobsStreamEventsFromDefinition as _, IgniterJobsAdapter as a, IgniterJobsWorkerMetrics as a0, IgniterJobsScopeDefinition as b, IgniterJobDefinition as c, IgniterJobsWorkerBuilderConfig as d, IgniterJobsTelemetry as e, IgniterJobsEventHandler as f, IgniterJobSearchResult as g, IgniterJobsQueueInfo as h, IgniterJobsWorkerHandle as i, IgniterJobsLimiter as j, IgniterJobsWorkerHandlers as k, IgniterJobsQueueCleanOptions as l, IgniterJobStatus as m, IgniterJobsDispatchParams as n, IgniterJobsInferSchemaInput as o, IgniterJobsScheduleParams as p, IgniterJobsJobStreamAccessor as q, IgniterCronDefinition as r, IgniterJobsScopeEntry as s, IgniterJobsSchema as t, IgniterJobsJobStreamSchemaMap as u, IgniterJobsScopeOptions as v, IgniterJobCounts as w, IgniterJobsAdapterDispatchParams as x, IgniterJobsAdapterJobStreamReadParams as y, IgniterJobsAdapterJobStreamSubscribeParams as z };

package/dist/{adapter-Cax_40HW.d.ts → adapter-DDyMVche.d.ts}

@@ -127,6 +127,62 @@ type IgniterJobsInferSchemaOutput<TSchema> = TSchema extends StandardSchemaV1 ?
     _output?: infer TOutput;
 } ? TOutput : unknown;
 
+type IgniterJobsJobStreamSchemaMap = Record<string, IgniterJobsSchema>;
+interface IgniterJobsJobStreamPersistenceConfig {
+    enabled: boolean;
+    maxEvents?: number;
+}
+interface IgniterJobsJobStreamDefinition<TEvents extends IgniterJobsJobStreamSchemaMap | undefined = undefined> {
+    persistence?: IgniterJobsJobStreamPersistenceConfig;
+    events?: TEvents;
+}
+interface IgniterJobsJobStreamEvent<TType extends string = string, TData = unknown> {
+    id: string;
+    type: TType;
+    data: TData;
+    timestamp: Date;
+    jobId: string;
+    jobName: string;
+    queue: string;
+    scope?: IgniterJobsScopeEntry;
+}
+interface IgniterJobsJobStreamReadParams {
+    after?: string;
+    limit?: number;
+}
+type IgniterJobsJobStreamReadResult<TEvent extends IgniterJobsJobStreamEvent = IgniterJobsJobStreamEvent> = {
+    items: TEvent[];
+    nextCursor?: string;
+    hasMore: boolean;
+};
+type IgniterJobsStreamEventsFromDefinition<TDef> = TDef extends {
+    stream?: {
+        events?: infer TEvents;
+    };
+} ? TEvents extends IgniterJobsJobStreamSchemaMap ? TEvents : {} : {};
+type IgniterJobsStreamEventKeys<TDef> = Extract<keyof IgniterJobsStreamEventsFromDefinition<TDef>, string>;
+type IgniterJobsInferStreamType<TDef> = [
+    IgniterJobsStreamEventKeys<TDef>
+] extends [never] ? string : IgniterJobsStreamEventKeys<TDef>;
+type IgniterJobsInferStreamEmitData<TDef, TType extends string> = [
+    IgniterJobsStreamEventKeys<TDef>
+] extends [never] ? unknown : TType extends IgniterJobsStreamEventKeys<TDef> ? IgniterJobsInferSchemaInput<IgniterJobsStreamEventsFromDefinition<TDef>[TType]> : unknown;
+type IgniterJobsInferStreamReadData<TDef, TType extends string> = [
+    IgniterJobsStreamEventKeys<TDef>
+] extends [never] ? unknown : TType extends IgniterJobsStreamEventKeys<TDef> ? IgniterJobsInferSchemaOutput<IgniterJobsStreamEventsFromDefinition<TDef>[TType]> : unknown;
+type IgniterJobsInferJobStreamEvent<TDef> = [
+    IgniterJobsStreamEventKeys<TDef>
+] extends [never] ? IgniterJobsJobStreamEvent<string, unknown> : {
+    [K in IgniterJobsStreamEventKeys<TDef>]: IgniterJobsJobStreamEvent<K, IgniterJobsInferStreamReadData<TDef, K>>;
+}[IgniterJobsStreamEventKeys<TDef>];
+interface IgniterJobsExecutionStreamEmitter<TDef = unknown, TType extends string = IgniterJobsInferStreamType<TDef>> {
+    emit<TEventType extends TType>(type: TEventType, data: IgniterJobsInferStreamEmitData<TDef, TEventType>): Promise<string>;
+}
+interface IgniterJobsJobStreamAccessor<TDef = unknown> {
+    subscribe(handler: (event: IgniterJobsInferJobStreamEvent<TDef>) => void | Promise<void>): Promise<() => Promise<void>>;
+    read(params?: IgniterJobsJobStreamReadParams): Promise<IgniterJobsJobStreamReadResult<IgniterJobsInferJobStreamEvent<TDef>>>;
+}
+
 /**
  * Rate limiter configuration applied to job dispatch or worker level.
  */
@@ -152,7 +208,7 @@ interface IgniterJobsInvokeOptions {
 /**
  * Runtime execution context passed to handlers.
  */
-interface IgniterJobsExecutionContext<TContext, TInput extends IgniterJobsSchema | unknown = unknown> {
+interface IgniterJobsExecutionContext<TContext, TInput extends IgniterJobsSchema | unknown = unknown, TStreamEvents extends IgniterJobsJobStreamSchemaMap | undefined = undefined> {
     input: IgniterJobsInferSchemaInput<TInput>;
     context: TContext;
     job: {
@@ -171,45 +227,51 @@ interface IgniterJobsExecutionContext<TContext, TInput extends IgniterJobsSchema
          * Reports job progress and triggers the public progress hook when supported by the adapter.
          */
         updateProgress?: (progress: number, message?: string) => Promise<void>;
+        /**
+         * Emits typed stream events for the current job execution.
+         */
+        stream: IgniterJobsExecutionStreamEmitter<IgniterJobDefinition<TContext, TInput, unknown, TStreamEvents>>;
     };
     scope?: IgniterJobsScopeEntry;
 }
 /**
  * Hook context shared by lifecycle handlers.
  */
-interface IgniterJobsHookContext<TContext, TInput extends IgniterJobsSchema | unknown = unknown> extends IgniterJobsExecutionContext<TContext, TInput> {
+interface IgniterJobsHookContext<TContext, TInput extends IgniterJobsSchema | unknown = unknown, TStreamEvents extends IgniterJobsJobStreamSchemaMap | undefined = undefined> extends IgniterJobsExecutionContext<TContext, TInput, TStreamEvents> {
     startedAt?: Date;
     duration?: number;
 }
-type IgniterJobsStartHook<TContext, TInput extends IgniterJobsSchema | unknown = unknown> = (context: IgniterJobsHookContext<TContext, TInput>) => void | Promise<void>;
-type IgniterJobsSuccessHook<TContext, TInput extends IgniterJobsSchema | unknown = unknown, TResult = unknown> = (context: IgniterJobsHookContext<TContext, TInput> & {
+type IgniterJobsStartHook<TContext, TInput extends IgniterJobsSchema | unknown = unknown, TStreamEvents extends IgniterJobsJobStreamSchemaMap | undefined = undefined> = (context: IgniterJobsHookContext<TContext, TInput, TStreamEvents>) => void | Promise<void>;
+type IgniterJobsSuccessHook<TContext, TInput extends IgniterJobsSchema | unknown = unknown, TResult = unknown, TStreamEvents extends IgniterJobsJobStreamSchemaMap | undefined = undefined> = (context: IgniterJobsHookContext<TContext, TInput, TStreamEvents> & {
     result: TResult;
 }) => void | Promise<void>;
-type IgniterJobsFailureHook<TContext, TInput extends IgniterJobsSchema | unknown = unknown> = (context: IgniterJobsHookContext<TContext, TInput> & {
+type IgniterJobsFailureHook<TContext, TInput extends IgniterJobsSchema | unknown = unknown, TStreamEvents extends IgniterJobsJobStreamSchemaMap | undefined = undefined> = (context: IgniterJobsHookContext<TContext, TInput, TStreamEvents> & {
     error: Error;
     isFinalAttempt: boolean;
 }) => void | Promise<void>;
-type IgniterJobsProgressHook<TContext, TInput extends IgniterJobsSchema | unknown = unknown> = (context: IgniterJobsHookContext<TContext, TInput> & {
+type IgniterJobsProgressHook<TContext, TInput extends IgniterJobsSchema | unknown = unknown, TStreamEvents extends IgniterJobsJobStreamSchemaMap | undefined = undefined> = (context: IgniterJobsHookContext<TContext, TInput, TStreamEvents> & {
     progress: number;
     message?: string;
 }) => void | Promise<void>;
 /**
  * Definition of a job registered on a queue.
  */
-interface IgniterJobDefinition<TContext, TInput extends IgniterJobsSchema | unknown = unknown, TResult = unknown> extends IgniterJobsInvokeOptions {
+interface IgniterJobDefinition<TContext, TInput extends IgniterJobsSchema | unknown = unknown, TResult = unknown, TStreamEvents extends IgniterJobsJobStreamSchemaMap | undefined = undefined> extends IgniterJobsInvokeOptions {
     /** Optional input schema for validation. */
     input?: TInput;
     /** Optional output schema (validation handled externally). */
     output?: IgniterJobsSchema;
     /** Optional queue override (creates child queue in adapters). */
     queue?: string;
+    /** Optional stream configuration for live and persisted per-job events. */
+    stream?: IgniterJobsJobStreamDefinition<TStreamEvents>;
     /** Job handler implementation. */
-    handler: (context: IgniterJobsExecutionContext<TContext, TInput>) => Promise<TResult> | TResult;
+    handler: (context: IgniterJobsExecutionContext<TContext, TInput, TStreamEvents>) => Promise<TResult> | TResult;
     /** Lifecycle hooks */
-    onStart?: IgniterJobsStartHook<TContext, TInput>;
-    onProgress?: IgniterJobsProgressHook<TContext, TInput>;
-    onSuccess?: IgniterJobsSuccessHook<TContext, TInput, TResult>;
-    onFailure?: IgniterJobsFailureHook<TContext, TInput>;
+    onStart?: IgniterJobsStartHook<TContext, TInput, TStreamEvents>;
+    onProgress?: IgniterJobsProgressHook<TContext, TInput, TStreamEvents>;
+    onSuccess?: IgniterJobsSuccessHook<TContext, TInput, TResult, TStreamEvents>;
+    onFailure?: IgniterJobsFailureHook<TContext, TInput, TStreamEvents>;
 }
 /**
  * Definition for cron-style recurring tasks.
@@ -303,11 +365,11 @@ type IgniterJobsScheduleParams<TInput = unknown> = IgniterJobsDispatchParams<TIn
 /**
  * Queue configuration produced by `IgniterQueueBuilder`.
  */
-interface IgniterJobsQueue<TContext, TJobs extends Record<string, IgniterJobDefinition<TContext, any, any>>, TCron extends Record<string, IgniterCronDefinition<TContext, any>>> {
+interface IgniterJobsQueue<TContext, TJobs extends Record<string, IgniterJobDefinition<TContext, any, any, any>>, TCron extends Record<string, IgniterCronDefinition<TContext, any>>> {
     name: string;
     jobs: TJobs;
     crons: TCron;
-    defaultJobOptions?: Partial<IgniterJobDefinition<TContext, any, any>>;
+    defaultJobOptions?: Partial<IgniterJobDefinition<TContext, any, any, any>>;
 }
 /**
  * Information about a queue used by management APIs.
@@ -481,6 +543,25 @@ interface IgniterJobsJobLog {
     message: string;
     level: "info" | "warn" | "error";
 }
+interface IgniterJobsAdapterJobStreamWriteParams {
+    queue: string;
+    jobName: string;
+    jobId: string;
+    scope?: IgniterJobsScopeEntry;
+    persistence?: IgniterJobsJobStreamPersistenceConfig;
+    event: Omit<IgniterJobsJobStreamEvent<string, unknown>, "id">;
+}
+interface IgniterJobsAdapterJobStreamReadParams {
+    queue: string;
+    jobId: string;
+    after?: string;
+    limit?: number;
+}
+interface IgniterJobsAdapterJobStreamSubscribeParams {
+    queue: string;
+    jobId: string;
+    handler: (event: IgniterJobsJobStreamEvent<string, unknown>) => void | Promise<void>;
+}
 /**
  * Adapter contract for jobs backends.
  */
@@ -517,6 +598,9 @@ interface IgniterJobsAdapter {
     getWorkers(): Map<string, IgniterJobsWorkerHandle>;
     publishEvent(channel: string, payload: unknown): Promise<void>;
     subscribeEvent(channel: string, handler: IgniterJobsEventHandler): Promise<() => Promise<void>>;
+    writeJobStreamEvent(params: IgniterJobsAdapterJobStreamWriteParams): Promise<string>;
+    readJobStream(params: IgniterJobsAdapterJobStreamReadParams): Promise<IgniterJobsJobStreamReadResult<IgniterJobsJobStreamEvent<string, unknown>>>;
+    subscribeJobStream(params: IgniterJobsAdapterJobStreamSubscribeParams): Promise<() => Promise<void>>;
     registerJob(queueName: string, jobName: string, definition: IgniterJobDefinition<any, any, any>): void;
     registerCron(queueName: string, cronName: string, definition: IgniterCronDefinition<any, any>): void;
     shutdown(): Promise<void>;
@@ -547,4 +631,4 @@ interface IgniterJobsBunSQLiteAdapterOptions {
     maxStalledCount?: number;
 }
 
-export type { IgniterJobsExecutionContext as A, IgniterJobsFailureHook as B, IgniterJobsHookContext as C, IgniterJobsInferSchemaOutput as D, IgniterJobsInvokeOptions as E, IgniterJobsJobLog as F, IgniterJobsProgressHook as G, IgniterJobsQueueManager as H, IgniterJobsQueue as I, IgniterJobsScheduleOptions as J, IgniterJobsStartHook as K, IgniterJobsSuccessHook as L, IgniterJobsWorkerMetrics as M, IgniterJobsAdapter as a, IgniterJobsScopeDefinition as b, IgniterJobDefinition as c, IgniterJobsWorkerBuilderConfig as d, IgniterJobsTelemetry as e, IgniterJobsEventHandler as f, IgniterJobSearchResult as g, IgniterJobsQueueInfo as h, IgniterJobsWorkerHandle as i, IgniterJobsLimiter as j, IgniterJobsWorkerHandlers as k, IgniterJobsQueueCleanOptions as l, IgniterJobStatus as m, IgniterJobsDispatchParams as n, IgniterJobsScheduleParams as o, IgniterJobsInferSchemaInput as p, IgniterCronDefinition as q, IgniterJobsScopeEntry as r, IgniterJobsSchema as s, IgniterJobsScopeOptions as t, IgniterJobCounts as u, IgniterJobsAdapterDispatchParams as v, IgniterJobsAdapterScheduleParams as w, IgniterJobsBullMQAdapterOptions as x, IgniterJobsBunSQLiteAdapterOptions as y, IgniterJobsEvent as z };
+export type { IgniterJobsSuccessHook as $, IgniterJobsAdapterJobStreamWriteParams as A, IgniterJobsAdapterScheduleParams as B, IgniterJobsBullMQAdapterOptions as C, IgniterJobsBunSQLiteAdapterOptions as D, IgniterJobsEvent as E, IgniterJobsExecutionContext as F, IgniterJobsExecutionStreamEmitter as G, IgniterJobsFailureHook as H, IgniterJobsQueue as I, IgniterJobsHookContext as J, IgniterJobsInferJobStreamEvent as K, IgniterJobsInferSchemaOutput as L, IgniterJobsInferStreamEmitData as M, IgniterJobsInferStreamReadData as N, IgniterJobsInferStreamType as O, IgniterJobsInvokeOptions as P, IgniterJobsJobLog as Q, IgniterJobsJobStreamDefinition as R, IgniterJobsJobStreamEvent as S, IgniterJobsJobStreamPersistenceConfig as T, IgniterJobsJobStreamReadParams as U, IgniterJobsJobStreamReadResult as V, IgniterJobsProgressHook as W, IgniterJobsQueueManager as X, IgniterJobsScheduleOptions as Y, IgniterJobsStartHook as Z, IgniterJobsStreamEventsFromDefinition as _, IgniterJobsAdapter as a, IgniterJobsWorkerMetrics as a0, IgniterJobsScopeDefinition as b, IgniterJobDefinition as c, IgniterJobsWorkerBuilderConfig as d, IgniterJobsTelemetry as e, IgniterJobsEventHandler as f, IgniterJobSearchResult as g, IgniterJobsQueueInfo as h, IgniterJobsWorkerHandle as i, IgniterJobsLimiter as j, IgniterJobsWorkerHandlers as k, IgniterJobsQueueCleanOptions as l, IgniterJobStatus as m, IgniterJobsDispatchParams as n, IgniterJobsInferSchemaInput as o, IgniterJobsScheduleParams as p, IgniterJobsJobStreamAccessor as q, IgniterCronDefinition as r, IgniterJobsScopeEntry as s, IgniterJobsSchema as t, IgniterJobsJobStreamSchemaMap as u, IgniterJobsScopeOptions as v, IgniterJobCounts as w, IgniterJobsAdapterDispatchParams as x, IgniterJobsAdapterJobStreamReadParams as y, IgniterJobsAdapterJobStreamSubscribeParams as z };

package/dist/adapters/bun.d.mts

@@ -1,4 +1,4 @@
-import { a as IgniterJobsAdapter, H as IgniterJobsQueueManager, y as IgniterJobsBunSQLiteAdapterOptions, c as IgniterJobDefinition, q as IgniterCronDefinition, v as IgniterJobsAdapterDispatchParams, w as IgniterJobsAdapterScheduleParams, g as IgniterJobSearchResult, m as IgniterJobStatus, F as IgniterJobsJobLog, h as IgniterJobsQueueInfo, u as IgniterJobCounts, l as IgniterJobsQueueCleanOptions, i as IgniterJobsWorkerHandle, d as IgniterJobsWorkerBuilderConfig, f as IgniterJobsEventHandler } from '../adapter-Cax_40HW.mjs';
+import { a as IgniterJobsAdapter, X as IgniterJobsQueueManager, D as IgniterJobsBunSQLiteAdapterOptions, c as IgniterJobDefinition, r as IgniterCronDefinition, x as IgniterJobsAdapterDispatchParams, B as IgniterJobsAdapterScheduleParams, g as IgniterJobSearchResult, m as IgniterJobStatus, Q as IgniterJobsJobLog, h as IgniterJobsQueueInfo, w as IgniterJobCounts, l as IgniterJobsQueueCleanOptions, i as IgniterJobsWorkerHandle, d as IgniterJobsWorkerBuilderConfig, f as IgniterJobsEventHandler, A as IgniterJobsAdapterJobStreamWriteParams, y as IgniterJobsAdapterJobStreamReadParams, V as IgniterJobsJobStreamReadResult, S as IgniterJobsJobStreamEvent, z as IgniterJobsAdapterJobStreamSubscribeParams } from '../adapter-DDyMVche.mjs';
 import 'ioredis';
 import '@igniter-js/common';
 
@@ -21,7 +21,9 @@ declare class IgniterJobsBunSQLiteAdapter implements IgniterJobsAdapter {
     private readonly queueRuntimes;
     private readonly workers;
     private readonly subscribers;
+    private readonly streamSubscribers;
     private readonly registeredJobs;
+    private streamDatabasePromise;
     private readonly registeredCrons;
     private constructor();
     static create(options: IgniterJobsBunSQLiteAdapterOptions): IgniterJobsAdapter;
@@ -57,8 +59,12 @@ declare class IgniterJobsBunSQLiteAdapter implements IgniterJobsAdapter {
     getWorkers(): Map<string, IgniterJobsWorkerHandle>;
     publishEvent(channel: string, payload: unknown): Promise<void>;
     subscribeEvent(channel: string, handler: IgniterJobsEventHandler): Promise<() => Promise<void>>;
+    writeJobStreamEvent(params: IgniterJobsAdapterJobStreamWriteParams): Promise<string>;
+    readJobStream(params: IgniterJobsAdapterJobStreamReadParams): Promise<IgniterJobsJobStreamReadResult<IgniterJobsJobStreamEvent<string, unknown>>>;
+    subscribeJobStream(params: IgniterJobsAdapterJobStreamSubscribeParams): Promise<() => Promise<void>>;
     shutdown(): Promise<void>;
     private loadBunqueue;
+    private getStreamDatabase;
     private getQueue;
     private getAllQueueNames;
     private markQueueCronsDirty;
@@ -75,6 +81,8 @@ declare class IgniterJobsBunSQLiteAdapter implements IgniterJobsAdapter {
     private closeWorkerState;
     private requireJob;
     private findQueueByJobId;
+    private getStreamKey;
+    private mapStreamRow;
     private mapJob;
     private mapJobSync;
     private normalizeEnvelope;

package/dist/adapters/bun.d.ts

@@ -1,4 +1,4 @@
-import { a as IgniterJobsAdapter, H as IgniterJobsQueueManager, y as IgniterJobsBunSQLiteAdapterOptions, c as IgniterJobDefinition, q as IgniterCronDefinition, v as IgniterJobsAdapterDispatchParams, w as IgniterJobsAdapterScheduleParams, g as IgniterJobSearchResult, m as IgniterJobStatus, F as IgniterJobsJobLog, h as IgniterJobsQueueInfo, u as IgniterJobCounts, l as IgniterJobsQueueCleanOptions, i as IgniterJobsWorkerHandle, d as IgniterJobsWorkerBuilderConfig, f as IgniterJobsEventHandler } from '../adapter-Cax_40HW.js';
+import { a as IgniterJobsAdapter, X as IgniterJobsQueueManager, D as IgniterJobsBunSQLiteAdapterOptions, c as IgniterJobDefinition, r as IgniterCronDefinition, x as IgniterJobsAdapterDispatchParams, B as IgniterJobsAdapterScheduleParams, g as IgniterJobSearchResult, m as IgniterJobStatus, Q as IgniterJobsJobLog, h as IgniterJobsQueueInfo, w as IgniterJobCounts, l as IgniterJobsQueueCleanOptions, i as IgniterJobsWorkerHandle, d as IgniterJobsWorkerBuilderConfig, f as IgniterJobsEventHandler, A as IgniterJobsAdapterJobStreamWriteParams, y as IgniterJobsAdapterJobStreamReadParams, V as IgniterJobsJobStreamReadResult, S as IgniterJobsJobStreamEvent, z as IgniterJobsAdapterJobStreamSubscribeParams } from '../adapter-DDyMVche.js';
 import 'ioredis';
 import '@igniter-js/common';
 
@@ -21,7 +21,9 @@ declare class IgniterJobsBunSQLiteAdapter implements IgniterJobsAdapter {
     private readonly queueRuntimes;
     private readonly workers;
     private readonly subscribers;
+    private readonly streamSubscribers;
     private readonly registeredJobs;
+    private streamDatabasePromise;
     private readonly registeredCrons;
     private constructor();
     static create(options: IgniterJobsBunSQLiteAdapterOptions): IgniterJobsAdapter;
@@ -57,8 +59,12 @@ declare class IgniterJobsBunSQLiteAdapter implements IgniterJobsAdapter {
     getWorkers(): Map<string, IgniterJobsWorkerHandle>;
     publishEvent(channel: string, payload: unknown): Promise<void>;
     subscribeEvent(channel: string, handler: IgniterJobsEventHandler): Promise<() => Promise<void>>;
+    writeJobStreamEvent(params: IgniterJobsAdapterJobStreamWriteParams): Promise<string>;
+    readJobStream(params: IgniterJobsAdapterJobStreamReadParams): Promise<IgniterJobsJobStreamReadResult<IgniterJobsJobStreamEvent<string, unknown>>>;
+    subscribeJobStream(params: IgniterJobsAdapterJobStreamSubscribeParams): Promise<() => Promise<void>>;
     shutdown(): Promise<void>;
     private loadBunqueue;
+    private getStreamDatabase;
     private getQueue;
     private getAllQueueNames;
     private markQueueCronsDirty;
@@ -75,6 +81,8 @@ declare class IgniterJobsBunSQLiteAdapter implements IgniterJobsAdapter {
     private closeWorkerState;
     private requireJob;
     private findQueueByJobId;
+    private getStreamKey;
+    private mapStreamRow;
     private mapJob;
     private mapJobSync;
     private normalizeEnvelope;