josk

library6.2.0jsnpmunverified

JoSk (v6.2.0) is a Node.js task manager for horizontally scaled applications, mimicking native setTimeout/setInterval API with CRON support. It synchronizes queued tasks across multiple application instances via Redis, MongoDB, or PostgreSQL adapters, using storage-level leases and atomic task claims to ensure each tick is processed by exactly one instance. Released under BSD-3-Clause, with zero runtime dependencies, TypeScript types, and support for Node.js >=20.9.0 and Bun >=1.1.0. Suitable for clusters, multi-server, and multi-threaded environments, as well as single-instance apps.

devops

npm install josk

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · JOSK

josk

devopsjavascriptv6.2.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

JoSk

✓ import { JoSk } from 'josk'

✗ const JoSk = require('josk')

ESM-only package since v6; CommonJS require() will fail. TypeScript types are bundled.

RedisAdapter

✓ import { RedisAdapter } from 'josk/adapters'

✗ import { RedisAdapter } from 'josk'

Adapters must be imported from 'josk/adapters' subpath; they are not re-exported from main entry.

MongoAdapter

✓ import { MongoAdapter } from 'josk/adapters'

✗ import { MongoAdapter } from 'josk'

Adapters are located in a separate subpath; ensure adapter package (e.g., mongodb) is installed.

PostgresAdapter

✓ import { PostgresAdapter } from 'josk/adapters'

✗ import { PostgresAdapter } from 'josk'

PostgreSQL adapter requires pg package to be installed separately.

JoSkOptions

✓ import type { JoSkOptions } from 'josk'

Type-only import for TypeScript users.

Creates a JoSk instance with Redis adapter, schedules interval and timeout tasks, and destroys scheduler after 30 seconds.

import { JoSk } from 'josk'; import { RedisAdapter } from 'josk/adapters'; const redisUrl = process.env.REDIS_URL ?? 'redis://localhost:6379'; const scheduler = new JoSk({ adapter: new RedisAdapter({ url: redisUrl }), prefix: 'myapp', }); // Schedule a recurring task every 5 seconds const timer = scheduler.setInterval(() => { console.log('Task executed at', new Date().toISOString()); }, 5000, 'my-recurring-task'); // Schedule a one-time task after 10 seconds scheduler.setTimeout(() => { console.log('One-time task executed'); }, 10000, 'my-once-task'); // Shut down gracefully after 30 seconds setTimeout(async () => { await scheduler.destroy(); console.log('Scheduler destroyed'); process.exit(0); }, 30000);

Debug

Known issues

breakingJoSk v6 is ESM-only; CommonJS require() will throw ERR_REQUIRE_ESM.

fix

Use import syntax or dynamic import(). Ensure package.json has type: 'module'.

affects: >=6.0.0

breakingAdapters must be imported from 'josk/adapters' subpath since v6.

fix

Change imports from 'josk' to 'josk/adapters' for adapter classes.

affects: >=6.0.0

deprecatedsetImmediate() is deprecated as of v5.2.0; use setInterval() with delay 0.

fix

Use scheduler.setInterval(callback, 0, uid) instead of scheduler.setImmediate().

affects: >=5.2.0

gotchaCallback functions must be serializable when using remote adapters; closures with references to external scope will lose context on other instances.

fix

Ensure callback logic is self-contained or uses globally available references; do not rely on closure variables.

affects: >=1.0.0

gotchaUIDs must be unique across all tasks; duplicate UIDs will overwrite existing scheduled tasks silently.

fix

Generate unique UIDs (e.g., using crypto.randomUUID()) to avoid collisions.

affects: >=1.0.0

Errors

Common errors & fixes

Error [ERR_MODULE_NOT_FOUND]: Cannot find module 'josk/adapters'

Importing from 'josk/adapters' but package version is <6.0.0 where adapters were in main entry.

fix

Upgrade to josk@6 or use import { RedisAdapter } from 'josk' for older versions.

TypeError: JoSk is not a constructor

Using require() to import the module (CommonJS).

fix

Use import { JoSk } from 'josk' or switch to dynamic import() in Node.js.

Error: adapter must be an instance of RedisAdapter, MongoAdapter, or PostgresAdapter

Passed an invalid or missing adapter to JoSk constructor.

fix

Ensure adapter is imported correctly and instantiated before passing to new JoSk({ adapter }).

MongoError: not authorized on admin to execute command

MongoDB user lacks write permissions on the database used for task storage.

fix

Grant write role on the specific database, or configure a user with appropriate privileges.

Upgrade

Version history

6.2.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

4 hits · last 30 days

node

Resources

githubgit://github.com/veliovgroup/josk ↗

packagejosk ↗

homepagehttps://github.com/veliovgroup/josk ↗