refactor: allow download as stream (#137)

* refactor: allow download as stream

* feat: fluent api for downloading as stream

* test: stream download error cases

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,
@@ -522,42 +523,21 @@ 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.
    */
-  async download(
+  download<Options extends { transform?: TransformOptions }>(
     path: string,
-    options?: { transform?: TransformOptions }
-  ): Promise<
-    | {
-        data: Blob
-        error: null
-      }
-    | {
-        data: null
-        error: StorageError
-      }
-  > {
+    options?: Options
+  ): 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,
       })
-      const data = await res.blob()
-      return { data, 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,18 +411,37 @@ 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(
         storage.from(bucketName).throwOnError().download('non-existent-file')
       ).rejects.toThrow()
     })
 
+    test('downloads an object as a stream', async () => {
+      await storage.from(bucketName).upload(uploadPath, file)
+
+      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 () => {
       await storage.from(bucketName).upload(uploadPath, file)
       const res = await storage.from(bucketName).remove([uploadPath])

test/storageFileApiErrorHandling.test.ts

@@ -25,10 +25,15 @@ describe('File API Error Handling', () => {
       global.fetch = jest.fn().mockImplementation(() => Promise.reject(mockError))
       const storage = new StorageClient(URL, { apikey: KEY })
 
-      const { data, error } = await storage.from(BUCKET_ID).download('test.jpg')
-      expect(data).toBeNull()
-      expect(error).not.toBeNull()
-      expect(error?.message).toBe('Network failure')
+      const blobDownload = await storage.from(BUCKET_ID).download('test.jpg')
+      expect(blobDownload.data).toBeNull()
+      expect(blobDownload.error).not.toBeNull()
+      expect(blobDownload.error?.message).toBe('Network failure')
+
+      const streamDownload = await storage.from(BUCKET_ID).download('test.jpg').asStream()
+      expect(streamDownload.data).toBeNull()
+      expect(streamDownload.error).not.toBeNull()
+      expect(streamDownload.error?.message).toBe('Network failure')
     })
 
     it('wraps non-Response errors as StorageUnknownError', async () => {
@@ -37,18 +42,23 @@ describe('File API Error Handling', () => {
 
       const storage = new StorageClient(URL, { apikey: KEY })
 
-      const { data, error } = await storage.from(BUCKET_ID).download('test.jpg')
-      expect(data).toBeNull()
-      expect(error).toBeInstanceOf(StorageUnknownError)
-      expect(error?.message).toBe('Invalid download format')
+      const blobDownload = await storage.from(BUCKET_ID).download('test.jpg')
+      expect(blobDownload.data).toBeNull()
+      expect(blobDownload.error).toBeInstanceOf(StorageUnknownError)
+      expect(blobDownload.error?.message).toBe('Invalid download format')
+
+      const streamDownload = await storage.from(BUCKET_ID).download('test.jpg').asStream()
+      expect(streamDownload.data).toBeNull()
+      expect(streamDownload.error).toBeInstanceOf(StorageUnknownError)
+      expect(streamDownload.error?.message).toBe('Invalid download format')
     })
 
     it('throws non-StorageError exceptions', async () => {
       // Create a storage client
       const storage = new StorageClient(URL, { apikey: KEY })
 
       // Create a spy on the fetch method that will throw a non-StorageError
-      const mockFn = jest.spyOn(global, 'fetch').mockImplementationOnce(() => {
+      const mockFn = jest.spyOn(global, 'fetch').mockImplementation(() => {
         const error = new Error('Unexpected error in download')
         Object.defineProperty(error, 'name', { value: 'CustomError' })
         throw error
@@ -58,6 +68,10 @@ describe('File API Error Handling', () => {
         'Unexpected error in download'
       )
 
+      await expect(storage.from(BUCKET_ID).download('test.jpg').asStream()).rejects.toThrow(
+        'Unexpected error in download'
+      )
+
       mockFn.mockRestore()
     })
   })