yaxa-svelte 2.2.0 → 2.4.0

package/dist/server/db/schema-sqlite.js

@@ -146,3 +146,23 @@ export const subscription = sqliteTable('subscription', {
     createdAt: integer('created_at', { mode: 'timestamp' }).notNull(),
     updatedAt: integer('updated_at', { mode: 'timestamp' }).notNull()
 });
+// ---------------------------------------------------------------------------
+// Background Jobs & Workflows Queue (SQLite / Turso)
+// ---------------------------------------------------------------------------
+export const job = sqliteTable('yaxa_job', {
+    id: text('id').primaryKey(),
+    queue: text('queue').notNull().default('default'),
+    name: text('name').notNull(),
+    payload: text('payload').notNull(),
+    status: text('status').notNull().default('pending'), // 'pending' | 'processing' | 'completed' | 'failed'
+    priority: integer('priority').notNull().default(0),
+    attempts: integer('attempts').notNull().default(0),
+    maxAttempts: integer('max_attempts').notNull().default(3),
+    runAt: integer('run_at', { mode: 'timestamp' }).notNull(),
+    lockedAt: integer('locked_at', { mode: 'timestamp' }),
+    lockedBy: text('locked_by'),
+    failedReason: text('failed_reason'),
+    createdAt: integer('created_at', { mode: 'timestamp' }).notNull(),
+    updatedAt: integer('updated_at', { mode: 'timestamp' }).notNull(),
+    completedAt: integer('completed_at', { mode: 'timestamp' })
+});

package/dist/server/db/types.d.ts

@@ -70,3 +70,21 @@ export interface PricingTier {
     buttonText?: string;
     features: (string | PricingFeature)[];
 }
+export type JobStatus = 'pending' | 'processing' | 'completed' | 'failed';
+export interface YaxaJob<TPayload = any> {
+    id: string;
+    queue: string;
+    name: string;
+    payload: TPayload;
+    status: JobStatus;
+    priority: number;
+    attempts: number;
+    maxAttempts: number;
+    runAt: Date;
+    lockedAt?: Date | null;
+    lockedBy?: string | null;
+    failedReason?: string | null;
+    createdAt: Date;
+    updatedAt: Date;
+    completedAt?: Date | null;
+}

package/dist/server/endpoint/guards.d.ts

@@ -11,6 +11,11 @@ export interface RequireAuthOptions {
      */
     detail?: string;
 }
+export interface YaxaGuardMetadata {
+    type: 'auth' | 'role' | 'rateLimit' | string;
+    roles?: string[];
+    options?: any;
+}
 /**
  * Declarative Guard: Enforces that the request has an active authenticated user in `event.locals.user`.
  */

package/dist/server/endpoint/guards.js

