@morojs/moro 1.6.6 → 1.7.0

package/dist/moro.d.ts

@@ -9,6 +9,11 @@ import { DocsConfig } from './core/docs/index.js';
 import { EventEmitter } from 'events';
 import { type AppConfig } from './core/config/index.js';
 import { RuntimeAdapter, RuntimeType } from './core/runtime/index.js';
+import type { JobSchedule, SimpleJobOptions, JobFunction, JobMetrics, SchedulerStats, JobHealth } from './core/jobs/index.js';
+import { WorkerThreadsFacade, type WorkerTask } from './core/workers/index.js';
+import type { GraphQLOptions } from './core/graphql/types.js';
+import type { GrpcOptions, ServiceImplementation, GrpcClient, GrpcClientOptions } from './core/grpc/types.js';
+import type { MailConfig, MailOptions, MailResult } from './core/mail/types.js';
 export declare class Moro extends EventEmitter {
     private coreFramework;
     private routes;
@@ -31,6 +36,25 @@ export declare class Moro extends EventEmitter {
     private runtimeType;
     private middlewareManager;
     private queuedWebSocketRegistrations;
+    private jobScheduler?;
+    private jobHealthChecker?;
+    private jobsStarted;
+    private graphqlCore?;
+    private graphqlSubscriptionManager?;
+    private graphqlInitPromise?;
+    private graphqlConfig?;
+    private grpcManager?;
+    private grpcInitPromise?;
+    private grpcStarted;
+    private grpcConfig?;
+    private queueManager?;
+    private queueInitialized;
+    private queueInitPromise?;
+    private queueConfigs;
+    private workerFacade;
+    private mailManager?;
+    private mailInitialized;
+    private mailConfig?;
     constructor(options?: MoroOptions);
     /**
      * Get configuration object
@@ -68,7 +92,7 @@ export declare class Moro extends EventEmitter {
     plugin(middleware: any, options?: any): Promise<this>;
     loadModule(moduleOrPath: ModuleConfig | string): Promise<this>;
     database(adapter: any): this;
-    websocket(namespace: string, handlers: Record<string, Function>): this;
+    websocket(namespace: string, handlers: Record<string, CallableFunction>): this;
     private processWebSocketRegistration;
     private processQueuedWebSocketRegistrations;
     listen(callback?: () => void): void;
@@ -138,6 +162,467 @@ export declare class Moro extends EventEmitter {
      * This should be called in tests and during shutdown
      */
     close(): Promise<void>;
+    /**
+     * Register a background job with cron or interval schedule
+     * @param name - Job name (used for identification)
+     * @param schedule - Cron expression, interval string ('5m', '1h'), or schedule object
+     * @param handler - Job function to execute
+     * @param options - Job configuration options
+     * @returns Job ID for management
+     *
+     * @example
+     * // Cron schedule
+     * app.job('cleanup', '0 2 * * *', async () => {
+     *   await cleanupOldData();
+     * });
+     *
+     * // Interval schedule
+     * app.job('health-check', '5m', async (ctx) => {
+     *   console.log('Health check', ctx.executionId);
+     * });
+     *
+     * // Advanced options
+     * app.job('report', '@daily', generateReport, {
+     *   timeout: 60000,
+     *   maxRetries: 3,
+     *   onError: (ctx, error) => console.error('Job failed', error)
+     * });
+     */
+    job(name: string, schedule: string | JobSchedule, handler: JobFunction, options?: SimpleJobOptions): string;
+    /**
+     * Enable or disable a registered job
+     */
+    setJobEnabled(jobId: string, enabled: boolean): boolean;
+    /**
+     * Manually trigger a job execution
+     */
+    triggerJob(jobId: string, metadata?: Record<string, any>): Promise<any>;
+    /**
+     * Unregister a job
+     */
+    unregisterJob(jobId: string): boolean;
+    /**
+     * Get job metrics
+     */
+    getJobMetrics(jobId: string): JobMetrics | null;
+    /**
+     * Get job health status
+     */
+    getJobHealth(jobId?: string): JobHealth | JobHealth[];
+    /**
+     * Get scheduler statistics
+     */
+    getJobStats(): SchedulerStats | null;
+    /**
+     * Get overall scheduler health
+     */
+    getSchedulerHealth(): {
+        status: import("./core/jobs/types.js").JobHealthStatus;
+        stats: SchedulerStats;
+        jobs: JobHealth[];
+        unhealthyJobCount: number;
+        message?: string;
+    } | {
+        status: "unknown";
+        message: string;
+        stats: null;
+        jobs: never[];
+        unhealthyJobCount: number;
+    };
+    /**
+     * Start the job scheduler (called automatically on listen)
+     */
+    private startJobScheduler;
+    /**
+     * Configure GraphQL endpoint (synchronous, lazy initialization)
+     *
+     * @param options - GraphQL configuration options
+     *
+     * @example
+     * ```ts
+     * // Using type definitions and resolvers
+     * app.graphqlInit({
+     *   typeDefs: `
+     *     type Query {
+     *       hello: String
+     *       users: [User]
+     *     }
+     *     type User {
+     *       id: ID!
+     *       name: String!
+     *     }
+     *   `,
+     *   resolvers: {
+     *     Query: {
+     *       hello: () => 'Hello World!',
+     *       users: () => [{ id: '1', name: 'Alice' }]
+     *     }
+     *   }
+     * });
+     *
+     * // Using Pothos schema builder
+     * import SchemaBuilder from '@pothos/core';
+     *
+     * const builder = new SchemaBuilder();
+     * builder.queryType({
+     *   fields: (t) => ({
+     *     hello: t.string({ resolve: () => 'Hello World!' })
+     *   })
+     * });
+     *
+     * app.graphqlInit({
+     *   pothosSchema: builder
+     * });
+     * ```
+     */
+    graphqlInit(options: GraphQLOptions): this;
+    /**
+     * Lazy initialize GraphQL system
+     */
+    private ensureGraphQLInitialized;
+    /**
+     * Initialize GraphQL system asynchronously
+     */
+    private initializeGraphQL;
+    /**
+     * Check if GraphQL package is available
+     */
+    private isGraphQLAvailable;
+    /**
+     * Lazy load GraphQL modules
+     */
+    private loadGraphQLModules;
+    /**
+     * Setup GraphQL subscriptions
+     */
+    private setupGraphQLSubscriptions;
+    /**
+     * Get GraphQL schema (if configured)
+     */
+    getGraphQLSchema(): Promise<any | undefined>;
+    /**
+     * Execute a task on worker threads (CPU-intensive operations)
+     * @param task - Task to execute
+     * @returns Promise resolving to task result
+     *
+     * @example
+     * ```ts
+     * // JWT verification (CPU-intensive)
+     * const payload = await app.executeOnWorker({
+     *   id: 'jwt-verify-123',
+     *   type: 'jwt:verify',
+     *   data: { token, secret }
+     * });
+     *
+     * // Heavy computation
+     * const result = await app.executeOnWorker({
+     *   id: 'compute-456',
+     *   type: 'computation:heavy',
+     *   data: { iterations: 1000000 }
+     * });
+     * ```
+     */
+    executeOnWorker<T = any>(task: WorkerTask): Promise<T>;
+    /**
+     * Get worker manager instance for advanced usage
+     */
+    getWorkerManager(): Promise<WorkerThreadsFacade>;
+    /**
+     * Get worker thread statistics
+     */
+    getWorkerStats(): Promise<import("./core/workers/facade.js").WorkerStats | null>;
+    /**
+     * JWT operations using worker threads (prevents event loop blocking)
+     */
+    getJwtWorker(): Promise<{
+        verify: import("./core/workers/facade.js").WorkerHelpers["verifyJWT"];
+        sign: import("./core/workers/facade.js").WorkerHelpers["signJWT"];
+    } | null>;
+    /**
+     * Crypto operations using worker threads
+     */
+    getCryptoWorker(): Promise<{
+        hash: import("./core/workers/facade.js").WorkerHelpers["hash"];
+    } | null>;
+    /**
+     * Heavy computation operations using worker threads
+     */
+    getComputeWorker(): Promise<{
+        heavy: import("./core/workers/facade.js").WorkerHelpers["heavyComputation"];
+        transformJSON: import("./core/workers/facade.js").WorkerHelpers["transformJSON"];
+    } | null>;
+    /**
+     * Get GraphQL stats
+     */
+    getGraphQLStats(): Promise<any>;
+    /**
+     * Configure gRPC server (synchronous, lazy initialization)
+     *
+     * @example
+     * ```typescript
+     * app.grpcInit({
+     *   port: 50051,
+     *   host: '0.0.0.0',
+     *   adapter: 'grpc-js',
+     *   enableHealthCheck: true,
+     *   enableReflection: true
+     * });
+     * ```
+     */
+    grpcInit(options?: GrpcOptions): this;
+    /**
+     * Lazy initialize gRPC system
+     */
+    private ensureGrpcInitialized;
+    /**
+     * Register a gRPC service from a proto file
+     *
+     * @example
+     * ```typescript
+     * app.grpcService('./proto/users.proto', 'UserService', {
+     *   getUser: async (call, callback) => {
+     *     const user = await db.users.findById(call.request.id);
+     *     callback(null, user);
+     *   },
+     *   listUsers: async (call) => {
+     *     for (const user of users) {
+     *       call.write(user);
+     *     }
+     *     call.end();
+     *   }
+     * });
+     * ```
+     */
+    grpcService(protoPath: string, serviceName: string, implementation: ServiceImplementation, packageName?: string): Promise<void>;
+    /**
+     * Start gRPC server
+     * Called automatically by listen() if gRPC is configured
+     */
+    startGrpc(): Promise<void>;
+    /**
+     * Stop gRPC server gracefully
+     */
+    stopGrpc(): Promise<void>;
+    /**
+     * Create a gRPC client for calling remote services
+     *
+     * @example
+     * ```typescript
+     * const client = await app.createGrpcClient(
+     *   './proto/users.proto',
+     *   'UserService',
+     *   'localhost:50051'
+     * );
+     *
+     * const user = await client.getUser({ id: '123' });
+     * ```
+     */
+    createGrpcClient(protoPath: string, serviceName: string, address: string, options?: Partial<GrpcClientOptions>): Promise<GrpcClient>;
+    /**
+     * Get gRPC statistics
+     */
+    getGrpcStats(): any;
+    /**
+     * Get list of registered gRPC services
+     */
+    getGrpcServices(): any;
+    /**
+     * Initialize queue system (synchronous for first queue, subsequent queues added immediately)
+     *
+     * @example
+     * ```typescript
+     * app.queueInit('emails', {
+     *   adapter: 'bull',
+     *   connection: {
+     *     host: 'localhost',
+     *     port: 6379
+     *   },
+     *   concurrency: 5
+     * });
+     * ```
+     */
+    queueInit(name: string, options: any): this;
+    /**
+     * Ensure queue system is initialized
+     */
+    private ensureQueueInitialized;
+    /**
+     * @deprecated Use queueInit() instead
+     */
+    queue(name: string, options: any): Promise<void>;
+    /**
+     * Add a job to a queue
+     *
+     * @example
+     * ```typescript
+     * await app.addToQueue('emails', {
+     *   to: 'user@example.com',
+     *   subject: 'Welcome'
+     * }, {
+     *   priority: 10,
+     *   delay: 5000
+     * });
+     * ```
+     */
+    addToQueue<T = any>(queueName: string, data: T, options?: any): Promise<any>;
+    /**
+     * Add multiple jobs to a queue in bulk
+     *
+     * @example
+     * ```typescript
+     * await app.addBulkToQueue('emails', [
+     *   { data: { to: 'user1@example.com' }, options: { priority: 1 } },
+     *   { data: { to: 'user2@example.com' }, options: { priority: 2 } }
+     * ]);
+     * ```
+     */
+    addBulkToQueue<T = any>(queueName: string, jobs: Array<{
+        data: T;
+        options?: any;
+    }>): Promise<any[]>;
+    /**
+     * Register a processor for a queue
+     *
+     * @example
+     * ```typescript
+     * // Simple processor
+     * app.processQueue('emails', async (job) => {
+     *   await sendEmail(job.data);
+     * });
+     *
+     * // With concurrency
+     * app.processQueue('images', 3, async (job) => {
+     *   await processImage(job.data);
+     * });
+     * ```
+     */
+    processQueue<R = any>(queueName: string, concurrencyOrHandler: number | ((job: any) => Promise<R>), handler?: (job: any) => Promise<R>): Promise<void>;
+    /**
+     * Get queue status
+     */
+    getQueueStatus(queueName: string): Promise<any>;
+    /**
+     * Get a specific job from a queue
+     */
+    getJob(queueName: string, jobId: string): Promise<any>;
+    /**
+     * Get jobs from a queue by status
+     */
+    getJobs(queueName: string, status?: 'waiting' | 'active' | 'completed' | 'failed' | 'delayed' | 'paused', start?: number, end?: number): Promise<any[]>;
+    /**
+     * Remove a job from a queue
+     */
+    removeJob(queueName: string, jobId: string): Promise<void>;
+    /**
+     * Retry a failed job
+     */
+    retryJob(queueName: string, jobId: string): Promise<void>;
+    /**
+     * Pause a queue
+     */
+    pauseQueue(queueName: string): Promise<void>;
+    /**
+     * Resume a paused queue
+     */
+    resumeQueue(queueName: string): Promise<void>;
+    /**
+     * Clean old jobs from a queue
+     */
+    cleanQueue(queueName: string, gracePeriod: number, status?: 'waiting' | 'active' | 'completed' | 'failed' | 'delayed' | 'paused'): Promise<void>;
+    /**
+     * Get all registered queue names
+     */
+    getQueueNames(): string[];
+    /**
+     * Check if a queue is registered
+     */
+    hasQueue(queueName: string): boolean;
+    /**
+     * Configure mail system (synchronous, lazy initialization)
+     *
+     * @example
+     * ```typescript
+     * // Using Nodemailer (SMTP) - chainable, no await needed!
+     * app.mailInit({
+     *   adapter: 'nodemailer',
+     *   from: { name: 'My App', email: 'noreply@myapp.com' },
+     *   connection: {
+     *     host: 'smtp.gmail.com',
+     *     port: 587,
+     *     secure: false,
+     *     auth: { user: process.env.EMAIL_USER, pass: process.env.EMAIL_PASSWORD }
+     *   },
+     *   templates: { path: './emails', engine: 'moro', cache: true }
+     * });
+     *
+     * // Using SendGrid
+     * app.mailInit({
+     *   adapter: 'sendgrid',
+     *   from: 'noreply@myapp.com',
+     *   connection: { apiKey: process.env.SENDGRID_API_KEY }
+     * });
+     * ```
+     */
+    mailInit(config: MailConfig): this;
+    /**
+     * Lazy initialize mail system on first use
+     */
+    private ensureMailInitialized;
+    /**
+     * Send an email
+     *
+     * @example
+     * ```typescript
+     * // Simple email
+     * await app.sendMail({
+     *   to: 'user@example.com',
+     *   subject: 'Welcome',
+     *   text: 'Welcome to our app!'
+     * });
+     *
+     * // With template
+     * await app.sendMail({
+     *   to: 'user@example.com',
+     *   subject: 'Password Reset',
+     *   template: 'password-reset',
+     *   data: { name: 'John', resetUrl: 'https://myapp.com/reset/token123' }
+     * });
+     *
+     * // With attachments
+     * await app.sendMail({
+     *   to: 'user@example.com',
+     *   subject: 'Invoice',
+     *   template: 'invoice',
+     *   data: { invoice },
+     *   attachments: [{ filename: 'invoice.pdf', content: pdfBuffer }]
+     * });
+     * ```
+     */
+    sendMail(options: MailOptions): Promise<MailResult>;
+    /**
+     * Send multiple emails in bulk
+     *
+     * @example
+     * ```typescript
+     * await app.sendBulkMail([
+     *   { to: 'user1@example.com', subject: 'Hello', text: 'Hi!' },
+     *   { to: 'user2@example.com', subject: 'Hello', text: 'Hi!' }
+     * ]);
+     * ```
+     */
+    sendBulkMail(options: MailOptions[]): Promise<MailResult[]>;
+    /**
+     * Verify mail adapter connection
+     */
+    verifyMail(): Promise<boolean>;
+    /**
+     * Get mail template engine for advanced usage
+     */
+    getMailTemplateEngine(): any;
+    /**
+     * Check if mail system is configured
+     */
+    hasMailSystem(): boolean;
 }
 export declare function createApp(options?: MoroOptions): Moro;
 export declare function createAppNode(options?: Omit<MoroOptions, 'runtime'>): Moro;