@carlos-tzin/tzin 0.1.8 → 0.1.10

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/dist/log.d.ts

@@ -0,0 +1,51 @@
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'fatal';
+export interface LogEntry {
+    level: LogLevel;
+    message: string;
+    data?: Record<string, unknown>;
+    timestamp: Date;
+    context?: string;
+}
+export interface Logger {
+    debug(message: string, data?: Record<string, unknown>): void;
+    info(message: string, data?: Record<string, unknown>): void;
+    warn(message: string, data?: Record<string, unknown>): void;
+    error(message: string, data?: Record<string, unknown>): void;
+    fatal(message: string, data?: Record<string, unknown>): void;
+    /** Create a child logger with a prefix */
+    child(prefix: string): Logger;
+}
+export interface LoggerConfig {
+    /** Minimum log level (default: 'info') */
+    level?: LogLevel;
+    /** Custom transport function */
+    transport?: (entry: LogEntry) => void;
+    /** Include timestamp in output (default: true) */
+    timestamp?: boolean;
+    /** Pretty print with colors (default: true in dev) */
+    pretty?: boolean;
+}
+/**
+ * Configure the global logger.
+ *
+ * @example
+ * ```ts
+ * import { configure } from '@carlos-tzin/tzin/log'
+ *
+ * configure({ level: 'debug', pretty: true })
+ * ```
+ */
+export declare function configure(config: LoggerConfig): void;
+/**
+ * Get the global logger.
+ *
+ * @example
+ * ```ts
+ * import { log } from '@carlos-tzin/tzin/log'
+ *
+ * log.info('Server started', { port: 3000 })
+ * ```
+ */
+export declare function getLogger(context?: string): Logger;
+/** Convenience export */
+export declare const log: Logger;

package/dist/log.js

@@ -0,0 +1,94 @@
+// ── Types ────────────────────────────────────────────────────────────
+// ── Log Level Order ──────────────────────────────────────────────────
+const LOG_LEVELS = {
+    debug: 0,
+    info: 1,
+    warn: 2,
+    error: 3,
+    fatal: 4,
+};
+// ── Colors ───────────────────────────────────────────────────────────
+const COLORS = {
+    debug: '\x1b[36m', // cyan
+    info: '\x1b[32m', // green
+    warn: '\x1b[33m', // yellow
+    error: '\x1b[31m', // red
+    fatal: '\x1b[35m', // magenta
+};
+const RESET = '\x1b[0m';
+// ── Default Transport ────────────────────────────────────────────────
+function defaultTransport(entry, config) {
+    const { level, message, data, timestamp, context } = entry;
+    const showTimestamp = config.timestamp !== false;
+    const pretty = config.pretty !== false;
+    if (pretty) {
+        const color = COLORS[level];
+        const prefix = context ? `[${context}]` : '';
+        const time = showTimestamp ? `${timestamp.toISOString()} ` : '';
+        const dataStr = data && Object.keys(data).length > 0 ? ` ${JSON.stringify(data)}` : '';
+        console.log(`${color}${time}${prefix} ${level.toUpperCase()}${RESET} ${message}${dataStr}`);
+    }
+    else {
+        const json = { level, message, timestamp: timestamp.toISOString() };
+        if (context)
+            json.context = context;
+        if (data && Object.keys(data).length > 0)
+            json.data = data;
+        console.log(JSON.stringify(json));
+    }
+}
+// ── Logger Factory ───────────────────────────────────────────────────
+function createLogger(config, context) {
+    const minLevel = LOG_LEVELS[config.level ?? 'info'];
+    const transport = config.transport ?? ((entry) => defaultTransport(entry, config));
+    function log(level, message, data) {
+        if (LOG_LEVELS[level] < minLevel)
+            return;
+        const entry = {
+            level,
+            message,
+            data,
+            timestamp: new Date(),
+            context,
+        };
+        transport(entry);
+    }
+    return {
+        debug: (msg, data) => log('debug', msg, data),
+        info: (msg, data) => log('info', msg, data),
+        warn: (msg, data) => log('warn', msg, data),
+        error: (msg, data) => log('error', msg, data),
+        fatal: (msg, data) => log('fatal', msg, data),
+        child: (prefix) => createLogger(config, context ? `${context}:${prefix}` : prefix),
+    };
+}
+// ── Global Logger ────────────────────────────────────────────────────
+let globalConfig = {};
+/**
+ * Configure the global logger.
+ *
+ * @example
+ * ```ts
+ * import { configure } from '@carlos-tzin/tzin/log'
+ *
+ * configure({ level: 'debug', pretty: true })
+ * ```
+ */
+export function configure(config) {
+    globalConfig = config;
+}
+/**
+ * Get the global logger.
+ *
+ * @example
+ * ```ts
+ * import { log } from '@carlos-tzin/tzin/log'
+ *
+ * log.info('Server started', { port: 3000 })
+ * ```
+ */
+export function getLogger(context) {
+    return createLogger(globalConfig, context);
+}
+/** Convenience export */
+export const log = getLogger();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@carlos-tzin/tzin",
-  "version": "0.1.8",
+  "version": "0.1.10",
   "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,14 @@
     "./auth": {
       "types": "./dist/auth.d.ts",
       "default": "./dist/auth.js"
+    },
+    "./jobs": {
+      "types": "./dist/jobs.d.ts",
+      "default": "./dist/jobs.js"
+    },
+    "./log": {
+      "types": "./dist/log.d.ts",
+      "default": "./dist/log.js"
     }
   },
   "files": [