queuert
Client, worker, job types and the in-process adapters.
$npm install queuert
Functions13
- createClientCreate a new Queuert client.
- createConsoleLogCreate a Log implementation that writes to console.
- createInProcessNotifyAdapterCreate a notify adapter that delivers notifications through in-process callbacks. Only clients and worker runners in this process are notified, so it suits single-process deployments.
- createInProcessStateAdapterCreate a state adapter that keeps chains, jobs and workers in memory. State is lost on process exit and visible only inside this process.
- createJobTypesCreate a job type registry with runtime validation and codec. Wraps adapter errors in JobTypeValidationError and enforces JSON-serializability on every encoded value.
- createProcessorsDefine a processor registry for a job type slice with full type inference. Handlers are type-checked against the slice's own definitions plus any external definitions it declares (for cross-slice blocker / continueWith references). The returned registry is plugged into createWorkerRunner.
- createTxHooksCreate a new tx hooks handle.
- createWorkerRunnerCreate a worker runner for processing jobs.
- defineJobTypesDefine job types with compile-time type checking only (no runtime validation). Returns a JobTypes that passes all values through (identity codec).
- isJsonSerializableRuntime check that value survives a JSON round-trip without coercion or loss.
- omitProcessorsCreate a registry holding every job type of processors except the listed ones, e.g. for the worker that handles whatever the dedicated workers built with pickProcessors don't. Each remaining processor keeps its handler, its middleware chain and its backoffConfig.
- pickProcessorsCreate a registry holding only the listed job types of processors, e.g. to run them on a dedicated worker. Each picked processor keeps its handler, its middleware chain and its backoffConfig.
- withTxHooksExecute a callback with auto-managed tx hooks. Flushes on success, discards on error.
Classes21
- BlockerLimitExceededErrorThrown when a job declares more blocker chains than the state adapter's maxBlockersPerJob allows. The limit is configurable but always bounded: the jobblocker model is not designed to scale to an unbounded number of blockers per job.
- BlockerReferenceErrorThrown when deleting chains that are still referenced as blockers by other jobs.
- ChainNotFoundErrorThrown when a chain does not exist.
- ChainTypeMismatchErrorThrown when a chain's actual type does not match the expected typeName.
- DuplicateJobTypeErrorThrown when merging registries that contain overlapping job type names.
- InvalidJobIdErrorThrown when a job ID fails the state adapter's validateJobId check.
- InvalidWorkerIdErrorThrown when a worker ID fails the state adapter's validateWorkerId check.
- JobAlreadyCompletedErrorThrown when attempting to complete an already-completed job.
- JobAttemptReclaimedErrorRecorded as a job's lastAttemptError when a worker reclaims its attempt because the worker holding the attempt lost its lease, stopped, or no longer runs it.
- JobNotFoundErrorThrown when a job does not exist.
- JobNotReschedulableErrorThrown when rescheduleJob targets a job that is not pending.
- JobsNotFoundErrorThrown when rescheduleJobs targets any job that does not exist. Batch variant of JobNotFoundError, listing every input id with no matching job.
- JobsNotReschedulableErrorThrown when rescheduleJobs targets any job that is not pending. Batch variant of JobNotReschedulableError, listing every offending input id.
- JobTakenByAnotherWorkerErrorThrown when the job's current attempt is not the one this worker holds.
- JobTypeMismatchErrorThrown when a job's actual type does not match the expected typeName.
- JobTypeValidationErrorThrown when runtime job type validation fails (via createJobTypes).
- SchemaFencedErrorThrown when a write is fenced: a breaking migration dropped the write fence of this code version, so older code can no longer change jobs, blockers or workers. The write changes nothing. Worker runners report it through workerError and keep retrying. On Redis it is also thrown until migrateToLatest() has run.
- UnknownJobTypeErrorThrown by a merged JobTypes when an operation references a type name that no slice owns. Only raised when every slice in the merge was built with createJobTypes; mixed merges that include a defineJobTypes slice fall back to no-op validation for unknown types.
- WaitChainTimeoutErrorThrown when awaitChain exceeds its timeout or is aborted.
- WorkerAlreadyLiveErrorThrown when a worker can't start because a live worker holds its id. Reported through workerError.
- WorkerLeaseLostErrorThrown when a worker lost its lease. Reported through workerError.
Types54
- AttemptMiddlewareWraps job processing with cross-cutting logic.
- BackoffConfigExponential backoff configuration for retry delays.
- BaseJobTypeDefinitionBase shape for a single job type definition.
- BaseJobTypeDefinitionsRecord mapping job type names to their definitions.
- BaseTxContextBase type for state adapter contexts.
- ChainA chain. Discriminated union on Chain.status | status.
- ChainStatusPossible statuses of a chain.
- ClientExperimentalThe public API for managing chains. Created via createClient.
- CompletedChainA chain narrowed to "completed" status.
- CompletedJobA job narrowed to "completed" status.
- DeduplicationOptionsOptions for chain deduplication.
- EnsureJsonSerializableCompile-time helper: resolves to T when T carries nothing that would be lost in a JSON round-trip, otherwise to a descriptive error string that surfaces at the call site of the consumer.
- InProcessStateAdapterIn-process state adapter type, returned by createInProcessStateAdapter.
- JobA job within a chain. Discriminated union on Job.status | status, with completed further split into a terminal variant (carries output, continuedToId === null) and a continued variant (no output, continuedToId points at the successor job).
- JobStatusPossible statuses of a job. A blocked job is waiting on incomplete blocker chains.
- JobTypeDefinitionErrorsDescriptive error type produced when job type definitions fail validation. Lists the invalid type names.
- JobTypeDefinitionsExtract the job type definitions from a JobTypes slice.
- JobTypeEntryNamesEntry type names — distributive, works on merged (union) definitions.
- JobTypeNamesDistributive keyof — returns all type names across all slices.
- JobTypeReferenceReference to another job type — either nominal (by name) or structural (by input shape).
- JobTypesRuntime registry for job type validation and codec.
- JobTypesDefinitionsResolve the definitions for a value that is either a single JobTypes slice or a readonly array of slices. Returns a union of each slice's definitions; the empty-tuple case maps to Record<never, never> so adapter generics can default the parameter and omit it cleanly.
- JobTypeValidationErrorCodeError codes for job type validation failures.
- JsonPrimitiveA JSON-safe primitive: string, number, boolean, or null.
- JsonSerializableA value that survives a JSON round-trip without coercion or loss.
- LogStructured log function. Accepts typed log entries with level, type, message, and data.
- NotifyAdapterAdapter for pub/sub notifications between workers and clients.
- ObservabilityAdapterAdapter for structured logging, metrics, and distributed tracing. All methods are synchronous — side effects are buffered via tx hooks and flushed after commit.
- OrderDirectionSort direction for paginated queries.
- PageA page of results with an optional cursor to the next page.
- PageParamsCursor-based pagination parameters.
- ProcessorsA processor registry that bundles processor implementations with their type definitions and middleware tuple via phantom symbol properties.
- ScheduleOptionsOptions for scheduling a job. Either an absolute at date or a relative afterMs delay in milliseconds.
- StateAdapterAbstracts database operations for job persistence.
- StateAdapterConfigA state adapter's resolved configuration, with defaults applied.
- StateBlockedJobA blocker with the job it blocks.
- StateChainA chain with its head job and its tail: the latest job continued from the head, whether or not the chain completed, or undefined while the head is its only job.
- StateChainInfoA chain row as a state adapter returns it, without its jobs.
- StateChainStatusA chain's status as a state adapter stores it.
- StateCountA count that stops at the adapter's countCap; hasMore is set when it stopped.
- StateDependentJobA blocker with the blocked job and that job's chain.
- StateJobA job with its chain.
- StateJobBlockerInfoOne blocker of a job: the chain the job waits for, in the order its blockers were added.
- StateJobInfoA job row as a state adapter returns it, without its chain.
- StateJobStatusA job's status as a state adapter stores it.
- StateWorkerCountsNumbers of workers whose lease is live and whose lease has ended.
- StateWorkerInfoA worker row as a state adapter returns it.
- TxHooksBuffers transaction side effects and controls their lifecycle.
- TxHooksHandleA TxHooks instance with flush and discard lifecycle methods.
- TxHooksSavepointA savepoint handle with manual rollback/release control.
- ValidatedJobTypeDefinitionsMarker type for compile-time validated job type definitions. Applied by defineJobTypes.
- WorkerA worker: one row in the worker table, live while its lease is.
- WorkerLeaseConfigThe lease the worker runner registers its worker with.
- WorkerRunnerA worker runner that processes jobs in the current process. Created via createWorkerRunner.