breejs / later

*Maintained fork of Later.* A javascript library for defining recurring schedules and calculating future (or past) occurrences for them. Includes support for using English phrases and Cron schedules. Works in Node and in the browser.

@breejs/later

This project is a maintained fork of Later, as I needed it to be maintained and modernized for Bree. Later is a library for describing recurring schedules and calculating their future occurrences. It supports a very flexible schedule definition including support for composite schedules and schedule exceptions. Create new schedules manually, via Cron expression, via text expressions, or using a fully chainable API.

Table of Contents

• Features
• Documentation
• Install
• Usage
  • Node
  • Browser
• Contributors
• License

Features

Types of schedules supported by Later:

• Run a report on the last day of every month at 12 AM except in December
• Install patches on the 2nd Tuesday of every month at 4 AM
• Gather CPU metrics every 10 mins Mon - Fri and every 30 mins Sat - Sun
• Send out a scary e-mail at 13:13:13 every Friday the 13th

Documentation

See https://breejs.github.io/later/ for complete documentation and usage.

Install

npm:

npm install @breejs/later

Usage

Node

const later = require('@breejs/later');

console.log(later);

Browser

VanillaJS

This is the solution for you if you're just using <script> tags everywhere!

<script src="https://unpkg.com/@breejs/later"></script>
<script type="text/javascript">
  (function() {
    console.log(later);
  })();
</script>

Bundler

Assuming you are using browserify, webpack, rollup, or another bundler, you can simply follow Node usage above.

Contributors

Name	Website
BunKat
Nick Baugh	http://niftylettuce.com/
yrambler2001	https://yrambler2001.me/

License

MIT © BunKat

later's Issues

[discussion] Detecting errors or stopping for no reason

Hello,

I have tasks that I configure with later and run every 10 minutes.

Some of these tasks stop working without error.

How can I detect this error or task stop. Because it does not give any error output.

Thank you

Checklist

• [x ] I have read the documentation.

[fix] later.schedule().isValid returns true even when the passed schedule is not.

Describe the bug

• Later version: 4.1.0
• Node.js version: v16.13.2
• OS & version: Arch Linux updated yesterday

When later.parse.text has errors, passing its result to later.schedule gives valid schedule

Actual behavior

If I give an invalid text string to later.parse.text, say, at 20h, the result has errors but when passed to later.schedule, it generates something that is correct, but never runs. It breaks Bree, which runs (in src/job-utils.js):

    const schedule = later.schedule(later.parse.text(value));
    if (schedule.isValid()) return later.parse.text(value);

Expected behavior

I expect isValid to return false when the schedule is not valid.

Code to reproduce

> later.parse.text('at 20h').error
3
> later.schedule(later.parse.text('at 20h')).isValid()
true

Checklist

• I have read the documentation.
• I have tried my code with the latest version of Node.js and @breejs/later.

[fix] `next` seems to produce erroneous results esp around the full hour

Describe the bug

• Node.js version: 16.5.0
• OS & version: MacOS Mojave

Actual behavior

When using next on a cron expression (eg */13 * * * * -> every 13 minutes), it seems to generate occurrences that are shorter than 13 minutes every once in a while.

Eg:

const later = require('@breejs/later')
const cron = '*/13 * * * *'

const sched = later.parse.cron(cron)
const nexts = later.schedule(sched).next(11, new Date(2022,10,10,05,00))
console.log(nexts)

produces:

[
  2022-11-10T05:00:00.000Z,
  2022-11-10T05:13:00.000Z,
  2022-11-10T05:26:00.000Z,
  2022-11-10T05:39:00.000Z,
  2022-11-10T05:52:00.000Z,
  2022-11-10T06:00:00.000Z,
  2022-11-10T06:13:00.000Z,
  2022-11-10T06:26:00.000Z,
  2022-11-10T06:39:00.000Z,
  2022-11-10T06:52:00.000Z,
  2022-11-10T07:00:00.000Z
]

After 5:52:00, it should be 6:05:00 and after 6:52:00 (which technically should not be a possible time in the schedule), it should be 7:05:00.

