feat: file upload middleware

packages/file-upload/README.md

@@ -0,0 +1,61 @@
+# Hono File Upload
+
+This is a File upload middleware library for [Hono](https://github.com/honojs/hono) which can save file to your server disk, Firebase FireStorage, or event AWS S3.
+
+## Install
+
+```
+npm install @hono/file-upload
+```
+
+## Usage
+
+```ts
+import { Hono } from 'hono'
+import { HonoFileUpload } from '@hono/file-upload'
+
+const app = new Hono()
+const fileUpload = new HonoFileUpload()
+
+// Save to server disk
+app.post(
+ '/upload/disk',
+ fileUpload.saveToDisk({
+ // Pass the destination path
+ destination: __dirname,
+ }),
+ (c) => c.text('OK'
+)
+
+// Save to firebase firestorage
+app.post(
+ '/upload/firestorage',
+ fileUpload.saveToFirebase({
+ // Pass the destination path in the firebase firestorage
+ destination: '/',
+ // Pass the firebase-admin storage instance
+ storage: ...
+ }),
+ (c) => c.text('OK'
+)
+
+// Save to aws s3
+app.post(
+ '/upload/firestorage',
+ fileUpload.saveToAws({
+ // Pass the bucket path in the aws s3
+ destination: '/',
+ // Pass the aws s3 instance
+ storage: ...
+ }),
+ (c) => c.text('OK'
+)
+```
+
+## Author
+
+krsbx <https://github.com/krsbx>
+
+## License
+
+MIT

packages/file-upload/jest.config.js

@@ -0,0 +1 @@
+module.exports = require('../../jest.config.js')

packages/file-upload/package.json

@@ -0,0 +1,31 @@
+{
+ "name": "file-upload",
+ "version": "1.0.0",
+ "description": "File upload middleware",
+ "main": "dist/index.js",
+ "types": "dist/index.d.ts",
+ "files": [
+ "dist"
+ ],
+ "repository": "https://github.com/honojs/middleware.git",
+ "author": "krsbx",
+ "scripts": {
+ "build": "tsc",
+ "prerelease": "yarn build",
+ "release": "yarn publish"
+ },
+ "license": "MIT",
+ "dependencies": {
+ "fs-extra": "^11.1.1"
+ },
+ "peerDependencies": {
+ "hono": "3.*"
+ },
+ "devDependencies": {
+ "@types/fs-extra": "^11.0.1",
+ "@types/supertest": "^2.0.12",
+ "aws-sdk": "^2.1449.0",
+ "firebase-admin": "^11.10.1",
+ "supertest": "^6.3.3"
+ }
+}

packages/file-upload/src/constants.ts

@@ -0,0 +1,3 @@
+export const DEFAULT_MAX_SIZE = 10 * 1024 * 1024 // 1 MB
+export const DEFAULT_MIN_SIZE = 10 * 1000 // 10 KB
+export const FORM_MIME_TYPES = ['multipart/form-data', 'application/x-www-form-urlencoded']

packages/file-upload/src/helper.ts

@@ -0,0 +1,140 @@
+import path from 'path'
+import type { Context, Next } from 'hono'
+import { FORM_MIME_TYPES } from './constants'
+import type {
+ HonoFileUploadAwsOption,
+ HonoFileUploadDiskOption,
+ HonoFileUploadFirebaseOption,
+ HonoFileUploadOption,
+} from './types'
+
+export function validateContentType(c: Context, next: Next, options: HonoFileUploadDiskOption) {
+ const contentType = c.req.headers.get('Content-Type')
+
+ if (!contentType || options.skipNonFormBody) {
+ return next()
+ }
+
+ if (FORM_MIME_TYPES.every((type) => !contentType.startsWith(type))) {
+ throw new Error(`Content-Type must be ${FORM_MIME_TYPES.join(' or ')}`)
+ }
+}
+
+export async function getFiles(c: Context, options: HonoFileUploadDiskOption) {
+ const form = await c.req.parseBody()
+ const files = Object.entries(form).filter(([, value]) => value instanceof File) as unknown as [
+ string,
+ File
+ ][]
+
+ if (files.length > options.totalFiles!) {
+ throw new Error('Too many files')
+ }
+
+ return files
+}
+
+export function normalizeOptions(
+ options: HonoFileUploadDiskOption,
+ defaultOptions: HonoFileUploadOption
+): Required<HonoFileUploadDiskOption> {
+ if (typeof options.totalFiles === 'undefined') {
+ options.totalFiles = defaultOptions.totalFiles
+ }
+
+ if (typeof options.skipNonFormBody === 'undefined' || options.skipNonFormBody === null) {
+ options.skipNonFormBody = defaultOptions.skipNonFormBody
+ }
+
+ if (typeof options.prefixByMilliseconds === 'undefined') {
+ options.prefixByMilliseconds = defaultOptions.prefixByMilliseconds
+ }
+
+ if (typeof options.fileNameHandler === 'undefined') {
+ options.fileNameHandler = defaultOptions.fileNameHandler
+ }
+
+ if (typeof options.autoSetContext === 'undefined') {
+ options.autoSetContext = defaultOptions.autoSetContext
+ }
+
+ if (
+ typeof options.destination === 'undefined' ||
+ options.destination === null ||
+ options.destination === ''
+ ) {
+ throw new Error('destination is required')
+ }
+
+ return options as Required<HonoFileUploadDiskOption>
+}
+
+export async function getFileInformation(value: File, options: HonoFileUploadDiskOption) {
+ const fileNames: string[] = []
+
+ if (options.prefixByMilliseconds) {
+ fileNames.push(Date.now().toString())
+ }
+
+ if (options.fileNameHandler) {
+ fileNames.push(options.fileNameHandler(value.name))
+ } else {
+ fileNames.push(value.name)
+ }
+
+ const finalName = fileNames.join('-')
+ const destination = path.resolve(options.destination, finalName)
+ const fileBuffer = Buffer.from(await value.arrayBuffer())
+
+ return {
+ fileBuffer,
+ destination,
+ finalName,
+ }
+}
+
+export async function uploadToFirestorage(value: File, options: HonoFileUploadFirebaseOption) {
+ const { destination, fileBuffer, finalName } = await getFileInformation(value, options)
+ const storage = options.storage.bucket().file(destination)
+
+ await storage.save(fileBuffer, {
+ contentType: value.type,
+ public: true,
+ })
+ const publicUri = storage.publicUrl()
+
+ return {
+ publicUri,
+ finalName,
+ destination,
+ }
+}
+
+export async function uploadToS3(value: File, options: HonoFileUploadAwsOption) {
+ const { destination, fileBuffer, finalName } = await getFileInformation(value, options)
+
+ const file = await options.storage
+ .upload({
+ Bucket: destination,
+ Key: finalName,
+ Body: fileBuffer,
+ })
+ .promise()
+
+ return {
+ publicUri: file.Location,
+ finalName,
+ destination,
+ }
+}
+
+export function autoSetToContext(
+ c: Context,
+ files: [string, File][],
+ options: HonoFileUploadOption
+) {
+ if (!options.autoSetContext) return
+
+ // Set the uploaded files to the context
+ c.set('__files__', files)
+}

packages/file-upload/src/index.ts

@@ -0,0 +1,136 @@
+import fs from 'fs-extra'
+import type { MiddlewareHandler } from 'hono'
+import { DEFAULT_MAX_SIZE, DEFAULT_MIN_SIZE } from './constants'
+import {
+ autoSetToContext,
+ getFileInformation,
+ getFiles,
+ normalizeOptions,
+ uploadToFirestorage,
+ uploadToS3,
+ validateContentType,
+} from './helper'
+import type {
+ HonoFileUploadAwsOption,
+ HonoFileUploadDiskOption,
+ HonoFileUploadFirebaseOption,
+ HonoFileUploadOption,
+} from './types'
+
+export class HonoFileUpload {
+ private options: Required<HonoFileUploadOption>
+
+ constructor(options: HonoFileUploadOption = {}) {
+ this.options = {
+ fieldNameSize: options?.fieldNameSize ?? 100,
+ maxFileSize: options?.maxFileSize ?? DEFAULT_MAX_SIZE,
+ minFileSize: options?.minFileSize ?? DEFAULT_MIN_SIZE,
+ totalFiles: options?.totalFiles ?? Infinity,
+ skipNonFormBody: options?.skipNonFormBody ?? false,
+ prefixByMilliseconds: options?.prefixByMilliseconds ?? false,
+ fileNameHandler: options?.fileNameHandler ?? ((filename: string) => filename),
+ autoSetContext: options?.autoSetContext ?? false,
+ }
+ }
+
+ public saveToDisk(options: HonoFileUploadDiskOption): MiddlewareHandler {
+ options = normalizeOptions(options, this.options) as HonoFileUploadDiskOption
+
+ return async function (c, next) {
+ await validateContentType(c, next, options)
+
+ const files = await getFiles(c, options)
+
+ if (files.length === 0) {
+ return next()
+ }
+
+ if (!(await fs.exists(options.destination))) {
+ await fs.mkdirp(options.destination)
+ }
+
+ await Promise.all(
+ files.map(async ([, value]) => {
+ const { destination, fileBuffer, finalName } = await getFileInformation(value, options)
+
+ // Assign new attributes to the files object
+ Object.assign(value, {
+ savedTo: destination,
+ savedName: finalName,
+ originalName: value.name,
+ })
+
+ return fs.writeFile(destination, fileBuffer)
+ })
+ )
+
+ autoSetToContext(c, files, options)
+
+ return next()
+ }
+ }
+
+ public saveToFirebase(options: HonoFileUploadFirebaseOption): MiddlewareHandler {
+ options = normalizeOptions(options, this.options) as HonoFileUploadFirebaseOption
+
+ return async function (c, next) {
+ await validateContentType(c, next, options)
+
+ const files = await getFiles(c, options)
+
+ if (files.length === 0) {
+ return next()
+ }
+
+ await Promise.all(
+ files.map(async ([, value]) => {
+ const { destination, finalName, publicUri } = await uploadToFirestorage(value, options)
+
+ // Assign new attributes to the files object
+ Object.assign(value, {
+ savedTo: destination,
+ savedName: finalName,
+ originalName: value.name,
+ uri: publicUri,
+ })
+ })
+ )
+
+ autoSetToContext(c, files, options)
+
+ return next()
+ }
+ }
+
+ public saveToAws(options: HonoFileUploadAwsOption): MiddlewareHandler {
+ options = normalizeOptions(options, this.options) as HonoFileUploadAwsOption
+
+ return async function (c, next) {
+ await validateContentType(c, next, options)
+
+ const files = await getFiles(c, options)
+
+ if (files.length === 0) {
+ return next()
+ }
+
+ await Promise.all(
+ files.map(async ([, value]) => {
+ const { destination, finalName, publicUri } = await uploadToS3(value, options)
+
+ // Assign new attributes to the files object
+ Object.assign(value, {
+ savedTo: destination,
+ savedName: finalName,
+ originalName: value.name,
+ uri: publicUri,
+ })
+ })
+ )
+
+ autoSetToContext(c, files, options)
+
+ return next()
+ }
+ }
+}