effect-mq README

The project's README from github.com/TeamWarp/effect-mq. As one markdown file: README.md.

effect-mq

Effect-native background jobs: schema-first job definitions, a storage-agnostic queue core, a worker runtime, and a Postgres store that lives inside your drizzle schema. Built on Effect v4; inspired by BullMQ's semantics and effect/workflow's DX.

→ Documentation: effect-mq.com — the package README (packages/effect-mq, also shown on npm) covers the same ground in one page.

Maintained by Warp. We're hiring.

import { Job } from "effect-mq"
import { Effect, Schema } from "effect"

class SendEmail extends Job.make("SendEmail", {
  payload: { to: Schema.String, subject: Schema.String },
  success: Schema.String,
  idempotencyKey: ({ to, subject }) => `${to}:${subject}`,
  metadata: ({ to }) => ({ to }),
  defaults: { attempts: 3, backoff: { type: "exponential", delay: "1 second" } }
}) {}

const producer = Effect.gen(function*() {
  const jobId = yield* SendEmail.enqueue({ to: "[email protected]", subject: "hi" })
})

Highlights

Repository layout

packages/effect-mq        the published package (src + tests, incl. the
                          Postgres and Redis suites under test/)
examples/tour             THE demo: four scenes against real Postgres +
                          Redis (kill -9 durability, dedup, a paused
                          cross-store flow) plus a live dashboard —
                          see examples/tour/README.md
examples/basic            minimal in-memory end-to-end: bun src/main.ts
docker-compose.yml        Postgres 17 (5433) + Redis 8 (6380) for the
                          storage test suites
tools/oxlint/anti-slop    local lint plugin enforcing honest types

Development

bun install
bun run check     # TypeScript 7, per package
bun run lint      # oxlint (incl. anti-slop rules)
bun run test      # vitest 4 + @effect/vitest, TestClock-driven
                  # (storage suites self-skip without their backing service)
bun run test:pg   # docker compose up + the Postgres suite
bun run test:redis  # docker compose up + the Redis suite
bun run ready     # check + lint + test
bun run build     # emit dist (tsc, .ts imports rewritten to .js)

The store conformance suite (effect-mq/testing) runs against the in-memory driver, real Postgres, and real Redis — under TestClock in all cases, because drivers take all time as parameters from the Effect Clock.

Release history lives in CHANGELOG.md; planned work in ROADMAP.md.

Releasing

CI (.github/workflows/ci.yml) runs check/lint/tests (with Postgres and Redis service containers) on every push and PR. Publishing to npm happens on version tags:

# bump "version" in packages/effect-mq/package.json, then
git tag v0.2.0 && git push --tags

The publish job runs npm publish with provenance; it needs an NPM_TOKEN repository secret. The package's prepack builds dist and swaps the dev (TS-source) exports for dist exports; postpack restores them. Verify a release candidate locally with:

cd packages/effect-mq && bun pm pack   # then inspect / install the tarball

License

MIT

effect-mq (TeamWarp/effect-mq)

Searching Database…

Что это?effect-mq — библиотека фоновых задач и очередей сообщений в духе Effect: определения задач через схемы, независимое от хранилища ядро очередей, среда выполнения воркеров и хранилища для Postgres (через Drizzle) и Redis.
Это библиотека для импорта или отдельный сервис для запуска?Это TypeScript-библиотека, разделённая на tree-shakeable-модули (ядро, хранилище drizzle-postgres, хранилище redis, набор для тестирования), которые вы встраиваете в своё Effect-приложение; отдельного серверного бинарника нет.
Как встроить его в проект?Установите effect-mq и нужный модуль хранилища, реэкспортируйте прилагаемые фабрики drizzle-схем, чтобы drizzle-kit управлял миграциями таблиц задач, затем определите задачи и запустите среду воркеров на этом хранилище.
Нужны ли Effect и экземпляр Postgres или Redis?Да, библиотека построена на Effect v4 и требует хотя бы одно хранилище — Postgres (захват задач через FOR UPDATE SKIP LOCKED и LISTEN/NOTIFY) или Redis (атомарные Lua-скрипты с pub/sub) — плюс in-memory-драйвер для тестов или одноразовых задач.
Что происходит, если воркер падает или задача зависает на середине?Доставка гарантируется хотя бы один раз (at-least-once) — с блокировками под токеном, обновлением heartbeat и восстановлением зависших задач, — а каждая попытка сохраняется в журнал запусков в хранилище, а не в памяти воркера, поэтому повторы переживают сбои.
Как повторяющиеся cron-задачи избегают двойного срабатывания на нескольких воркерах?Каждое срабатывание захватывается и ставится в очередь одной атомарной операцией хранилища, что гарантирует ровно одну задачу на срабатывание при любом числе запущенных воркеров и любых настройках хранения.
Какие варианты дедупликации он предлагает?Поддерживаются pending-dedup, throttle, debounce и replace-while-delayed — все используют отдельный ключ дедупликации, так что реальный id задачи никогда не перезаписывается.
Можно ли отправлять разные задачи в разные хранилища?Да, задачи можно привязывать к именованным хранилищам — например, Postgres для критичных для бизнеса запусков и память или Redis для одноразовых — и такая маршрутизация соблюдается на этапе компиляции.
Есть ли встроенный дашборд?Готового интерфейса в комплекте нет, но effect-mq открывает слой данных для дашборда: список с фильтрами по метаданным, keyset-пагинацию, поллинг, повтор и удержание по отдельной задаче и по хранилищу — поверх этого можно построить дашборд.
What are similar projects?bull, rq, tork, carno.js, react-starter-kit, rankme.fast, dockhand, asynq
Creator
TeamWarp
Size
0.7 MB
Stars
188
Updated
CommitSep 09
Age
1mo
Commits · 90 Days