simple-tasks

Function-based task framework on top of BullMQ. Define tasks with a single function, enqueue them easily, and run all workers from one entrypoint.

Install

bun install @rhymiz/simple-tasks bullmq

Peer dependencies:

• bullmq (>=5 <6)

Quick start

Define a task:

// src/queues/email.ts
import { defineTask } from '@rhymiz/simple-tasks';

type SendWelcomeData = { userId: string };

export const sendWelcomeEmail = defineTask<SendWelcomeData>({
  name: 'send-welcome-email',
  queuePrefix: 'emails',
  worker: { concurrency: 5 },
  defaultJobOptions: { attempts: 3 },
}, async (data, job) => {
  console.log('Sending welcome email to', data.userId, 'job', job.id);
});

Enqueue from anywhere:

await sendWelcomeEmail.enqueue({ userId: '123' });
await sendWelcomeEmail.enqueue({ userId: '123' }, { delay: 10_000 });

Schedule recurring jobs with BullMQ v5 job schedulers:

await sendWelcomeEmail.schedule(
  'daily-welcome-check',
  { pattern: '0 9 * * *' },
  { userId: '123' }
);

await sendWelcomeEmail.unschedule('daily-welcome-check');
const schedule = await sendWelcomeEmail.getSchedule('daily-welcome-check');

Worker entrypoint:

// src/queue-worker.ts
import './queues/email';
import './queues/billing';
import './queues/notifications';

import { runAllWorkers } from '@rhymiz/simple-tasks/runtime';

const onlyQueues = process.env.QUEUES?.split(',').filter(Boolean);
const onlyJobs = process.env.JOBS?.split(',').filter(Boolean);

runAllWorkers({ onlyQueues, onlyJobs });

Configuration

The framework passes Redis connection options to BullMQ. Configure via environment variables:

• REDIS_URL (optional, takes precedence over host/port)
• REDIS_HOST (default: 127.0.0.1)
• REDIS_PORT (default: 6379)
• SIMPLE_TASKS_QUEUE_PREFIX (optional, prepends to every queue name with -)

BullMQ manages its own clients; this package does not import ioredis directly.

Migrating to v1

Version 1 requires BullMQ 5. BullMQ 4 is no longer supported.

Recurring jobs use BullMQ v5 job schedulers through task.schedule(...), task.unschedule(...), and task.getSchedule(...). This package does not create or migrate legacy repeatable jobs. If you previously created repeatable jobs directly with BullMQ, remove or migrate those jobs before adding equivalent schedulers to avoid duplicate recurring work.

One-off delayed jobs still use task.enqueue(data, { delay }).

Development

This package is built with TypeScript.

bun run build           # build JS and .d.ts into dist/
bun run lint            # run linter
bun run test            # run tests
bun run test:e2e:scheduler # verify BullMQ v5 schedulers against local Redis
bun run pack            # create tarball for testing

Releasing

This project uses automated releases via GitHub Actions.

Manual Release Process

1. Bump version (creates a git tag automatically):

   bun run version:patch   # 0.1.0 -> 0.1.1 (bug fixes)
   bun run version:minor   # 0.1.0 -> 0.2.0 (new features)
   bun run version:major   # 0.1.0 -> 1.0.0 (breaking changes)

2. Push the tag to trigger the release:

   git push --follow-tags

3. The GitHub Action will automatically:

   • Create a GitHub Release
   • Build the package
   • Publish to GitHub Package Registry

Using the Package

To install from GitHub Packages, add to your .npmrc:

@rhymiz:registry=https://npm.pkg.github.com

Then install:

bun install @rhymiz/simple-tasks bullmq

License

MIT