Josk

JoSk

Distributed setInterval / setTimeout / setImmediate for Node ≥20.9 and Bun ≥1.1. Server-only. Schedule in Redis, MongoDB, or PostgreSQL; lease + atomic claim limit duplicate ticks.

Quick start

JoSk does not open connections — pass a connected client. Always wire onError and destroy() on shutdown. Read references/ lazily; do not guess v4/v5/v6 semantics from memory.

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

const client = createClient({ url: process.env.REDIS_URL });
await client.connect();

const jobs = new JoSk({
  adapter: new RedisAdapter({ client }),
  onError: (title, { error, uid }) => console.error(title, uid, error),
});

await jobs.setInterval(async () => { /* idempotent work */ }, 60_000, 'poll-1m');
// jobs.pause() / jobs.resume() / jobs.destroy()

Reference map

Mental model

• adapter required — RedisAdapter, MongoAdapter, PostgresAdapter, or custom (adapters.md).
• uid — app-wide unique string per logical task; reuse collides in storage.
• Handler — async/Promise preferred; sync zero-arg; or (ready) => for callback APIs (patterns.md).
• set* → Promise<string> — pass string or that Promise to clear*.

Pick the adapter

Pick the scheduling method

zombieTime (default 15 min): max interval handler runtime before re-claim. Keep ≥ slowest handler + margin; not below 60s.

Throughput

• execute: 'batch' (default) — all due tasks per lease; 'one' — one task per lease
• concurrency: Infinity (default) — parallel handlers; set integer to cap pool/API/CPU

Red flags

Call out proactively when reviewing JoSk usage:

• Missing onError
• Reused uid across different tasks
• Default zombieTime with handlers >15 min
• resetOnInit: true in production cluster
• Replica reads / multi-writer Redis
• Redis Cluster without useHashTags: true
• Intervals <~2s (storage + jitter overlap)
• MongoAdapter on CosmosDB/DocumentDB/Mongoose without warning
• KeyDB active-replication / multi-master

Source: veliovgroup/josk — distributed by TomeVault.