Progress

The progress plugin tracks upload and download progress by automatically switching to XHR transport.

Installation

npm install @spoosh/plugin-progress

Usage

import { Spoosh } from "@spoosh/core";
import { progressPlugin } from "@spoosh/plugin-progress";

const client = new Spoosh<ApiSchema, Error>("/api").use([progressPlugin()]);

Enable progress tracking per-request:

const { data, progress } = useRead((api) => api("files/:id").GET(), {
  progress: true,
});

// progress?.loaded - bytes received
// progress?.total  - total bytes (if known)

File Upload

const { trigger, progress } = useWrite((api) => api("files").POST);

trigger({ body: form({ file: selectedFile }), progress: true });

// progress?.loaded tracks bytes uploaded

Custom Total Header

When the server doesn't set Content-Length (e.g. streaming responses), you can read the total size from a custom header:

useRead((api) => api("files/:id").GET(), {
  progress: { totalHeader: "X-Total-Size" },
});

Per-Request Options

Option	Type	Description
`progress`	`boolean \| ProgressOptions`	Enable progress tracking. Automatically uses XHR transport.

ProgressOptions

Option	Type	Description
`totalHeader`	`string`	Response header to read total size from when `Content-Length` is unavailable

Result

When progress is enabled, the result includes a progress field:

Field	Type	Description
`loaded`	`number`	Bytes transferred so far
`total`	`number`	Total bytes (0 if unknown)