@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