@carlos-tzin/tzin 0.1.8 → 0.1.9

package/dist/jobs.d.ts

@@ -0,0 +1,104 @@
+export interface JobConfig {
+    /** Unique job name */
+    name: string;
+    /** Max retries on failure (default: 3) */
+    maxRetries?: number;
+    /** Delay between retries in ms (default: 1000) */
+    retryDelay?: number;
+    /** Job timeout in ms (default: 30000) */
+    timeout?: number;
+}
+export interface JobDefinition<Payload = unknown> {
+    readonly name: string;
+    readonly config: JobConfig;
+    /** Process the job */
+    handler: (payload: Payload, ctx: JobContext) => Promise<void>;
+}
+export interface JobContext {
+    /** Job attempt number (0-based) */
+    attempt: number;
+    /** Abort signal for cancellation */
+    signal: AbortSignal;
+    /** Logger scoped to this job */
+    log: JobLogger;
+}
+export interface JobLogger {
+    info(message: string, data?: Record<string, unknown>): void;
+    warn(message: string, data?: Record<string, unknown>): void;
+    error(message: string, data?: Record<string, unknown>): void;
+}
+export interface Job<Payload = unknown> {
+    /** Job name */
+    readonly name: string;
+    /** Job configuration */
+    readonly config: JobConfig;
+    /** Enqueue the job for processing */
+    enqueue(payload: Payload, options?: EnqueueOptions): Promise<JobHandle>;
+}
+export interface EnqueueOptions {
+    /** Delay before processing in ms */
+    delay?: number;
+    /** Schedule for a specific time */
+    scheduledAt?: Date;
+}
+export interface JobHandle {
+    /** Job ID */
+    id: string;
+    /** Poll for completion */
+    wait(): Promise<JobResult>;
+}
+export interface JobResult {
+    status: 'completed' | 'failed';
+    error?: string;
+    duration: number;
+}
+export type JobStatus = 'pending' | 'running' | 'completed' | 'failed';
+export interface JobRecord {
+    id: string;
+    name: string;
+    payload: unknown;
+    status: JobStatus;
+    attempt: number;
+    maxRetries: number;
+    error?: string;
+    createdAt: Date;
+    startedAt?: Date;
+    completedAt?: Date;
+}
+export interface JobStore {
+    add(record: JobRecord): void;
+    update(id: string, data: Partial<JobRecord>): void;
+    getById(id: string): JobRecord | null;
+    getPending(): JobRecord[];
+}
+/**
+ * Define a background job.
+ *
+ * @example
+ * ```ts
+ * import { defineJob } from '@carlos-tzin/tzin/jobs'
+ *
+ * const sendEmail = defineJob<{ to: string; subject: string; body: string }>({
+ *   name: 'send-email',
+ *   maxRetries: 3,
+ *   handler: async (payload, ctx) => {
+ *     ctx.log.info('Sending email', { to: payload.to })
+ *     await resend.emails.send({ ... })
+ *   },
+ * })
+ *
+ * // In a handler:
+ * await sendEmail.enqueue({ to: 'ada@example.com', subject: 'Hello', body: '...' })
+ * ```
+ */
+export declare function defineJob<Payload = void>(config: JobConfig & {
+    handler: (payload: Payload, ctx: JobContext) => Promise<void>;
+}): Job<Payload>;
+/**
+ * Get all job records (useful for debugging).
+ */
+export declare function getJobRecords(): JobRecord[];
+/**
+ * Reset the job store (useful for testing).
+ */
+export declare function resetJobs(): void;

package/dist/jobs.js

