⚡ Lightning Timer

High-performance TypeScript library for managing large volumes of timers with nanosecond precision. Features a priority queue-based implementation with support for webhooks, Kafka messages, and custom function callbacks.

Features

• Nanosecond Precision: Uses Node.js high-resolution time for precise scheduling
• Priority Queue: Efficient min-heap implementation for O(log n) operations
• Game Loop Architecture: Configurable tick rate for processing timers
• Dynamic Callbacks: Support for webhooks, Kafka messages, and custom functions
• Concurrent Execution: Configurable max concurrent callback executions
• Retry Logic: Built-in retry mechanism for failed callbacks
• High Performance: Optimized for handling thousands of timers per second

Installation

npm install lightning-timer

Quick Start

import { LightningTimer } from 'lightning-timer';

const timer = new LightningTimer({
  tickRate: 1,  // Check timers every 1ms
  maxConcurrentCallbacks: 100,
  enableLogging: true
});

// Schedule using UTC timestamp (milliseconds)
const futureTime = Date.now() + 5000; // 5 seconds from now
timer.scheduleFunctionAt(futureTime, () => {
  console.log('Timer executed!');
});

// Schedule using nanosecond timestamp (BigInt)
const nanoTime = BigInt(Date.now()) * 1000000n + 100000000n; // 100ms from now in nanoseconds
timer.scheduleFunctionAt(nanoTime, () => {
  console.log('Precise timer executed!');
});

// Or use convenience methods with delay in ms
timer.scheduleFunction(100, () => {
  console.log('Timer after 100ms!');
});

// Schedule a webhook at specific time
const webhookTime = new Date('2025-01-26T10:00:00Z').getTime();
timer.scheduleWebhookAt(webhookTime, {
  url: 'https://api.example.com/webhook',
  method: 'POST',
  body: { message: 'Scheduled webhook' }
});

// Start the timer
timer.start();

API Reference

LightningTimer

const timer = new LightningTimer({
  tickRate?: number;              // Game loop tick rate in ms (default: 1)
  maxConcurrentCallbacks?: number; // Max concurrent executions (default: 100)
  enableLogging?: boolean;         // Enable debug logging (default: false)
});

Scheduling Methods

Schedule at specific UTC timestamp:

// Using millisecond timestamp (number)
timer.scheduleAt(timestampMs: number, callback: TimerCallback, metadata?: any): string;
timer.scheduleFunctionAt(timestampMs: number, fn: () => void | Promise<void>, metadata?: any): string;
timer.scheduleWebhookAt(timestampMs: number, config: WebhookConfig, metadata?: any): string;
timer.scheduleKafkaAt(timestampMs: number, config: KafkaConfig, metadata?: any): string;

// Using nanosecond timestamp (bigint)
const nanoTime = BigInt(Date.now()) * 1000000n;
timer.scheduleAt(nanoTime, callback, metadata): string;

Schedule with delay (convenience methods):

// Schedule with delay in milliseconds from now
timer.schedule(delayMs: number, callback: TimerCallback, metadata?: any): string;
timer.scheduleFunction(delayMs: number, fn: () => void | Promise<void>, metadata?: any): string;
timer.scheduleWebhook(delayMs: number, config: WebhookConfig, metadata?: any): string;
timer.scheduleKafka(delayMs: number, config: KafkaConfig, metadata?: any): string;

Kafka Configuration

import { CallbackExecutor } from 'lightning-timer';

const executor = new CallbackExecutor();
await executor.configureKafka({
  clientId: 'timer-service',
  brokers: ['localhost:9092'],
  ssl: true,
  sasl: {
    mechanism: 'plain',
    username: 'user',
    password: 'pass'
  }
});

Examples

Running Examples

npm run example:basic    # Basic timer functionality
npm run example:webhook  # Webhook integration example
npm run example:stress   # Stress test with 10,000 timers

Stress Test Performance

The library can handle 10,000+ timers efficiently:

// Schedule 10,000 timers at specific timestamps
const baseTime = Date.now();
for (let i = 0; i < 10000; i++) {
  const executeAt = baseTime + Math.random() * 1000;
  timer.scheduleFunctionAt(executeAt, () => {
    // Timer callback
  });
}

Architecture

• Priority Queue: Min-heap for O(log n) insertion/extraction
• Game Loop: Continuous processing at configured tick rate
• Nanosecond Timing: Using process.hrtime.bigint() for precision
• Batch Processing: Processes multiple ready timers per tick
• Concurrent Limits: Prevents overwhelming system resources

Performance Considerations

• Tick rate affects precision vs CPU usage trade-off
• Lower tick rates (1ms) provide better precision but higher CPU usage
• Adjust maxConcurrentCallbacks based on your system resources
• For Kafka callbacks, ensure producer is properly configured before use

License

MIT