feat: add getMetadata method (#90)

Author: eduardoboucas

README.md

@@ -233,6 +233,22 @@ if (fresh) {
 }
 ```
 
+### `getMetadata(key: string, { etag?: string, type?: string }): Promise<{ data: any, etag: string, metadata: object }>`
+
+Retrieves any metadata associated with a given key and its
+[ETag value](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/ETag).
+
+If an object with the given key is not found, `null` is returned.
+
+This method can be used to check whether a key exists without having to actually retrieve it and transfer a
+potentially-large blob.
+
+```javascript
+const blob = await store.getMetadata('some-key')
+
+console.log(blob.etag, blob.metadata)
+```
+
 ### `set(key: string, value: ArrayBuffer | Blob | ReadableStream | string, { metadata?: object }): Promise<void>`
 
 Creates an object with the given key and value.

src/client.ts

@@ -84,6 +84,8 @@ export class Client {
 
     url.searchParams.set('context', storeName)
 
+    // If there is no key, we're dealing with the list endpoint, which is
+    // implemented directly in the Netlify API.
     if (key === undefined) {
       return {
         headers: apiHeaders,
@@ -97,6 +99,14 @@ export class Client {
       apiHeaders[METADATA_HEADER_EXTERNAL] = encodedMetadata
     }
 
+    // HEAD requests are implemented directly in the Netlify API.
+    if (method === HTTPMethod.HEAD) {
+      return {
+        headers: apiHeaders,
+        url: url.toString(),
+      }
+    }
+
     const res = await this.fetch(url.toString(), { headers: apiHeaders, method })
 
     if (res.status !== 200) {

src/main.test.ts

@@ -346,6 +346,120 @@ describe('get', () => {
   })
 })
 
+describe('getMetadata', () => {
+  describe('With API credentials', () => {
+    test('Reads from the blob store and returns the etag and the metadata object', async () => {
+      const mockMetadata = {
+        name: 'Netlify',
+        cool: true,
+        functions: ['edge', 'serverless'],
+      }
+      const headers = {
+        etag: '123456789',
+        'x-amz-meta-user': `b64;${base64Encode(mockMetadata)}`,
+      }
+      const mockStore = new MockFetch().head({
+        headers: { authorization: `Bearer ${apiToken}` },
+        response: new Response(null, { headers }),
+        url: `https://api.netlify.com/api/v1/sites/${siteID}/blobs/${key}?context=production`,
+      })
+
+      globalThis.fetch = mockStore.fetch
+
+      const blobs = getStore({
+        name: 'production',
+        token: apiToken,
+        siteID,
+      })
+
+      const entry = await blobs.getMetadata(key)
+      expect(entry?.etag).toBe(headers.etag)
+      expect(entry?.metadata).toEqual(mockMetadata)
+
+      expect(mockStore.fulfilled).toBeTruthy()
+    })
+
+    test('Returns `null` when the API returns a 404', async () => {
+      const mockStore = new MockFetch().head({
+        headers: { authorization: `Bearer ${apiToken}` },
+        response: new Response(null, { status: 404 }),
+        url: `https://api.netlify.com/api/v1/sites/${siteID}/blobs/${key}?context=production`,
+      })
+
+      globalThis.fetch = mockStore.fetch
+
+      const blobs = getStore({
+        name: 'production',
+        token: apiToken,
+        siteID,
+      })
+
+      expect(await blobs.getMetadata(key)).toBeNull()
+      expect(mockStore.fulfilled).toBeTruthy()
+    })
+
+    test('Throws when the metadata object cannot be parsed', async () => {
+      const headers = {
+        etag: '123456789',
+        'x-amz-meta-user': `b64;${base64Encode(`{"name": "Netlify", "cool`)}`,
+      }
+      const mockStore = new MockFetch().head({
+        headers: { authorization: `Bearer ${apiToken}` },
+        response: new Response(null, { headers }),
+        url: `https://api.netlify.com/api/v1/sites/${siteID}/blobs/${key}?context=production`,
+      })
+
+      globalThis.fetch = mockStore.fetch
+
+      const blobs = getStore({
+        name: 'production',
+        token: apiToken,
+        siteID,
+      })
+
+      await expect(async () => await blobs.getMetadata(key)).rejects.toThrowError(
+        'An internal error occurred while trying to retrieve the metadata for an entry. Please try updating to the latest version of the Netlify Blobs client.',
+      )
+
+      expect(mockStore.fulfilled).toBeTruthy()
+    })
+  })
+
+  describe('With edge credentials', () => {
+    test('Reads from the blob store and returns the etag and the metadata object', async () => {
+      const mockMetadata = {
+        name: 'Netlify',
+        cool: true,
+        functions: ['edge', 'serverless'],
+      }
+      const headers = {
+        etag: '123456789',
+        'x-amz-meta-user': `b64;${base64Encode(mockMetadata)}`,
+      }
+      const mockStore = new MockFetch().head({
+        headers: { authorization: `Bearer ${edgeToken}` },
+        response: new Response(null, { headers }),
+        url: `${edgeURL}/${siteID}/production/${key}`,
+      })
+
+      globalThis.fetch = mockStore.fetch
+
+      const blobs = getStore({
+        edgeURL,
+        name: 'production',
+        token: edgeToken,
+        siteID,
+      })
+
+      const entry = await blobs.getMetadata(key)
+      expect(entry?.etag).toBe(headers.etag)
+      expect(entry?.metadata).toEqual(mockMetadata)
+
+      expect(mockStore.fulfilled).toBeTruthy()
+    })
+  })
+})
+
 describe('getWithMetadata', () => {
   describe('With API credentials', () => {
     test('Reads from the blob store and returns the etag and the metadata object', async () => {
@@ -387,14 +501,14 @@ describe('getWithMetadata', () => {
       })
 
       const entry1 = await blobs.getWithMetadata(key)
-      expect(entry1.data).toBe(value)
-      expect(entry1.etag).toBe(responseHeaders.etag)
-      expect(entry1.metadata).toEqual(mockMetadata)
+      expect(entry1?.data).toBe(value)
+      expect(entry1?.etag).toBe(responseHeaders.etag)
+      expect(entry1?.metadata).toEqual(mockMetadata)
 
       const entry2 = await blobs.getWithMetadata(key, { type: 'stream' })
-      expect(await streamToString(entry2.data as unknown as NodeJS.ReadableStream)).toBe(value)
-      expect(entry2.etag).toBe(responseHeaders.etag)
-      expect(entry2.metadata).toEqual(mockMetadata)
+      expect(await streamToString(entry2?.data as unknown as NodeJS.ReadableStream)).toBe(value)
+      expect(entry2?.etag).toBe(responseHeaders.etag)
+      expect(entry2?.metadata).toEqual(mockMetadata)
 
       expect(mockStore.fulfilled).toBeTruthy()
     })
@@ -495,16 +609,16 @@ describe('getWithMetadata', () => {
       })
 
       const staleEntry = await blobs.getWithMetadata(key, { etag: etags[0] })
-      expect(staleEntry.data).toBe(value)
-      expect(staleEntry.etag).toBe(etags[0])
-      expect(staleEntry.fresh).toBe(false)
-      expect(staleEntry.metadata).toEqual(mockMetadata)
+      expect(staleEntry?.data).toBe(value)
+      expect(staleEntry?.etag).toBe(etags[0])
+      expect(staleEntry?.fresh).toBe(false)
+      expect(staleEntry?.metadata).toEqual(mockMetadata)
 
       const freshEntry = await blobs.getWithMetadata(key, { etag: etags[1], type: 'text' })
-      expect(freshEntry.data).toBe(null)
-      expect(freshEntry.etag).toBe(etags[0])
-      expect(freshEntry.fresh).toBe(true)
-      expect(freshEntry.metadata).toEqual(mockMetadata)
+      expect(freshEntry?.data).toBe(null)
+      expect(freshEntry?.etag).toBe(etags[0])
+      expect(freshEntry?.fresh).toBe(true)
+      expect(freshEntry?.metadata).toEqual(mockMetadata)
 
       expect(mockStore.fulfilled).toBeTruthy()
     })
@@ -543,14 +657,14 @@ describe('getWithMetadata', () => {
       })
 
       const entry1 = await blobs.getWithMetadata(key)
-      expect(entry1.data).toBe(value)
-      expect(entry1.etag).toBe(responseHeaders.etag)
-      expect(entry1.metadata).toEqual(mockMetadata)
+      expect(entry1?.data).toBe(value)
+      expect(entry1?.etag).toBe(responseHeaders.etag)
+      expect(entry1?.metadata).toEqual(mockMetadata)
 
       const entry2 = await blobs.getWithMetadata(key, { type: 'stream' })
-      expect(await streamToString(entry2.data as unknown as NodeJS.ReadableStream)).toBe(value)
-      expect(entry2.etag).toBe(responseHeaders.etag)
-      expect(entry2.metadata).toEqual(mockMetadata)
+      expect(await streamToString(entry2?.data as unknown as NodeJS.ReadableStream)).toBe(value)
+      expect(entry2?.etag).toBe(responseHeaders.etag)
+      expect(entry2?.metadata).toEqual(mockMetadata)
 
       expect(mockStore.fulfilled).toBeTruthy()
     })

