@engjts/nexus 0.1.0

package/src/advanced/jobs/RedisQueueStore.ts

@@ -0,0 +1,367 @@
+import { QueueStore, Job, JobState, QueueStats } from './types';
+
+/**
+ * Redis queue store configuration
+ */
+export interface RedisQueueConfig {
+    /**
+     * Redis connection URL
+     * @example 'redis://localhost:6379'
+     */
+    url?: string;
+
+    /**
+     * Redis host
+     * @default 'localhost'
+     */
+    host?: string;
+
+    /**
+     * Redis port
+     * @default 6379
+     */
+    port?: number;
+
+    /**
+     * Redis password
+     */
+    password?: string;
+
+    /**
+     * Redis database number
+     * @default 0
+     */
+    db?: number;
+
+    /**
+     * Key prefix for queue data
+     * @default 'nexus:queue:'
+     */
+    prefix?: string;
+
+    /**
+     * Poll interval for delayed jobs in milliseconds
+     * @default 1000
+     */
+    pollInterval?: number;
+}
+
+/**
+ * Redis client interface (compatible with ioredis and node-redis)
+ */
+export interface RedisClientLike {
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string): Promise<any>;
+    del(key: string | string[]): Promise<number>;
+    keys(pattern: string): Promise<string[]>;
+    lpush(key: string, ...values: string[]): Promise<number>;
+    rpop(key: string): Promise<string | null>;
+    lrange(key: string, start: number, stop: number): Promise<string[]>;
+    lrem(key: string, count: number, value: string): Promise<number>;
+    zadd(key: string, ...args: (string | number)[]): Promise<number>;
+    zrangebyscore(key: string, min: number | string, max: number | string): Promise<string[]>;
+    zrem(key: string, ...members: string[]): Promise<number>;
+    hset(key: string, field: string, value: string): Promise<number>;
+    hget(key: string, field: string): Promise<string | null>;
+    hgetall(key: string): Promise<Record<string, string>>;
+    hdel(key: string, ...fields: string[]): Promise<number>;
+    incr(key: string): Promise<number>;
+    expire(key: string, seconds: number): Promise<number>;
+    quit?(): Promise<any>;
+    disconnect?(): Promise<any>;
+}
+
+/**
+ * Redis-based queue store implementation
+ * Provides persistent job storage with support for distributed workers
+ * 
+ * @example
+ * ```typescript
+ * import Redis from 'ioredis';
+ * import { JobQueue, RedisQueueStore } from 'nexus';
+ * 
+ * const redis = new Redis();
+ * const store = new RedisQueueStore('emails', { client: redis });
+ * const queue = new JobQueue('emails', { store });
+ * 
+ * // Add a job
+ * await queue.add('sendEmail', { to: 'user@example.com', subject: 'Hello' });
+ * 
+ * // Process jobs
+ * queue.process('sendEmail', async (job) => {
+ *   await sendEmail(job.data);
+ *   return { sent: true };
+ * });
+ * ```
+ */
+export class RedisQueueStore<Data = any> implements QueueStore<Data> {
+    private client: RedisClientLike;
+    private prefix: string;
+    private queueName: string;
+    private pollInterval: number;
+    private pollTimer?: NodeJS.Timeout;
+
+    constructor(
+        queueName: string,
+        options: RedisQueueConfig & { client: RedisClientLike }
+    ) {
+        this.queueName = queueName;
+        this.client = options.client;
+        this.prefix = options.prefix ?? 'nexus:queue:';
+        this.pollInterval = options.pollInterval ?? 1000;
+    }
+
+    /**
+     * Build Redis key with prefix
+     */
+    private key(type: string): string {
+        return `${this.prefix}${this.queueName}:${type}`;
+    }
+
+    /**
+     * Serialize job to JSON
+     */
+    private serialize(job: Job<Data>): string {
+        return JSON.stringify(job);
+    }
+
+    /**
+     * Deserialize job from JSON
+     */
+    private deserialize(data: string): Job<Data> {
+        return JSON.parse(data);
+    }
+
+    /**
+     * Add a job to the queue
+     */
+    async enqueue(job: Job<Data>): Promise<void> {
+        const serialized = this.serialize(job);
+
+        // Store job data in hash
+        await this.client.hset(this.key('jobs'), job.id, serialized);
+
+        if (job.state === 'delayed') {
+            // Add to delayed set with score = runAt timestamp
+            await this.client.zadd(this.key('delayed'), job.runAt, job.id);
+        } else if (job.state === 'waiting') {
+            // Add to waiting list (with priority handling)
+            await this.client.lpush(this.key(`waiting:${job.priority}`), job.id);
+        }
+
+        // Increment total counter
+        await this.client.incr(this.key('total'));
+    }
+
+    /**
+     * Get the next job to process
+     */
+    async dequeue(): Promise<Job<Data> | undefined> {
+        // First, check delayed jobs that are now ready
+        const now = Date.now();
+        const readyDelayed = await this.client.zrangebyscore(
+            this.key('delayed'),
+            '-inf',
+            now
+        );
+
+        // Move ready delayed jobs to waiting
+        for (const jobId of readyDelayed) {
+            const jobData = await this.client.hget(this.key('jobs'), jobId);
+            if (jobData) {
+                const job = this.deserialize(jobData);
+                job.state = 'waiting';
+                await this.client.hset(this.key('jobs'), jobId, this.serialize(job));
+                await this.client.zrem(this.key('delayed'), jobId);
+                await this.client.lpush(this.key(`waiting:${job.priority}`), jobId);
+            }
+        }
+
+        // Check priority queues (high to low: 10, 5, 0, -5, -10, etc.)
+        const priorities = [10, 5, 0, -5, -10];
+        
+        for (const priority of priorities) {
+            const jobId = await this.client.rpop(this.key(`waiting:${priority}`));
+            if (jobId) {
+                const jobData = await this.client.hget(this.key('jobs'), jobId);
+                if (jobData) {
+                    const job = this.deserialize(jobData);
+                    job.state = 'active';
+                    job.updatedAt = Date.now();
+                    await this.client.hset(this.key('jobs'), jobId, this.serialize(job));
+                    return job;
+                }
+            }
+        }
+
+        // Fallback: check default priority (0)
+        const jobId = await this.client.rpop(this.key('waiting:0'));
+        if (jobId) {
+            const jobData = await this.client.hget(this.key('jobs'), jobId);
+            if (jobData) {
+                const job = this.deserialize(jobData);
+                job.state = 'active';
+                job.updatedAt = Date.now();
+                await this.client.hset(this.key('jobs'), jobId, this.serialize(job));
+                return job;
+            }
+        }
+
+        return undefined;
+    }
+
+    /**
+     * Update job state
+     */
+    async update(job: Job<Data>): Promise<void> {
+        const serialized = this.serialize(job);
+        await this.client.hset(this.key('jobs'), job.id, serialized);
+
+        // Handle state-specific storage
+        if (job.state === 'delayed') {
+            await this.client.zadd(this.key('delayed'), job.runAt, job.id);
+        } else if (job.state === 'waiting') {
+            await this.client.lpush(this.key(`waiting:${job.priority}`), job.id);
+        } else if (job.state === 'completed') {
+            await this.client.lpush(this.key('completed'), job.id);
+            // Set expiry for completed jobs (24 hours)
+            await this.client.expire(this.key('completed'), 86400);
+        } else if (job.state === 'failed') {
+            await this.client.lpush(this.key('failed'), job.id);
+        }
+    }
+
+    /**
+     * Get a job by ID
+     */
+    async get(id: string): Promise<Job<Data> | undefined> {
+        const data = await this.client.hget(this.key('jobs'), id);
+        if (!data) return undefined;
+        return this.deserialize(data);
+    }
+
+    /**
+     * List jobs by state
+     */
+    async list(state?: JobState): Promise<Job<Data>[]> {
+        const allJobs = await this.client.hgetall(this.key('jobs'));
+        const jobs = Object.values(allJobs).map(data => this.deserialize(data));
+
+        if (!state) {
+            return jobs;
+        }
+
+        return jobs.filter(job => job.state === state);
+    }
+
+    /**
+     * Get queue statistics
+     */
+    async stats(): Promise<QueueStats> {
+        const allJobs = await this.client.hgetall(this.key('jobs'));
+        const stats: QueueStats = {
+            waiting: 0,
+            active: 0,
+            completed: 0,
+            failed: 0,
+            delayed: 0
+        };
+
+        for (const data of Object.values(allJobs)) {
+            const job = this.deserialize(data);
+            if (job.state in stats) {
+                (stats as any)[job.state]++;
+            }
+        }
+
+        return stats;
+    }
+
+    /**
+     * Clean old completed/failed jobs
+     */
+    async clean(state: 'completed' | 'failed', olderThanMs: number = 86400000): Promise<number> {
+        const cutoff = Date.now() - olderThanMs;
+        const jobs = await this.list(state);
+        let cleaned = 0;
+
+        for (const job of jobs) {
+            if (job.updatedAt < cutoff) {
+                await this.client.hdel(this.key('jobs'), job.id);
+                await this.client.lrem(this.key(state), 0, job.id);
+                cleaned++;
+            }
+        }
+
+        return cleaned;
+    }
+
+    /**
+     * Disconnect from Redis
+     */
+    async disconnect(): Promise<void> {
+        if (this.pollTimer) {
+            clearInterval(this.pollTimer);
+        }
+        if (this.client.quit) {
+            await this.client.quit();
+        } else if (this.client.disconnect) {
+            await this.client.disconnect();
+        }
+    }
+}
+
+/**
+ * Create a Redis queue store with automatic client creation
+ * Requires 'ioredis' or 'redis' package to be installed
+ * 
+ * @example
+ * ```typescript
+ * const store = await createRedisQueueStore('emails', {
+ *   host: 'localhost',
+ *   port: 6379
+ * });
+ * 
+ * const queue = new JobQueue('emails', { store });
+ * ```
+ */
+export async function createRedisQueueStore<Data = any>(
+    queueName: string,
+    config: RedisQueueConfig = {}
+): Promise<RedisQueueStore<Data>> {
+    let client: RedisClientLike;
+
+    // Try ioredis first
+    try {
+        const Redis = require('ioredis');
+        client = new Redis({
+            host: config.host ?? 'localhost',
+            port: config.port ?? 6379,
+            password: config.password,
+            db: config.db ?? 0
+        });
+    } catch {
+        // Try node-redis
+        try {
+            const { createClient } = require('redis');
+            const url = config.url ?? `redis://${config.host ?? 'localhost'}:${config.port ?? 6379}`;
+            
+            client = createClient({
+                url,
+                password: config.password,
+                database: config.db ?? 0
+            });
+
+            await (client as any).connect();
+        } catch {
+            throw new Error(
+                'Redis client not found. Please install either "ioredis" or "redis" package:\n' +
+                '  npm install ioredis\n' +
+                '  # or\n' +
+                '  npm install redis'
+            );
+        }
+    }
+
+    return new RedisQueueStore<Data>(queueName, { ...config, client });
+}