Expected behavior

It should compute the right time for the interval.

Code to reproduce

const later = require('@breejs/later')
const cron = '*/13 * * * *'

const sched = later.parse.cron(cron)
const nexts = later.schedule(sched).next(11, new Date(2022,10,10,05,00))
console.log(nexts)

Checklist

• I have read the documentation.
• I have tried my code with the latest version of Node.js and @breejs/later.

[discussion] multiple time zone support

This library cannot be effectively used over multiple time zones

Currently, later supports only two possible time zone: localTime and UTC. For most use cases, this is likely enough, but I ran into a case where it is basically mostly useless. This is the situation:

• Web server is running in Europe/Amstedam time zone, so currently UTC+2
• On that same server, crontab is running jobs. Those are listed with crontab -l and passed to the clients
• Clients of the web server are in either Europe/Amsterdam or Europe/Bucharest (one hour ahead of Amsterdam)

I want to run later in the client's browser to expand a full time line of all jobs that will be run in that particular day in Europe/Amsterdam. Now this presents a huge problem. I cannot use localTime, as that varies, depending on the user. I also can't use UTC as that will completely break crontab entries that run on specific week days like this :

30 0 * * 6

This is supposed to run at 00:30 every Saturday. However, 0:30 on Saturday in UTC+2 will be 22:30 on Friday in UTC, so evaluating that crontab entry in a later schedule will not run it at 0:30 UTC+2 on Saturday.

I've been trying to work around this issue. Bottom line is that you cannot evaluate crontab entries in a different time zone and get proper results. So a UTC+2 schedule cannot be evaluated in either UTC or UTC+3 successfully without breaking day-of-week support.

I believe later would benefit from an extension so it supports any time zone through something like later.date.timeZone('Europe/Amsterdam') to make sure the crontab entry gets evaluated in the correct time zone.

Edit: I am aware that expanding the crontab entries on the server would work in this case. However, this crontab has several hundred entries. This would result in many thousands of entries, thus increasing the traffic by quite a bit.

Checklist

• [X ] I have read the documentation.

[feat] on the first Monday of the month

What problem are you trying to solve?

I can't run a job every month on a specific day of the week.

Describe the feature

Be able to run a job every month on a specific day of the week.

Checklist

• I have read the documentation and made sure this feature doesn't already exist.

[discussion] How to get all occurrences between start and end date?

What would you like to discuss?

How to get all the dates of occurrences between a defined start and end date?

Checklist

• [ y] I have read the documentation.

The documentation shows:
later.schedule(schedule).next(count, start, end)

What if I want to find out all possible occurrences between two dates for example:

let sched = later.schedule(later.parse.text("every 2 days on Monday"));
let start = new Date('November 9, 2022 03:24:00');
let end = new Date('December 17, 2022 03:24:00');
let occurrences = sched.next(5, start, end);
console.log(occurrences);

So instead of;
let occurrences = sched.next(5, start, end);
is there a way to get all the occurrences between the two dates without limiting them to 5 dates.

I can do a workaround of a loop to check with end date, but I thought there might be a way already.

Thanks

Can't get UTC output to work

Having read the docs, my understanding is that I can call later.date.UTC() to make the occurrences I create to be in UTC.
UTC should even be the default.

But no matter what I do I just get local time zone...
The code snippet below prints current time as UTC to the left and the occurrences from later to the right. I am basically trying to get later output something without a timezone offset applied.

const later = require('@breejs/later');

const sched = later.parse.text('every 5 minutes');
later.date.UTC();

const s = later.schedule(sched);
const occurrences = s.next(5);

const utcDate = new Date(Date.now());

console.log('-------------------------------------------------------------------------');
for (let i = 0; i < 5; i++) {
    console.log(`${utcDate.toUTCString()} /// ${i + 1} /// ${occurrences[i]}`);
}

results in this:

