108 lines
3.7 KiB
Markdown
108 lines
3.7 KiB
Markdown
|
# @tinyhttp/content-disposition
|
||
|
|
|
||
|
|
> [`content-disposition`](https://github.com/jshttp/content-disposition) rewrite
|
||
|
|
> in TypeScript.
|
||
|
|
|
||
|
|
Create and parse HTTP `Content-Disposition` header
|
||
|
|
|
||
|
|
## Install
|
||
|
|
|
||
|
|
```sh
|
||
|
|
pnpm i @tinyhttp/content-disposition
|
||
|
|
```
|
||
|
|
|
||
|
|
## API
|
||
|
|
|
||
|
|
```ts
|
||
|
|
import { contentDisposition, parse } from '@tinyhttp/content-disposition'
|
||
|
|
```
|
||
|
|
|
||
|
|
### `contentDisposition(filename)`
|
||
|
|
|
||
|
|
Create an attachment `Content-Disposition` header value using the given file
|
||
|
|
name, if supplied. The `filename` is optional and if no file name is desired,
|
||
|
|
but you want to specify `options`, set `filename` to `undefined`.
|
||
|
|
|
||
|
|
```js
|
||
|
|
res.setHeader('Content-Disposition', contentDisposition('∫ maths.pdf'))
|
||
|
|
```
|
||
|
|
|
||
|
|
**note** HTTP headers are of the ISO-8859-1 character set. If you are writing
|
||
|
|
this header through a means different from `setHeader` in Node.js, you'll want
|
||
|
|
to specify the `'binary'` encoding in Node.js.
|
||
|
|
|
||
|
|
#### Options
|
||
|
|
|
||
|
|
`contentDisposition` accepts these properties in the options object.
|
||
|
|
|
||
|
|
##### `fallback`
|
||
|
|
|
||
|
|
If the `filename` option is outside ISO-8859-1, then the file name is actually
|
||
|
|
stored in a supplemental field for clients that support Unicode file names and a
|
||
|
|
ISO-8859-1 version of the file name is automatically generated.
|
||
|
|
|
||
|
|
This specifies the ISO-8859-1 file name to override the automatic generation or
|
||
|
|
disables the generation all together, defaults to `true`.
|
||
|
|
|
||
|
|
- A string will specify the ISO-8859-1 file name to use in place of automatic
|
||
|
|
generation.
|
||
|
|
- `false` will disable including a ISO-8859-1 file name and only include the
|
||
|
|
Unicode version (unless the file name is already ISO-8859-1).
|
||
|
|
- `true` will enable automatic generation if the file name is outside
|
||
|
|
ISO-8859-1.
|
||
|
|
|
||
|
|
If the `filename` option is ISO-8859-1 and this option is specified and has a
|
||
|
|
different value, then the `filename` option is encoded in the extended field and
|
||
|
|
this set as the fallback field, even though they are both ISO-8859-1.
|
||
|
|
|
||
|
|
##### `type`
|
||
|
|
|
||
|
|
Specifies the disposition type, defaults to `"attachment"`. This can also be
|
||
|
|
`"inline"`, or any other value (all values except inline are treated like
|
||
|
|
`attachment`, but can convey additional information if both parties agree to
|
||
|
|
it). The type is normalized to lower-case.
|
||
|
|
|
||
|
|
### `contentDisposition.parse(string)`
|
||
|
|
|
||
|
|
```js
|
||
|
|
contentDisposition.parse('attachment; filename="EURO rates.txt"; filename*=UTF-8\'\'%e2%82%ac%20rates.txt')
|
||
|
|
```
|
||
|
|
|
||
|
|
Parse a `Content-Disposition` header string. This automatically handles extended
|
||
|
|
("Unicode") parameters by decoding them and providing them under the standard
|
||
|
|
parameter name. This will return an object with the following properties
|
||
|
|
(examples are shown for the string
|
||
|
|
`'attachment; filename="EURO rates.txt"; filename*=UTF-8\'\'%e2%82%ac%20rates.txt'`):
|
||
|
|
|
||
|
|
- `type`: The disposition type (always lower case). Example: `'attachment'`
|
||
|
|
|
||
|
|
- `parameters`: An object of the parameters in the disposition (name of
|
||
|
|
parameter always lower case and extended versions replace non-extended
|
||
|
|
versions). Example: `{filename: "€ rates.txt"}`
|
||
|
|
|
||
|
|
## Example
|
||
|
|
|
||
|
|
This simple example shows how to use `accepts` to return a different typed
|
||
|
|
respond body based on what the client wants to accept. The server lists it's
|
||
|
|
preferences in order and will get back the best match between the client and
|
||
|
|
server.
|
||
|
|
|
||
|
|
```ts
|
||
|
|
import { contentDisposition } from '@tinyhttp/content-disposition'
|
||
|
|
import destroy from 'destroy'
|
||
|
|
import fs from 'node:fs'
|
||
|
|
import { createServer } from 'node:http'
|
||
|
|
import onFinished from 'on-finished'
|
||
|
|
|
||
|
|
const filePath = '/path/to/public/plans.pdf'
|
||
|
|
|
||
|
|
createServer((req, res) => {
|
||
|
|
res.setHeader('Content-Type', 'application/pdf')
|
||
|
|
res.setHeader('Content-Disposition', contentDisposition(filePath))
|
||
|
|
|
||
|
|
const stream = fs.createReadStream(filePath)
|
||
|
|
stream.pipe(res)
|
||
|
|
onFinished(res, () => destroy(stream))
|
||
|
|
})
|
||
|
|
```
|