@nendlabs/cloc

A lightweight framework for running and managing background tasks on a schedule. Ideal for scenarios like periodic maintenance, data syncing, or any recurring task in your application.

Installation

npm install @nendlabs/cloc

Quick Start

This example demonstrates how to set up a simple task with a logging dependency:

import { cloc } from '@nendlabs/cloc';
import { Logger } from './logger';

// Define your dependencies
declare global {
  namespace Cloc {
    interface Dependencies {
      logger: ReturnType<(typeof Logger)['createChild']>;
    }
  }
}

// Initialize cloc
cloc({
  tasks: {
    greet: {
      intervalMs: 5000,
      fn: async ({ logger }) => {
        logger.info('Hello from cloc!');
      },
    },
  },
  dependencies: {
    logger: Logger.createChild({ namespace: 'my-app' }),
  },
});

Configuration

The cloc function accepts the following configuration options. Choose the ones that best suit your use case:

interface Config {
  // Define tasks inline
  tasks?: Record<string, Cloc.Task>;
  
  // OR specify a directory containing task files
  tasksDir?: string;
  
  // Dependencies to inject into tasks
  dependencies: Cloc.Dependencies;
  
  // Optional dependency transformer
  transformDependencies?: (
    task: Cloc.Task,
    dependencies: Cloc.Dependencies
  ) => Cloc.Dependencies;
  
  // Optional telemetry configuration
  telemetry?: {
    enabled: boolean;
    project: string;
  };
}

Tasks

Defining Tasks

Tasks can be defined in one of two ways:

Inline Tasks

Inline tasks are directly defined in your configuration object:

cloc({
  tasks: {
    taskName: {
      intervalMs: 5000,
      fn: async (deps) => {
        // Your task logic here
      },
    },
  },
  dependencies: {
    // Your Task function dependencies here
  },
});

File-based Tasks

Organize tasks in separate files for better modularity and scalability:

// tasks/my-task.ts
export default {
  intervalMs: 5000,
  fn: async ({ logger }) => {
    logger.info('Running my task');
  },
} as Cloc.Task;

Then initialize cloc with the tasks directory:

cloc({
  tasksDir: './tasks',
  dependencies: {
    // Your dependencies here
  },
});

Task Dependencies

Set up type-safe dependencies by extending the global Cloc.Dependencies interface. This ensures your tasks have access to the right tools:

import { PrismaClient } from '@prisma/client';

declare global {
  namespace Cloc {
    interface Dependencies {
      prisma: PrismaClient;
      config: ApplicationConfig;
      // Add more dependencies as needed
    }
  }
}

These dependencies will be injected into the task functions and provided to cloc during instantiation.

Transforming Dependencies

Adapt dependencies for specific tasks using a transformer function:

cloc({
  dependencies: {
    logger: Logger.createChild({ namespace: 'my-app' }),
  },
  transformDependencies: (task, dependencies) => {
    // Transform dependencies for this task
    const taskLogger = dependencies.logger.createChild({ namespace: task.name });
    return { ...dependencies, logger: taskLogger };
  },
});

Telemetry

Enable Prometheus-based telemetry metrics using prom-client to monitor task performance:

cloc({
  // ... other config
  telemetry: {
    enabled: true,
    project: 'my-project',
  },
});

Cloc collects the following metrics using Prometheus-compatible instruments:

• Active Tasks (Gauge): Tracks the number of tasks currently running.
• Task Execution Count (Counter): Counts how many times tasks have been executed.
• Task Execution Duration (Histogram): Measures the duration of task executions in milliseconds.
• Task Failures (Counter): Tracks the number of task executions that resulted in errors.

Usage

These metrics help to:

1. Monitor Activity: Use the active gauge to understand task concurrency in real-time.
2. Track Performance: Analyze the duration histogram to identify slow-running tasks.
3. Measure Reliability: Use the failure counter to monitor task stability and troubleshoot errors.
4. Audit Frequency: Leverage the count counter to verify task schedules and execution consistency.

Integrate these insights into your monitoring system to enhance system reliability and performance.