@@ -4,7 +4,7 @@ import { problemResponse } from './problem';
  * Declarative Guard: Enforces that the request has an active authenticated user in `event.locals.user`.
  */
 export function requireAuth(options = {}) {
-    return (event) => {
+    const guard = (event) => {
         const user = event.locals?.user;
         if (!user) {
             if (options.redirect) {
@@ -22,6 +22,11 @@ export function requireAuth(options = {}) {
             });
         }
     };
+    guard._yaxaGuard = {
+        type: 'auth',
+        options
+    };
+    return guard;
 }
 /**
  * Declarative Guard: Enforces that the active user/member possesses one of the allowed roles.
@@ -29,7 +34,7 @@ export function requireAuth(options = {}) {
  */
 export function requireRole(roles, options = {}) {
     const allowedRoles = Array.isArray(roles) ? roles : [roles];
-    return (event) => {
+    const guard = (event) => {
         const locals = event.locals;
         const user = locals?.user;
         if (!user) {
@@ -54,6 +59,12 @@ export function requireRole(roles, options = {}) {
             });
         }
     };
+    guard._yaxaGuard = {
+        type: 'role',
+        roles: allowedRoles,
+        options
+    };
+    return guard;
 }
 const rateLimitStore = new Map();
 // Periodic cleanup of stale rate-limit buckets (every 5 minutes)
@@ -77,7 +88,7 @@ if (typeof setInterval !== 'undefined') {
 export function rateLimit(options = {}) {
     const points = options.points ?? 60;
     const windowMs = (options.windowSeconds ?? 60) * 1000;
-    return (event) => {
+    const guard = (event) => {
         let key;
         if (options.keyGenerator) {
             key = options.keyGenerator(event);
@@ -122,6 +133,11 @@ export function rateLimit(options = {}) {
         }
         bucket.tokens -= 1;
     };
+    guard._yaxaGuard = {
+        type: 'rateLimit',
+        options: { points, windowSeconds: options.windowSeconds ?? 60 }
+    };
+    return guard;
 }
 /**
  * Combines multiple guards into a single composite guard.

package/dist/server/endpoint/index.js

@@ -1,5 +1,6 @@
 import { isProblemDetails, problemResponse } from './problem';
 import { validateData } from './validate';
+import { globalApiRegistry } from '../openapi/registry';
 /**
  * Parses URLSearchParams into a plain key-value object.
  * Duplicate keys are parsed into arrays.
@@ -230,6 +231,9 @@ export function yaxaEndpoint(config) {
     };
     // Attach configuration metadata for runtime reflection and OpenAPI generation (Milestone 3)
     handler._yaxaConfig = config;
+    if (config.path && config.method) {
+        globalApiRegistry.register(config.path, { [config.method]: handler });
+    }
     return handler;
 }
 export * from './types';

package/dist/server/endpoint/types.d.ts

@@ -137,6 +137,13 @@ export interface YaxaEndpointConfig<TBodySchema = any, TQuerySchema = any, TPara
     description?: string;
     tags?: string[];
     deprecated?: boolean;
+    operationId?: string;
+    path?: string;
+    method?: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | string;
+    responses?: Record<number, {
+        description: string;
+        schema?: any;
+    }>;
     /**
      * Core business logic handler.
      */

package/dist/server/index.d.ts

@@ -24,3 +24,7 @@ export { getS3Client, createPresignedUploadUrl, createS3UploadHandler } from './
 export type { S3StorageConfig, PresignedUploadOptions, PresignedUploadResult, S3UploadHandlerOptions } from './storage/index';
 export { yaxaEndpoint, createProblemDetails, problemResponse, isProblemDetails, requireAuth, requireRole, rateLimit, composeGuards, validateData } from './endpoint/index';
 export type { YaxaEndpointConfig, YaxaEndpointContext, YaxaEndpointSchemaConfig, YaxaInterceptor, Guard, GuardResult, ProblemDetails, CreateProblemOptions, RequireAuthOptions, RequireRoleOptions, RateLimitOptions, AnyValidator, InferValidatorOutput, ValidationOutcome, ValidationSuccess, ValidationFailure } from './endpoint/index';
+export { generateOpenApiSpec, createApiDocsHandler, createApiRegistry, globalApiRegistry, convertToJsonSchema } from './openapi/index';
+export type { OpenApiSpec31, OpenApiOperation, OpenApiParameter, OpenApiRequestBody, OpenApiResponse, GenerateOpenApiOptions, ApiDocsOptions, ApiDocsTheme, EndpointLike, EndpointMap } from './openapi/index';
+export { enqueueJob, defineWorker, createJobRunner, eventBus, EventBus, parseJobDelay } from './jobs/index';
+export type { JobRecord, JobDelay, EnqueueJobOptions, WorkerContext, WorkerHandler, WorkerDefinition, JobRunnerOptions, JobBatchResult, JobRunner, EventHandler, EventSubscription, IEventBus } from './jobs/index';

package/dist/server/index.js

@@ -20,3 +20,7 @@ export { getResendClient, sendMagicLinkEmail, sendWelcomeEmail } from './email/i
 export { getS3Client, createPresignedUploadUrl, createS3UploadHandler } from './storage/index';
 // Endpoint Pipeline, Guards & RFC 7807 Validation (Milestone 1)
 export { yaxaEndpoint, createProblemDetails, problemResponse, isProblemDetails, requireAuth, requireRole, rateLimit, composeGuards, validateData } from './endpoint/index';
+// Auto-Generated OpenAPI 3.1 & Interactive Docs (Milestone 3)
+export { generateOpenApiSpec, createApiDocsHandler, createApiRegistry, globalApiRegistry, convertToJsonSchema } from './openapi/index';
+// Embedded Background Workflows, Job Queue & Domain Events (Milestone 6)
+export { enqueueJob, defineWorker, createJobRunner, eventBus, EventBus, parseJobDelay } from './jobs/index';

package/dist/server/jobs/events.d.ts

@@ -0,0 +1,29 @@
+import type { EventHandler, EventSubscription, IEventBus } from './types';
+/**
+ * In-process Domain Event Bus for decoupled asynchronous event notifications.
+ */
+export declare class EventBus implements IEventBus {
+    private subscribers;
+    private counter;
+    /**
+     * Subscribes a handler to an event.
+     */
+    subscribe<TData = any>(eventName: string, handler: EventHandler<TData>): EventSubscription;
+    /**
+     * Subscribes a handler to an event for exactly one invocation.
+     */
+    once<TData = any>(eventName: string, handler: EventHandler<TData>): EventSubscription;
+    /**
+     * Publishes an event to all registered subscribers.
+     * Handlers run asynchronously and errors in one subscriber do not crash others.
+     */
+    publish<TData = any>(eventName: string, data: TData): Promise<void>;
+    /**
+     * Clears all registered subscribers. Useful for test isolation.
+     */
+    clear(): void;
+}
+/**
+ * Global singleton EventBus instance.
+ */
+export declare const eventBus: EventBus;

package/dist/server/jobs/events.js

@@ -0,0 +1,74 @@
+/**
+ * In-process Domain Event Bus for decoupled asynchronous event notifications.
+ */
+export class EventBus {
+    subscribers = new Map();
+    counter = 0;
+    /**
+     * Subscribes a handler to an event.
+     */
+    subscribe(eventName, handler) {
+        const id = `sub_${++this.counter}_${Date.now()}`;
+        const list = this.subscribers.get(eventName) || [];
+        list.push({ id, handler });
+        this.subscribers.set(eventName, list);
+        return {
+            unsubscribe: () => {
+                const current = this.subscribers.get(eventName);
+                if (current) {
+                    this.subscribers.set(eventName, current.filter((item) => item.id !== id));
+                }
+            }
+        };
+    }
+    /**
+     * Subscribes a handler to an event for exactly one invocation.
+     */
+    once(eventName, handler) {
+        const id = `sub_once_${++this.counter}_${Date.now()}`;
+        const list = this.subscribers.get(eventName) || [];
+        list.push({ id, handler, once: true });
+        this.subscribers.set(eventName, list);
+        return {
+            unsubscribe: () => {
+                const current = this.subscribers.get(eventName);
+                if (current) {
+                    this.subscribers.set(eventName, current.filter((item) => item.id !== id));
+                }
+            }
+        };
+    }
+    /**
+     * Publishes an event to all registered subscribers.
+     * Handlers run asynchronously and errors in one subscriber do not crash others.
+     */
+    async publish(eventName, data) {
+        const current = this.subscribers.get(eventName);
+        if (!current || current.length === 0) {
+            return;
+        }
+        // Filter out one-time subscribers
+        const toRun = [...current];
+        const remaining = current.filter((item) => !item.once);
+        this.subscribers.set(eventName, remaining);
+        const promises = toRun.map(async (sub) => {
+            try {
+                await sub.handler(data);
+            }
+            catch (err) {
+                console.error(`[EventBus] Error in subscriber for event "${eventName}":`, err);
+            }
+        });
+        await Promise.allSettled(promises);
+    }
+    /**
+     * Clears all registered subscribers. Useful for test isolation.
+     */
+    clear() {
+        this.subscribers.clear();
+    }
+}
+/**
+ * Global singleton EventBus instance.
+ */
+export const eventBus = new EventBus();

package/dist/server/jobs/index.d.ts

@@ -0,0 +1,4 @@
+export { enqueueJob, parseJobDelay, memoryJobStore } from './queue';
+export { defineWorker, createJobRunner } from './runner';
+export { EventBus, eventBus } from './events';
+export type { JobRecord, JobDelay, EnqueueJobOptions, WorkerContext, WorkerHandler, WorkerDefinition, JobRunnerOptions, JobBatchResult, JobRunner, EventHandler, EventSubscription, IEventBus } from './types';

package/dist/server/jobs/index.js

@@ -0,0 +1,3 @@
+export { enqueueJob, parseJobDelay, memoryJobStore } from './queue';
+export { defineWorker, createJobRunner } from './runner';
+export { EventBus, eventBus } from './events';

package/dist/server/jobs/jobs.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/server/jobs/jobs.test.js

@@ -0,0 +1,189 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { EventBus, eventBus, enqueueJob, defineWorker, createJobRunner, parseJobDelay, memoryJobStore } from './index.js';
+describe('Domain Event Bus (EventBus)', () => {
+    let bus;
+    beforeEach(() => {
+        bus = new EventBus();
+        eventBus.clear();
+    });
+    it('dispatches events asynchronously to registered subscribers', async () => {
+        const received = [];
+        bus.subscribe('user.registered', async (data) => {
+            received.push(data);
+        });
+        await bus.publish('user.registered', { id: 'usr_1', email: 'alex@example.com' });
+        expect(received).toHaveLength(1);
+        expect(received[0].email).toBe('alex@example.com');
+    });
+    it('supports unsubscription via returned handler', async () => {
+        let count = 0;
+        const sub = bus.subscribe('counter.increment', () => {
+            count++;
+        });
+        await bus.publish('counter.increment', {});
+        expect(count).toBe(1);
+        sub.unsubscribe();
+        await bus.publish('counter.increment', {});
+        expect(count).toBe(1);
+    });
+    it('supports one-time subscribers with once()', async () => {
+        let triggered = 0;
+        bus.once('invoice.paid', () => {
+            triggered++;
+        });
+        await bus.publish('invoice.paid', { amount: 100 });
+        await bus.publish('invoice.paid', { amount: 200 });
+        expect(triggered).toBe(1);
+    });
+    it('isolates subscriber errors without crashing other subscribers or the publisher', async () => {
+        const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => { });
+        const healthyReceived = [];
+        bus.subscribe('order.placed', () => {
+            throw new Error('Failing external analytics webhook');
+        });
+        bus.subscribe('order.placed', (data) => {
+            healthyReceived.push(data.orderId);
+        });
+        // Publishing should complete without throwing
+        await expect(bus.publish('order.placed', { orderId: 'ord_999' })).resolves.not.toThrow();
+        expect(healthyReceived).toEqual(['ord_999']);
+        errorSpy.mockRestore();
+    });
+});
+describe('Job Delay Parser (parseJobDelay)', () => {
+    it('parses second, minute, hour, and day string abbreviations', () => {
+        const now = Date.now();
+        const in30s = parseJobDelay('30s').getTime();
+        expect(in30s).toBeGreaterThanOrEqual(now + 29000);
+        expect(in30s).toBeLessThanOrEqual(now + 31000);
+        const in5m = parseJobDelay('5m').getTime();
+        expect(in5m).toBeGreaterThanOrEqual(now + 5 * 60 * 1000 - 1000);
+        const in2h = parseJobDelay('2h').getTime();
+        expect(in2h).toBeGreaterThanOrEqual(now + 2 * 60 * 60 * 1000 - 1000);
+        const in1d = parseJobDelay('1d').getTime();
+        expect(in1d).toBeGreaterThanOrEqual(now + 24 * 60 * 60 * 1000 - 1000);
+    });
+    it('accepts raw millisecond numbers and Date instances directly', () => {
+        const targetDate = new Date(Date.now() + 10000);
+        expect(parseJobDelay(targetDate)).toEqual(targetDate);
+        const msResult = parseJobDelay(5000).getTime();
+        expect(msResult).toBeGreaterThanOrEqual(Date.now() + 4900);
+    });
+});
+describe('Job Queue & Runner Engine', () => {
+    beforeEach(() => {
+        memoryJobStore.clear();
+    });
+    it('enqueues jobs with default metadata and parameters', async () => {
+        const job = await enqueueJob('send-email', { to: 'elena@example.com' }, {
+            priority: 5,
+            maxAttempts: 4
+        });
+        expect(job.id).toBeDefined();
+        expect(job.name).toBe('send-email');
+        expect(job.payload.to).toBe('elena@example.com');
+        expect(job.status).toBe('pending');
+        expect(job.priority).toBe(5);
+        expect(job.maxAttempts).toBe(4);
+        expect(job.attempts).toBe(0);
+        expect(memoryJobStore.has(job.id)).toBe(true);
+    });
+    it('processes pending jobs successfully via defined worker', async () => {
+        const processed = [];
+        const emailWorker = defineWorker('send-welcome', async (payload) => {
+            processed.push(payload.to);
+        });
+        const runner = createJobRunner({
+            workers: [emailWorker]
+        });
+        const job = await enqueueJob('send-welcome', { to: 'alex@example.com' });
+        const result = await runner.processNextBatch();
+        expect(result.processed).toBe(1);
+        expect(result.succeeded).toBe(1);
+        expect(result.failed).toBe(0);
+        expect(processed).toEqual(['alex@example.com']);
+        // Verify job record state
+        const updatedJob = memoryJobStore.get(job.id);
+        expect(updatedJob?.status).toBe('completed');
+        expect(updatedJob?.completedAt).toBeDefined();
+        expect(updatedJob?.lockedAt).toBeNull();
+    });
+    it('retries failing jobs with exponential backoff when attempts < maxAttempts', async () => {
+        const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => { });
+        let callCount = 0;
+        const flakyWorker = defineWorker('flaky-task', async () => {
+            callCount++;
+            throw new Error('Temporary 503 from external service');
+        });
+        const runner = createJobRunner({
+            workers: [flakyWorker]
+        });
+        const job = await enqueueJob('flaky-task', {}, { maxAttempts: 3 });
+        const result = await runner.processNextBatch();
+        expect(result.processed).toBe(1);
+        expect(result.succeeded).toBe(0);
+        expect(result.failed).toBe(0); // Not marked permanently failed yet
+        expect(callCount).toBe(1);
+        const updatedJob = memoryJobStore.get(job.id);
+        expect(updatedJob?.attempts).toBe(1);
+        expect(updatedJob?.status).toBe('pending');
+        expect(updatedJob?.failedReason).toContain('Temporary 503');
+        // Backoff placed runAt into the future
+        expect(updatedJob?.runAt.getTime()).toBeGreaterThan(Date.now());
+        warnSpy.mockRestore();
+    });
+    it('transitions to Dead Letter Queue (status: failed) when maxAttempts is reached', async () => {
+        const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => { });
+        const fatalWorker = defineWorker('fatal-task', async () => {
+            throw new Error('Permanent database constraint error');
+        });
+        const runner = createJobRunner({
+            workers: [fatalWorker]
+        });
+        // maxAttempts = 1 -> should fail immediately after 1 attempt
+        const job = await enqueueJob('fatal-task', {}, { maxAttempts: 1 });
+        const result = await runner.processNextBatch();
+        expect(result.processed).toBe(1);
+        expect(result.succeeded).toBe(0);
+        expect(result.failed).toBe(1);
+        const updatedJob = memoryJobStore.get(job.id);
+        expect(updatedJob?.status).toBe('failed');
+        expect(updatedJob?.attempts).toBe(1);
+        expect(updatedJob?.failedReason).toContain('Permanent database constraint');
+        errorSpy.mockRestore();
+    });
+    it('prioritizes high priority jobs before lower priority jobs', async () => {
+        const order = [];
+        const worker = defineWorker('priority-test', async (payload) => {
+            order.push(payload.label);
+        });
+        const runner = createJobRunner({
+            workers: [worker],
+            batchSize: 5
+        });
+        await enqueueJob('priority-test', { label: 'low' }, { priority: 0 });
+        await enqueueJob('priority-test', { label: 'high' }, { priority: 10 });
+        await enqueueJob('priority-test', { label: 'medium' }, { priority: 5 });
+        await runner.processNextBatch();
+        expect(order).toEqual(['high', 'medium', 'low']);
+    });
+    it('skips scheduled delayed jobs until their runAt threshold has passed', async () => {
+        const worker = defineWorker('delayed-test', async () => { });
+        const runner = createJobRunner({ workers: [worker] });
+        // Schedule 1 hour in future
+        await enqueueJob('delayed-test', {}, { delay: '1h' });
+        const result = await runner.processNextBatch();
+        expect(result.processed).toBe(0);
+    });
+    it('starts and stops continuous background polling cleanly', () => {
+        const runner = createJobRunner({
+            workers: [],
+            pollIntervalMs: 100
+        });
+        expect(runner.isRunning()).toBe(false);
+        runner.start();
+        expect(runner.isRunning()).toBe(true);
+        runner.stop();
+        expect(runner.isRunning()).toBe(false);
+    });
+});

package/dist/server/jobs/queue.d.ts

@@ -0,0 +1,14 @@
+import type { EnqueueJobOptions, JobDelay, JobRecord } from './types';
+/**
+ * Parses delay specifier ('5m', '30s', '2h', number ms, Date) into an absolute Date.
+ */
+export declare function parseJobDelay(delay?: JobDelay): Date;
+/**
+ * In-memory fallback job store for unit testing or serverless instances without DB setup.
+ */
+export declare const memoryJobStore: Map<string, JobRecord<any>>;
+/**
+ * Enqueues a background job for asynchronous execution.
+ * Supports delayed scheduling, priority, custom partitions, and the Transactional Outbox pattern.
+ */
+export declare function enqueueJob<TPayload = any>(name: string, payload: TPayload, options?: EnqueueJobOptions): Promise<JobRecord<TPayload>>;

package/dist/server/jobs/queue.js

@@ -0,0 +1,90 @@
+import { schemaPg, schemaSqlite } from '../db';
+/**
+ * Parses delay specifier ('5m', '30s', '2h', number ms, Date) into an absolute Date.
+ */
+export function parseJobDelay(delay) {
+    const now = Date.now();
+    if (!delay) {
+        return new Date(now);
+    }
+    if (delay instanceof Date) {
+        return delay;
+    }
+    if (typeof delay === 'number') {
+        return new Date(now + Math.max(0, delay));
+    }
+    if (typeof delay === 'string') {
+        const match = delay.trim().match(/^(\d+(?:\.\d+)?)\s*(s|m|h|d|ms)?$/i);
+        if (match) {
+            const value = parseFloat(match[1]);
+            const unit = (match[2] || 'ms').toLowerCase();
+            const multipliers = {
+                s: 1000,
+                m: 60 * 1000,
+                h: 60 * 60 * 1000,
+                d: 24 * 60 * 60 * 1000,
+                ms: 1
+            };
+            const multiplier = multipliers[unit] ?? 1;
+            return new Date(now + Math.round(value * multiplier));
+        }
+    }
+    return new Date(now);
+}
+/**
+ * In-memory fallback job store for unit testing or serverless instances without DB setup.
+ */
+export const memoryJobStore = new Map();
+/**
+ * Enqueues a background job for asynchronous execution.
+ * Supports delayed scheduling, priority, custom partitions, and the Transactional Outbox pattern.
+ */
+export async function enqueueJob(name, payload, options = {}) {
+    const id = `job_${Date.now()}_${Math.random().toString(36).slice(2, 9)}`;
+    const queue = options.queue || 'default';
+    const priority = options.priority ?? 0;
+    const maxAttempts = options.maxAttempts ?? 3;
+    const runAt = parseJobDelay(options.delay);
+    const now = new Date();
+    const jobRecord = {
+        id,
+        queue,
+        name,
+        payload,
+        status: 'pending',
+        priority,
+        attempts: 0,
+        maxAttempts,
+        runAt,
+        createdAt: now,
+        updatedAt: now
+    };
+    // Save to in-memory store
+    memoryJobStore.set(id, jobRecord);
+    const client = options.tx || options.db;
+    if (client) {
+        try {
+            const payloadString = JSON.stringify(payload);
+            // Determine table schema (detect postgres vs sqlite table)
+            const table = client?.schema?.job || schemaPg.job || schemaSqlite.job;
+            await client.insert(table).values({
+                id,
+                queue,
+                name,
+                payload: payloadString,
+                status: 'pending',
+                priority,
+                attempts: 0,
+                maxAttempts,
+                runAt,
+                createdAt: now,
+                updatedAt: now
+            });
+        }
+        catch (err) {
+            // In case DB insert fails, log error
+            console.error(`[JobQueue] Failed to persist job "${name}" (${id}) to database:`, err);
+        }
+    }
+    return jobRecord;
+}

package/dist/server/jobs/runner.d.ts

@@ -0,0 +1,12 @@
+import type { JobRunner, JobRunnerOptions, WorkerDefinition, WorkerHandler } from './types';
+/**
+ * Declares a typed worker handler for a specific job name.
+ */
+export declare function defineWorker<TPayload = any>(name: string, handler: WorkerHandler<TPayload>, options?: {
+    queue?: string;
+}): WorkerDefinition<TPayload>;
+/**
+ * Creates an embedded job runner capable of executing pending jobs either on-demand
+ * (for serverless cron invocations) or continuously in the background (for Node.js servers).
+ */
+export declare function createJobRunner(options: JobRunnerOptions): JobRunner;