feat: fluent api for downloading as stream

Author: xxRockOnxx

src/lib/types.ts

@@ -1,3 +1,5 @@
+import { StorageError } from './errors'
+
 export type BucketType = 'STANDARD' | 'ANALYTICS'
 
 export interface Bucket {
@@ -164,3 +166,13 @@ type CamelCase<S extends string> = S extends `${infer P1}_${infer P2}${infer P3}
 export type Camelize<T> = {
   [K in keyof T as CamelCase<Extract<K, string>>]: T[K]
 }
+
+export type DownloadResult<T> =
+  | {
+      data: T
+      error: null
+    }
+  | {
+      data: null
+      error: StorageError
+    }

src/packages/BlobDownloadBuilder.ts

@@ -0,0 +1,39 @@
+import { isStorageError } from '../lib/errors'
+import { DownloadResult } from '../lib/types'
+import StreamDownloadBuilder from './StreamDownloadBuilder'
+
+export default class BlobDownloadBuilder implements PromiseLike<DownloadResult<Blob>> {
+  constructor(private downloadFn: () => Promise<Response>, private shouldThrowOnError: boolean) {}
+
+  asStream(): StreamDownloadBuilder {
+    return new StreamDownloadBuilder(this.downloadFn, this.shouldThrowOnError)
+  }
+
+  then<TResult1 = DownloadResult<Blob>, TResult2 = never>(
+    onfulfilled?: ((value: DownloadResult<Blob>) => TResult1 | PromiseLike<TResult1>) | null,
+    onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null
+  ): Promise<TResult1 | TResult2> {
+    return this.execute().then(onfulfilled, onrejected)
+  }
+
+  private async execute(): Promise<DownloadResult<Blob>> {
+    try {
+      const result = await this.downloadFn()
+
+      return {
+        data: await result.blob(),
+        error: null,
+      }
+    } catch (error) {
+      if (this.shouldThrowOnError) {
+        throw error
+      }
+
+      if (isStorageError(error)) {
+        return { data: null, error }
+      }
+
+      throw error
+    }
+  }
+}

src/packages/StorageFileApi.ts

@@ -13,6 +13,7 @@ import {
   SearchV2Options,
   SearchV2Result,
 } from '../lib/types'
+import BlobDownloadBuilder from './BlobDownloadBuilder'
 
 const DEFAULT_SEARCH_OPTIONS = {
   limit: 100,
@@ -521,52 +522,22 @@ export default class StorageFileApi {
    *
    * @param path The full path and file name of the file to be downloaded. For example `folder/image.png`.
    * @param options.transform Transform the asset before serving it to the client.
-   * @param options.stream If set to true, the response will be a ReadableStream. Otherwise, it will be a Blob (default).
    */
-  async download<Options extends { transform?: TransformOptions, stream?: boolean }>(
+  download<Options extends { transform?: TransformOptions }>(
     path: string,
     options?: Options
-  ): Promise<
-    | {
-        data: Options['stream'] extends true ? ReadableStream : Blob
-        error: null
-      }
-    | {
-        data: null
-        error: StorageError
-      }
-  > {
+  ): BlobDownloadBuilder {
     const wantsTransformation = typeof options?.transform !== 'undefined'
     const renderPath = wantsTransformation ? 'render/image/authenticated' : 'object'
     const transformationQuery = this.transformOptsToQueryString(options?.transform || {})
     const queryString = transformationQuery ? `?${transformationQuery}` : ''
-
-    try {
-      const _path = this._getFinalPath(path)
-      const res = await get(this.fetch, `${this.url}/${renderPath}/${_path}${queryString}`, {
+    const _path = this._getFinalPath(path)
+    const downloadFn = () =>
+      get(this.fetch, `${this.url}/${renderPath}/${_path}${queryString}`, {
         headers: this.headers,
         noResolveJson: true,
       })
-
-      if (!options?.stream) {
-        const data = await res.blob()
-        return { data, error: null }
-      }
-
-      return {
-        data: res.body,
-        error: null,
-      }
-    } catch (error) {
-      if (this.shouldThrowOnError) {
-        throw error
-      }
-      if (isStorageError(error)) {
-        return { data: null, error }
-      }
-
-      throw error
-    }
+    return new BlobDownloadBuilder(downloadFn, this.shouldThrowOnError)
   }
 
   /**

src/packages/StreamDownloadBuilder.ts

@@ -0,0 +1,36 @@
+import { isStorageError } from '../lib/errors'
+import { DownloadResult } from '../lib/types'
+
+export default class StreamDownloadBuilder implements PromiseLike<DownloadResult<ReadableStream>> {
+  constructor(private downloadFn: () => Promise<Response>, private shouldThrowOnError: boolean) {}
+
+  then<TResult1 = DownloadResult<ReadableStream>, TResult2 = never>(
+    onfulfilled?:
+      | ((value: DownloadResult<ReadableStream>) => TResult1 | PromiseLike<TResult1>)
+      | null,
+    onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null
+  ): Promise<TResult1 | TResult2> {
+    return this.execute().then(onfulfilled, onrejected)
+  }
+
+  private async execute(): Promise<DownloadResult<ReadableStream>> {
+    try {
+      const result = await this.downloadFn()
+
+      return {
+        data: result.body as ReadableStream,
+        error: null,
+      }
+    } catch (error) {
+      if (this.shouldThrowOnError) {
+        throw error
+      }
+
+      if (isStorageError(error)) {
+        return { data: null, error }
+      }
+
+      throw error
+    }
+  }
+}

test/storageFileApi.test.ts

@@ -3,9 +3,12 @@ import * as fsp from 'fs/promises'
 import * as fs from 'fs'
 import * as path from 'path'
 import assert from 'assert'
+import ReadableStream from 'node:stream'
 // @ts-ignore
 import fetch, { Response } from '@supabase/node-fetch'
 import { StorageApiError, StorageError } from '../src/lib/errors'
+import BlobDownloadBuilder from '../src/packages/BlobDownloadBuilder'
+import StreamDownloadBuilder from '../src/packages/StreamDownloadBuilder'
 
 // TODO: need to setup storage-api server for this test
 const URL = 'http://localhost:8000/storage/v1'
@@ -408,11 +411,14 @@ describe('Object API', () => {
 
     test('downloads an object', async () => {
       await storage.from(bucketName).upload(uploadPath, file)
-      const res = await storage.from(bucketName).download(uploadPath)
 
-      expect(res.error).toBeNull()
-      expect(res.data?.size).toBeGreaterThan(0)
-      expect(res.data?.type).toEqual('text/plain;charset=utf-8')
+      const blobBuilder = storage.from(bucketName).download(uploadPath)
+      expect(blobBuilder).toBeInstanceOf(BlobDownloadBuilder)
+
+      const blobResponse = await blobBuilder
+      expect(blobResponse.error).toBeNull()
+      expect(blobResponse.data?.size).toBeGreaterThan(0)
+      expect(blobResponse.data?.type).toEqual('text/plain;charset=utf-8')
 
       // throws when .throwOnError is enabled
       await expect(
@@ -422,12 +428,18 @@ describe('Object API', () => {
 
     test('downloads an object as a stream', async () => {
       await storage.from(bucketName).upload(uploadPath, file)
-      const res = await storage.from(bucketName).download(uploadPath, {
-        stream: true,
-      })
 
-      expect(res.error).toBeNull()
-      expect(res.data).toBeInstanceOf(ReadableStream)
+      const streamBuilder = storage.from(bucketName).download(uploadPath).asStream()
+      expect(streamBuilder).toBeInstanceOf(StreamDownloadBuilder)
+
+      const streamResponse = await streamBuilder
+      expect(streamResponse.error).toBeNull()
+      expect(streamResponse.data).toBeInstanceOf(ReadableStream)
+
+      // throws when .throwOnError is enabled
+      await expect(
+        storage.from(bucketName).throwOnError().download('non-existent-file').asStream()
+      ).rejects.toThrow()
     })
 
     test('removes an object', async () => {