feat(storage): expose purge cache for entire bucket

Author: itslenny

packages/core/storage-js/src/packages/StorageFileApi.ts

@@ -1161,7 +1161,7 @@ export default class StorageFileApi extends BaseApiClient<StorageError> {
   }
 
   /**
-   * Purges the CDN cache for a single object in this bucket.
+   * Purges the CDN cache for an entire bucket or single object in this bucket.
    *
    * Maps to `DELETE /cdn/{bucket}/{path}` on the Storage API. The server
    * issues a CDN invalidation for the object and returns `{ message: 'success' }`.
@@ -1174,12 +1174,12 @@ export default class StorageFileApi extends BaseApiClient<StorageError> {
    * have `CDN_PURGE_ENDPOINT_URL` configured and the `purgeCache` tenant
    * feature enabled, otherwise the server returns an error.
    *
-   * Operates on a single object path. There is no wildcard or recursion: pass
-   * the exact path of the object you want invalidated.
+   * Operates on an entire bucket or a single object path. There is no wildcard or recursion: pass
+   * the exact path of the object you want invalidated or none to invalidate the entire bucket.
    *
    * @category Storage
    * @subcategory File Buckets
-   * @param path The path (relative to the bucket) of the object to purge, e.g. `folder/avatar.png`.
+   * @param options Purge options including the object path (relative to the bucket) of the object to purge, e.g. `folder/avatar.png`. Purges cache for the entire bucket if omitted
    * @param parameters Optional fetch parameters such as an `AbortController` signal.
    * @returns Promise with `{ data: { message }, error: null }` on success or `{ data: null, error }` on failure.
    *
@@ -1192,7 +1192,7 @@ export default class StorageFileApi extends BaseApiClient<StorageError> {
    * ```
    */
   async purgeCache(
-    path: string,
+    options?: { object: string },
     parameters?: FetchParameters
   ): Promise<
     | {
@@ -1205,10 +1205,12 @@ export default class StorageFileApi extends BaseApiClient<StorageError> {
       }
   > {
     return this.handleOperation(async () => {
-      const _path = this._getFinalPath(path)
+      const purgePath =
+        options?.object === undefined ? this.bucketId : this._getFinalPath(options.object)
+
       return await remove(
         this.fetch,
-        `${this.url}/cdn/${_path}`,
+        `${this.url}/cdn/${purgePath}`,
         {},
         { headers: this.headers },
         parameters

packages/core/storage-js/test/storageFileApi.test.ts

@@ -1033,7 +1033,7 @@ describe('purgeCache', () => {
     jest.restoreAllMocks()
   })
 
-  it('issues DELETE to /cdn/{bucket}/{path} and returns the server message', async () => {
+  it('issues DELETE to /cdn/{bucket}/{path} for single object purge and returns the server message', async () => {
     const fetchMock = jest.fn().mockResolvedValue(
       new Response(JSON.stringify({ message: 'success' }), {
         status: 200,
@@ -1043,7 +1043,7 @@ describe('purgeCache', () => {
     global.fetch = fetchMock
 
     const client = new StorageClient(PURGE_URL, { apikey: 'service-role-token' })
-    const { data, error } = await client.from(BUCKET).purgeCache(PATH)
+    const { data, error } = await client.from(BUCKET).purgeCache({ object: PATH })
 
     expect(error).toBeNull()
     expect(data?.message).toBe('success')
@@ -1053,6 +1053,46 @@ describe('purgeCache', () => {
     )
   })
 
+  it('issues DELETE to /cdn/{bucket}/{path} EMPTY STRING for single object purge and returns the server message', async () => {
+    const fetchMock = jest.fn().mockResolvedValue(
+      new Response(JSON.stringify({ message: 'success' }), {
+        status: 200,
+        headers: { 'Content-Type': 'application/json' },
+      })
+    )
+    global.fetch = fetchMock
+
+    const client = new StorageClient(PURGE_URL, { apikey: 'service-role-token' })
+    const { data, error } = await client.from(BUCKET).purgeCache({ object: '' })
+
+    expect(error).toBeNull()
+    expect(data?.message).toBe('success')
+    expect(fetchMock).toHaveBeenCalledWith(
+      `${PURGE_URL}/cdn/${BUCKET}/`,
+      expect.objectContaining({ method: 'DELETE' })
+    )
+  })
+
+  it('issues DELETE to /cdn/{bucket} for bucket purge and returns the server message', async () => {
+    const fetchMock = jest.fn().mockResolvedValue(
+      new Response(JSON.stringify({ message: 'success' }), {
+        status: 200,
+        headers: { 'Content-Type': 'application/json' },
+      })
+    )
+    global.fetch = fetchMock
+
+    const client = new StorageClient(PURGE_URL, { apikey: 'service-role-token' })
+    const { data, error } = await client.from(BUCKET).purgeCache()
+
+    expect(error).toBeNull()
+    expect(data?.message).toBe('success')
+    expect(fetchMock).toHaveBeenCalledWith(
+      `${PURGE_URL}/cdn/${BUCKET}`,
+      expect.objectContaining({ method: 'DELETE' })
+    )
+  })
+
   it('surfaces server errors via StorageApiError', async () => {
     const fetchMock = jest
       .fn()
@@ -1065,7 +1105,7 @@ describe('purgeCache', () => {
     global.fetch = fetchMock
 
     const client = new StorageClient(PURGE_URL, { apikey: 'service-role-token' })
-    const { data, error } = await client.from(BUCKET).purgeCache(PATH)
+    const { data, error } = await client.from(BUCKET).purgeCache({ object: PATH })
 
     expect(data).toBeNull()
     expect(error).toBeInstanceOf(StorageApiError)
@@ -1083,7 +1123,9 @@ describe('purgeCache', () => {
 
     const client = new StorageClient(PURGE_URL, { apikey: 'service-role-token' })
     const controller = new AbortController()
-    const { error } = await client.from(BUCKET).purgeCache(PATH, { signal: controller.signal })
+    const { error } = await client
+      .from(BUCKET)
+      .purgeCache({ object: PATH }, { signal: controller.signal })
 
     expect(error).toBeNull()
     expect(fetchMock).toHaveBeenCalledWith(