Package Exports

lightning-timer
lightning-timer/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (lightning-timer) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

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 { TimerManager } from 'lightning-timer';

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

// Schedule a simple function
manager.scheduleFunction(100, () => {
  console.log('Timer executed!');
});

// Schedule a webhook
manager.scheduleWebhook(500, {
  url: 'https://api.example.com/webhook',
  method: 'POST',
  body: { message: 'Timer triggered' }
});

// Start the timer manager
manager.start();

API Reference

TimerManager

const manager = new TimerManager({
  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 with custom callback object
manager.scheduleTimer(delayMs: number, callback: TimerCallback, metadata?: any): string;

// Schedule webhook call
manager.scheduleWebhook(delayMs: number, config: WebhookConfig, metadata?: any): string;

// Schedule Kafka message
manager.scheduleKafkaMessage(delayMs: number, config: KafkaConfig, metadata?: any): string;

// Schedule function execution
manager.scheduleFunction(delayMs: number, fn: () => void | Promise<void>, 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:

for (let i = 0; i < 10000; i++) {
  manager.scheduleFunction(Math.random() * 1000, () => {
    // 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