yaxa-svelte 2.2.0 → 2.4.0

package/dist/server/jobs/runner.js

@@ -0,0 +1,176 @@
+import { memoryJobStore } from './queue';
+/**
+ * Declares a typed worker handler for a specific job name.
+ */
+export function defineWorker(name, handler, options = {}) {
+    return {
+        name,
+        handler,
+        queue: options.queue || 'default'
+    };
+}
+/**
+ * Calculates exponential backoff delay with jitter.
+ */
+function calculateBackoffDelay(attempt) {
+    const baseDelay = Math.min(3600000, Math.pow(2, attempt) * 1000);
+    const jitter = Math.floor(Math.random() * 500);
+    return baseDelay + jitter;
+}
+/**
+ * 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 function createJobRunner(options) {
+    const queue = options.queue || 'default';
+    const batchSize = options.batchSize || 10;
+    const pollIntervalMs = options.pollIntervalMs || 3000;
+    const lockTimeoutMs = options.lockTimeoutMs || 5 * 60 * 1000;
+    const workerId = options.workerId || `worker_${Date.now()}_${Math.random().toString(36).slice(2, 7)}`;
+    // Index worker handlers by name
+    const workerMap = new Map();
+    for (const worker of options.workers) {
+        workerMap.set(worker.name, worker.handler);
+    }
+    let activeTimer = null;
+    let isRunning = false;
+    let isProcessing = false;
+    /**
+     * Leases next batch of jobs from memory or database.
+     */
+    const leaseNextBatch = async () => {
+        const now = Date.now();
+        const leased = [];
+        // 1. Process from memory store
+        const candidates = Array.from(memoryJobStore.values()).filter((job) => {
+            if (job.queue !== queue)
+                return false;
+            const isReady = job.runAt.getTime() <= now;
+            const isPending = job.status === 'pending' && isReady;
+            const isStaleLocked = job.status === 'processing' && job.lockedAt && now - job.lockedAt.getTime() > lockTimeoutMs;
+            return isPending || isStaleLocked;
+        });
+        // Sort by priority DESC, runAt ASC
+        candidates.sort((a, b) => {
+            if (b.priority !== a.priority)
+                return b.priority - a.priority;
+            return a.runAt.getTime() - b.runAt.getTime();
+        });
+        const batch = candidates.slice(0, batchSize);
+        for (const job of batch) {
+            job.status = 'processing';
+            job.lockedAt = new Date(now);
+            job.lockedBy = workerId;
+            job.updatedAt = new Date(now);
+            leased.push(job);
+        }
+        return leased;
+    };
+    /**
+     * Processes the next batch of pending jobs.
+     */
+    const processNextBatch = async () => {
+        if (isProcessing) {
+            return { processed: 0, succeeded: 0, failed: 0 };
+        }
+        isProcessing = true;
+        let succeeded = 0;
+        let failed = 0;
+        try {
+            const batch = await leaseNextBatch();
+            for (const job of batch) {
+                const handler = workerMap.get(job.name);
+                if (!handler) {
+                    console.warn(`[JobRunner] No worker handler registered for job "${job.name}" (${job.id}). Leaving pending.`);
+                    job.status = 'pending';
+                    job.lockedAt = null;
+                    job.lockedBy = null;
+                    continue;
+                }
+                const logger = {
+                    info: (msg, ...args) => console.log(`[JobRunner:${job.name}:${job.id}] ${msg}`, ...args),
+                    warn: (msg, ...args) => console.warn(`[JobRunner:${job.name}:${job.id}] ${msg}`, ...args),
+                    error: (msg, ...args) => console.error(`[JobRunner:${job.name}:${job.id}] ${msg}`, ...args)
+                };
+                try {
+                    await handler(job.payload, { job, logger });
+                    // Mark completed
+                    const now = new Date();
+                    job.status = 'completed';
+                    job.completedAt = now;
+                    job.updatedAt = now;
+                    job.lockedAt = null;
+                    job.lockedBy = null;
+                    succeeded++;
+                }
+                catch (err) {
+                    const now = new Date();
+                    job.attempts += 1;
+                    job.lockedAt = null;
+                    job.lockedBy = null;
+                    job.failedReason = err?.message || String(err);
+                    job.updatedAt = now;
+                    if (job.attempts < job.maxAttempts) {
+                        // Exponential backoff retry
+                        const delayMs = calculateBackoffDelay(job.attempts);
+                        job.status = 'pending';
+                        job.runAt = new Date(Date.now() + delayMs);
+                        logger.warn(`Job execution failed (Attempt ${job.attempts}/${job.maxAttempts}). Retrying in ${Math.round(delayMs / 1000)}s: ${job.failedReason}`);
+                    }
+                    else {
+                        // Exceeded max attempts: Route to Dead Letter Queue (DLQ)
+                        job.status = 'failed';
+                        failed++;
+                        logger.error(`Job failed permanently after ${job.attempts} attempts. Routed to Dead Letter Queue: ${job.failedReason}`);
+                    }
+                }
+            }
+            return {
+                processed: batch.length,
+                succeeded,
+                failed
+            };
+        }
+        finally {
+            isProcessing = false;
+        }
+    };
+    /**
+     * Continuous background polling loop.
+     */
+    const poll = async () => {
+        if (!isRunning)
+            return;
+        try {
+            await processNextBatch();
+        }
+        catch (err) {
+            console.error('[JobRunner] Unexpected error during polling cycle:', err);
+        }
+        finally {
+            if (isRunning) {
+                activeTimer = setTimeout(poll, pollIntervalMs);
+                if (activeTimer && typeof activeTimer === 'object' && 'unref' in activeTimer) {
+                    activeTimer.unref();
+                }
+            }
+        }
+    };
+    return {
+        processNextBatch,
+        start: () => {
+            if (isRunning)
+                return;
+            isRunning = true;
+            poll();
+        },
+        stop: () => {
+            isRunning = false;
+            if (activeTimer) {
+                clearTimeout(activeTimer);
+                activeTimer = null;
+            }
+        },
+        isRunning: () => isRunning
+    };
+}

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