➜ node index.js
-------------------------------------------------------------------------
Thu, 21 Oct 2021 18:56:00 GMT /// 1 /// Thu Oct 21 2021 21:00:00 GMT+0200 (Central European Summer Time)
Thu, 21 Oct 2021 18:56:00 GMT /// 2 /// Thu Oct 21 2021 21:05:00 GMT+0200 (Central European Summer Time)
Thu, 21 Oct 2021 18:56:00 GMT /// 3 /// Thu Oct 21 2021 21:10:00 GMT+0200 (Central European Summer Time)
Thu, 21 Oct 2021 18:56:00 GMT /// 4 /// Thu Oct 21 2021 21:15:00 GMT+0200 (Central European Summer Time)
Thu, 21 Oct 2021 18:56:00 GMT /// 5 /// Thu Oct 21 2021 21:20:00 GMT+0200 (Central European Summer Time)
➜

[fix] later.setInterval is advancing 3 hours

Describe the bug

• Later version: 4.1.0
• Node.js version: v16.13.1
• OS & version: "Debian GNU/Linux 9 (stretch)" / "Debian GNU/Linux 10 (buster)"

I'm using the following code snippet to schedule a routine that runs daily on the same hour later.parse.recur().every(1).dayOfMonth().on(10).hour().on(33).minute();
through the later.setInterval

Actual behavior

The execution takes place well for 2 days, but in the 3rd execution it is executed 3 hours in advance.

...

Expected behavior

I expect setInterval to run daily at the same time every day

...

Code to reproduce

let routine = later.parse.recur().every(1).dayOfMonth().on(10).hour().on(33).minute();

//JSON.stringify -> {"schedules":[{"D":[1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31],"h":[10],"m":[33]}],"exceptions":[]}

later.setInterval(function() {execRoutine(data)}, routine, timeZone); //timezone = "America/Sao_Paulo"
...

Checklist

• I have read the documentation.
• I have tried my code with the latest version of Node.js and @breejs/later.

[discussion] Compose time intervals with after a specific datetime value

What would you like to discuss?

Hi!

I'd like to compose two, otherwise separately working schedule together.

1st schedule is:
in text format:
'after 10:00am and before 11:00am also after 4:00pm and before 5:00pm'
in JSON format:
{schedules: [ { t_a: [36000], t_b: [39600], }, { t_a: [57600], t_b: [61200], }, ]}

2nd schedule is:
in text format:
'after 6:00pm on the 24 day of August in 2022'
in JSON format:
{schedules: [ { t_a: [64800], D: [24], M: [8], Y: [2022], }, ]}

but when I compose it together, the 2nd part is ignored.

text:
'after 10:00am and before 11:00am also after 4:00pm and before 5:00pm also after 6:00pm on the 24 day of August in 2022'
JSON:
{schedules: [ { t_a: [36000], t_b: [39600], }, { t_a: [57600], t_b: [61200], }, { t_a: [64800], D: [24], M: [8], Y: [2022], }, ]}

What would the correct way to describe a schedule for two recurring intervals but only after a specific time and date?

thanks,
Norbi

Checklist

• [X ] I have read the documentation.

incompatible with "clj-fuzzy"

hi, apparently this module doesn't work after "clj-fuzzy" is loaded, i have no idea why, as that module is minified

this is my test code:

const later = require('@breejs/later')

const parsedSchedule = later.parse.text('at 0:00')
const scheduleObject = later.schedule(parsedSchedule)
let next

next = scheduleObject.next(2)

if (next[0].getTime() === next[1].getTime()) {
console.log('NOT OK')
} else {
console.log('OK')
}

require('clj-fuzzy')

next = scheduleObject.next(2)

if (next[0].getTime() === next[1].getTime()) {
console.log('NOT OK')
} else {
console.log('OK')
}

in the second test both dates returned by "next" are identical, the current time

FOUND IT !!

