@fnet/cron-time-segmenter

The "@fnet/cron-time-segmenter" is a simple utility designed to generate and manage time-based segments based on a specified cron pattern. This project primarily serves users who need structured time intervals for tasks scheduling or reporting, providing a straightforward way to handle these operations with customization options.

How It Works

In essence, the "@fnet/cron-time-segmenter" leverages cron expressions to determine time segments over a defined interval. Users can customize the number of segments, the granularity of these intervals, and the timezone in use. The tool updates its time segments according to the cron pattern and triggers a user-defined callback whenever a change in segments occurs.

Once initialized, the utility can continue monitoring time transitions and update the segments in real-time, depending on its configuration, while also providing an option to stop the job when desired.

Key Features

Cron-Based Time Segmentation: Defines time intervals using cron patterns, enabling versatile scheduling.
Customizable: User-defined number of segments, look-back period, and timezone settings.
Real-Time Updates: Optional callback function that alerts whenever there's an adjustment in the time segments.
Stop Functionality: Ability to halt the segment update process at any time as needed.

Conclusion

The "@fnet/cron-time-segmenter" offers a modest but effective solution for users who require cron-based time management and segmentation. Its simplicity and ease of use ensure that specific scheduling tasks can be handled efficiently, with minimal setup and configuration.

@fnet/cron-time-segmenter Developer Guide

Overview

The @fnet/cron-time-segmenter library provides developers with tools to generate and manage time-based segments based on cron expressions. These segments are generated according to specified time intervals and can be easily formatted and manipulated. Additionally, the library allows for real-time updates through an optional subscription mechanism, empowering applications to react dynamically to time changes.

Installation

To install the @fnet/cron-time-segmenter library in your project, you can use either npm or yarn:

npm install @fnet/cron-time-segmenter

yarn add @fnet/cron-time-segmenter

Usage

The core functionality of the library revolves around the index function, which creates time segments according to a cron pattern. Below is a simplified example demonstrating how to use the library:

import cronTimeSegmenter from '@fnet/cron-time-segmenter';

async function useCronSegmenter() {
  // Initialize segmenter with custom settings
  const { segments, stop } = cronTimeSegmenter({
    count: 5, // Generate 5 segments
    pattern: '*/5 * * * *', // Every 5 minutes
    back: 2, // Go back two intervals
    tz: 'America/New_York', // Use New York timezone
    format: 'YYYY-MM-DD HH:mm:ss', // Custom date format
    onUpdate: (newSegments) => {
      console.log('Updated Segments:', newSegments);
    }
  });

  console.log('Initial Segments:', segments);

  // To stop the cron updates
  setTimeout(() => {
    stop();
    console.log('Cron job stopped.');
  }, 300000); // Stops after 5 minutes
}

useCronSegmenter();

Examples

Here are some concise examples to showcase common usage of the library:

Example 1: Basic Usage

import cronTimeSegmenter from '@fnet/cron-time-segmenter';

// Generate segments for every hour
const { segments } = cronTimeSegmenter({
  pattern: '0 * * * *', // Top of every hour
});

console.log('Hourly Segments:', segments);

Example 2: Using Custom Timezone and Format

import cronTimeSegmenter from '@fnet/cron-time-segmenter';

// Generate segments for every day at midnight, using a specific timezone
const { segments } = cronTimeSegmenter({
  pattern: '0 0 * * *', // Every day at midnight
  tz: 'Europe/London',
  format: 'DD/MM/YYYY',
});

console.log('Daily Segments (London time):', segments);

Example 3: Listening to Updates

import cronTimeSegmenter from '@fnet/cron-time-segmenter';

// Setup segmenter with update listener
const { stop } = cronTimeSegmenter({
  pattern: '*/10 * * * *', // Every 10 minutes
  onUpdate: (segments) => {
    console.log('New Segments:', segments);
  }
});

// Stop the updates after some time if needed
setTimeout(() => stop(), 600000); // Example: stop after 10 minutes

Acknowledgement

This library utilizes well-known libraries like node-cron for scheduling, cron-parser for parsing cron patterns, and moment-timezone for date and time formatting.

Input Schema

$schema: https://json-schema.org/draft/2020-12/schema
type: object
properties:
  count:
    type: integer
    description: The number of segments to generate.
    default: 3
  pattern:
    type: string
    description: The cron pattern representing the time interval for each segment.
    default: "* * * * *"
  back:
    type: integer
    description: The step size in terms of cron intervals to go back in time for
      each segment.
    default: 1
  tz:
    type: string
    description: The timezone to use for scheduling and formatting dates.
    default: UTC
  onUpdate:
    type: object
    description: Optional callback function that triggers when a new segment is
      added or removed.
    format: function
  format:
    type: string
    description: Optional date format.
    default: YYYYMMDD.HHmmss
required: []