sidetrack

library0.1.14jsnpmunverified

Sidetrack is a TypeScript-first job processing library backed by PostgreSQL (current version 0.1.14). It is actively developed with a focus on simplicity, reliability, and TypeScript ergonomics. Unlike general-purpose message brokers (like RabbitMQ or Redis-based queues), Sidetrack leverages Postgres as both the backing store and the scheduling engine, enabling transactional enqueuing and strong consistency. It supports delayed jobs, retries, concurrency control, and rate limiting. The library is designed for serverless and Edge environments where a single Postgres database is already in use, avoiding additional infrastructure. It requires a running Postgres instance and the pg driver. While still in early development (pre-1.0), it has a growing community and is considered stable for production use. Release cadence is irregular but frequent (several minor releases per month).

database

npm install sidetrack

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · SIDETRACK

sidetrack

databasejavascriptv0.1.14

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.

Sidetrack

✓ import { Sidetrack } from 'sidetrack'

✗ const Sidetrack = require('sidetrack').Sidetrack

ESM-only package; CommonJS require() must use .default or destructure.

Job

✓ import { Job } from 'sidetrack'

✗ import Job from 'sidetrack'

Job is a named export, not default.

Queue

✓ import { Queue } from 'sidetrack'

✗ import { Queue } from 'sidetrack/queue'

All exports are from the main entry point.

Initialize Sidetrack with a pg Pool, define a worker, enqueue a job, start processing, and handle graceful shutdown.

import { Sidetrack } from 'sidetrack'; import { Pool } from 'pg'; const pool = new Pool({ connectionString: process.env.DATABASE_URL ?? 'postgres://localhost:5432/mydb' }); const st = new Sidetrack({ pool }); async function main() { await st.init(); // Creates necessary tables // Define a worker st.worker('email', async (job) => { console.log(`Sending email to ${job.data.to}`); // ... send email }); // Enqueue a job await st.enqueue('email', { to: 'user@example.com', subject: 'Hello' }); // Start processing await st.start(); // Graceful shutdown process.on('SIGINT', async () => { await st.stop(); process.exit(0); }); } main().catch(console.error);

Debug

Known issues

breakingv0.1.0 changed the constructor signature from `new Sidetrack(connectionString)` to `new Sidetrack({ pool })`.

fix

Upgrade to v0.1.0+ and pass an options object with a `pool` property (an instance of `pg.Pool`).

affects: 0.0.x

gotchaJob handlers must be registered before calling `start()`. Registering after start results in undefined behavior.

fix

Ensure all `worker()` calls happen before `start()`.

affects: >=0.1.0

gotchaThe `init()` method must be called before any enqueue or worker operations; it creates the required database tables.

fix

Call `await st.init()` right after creating the Sidetrack instance.

affects: >=0.1.0

deprecatedThe method `addWorker()` is deprecated since v0.1.10; use `worker()` instead.

fix

Replace `addWorker(name, handler)` with `worker(name, handler)`.

affects: <0.1.10

gotchaWhen using TypeScript, job data types must be explicitly provided for type safety; otherwise inferred as `any`.

fix

Define an interface and use `st.enqueue<MyData>('queue', data)`.

affects: >=0.1.0

Errors

Common errors & fixes

Error: relation "sidetrack_jobs" does not exist

The database tables have not been created. You forgot to call `st.init()`.

fix

Call `await st.init()` before any other operations.

TypeError: st.worker is not a function

Using an older version of Sidetrack (<0.1.10) where the method was named `addWorker`.

fix

Update to v0.1.10+ and use `st.worker(name, handler)`.

No overload matches this call. Overload 1 of 2, "(data: never): ..." gave the following error.

TypeScript cannot infer the job data type. The enqueue call lacks a generic type parameter.

fix

Add a generic type: `st.enqueue<YourDataType>('queue', data)`.

Error: pool is not a Pool instance

Passed a connection string instead of a Pool object to the Sidetrack constructor (pre-v0.1.0 pattern).

fix

Update to `new Sidetrack({ pool: new Pool({ connectionString }) })`.

Upgrade

Version history

0.1.14latest on npm

Audit

Dependencies

pgrequiredPostgreSQL client for Node.js; required to connect to the database

Agent activity

5 hits · last 30 days

node