Add support to REST client for getting binary data

[scerdal]

Environment

Node version: 20.12.2 Npm version: 10.5.0 OS and version: MacOS 14.2.1 typed-rest-client version: 2.0.0

Issue Description

Some REST API endpoints that we are working with return binary data from GET requests, but the REST client does not provide a way to access the response stream.

I'm aware that a similar issue was opened for receiving binary data through the HTTP client, however the workaround is not applicable to the REST client since the REST client methods do not return the raw http.IncomingMessage. Doing it directly through the HTTP client as in the above issue is not convenient, since we then have to duplicate logic that is handled in the REST client.

Expected behaviour

Ideally there would be a way to retrieve the response stream in the IRestResponse interface, something like:

export interface IRestResponse<T> {
    statusCode?: number;
    result: T | null;
    headers: object;
    responseStream?: NodeJS.ReadableStream; // Defined if the responseAsStream request option is true
}

and correspondingly there is a responseAsStream option that we can pass in the IRequestOptions:

export interface IRequestOptions {
    // defaults to application/json
    // common versioning is application/json;version=2.1
    acceptHeader?: string;
    // since accept is defaulted, set additional headers if needed
    additionalHeaders?: ifm.IHeaders;

    responseProcessor?: any;
    responseAsStream?: boolean; // Return response as a ReadableStream for binary data
    //Dates aren't automatically deserialized by JSON, this adds a date reviver to ensure they aren't just left as strings
    deserializeDates?: boolean;
    queryParameters?: ifm.IRequestQueryParams;
}

I already have a working example with these additions, so if this feature looks reasonable I can create a PR for it as well.

Actual behaviour

Steps to reproduce

Logs

[ivanduplenskikh]

@scerdal, thank you for working on it. After conducting some research, I found that REST modules typically do not include methods to utilize stream responses. Could you provide more details about your issue? Do you need to consume JSON from a stream response?

[scerdal]

Hey @ivanduplenskikh, thank you for looking into this. The API that we're working with serves files, so we need the REST client to expose the binary data somehow, or just expose the raw response stream.

[scerdal]

@ivanduplenskikh any updates on this?

[ivanduplenskikh]

@scerdal, could you please create a PR with your working example that exposes binary data/response stream? We would appreciate your contribution and will review it.

[scerdal]

@ivanduplenskikh just opened a PR for this issue. Let me know if the PR is missing anything

[ivanduplenskikh]

@scerdal, thanks for contribution! Let us take a look.

[scerdal]

@ivanduplenskikh any updates on this?

[ivanduplenskikh]

@scerdal, I've reviewed it, and it looks good to me. Currently, I'm awaiting feedback from colleagues.