feat: support async handling and add CronJob status tracking

[Zamoca42]

Description

This PR improves async handling in the CronJob class and adds status tracking functionality.

• Modified the fireOnTick() method to return a Promise for better async callback handling
• Added an isCallbackRunning flag to track the running state of CronJob instances
• Updated the test suite to use the new async behavior and track the job's running state
• Added waitForCompletion functionality to the job.stop() method
  • waits for running jobs to complete before executing the onComplete callback

During test case writing, I encountered a type error with sinon.
To resolve this, added sinon.restore() to the afterEach block.

Reference: https://stackoverflow.com/questions/73232999/sinon-cant-install-fake-timers-twice-on-the-same-global-object

Related Issue

Closes #713
Closes #556

Motivation and Context

These changes allow the CronJob class to handle asynchronous callbacks more effectively and provide a way to track the running state of jobs.

How Has This Been Tested?

• Updated existing test suite to verify the new async behavior
• Adjusted test timeouts to use the tickAsync method
• Added new test cases to check for proper waiting of running callbacks before stopping

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)

Checklist:

• My code follows the code style of this project.
• My change requires a change to the documentation.
• I have updated the documentation accordingly.
• I have added tests to cover my changes.
• All new and existing tests passed.
• If my change introduces a breaking change, I have added a ! after the type/scope in the title (see the Conventional Commits standard).

[sheerlox]

Thank you so much for your PR. It is overall very good but needs a few adjustments in order to avoid introducing breaking changes in the current behavior.

As explained in my comments, this change should be opt-in by adding an option on the CronJob declaration and in the stop method.

I remain at your disposal for any questions or further discussions on the topic!

[ncb000gt]

🎉 This PR is included in version 3.3.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀

[intcreator]

if new jobs that would start before the previous job is finished are skipped entirely, the job that starts at the first second and is still running at 2 seconds (because it needs to wait 1.5 seconds before finishing) should mean the second job that normally would have started at 2 seconds is skipped, right? so the array should actually just equal [1] right?

[cduff]

Agreed, the array there should just equal [1].

Here's a version of that test that also tracks/asserts the number of callbacks started:

it('should track multiple running jobs correctly', async () => {
	const clock = sinon.useFakeTimers();
	const executionOrder: number[] = [];
	let started = 0;

	const job = new CronJob(
		'* * * * * *',
		async () => {
			started++;
			await new Promise<void>(resolve => {
				setTimeout(() => {
					callback();
					resolve();
				}, 1500);
			});
			const jobNumber = executionOrder.length + 1;
			executionOrder.push(jobNumber);
		},
		null,
		true,
		null,
		null,
		false,
		null,
		false,
		true // waitForCompletion: true
	);

	await clock.tickAsync(3500);

	expect(started).toBe(2);
	expect(executionOrder).toEqual([1]);
	job.stop();
});

Is the issue on this line?

node-cron/src/job.ts

Line 210 in f4e9e02

if (!this.waitForCompletion && this._isCallbackRunning) return;

If the ! is removed all the tests pass.

[intcreator]

I think you're right. I'll double check the tests and push a fix