Background Jobs

@granit/background-jobs provides framework-agnostic types for background job monitoring — mirroring Granit.BackgroundJobs on the .NET backend. @granit/react-background-jobs wraps these into React hooks with TanStack Query integration: auto-polling job status every 15 seconds, plus pause/resume/trigger mutations.

Peer dependencies: axios, react ^19, @tanstack/react-query ^5

Package structure

Directory@granit/background-jobs/ Job status type (framework-agnostic)
- @granit/react-background-jobs Query/mutation hooks for job monitoring

Package	Role	Depends on
`@granit/background-jobs`	`BackgroundJobStatus` type definition	—
`@granit/react-background-jobs`	`useBackgroundJobs`, `usePauseJob`, `useResumeJob`, `useTriggerJob`	`@granit/background-jobs`, `@tanstack/react-query`, `axios`, `react`

import { useBackgroundJobs, usePauseJob, useResumeJob, useTriggerJob } from '@granit/react-background-jobs';
import { api } from './api-client';

function JobDashboard() {
  const { data: jobs, isLoading } = useBackgroundJobs({ client: api });
  const { mutate: pause } = usePauseJob({ client: api });
  const { mutate: resume } = useResumeJob({ client: api });
  const { mutate: trigger } = useTriggerJob({ client: api });

  // Render job list with action buttons...
}

import type { BackgroundJobStatus } from '@granit/background-jobs';

TypeScript SDK

Types

interface BackgroundJobStatus {
  readonly jobName: string;
  readonly cronExpression: string;
  readonly isEnabled: boolean;
  readonly lastExecutedAt: string | null;
  readonly nextExecutionAt: string | null;
  readonly consecutiveFailures: number;
  readonly deadLetterCount: number;
  readonly lastError: string | null;
}

REST endpoints

Method	Endpoint	Description
`GET`	`/background-jobs`	List all jobs with current status
`POST`	`/background-jobs/{jobName}/pause`	Pause a job
`POST`	`/background-jobs/{jobName}/resume`	Resume a paused job
`POST`	`/background-jobs/{jobName}/trigger`	Manually trigger a job

React bindings

Options

All hooks accept the same options object:

interface BackgroundJobsOptions {
  readonly client: AxiosInstance;
  readonly basePath?: string;    // default: '/api/v1/background-jobs'
}

`useBackgroundJobs(options)`

Fetches all background jobs with 15-second auto-polling.

function useBackgroundJobs(
  options: BackgroundJobsOptions
): UseQueryResult<readonly BackgroundJobStatus[]>;

`usePauseJob(options)`

Pauses a job by name. Invalidates the job list on success.

function usePauseJob(
  options: BackgroundJobsOptions
): UseMutationResult<void, Error, string>;

`useResumeJob(options)`

Resumes a paused job by name. Invalidates the job list on success.

function useResumeJob(
  options: BackgroundJobsOptions
): UseMutationResult<void, Error, string>;

`useTriggerJob(options)`

Manually triggers a job by name. Invalidates the job list on success.

function useTriggerJob(
  options: BackgroundJobsOptions
): UseMutationResult<void, Error, string>;

Query keys

const backgroundJobKeys = {
  all: ['background-jobs'] as const,
  list: () => [...backgroundJobKeys.all, 'list'] as const,
  job: (name: string) => [...backgroundJobKeys.all, 'job', name] as const,
};

Public API summary

Category	Key exports	Package
Types	`BackgroundJobStatus`	`@granit/background-jobs`
Query hook	`useBackgroundJobs()`	`@granit/react-background-jobs`
Mutations	`usePauseJob()`, `useResumeJob()`, `useTriggerJob()`	`@granit/react-background-jobs`
Cache keys	`backgroundJobKeys`	`@granit/react-background-jobs`