feat: add list() method (#82)

Author: eduardoboucas

README.md

@@ -186,7 +186,7 @@ second parameter, with one of the following values:
 If an object with the given key is not found, `null` is returned.
 
 ```javascript
-const entry = await blobs.get('some-key', { type: 'json' })
+const entry = await store.get('some-key', { type: 'json' })
 
 console.log(entry)
 ```
@@ -209,7 +209,7 @@ second parameter, with one of the following values:
 If an object with the given key is not found, `null` is returned.
 
 ```javascript
-const blob = await blobs.getWithMetadata('some-key', { type: 'json' })
+const blob = await store.getWithMetadata('some-key', { type: 'json' })
 
 console.log(blob.data, blob.etag, blob.metadata)
 ```
@@ -223,7 +223,7 @@ const cachedETag = getFromMockCache('my-key')
 
 // Get entry from the blob store only if its ETag is different from the one you
 // have locally, which means the entry has changed since you last obtained it
-const { data, etag, fresh } = await blobs.getWithMetadata('some-key', { etag: cachedETag })
+const { data, etag, fresh } = await store.getWithMetadata('some-key', { etag: cachedETag })
 
 if (fresh) {
   // `data` is `null` because the local blob is fresh
@@ -240,7 +240,7 @@ Creates an object with the given key and value.
 If an entry with the given key already exists, its value is overwritten.
 
 ```javascript
-await blobs.set('some-key', 'This is a string value')
+await store.set('some-key', 'This is a string value')
 ```
 
 ### `setJSON(key: string, value: any, { metadata?: object }): Promise<void>`
@@ -250,7 +250,7 @@ Convenience method for creating a JSON-serialized object with the given key.
 If an entry with the given key already exists, its value is overwritten.
 
 ```javascript
-await blobs.setJSON('some-key', {
+await store.setJSON('some-key', {
   foo: 'bar',
 })
 ```
@@ -260,9 +260,86 @@ await blobs.setJSON('some-key', {
 Deletes an object with the given key, if one exists.
 
 ```javascript
-await blobs.delete('my-key')
+await store.delete('my-key')
 ```
 
+### `list(options?: { cursor?: string, directories?: boolean, paginate?: boolean. prefix?: string }): Promise<{ blobs: BlobResult[], directories: string[] }>`
+
+Returns a list of blobs in a given store.
+
+```javascript
+const { blobs } = await store.list()
+
+// [ { etag: 'etag1', key: 'some-key' }, { etag: 'etag2', key: 'another-key' } ]
+console.log(blobs)
+```
+
+To filter down the entries that should be returned, an optional `prefix` parameter can be supplied. When used, only the
+entries whose key starts with that prefix are returned.
+
+```javascript
+const { blobs } = await store.list({ prefix: 'some' })
+
+// [ { etag: 'etag1', key: 'some-key' } ]
+console.log(blobs)
+```
+
+Optionally, you can choose to group blobs together under a common prefix and then browse them hierarchically when
+listing a store, just like grouping files in a directory. To do this, use the `/` character in your keys to group them
+into directories.
+
+Take the following list of keys as an example:
+
+```
+cats/garfield.jpg
+cats/tom.jpg
+mice/jerry.jpg
+mice/mickey.jpg
+pink-panther.jpg
+```
+
+By default, calling `store.list()` will return all five keys.
+
+```javascript
+const { blobs } = await store.list()
+
+// [
+//   { etag: "etag1", key: "cats/garfield.jpg" },
+//   { etag: "etag2", key: "cats/tom.jpg" },
+//   { etag: "etag3", key: "mice/jerry.jpg" },
+//   { etag: "etag4", key: "mice/mickey.jpg" },
+//   { etag: "etag5", key: "pink-panther.jpg" },
+// ]
+console.log(blobs)
+```
+
+But if you want to list entries hierarchically, use the `directories` parameter.
+
+```javascript
+const { blobs, directories } = await store.list({ directories: true })
+
+// [ { etag: "etag1", key: "pink-panther.jpg" } ]
+console.log(blobs)
+
+// [ "cats", "mice" ]
+console.log(directories)
+```
+
+To drill down into a directory and get a list of its items, you can use the directory name as the `prefix` value.
+
+```javascript
+const { blobs, directories } = await store.list({ directories: true, prefix: 'cats/' })
+
+// [ { etag: "etag1", key: "cats/garfield.jpg" }, { etag: "etag2", key: "cats/tom.jpg" } ]
+console.log(blobs)
+
+// [ ]
+console.log(directories)
+```
+
+Note that we're only interested in entries under the `cats` directory, which is why we're using a trailing slash.
+Without it, other keys like `catsuit` would also match.
+
 ## Contributing
 
 Contributions are welcome! If you encounter any issues or have suggestions for improvements, please open an issue or

src/backend/list.ts

@@ -0,0 +1,12 @@
+export interface ListResponse {
+  blobs?: ListResponseBlob[]
+  directories?: string[]
+  next_cursor?: string
+}
+
+export interface ListResponseBlob {
+  etag: string
+  last_modified: string
+  size: number
+  key: string
+}

src/client.ts

@@ -6,9 +6,10 @@ import { BlobInput, Fetcher, HTTPMethod } from './types.ts'
 interface MakeStoreRequestOptions {
   body?: BlobInput | null
   headers?: Record<string, string>
-  key: string
+  key?: string
   metadata?: Metadata
   method: HTTPMethod
+  parameters?: Record<string, string>
   storeName: string
 }
 
@@ -20,6 +21,14 @@ export interface ClientOptions {
   token: string
 }
 
+interface GetFinalRequestOptions {
+  key: string | undefined
+  metadata?: Metadata
+  method: string
+  parameters?: Record<string, string>
+  storeName: string
+}
+
 export class Client {
   private apiURL?: string
   private edgeURL?: string
@@ -41,7 +50,7 @@ export class Client {
     }
   }
 
-  private async getFinalRequest(storeName: string, key: string, method: string, metadata?: Metadata) {
+  private async getFinalRequest({ key, metadata, method, parameters = {}, storeName }: GetFinalRequestOptions) {
     const encodedMetadata = encodeMetadata(metadata)
 
     if (this.edgeURL) {
@@ -53,38 +62,72 @@ export class Client {
         headers[METADATA_HEADER_EXTERNAL] = encodedMetadata
       }
 
+      const path = key ? `/${this.siteID}/${storeName}/${key}` : `/${this.siteID}/${storeName}`
+      const url = new URL(path, this.edgeURL)
+
+      for (const key in parameters) {
+        url.searchParams.set(key, parameters[key])
+      }
+
       return {
         headers,
-        url: `${this.edgeURL}/${this.siteID}/${storeName}/${key}`,
+        url: url.toString(),
       }
     }
 
-    const apiURL = `${this.apiURL ?? 'https://api.netlify.com'}/api/v1/sites/${
-      this.siteID
-    }/blobs/${key}?context=${storeName}`
     const apiHeaders: Record<string, string> = { authorization: `Bearer ${this.token}` }
+    const url = new URL(`/api/v1/sites/${this.siteID}/blobs`, this.apiURL ?? 'https://api.netlify.com')
+
+    for (const key in parameters) {
+      url.searchParams.set(key, parameters[key])
+    }
+
+    url.searchParams.set('context', storeName)
+
+    if (key === undefined) {
+      return {
+        headers: apiHeaders,
+        url: url.toString(),
+      }
+    }
+
+    url.pathname += `/${key}`
 
     if (encodedMetadata) {
       apiHeaders[METADATA_HEADER_EXTERNAL] = encodedMetadata
     }
 
-    const res = await this.fetch(apiURL, { headers: apiHeaders, method })
+    const res = await this.fetch(url.toString(), { headers: apiHeaders, method })
 
     if (res.status !== 200) {
-      throw new Error(`${method} operation has failed: API returned a ${res.status} response`)
+      throw new Error(`Netlify Blobs has generated an internal error: ${res.status} response`)
     }
 
-    const { url } = await res.json()
+    const { url: signedURL } = await res.json()
     const userHeaders = encodedMetadata ? { [METADATA_HEADER_INTERNAL]: encodedMetadata } : undefined
 
     return {
       headers: userHeaders,
-      url,
+      url: signedURL,
     }
   }
 
-  async makeRequest({ body, headers: extraHeaders, key, metadata, method, storeName }: MakeStoreRequestOptions) {
-    const { headers: baseHeaders = {}, url } = await this.getFinalRequest(storeName, key, method, metadata)
+  async makeRequest({
+    body,
+    headers: extraHeaders,
+    key,
+    metadata,
+    method,
+    parameters,
+    storeName,
+  }: MakeStoreRequestOptions) {
+    const { headers: baseHeaders = {}, url } = await this.getFinalRequest({
+      key,
+      metadata,
+      method,
+      parameters,
+      storeName,
+    })
     const headers: Record<string, string> = {
       ...baseHeaders,
       ...extraHeaders,
@@ -106,17 +149,7 @@ export class Client {
       options.duplex = 'half'
     }
 
-    const res = await fetchAndRetry(this.fetch, url, options)
-
-    if (res.status === 404 && method === HTTPMethod.GET) {
-      return null
-    }
-
-    if (res.status !== 200 && res.status !== 304) {
-      throw new Error(`${method} operation has failed: store returned a ${res.status} response`)
-    }
-
-    return res
+    return fetchAndRetry(this.fetch, url, options)
   }
 }