@@ -0,0 +1,136 @@
+import type { AnyDb } from '../db';
+import type { JobStatus } from '../db/types';
+/**
+ * Persisted Job record structure.
+ */
+export interface JobRecord<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;
+}
+/**
+ * Delay specifier:
+ * - String format: '30s', '5m', '2h', '1d'
+ * - Number: delay in milliseconds
+ * - Date: absolute execution timestamp
+ */
+export type JobDelay = string | number | Date;
+export interface EnqueueJobOptions {
+    /**
+     * Queue partition name (default: 'default').
+     */
+    queue?: string;
+    /**
+     * Execution delay or scheduled Date.
+     */
+    delay?: JobDelay;
+    /**
+     * Job execution priority (higher number = higher priority). Default: 0.
+     */
+    priority?: number;
+    /**
+     * Maximum retry attempts before routing to Dead Letter Queue (DLQ). Default: 3.
+     */
+    maxAttempts?: number;
+    /**
+     * Optional Drizzle transaction object for the Transactional Outbox pattern.
+     */
+    tx?: any;
+    /**
+     * Optional custom Drizzle DB client instance.
+     */
+    db?: AnyDb;
+}
+export interface WorkerContext<TPayload = any> {
+    job: JobRecord<TPayload>;
+    logger: {
+        info: (msg: string, ...args: any[]) => void;
+        warn: (msg: string, ...args: any[]) => void;
+        error: (msg: string, ...args: any[]) => void;
+    };
+}
+export type WorkerHandler<TPayload = any> = (payload: TPayload, context: WorkerContext<TPayload>) => Promise<void> | void;
+export interface WorkerDefinition<TPayload = any> {
+    name: string;
+    handler: WorkerHandler<TPayload>;
+    queue?: string;
+}
+export interface JobRunnerOptions {
+    /**
+     * Drizzle database instance (Neon or Turso).
+     */
+    db?: AnyDb;
+    /**
+     * Database driver ('neon' | 'turso' | 'sqlite').
+     */
+    driver?: 'neon' | 'turso' | 'sqlite';
+    /**
+     * List of registered worker handlers.
+     */
+    workers: WorkerDefinition<any>[];
+    /**
+     * Target queue name to poll (default: 'default').
+     */
+    queue?: string;
+    /**
+     * Maximum jobs to lease and process per batch (default: 10).
+     */
+    batchSize?: number;
+    /**
+     * Polling interval in milliseconds for daemon mode (default: 3000ms).
+     */
+    pollIntervalMs?: number;
+    /**
+     * Lock timeout in milliseconds before a processing job is considered stale (default: 5 minutes).
+     */
+    lockTimeoutMs?: number;
+    /**
+     * Worker instance identifier (default: generated worker id).
+     */
+    workerId?: string;
+}
+export interface JobBatchResult {
+    processed: number;
+    succeeded: number;
+    failed: number;
+}
+export interface JobRunner {
+    /**
+     * Processes the next batch of pending jobs. Perfect for serverless cron endpoints (/api/cron/jobs).
+     */
+    processNextBatch: () => Promise<JobBatchResult>;
+    /**
+     * Starts the continuous background polling loop (for long-lived Node.js servers).
+     */
+    start: () => void;
+    /**
+     * Stops the background polling loop.
+     */
+    stop: () => void;
+    /**
+     * Returns true if the polling runner is currently active.
+     */
+    isRunning: () => boolean;
+}
+export type EventHandler<TData = any> = (data: TData) => Promise<void> | void;
+export interface EventSubscription {
+    unsubscribe: () => void;
+}
+export interface IEventBus {
+    publish: <TData = any>(eventName: string, data: TData) => Promise<void>;
+    subscribe: <TData = any>(eventName: string, handler: EventHandler<TData>) => EventSubscription;
+    once: <TData = any>(eventName: string, handler: EventHandler<TData>) => EventSubscription;
+    clear: () => void;
+}

