@bernierllc/scheduler-service

Service layer for job scheduling with cron management and queue integration

Orchestrates cron scheduling functionality with message queue integration and event publishing. Manages scheduled jobs, handles recurring schedules, and provides scheduling workflow orchestration.

Installation

npm install @bernierllc/scheduler-service

Usage

Basic Usage

import { SchedulerService, JobType, ScheduleType } from '@bernierllc/scheduler-service';

const scheduler = new SchedulerService({
  maxConcurrentJobs: 10,
  defaultTimezone: 'UTC'
});

// Start the scheduler
await scheduler.startScheduler();

// Schedule a one-time content publishing job
const job = await scheduler.scheduleContentPublishing('content-123', {
  type: ScheduleType.ONCE,
  publishAt: new Date('2025-01-01T12:00:00Z')
});

console.log(`Job scheduled: ${job.id}`);

Using the Factory

import { SchedulerServiceFactory } from '@bernierllc/scheduler-service';

// Create a content-optimized scheduler
const contentScheduler = SchedulerServiceFactory.createContentScheduler();

// Create a basic scheduler for simple tasks
const basicScheduler = SchedulerServiceFactory.createBasicScheduler();

// Create a development scheduler with enhanced logging
const devScheduler = SchedulerServiceFactory.createDevelopmentScheduler();

Using Utilities

import { SchedulerUtils, JobType } from '@bernierllc/scheduler-service';

// Create schedule configurations
const oneTime = SchedulerUtils.createOneTimeSchedule(
  new Date('2025-01-01T12:00:00Z'),
  'America/New_York'
);

const daily = SchedulerUtils.createCronSchedule('0 9 * * *'); // Daily at 9 AM

const natural = SchedulerUtils.createNaturalSchedule('every weekday at 2pm');

// Create job configurations
const contentJob = SchedulerUtils.createContentPublishJob(
  'content-456', 
  oneTime,
  ['twitter', 'facebook']
);

const workflowJob = SchedulerUtils.createWorkflowTriggerJob(
  'workflow-789',
  daily,
  { triggerData: 'value' }
);

API Reference

SchedulerService

Configuration Options

interface SchedulerServiceConfig {
  maxConcurrentJobs: number;
  defaultTimezone: string;
  jobRetention: {
    completedJobs: number; // days
    failedJobs: number; // days
  };
  retryDefaults: {
    attempts: number;
    delay: number;
    exponentialBackoff: boolean;
  };
  events: {
    enabled: boolean;
    publishToNeverHub: boolean;
  };
  logging: {
    enabled: boolean;
    level: LogLevel;
  };
}

Core Methods

Job Scheduling

• scheduleJob(jobConfig: JobConfig): Promise<ScheduledJob>
• scheduleContentPublishing(contentId: string, schedule: ScheduleConfig): Promise<ScheduledJob>
• scheduleRecurring(recurringConfig: JobConfig): Promise<ScheduledJob>

Job Management

• cancelJob(jobId: string): Promise<boolean>
• pauseJob(jobId: string): Promise<boolean>
• resumeJob(jobId: string): Promise<boolean>
• rescheduleJob(jobId: string, newSchedule: ScheduleConfig): Promise<ScheduledJob>

Job Queries

• getJob(jobId: string): Promise<ScheduledJob | null>
• listJobs(filters?: JobFilters): Promise<ScheduledJob[]>
• getUpcomingJobs(timeWindow?: number): Promise<ScheduledJob[]>

Batch Operations

• scheduleBatch(jobs: JobConfig[]): Promise<BatchScheduleResult>
• cancelBatch(jobIds: string[]): Promise<BatchOperationResult>

Service Management

• startScheduler(): Promise<void>
• stopScheduler(): Promise<void>
• getSchedulerStatus(): Promise<SchedulerStatus>

Types

JobConfig

interface JobConfig {
  id?: string;
  name: string;
  type: JobType;
  schedule: ScheduleConfig;
  payload: Record<string, any>;
  options?: JobOptions;
}

ScheduleConfig

interface ScheduleConfig {
  type: ScheduleType;
  expression?: string; // Cron or natural language
  publishAt?: Date;
  recurring?: RecurringConfig;
  timezone?: string;
  exceptions?: Date[];
}

Job Types

• CONTENT_PUBLISH - Content publishing jobs
• WORKFLOW_TRIGGER - Workflow trigger jobs
• MAINTENANCE - System maintenance jobs
• CUSTOM - Custom job types

Schedule Types

• ONCE - One-time execution
• RECURRING - Recurring execution with cron
• NATURAL - Natural language scheduling

Examples

Content Publishing Workflow

import { SchedulerService, SchedulerUtils, JobType } from '@bernierllc/scheduler-service';

const scheduler = new SchedulerService();
await scheduler.startScheduler();

// Schedule immediate publishing
const immediateJob = await scheduler.scheduleContentPublishing('article-123', {
  type: ScheduleType.ONCE,
  publishAt: new Date(Date.now() + 5000) // 5 seconds from now
});

// Schedule recurring social media posts
const socialSchedule = SchedulerUtils.createCronSchedule('0 9,15,21 * * *'); // 3 times daily
const socialJob = await scheduler.scheduleContentPublishing('social-post-456', socialSchedule);

console.log('Jobs scheduled:', { immediateJob: immediateJob.id, socialJob: socialJob.id });

Batch Operations

import { SchedulerUtils, JobType } from '@bernierllc/scheduler-service';

const jobs = [
  SchedulerUtils.createContentPublishJob('content-1', oneTimeSchedule),
  SchedulerUtils.createContentPublishJob('content-2', oneTimeSchedule),
  SchedulerUtils.createContentPublishJob('content-3', oneTimeSchedule)
];

const result = await scheduler.scheduleBatch(jobs);
console.log(`Scheduled ${result.successful.length}/${result.total} jobs`);

if (result.errors.length > 0) {
  console.error('Errors:', result.errors);
}

Job Monitoring

// Get scheduler status
const status = await scheduler.getSchedulerStatus();
console.log(`Scheduler running: ${status.running}, Active jobs: ${status.activeJobs}`);

// List upcoming jobs
const upcoming = await scheduler.getUpcomingJobs(3600000); // Next hour
console.log('Upcoming jobs:', upcoming.map(j => ({ 
  id: j.id, 
  name: j.name, 
  nextRun: j.nextRun 
})));

// Filter jobs by type
const contentJobs = await scheduler.listJobs({ type: JobType.CONTENT_PUBLISH });
console.log(`Content publishing jobs: ${contentJobs.length}`);

Integration with NeverHub

When NeverHub is detected, the scheduler automatically publishes events:

• job.scheduled - When a job is scheduled
• job.started - When job execution begins
• job.completed - When job completes successfully
• job.failed - When job execution fails
• scheduler.started - When scheduler starts
• scheduler.stopped - When scheduler stops

Dependencies

This package orchestrates several BernierLLC core packages:

• @bernierllc/cron-scheduler - Core cron functionality
• @bernierllc/schedule-parser - Schedule expression parsing
• @bernierllc/message-queue - Job queuing
• @bernierllc/neverhub-adapter - Event publishing (optional)
• @bernierllc/logger - Logging
• @bernierllc/retry-manager - Retry logic for failed jobs

See Also

• @bernierllc/cron-scheduler - Core cron scheduling functionality
• @bernierllc/schedule-parser - Schedule expression parsing
• @bernierllc/content-service - Content management service
• @bernierllc/workflow-service - Workflow orchestration service

License

Copyright (c) 2025 Bernier LLC. All rights reserved.