Streaming downloads

Use case

Consume a response body incrementally as a ReadableStream rather than buffering the entire response into memory.

Using responseType: 'stream'

parcely supports responseType: 'stream', which returns the un-consumed ReadableStream<Uint8Array> | null as data. The body is NOT read or parsed — you consume it yourself.

import { createClient } from '@parcely/core'

const http = createClient({ baseURL: 'https://api.example.com' })

const { data: stream } = await http.get('/large-file', {
  responseType: 'stream',
})

if (stream) {
  const reader = stream.getReader()
  while (true) {
    const { done, value } = await reader.read()
    if (done) break
    process.stdout.write(value) // or pipe to a file, transform, etc.
  }
}

When responseType: 'stream' is set:

• data is ReadableStream<Uint8Array> | null
• validate is silently skipped (you can't validate bytes before reading them)
• onDownloadProgress still works if set — the stream is wrapped with progress tracking before being returned

Combining with download progress

const { data: stream } = await http.get('/large-file', {
  responseType: 'stream',
  onDownloadProgress: ({ loaded, total, percent }) => {
    console.log(`Downloaded: ${loaded} bytes (${percent ?? '?'}%)`)
  },
})
// stream is progress-wrapped — progress fires as you read from it

Alternative: blob with progress

If you don't need true streaming and just want progress visibility while downloading into memory:

const { data } = await http.get('/large-file', {
  responseType: 'blob',
  onDownloadProgress: ({ loaded, total, percent }) => {
    console.log(`Downloaded: ${loaded} bytes (${percent ?? '?'}%)`)
  },
})
// data is a Blob — fully buffered in memory

Axios equivalent

Axios provides responseType: 'stream' in Node.js, which returns a Node Readable. parcely's 'stream' returns a Web ReadableStream (the platform standard). In Node 20+, Web ReadableStreams are first-class and interoperate with node:stream via Readable.fromWeb().

Notes and gotchas

• The ReadableStream is one-shot — once you read it, it's consumed. If you need to read the body twice, buffer it into a Blob or ArrayBuffer first.
• validate is skipped for stream responses. If you need validation, read the stream into text/JSON yourself and validate manually.
• In browsers, the stream comes from response.body which is universally supported in modern browsers.