src/metadata.ts

@@ -33,3 +33,17 @@ export const decodeMetadata = (header: string | null): Metadata => {
 
   return metadata
 }
+
+export const getMetadataFromResponse = (response: Response) => {
+  if (!response.headers) {
+    return {}
+  }
+
+  try {
+    return decodeMetadata(response.headers.get(METADATA_HEADER_INTERNAL))
+  } catch {
+    throw new Error(
+      'An internal error occurred while trying to retrieve the metadata for an entry. Please try updating to the latest version of the Netlify Blobs client.',
+    )
+  }
+}

src/server.test.ts

@@ -62,7 +62,7 @@ test('Reads and writes from the file system', async () => {
   expect(await blobs.get('parent')).toBe(null)
 
   const entry = await blobs.getWithMetadata('simple-key')
-  expect(entry.metadata).toEqual(metadata)
+  expect(entry?.metadata).toEqual(metadata)
 
   await blobs.delete('simple-key')
   expect(await blobs.get('simple-key')).toBe(null)

src/store.ts

@@ -2,7 +2,7 @@ import { Buffer } from 'node:buffer'
 
 import { ListResponse, ListResponseBlob } from './backend/list.ts'
 import { Client } from './client.ts'
-import { decodeMetadata, Metadata, METADATA_HEADER_INTERNAL } from './metadata.ts'
+import { getMetadataFromResponse, Metadata } from './metadata.ts'
 import { BlobInput, HTTPMethod } from './types.ts'
 import { BlobsInternalError } from './util.ts'
 
@@ -131,10 +131,31 @@ export class Store {
     throw new BlobsInternalError(res.status)
   }
 
+  async getMetadata(key: string) {
+    const res = await this.client.makeRequest({ key, method: HTTPMethod.HEAD, storeName: this.name })
+
+    if (res.status === 404) {
+      return null
+    }
+
+    if (res.status !== 200 && res.status !== 304) {
+      throw new BlobsInternalError(res.status)
+    }
+
+    const etag = res?.headers.get('etag') ?? undefined
+    const metadata = getMetadataFromResponse(res)
+    const result = {
+      etag,
+      metadata,
+    }
+
+    return result
+  }
+
   async getWithMetadata(
     key: string,
     options?: GetWithMetadataOptions,
-  ): Promise<{ data: string } & GetWithMetadataResult>
+  ): Promise<({ data: string } & GetWithMetadataResult) | null>
 
   async getWithMetadata(
     key: string,
@@ -144,26 +165,26 @@ export class Store {
   async getWithMetadata(
     key: string,
     options: { type: 'blob' } & GetWithMetadataOptions,
-  ): Promise<{ data: Blob } & GetWithMetadataResult>
+  ): Promise<({ data: Blob } & GetWithMetadataResult) | null>
 
   /* eslint-disable @typescript-eslint/no-explicit-any */
 
   async getWithMetadata(
     key: string,
     options: { type: 'json' } & GetWithMetadataOptions,
-  ): Promise<{ data: any } & GetWithMetadataResult>
+  ): Promise<({ data: any } & GetWithMetadataResult) | null>
 
   /* eslint-enable @typescript-eslint/no-explicit-any */
 
   async getWithMetadata(
     key: string,
     options: { type: 'stream' } & GetWithMetadataOptions,
-  ): Promise<{ data: ReadableStream } & GetWithMetadataResult>
+  ): Promise<({ data: ReadableStream } & GetWithMetadataResult) | null>
 
   async getWithMetadata(
     key: string,
     options: { type: 'text' } & GetWithMetadataOptions,
-  ): Promise<{ data: string } & GetWithMetadataResult>
+  ): Promise<({ data: string } & GetWithMetadataResult) | null>
 
   async getWithMetadata(
     key: string,
@@ -187,17 +208,7 @@ export class Store {
     }
 
     const responseETag = res?.headers.get('etag') ?? undefined
-
-    let metadata: Metadata = {}
-
-    try {
-      metadata = decodeMetadata(res?.headers.get(METADATA_HEADER_INTERNAL))
-    } catch {
-      throw new Error(
-        'An internal error occurred while trying to retrieve the metadata for an entry. Please try updating to the latest version of the Netlify Blobs client.',
-      )
-    }
-
+    const metadata = getMetadataFromResponse(res)
     const result: GetWithMetadataResult = {
       etag: responseETag,
       fresh: false,

src/types.ts

@@ -5,5 +5,6 @@ export type Fetcher = typeof globalThis.fetch
 export enum HTTPMethod {
   DELETE = 'delete',
   GET = 'get',
+  HEAD = 'head',
   PUT = 'put',
 }

test/mock_fetch.ts

@@ -45,6 +45,10 @@ export class MockFetch {
     return this.addExpectedRequest({ ...options, method: 'get' })
   }
 
+  head(options: ExpectedRequestOptions) {
+    return this.addExpectedRequest({ ...options, method: 'head' })
+  }
+
   post(options: ExpectedRequestOptions) {
     return this.addExpectedRequest({ ...options, method: 'post' })
   }