Cron

18 exports Added in v2.0.0 Source

Constructors

make

Added in v2.0.0 Source

Creates a Cron instance.

Signature

declare function make(values: {
  readonly and?: boolean;
  readonly days: Iterable<number>;
  readonly hours: Iterable<number>;
  readonly minutes: Iterable<number>;
  readonly months: Iterable<number>;
  readonly seconds?: Iterable<number, any, any>;
  readonly tz?: TimeZone;
  readonly weekdays: Iterable<number>;
}): Cron

parse

Added in v2.0.0 Source

Parses a cron expression into a Cron instance.

Signature

declare function parse(cron: string, tz?: string | TimeZone): Either<Cron, ParseError>

Example

import * as assert from "node:assert"
import { Cron, Either } from "effect"

// At 04:00 on every day-of-month from 8 through 14.
assert.deepStrictEqual(Cron.parse("0 0 4 8-14 * *"), Either.right(Cron.make({
  seconds: [0],
  minutes: [0],
  hours: [4],
  days: [8, 9, 10, 11, 12, 13, 14],
  months: [],
  weekdays: []
})))

unsafeParse

Added in v2.0.0 Source

Parses a cron expression into a Cron instance.

Details

This function takes a cron expression as a string and attempts to parse it into a Cron instance. If the expression is valid, the resulting Cron instance will represent the schedule defined by the cron expression.

If the expression is invalid, the function throws a ParseError.

You can optionally provide a time zone (tz) to interpret the cron expression in a specific time zone. If no time zone is provided, the cron expression will use the default time zone.

Signature

declare function unsafeParse(cron: string, tz?: string | TimeZone): Cron

Example

import { Cron } from "effect"

// At 04:00 on every day-of-month from 8 through 14.
console.log(Cron.unsafeParse("0 4 8-14 * *"))
// Output:
// {
//   _id: 'Cron',
//   tz: { _id: 'Option', _tag: 'None' },
//   seconds: [ 0 ],
//   minutes: [ 0 ],
//   hours: [ 4 ],
//   days: [
//      8,  9, 10, 11,
//     12, 13, 14
//   ],
//   months: [],
//   weekdays: []
// }

Guards

isCron

Added in v2.0.0 Source

Checks if a given value is a Cron instance.

Signature

declare function isCron(u: unknown): u is Cron

isParseError

Added in v2.0.0 Source

Returns true if the specified value is an ParseError, false otherwise.

Signature

declare function isParseError(u: unknown): u is ParseError

Instances

Equivalence

Added in v2.0.0 Source

Signature

declare const Equivalence: equivalence.Equivalence<Cron>

Models

Cron interface

Added in v2.0.0 Source

Signature

interface Cron extends Pipeable, Equal, Inspectable {
  readonly [TypeId]: typeof TypeId;
  readonly days: ReadonlySet<number>;
  readonly hours: ReadonlySet<number>;
  readonly minutes: ReadonlySet<number>;
  readonly months: ReadonlySet<number>;
  readonly seconds: ReadonlySet<number>;
  readonly tz: Option<TimeZone>;
  readonly weekdays: ReadonlySet<number>;
}

ParseError

Added in v2.0.0 Source

Represents a checked exception which occurs when decoding fails.

Signature

declare class ParseError extends YieldableError<this> & {
  readonly _tag: "CronParseError";
} & Readonly<{
  readonly input?: string;
  readonly message: string;
}> {
  constructor(args: {
    readonly input?: string;
    readonly message: string;
  });
  readonly [ParseErrorTypeId]: symbol;
}

Other

match

Added in v2.0.0 Source

Checks if a given Date falls within an active Cron time window.

Signature

declare function match(cron: Cron, date: Input): boolean

Example

import * as assert from "node:assert"
import { Cron, Either } from "effect"

const cron = Either.getOrThrow(Cron.parse("0 4 8-14 * *"))
assert.deepStrictEqual(Cron.match(cron, new Date("2021-01-08 04:00:00")), true)
assert.deepStrictEqual(Cron.match(cron, new Date("2021-01-08 05:00:00")), false)

Added in v2.0.0 Source

Returns the next run Date for the given Cron instance.

Uses the current time as a starting point if no value is provided for startFrom.

Signature

declare function next(cron: Cron, startFrom?: Input): Date

Example

import * as assert from "node:assert"
import { Cron, Either } from "effect"

const after = new Date("2021-01-01 00:00:00")
const cron = Either.getOrThrow(Cron.parse("0 4 8-14 * *"))
assert.deepStrictEqual(Cron.next(cron, after), new Date("2021-01-08 04:00:00"))

Added in v3.20.0 Source

Returns the previous run Date for the given Cron instance.

Uses the current time as a starting point if no value is provided for startFrom.

Signature

declare function prev(cron: Cron, startFrom?: Input): Date

Example

import * as assert from "node:assert"
import { Cron, Either } from "effect"

const before = new Date("2021-01-15 00:00:00")
const cron = Either.getOrThrow(Cron.parse("0 4 8-14 * *"))
assert.deepStrictEqual(Cron.prev(cron, before), new Date("2021-01-14 04:00:00"))

sequence

Added in v2.0.0 Source

Returns an IterableIterator which yields the sequence of Dates that match the Cron instance.

Signature

declare function sequence(cron: Cron, startFrom?: Input): IterableIterator<Date>

sequenceReverse

Added in v3.20.0 Source

Returns an IterableIterator which yields the sequence of Dates that match the Cron instance, in reverse direction.

Signature

declare function sequenceReverse(cron: Cron, startFrom?: Input): IterableIterator<Date>

Predicates

equals

Added in v2.0.0 Source

Checks if two Crons are equal.

Signature

declare const equals: {
  (that: Cron): (self: Cron) => boolean;
  (self: Cron, that: Cron): boolean;
}

Symbol

ParseErrorTypeId

Added in v2.0.0 Source

Signature

declare const ParseErrorTypeId: unique symbol

TypeId type

Added in v2.0.0 Source

Signature

type TypeId = typeof TypeId

Symbols

ParseErrorTypeId type

Added in v2.0.0 Source

Signature

type ParseErrorTypeId = typeof ParseErrorTypeId

TypeId

Added in v2.0.0 Source

Signature

declare const TypeId: unique symbol