@useschedo/node

The official Node.js SDK for Schedo, a job scheduling and execution management service.

Installation

npm install @useschedo/node
# or
yarn add @useschedo/node
# or
pnpm add @useschedo/node

Quick Start

import {
  SchedoSDK,
  ExecutionInterval,
  withApiKey,
  withBaseURL,
} from "@useschedo/node";

async function main() {
  // Initialize the SDK with your API key
  const sdk = new SchedoSDK(
    withApiKey("YOUR_API_KEY"),
  );

  // Define a job that runs every minute
  await sdk.defineJob(
    "example_job",
    ExecutionInterval.EveryMinute,
    async (ctx) => {
      console.log("Executing job...");
      return "Job completed successfully";
    },
  );

  // Start listening for job execution events
  sdk.start();

  // Keep the process running
  setInterval(() => {}, 1000 * 60);
}

main().catch(console.error);

Core Concepts

The Schedo SDK allows you to define jobs with specific schedules and execute them when triggered. The main components are:

• SchedoSDK: The main class for job scheduling and execution management
• Jobs: Tasks defined with a name, schedule, and execution function
• Executors: Functions that run when a job is triggered
• Execution Context: Context object available to executors containing job metadata and utilities

Detailed Usage

Initializing the SDK

import { SchedoSDK, withApiKey, withBaseURL, withVerbose } from "@useschedo/node";

const sdk = new SchedoSDK(
  withApiKey("YOUR_API_KEY"),
  withVerbose(true), // Optional: enables verbose logging
);

Scheduling Jobs

import { ExecutionInterval, withTimeout, withMetadata, withBlocking } from "@useschedo/node";

// Define a job with a cron expression
await sdk.defineJob(
  "cron_job_example",
  "0 9 * * 1-5", // Runs at 9 AM on weekdays
  async (ctx) => {
    console.log("Running weekday morning job");
    return { status: "success" };
  },
  withTimeout(30), // Optional: 30 second timeout
  withMetadata({ category: "reports" }), // Optional: adds metadata to the job
  withBlocking(true), // Optional: makes job execution blocking
);

// Define a job with predefined intervals
await sdk.defineJob(
  "interval_job_example",
  ExecutionInterval.Hourly,
  async (ctx) => {
    console.log("Running hourly job");
    const { metadata } = ctx;
    return { processedAt: new Date().toISOString() };
  }
);

Available Execution Intervals

The SDK provides convenient constants for common execution intervals:

import { ExecutionInterval } from "@useschedo/node";

ExecutionInterval.EveryMinute  // "* * * * *"
ExecutionInterval.Hourly       // "0 * * * *"
ExecutionInterval.Daily        // "0 0 * * *"
ExecutionInterval.Weekly       // "0 0 * * 0"
ExecutionInterval.Monthly      // "0 0 1 * *"

Working with Execution Context

Every job executor receives a context object with useful information and utilities:

await sdk.defineJob(
  "context_example",
  ExecutionInterval.Daily,
  async (ctx) => {
    // Access job metadata
    const { metadata } = ctx;

    // Access execution info
    console.log(`Executing job: ${ctx.jobCode}`);
    console.log(`Execution ID: ${ctx.executionId}`);

    // Perform job work...

    return { completed: true, timestamp: new Date().toISOString() };
  },
  withMetadata({ owner: "analytics-team", priority: "high" })
);

Starting and Stopping the SDK

// Start listening for job execution events
sdk.start();

// Stop listening for job execution events
sdk.stop();

Configuration Options

SDK Options

| Option | Function | Description | Default | |--------|----------|-------------|---------| | API Key | withApiKey(key) | Sets the API key for authentication | Required | | Verbose | withVerbose(boolean) | Enables verbose logging | false |

Job Definition Options

| Option | Function | Description | Default | |--------|----------|-------------|---------| | Blocking | withBlocking(boolean) | Sets whether job execution should block | false | | Metadata | withMetadata(object) | Sets metadata for the job | {} | | Timeout | withTimeout(seconds) | Sets timeout duration in seconds | 0 |

Error Handling

The SDK automatically handles many types of errors, including:

• Job execution timeouts
• Executor failures
• Network and connection issues

try {
  await sdk.defineJob(
    "error_handling_example",
    ExecutionInterval.Daily,
    async (ctx) => {
      // This job might fail
      if (Math.random() > 0.5) {
        throw new Error("Random failure");
      }
      return { success: true };
    },
    withTimeout(5) // Set a 5-second timeout
  );
} catch (error) {
  console.error("Failed to define job:", error);
}

Advanced Usage

Custom Error Handling

await sdk.defineJob(
  "custom_error_handler",
  ExecutionInterval.Hourly,
  async (ctx) => {
    try {
      // Attempt to perform work
      const result = await performRiskyOperation();
      return { success: true, result };
    } catch (error) {
      // Log error details and return formatted error
      console.error("Operation failed:", error);
      return { success: false, error: error.message };
    }
  }
);

License

MIT