@@ -0,0 +1,202 @@
+// ── Types ────────────────────────────────────────────────────────────
+class MemoryJobStore {
+    records = new Map();
+    add(record) {
+        this.records.set(record.id, { ...record });
+    }
+    update(id, data) {
+        const record = this.records.get(id);
+        if (record)
+            Object.assign(record, data);
+    }
+    getById(id) {
+        const record = this.records.get(id);
+        return record ? { ...record } : null;
+    }
+    getPending() {
+        return [...this.records.values()].filter((r) => r.status === 'pending');
+    }
+}
+// ── Queue State ──────────────────────────────────────────────────────
+let globalStore = new MemoryJobStore();
+let processing = false;
+let processTimer = null;
+const handlers = new Map();
+// ── defineJob ────────────────────────────────────────────────────────
+/**
+ * Define a background job.
+ *
+ * @example
+ * ```ts
+ * import { defineJob } from '@carlos-tzin/tzin/jobs'
+ *
+ * const sendEmail = defineJob<{ to: string; subject: string; body: string }>({
+ *   name: 'send-email',
+ *   maxRetries: 3,
+ *   handler: async (payload, ctx) => {
+ *     ctx.log.info('Sending email', { to: payload.to })
+ *     await resend.emails.send({ ... })
+ *   },
+ * })
+ *
+ * // In a handler:
+ * await sendEmail.enqueue({ to: 'ada@example.com', subject: 'Hello', body: '...' })
+ * ```
+ */
+export function defineJob(config) {
+    const jobConfig = {
+        maxRetries: 3,
+        retryDelay: 1000,
+        timeout: 30000,
+        ...config,
+    };
+    handlers.set(config.name, config.handler);
+    return {
+        name: config.name,
+        config: jobConfig,
+        async enqueue(payload, options) {
+            const id = `${config.name}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+            const record = {
+                id,
+                name: config.name,
+                payload,
+                status: 'pending',
+                attempt: 0,
+                maxRetries: jobConfig.maxRetries,
+                createdAt: new Date(),
+                ...(options?.scheduledAt && { scheduledAt: options.scheduledAt }),
+            };
+            globalStore.add(record);
+            scheduleProcess();
+            return {
+                id,
+                async wait() {
+                    return waitForJob(id, jobConfig.timeout * (jobConfig.maxRetries + 1));
+                },
+            };
+        },
+    };
+}
+// ── Processing ───────────────────────────────────────────────────────
+function scheduleProcess() {
+    if (processTimer)
+        return;
+    processTimer = setTimeout(async () => {
+        processTimer = null;
+        await processPending();
+    }, 10);
+}
+async function processPending() {
+    if (processing)
+        return;
+    processing = true;
+    try {
+        const pending = globalStore.getPending();
+        for (const record of pending) {
+            await processRecord(record);
+        }
+    }
+    finally {
+        processing = false;
+        if (globalStore.getPending().length > 0) {
+            scheduleProcess();
+        }
+    }
+}
+async function processRecord(record) {
+    const handler = handlers.get(record.name);
+    if (!handler) {
+        globalStore.update(record.id, { status: 'failed', error: 'No handler found' });
+        return;
+    }
+    globalStore.update(record.id, { status: 'running', startedAt: new Date() });
+    const controller = new AbortController();
+    const ctx = {
+        attempt: record.attempt,
+        signal: controller.signal,
+        log: createLogger(record.name),
+    };
+    try {
+        await Promise.race([
+            handler(record.payload, ctx),
+            new Promise((_, reject) => setTimeout(() => reject(new Error('Job timeout')), 30000)),
+        ]);
+        globalStore.update(record.id, {
+            status: 'completed',
+            completedAt: new Date(),
+        });
+    }
+    catch (err) {
+        const error = err instanceof Error ? err.message : String(err);
+        const attempt = record.attempt + 1;
+        if (attempt < record.maxRetries) {
+            globalStore.update(record.id, { status: 'pending', attempt });
+            setTimeout(() => scheduleProcess(), 1000);
+        }
+        else {
+            globalStore.update(record.id, {
+                status: 'failed',
+                error,
+                attempt,
+                completedAt: new Date(),
+            });
+        }
+    }
+}
+function waitForJob(id, timeout) {
+    return new Promise((resolve, reject) => {
+        const start = Date.now();
+        const check = () => {
+            const record = globalStore.getById(id);
+            if (!record) {
+                reject(new Error('Job not found'));
+                return;
+            }
+            if (record.status === 'completed') {
+                resolve({
+                    status: 'completed',
+                    duration: (record.completedAt?.getTime() ?? Date.now()) - record.createdAt.getTime(),
+                });
+                return;
+            }
+            if (record.status === 'failed') {
+                resolve({
+                    status: 'failed',
+                    error: record.error,
+                    duration: (record.completedAt?.getTime() ?? Date.now()) - record.createdAt.getTime(),
+                });
+                return;
+            }
+            if (Date.now() - start > timeout) {
+                reject(new Error('Timeout waiting for job'));
+                return;
+            }
+            setTimeout(check, 100);
+        };
+        check();
+    });
+}
+function createLogger(name) {
+    const prefix = `[job:${name}]`;
+    return {
+        info: (msg, data) => console.log(prefix, msg, data ?? ''),
+        warn: (msg, data) => console.warn(prefix, msg, data ?? ''),
+        error: (msg, data) => console.error(prefix, msg, data ?? ''),
+    };
+}
+// ── Utilities ────────────────────────────────────────────────────────
+/**
+ * Get all job records (useful for debugging).
+ */
+export function getJobRecords() {
+    return globalStore['records']
+        ? [...globalStore['records'].values()]
+        : [];
+}
+/**
+ * Reset the job store (useful for testing).
+ */
+export function resetJobs() {
+    globalStore = new MemoryJobStore();
+    handlers.clear();
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@carlos-tzin/tzin",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "description": "Contract-first TypeScript framework. Types that scale, realtime channels with presence, and an MCP server for every API.",
   "license": "MIT",
   "author": "The tzin authors",
@@ -54,6 +54,10 @@
     "./auth": {
       "types": "./dist/auth.d.ts",
       "default": "./dist/auth.js"
+    },
+    "./jobs": {
+      "types": "./dist/jobs.d.ts",
+      "default": "./dist/jobs.js"
     }
   },
   "files": [