josk

KO | EN

gitlite — search

#python #ai #typescript #llm #golang #android #machine-learning #deep-learning #windows #security #ios #mcp #openai #open-source

(★ 40)

Node.js setInterval and CRON tasks scheduler and manager for horizontally scaled multi-server applications

josk 최신버젼 다운로드

최종 버전 다운로드 (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# JoSk

[![npm version][badge-npm-v]][npm-url]
[![npm downloads][badge-npm-dm]][npm-url]
[![CI][badge-ci]][ci-url]
[![minified size][badge-size]][size-url]
[![Coverage][badge-cov]](https://raw.githubusercontent.com/veliovgroup/josk/master/)
[![License: BSD-3-Clause][badge-license]][license-url]
[![Node.js][badge-node]][node-url]
[![TypeScript][badge-ts]][ts-url]
[![Bun][badge-bun]][bun-url]
[![Meteor.js][badge-meteor]][meteor-url]
[![zero dependencies][badge-deps]][npm-url]
[![Sponsor][badge-sponsor]][sponsor-url]
[![Donate][badge-donate]][donate-url]
<a href="https://bridge-cdn.com/?ref=github-josk-repo-top"><img src="https://bridge-cdn.com/favicon.svg" height="20"></a>
<a href="https://ostr.io/info/built-by-developers-for-developers?ref=github-josk-repo-top"><img src="https://ostr.io/apple-touch-icon-60x60.png" height="20"></a>
<a href="https://meteor-files.com/?ref=github-josk-repo-top"><img src="https://meteor-files.com/apple-touch-icon-60x60.png" height="20"></a>

"JoSk" is a Node.js task manager for horizontally scaled apps and apps that would need to scale horizontally quickly at some point of growth.

"JoSk" mimics the native API of `setTimeout` and `setInterval` and supports [CRON expressions](https://github.com/veliovgroup/josk?tab=readme-ov-file#cron). All queued tasks are synced between all running application instances via Redis, MongoDB, or a [custom adapter](https://github.com/veliovgroup/josk/blob/master/docs/adapter-api.md).

The "JoSk" package is made for a variety of horizontally scaled apps, such as clusters, multi-servers, and multi-threaded Node.js instances, that are running either on the same or different machines or even different data centers. "JoSk" uses storage-level leases and atomic task claims so each due tick is claimed by one instance; delivery guarantees depend on the scheduling method.

"JoSk" is not just for multi-instance apps. It seamlessly integrates with single-instance applications as well, showcasing its versatility and adaptability.

__Note: JoSk is the server-only package.__

## ToC

- [Main features](https://github.com/veliovgroup/josk?tab=readme-ov-file#main-features)
- [Prerequisites](https://github.com/veliovgroup/josk?tab=readme-ov-file#prerequisites)
- [Install](https://github.com/veliovgroup/josk?tab=readme-ov-file#install) as [NPM package](https://www.npmjs.com/package/josk)
  - [Bun runtime](https://github.com/veliovgroup/josk?tab=readme-ov-file#bun-runtime)
  - [Agent Skill (Claude Code, Codex, Cursor, Copilot, Windsurf, …)](https://github.com/veliovgroup/josk?tab=readme-ov-file#agent-skill)
- [API](https://github.com/veliovgroup/josk?tab=readme-ov-file#api)
  - [Constructor `new JoSk()`](https://github.com/veliovgroup/josk?tab=readme-ov-file#new-joskopts)
    - [`RedisAdapter`](https://github.com/veliovgroup/josk?tab=readme-ov-file#redis-adapter)
    - [`MongoAdapter`](https://github.com/veliovgroup/josk?tab=readme-ov-file#mongodb-adapter)
    - [`PostgresAdapter`](#postgresql-adapter)
  - [`JoSk#setInterval()`](https://github.com/veliovgroup/josk?tab=readme-ov-file#setintervalfunc-delay-uid)
  - [`JoSk#setTimeout()`](https://github.com/veliovgroup/josk?tab=readme-ov-file#settimeoutfunc-delay-uid)
  - [`JoSk#setImmediate()`](https://github.com/veliovgroup/josk?tab=readme-ov-file#setimmediatefunc-uid)
  - [`JoSk#clearInterval()`](https://github.com/veliovgroup/josk?tab=readme-ov-file#clearintervaltimer)
  - [`JoSk#clearTimeout()`](https://github.com/veliovgroup/josk?tab=readme-ov-file#cleartimeouttimer)
  - [`JoSk#destroy()`](https://github.com/veliovgroup/josk?tab=readme-ov-file#destroy)
  - [`JoSk#ping()`](https://github.com/veliovgroup/josk?tab=readme-ov-file#ping)
  - [`JoSk#pause()`](https://github.com/veliovgroup/josk?tab=readme-ov-file#pause)
  - [`JoSk#resume()`](https://github.com/veliovgroup/josk?tab=readme-ov-file#resume)
- [Execution semantics](https://github.com/veliovgroup/josk?tab=readme-ov-file#execution-semantics)
- [TypeScript](https://github.com/veliovgroup/josk?tab=readme-ov-file#typescript)
- [Examples](https://github.com/veliovgroup/josk?tab=readme-ov-file#examples)
  - [CRON usage](https://github.com/veliovgroup/josk?tab=readme-ov-file#cron)
  - [Passing arguments](https://github.com/veliovgroup/josk?tab=readme-ov-file#pass-arguments)
  - [Clean up old tasks](https://github.com/veliovgroup/josk?tab=readme-ov-file#clean-up-old-tasks)
  - [MongoDB connection options](https://github.com/veliovgroup/josk?tab=readme-ov-file#mongodb-connection-fine-tuning)
  - [Meteor.js](https://github.com/veliovgroup/josk/blob/master/docs/meteor.md)
- [Prefix mapping per adapter](https://github.com/veliovgroup/josk?tab=readme-ov-file#prefix-mapping)
- [Operational FAQ](https://github.com/veliovgroup/josk?tab=readme-ov-file#operational-faq)
- [Migration guide (v4 → v5)](docs/migration-v4-v5.md)
- [Migration guide (v5 → v6)](docs/migration-v5-v6.md)
- [Migration guide (v6 → v6.1)](docs/migration-v6-v6.1.md)
- [Migration guides](https://github.com/veliovgroup/josk/blob/master/docs/README.md#migration-guides)
- [Important notes](https://github.com/veliovgroup/josk?tab=readme-ov-file#notes)
- [~99% tests coverage](https://github.com/veliovgroup/josk?tab=readme-ov-file#running-tests)
- [Why it's named "JoSk"](https://github.com/veliovgroup/josk?tab=readme-ov-file#why-josk)
- [Support Section](https://github.com/veliovgroup/josk?tab=readme-ov-file#support-our-open-source-contribution)

## Main features

- 🏢 Synchronize single task across multiple servers;
- 🔏 Read locking to avoid simultaneous task executions across complex infrastructure;
- 📦 Zero dependencies, written from scratch for top performance;
- 👨‍🔬 ~99% tests coverage;
- 💪 Bulletproof design, built-in retries, and "zombie" task recovery 🧟🔫.

## Prerequisites

- `redis-server@>=5.0.0` or KeyDB — for RedisAdapter (requires `redis` NPM package, both `redis@^4` and `redis@^5` are supported). KeyDB and Valkey are supported with the same single-writer topology.
- `mongod@>=4.4` — for MongoAdapter (requires the official `mongodb` NPM package; tested against the official driver only)
- `postgres@>=12` — for PostgresAdapter (requires `pg@>=8.0.3` NPM package; `pg@7` does not connect on Node 14+)
- `node@>=20.9.0` — Node.js version
- `bun@>=1.1.0` — optional, runs the same package and the same Jest suite under [Bun](https://bun.sh) via `bun:test` (see [Bun runtime](#bun-runtime) section)

### Older releases compatibility

- `node@<20.9.0` — use `josk@^5`
- `mongod@<4.0.0` — use `josk@=1.1.0`
- `node@<14.20.0` — use `josk@=3.0.2`
- `node@<8.9.0` — use `josk@=1.1.0`

## Install:

```shell
npm install josk --save
```

```js
// ES Module Style
import { JoSk, RedisAdapter, MongoAdapter, PostgresAdapter } from 'josk';

// CommonJS
const { JoSk, RedisAdapter, MongoAdapter, PostgresAdapter } = require('josk');
```

### Bun runtime

*Since* `v6.0.0`

JoSk runs unmodified on [Bun](https://bun.sh) `>=1.1.0`. The package is pure ESM, has no Node-only globals beyond `node:crypto.randomUUID()` (which Bun ships natively), and the official `mongodb`, `pg`, and `redis` drivers all work under Bun. Install with `bun add josk` and import the same way:

```js
import { JoSk, RedisAdapter, MongoAdapter, PostgresAdapter } from 'josk';
```

The full Jest test suite (`test/jest/`) doubles as the Bun test suite — `npm run test:bun` runs every core and adapter test under Bun's `bun:test` runner. See [Running Tests](#running-tests).

Notes:

- Use the same adapter packages as on Node (`mongodb`, `pg`, `redis`).
- Schedulers running across mixed Node and Bun processes coexist under the same prefix; lease acquisition and task claiming are storage-level operations and runtime-agnostic.
- Bun's standalone executables (`bun build --compile`) bundle JoSk like any ESM library.

### Agent Skill

JoSk ships a Claude / Copilot / Cursor / Codex / Gemini-ready skill bundle. Install it once in your project (or globally) and your AI agent will reach for the right preset, adapter, and pitfall list without you having to paste docs into the chat.

```sh
# Install the JoSK skill globally:
npx skills add veliovgroup/josk -g

# Or install the JoSK skill into the current project:
npx skills add veliovgroup/josk
```

The `npx skills` CLI ([vercel-labs/skills](https://github.com/vercel-labs/skills)) supports 50+ AI coding agents. Pass `-a claude-code` to target a specific agent. The bundled JoSk skill covers full public API, adapter setup, execution semantics, CRON and handler patterns, and common pitfalls — it's the same material as the README and `docs/`, structured for an LLM.

> [!NOTE]
> The skill source is **not** shipped in the npm tarball — it's distributed via GitHub and consumed only by AI tooling.

## API:

Constructor options for *JoSk*, *RedisAdapter*, *MongoAdapter*, *PostgresAdapter*

### `new JoSk(opts)`

- `opts.adapter` {*RedisAdapter*|*MongoAdapter*|*PostgresAdapter*} - [Required] Instance of adapter or [custom](https://github.com/veliovgroup/josk/blob/master/docs/adapter-api.md)
- `opts.debug` {*Boolean*} - [Optional] Enable debugging messages, useful during development
- `opts.autoClear` {*Boolean*} - [Optional] Remove (*Clear*) obsolete tasks (*any tasks which are not found in the instance memory (runtime), but exists in the database*). Obsolete tasks may appear in cases when it wasn't cleared from the database on process shutdown, and/or was removed/renamed in the app. Obsolete tasks may appear if multiple app instances running different codebase within the same database, and the task may not exist on one of the instances. Default: `false`
- `opts.zombieTime` {*Number*} - [Optional] time in milliseconds, after this time - task will be interpreted as "*zombie*". This parameter allows to rescue task from "*zombie* mode" in case when: `ready()` wasn't called, exception during runtime was thrown, or caused by bad logic. While `resetOnInit` option helps to make sure tasks are `done` on startup, `zombieTime` option helps to solve same issue, but during runtime. Default value is `900000` (*15 minutes*). It's not recommended to set this value to below `60000` (*one minute*)
- `opts.lockLeaseTime` {*Number*} - [Optional] Scheduler lease TTL in milliseconds. Default: `min(zombieTime, 30000)`, floored at `2 * maxRevolvingDelay + 1000`. See [v6.3 migration notes](https://github.com/veliovgroup/josk/blob/master/docs/migration-v6.2-v6.3.md)
- `opts.execute` {*String*} - [Optional] due-task execution mode. Use `one` to claim and run one task per scheduler lease, or `batch` to drain all currently due tasks under same lease. Default: `batch`
- `opts.concurrency` {*Number*} - [Optional] maximum number of task handlers that can run in parallel. Use a positive integer to cap parallelism (useful when handlers share rate-limited resources like the same DB the adapter uses); use `Infinity` to disable throttling. Default: `Infinity`
- `opts.lockOwnerId` {*String*} - [Optional] stable owner id for scheduler lease tokens. Useful for observability (lease IDs include this prefix) and for re-claiming this instance's leases after a planned restart. Default: auto-generated per `JoSk` instance via `crypto.randomUUID()`
- `opts.minRevolvingDelay` {*Number*} - [Optional] Minimum revolving delay — the minimum delay between tasks executions in milliseconds. Default: `128`
- `opts.maxRevolvingDelay` {*Number*} - [Optional] Maximum revolving delay — the maximum delay between tasks executions in milliseconds. Default: `768`
- `opts.onError` {*Function*} - [Optional] Informational hook, called instead of throwing exceptions. Default: `false`. Called with two arguments:
  - `title` {*String*}
  - `details` {*Object*}
  - `details.description` {*String*}
  - `details.error` {*Mix*}
  - `details.uid` {*String*} - Internal `uid`, suitable for `.clearInterval()` and `.clearTimeout()`
  - `details.task` {*Mix*} - Present only for malformed-task errors; the offending task payload
- `opts.onExecuted` {*Function*} - [Optional] Informational hook, called when task is finished. Default: `false`. Called with two arguments:
  - `uid` {*String*} - `uid` passed into `.setImmediate()`, `.setTimeout()`, or `setInterval()` methods
  - `details` {*Object*}
  - `details.uid` {*String*} - Internal `uid`, suitable for `.clearInterval()` and `.clearTimeout()`
  - `details.date` {*Date*} - Execution timestamp as JS {*Date*}
  - `details.delay` {*Number*} - Execution `delay` (e.g. `interval` for `.setInterval()`)
  - `details.timestamp` {*Number*} - Execution timestamp as unix {*Number*}

Hook throws and async rejections are logged and isolated from scheduler execution.

### `new RedisAdapter(opts)`

*Since* `v5.0.0`

- `opts.client` {*RedisClient*} - [*Required*] `RedisClient` instance, like one returned from `await redis.createClient().connect()` method
- `opts.prefix` {*String*} - [Optional] use to create multiple named instances
- `opts.resetOnInit` {*Boolean*} - [Optional] (*__use with caution__*) make sure all old tasks are completed during initialization. Useful for single-instance apps to clean up unfinished that occurred due to intermediate shutdown, reboot, or exception. Default: `false`
- `opts.useHashTags` {*Boolean*} - [Optional] use Redis Cluster hash-tag keys (`josk:{prefix}:*`) so all adapter keys live in same slot. Default: `false`, preserving existing standalone keys (`josk:prefix:*`)

### `new MongoAdapter(opts)`

*Since* `v5.0.0`

- `opts.db` {*Db*} - [*Required*] Mongo's `Db` instance, like one returned from `MongoClient#db()` method
- `opts.prefix` {*String*} - [Optional] use to create multiple named instances
- `opts.lockCollectionName` {*String*} - [Optional] By default all JoSk instances use the same `__JobTasks__.lock` collection for locking
- `opts.resetOnInit` {*Boolean*} - [Optional] (*__use with caution__*) make sure all old tasks are completed during initialization. Useful for single-instance apps to clean up unfinished that occurred due to intermediate shutdown, reboot, or exception. Default: `false`

### `new PostgresAdapter(opts)`

*Since* `v6.0.0`

- `opts.client` {*Pool*|*Client*} - [*Required*] `pg` client with `.query()` method. `Pool` is recommended for long-running applications
- `opts.prefix` {*String*} - [Optional] use to create multiple isolated scheduler namespaces in same database. Default: `default`
- `opts.resetOnInit` {*Boolean*} - [Optional] (*__use with caution__*) deletes tasks and locks for current `prefix` during initialization. Useful for local development and single-instance startup recovery. Default: `false`

### Initialization

JoSk is storage-agnostic (since `v4.0.0`). Shipped with Redis, MongoDB, and PostgreSQL adapters. Extend via [custom adapter](docs/adapter-api.md)

#### Redis Adapter

JoSk has no dependencies, hence make sure `redis` NPM package is installed in order to support Redis Storage Adapter. `RedisAdapter` stores due timestamps in sorted set and task payloads in hash, then claims due work atomically via Lua scripts. `RedisAdapter` is compatible with Redis-like databases with Lua + sorted-set support, and was well-tested with [Redis](https://redis.io/) and [KeyDB](https://docs.keydb.dev/)

KeyDB guidelines:

- Use a single writable KeyDB primary. For Redis Cluster or KeyDB Cluster, pass `useHashTags: true` so adapter keys use one hash slot: `josk:{prefix}:schedule`, `josk:{prefix}:tasks`, `josk:{prefix}:lock`.
- Do not route JoSk reads or writes to replicas. Scheduler correctness depends on immediate visibility of lock and task-claim writes.
- Avoid KeyDB active-replication/multi-master mode for scheduler correctness. Conflict resolution and eventual convergence can allow duplicate task claims across writers.
- For multi-DC strict single-claim scheduling, use a strongly consistent storage topology, or prefer PostgreSQL with one write authority.

```js
import { JoSk, RedisAdapter } from 'josk';
import { createClient } from 'redis';

const redisClient = await createClient({
  url: 'redis://127.0.0.1:6379'
}).connect();

const jobs = new JoSk({
  adapter: new RedisAdapter({
    client: redisClient,
    prefix: 'app-scheduler',
    // useHashTags: true, // Enable for Redis Cluster / KeyDB Cluster
  }),
  onError(reason, details) {
    // Use onError hook to catch runtime exceptions
    // thrown inside scheduled tasks
    console.log(reason, details.error);
  }
});
```

#### MongoDB Adapter

JoSk has no dependencies, hence make sure `mongodb` NPM package is installed in order to support MongoDB Storage Adapter. Note: this package will add two new MongoDB collections per each `new JoSk()`. One collection for tasks and second for "Read Locking" with `.lock` suffix

```js
import { JoSk, MongoAdapter } from 'josk';
import { MongoClient } from 'mongodb';

#### PostgreSQL Adapter

*Since* `v6.0.0`

JoSk has no dependencies, hence make sure `pg` NPM package (`npm i pg`) is installed. PostgreSQL `>=12` is recommended. Adapter auto-creates and migrates `josk_tasks` and `josk_locks` tables on init, using current database/schema from the provided client.

```js
import { JoSk, PostgresAdapter } from 'josk';
import { Pool } from 'pg';

const pool = new Pool({
  connectionString: 'postgres://user:pass@localhost:5432/joskdb'
});

const jobs = new JoSk({
  adapter: new PostgresAdapter({
    client: pool,
    prefix: 'cluster-scheduler',
  }),
  onError(reason, details) {
    // Use onError hook to catch runtime exceptions
    // thrown inside scheduled tasks
    console.log(reason, details.error);
  }
});
```

PostgreSQL guidelines:

- Use `pg.Pool` for application runtime. Share same pool when scheduler tasks also use PostgreSQL, or use a small dedicated pool when you want scheduler isolation.
- Use one writable primary endpoint. Do not route JoSk reads or writes to read replicas; task claims must be immediately visible across app instances.
- Use same `prefix` on instances that must share one schedule. Use different `prefix` values for isolated tenants, environments, or test suites.
- Prefer a dedicated database or schema when possible. Adapter creates `josk_tasks` and `josk_locks`; table names are fixed, isolation is by `prefix`.
- Keep `resetOnInit: false` in clustered production. `true` deletes current-prefix tasks and lock rows during adapter initialization.
- `execute: 'batch'` is default. It claims due tasks in batches using `FOR UPDATE SKIP LOCKED`, then iterates returned task list in memory. Best for draining backlogs with fewer DB round-trips.
- `execute: 'one'` claims one due task per scheduler lease with `LIMIT 1`. Useful when you want smaller execution bursts or tighter fairness between instances.
- Tune `minRevolvingDelay` and `maxRevolvingDelay` with pool capacity and task runtime. Lower delays poll more often and increase database writes.

#### Create the first task

After JoSk initialized simply call `JoSk#setInterval` to create recurring task

```js
const jobs = new JoSk({ /*...*/ });

jobs.setInterval((ready) => {
  /* ...code here... */
  ready();
}, 60 * 60000, 'task1h'); // every hour

jobs.setInterval((ready) => {
  /* ...code here... */
  asyncCall(() => {
    /* ...more code here...*/
    ready();
  });
}, 15 * 60000, 'asyncTask15m'); // every 15 mins

/**
 * no need to call ready() inside async function
 */
jobs.setInterval(async () => {
  try {
    await asyncMethod();
  } catch (err) {
    console.log(err)
  }
}, 30 * 60000, 'asyncAwaitTask30m'); // every 30 mins

/**
 * no need to call ready() when call returns Promise
 */
jobs.setInterval(() => {
  return asyncMethod(); // <-- returns Promise
}, 2 * 60 * 60000, 'asyncAwaitTask2h'); // every two hours
```

Note: This library relies on job ID. Always use different `uid`, even for the same task:

```js
const task = function (ready) {
  //... code here
  ready();
};

jobs.setInterval(task, 60000, 'task-1m'); // every minute
jobs.setInterval(task, 2 * 60000, 'task-2m'); // every two minutes
```

### `setInterval(func, delay, uid)`

- `func` {*Function*} - Function to call on schedule
- `delay` {*Number*} - Delay for the first run and interval between further executions in milliseconds
- `uid` {*String*} - Unique app-wide task id
- Returns: {*`Promise<string>`*}

*Set task into interval execution loop.* `ready()` *callback is passed as the first argument into a task function.*

In the example below, the next task __will not be scheduled__ until the current is ready:

```js
jobs.setInterval(function (ready) {
  /* ...run sync code... */
  ready();
}, 60 * 60000, 'syncTask1h'); // will execute every hour + time to execute the task

jobs.setInterval(async function () {
  try {
    await asyncMethod();
  } catch (err) {
    console.log(err)
  }
}, 60 * 60000, 'asyncAwaitTask1h'); // will execute every hour + time to execute the task
```

In the example below, the next task __will not wait__ for the current task to finish:

```js
jobs.setInterval(function (ready) {
  ready();
  /* ...run sync code... */
}, 60 * 60000, 'syncTask1h'); // will execute every hour

jobs.setInterval(async function () {
  /* ...task re-scheduled instantly here... */
  process.nextTick(async () => {
    await asyncMethod();
  });
}, 60 * 60000, 'asyncAwaitTask1h'); // will execute every hour
```

In the next example, a long running task is executed in a loop without delay after the full execution:

```js
jobs.setInterval(function (ready) {
  asyncCall((error, result) => {
    if (error) {
      ready(); // <-- Always run `ready()`, even if call was unsuccessful
    } else {
      anotherCall(result.data, ['param'], (error, response) => {
        if (error) {
          ready(); // <-- Always run `ready()`, even if call was unsuccessful
          return;
        }

waitForSomethingElse(response, () => {
          ready(); // <-- End of the full execution
        });
      });
    }
  });
}, 0, 'longRunningAsyncTask'); // run in a loop as soon as previous run is finished
```

Same task combining `await`/`async` and callbacks

```js
jobs.setInterval(function (ready) {
  process.nextTick(async () => {
    try {
      const result = await asyncCall();
      const response = await anotherCall(result.data, ['param']);

waitForSomethingElse(response, () => {
        ready(); // <-- End of the full execution
      });
    } catch (err) {
      console.log(err)
      ready(); // <-- Always run `ready()`, even if call was unsuccessful
    }
  });
}, 0, 'longRunningAsyncTask'); // run in a loop as soon as previous run is finished
```

#### `ready()` — argument forms

`ready` is the function passed as the first argument to every task handler. It is a `Promise<boolean>`-returning function and accepts several optional argument shapes:

- `ready()` — schedule the next interval run at `now + delay` (default).
- `ready(date)` — `Date` instance; schedule the next interval run at that exact wall-clock moment. Only honored for `setInterval`; `setTimeout`/`setImmediate` are at-most-once and have already been removed before the handler ran. This is the building block for CRON expressions — pair with [`cron-parser`](https://www.npmjs.com/package/cron-parser).
- `ready(timestamp)` — numeric ms-epoch; same as above.
- `ready(callback)` — Node-style callback `(error, success) => void`. Useful for non-async handlers that prefer not to use the returned `Promise`.

Calling `ready()` twice throws (or invokes the callback with `error`) — *"Resolution method is overspecified"*. Either return a `Promise` from the handler **or** call `ready()` once, never both.

For zero-arity handlers (`async function () { … }` or `() => doSomething()`), JoSk auto-calls `ready()` for you when the returned Promise settles. You only need to call `ready()` manually when the handler accepts it as an argument.

```js
import { CronExpressionParser } from 'cron-parser';

const intervalCron = (job, cronExpr, uid) => {
  const next = () => CronExpressionParser.parse(cronExpr).next().toDate();
  return jobs.setInterval(function (ready) {
    job();
    ready(next()); // schedule the next run at the cron's next fire time
  }, Math.max(0, +next() - Date.now()), uid);
};

intervalCron(() => sendReport(), '0 9 * * *', 'daily-report-9am');
```

### `setTimeout(func, delay, uid)`

- `func` {*Function*} - Function to call after `delay`
- `delay` {*Number*} - Delay in milliseconds
- `uid` {*String*} - Unique app-wide task id
- Returns: {*`Promise<string>`*}

*Run a task after delay in ms.* `setTimeout` *is useful for cluster work where duplicate execution is worse than a missed run.* `ready()` *callback is passed as the first argument into a task function.*

```js
jobs.setTimeout(function (ready) {
  /* ...run sync code... */
  ready();
}, 60000, 'syncTaskIn1m'); // will run at most once across the cluster in a minute

jobs.setTimeout(function (ready) {
  asyncCall(function () {
    /* ...run async code... */
    ready();
  });
}, 60000, 'asyncTaskIn1m'); // will run at most once across the cluster in a minute

jobs.setTimeout(async function () {
  try {
    /* ...code here... */
    await asyncMethod();
    /* ...more code here...*/
  } catch (err) {
    console.log(err)
  }
}, 60000, 'asyncAwaitTaskIn1m'); // will run at most once across the cluster in a minute
```

### `setImmediate(func, uid)`

- `func` {*Function*} - Function to execute
- `uid`  {*String*}   - Unique app-wide task id
- Returns: {*`Promise<string>`*}

*Run a one-shot task as soon as the next scheduler tick claims it.* `setImmediate` *is useful for cluster work where duplicate execution is worse than a missed run.* `ready()` *is passed as the first argument into the task function.*

```js
jobs.setImmediate(function (ready) {
  //...run sync code
  ready();
}, 'syncTask'); // will run at most once across the cluster

jobs.setImmediate(function (ready) {
  asyncCall(function () {
    //...run more async code
    ready();
  });
}, 'asyncTask'); // will run at most once across the cluster

jobs.setImmediate(async function () {
  try {
    /* ...code here... */
    await asyncMethod();
  } catch (err) {
    console.log(err)
  }
}, 'asyncTask'); // will run at most once across the cluster
```

### `clearInterval(timerId)`

- `timerId` {*String*|*`Promise<string>`*} — Timer id returned from `JoSk#setInterval()` method
- Returns: {`Promise<boolean>`} `true` when task is successfully cleared, or `false` when task was not found

*Cancel current interval timer.*

```js
const timer = await jobs.setInterval(func, 34789, 'unique-taskid');
await jobs.clearInterval(timer);
```

### `clearTimeout(timerId)`

- `timerId` {*String*|*`Promise<string>`*} — Timer id returned from `JoSk#setTimeout()` method
- Returns: {`Promise<boolean>`} `true` when task is successfully cleared, or `false` when task was not found

*Cancel current timeout timer.*

```js
const timer = await jobs.setTimeout(func, 34789, 'unique-taskid');
await jobs.clearTimeout(timer);
```

### `destroy()`

- Returns: {*boolean*} `true` if instance successfully destroyed, `false` if instance already destroyed

*Destroy JoSk instance*. This method shouldn't be called in normal circumstances. Stop internal interval timer. After JoSk is destroyed — calling public methods would end up logged to `stdout` or if `onError` hook was passed to JoSk it would receive an error. Only permitted methods are `clearTimeout` and `clearInterval`.

```js
// EXAMPLE: DESTROY JoSk INSTANCE UPON SERVER PROCESS TERMINATION
const jobs = new JoSk({ /* ... */ });

const cleanUpBeforeTermination = function () {
  /* ...CLEAN UP AND STOP OTHER THINGS HERE... */
  jobs.destroy();
  process.exit(1);
};

process.stdin.resume();
process.on('uncaughtException', cleanUpBeforeTermination);
process.on('exit', cleanUpBeforeTermination);
process.on('SIGHUP', cleanUpBeforeTermination);
```

### `ping()`

- Returns: {*`Promise<object>`*}

*Ping JoSk instance*. Check scheduler readiness and its connection to the "storage adapter"

```js
const jobs = new JoSk({ /* ... */ });

const pingResult = await jobs.ping();
console.log(pingResult)
/**
In case of the successful response
{
  status: 'OK',
  code: 200,
  statusCode: 200,
}

Failed response
{
  status: 'Error reason',
  code: 500,
  statusCode: 500,
  error: ErrorObject
}
*/
```

### `pause()`

- Signature: `pause()` or `pause(timerId)`
- Returns: {*boolean*} `true` if pause state changed, `false` if already paused for that scope
- **When to use:** Multi-instance setups only — other JoSk peers must exist to run work while this process is paused. For long-running tasks that should not keep the JoSk handler (and revolving loop) blocked until finished; skip on single-instance apps and short handlers.
- **Global** `pause()` — this instance stops acquiring the scheduler lease on revolving ticks. Handlers already running continue. Tasks stay registered in storage; other cluster members keep competing.
- **Per-task** `pause(timerId)` — when this instance claims that task, it reschedules without invoking the handler so another instance can run it. Pass only the timer id string returned from `setInterval`, `setTimeout`, or `setImmediate` (not the bare `uid` argument you passed to `set*`).

```js
if (loadSheddingActive()) {
  jobs.pause(); // stop competing while saturated
}
const heavy = await jobs.setInterval(worker, 60_000, 'heavy-sync');
jobs.pause(heavy); // only skip this task on this pod
```

### `resume()`

- Signature: `resume()` or `resume(timerId)`
- Returns: {*boolean*} `true` if pause cleared, `false` if not paused
- `resume()` clears global pause. `resume(timerId)` clears per-task pause (same timer id from `set*`). Competing resumes on the next revolving tick (no separate `start()`).

```js
jobs.resume();        // global
jobs.resume(heavy);   // per timer id from set*
```

**Inside `set*` handlers (queue polling):** After this instance wins a tick, claim rows from your own queue, then `pause()` or `pause(timerId)`, call `ready()` (or return only after `ready()` if work is branched off), run heavy processing on this instance, and `resume()` / `resume(timerId)` in `finally` when done — so JoSk releases the tick quickly and this instance stops competing until local work finishes. See [skills/josk/references/patterns.md](skills/josk/references/patterns.md) for full examples (global and per-`timerId`).

## Execution semantics

Different scheduling methods have different at-least-once / at-most-once guarantees. Pick the one that matches your tolerance for missed or duplicated runs.

| Method | Guarantee | Notes |
|---|---|---|
| `setImmediate(func, uid)` | **At-most-once** across the cluster | Task is removed from storage *before* the handler runs. If the process dies between removal and completion, the run is lost. |
| `setTimeout(func, delay, uid)` | **At-most-once** across the cluster | Task is removed from storage *before* the handler runs. If the process dies between removal and completion, the run is lost. |
| `setInterval(func, delay, uid)` | **At-least-once** per scheduled tick (until cleared) | Storage row stays during execution. If `ready()` is not called within `zombieTime`, the task is re-claimed and may run again. Make your handler idempotent. |

`zombieTime` is the safety net for stuck handlers. Choose it long enough to cover your slowest legitimate handler, plus storage round-trip overhead. Default `900000` ms (15 minutes).

`execute` controls how the scheduler drains the work queue under a single lease:

- `batch` (default) claims due tasks in batches under one lease — best throughput.
- `one` claims a single due task per lease — smaller bursts, tighter fairness across instances.

`concurrency` caps how many handlers run in parallel inside this JoSk instance. Default is unbounded (`Infinity`), which matches `setInterval`/`setTimeout` semantics from Node's standard library. Set a finite cap if handlers share resources (DB connections, external API rate limits).

**Instance backpressure:** `pause()` / `pause(timerId)` are per-process, not cluster-wide — useful only when **several instances** share the scheduler and this one should yield during **long** local work. Pair with `concurrency` (caps parallel handlers) and `execute: 'one'` (smaller claim bursts).

## TypeScript

JoSk ships with TypeScript declarations for both ESM (`index.d.ts`) and CommonJS (`index.d.cts`). The `JoSkAdapter` interface is exported so custom adapters can be type-checked against the public contract.

```ts
import { JoSk, RedisAdapter } from 'josk';
import type { JoSkAdapter, JoSkOption, JoSkOnError } from 'josk';
import { createClient } from 'redis';

const onError: JoSkOnError = async (title, details) => {
  console.error(title, details.error, details.uid);
};

const adapter: JoSkAdapter = new RedisAdapter({
  client: await createClient({ url: process.env.REDIS_URL }).connect(),
  prefix: 'cluster-scheduler'
});

const options: JoSkOption = { adapter, execute: 'batch', concurrency: 16, onError };
const jobs = new JoSk(options);
```

## Examples

Use cases and usage examples

### CRON

Use JoSk to invoke synchronized tasks by CRON schedule, and the [`cron-parser` package](https://www.npmjs.com/package/cron-parser) to parse CRON expressions. The example below uses `cron-parser@^5` (v5 renamed the entrypoint to the `CronExpressionParser.parse()` static method).

```js
import { CronExpressionParser } from 'cron-parser';

const jobsCron = new JoSk({
  adapter: new RedisAdapter({
    client: await createClient({ url: 'redis://127.0.0.1:6379' }).connect(),
    prefix: 'cron-scheduler'
  }),
  minRevolvingDelay: 512, // Adjust revolving delays to higher values
  maxRevolvingDelay: 1000, // as CRON schedule defined to seconds
});

// CRON HELPER FUNCTION
const setCron = async (uniqueName, cronTask, task) => {
  const next = CronExpressionParser.parse(cronTask).next().toDate();
  // Guard against clock skew: parsed "next" can land in the recent past.
  const initialDelay = Math.max(0, +next - Date.now());

return await jobsCron.setInterval(function (ready) {
    const upcoming = CronExpressionParser.parse(cronTask).next().toDate();
    ready(upcoming);
    task();
  }, initialDelay, uniqueName);
};

setCron('Run every two seconds cron', '*/2 * * * * *', function () {
  console.log(new Date());
});
```

### Pass arguments

Passing arguments can be done via wrapper function

```js
const jobs = new JoSk({ /* ... */ });
const myVar = { key: 'value' };
let myLet = 'Some top level or env.variable (can get changed during runtime)';

const task = function (arg1, arg2, ready) {
  //... code here
  ready();
};

jobs.setInterval((ready) => {
  task(myVar, myLet, ready);
}, 60 * 60000, 'taskA');

jobs.setInterval((ready) => {
  task({ otherKey: 'Another Value' }, 'Some other string', ready);
}, 60 * 60000, 'taskB');
```

### Async/Await with ready() callback

For long-running async tasks, or with callback-apis it might be needed to call `ready()` explicitly. Wrap task's body into `process.nextTick` to enjoy `await`/`async` combined with classic callback-apis

```js
jobs.setInterval((ready) => {
  process.nextTick(async () => {
    try {
      const result = await asyncCall();
      waitForSomethingElse(async (error, data) => {
        if (error) {
          ready(); // <-- Always run `ready()`, even if call was unsuccessful
          return;
        }

await saveCollectedData(result, [data]);
        ready(); // <-- End of the full execution
      });
    } catch (err) {
      console.log(err)
      ready(); // <-- Always run `ready()`, even if call was unsuccessful
    }
  });
}, 60 * 60000, 'longRunningTask1h'); // once every hour
```

### Clean up old tasks

During development and tests you may want to clean up Adapter's Storage

#### Clean up Redis

To clean up old tasks via Redis CLI use the next query pattern:

```shell
redis-cli --no-auth-warning --scan --pattern "josk:default:*" | xargs redis-cli --raw --no-auth-warning DEL

# If you're using multiple JoSk instances with prefix:
redis-cli --no-auth-warning --scan --pattern "josk:prefix:*" | xargs redis-cli --raw --no-auth-warning DEL

# If useHashTags is true:
redis-cli --no-auth-warning --scan --pattern "josk:{prefix}:*" | xargs redis-cli --raw --no-auth-warning DEL
```

#### Clean up MongoDB

To clean up old tasks via MongoDB use the next query pattern:

```js
// Run directly in MongoDB console (default prefix `default`):
db.getCollection('__JobTasks__default').deleteMany({});
// If you're using a custom prefix:
db.getCollection('__JobTasks__PrefixHere').deleteMany({});
// Lock collection (shared across prefixes by default):
db.getCollection('__JobTasks__.lock').deleteMany({});
```

#### Clean up PostgreSQL

To clean up old tasks and lock for current prefix via PostgreSQL:

```sql
DELETE FROM josk_tasks WHERE prefix = 'default';
DELETE FROM josk_locks WHERE lock_key = 'josk-default.lock';

-- If you're using custom prefix:
DELETE FROM josk_tasks WHERE prefix = 'cluster-scheduler';
DELETE FROM josk_locks WHERE lock_key = 'josk-cluster-scheduler.lock';
```

### MongoDB connection fine tuning

For replica-set tuning, dedicated-DB recommendations, the maintained index inventory, and notes on Mongoose / CosmosDB / DocumentDB compatibility, see [`docs/mongodb.md`](docs/mongodb.md).

## Prefix mapping

`prefix` isolates scheduler state per adapter. Same prefix = same shared queue; different prefixes = isolated namespaces. The default value is `default` across all adapters.

| Adapter | Storage layout for `prefix: 'app'` | Notes |
|---|---|---|
| Redis | Default keys: `josk:app:schedule`, `josk:app:tasks`, `josk:app:lock`. With `useHashTags: true`: `josk:{app}:schedule`, `josk:{app}:tasks`, `josk:{app}:lock`. | Hash tags keep all keys on the same Cluster slot. Prefix must match `/^[A-Za-z0-9_\-:.]+/` — special characters (notably `{` and `}`) are rejected to protect Cluster routing. |
| MongoDB | Collection `__JobTasks__app`; lock collection `__JobTasks__.lock` (shared across prefixes, scoped by `uniqueName` field) | Override the lock collection with `lockCollectionName`. Keep collection names short — Mongo's name limit is 120 characters including database name. |
| PostgreSQL | Rows in `josk_tasks` filtered by `prefix='app'`; lock row in `josk_locks` with `lock_key='josk-app.lock'` | Table names are fixed. Use prefix for tenant/environment isolation. |

## Operational FAQ

### How do I monitor stuck tasks?

Set a long-running task to throw or skip `ready()` past `zombieTime`. The `onError` hook fires with `'One of your tasks is missing'` (only if `autoClear: false`). For active observability, query the storage directly: Redis `HLEN josk:prefix:tasks` (or `HLEN josk:{prefix}:tasks` with `useHashTags: true`), Mongo `db.__JobTasks__<prefix>.countDocuments({ executeAt: { $lt: new Date() } })`, Postgres `SELECT COUNT(*) FROM josk_tasks WHERE prefix='<prefix>' AND execute_at < (EXTRACT(EPOCH FROM CURRENT_TIMESTAMP) * 1000)::BIGINT`.

### How do I handle storage restarts?

JoSk swallows adapter errors and retries on the next tick. The scheduler self-recovers once the connection is healthy. Locks held by crashed nodes self-expire (Redis: PEXPIRE, Mongo: TTL index, Postgres: `locked_until` compared against server time on next claim).

### `one` vs `batch` execute mode?

Use `batch` for normal throughput — it claims due tasks in chunks and reduces storage round-trips. Switch to `one` if you need smaller execution bursts per instance, finer fairness between cluster members, or if your handlers contend on the same downstream resource.

### Jitter: Why is my interval running every `delay + maxRevolvingDelay` ms?

JoSk polls between `minRevolvingDelay` and `maxRevolvingDelay`. The effective interval is `delay + (poll latency)`. Lower `maxRevolvingDelay` for tighter intervals at the cost of more storage reads.

### What about clock skew between nodes?

Redis uses relative `PX` TTL. Postgres derives lease expiry from `CURRENT_TIMESTAMP`, so app-node clock skew does not change lock lifetime. Mongo stores app-generated dates and uses a server-side TTL index for cleanup; keep Mongo app nodes time-synchronized.

## Notes

- This package is perfect when you have multiple horizontally scaled servers for load-balancing, durability, an array of micro-services or any other solution with multiple running copies of code running repeating tasks that need one cluster-wide claim per due tick, not one claim per server/instance;
- Recommended floor — unique tasks shorter than ~2 seconds may overlap with the storage round-trip plus revolving delay; tasks ≥2s have stable execution gaps. Example tasks: [Email](https://www.npmjs.com/package/mail-time), SMS queue, Long-polling requests, Periodic application logic operations or Periodic data fetch, sync, etc.
- Accuracy — Delay of each task depends on storage round-trip and jitter window. Trusted execution range is `task_delay ± (maxRevolvingDelay + Storage_Request_Delay)`. With default `minRevolvingDelay: 128` / `maxRevolvingDelay: 768`, expect ±0.8s + storage latency. Tighten the bounds for stricter timing at the cost of more storage reads.
- Use `opts.minRevolvingDelay` and `opts.maxRevolvingDelay` to set the range for *random* delays between executions. Revolving range acts as a safety control to make sure different servers __not__ picking the same task at the same time. Default values (`128` and `768`) are the best for 3-server setup (*the most common topology*). Tune these options to match needs of your project. Higher `opts.minRevolvingDelay` will reduce storage read/writes;
- This package implements scheduler locking via Redis key, MongoDB `.lock` collection, or PostgreSQL `josk_locks` table. Task claims are adapter-level atomic operations.

## Running Tests

Setup, full and targeted suites, coverage, and the Bun runner live in [`docs/testing.md`](docs/testing.md). Quickstart:

```shell
REDIS_URL="…" MONGO_URL="…" PG_URL="…" npm test
```

## Why JoSk?

`JoSk` is *Job-Task* - Is randomly generated name by ["uniq" project](https://uniq.site)

## Support our open source contribution:

- Try [🌉 Bridge CDN](https://bridge-cdn.com/?ref=github-josk-repo-footer) - A SEO-focused alternative to Cloudflare. CDN, DNS, IndexNow, Prerender, SEO, Edge Computing.
- Upload and share files using [☄️ meteor-files.com](https://meteor-files.com/?ref=github-josk-repo-footer) — Continue interrupted file uploads without losing any progress. There is nothing that will stop Meteor from delivering your file to the desired destination
- Use [▲ ostr.io](https://ostr.io?ref=github-josk-repo-footer) for [Server Monitoring](https://snmp-monitoring.com), [Web Analytics](https://ostr.io/info/web-analytics?ref=github-josk-repo-footer), [WebSec](https://domain-protection.info), [Web-CRON](https://web-cron.info) and [SEO Pre-rendering](https://prerendering.com) of a website
- Star on [GitHub](https://github.com/veliovgroup/josk)
- Star on [NPM](https://www.npmjs.com/package/josk)
- Star on [Atmosphere](https://atmospherejs.com/ostrio/cron-jobs)
- [Sponsor via GitHub](https://github.com/sponsors/dr-dimitru)
- [Support via PayPal](https://paypal.me/veliovgroup)

[npm-url]: https://www.npmjs.com/package/josk
[badge-npm-v]: https://img.shields.io/npm/v/josk.svg
[badge-npm-dm]: https://img.shields.io/npm/dm/josk.svg
[badge-ci]: https://github.com/veliovgroup/josk/actions/workflows/test.yml/badge.svg?branch=master
[ci-url]: https://github.com/veliovgroup/josk/actions/workflows/test.yml
[badge-size]: https://img.shields.io/bundlephobia/minzip/josk.svg
[size-url]: https://bundlephobia.com/package/josk
[badge-cov]: https://img.shields.io/badge/coverage-~99%25-brightgreen
[badge-license]: https://img.shields.io/badge/License-BSD%203--Clause-blue.svg
[license-url]: https://opensource.org/licenses/BSD-3-Clause
[badge-node]: https://img.shields.io/node/v/josk
[node-url]: https://nodejs.org/
[badge-ts]: https://img.shields.io/badge/TypeScript-ready-blue
[ts-url]: https://github.com/veliovgroup/josk#typescript
[badge-bun]: https://img.shields.io/badge/Bun-%3E%3D1.1.0-black?logo=bun
[bun-url]: https://github.com/veliovgroup/josk#bun-runtime
[badge-meteor]: https://img.shields.io/badge/Meteor.js-ostrio%3Acron--jobs-red?logo=meteor&logoColor=white
[meteor-url]: https://packosphere.com/ostrio/cron-jobs
[badge-deps]: https://img.shields.io/badge/dependencies-0-brightgreen
[badge-sponsor]: https://img.shields.io/github/sponsors/dr-dimitru?label=Sponsor
[sponsor-url]: https://github.com/sponsors/dr-dimitru
[badge-donate]: https://img.shields.io/badge/Donate-PayPal-00457C?logo=paypal&logoColor=white
[donate-url]: https://paypal.me/veliovgroup

josk

josk 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

josk

josk 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

Download README