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 (>=4 <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 });

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.

Development

This package is built with TypeScript.

npm run build           # build JS and .d.ts into dist/
npm run lint            # run linter
npm 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