https://github.com/idiocc/form-data
Multipart/Form-Data And File Upload Middleware For Koa Written In ES6 And Optimised With JavaScript Compiler.
https://github.com/idiocc/form-data
Last synced: about 2 months ago
JSON representation
Multipart/Form-Data And File Upload Middleware For Koa Written In ES6 And Optimised With JavaScript Compiler.
- Host: GitHub
- URL: https://github.com/idiocc/form-data
- Owner: idiocc
- License: agpl-3.0
- Created: 2019-07-02T04:42:31.000Z (almost 7 years ago)
- Default Branch: master
- Last Pushed: 2019-12-28T19:05:13.000Z (over 6 years ago)
- Last Synced: 2025-09-27T22:55:18.401Z (9 months ago)
- Language: JavaScript
- Homepage: https://www.idio.cc
- Size: 1.69 MB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: COPYING
Awesome Lists containing this project
README
# @multipart/form-data
[](https://www.npmjs.com/package/@multipart/form-data)
`@multipart/form-data` is Multipart/Form-Data And File Upload Middleware For Koa Written In ES6 And Optimised With [JavaScript Compiler](https://compiler.page).
Originally, this was a [Multer](https://github.com/expressjs/multer) fork, however it was rewritten specifically for Koa2, and the interfaces were updated to be async rather than callbacks. Differences:
- When the file size limit is reached, the next middleware is called, rather than waiting to drain the request stream. This can result in the client-side **EPIPE** (connection reset) errors when sending files larger than allowed. But ideally, _Node.JS_ applications should be run behind a proxy such as NginX to limit the upload size.
- Removes the unnecessary `typeis` dependency that includes the `mime-type` database, just checks the _Content-Type_ to start with `multipart/form-data`.
- Compiled with _Google Closure Compiler_ and has just 1 dependency ([`text-decoding`](https://github.com/idiocc/text-decoding)) to decode non-utf8 fields (e.g., when a form submitted had the [`accept-charset`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/form#Attributes) attribute).
```sh
yarn add @multipart/form-data
```
## Table Of Contents
- [Table Of Contents](#table-of-contents)
- [API](#api)
- [`class FormData`](#class-formdata)
* [`FormData`](#type-formdata)
* [`FormDataConfig`](#type-formdataconfig)
* [single(fieldname)](#singlefieldname)
* [array(fieldname, maxCount)](#arrayfieldname-maxcount)
* [fields(Array<FormDataField>)](#fieldsarrayltformdatafieldgt)
* [`FormDataField`](#type-formdatafield)
* [none()](#none)
* [any()](#any)
- [`FormDataFile`](#formdatafile)
- [Copyright & License](#copyright--license)
## API
The package is available by importing its default and named functions:
```js
import FormData, {
diskStorage, memoryStorage, FormDataError,
} from '@multipart/form-data'
```
## `class FormData`
This class is used to create middleware according to the required file upload strategy.
__`FormData`__: An instance to create middleware.
Name
Type & Description
constructor
new (options?: !FormDataConfig) => FormData
Creates a new form-data instance.
single
(name: string) => !_goa.Middleware
Accept a single file.
array
(name: string, maxFiles: string) => !_goa.Middleware
Accept multiple files.
fields
(fields: !Array<FormDataField>) => !_goa.Middleware
Accept files according to the configured fields.
none
() => !_goa.Middleware
Do not accept files, only fields.
any
() => !_goa.Middleware
Accept any fields and files.
Creates a new instance according to the config. It is later used to access the middleware functions described below.
__`FormDataConfig`__: The configuration for the instance.
| Name | Type | Description | Default |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| dest | string | The directory where to store the files using the `DiskStorage`. If not specified, files will be saved in the system's temp directory (`os.tmpdir()`). | - |
| storage | FormDataStorageEngine | An _instance_ of a custom storage engine. | - |
| fileFilter | FormDataFileFilter | The file filter. | - |
| limits | _goa.BusBoyLimits | The limits of the uploaded data. | - |
| preservePath | boolean | Whether to keep the full path of files instead of just the base name. | `false` |
single(fieldname): Accept a single file.
```js
import Multipart from '@multipart/form-data'
import Goa from '@goa/koa'
const app = new Goa()
const multipart = new Multipart({
dest: 'temp',
})
const middleware = multipart.single('file')
app.use(middleware)
app.use((ctx) => {
console.log('Fields: %O', ctx.req.body)
delete ctx.req.file.stream
console.log('File: %O', ctx.req.file)
})
```
```js
Fields: { hello: 'world', name: 'multipart' }
File: { fieldname: 'file',
originalname: 'test.txt',
encoding: '7bit',
mimetype: 'application/octet-stream',
destination: 'temp',
filename: 'afb49cada5f721d7fa8337f072d03ec5',
path: 'temp/afb49cada5f721d7fa8337f072d03ec5',
size: 12 }
```
array(fieldname, maxCount): Accept multiple files under the same field name.
```js
import Multipart from '@multipart/form-data'
import Goa from '@goa/koa'
const app = new Goa()
const multipart = new Multipart({
dest: 'temp',
preservePath: true,
})
const middleware = multipart.array('file', 2)
app.use(middleware)
app.use((ctx) => {
log('Fields', ctx.req.body)
log('Files', ctx.req.files)
})
```
```js
Fields: { hello: 'world', name: 'multipart' }
Files: [ { fieldname: 'file',
originalname: 'test/fixture/test.txt',
encoding: '7bit',
mimetype: 'application/octet-stream',
destination: 'temp',
filename: '0fa202db40',
path: 'temp/0fa202db40',
size: 12 },
{ fieldname: 'file',
originalname: 'test/fixture/test.txt',
encoding: '7bit',
mimetype: 'application/octet-stream',
destination: 'temp',
filename: '149e4b08d6',
path: 'temp/149e4b08d6',
size: 12 } ]
```
fields(Array<FormDataField>): Accept files according to the configured fields and place them in a hashmap.
Click to show the FormDataField interface.
__`FormDataField`__: The item to use in the `.fields` method.
| Name | Type | Description |
| --------- | --------------- | ------------------------------- |
| __name*__ | string | The name of the field. |
| maxCount | number | The maximum count of the field. |
```js
import Multipart from '@multipart/form-data'
import Goa from '@goa/koa'
const app = new Goa()
const multipart = new Multipart({
dest: 'temp',
})
const middleware = multipart.fields([
{ name: 'file', maxCount: 2 },
{ name: 'picture', maxCount: 1 },
])
app.use(middleware)
app.use((ctx) => {
log('Fields', ctx.req.body)
log('Files', ctx.req.files)
})
```
```js
Fields: { hello: 'world', name: 'multipart' }
Files: { file:
[ { fieldname: 'file',
originalname: 'test.txt',
encoding: '7bit',
mimetype: 'application/octet-stream',
destination: 'temp',
filename: '13093f0764',
path: 'temp/13093f0764',
size: 12 },
{ fieldname: 'file',
originalname: 'test.txt',
encoding: '7bit',
mimetype: 'application/octet-stream',
destination: 'temp',
filename: '22e2e6e6f7',
path: 'temp/22e2e6e6f7',
size: 12 } ],
picture:
[ { fieldname: 'picture',
originalname: 'large.jpg',
encoding: '7bit',
mimetype: 'application/octet-stream',
destination: 'temp',
filename: '352a1aea6a',
path: 'temp/352a1aea6a',
size: 1592548 } ] }
```
none(): Do not accept files, only fields.
```js
import Multipart from '@multipart/form-data'
import Goa from '@goa/koa'
const app = new Goa()
const multipart = new Multipart({
dest: 'temp',
})
const middleware = multipart.none()
app.use(middleware)
app.use((ctx) => {
log('Fields', ctx.req.body)
log('Files', ctx.req.files)
})
```
```js
Fields: { hello: 'world', name: 'multipart' }
Files: undefined
```
any(): Accept all files and fields.
```js
import Multipart from '@multipart/form-data'
import Goa from '@goa/koa'
const app = new Goa()
const multipart = new Multipart({
dest: 'temp',
})
const middleware = multipart.any()
app.use(middleware)
app.use((ctx) => {
log('Fields', ctx.req.body)
log('Files', ctx.req.files)
})
```
```js
Fields: { hello: 'world', name: 'multipart' }
Files: [ { fieldname: 'file',
originalname: 'test.txt',
encoding: '7bit',
mimetype: 'application/octet-stream',
destination: 'temp',
filename: '7218bd891a',
path: 'temp/7218bd891a',
size: 12 },
{ fieldname: 'picture',
originalname: 'large.jpg',
encoding: '7bit',
mimetype: 'application/octet-stream',
destination: 'temp',
filename: 'e7a8050980',
path: 'temp/e7a8050980',
size: 1592548 } ]
```
## `FormDataFile`
_MultipartFormData_ adds a `body` object and a `file` or `files` object to the request object. The `body` hashmap contains the values of the text fields of the form, the `file` or `files` object contains the files uploaded via the form.
[`import('stream').Readable`](https://nodejs.org/api/stream.html#stream_readable_streams) __`stream.Readable`__: A stream that pushes data when it becomes available.
__`FormDataFile`__: The information about each file.
| Name | Type | Description |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------- |
| __fieldname*__ | string | The field name specified in the form. |
| __originalname*__ | string | The name of the file on the user's computer. |
| __encoding*__ | string | The encoding type of the file. |
| __mimetype*__ | string | The mime type of the file. |
| __size*__ | number | The size of the file in bytes. |
| __destination*__ | string | The folder to which the file has been saved. Set by _DiskStorage_. |
| __filename*__ | string | The name of the file within the `destination`. Set by _DiskStorage_. |
| __path*__ | string | The full path to the uploaded file. Set by _DiskStorage_. |
| __buffer*__ | Buffer | The `Buffer` of the entire file. Set by _MemoryStorage_. |
| __stream*__ | stream.Readable | The _Readable_ stream with the file data. This stream should not be read other than by a storage engine. |
## Copyright & License
GNU Affero General Public License v3.0
[Original work](https://github.com/expressjs/multer) by Multer's contributors under MIT license found in [COPYING](COPYING).
© Art Deco for Idio 2019
Tech Nation Visa Sucks