package/src/advanced/jobs/index.ts

@@ -0,0 +1,5 @@
+export { JobQueue, CronSchedule, ScheduledJobConfig } from './JobQueue';
+export { InMemoryQueueStore } from './InMemoryQueueStore';
+export { RedisQueueStore, createRedisQueueStore } from './RedisQueueStore';
+export type { RedisQueueConfig, RedisClientLike } from './RedisQueueStore';
+export * from './types';

package/src/advanced/jobs/types.ts

@@ -0,0 +1,70 @@
+export type JobState = 'waiting' | 'delayed' | 'active' | 'completed' | 'failed' | 'paused';
+
+
+export interface Job<Data = any, Result = any> {
+    id: string;
+    name: string;
+    data: Data;
+    result?: Result;
+    error?: { message: string; stack?: string };
+    state: JobState;
+    attemptsMade: number;
+    maxAttempts: number;
+    priority: number;
+    createdAt: number;
+    runAt: number;
+    updatedAt: number;
+    metadata?: Record<string, any>;
+}
+
+export interface RetryOptions {
+    attempts?: number;
+    backoff?: 'fixed' | 'exponential';
+    delay?: number;
+    maxDelay?: number;
+}
+
+export interface RateLimitOptions {
+    max: number;
+    duration: number;
+}
+
+export interface QueueHooks<Data = any> {
+    onComplete?: (job: Job<Data>, result: any) => void | Promise<void>;
+    onFailed?: (job: Job<Data>, error: Error) => void | Promise<void>;
+    onRetry?: (job: Job<Data>, attempt: number, delay: number) => void | Promise<void>;
+}
+
+export interface QueueOptions<Data = any> {
+    concurrency?: number;
+    retry?: RetryOptions;
+    limiter?: RateLimitOptions;
+    hooks?: QueueHooks<Data>;
+    store?: QueueStore<Data>;
+}
+
+export interface EnqueueOptions {
+    delay?: number;
+    priority?: number;
+    metadata?: Record<string, any>;
+    attempts?: number;
+}
+
+export type JobHandler<Data = any, Result = any> = (job: Job<Data>) => Promise<Result>;
+
+export interface QueueStore<Data = any> {
+    enqueue(job: Job<Data>): Promise<void>;
+    dequeue(): Promise<Job<Data> | undefined>;
+    update(job: Job<Data>): Promise<void>;
+    get(id: string): Promise<Job<Data> | undefined>;
+    list(state?: JobState): Promise<Job<Data>[]>;
+    stats(): Promise<QueueStats>;
+}
+
+export interface QueueStats {
+    waiting: number;
+    active: number;
+    completed: number;
+    failed: number;
+    delayed: number;
+}

