feat(blob): add .get() (#283)

docs/content/1.docs/2.features/blob.md

@@ -35,7 +35,7 @@ Server composable that returns a set of methods to manipulate the blob storage.
 
 ### `list()`
 
-Returns a paginated list of blobs.
+Returns a paginated list of blobs (metadata only).
 
 ```ts [server/api/files.get.ts]
 export default eventHandler(async () => {
@@ -111,7 +111,7 @@ Returns the blob's raw data and sets `Content-Type` and `Content-Length` headers
 Returns a blob's metadata.
 
 ```ts
-const blob = await hubBlob().head(pathname)
+const metadata = await hubBlob().head(pathname)
 ```
 
 #### Params
@@ -126,6 +126,27 @@ const blob = await hubBlob().head(pathname)
 
 Returns a [`BlobObject`](#blobobject).
 
+
+### `get()`
+
+Returns a blob body.
+
+```ts
+const blob = await hubBlob().get(pathname)
+```
+
+#### Params
+
+::field-group
+  ::field{name="pathname" type="String"}
+    The name of the blob to serve.
+  ::
+::
+
+#### Return
+
+Returns a [`Blob`](https://developer.mozilla.org/en-US/docs/Web/API/Blob) or `null` if not found.
+
 ### `put()`
 
 Uploads a blob to the storage.

playground/server/api/blob/get/[...pathname].get.ts

@@ -0,0 +1,11 @@
+export default eventHandler(async (event) => {
+  const { pathname } = await getValidatedRouterParams(event, z.object({
+    pathname: z.string().min(1)
+  }).parse)
+
+  const blob = await hubBlob().get(pathname)
+
+  console.log('blob', blob)
+
+  return blob
+})

src/runtime/blob/server/utils/blob.ts

@@ -34,16 +34,26 @@ function _useBucket(name: string = 'BLOB') {
 
 interface HubBlob {
   /**
-   * List all the blobs in the bucket.
+   * List all the blobs in the bucket (metadata only).
    *
    * @param options The list options
+   *
+   * @example ```ts
+   * const { blobs } = await hubBlob().list({ limit: 10 })
+   * ```
    */
   list(options?: BlobListOptions): Promise<BlobListResult>
   /**
    * Serve the blob from the bucket.
    *
    * @param event The H3 event (needed to set headers for the response)
    * @param pathname The pathname of the blob
+   *
+   * @example ```ts
+   * export default eventHandler(async (event) => {
+   *   return hubBlob().serve(event, '/my-image.jpg')
+   * })
+   * ```
    */
   serve(event: H3Event, pathname: string): Promise<ReadableStream<any>>
   /**
@@ -52,44 +62,78 @@ interface HubBlob {
    * @param pathname The pathname of the blob
    * @param body The blob content
    * @param options The put options
+   *
+   * @example ```ts
+   * const blob = await hubBlob().put('/my-image.jpg', file)
+   * ```
    */
   put(pathname: string, body: string | ReadableStream<any> | ArrayBuffer | ArrayBufferView | Blob, options?: BlobPutOptions): Promise<BlobObject>
   /**
    * Get the blob metadata from the bucket.
    *
    * @param pathname The pathname of the blob
+   *
+   * @example ```ts
+   * const blobMetadata = await hubBlob().head('/my-image.jpg')
+   * ```
    */
   head(pathname: string): Promise<BlobObject>
+  /**
+   * Get the blob body from the bucket.
+   *
+   * @param pathname The pathname of the blob
+   *
+   * @example ```ts
+   * const blob = await hubBlob().get('/my-image.jpg')
+   * ```
+   */
+  get(pathname: string): Promise<Blob | null>
   /**
    * Delete the blob from the bucket.
    *
    * @param pathnames The pathname of the blob
+   *
+   * @example ```ts
+   * await hubBlob().del('/my-image.jpg')
+   * ```
    */
   del(pathnames: string | string[]): Promise<void>
   /**
    * Delete the blob from the bucket.
    *
    * @param pathnames The pathname of the blob
+   *
+   * @example ```ts
+   * await hubBlob().delete('/my-image.jpg')
+   * ```
    */
   delete(pathnames: string | string[]): Promise<void>
   /**
    * Create a multipart upload.
+   *
+   * @see https://hub.nuxt.com/docs/features/blob#createmultipartupload
    */
   createMultipartUpload(pathname: string, options?: BlobMultipartOptions): Promise<BlobMultipartUpload>
   /**
    * Get the specified multipart upload.
+   *
+   * @see https://hub.nuxt.com/docs/features/blob#resumemultipartupload
    */
   resumeMultipartUpload(pathname: string, uploadId: string): BlobMultipartUpload
   /**
    * Handle the multipart upload request.
    * Make sure your route includes `[action]` and `[...pathname]` params.
+   *
+   * @see https://hub.nuxt.com/docs/features/blob#handlemultipartupload
    */
   handleMultipartUpload(event: H3Event, options?: BlobMultipartOptions): Promise<HandleMPUResponse>
   /**
    * Handle a file upload.
    *
    * @param event The H3 event (needed to set headers for the response)
    * @param options The upload options
+   *
+   * @see https://hub.nuxt.com/docs/features/blob#handleupload
    */
   handleUpload(event: H3Event, options?: BlobUploadOptions): Promise<BlobObject[]>
 }
@@ -147,6 +191,15 @@ export function hubBlob(): HubBlob {
 
       return object.body
     },
+    async get(pathname: string): Promise<Blob | null> {
+      const object = await bucket.get(decodeURI(pathname))
+
+      if (!object) {
+        return null
+      }
+
+      return object.blob() as Promise<Blob>
+    },
     async put(pathname: string, body: string | ReadableStream<any> | ArrayBuffer | ArrayBufferView | Blob, options: BlobPutOptions = {}) {
       pathname = decodeURI(pathname)
       const { contentType: optionsContentType, contentLength, addRandomSuffix, prefix, customMetadata } = options
@@ -321,6 +374,12 @@ export function proxyHubBlob(projectUrl: string, secretKey?: string): HubBlob {
         method: 'GET'
       })
     },
+    async get(pathname: string): Promise<Blob> {
+      return await blobAPI(`/${decodeURI(pathname)}`, {
+        method: 'GET',
+        responseType: 'blob'
+      })
+    },
     async del(pathnames: string | string[]) {
       if (Array.isArray(pathnames)) {
         await blobAPI('/delete', {