Scheduler

Manages task execution with priority-based scheduling, batching, and concurrency control.

Import

import { Scheduler } from '@soulcache/core';

Constructor

new Scheduler(options?: SchedulerOptions)

Parameters

Parameter	Type	Default	Description
`maxQueueSize`	`number`	`10000`	Maximum tasks in queue
`eventBus`	`EventBus`	—	Optional event bus for metrics

Properties

Property	Type	Description
`isDestroyed`	`boolean`	Whether scheduler is destroyed
`queueSize`	`number`	Current queue size
`activeTaskCount`	`number`	Number of currently running tasks

Methods

`schedule(options)`

Schedule a task for execution. Returns a task ID.

schedule(options: ScheduleTaskOptions): string

`cancel(taskId)`

Cancel a scheduled task.

cancel(taskId: string): boolean

`getTask(taskId)`

Get a scheduled task by ID.

getTask(taskId: string): ScheduledTask | undefined

`getTasksByStatus(status)`

Get tasks filtered by status.

getTasksByStatus(status: TaskStatus): ScheduledTask[]

`getTasksByCategory(category)`

Get tasks filtered by category.

getTasksByCategory(category: TaskCategory): ScheduledTask[]

`flush()`

Execute all pending tasks.

flush(): number

`flushCategory(category)`

Execute pending tasks in a specific category.

flushCategory(category: TaskCategory): number

`flushIdle()`

Execute idle-priority tasks.

flushIdle(): number

`getMetrics()`

Get scheduler metrics.

getMetrics(): SchedulerMetrics

`destroy()`

Destroy the scheduler and cancel all tasks.

destroy(): void

Types

`ScheduleTaskOptions`

interface ScheduleTaskOptions {
  category: TaskCategory;
  priority?: TaskPriority;              // default: 'normal'
  fn: () => void | Promise<void>;
  owner?: string;                       // default: 'internal'
  dependencies?: readonly string[];
  metadata?: Record<string, unknown>;
}

`ScheduledTask`

interface ScheduledTask {
  readonly id: string;
  readonly owner: string;
  readonly category: TaskCategory;
  readonly priority: TaskPriority;
  status: TaskStatus;
  readonly fn: () => void | Promise<void>;
  readonly dependencies: readonly string[];
  readonly metadata: Record<string, unknown>;
  readonly createdAt: number;
  startedAt: number | undefined;
  completedAt: number | undefined;
  error: Error | undefined;
}

`TaskCategory`

type TaskCategory =
  | 'query-execution'
  | 'mutation-execution'
  | 'cache-update'
  | 'cache-cleanup'
  | 'observer-notification'
  | 'event-dispatch'
  | 'persistence'
  | 'plugin-hook'
  | 'internal-maintenance';

`TaskPriority`

type TaskPriority = 'critical' | 'high' | 'normal' | 'low' | 'idle';

`TaskStatus`

type TaskStatus = 'pending' | 'queued' | 'running' | 'completed' | 'failed' | 'cancelled';

`SchedulerMetrics`

interface SchedulerMetrics {
  readonly totalScheduled: number;
  readonly totalCompleted: number;
  readonly totalFailed: number;
  readonly totalCancelled: number;
  readonly queueSize: number;
  readonly activeTaskCount: number;
  readonly flushCount: number;
  readonly batchCount: number;
}

Usage

import { Scheduler } from '@soulcache/core';
 
const scheduler = new Scheduler({ maxQueueSize: 5000 });
 
// Schedule a high-priority cache update
const taskId = scheduler.schedule({
  category: 'cache-update',
  priority: 'high',
  fn: () => cache.set({ queryKey: ['users'], data: users }),
  owner: 'query-client',
});
 
// Schedule with dependencies
const taskId2 = scheduler.schedule({
  category: 'observer-notification',
  priority: 'normal',
  fn: () => notifyObservers(),
  dependencies: [taskId],
});
 
// Check metrics
const metrics = scheduler.getMetrics();
console.log(`Completed: ${metrics.totalCompleted}, Queue: ${metrics.queueSize}`);

Best Practices

Scheduler Guidelines

Use appropriate priorities — Ensure critical tasks run first
Declare dependencies — Maintain correct execution order
Keep tasks short — Don't block the scheduler
Monitor queue size — Detect overload early

Scheduler

On this page