@memberjunction/scheduling-engine-base

Base scheduling engine providing metadata caching for MemberJunction’s scheduled jobs system. Loads and caches job types, scheduled jobs, and recent runs. Can be used on both client and server.

Architecture

graph TD
    subgraph "@memberjunction/scheduling-engine-base"
        A[SchedulingEngineBase] --> B[Job Types Cache]
        A --> C[Scheduled Jobs Cache]
        A --> D[Job Runs Cache]
        A --> E[Polling Interval<br/>Calculator]
        F[MJScheduledJobEntityExtended] --> A
    end

    subgraph "Data Sources"
        G["MJ: Scheduled Job Types"]
        H["MJ: Scheduled Jobs"]
        I["MJ: Scheduled Job Runs"]
    end

    G --> B
    H --> C
    I --> D

    J["@memberjunction/scheduling-engine<br/>(Server Execution)"] -->|extends| A

    style A fill:#2d6a9f,stroke:#1a4971,color:#fff
    style B fill:#2d8659,stroke:#1a5c3a,color:#fff
    style C fill:#2d8659,stroke:#1a5c3a,color:#fff
    style D fill:#2d8659,stroke:#1a5c3a,color:#fff
    style E fill:#7c5295,stroke:#563a6b,color:#fff
    style F fill:#b8762f,stroke:#8a5722,color:#fff
    style J fill:#7c5295,stroke:#563a6b,color:#fff

Overview

This package provides two main components:

SchedulingEngineBase

A singleton engine that extends BaseEngine to load and cache scheduling metadata:

• Job Types: Plugin registry mapping job type names to driver classes
• Scheduled Jobs: Active (or all) scheduled jobs with their configurations
• Job Runs: Recent execution history (last 7 days, optional)
• Polling Interval: Adaptive polling interval calculation based on next run times
• Lookup Methods: Find job types by name or driver class, get jobs by type, get runs for a job

MJScheduledJobEntityExtended

An extended entity class registered via @RegisterClass that adds helper properties and methods to ScheduledJobEntity:

• Lock Management: IsLocked, IsLockStale, CurrentLockHolder properties
• Concurrency: AllowsConcurrent, QueuesOverlappingRuns, SkipsOverlappingRuns
• Statistics: SuccessRate, FailureRate percentage calculations
• Timing: GetTimeUntilNextRun() millisecond calculation
• Auto-Notifications: Overrides Save() and Delete() to auto-refresh engine metadata and recalculate polling intervals

Installation

npm install @memberjunction/scheduling-engine-base

Usage

Loading Metadata

import { SchedulingEngineBase } from '@memberjunction/scheduling-engine-base';

const engine = SchedulingEngineBase.Instance;

// Load active jobs only (default)
await engine.Config(false, contextUser);

// Load all jobs with recent runs
await engine.Config(false, contextUser, undefined, true, true);

Accessing Cached Data

// Job types (plugin registry)
const jobTypes = engine.ScheduledJobTypes;
const agentType = engine.GetJobTypeByName('Agent');
const byDriver = engine.GetJobTypeByDriverClass('ScheduledJobAgent');

// Scheduled jobs
const activeJobs = engine.ScheduledJobs;
const agentJobs = engine.GetJobsByType(agentType.ID);

// Job runs
const runs = engine.GetRunsForJob(jobId);

// Adaptive polling
engine.UpdatePollingInterval();
const interval = engine.ActivePollingInterval; // ms, or null if no jobs

Using Extended Entity

import { MJScheduledJobEntityExtended } from '@memberjunction/scheduling-engine-base';

const job = activeJobs[0] as MJScheduledJobEntityExtended;

console.log(job.IsLocked);          // Is currently being executed?
console.log(job.IsLockStale);       // Has the lock expired?
console.log(job.SuccessRate);       // e.g., 95.5
console.log(job.AllowsConcurrent);  // Can run in parallel?
console.log(job.GetTimeUntilNextRun()); // ms until next execution

API Reference

SchedulingEngineBase

Member	Type	Description
Instance	static getter	Singleton instance
Config()	method	Load scheduling metadata with options
ScheduledJobTypes	getter	All job type definitions
ScheduledJobs	getter	Active (or all) scheduled jobs
ScheduledJobRuns	getter	Recent job runs (if loaded)
GetJobTypeByName()	method	Find job type by name
GetJobTypeByDriverClass()	method	Find job type by driver class
GetJobsByType()	method	Get all jobs of a specific type
GetRunsForJob()	method	Get runs for a specific job
ActivePollingInterval	getter	Current polling interval (ms) or null
UpdatePollingInterval()	method	Recalculate optimal polling interval

Relationship to Other Scheduling Packages

graph LR
    A["base-types<br/>(Interfaces)"] --> B["base-engine<br/>(Metadata Cache)"]
    B --> C["engine<br/>(Execution)"]
    A --> D["actions<br/>(Agentic Tools)"]

    style A fill:#2d6a9f,stroke:#1a4971,color:#fff
    style B fill:#2d8659,stroke:#1a5c3a,color:#fff
    style C fill:#7c5295,stroke:#563a6b,color:#fff
    style D fill:#b8762f,stroke:#8a5722,color:#fff

Dependencies

Package	Purpose
@memberjunction/core	BaseEngine, UserInfo, IMetadataProvider
@memberjunction/core-entities	ScheduledJobEntity, ScheduledJobTypeEntity, ScheduledJobRunEntity
@memberjunction/global	RegisterClass decorator
@memberjunction/scheduling-base-types	Shared type definitions

License

ISC