package/src/advanced/observability/APMManager.ts

@@ -0,0 +1,163 @@
+import { APMOptions } from './types';
+import { getSentry, SentryClient } from '../sentry';
+
+/**
+ * APM (Application Performance Monitoring) manager
+ * 
+ * This is a lightweight wrapper that delegates to Sentry when available.
+ * For full APM features (memory leak detection, slow query tracking),
+ * use Sentry integration which has built-in APM support.
+ * 
+ * @example
+ * ```typescript
+ * // Recommended: Use Sentry with APM
+ * import { initSentry } from 'nexus';
+ * 
+ * initSentry({
+ *   dsn: 'your-dsn',
+ *   apm: {
+ *     slowQueryThreshold: 500,
+ *     memoryLeakDetection: { enabled: true }
+ *   }
+ * });
+ * 
+ * // Then use APMManager as facade
+ * const apm = new APMManager();
+ * apm.recordQuery('SELECT * FROM users', 1200);
+ * ```
+ */
+export class APMManager {
+    private options: APMOptions;
+    private sentryClient?: SentryClient | null;
+    
+    // Fallback storage when Sentry is not available
+    private slowQueries: Array<{ query: string; duration: number; timestamp: number; }> = [];
+    private memorySnapshots: Array<{ timestamp: number; heapUsed: number; heapTotal: number; }> = [];
+    private memoryCheckInterval?: NodeJS.Timeout;
+
+    constructor(options: APMOptions = {}) {
+        this.options = options;
+        this.sentryClient = getSentry();
+
+        // If Sentry is not available and memory leak detection is enabled, use fallback
+        if (!this.sentryClient && options.memoryLeakDetection?.enabled) {
+            this.startMemoryMonitoring();
+        }
+    }
+
+    /**
+     * Record a database/external query
+     * Delegates to Sentry when available
+     */
+    recordQuery(query: string, durationMs: number, metadata?: Record<string, any>) {
+        // Delegate to Sentry if available
+        if (this.sentryClient) {
+            this.sentryClient.recordQuery(query, durationMs, metadata);
+            return;
+        }
+
+        // Fallback: store locally
+        const threshold = this.options.slowQueryThreshold ?? 1000;
+        if (durationMs >= threshold) {
+            this.slowQueries.push({
+                query,
+                duration: durationMs,
+                timestamp: Date.now()
+            });
+
+            // Keep last 100 slow queries
+            if (this.slowQueries.length > 100) {
+                this.slowQueries.shift();
+            }
+        }
+    }
+
+    /**
+     * Get slow queries
+     * Delegates to Sentry when available
+     */
+    getSlowQueries() {
+        if (this.sentryClient) {
+            return this.sentryClient.getSlowQueries();
+        }
+        return [...this.slowQueries];
+    }
+
+    private startMemoryMonitoring() {
+        const interval = this.options.memoryLeakDetection?.interval ?? 60000;
+
+        this.memoryCheckInterval = setInterval(() => {
+            const usage = process.memoryUsage();
+            this.memorySnapshots.push({
+                timestamp: Date.now(),
+                heapUsed: usage.heapUsed,
+                heapTotal: usage.heapTotal
+            });
+
+            // Keep last 60 snapshots
+            if (this.memorySnapshots.length > 60) {
+                this.memorySnapshots.shift();
+            }
+
+            // Check for potential memory leak
+            this.checkMemoryLeak();
+        }, interval);
+    }
+
+    private checkMemoryLeak() {
+        if (this.memorySnapshots.length < 10) return;
+
+        const recent = this.memorySnapshots.slice(-10);
+        const oldest = recent[0].heapUsed;
+        const newest = recent[recent.length - 1].heapUsed;
+        const growth = (newest - oldest) / oldest;
+
+        // Parse threshold
+        let threshold = 0.5;
+        const thresholdConfig = this.options.memoryLeakDetection?.threshold;
+        if (typeof thresholdConfig === 'string') {
+            threshold = parseFloat(thresholdConfig.replace('%', '')) / 100;
+        } else if (typeof thresholdConfig === 'number') {
+            threshold = thresholdConfig;
+        }
+
+        // Alert if memory grew more than threshold in the monitoring window
+        if (growth > threshold) {
+            console.warn('[APM] Potential memory leak detected:', {
+                growth: `${(growth * 100).toFixed(1)}%`,
+                from: `${(oldest / 1024 / 1024).toFixed(1)}MB`,
+                to: `${(newest / 1024 / 1024).toFixed(1)}MB`
+            });
+        }
+    }
+
+    /**
+     * Get memory statistics
+     * Delegates to Sentry when available
+     */
+    getMemoryStats() {
+        if (this.sentryClient) {
+            return this.sentryClient.getMemoryStats();
+        }
+
+        const current = process.memoryUsage();
+        return {
+            current: {
+                heapUsed: current.heapUsed,
+                heapTotal: current.heapTotal,
+                external: current.external,
+                rss: current.rss
+            },
+            history: this.memorySnapshots
+        };
+    }
+
+    /**
+     * Stop APM monitoring
+     */
+    stop() {
+        if (this.memoryCheckInterval) {
+            clearInterval(this.memoryCheckInterval);
+        }
+    }
+}