Skip to content

api-reference.md

Latest commit

 

History

History
138 lines (111 loc) · 6.9 KB

api-reference.md

File metadata and controls

138 lines (111 loc) · 6.9 KB
Raw

API reference

The package is ESM and exposes the root module plus stable module subpaths. Public TypeScript declarations in the packed tarball are authoritative; this page describes the intended entry points and their contracts.

Task

  • Task.make(config) synchronously defines payload, success, and typed-failure schemas, an optional progress schema, stable schemaId, idempotency key, retry schedule/cap, storage limits, and retention. It does not evaluate an Effect or validate runtime invariants.
  • defaultRetentionPolicy is 7 days for task records and terminal indexes, 1 day for results, 30 days for dead-letter entries, and 7 days for events.
  • Queue and worker operations check definition invariants at first use. Invalid programmer-authored task configuration is a defect, not a typed failure.

TaskQueue

  • make(name, definition) binds a task definition to a queue name.
  • offer(queue, payload, options?) returns TaskCreated | TaskExisting; both include the decoded task and a generation-specific TaskHandle.
  • wait(queue, handle, options?) resolves the exact generation's typed success or fails with a typed task/storage/cursor/timeout outcome.
  • execute(queue, payload, options?) is offer followed by handle-based wait.
  • completeOne(queue, handler, processing?) acquires and supervises at most one attempt, returning whether work was processed.
  • complete(queue, handler) processes one task and returns its id.
  • stream(queue, options?) decodes versioned queue-wide lifecycle events from a cursor.
  • readEvents(queue, handle, options?) pages typed progress and compact lifecycle history for one generation, using an independent opaque history cursor.

Important offer options include taskId, delay, maxRetries, completion policies, onDuplicate, and retainResultUntil: "current-task-settles". Numeric overrides are validated before Redis is mutated. Processing options configure lease duration, heartbeat interval, and bounded heartbeat transport retry.

TaskHistory

Declare progress on Task.make to enable history for new generations; Schema.Never enables lifecycle-only history. Managed handlers in complete, completeOne, and Worker receive TaskHistory.Context as their second argument. Its progress(value) Effect encodes the declared schema and returns the stored entry id. Progress failures use ProgressWriteError, outside the business-error schema; an uncaught failure leaves the attempt for lease recovery.

TaskHistory.Entry contains generation/attempt identity, a timestamp, and a Progress or Lifecycle event. Page contains entries, cursor, hasMore, and truncated; ReadOptions accepts after and a limit of 1–1,000 (default 100). Readers are independent and can poll empty pages while work is running.

History follows the task record's lifetime, including deletion and retention holds. It is unlimited unless storageLimits.maxHistoryEntries is a positive safe integer. Trimming can produce HistoryCursorExpired; result retention does not preserve history after record deletion. See the progress guide and upgrade requirements.

EventQueue, EventEngine, and EventRecord

EventQueue.make(name, payloadSchema, options?) defines durable application events. subscribe registers an idempotent named recipient; emit captures the current recipient set. Use processOne for managed processing or take, acknowledge, renew, and release for explicit delivery control. unsubscribe waives that generation's outstanding obligations. Run runMaintenance for idle expiry and cleanup; get and listArchived inspect retained records.

EventEngine.layer() supplies the standard Node Redis and Crypto graph; layerNoDeps() supports custom Redis pools. EventRecord owns public event, subscription, and delivery types. See durable events for examples, retention policies, delivery guarantees, and operational bounds.

Worker

  • make(queue, handler, options?) describes a managed worker.
  • run(worker) runs scoped acquisition slots plus maintenance until interrupted. Options include concurrency, poll/maintenance intervals, drain timeout, and processing supervision. Invalid concurrency, durations, or processing settings fail with WorkerConfigurationError before any fibers start.

Scheduler

  • make(config) synchronously creates a long-running durable materializer Effect descriptor. Invalid definition configuration is a defect when the scheduler first runs.
  • materializeDue(config, now?) performs one deterministic bounded observation, useful for tests and externally driven scheduler loops.
  • Missed policy is skip, coalesce, or bounded backfill.

NodeRedisPool and RedisPool

  • NodeRedisPool.layer(config?) provides independent producer, worker, and maintenance services plus Effect's Redis service and RedisConnectionHealth. Standalone and Sentinel are supported; Cluster fails with UnsupportedRedisTopology.
  • RedisConnectionHealth.snapshot is passive and secret-free; readiness actively pings every role.
  • RedisPool is the minimal custom-client boundary: text/binary send and content-addressed evalScript with NOSCRIPT recovery.

TaskEngine

TaskEngine is the lower-level storage protocol. Its public operations include offer/get/result, fenced acquire/renew/succeed/fail/release, bounded maintenance, paginated state inspection, event cursors/streaming, progress append/history reads, schedule cursor coordination, ordinary removal, and administrative force removal. Prefer TaskQueue, Worker, and Scheduler unless building tooling or an alternate runtime.

  • TaskEngine.layer(config?) is the zero-requirement Node live graph and retains Redis operational services in its output.
  • TaskEngine.layerNoDeps(config?) requires an ambient RedisPool for custom client compositions.
  • Invalid configuration and Redis reply shapes use structured typed errors; diagnostic strings are retained only as causes.

TaskRecord and TaskEvent

TaskRecord owns public durable task identity/state schemas and typed record codecs. TaskEvent owns public versioned lifecycle event schemas. MessagePack, raw engine-record, and retry-schedule modules are internal and unsupported as package subpaths.

StorageProtocol and Observability

StorageProtocol owns the versioned opaque-value codec and typed corruption, version, schema, value, size, and count errors. Observability exports Effect metrics for depth/age/backlogs, Redis errors/reconnects/script reloads, ownership loss, and retention failure.

Stable subpaths are ./EventEngine, ./EventQueue, ./EventRecord, ./NodeRedisPool, ./Observability, ./RedisPool, ./Scheduler, ./StorageProtocol, ./Task, ./TaskEngine, ./TaskEvent, ./TaskHistory, ./TaskQueue, ./TaskRecord, and ./Worker.