that module does this (yes that is totaly wrong)
Date.prototype.s = function (a, b) { return b instanceof Date && this.valueOf() === b.valueOf()
and later does

val: function val(d) {
return d.s || (d.s = later.date.getSec.call(d));
},

(line 363)
but, d is a standard javascript date at that time, i understand that this is some kind of optimization ? (are seconds cached this way ?

of course attaching methods to global classes is the problem here, but attaching properties isn't very safe either
sadly that other module isn't being maintained

Best way to run something every N seconds, precisely

Hi!
I am looking to schedule a task with bree every N seconds. N is chosen by the user.
Let's say N=45s. This means the function should be called e.g. at 13:00:00,13:00:45, 13:01:30, 13:02:15, 13:03:00, ...
Of course this becomes more complex for other Ns, such as N=167.

Ideally I could do it like this:

later = require('later')
const textSched = later.parse.text('every 45 sec');
function logTime() {
    console.log(new Date());
}
const timer = later.setInterval(logTime, textSched);

However, this does not actually run every 45 seconds, but it actually triggers every x:00 and x:45.

Is there any way to schedule something like this?

Timezone Support?

TL;DR Would adding timezone support - esp. IANA timezones with DST - without external dependencies - be a worthwhile effort in this library?
If not, would it be possible to add hooks, so that some other library *cough* luxon/moment-tz *cough* could do the timezone+DST specific heavy lifting and later could just make use of the Date objects provided by it

Current State

From what I see of the code, later currently supports UTC or the server's local timezone alone

Use Case

I'm writing a small service which gets reminder/schedule from users who could potentially be in different time zones.
later fits all my requirements (lightweight, human-readable schedule parsing) except for the timezone part.
I'll anyways be using later as timezone support isn't a deal-breaker, but might be easier if atleast some hooks were provided so that it would be possible to "opt-in" for timezone support without having to fork the code.

Considerations

I wouldn't want to support timezones in later itself if its only possible by adding dependencies, because no dependencies is a really good selling point for this library

Start the week on monday?

Hi,

how to set up the "later.parse.recur()" to set Monday as the 1st day of the week?

I would like to specify in my calculation, that the occurence should happen the 1st week of the month and currently the result doesn t match because the default first day is sunday.

Thanks.

setInterval and setTimeout are limited to 24 days delay

In old node version setTimeout was limited to 32bit timeout which translate to 24 days. On a larger numbers it would overflow. To avoid this issue, "Later" had capped the maximum delay to 32bit delay. However, this limit in node was resolved many years ago.
This adjustment in "later" should be removed also.

t = diff < 2147483647 ? setTimeout(fn, diff) : setTimeout(scheduleTimeout, 2147483647);

this if needs to be removed.

[docs] Text Parser has no 2nd argument "hasSeconds" (only for Cron Parser)

In Parsers documentation, we have:
https://breejs.github.io/later/parsers.html#text

later.parse.text(expr, hasSeconds)

Parses the text expression expr and returns a valid schedule that can be used with Later.

but actually parse.text takes only a single argument:

later/src/index.js

Line 1708 in e8d16f3

later.parse.text = function (string) {

The hasSeconds argument only makes sense for parse.cron, which may have an optional seconds component in its expression, which may be difficult to detect automatically, whereas the text parser expects an explicit word for seconds.

TypeScript declarations

@niftylettuce Are you interested in hosting the typescript declarations in this repository or even convert this project to typescript?
There already exist type declarations under @types/later which in case you don't want to copy them to this repository, would need to be published under @types/breejs__later by doing a pull request to DefinitelyTyped. For users it might be easier to ship the declarations directly with this package.

Also I just saw that you combined all the files into a single huge index.js file which IMO makes it harder to read the code. Could you clarify why this change was made?

Thanks for maintaining later! ❤️

No parsing error when passing an invalid cron expression to `cron` function

refs bunkat/later#174

Problem

As pointed out in referenced issue there is no error detection logic in later.parse.cron function. This introduced an inconsistency with how later.parse.text behave when invalid values are passed in. In case of cron method there is no indication of any type of error if completely invalid string is passed in. Contrary for text method there's error property assigned to returned object when the expression is not parsed.

Possible solution

There are multiple ways I can see this issue can be approached:

1. Leave it as is, but be very specific that making sure the cron expression is valid is on the client
2. Validate cron expression internally and return consistent error just like in case of parsing expression through text function

Personally I'm in favor of second approach as that would allow to unify error handling.

[discussion] localTime() with text parser

localTime() has no effects while using later.parse.text()?

Not sure if I am using this properly, but the following code does not seem to generate different results no matter if UTC() or localTime() is used:

later.date.localTime();
//later.date.UTC();
const r = later.parse.text(something);

What am I doing wrong?

Checklist

• [x ] I have read the documentation.

Ability to set first day of the week as Monday

Apologies if this is covered in the documentation and i cant find it but im struggling to set the first day of the week as a monday, because it defaults to Sunday its causing issues in my implementation.

Difference between `@breejs/later` and `sfn-scheduler-parser`?

I don't think breejs quite fits my usecase, but I'd still love to use @breejs/later to turn specifically human phrases into programmatically usable dates. In breejs' readme, it lists sfn-scheduler as an unmaintained alternative, and cites that its parser doesn't accept crons. However, I don't need support for crons, so I was wondering if there was any big selling point to this library over sfn-scheduler-parser relating to text parsing. Thanks!

[discussion] How do I parse a later schedule into CRON?

What would you like to discuss?

I'm wondering how I can convert a later schedule into cron format?
For example:

const everyNthDays = later.parse.recur().every(12).dayOfMonth();
const dayOccurs = later.schedule(everyNthDays).next(5);
console.log({ everyNthDays });

// how to convert to cron??

Checklist

• I have read the documentation.
• I understand that later can parse a cron expression ...
• How do I parse a later schedule to cron?

If it's not possible with laterjs, do you have any recommended libraries that could help?

Thank you

schedule(s).next(1, d) fails if s = { schedules: [{ Y: [2012] }, { Y: [2017] }] } and d = new Date('2013-03-21T00:00:05Z') with TypeError: a.getTime is not a function

schedule(s).next(1, d) fails if
s = { schedules: [{ Y: [2012] }, { Y: [2017] }] }
d = new Date('2013-03-21T00:00:05Z')
with TypeError: a.getTime is not a function

Running twice within a second when second is fixed

I am trying to trigger a job once at a specific moment - 2021-06-14T18:14:00.000Z. But the job is being triggered twice. The code is given below:

const later = require('@breejs/later');

const schedule = {
  schedules: [
    {
      year: [2021],
      month: [6],
      day: [14],
      hour: [18],
      minute: [14],
      second: [0],
    },
  ],
};

later.setInterval(() => {
  console.log(`[${new Date().toISOString()}] Job triggered`);
}, schedule);

Output of the above code:

[2021-06-14T18:14:00.681Z] Job triggered
[2021-06-14T18:14:01.702Z] Job triggered

Why is the job being triggered twice? Also, if I don't specify second then job is triggered every second in 14th minute of the mentioned date and time. Is this the expected behaviour? Could anyone please help?

I don't want to use setTimeout as I want to keep the schedule generic.

Every 5th of September and December

Hi,

When I execute this code:
var scheduler = later.parse.recur().on(12).month()
.and().on(9).month()
.and().on(5).dayOfMonth();

  later.date.localTime();
  var results = later.schedule(scheduler).next(3);

I was thinking to get:

• 5/12/2020
• 5/9/2021
• 5/12/2021

But I receive:

• 5/11/2020
• 1/12/2020
• 5/12/2020

How to get the expected result?
Thanks

npm install for 4.1.0 not working on macOS

Installing via npm i @breejs/later on macOS Monterey, after some time, it completes without error, but I get a node_modules/@breejs/later folder which only has three files - licence, package.json and readme.

If I install with npm i @breejs/[email protected] then I get a dist and lib folder created as well.

Is this something awry with packaging of latest on the npmjs repo, or is this something client-side that I can provide more info to debug? I'm running npm 8.2.0 at the moment.

[fix] Order is significant in composite/complex schedules where only some entries specify a year

Describe the bug

• Node.js version: all versions up to v16.x so far
• OS & version: Windows 10, Ubuntu

Not sure if this is truly a bug, or an expected behavior. In a composite schedule where some entries specify a year, and others do not, using the .next() call with the schedule throws an error depending on the order that the crontabs are presented / processed. If schedules that include a year are presented last, then the result is as expected. If schedules that include a year are presented before any open/generic schedules it throws an error.

Actual behavior

\test-later\node_modules\@breejs\later\lib\index.js:926
      return !b || a.getTime() > b.getTime();
                     ^

TypeError: a.getTime is not a function
    at \test-later\node_modules\←[4m@breejs←[24m\later\lib\index.js:926:22
    at findNext (\test-later\node_modules\←[4m@breejs←[24m\later\lib\index.js:936:26)
    at getInstances (\test-later\node_modules\←[4m@breejs←[24m\later\lib\index.js:745:50)
    at Object.next (\test-later\node_modules\←[4m@breejs←[24m\later\lib\index.js:949:14)
    at Object.<anonymous> (\test-later\bad.js:25:52)
←[90m    at Module._compile (node:internal/modules/cjs/loader:1101:14)←[39m
←[90m    at Object.Module._extensions..js (node:internal/modules/cjs/loader:1153:10)←[39m
←[90m    at Module.load (node:internal/modules/cjs/loader:981:32)←[39m
←[90m    at Function.Module._load (node:internal/modules/cjs/loader:822:12)←[39m
←[90m    at Function.executeUserEntryPoint [as runMain] (node:internal/modules/run_main:81:12)←[39m

Expected behavior

[
  2023-01-01T23:30:00.000Z,
  2024-01-01T23:30:00.000Z,
  2025-01-01T23:30:00.000Z,
  2026-01-01T23:30:00.000Z,
  2027-01-01T23:30:00.000Z
]

Code to reproduce

const later = require('@breejs/later');
later.date.localTime();

let good_composite_schedule = {
  "schedules": [
    { "s": [ 0 ], "m": [ 30 ], "h": [ 18 ], "D": [ 1 ], "M": [ 1 ] },
    { "s": [ 0 ], "m": [ 30 ], "h": [ 17 ], "D": [ 2 ], "M": [ 2 ],"Y": [ 2021 ] }
  ],
  "exceptions": []
};
console.log(later.schedule(good_composite_schedule).next(5));

let bad_composite_schedule = {
  "schedules": [
    { "s": [ 0 ], "m": [ 30 ], "h": [ 17 ], "D": [ 2 ], "M": [ 2 ],"Y": [ 2021 ] },
    { "s": [ 0 ], "m": [ 30 ], "h": [ 18 ], "D": [ 1 ], "M": [ 1 ] }
  ],
  "exceptions": []
};
console.log(later.schedule(bad_composite_schedule).next(5));

Checklist

• [ X ] I have read the documentation.
• [ X ] I have tried my code with the latest version of Node.js and @breejs/later.

Support LW on day component

Support Quartz syntax "LW" as "last weekday of the month"

Example:

0 14 LW * ?

Next 5 executions from today:

09/30/2020 14:00:00
10/30/2020 14:00:00
11/30/2020 14:00:00
12/31/2020 14:00:00
01/29/2021 14:00:00

Reference from quartz-scheduler docs:

The 'L' and 'W' characters can also be combined for the day-of-month expression to yield 'LW', which translates to "last weekday of the month".

Support L-{number} on day component

Support Quartz syntax "L-{number}" as "{number} days before month end"

Example:

0 14 L-3 * ?

Should evaluate 3 days before each month ends

Next 5 executions from today:

09/27/2020 14:00:00
10/28/2020 14:00:00
11/27/2020 14:00:00
12/28/2020 14:00:00
01/28/2021 14:00:00

Reference from quartz-scheduler docs:

You can also specify an offset from the last day of the month, such as "L-3" which would mean the third-to-last day of the calendar month.

[bug] tests aren't 100% working

It seems like there's a timezone offset issue with running the tests versus the original author's timezone (which are hardcoded). There might be other issues too, e.g. with the original codebase. I did notice one major issue which I thought stood out, search for "TODO" in the src/index.js file to see the comment.