package/dist/server/jobs/types.js

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

package/dist/server/openapi/generator.d.ts

@@ -0,0 +1,5 @@
+import type { GenerateOpenApiOptions, OpenApiSpec31 } from './types';
+/**
+ * Generates an OpenAPI 3.1.0 document from registered yaxaEndpoints.
+ */
+export declare function generateOpenApiSpec(options?: GenerateOpenApiOptions): OpenApiSpec31;

package/dist/server/openapi/generator.js

@@ -0,0 +1,317 @@
+import { convertToJsonSchema } from './schema';
+import { globalApiRegistry } from './registry';
+/**
+ * Standard RFC 7807 Problem Details Schema for OpenAPI Components.
+ */
+const PROBLEM_DETAILS_SCHEMA = {
+    type: 'object',
+    properties: {
+        type: { type: 'string', format: 'uri', example: 'https://yaxa.dev/errors/validation-failed' },
+        title: { type: 'string', example: 'Unprocessable Entity' },
+        status: { type: 'integer', example: 422 },
+        detail: { type: 'string', example: 'Validation failed for 1 parameter(s).' },
+        instance: { type: 'string' },
+        invalidParams: {
+            type: 'array',
+            items: {
+                type: 'object',
+                properties: {
+                    name: { type: 'string', example: 'body.email' },
+                    reason: { type: 'string', example: 'Invalid email address' }
+                },
+                required: ['name', 'reason']
+            }
+        }
+    },
+    required: ['type', 'title', 'status']
+};
+/**
+ * Extracts parameter list from a converted JSON schema.
+ */
+function extractParametersFromSchema(jsonSchema, location) {
+    if (!jsonSchema || typeof jsonSchema !== 'object' || !jsonSchema.properties) {
+        return [];
+    }
+    const requiredList = Array.isArray(jsonSchema.required) ? jsonSchema.required : [];
+    const parameters = [];
+    for (const [key, propSchema] of Object.entries(jsonSchema.properties)) {
+        parameters.push({
+            name: key,
+            in: location,
+            required: location === 'path' ? true : requiredList.includes(key),
+            description: propSchema?.description,
+            deprecated: propSchema?.deprecated,
+            schema: propSchema
+        });
+    }
+    return parameters;
+}
+/**
+ * Resolves YaxaEndpointConfig from an endpoint function or config object.
+ */
+function resolveConfig(endpoint) {
+    if (!endpoint)
+        return null;
+    if (typeof endpoint === 'function' && '_yaxaConfig' in endpoint) {
+        return endpoint._yaxaConfig;
+    }
+    if (typeof endpoint === 'object' && 'handle' in endpoint) {
+        return endpoint;
+    }
+    return null;
+}
+/**
+ * Generates an OpenAPI 3.1.0 document from registered yaxaEndpoints.
+ */
+export function generateOpenApiSpec(options = {}) {
+    const title = options.title || 'Yaxa SvelteKit API';
+    const version = options.version || '1.0.0';
+    const description = options.description || 'Auto-generated OpenAPI 3.1 contract via yaxa-svelte.';
+    const registry = options.registry || globalApiRegistry;
+    const registeredEndpoints = registry.getEndpoints();
+    // Merge manual options.endpoints if provided
+    const mergedEndpoints = {
+        ...registeredEndpoints
+    };
+    if (options.endpoints) {
+        for (const [rawPath, methods] of Object.entries(options.endpoints)) {
+            const normalizedPath = registry.normalizePath(rawPath);
+            if (!mergedEndpoints[normalizedPath]) {
+                mergedEndpoints[normalizedPath] = {};
+            }
+            for (const [method, handler] of Object.entries(methods)) {
+                mergedEndpoints[normalizedPath][method.toUpperCase()] = handler;
+            }
+        }
+    }
+    const paths = {};
+    const securitySchemes = {};
+    let usesSecurity = false;
+    for (const [path, methods] of Object.entries(mergedEndpoints)) {
+        paths[path] = {};
+        for (const [method, endpoint] of Object.entries(methods)) {
+            const config = resolveConfig(endpoint);
+            const methodLower = method.toLowerCase();
+            if (!config) {
+                // Fallback for raw RequestHandler
+                paths[path][methodLower] = {
+                    summary: `${method.toUpperCase()} ${path}`,
+                    responses: {
+                        '200': { description: 'Successful response' }
+                    }
+                };
+                continue;
+            }
+            const parameters = [];
+            // 1. Path Params
+            if (config.schema?.params) {
+                const paramsSchema = convertToJsonSchema(config.schema.params);
+                parameters.push(...extractParametersFromSchema(paramsSchema, 'path'));
+            }
+            else {
+                // Detect {param} placeholders in path and add basic string parameters
+                const pathParamMatches = path.match(/\{(\w+)\}/g);
+                if (pathParamMatches) {
+                    for (const match of pathParamMatches) {
+                        const paramName = match.slice(1, -1);
+                        parameters.push({
+                            name: paramName,
+                            in: 'path',
+                            required: true,
+                            schema: { type: 'string' }
+                        });
+                    }
+                }
+            }
+            // 2. Query Params
+            if (config.schema?.query) {
+                const querySchema = convertToJsonSchema(config.schema.query);
+                parameters.push(...extractParametersFromSchema(querySchema, 'query'));
+            }
+            // 3. Header Params
+            if (config.schema?.headers) {
+                const headersSchema = convertToJsonSchema(config.schema.headers);
+                parameters.push(...extractParametersFromSchema(headersSchema, 'header'));
+            }
+            // 4. Request Body
+            let requestBody = undefined;
+            if (config.schema?.body && method !== 'GET' && method !== 'HEAD') {
+                const bodySchema = convertToJsonSchema(config.schema.body);
+                requestBody = {
+                    required: true,
+                    content: {
+                        'application/json': {
+                            schema: bodySchema
+                        }
+                    }
+                };
+            }
+            // 5. Responses
+            const responses = {};
+            const successStatus = config.status
+                ? String(config.status)
+                : method === 'POST'
+                    ? '201'
+                    : '200';
+            if (config.responses) {
+                for (const [statusCode, resp] of Object.entries(config.responses)) {
+                    responses[String(statusCode)] = {
+                        description: resp.description,
+                        content: resp.schema
+                            ? {
+                                'application/json': {
+                                    schema: convertToJsonSchema(resp.schema)
+                                }
+                            }
+                            : undefined
+                    };
+                }
+            }
+            if (!responses[successStatus]) {
+                responses[successStatus] = {
+                    description: successStatus === '201'
+                        ? 'Created'
+                        : successStatus === '204'
+                            ? 'No Content'
+                            : 'Successful Operation',
+                    content: successStatus !== '204'
+                        ? {
+                            'application/json': {
+                                schema: { type: 'object' }
+                            }
+                        }
+                        : undefined
+                };
+            }
+            // 6. Guard Reflection (Security & Error Status Codes)
+            let hasAuthGuard = false;
+            let hasRoleGuard = false;
+            let roleGuardRoles = [];
+            let hasRateLimitGuard = false;
+            let rateLimitRetryAfter = 60;
+            if (config.guards && config.guards.length > 0) {
+                for (const guard of config.guards) {
+                    const meta = guard._yaxaGuard;
+                    if (meta) {
+                        if (meta.type === 'auth') {
+                            hasAuthGuard = true;
+                        }
+                        else if (meta.type === 'role') {
+                            hasRoleGuard = true;
+                            if (meta.roles)
+                                roleGuardRoles = meta.roles;
+                        }
+                        else if (meta.type === 'rateLimit') {
+                            hasRateLimitGuard = true;
+                            if (meta.options?.windowSeconds) {
+                                rateLimitRetryAfter = meta.options.windowSeconds;
+                            }
+                        }
+                    }
+                }
+            }
+            const operationSecurity = [];
+            if (hasAuthGuard || hasRoleGuard) {
+                usesSecurity = true;
+                securitySchemes['BearerAuth'] = {
+                    type: 'http',
+                    scheme: 'bearer',
+                    bearerFormat: 'JWT',
+                    description: 'Standard Bearer Token Header (`Authorization: Bearer <token>`)'
+                };
+                securitySchemes['CookieAuth'] = {
+                    type: 'apiKey',
+                    in: 'cookie',
+                    name: 'better-auth.session_token',
+                    description: 'Session cookie via Better-Auth'
+                };
+                operationSecurity.push({ BearerAuth: [] }, { CookieAuth: [] });
+                responses['401'] = {
+                    description: 'Unauthorized (RFC 7807 Problem Details)',
+                    content: {
+                        'application/problem+json': {
+                            schema: { $ref: '#/components/schemas/ProblemDetails' }
+                        }
+                    }
+                };
+            }
+            if (hasRoleGuard) {
+                responses['403'] = {
+                    description: `Forbidden — Insufficient role permissions. Requires: [${roleGuardRoles.join(', ')}]`,
+                    content: {
+                        'application/problem+json': {
+                            schema: { $ref: '#/components/schemas/ProblemDetails' }
+                        }
+                    }
+                };
+            }
+            // 7. Schema Validation Error (422)
+            if (config.schema &&
+                (config.schema.body || config.schema.query || config.schema.params || config.schema.headers)) {
+                responses['422'] = {
+                    description: 'Unprocessable Entity — Schema validation failed (RFC 7807)',
+                    content: {
+                        'application/problem+json': {
+                            schema: { $ref: '#/components/schemas/ProblemDetails' }
+                        }
+                    }
+                };
+            }
+            // 8. Rate Limit Error (429)
+            if (hasRateLimitGuard) {
+                responses['429'] = {
+                    description: 'Too Many Requests — Rate limit exceeded (RFC 7807)',
+                    headers: {
+                        'Retry-After': {
+                            description: 'Seconds to wait before retrying',
+                            schema: { type: 'integer', example: rateLimitRetryAfter }
+                        }
+                    },
+                    content: {
+                        'application/problem+json': {
+                            schema: { $ref: '#/components/schemas/ProblemDetails' }
+                        }
+                    }
+                };
+            }
+            // 9. Standard 500 Sanitized Error
+            responses['500'] = {
+                description: 'Internal Server Error — Sanitized exception (RFC 7807)',
+                content: {
+                    'application/problem+json': {
+                        schema: { $ref: '#/components/schemas/ProblemDetails' }
+                    }
+                }
+            };
+            const operation = {
+                summary: config.summary || `${method.toUpperCase()} ${path}`,
+                description: config.description,
+                operationId: config.operationId ||
+                    `${methodLower}_${path.replace(/[/{}]+/g, '_').replace(/^_+|_+$/g, '')}`,
+                tags: config.tags || (path.split('/')[2] ? [path.split('/')[2]] : ['Default']),
+                deprecated: config.deprecated,
+                parameters: parameters.length > 0 ? parameters : undefined,
+                requestBody,
+                responses,
+                security: operationSecurity.length > 0 ? operationSecurity : undefined
+            };
+            paths[path][methodLower] = operation;
+        }
+    }
+    return {
+        openapi: '3.1.0',
+        info: {
+            title,
+            version,
+            description
+        },
+        servers: options.servers || [{ url: '/', description: 'Current Environment' }],
+        paths,
+        components: {
+            schemas: {
+                ProblemDetails: PROBLEM_DETAILS_SCHEMA
+            },
+            securitySchemes: usesSecurity ? securitySchemes : undefined
+        }
+    };
+}

package/dist/server/openapi/handler.d.ts

@@ -0,0 +1,7 @@
+import type { RequestHandler } from '@sveltejs/kit';
+import type { ApiDocsOptions } from './types';
+/**
+ * Creates a turnkey SvelteKit RequestHandler that generates an interactive OpenAPI 3.1 documentation
+ * page (Scalar, Swagger UI, or Redoc) or returns raw OpenAPI 3.1 JSON when ?format=json is requested.
+ */
+export declare function createApiDocsHandler(options?: ApiDocsOptions): RequestHandler;