Types

All types are exported from @queuebase/nextjs and @queuebase/node (re-exported from @queuebase/core).

JobStatus

type JobStatus = 'pending' | 'running' | 'completed' | 'failed' | 'cancelled';

BackoffStrategy

type BackoffStrategy = 'linear' | 'exponential';

EnqueueOptions

Options for enqueueing a job. Can be set as defaults on a job definition or passed to .enqueue().

interface EnqueueOptions {
  delay?: string | number;
  retries?: number;
  backoff?: BackoffStrategy;
  backoffDelay?: number;
}

Field	Type	Description
delay	string | number	Delay before running. Strings: '5s', '5m', '1h', '2d'. Numbers: milliseconds.
retries	number	Number of retry attempts on failure.
backoff	BackoffStrategy	Backoff strategy for retries.
backoffDelay	number	Base delay between retries in ms (default: 1000).

ScheduleInput

Schedule configuration for a job. Only available on jobs with an empty input schema.

type ScheduleInput = string | ScheduleConfig;

When a string, it can be a plain English expression ("every day at 9am") or a raw cron expression ("0 9 * * *").

ScheduleConfig

Full schedule configuration object.

interface ScheduleConfig {
  cron: string;
  timezone?: string;
  enabled?: boolean;
  overlap?: OverlapPolicy;
}

Field	Type	Description	Default
cron	string	Cron expression or plain English string	(required)
timezone	string	IANA timezone	'UTC'
enabled	boolean	Whether the schedule is active	true
overlap	OverlapPolicy	Behavior when previous run is still executing	'skip'

OverlapPolicy

type OverlapPolicy = 'skip' | 'allow';

ResolvedSchedule

Internal normalized form of a schedule after parsing and validation.

interface ResolvedSchedule {
  cronExpression: string;
  timezone: string;
  enabled: boolean;
  overlap: OverlapPolicy;
}

JobDefinition<TInput, TOutput>

A job definition with typed input and output.

interface JobDefinition<TInput = unknown, TOutput = unknown> {
  input: StandardSchemaV1<TInput>;
  handler: (ctx: JobContext<TInput>) => Promise<TOutput>;
  defaults?: EnqueueOptions;
  config?: JobTypeConfig;
  schedule?: ScheduleInput; // only when TInput is Record<string, never>
}

The input field accepts any Standard Schema-compatible validator (Zod, Valibot, ArkType, etc.).

JobTypeConfig

Per-job-type configuration for timeout and concurrency.

interface JobTypeConfig {
  timeout?: string | number;
  concurrency?: number;
}

Field	Type	Description
timeout	string | number	Max execution time ('5m', '30s', or milliseconds)
concurrency	number	Max concurrent executions of this job type per worker

JobContext<TInput>

Context passed to job handlers.

interface JobContext<TInput = unknown> {
  input: TInput;
  jobId: string;
  attempt: number;
  maxAttempts: number;
  fail: (reason: string) => never;
}

Field	Type	Description
input	TInput	Validated input data
jobId	string	Unique job ID
attempt	number	Current attempt (1-indexed)
maxAttempts	number	Maximum attempts allowed
fail	(reason: string) => never	Explicitly mark the job as failed. See Defining Jobs.

EnqueueResult

Returned from .enqueue().

interface EnqueueResult {
  jobId: string;
  getStatus: () => Promise<JobStatusResponse>;
}

JobStatusResponse

Job status as returned by the API.

interface JobStatusResponse {
  publicId: string;
  name: string;
  status: JobStatus;
  attempt: number;
  maxAttempts: number;
  createdAt: string;
  startedAt: string | null;
  completedAt: string | null;
  result: unknown;
  error: string | null;
}

JobResult<TOutput>

Result of a job execution.

interface JobResult<TOutput = unknown> {
  success: boolean;
  output?: TOutput;
  error?: string;
  duration: number;
}

QueuebaseConfig

Configuration for Queuebase.

interface QueuebaseConfig {
  jobsDir: string;
  callbackUrl?: string;
  apiKey?: string;
  apiUrl?: string;
}