feat: handleUpload() util and useUpload() composable (#99)

Co-authored-by: Sébastien Chopin <seb@nuxt.com>

Author: farnabaz

docs/content/docs/2.storage/3.blob.md

@@ -151,6 +151,9 @@ export default eventHandler(async (event) => {
     ::field{name="addRandomSuffix" type="Boolean"}
       If `true`, a random suffix will be added to the blob's name. Defaults to `false`.
     ::
+    ::field{name="prefix" type="string"}
+      The prefix to use for the blob pathname.
+    ::
   ::
 ::
 
@@ -194,6 +197,56 @@ You can also use the `delete()` method as alias of `del()`.
 
 Returns nothing.
 
+### `handleUpload()`
+
+`handleUpload` is a all in one function to validate a `Blob` by checking its size and type and upload it to the storage.
+It can used to handle file uploads in API routes.
+
+```ts [server/api/blob.put.ts]
+export default eventHandler(async (event) => {
+  return hubBlob().handleUpload(event, {
+    formKey: 'file', // read file or files form the `formKey` field of request body (body should be a `FormData` object)
+    multiple: true // when `true`, the `formKey` field will be an array of `Blob` objects
+  })
+})
+```
+
+#### Params
+
+::field-group
+  ::field{name="formKey" type="string"}
+    The form key to read the file from. Defaults to `'file'`.
+  ::
+  ::field{name="multiple" type="boolean"}
+    When `true`, the `formKey` field will be an array of `Blob` objects.
+  ::
+  ::field{name="maxSize" type="BlobSize"}
+    The maximum size of the file, should be: :br
+    (`1` | `2` | `4` | `8` | `16` | `32` | `64` | `128` | `256` | `512` | `1024`) + (`B` | `KB` | `MB` | `GB`) :br
+    e.g. `'512KB'`, `'1MB'`, `'2GB'`, etc.
+  ::
+  ::field{name="types" type="BlobType[]"}
+    Allowed types of the file, e.g. `['image/jpeg']`.
+  ::
+  ::field{name="contentType" type="string"}
+    The content type of the blob.
+  ::
+  ::field{name="contentLength" type="string"}
+    The content length of the blob.
+  ::
+  ::field{name="addRandomSuffix" type="boolean"}
+    If `true`, a random suffix will be added to the blob's name. Defaults to `false`.
+  ::
+  ::field{name="prefix" type="string"}
+    The prefix to use for the blob pathname.
+  ::
+::
+
+#### Return
+
+Returns a [`BlobObject`](#blobobject) or an array of [`BlobObject`](#blobobject) if `multiple` is `true`.
+
+Throws an error if `file` doesn't meet the requirements.
 
 ## `ensureBlob()`
 
@@ -229,6 +282,51 @@ Returns nothing.
 
 Throws an error if `file` doesn't meet the requirements.
 
+## Composables
+
+### `useUpload()`
+
+`useUpload` is to handle file uploads in your Nuxt application.
+
+```vue
+<script setup lang="ts">
+const upload = useUpload('/api/blob', { method: 'PUT' })
+
+async function onFileSelect({ target }: Event) {
+  const uploadedFiles = await upload(target as HTMLInputElement)
+
+  // file uploaded successfully
+}
+</script>
+
+<template>
+  <input
+    accept="jpeg, png"
+    type="file"
+    name="file"
+    multiple
+    @change="onFileSelect"
+  >
+</template>
+```
+
+#### Params
+
+::field-group
+  ::field{name="apiBase" type="string" required}
+    The base URL of the upload API.
+  ::
+  ::field{name="options" type="Object" required}
+    Optionally, you can pass Fetch options to the request. Read more about Fetch API [here](https://developer.mozilla.org/en-US/docs/Web/API/fetch#options).
+    ::field{name="formKey" type="string"}
+      The key to add the file/files to the request form. Defaults to `'file'`.
+    ::
+    ::field{name="multiple" type="boolean"}
+      Whether to allow multiple files to be uploaded. Defaults to `true`.
+    ::
+  ::
+::
+
 ## Types
 
 ### `BlobObject`

playground/pages/blob.vue

@@ -1,7 +1,7 @@
 <script setup lang="ts">
 const loading = ref(false)
 const newFilesValue = ref<File[]>([])
-const uploadRef = ref()
+const uploadRef = ref<HTMLInputElement>()
 const folded = ref(false)
 const prefixes = ref([])
 const limit = ref(5)
@@ -20,7 +20,7 @@ const files = computed(() => blobData.value?.blobs || [])
 const folders = computed(() => blobData.value?.folders || [])
 
 async function loadMore() {
-  if (!blobData.value.hasMore) return
+  if (!blobData.value?.hasMore) return
   const nextPage = await $fetch('/api/blob', {
     params: {
       folded: folded.value,
@@ -45,15 +45,8 @@ async function addFile() {
   loading.value = true
 
   try {
-    const formData = new FormData()
-    newFilesValue.value.forEach(file => formData.append('files', file))
-    const uploadedFiles = await $fetch('/api/blob', {
-      method: 'PUT',
-      params: {
-        prefix: String(prefix.value || '')
-      },
-      body: formData
-    })
+    const uploadedFiles = await useUpload('/api/blob', { method: 'PUT', prefix: String(prefix.value || '') })(newFilesValue.value)
+
     files.value!.push(...uploadedFiles)
     toast.add({ title: `File${uploadedFiles.length > 1 ? 's' : ''} uploaded.` })
     newFilesValue.value = []
@@ -80,7 +73,7 @@ async function deleteFile(pathname: string) {
   try {
     await $fetch(`/api/blob/${pathname}`, { method: 'DELETE' })
 
-    blobData.value.blobs = blobData.value.blobs!.filter(t => t.pathname !== pathname)
+    blobData.value!.blobs = blobData.value!.blobs!.filter(t => t.pathname !== pathname)
 
     toast.add({ title: `File "${pathname}" deleted.` })
   } catch (err: any) {

playground/server/api/blob/index.put.ts

@@ -1,27 +1,8 @@
 export default eventHandler(async (event) => {
   const { prefix } = getQuery(event)
-  const form = await readFormData(event)
-  const files = form.getAll('files') as File[]
-  if (!files) {
-    throw createError({ statusCode: 400, message: 'Missing files' })
-  }
-
-  const { put } = hubBlob()
-  const objects: BlobObject[] = []
-  try {
-    for (const file of files) {
-      // const object = await put(file.name, file, { addRandomSuffix: true })
-      const object = await put(file.name, file, {
-        prefix: String(prefix || '')
-      })
-      objects.push(object)
-    }
-  } catch (e: any) {
-    throw createError({
-      statusCode: 500,
-      message: `Storage error: ${e.message}`
-    })
-  }
-
-  return objects
+  return hubBlob().handleUpload(event, {
+    formKey: 'file', // default
+    multiple: true, // default
+    prefix: String(prefix || '')
+  })
 })

src/module.ts

@@ -1,7 +1,7 @@
 import { mkdir, writeFile, readFile } from 'node:fs/promises'
 import { execSync } from 'node:child_process'
 import { argv } from 'node:process'
-import { defineNuxtModule, createResolver, logger, addServerScanDir, installModule, addServerImportsDir } from '@nuxt/kit'
+import { defineNuxtModule, createResolver, logger, addServerScanDir, installModule, addServerImportsDir, addImportsDir } from '@nuxt/kit'
 import { join } from 'pathe'
 import { defu } from 'defu'
 import { findWorkspaceDir } from 'pkg-types'
@@ -160,9 +160,12 @@ export default defineNuxtModule<ModuleOptions>({
       ? '#internal/nitro/routes/openapi'
       : resolve('./runtime/templates/openapi')
 
-    // Register composables
+    // Register server utils
     addServerImportsDir(resolve('./runtime/server/utils'))
 
+    // Register client composables
+    addImportsDir(resolve('./runtime/compsables'))
+
     // nuxt prepare, stop here
     if (nuxt.options._prepare) {
       return

src/runtime/compsables/useUpload.ts

@@ -0,0 +1,52 @@
+import type { FetchOptions } from 'ofetch'
+
+interface UploadOptions extends FetchOptions {
+  /**
+   * The key to add the file/files to the request form.
+   * @default 'file'
+   */
+  formKey?: string
+
+  /**
+   * Whether to allow multiple files to be uploaded.
+   * @default true
+   */
+  multiple?: boolean
+
+}
+
+export function useUpload(apiBase: string, options: UploadOptions & { multiple: false }): (data: FileList | HTMLInputElement | File[] | File) => Promise<BlobObject>
+export function useUpload(apiBase: string, options: UploadOptions): ((data: File) => Promise<BlobObject>) & ((data: FileList | HTMLInputElement | File[]) => Promise<BlobObject[]>)
+export function useUpload(apiBase: string, options: UploadOptions = {}) {
+  const { formKey = 'file', multiple = true, method, ...fetchOptions } = options || {}
+
+  async function upload(data: File): Promise<BlobObject>
+  async function upload(data: FileList | HTMLInputElement | File[] | File): Promise<BlobObject[] | BlobObject> {
+    if (data instanceof HTMLInputElement) {
+      data = data.files!
+    }
+    if (data instanceof File) {
+      data = [data]
+    }
+    if (!data || !data.length) {
+      throw createError({ statusCode: 400, message: 'Missing files' })
+    }
+
+    const formData = new FormData()
+    if (multiple) {
+      for (const file of data) {
+        formData.append(formKey, file)
+      }
+    } else {
+      formData.append(formKey, data[0])
+    }
+
+    return $fetch<BlobObject[]>(apiBase, {
+      ...fetchOptions,
+      method: (method || 'POST') as any,
+      body: formData
+    }).then(result => (multiple === false || data instanceof File) ? result[0] : result)
+  }
+
+  return upload
+}

src/runtime/server/api/_hub/blob/index.post.ts

@@ -1,34 +1,14 @@
-import { createError, eventHandler, readFormData } from 'h3'
-import { hubBlob, type BlobObject } from '../../../utils/blob'
+import { eventHandler } from 'h3'
+import { hubBlob } from '../../../utils/blob'
 import { requireNuxtHubAuthorization } from '../../../utils/auth'
-import { requireNuxtHubFeature } from '../../../utils/features'
 
 export default eventHandler(async (event) => {
   await requireNuxtHubAuthorization(event)
-  requireNuxtHubFeature('blob')
-
   const query = getQuery(event)
-  const options = { ...query } as BlobPutOptions
-
-  const form = await readFormData(event)
-  const files = form.getAll('files') as File[]
-  if (!files) {
-    throw createError({ statusCode: 400, message: 'Missing files' })
-  }
-  const blob = hubBlob()
-
-  const objects: BlobObject[] = []
-  try {
-    for (const file of files) {
-      const object = await blob.put(file.name!, file, options)
-      objects.push(object)
-    }
-  } catch (e: any) {
-    throw createError({
-      statusCode: 500,
-      message: `Storage error: ${e.message}`
-    })
-  }
 
-  return objects
+  return hubBlob().handleUpload(event, {
+    formKey: 'files',
+    multiple: true,
+    ...query
+  })
 })