# downloadStream

> **downloadStream**(`options`): [`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\<[`ReturnType`](/reference/filoz/synapse-core/piece/namespaces/downloadstream/type-aliases/returntype/)\>

Defined in: [packages/synapse-core/src/piece/download.ts:109](https://github.com/FilOzone/synapse-sdk/blob/5989c4b03ed2fe4cf8b1ef29efe1d4ff1ad4c7bc/packages/synapse-core/src/piece/download.ts#L109)

Download a piece from a URL as a stream, validating its PieceCID as the bytes flow through.

Memory use stays bounded regardless of the piece size, so this is the function to use for
large pieces. The returned promise rejects for request errors (network, HTTP status, null body).
Validation errors surface on the stream itself: every chunk is passed through as it arrives and,
once the body ends, the stream errors with a [DownloadPieceError](/reference/filoz/synapse-core/errors/classes/downloadpieceerror/) instead of closing if the
calculated PieceCID does not match `expectedPieceCid` or the body is empty. A body longer than the
size encoded in `expectedPieceCid` errors as soon as it goes past that size.

Because the error only arrives after the last chunk, consumers that persist data (e.g. to a file)
must treat the bytes as untrusted until the stream closes cleanly, and discard them on error.

Pass `validate: false` to skip validation, in which case `expectedPieceCid` is not needed.

## Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `options` | [`OptionsType`](/reference/filoz/synapse-core/piece/namespaces/downloadstream/type-aliases/optionstype/) | [downloadStream.OptionsType](/reference/filoz/synapse-core/piece/namespaces/downloadstream/type-aliases/optionstype/) |

## Returns

[`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\<[`ReturnType`](/reference/filoz/synapse-core/piece/namespaces/downloadstream/type-aliases/returntype/)\>

A stream of the piece bytes [downloadStream.ReturnType](/reference/filoz/synapse-core/piece/namespaces/downloadstream/type-aliases/returntype/)

## Throws

Errors [downloadStream.ErrorType](/reference/filoz/synapse-core/piece/namespaces/downloadstream/type-aliases/errortype/)

## Example

```ts
import * as Piece from '@filoz/synapse-core/piece'
const stream = await Piece.downloadStream({
  url: 'https://example.com/piece',
  expectedPieceCid: 'bafkzcib...',
})
for await (const chunk of stream) {
  console.log(chunk.length)
}
```