feat: custom-metadata, exists, info methods (#207)

Author: fenos

infra/storage/Dockerfile

@@ -1,3 +1,3 @@
-FROM supabase/storage-api:v1.2.1
+FROM supabase/storage-api:v1.8.2
 
 RUN apk add curl --no-cache

src/lib/fetch.ts

@@ -11,15 +11,19 @@ export interface FetchOptions {
   noResolveJson?: boolean
 }
 
-export type RequestMethodType = 'GET' | 'POST' | 'PUT' | 'DELETE'
+export type RequestMethodType = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'HEAD'
 
 const _getErrorMessage = (err: any): string =>
   err.msg || err.message || err.error_description || err.error || JSON.stringify(err)
 
-const handleError = async (error: unknown, reject: (reason?: any) => void) => {
+const handleError = async (
+  error: unknown,
+  reject: (reason?: any) => void,
+  options?: FetchOptions
+) => {
   const Res = await resolveResponse()
 
-  if (error instanceof Res) {
+  if (error instanceof Res && !options?.noResolveJson) {
     error
       .json()
       .then((err) => {
@@ -46,7 +50,10 @@ const _getRequestParams = (
   }
 
   params.headers = { 'Content-Type': 'application/json', ...options?.headers }
-  params.body = JSON.stringify(body)
+
+  if (body) {
+    params.body = JSON.stringify(body)
+  }
   return { ...params, ...parameters }
 }
 
@@ -66,7 +73,7 @@ async function _handleRequest(
         return result.json()
       })
       .then((data) => resolve(data))
-      .catch((error) => handleError(error, reject))
+      .catch((error) => handleError(error, reject, options))
   })
 }
 
@@ -99,6 +106,24 @@ export async function put(
   return _handleRequest(fetcher, 'PUT', url, options, parameters, body)
 }
 
+export async function head(
+  fetcher: Fetch,
+  url: string,
+  options?: FetchOptions,
+  parameters?: FetchParameters
+): Promise<any> {
+  return _handleRequest(
+    fetcher,
+    'HEAD',
+    url,
+    {
+      ...options,
+      noResolveJson: true,
+    },
+    parameters
+  )
+}
+
 export async function remove(
   fetcher: Fetch,
   url: string,

src/lib/helpers.ts

@@ -21,3 +21,19 @@ export const resolveResponse = async (): Promise<typeof Response> => {
 
   return Response
 }
+
+export const recursiveToCamel = (item: Record<string, any>): unknown => {
+  if (Array.isArray(item)) {
+    return item.map((el) => recursiveToCamel(el))
+  } else if (typeof item === 'function' || item !== Object(item)) {
+    return item
+  }
+
+  const result: Record<string, any> = {}
+  Object.entries(item).forEach(([key, value]) => {
+    const newKey = key.replace(/([-_][a-z])/gi, (c) => c.toUpperCase().replace(/[-_]/g, ''))
+    result[newKey] = recursiveToCamel(value)
+  })
+
+  return result
+}

src/lib/types.ts

@@ -21,6 +21,22 @@ export interface FileObject {
   buckets: Bucket
 }
 
+export interface FileObjectV2 {
+  id: string
+  version: string
+  name: string
+  bucket_id: string
+  updated_at: string
+  created_at: string
+  last_accessed_at: string
+  size?: number
+  cache_control?: string
+  content_type?: string
+  etag?: string
+  last_modified?: string
+  metadata?: Record<string, any>
+}
+
 export interface SortBy {
   column?: string
   order?: string
@@ -43,6 +59,16 @@ export interface FileOptions {
    * The duplex option is a string parameter that enables or disables duplex streaming, allowing for both reading and writing data in the same stream. It can be passed as an option to the fetch() method.
    */
   duplex?: string
+
+  /**
+   * The metadata option is an object that allows you to store additional information about the file. This information can be used to filter and search for files. The metadata object can contain any key-value pairs you want to store.
+   */
+  metadata?: Record<string, any>
+
+  /**
+   * Optionally add extra headers
+   */
+  headers?: Record<string, string>
 }
 
 export interface DestinationOptions {
@@ -113,3 +139,11 @@ export interface TransformOptions {
    */
   format?: 'origin'
 }
+
+type CamelCase<S extends string> = S extends `${infer P1}_${infer P2}${infer P3}`
+  ? `${Lowercase<P1>}${Uppercase<P2>}${CamelCase<P3>}`
+  : S
+
+export type Camelize<T> = {
+  [K in keyof T as CamelCase<Extract<K, string>>]: T[K]
+}

src/packages/StorageFileApi.ts

@@ -1,13 +1,15 @@
-import { isStorageError, StorageError } from '../lib/errors'
-import { Fetch, get, post, remove } from '../lib/fetch'
-import { resolveFetch } from '../lib/helpers'
+import { isStorageError, StorageError, StorageUnknownError } from '../lib/errors'
+import { Fetch, get, head, post, remove } from '../lib/fetch'
+import { recursiveToCamel, resolveFetch } from '../lib/helpers'
 import {
   FileObject,
   FileOptions,
   SearchOptions,
   FetchParameters,
   TransformOptions,
   DestinationOptions,
+  FileObjectV2,
+  Camelize,
 } from '../lib/types'
 
 const DEFAULT_SEARCH_OPTIONS = {
@@ -80,22 +82,39 @@ export default class StorageFileApi {
     try {
       let body
       const options = { ...DEFAULT_FILE_OPTIONS, ...fileOptions }
-      const headers: Record<string, string> = {
+      let headers: Record<string, string> = {
         ...this.headers,
         ...(method === 'POST' && { 'x-upsert': String(options.upsert as boolean) }),
       }
 
+      const metadata = options.metadata
+
       if (typeof Blob !== 'undefined' && fileBody instanceof Blob) {
         body = new FormData()
         body.append('cacheControl', options.cacheControl as string)
         body.append('', fileBody)
+
+        if (metadata) {
+          body.append('metadata', this.encodeMetadata(metadata))
+        }
       } else if (typeof FormData !== 'undefined' && fileBody instanceof FormData) {
         body = fileBody
         body.append('cacheControl', options.cacheControl as string)
+        if (metadata) {
+          body.append('metadata', this.encodeMetadata(metadata))
+        }
       } else {
         body = fileBody
         headers['cache-control'] = `max-age=${options.cacheControl}`
         headers['content-type'] = options.contentType as string
+
+        if (metadata) {
+          headers['x-metadata'] = this.toBase64(this.encodeMetadata(metadata))
+        }
+      }
+
+      if (fileOptions?.headers) {
+        headers = { ...headers, ...fileOptions.headers }
       }
 
       const cleanPath = this._removeEmptyFolders(path)
@@ -525,6 +544,76 @@ export default class StorageFileApi {
     }
   }
 
+  /**
+   * Retrieves the details of an existing file.
+   * @param path
+   */
+  async info(
+    path: string
+  ): Promise<
+    | {
+        data: Camelize<FileObjectV2>
+        error: null
+      }
+    | {
+        data: null
+        error: StorageError
+      }
+  > {
+    const _path = this._getFinalPath(path)
+
+    try {
+      const data = await get(this.fetch, `${this.url}/object/info/${_path}`, {
+        headers: this.headers,
+      })
+
+      return { data: recursiveToCamel(data) as Camelize<FileObjectV2>, error: null }
+    } catch (error) {
+      if (isStorageError(error)) {
+        return { data: null, error }
+      }
+
+      throw error
+    }
+  }
+
+  /**
+   * Checks the existence of a file.
+   * @param path
+   */
+  async exists(
+    path: string
+  ): Promise<
+    | {
+        data: boolean
+        error: null
+      }
+    | {
+        data: boolean
+        error: StorageError
+      }
+  > {
+    const _path = this._getFinalPath(path)
+
+    try {
+      await head(this.fetch, `${this.url}/object/${_path}`, {
+        headers: this.headers,
+      })
+
+      return { data: true, error: null }
+    } catch (error) {
+      if (isStorageError(error) && error instanceof StorageUnknownError) {
+        const originalError = (error.originalError as unknown) as { status: number }
+
+        if ([400, 404].includes(originalError?.status)) {
+          return { data: false, error }
+        }
+      }
+
+      throw error
+    }
+  }
+
   /**
    * A simple convenience function to get the URL for an asset in a public bucket. If you do not want to use this function, you can construct the public URL by concatenating the bucket URL with the path to the asset.
    * This function does not verify if the bucket is public. If a public URL is created for a bucket which is not public, you will not be able to download the asset.
@@ -700,6 +789,17 @@ export default class StorageFileApi {
     }
   }
 
+  protected encodeMetadata(metadata: Record<string, any>) {
+    return JSON.stringify(metadata)
+  }
+
+  toBase64(data: string) {
+    if (typeof Buffer !== 'undefined') {
+      return Buffer.from(data).toString('base64')
+    }
+    return btoa(data)
+  }
+
   private _getFinalPath(path: string) {
     return `${this.bucketId}/${path}`
   }

test/storageFileApi.test.ts

@@ -163,6 +163,25 @@ describe('Object API', () => {
       expect(updateRes.data?.path).toEqual(uploadPath)
     })
 
+    test('can upload with custom metadata', async () => {
+      const res = await storage.from(bucketName).upload(uploadPath, file, {
+        metadata: {
+          custom: 'metadata',
+          second: 'second',
+          third: 'third',
+        },
+      })
+      expect(res.error).toBeNull()
+
+      const updateRes = await storage.from(bucketName).info(uploadPath)
+      expect(updateRes.error).toBeNull()
+      expect(updateRes.data?.metadata).toEqual({
+        custom: 'metadata',
+        second: 'second',
+        third: 'third',
+      })
+    })
+
     test('can upload a file within the file size limit', async () => {
       const bucketName = 'with-limit' + Date.now()
       await storage.createBucket(bucketName, {
@@ -368,6 +387,38 @@ describe('Object API', () => {
         }),
       ])
     })
+
+    test('get object info', async () => {
+      await storage.from(bucketName).upload(uploadPath, file)
+      const res = await storage.from(bucketName).info(uploadPath)
+
+      expect(res.error).toBeNull()
+      expect(res.data).toEqual(
+        expect.objectContaining({
+          id: expect.any(String),
+          name: expect.any(String),
+          createdAt: expect.any(String),
+          cacheControl: expect.any(String),
+          size: expect.any(Number),
+          etag: expect.any(String),
+          lastModified: expect.any(String),
+          contentType: expect.any(String),
+          metadata: {},
+          version: expect.any(String),
+        })
+      )
+    })
+
+    test('check if object exists', async () => {
+      await storage.from(bucketName).upload(uploadPath, file)
+      const res = await storage.from(bucketName).exists(uploadPath)
+
+      expect(res.error).toBeNull()
+      expect(res.data).toEqual(true)
+
+      const resNotExists = await storage.from(bucketName).exists('do-not-exists')
+      expect(resNotExists.data).toEqual(false)
+    })
   })
 
   describe('Transformations', () => {