0
# Type-Is
1

2
Type-Is is a Node.js utility library for inferring and checking the content-type of HTTP requests. It provides essential MIME type detection capabilities for web servers and Express.js applications, with support for wildcards, file extensions, and complex MIME type patterns.
3

4
## Package Information
5

6
- **Package Name**: type-is
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install type-is`
10

11
## Core Imports
12

13
```javascript
14
const typeis = require("type-is");
15
```
16

17
For ES modules:
18

19
```javascript
20
import typeis from "type-is";
21
// Properties are available on the default import
22
// typeis.is, typeis.hasBody, typeis.normalize, typeis.match
23
```
24

25
## Basic Usage
26

27
```javascript
28
const http = require("http");
29
const typeis = require("type-is");
30

31
http.createServer(function (req, res) {
32
  const isText = typeis(req, ["text/*"]);
33
  res.end("you " + (isText ? "sent" : "did not send") + " me text");
34
});
35

36
// Check if request has JSON content
37
if (typeis(req, ["json"])) {
38
  // Handle JSON data
39
}
40

41
// Check for multiple types
42
const bodyType = typeis(req, ["urlencoded", "json", "multipart"]);
43
switch (bodyType) {
44
  case "urlencoded":
45
    // Handle form data
46
    break;
47
  case "json":
48
    // Handle JSON data
49
    break;
50
  case "multipart":
51
    // Handle multipart data
52
    break;
53
}
54
```
55

56
## Capabilities
57

58
### Request Content-Type Checking
59

60
Check if an HTTP request matches one or more content types. Returns the first matching type, `false` if no match, or `null` if the request has no body.
61

62
```javascript { .api }
63
/**
64
 * Check if the incoming request contains the "Content-Type" header field,
65
 * and it contains any of the given mime types.
66
 * @param {Object} req - HTTP request object
67
 * @param {Array|String} types - Array of type strings or individual type arguments
68
 * @returns {String|false|null} First matching type, false if no match, null if no body
69
 */
70
function typeis(req, types);
71
```
72

73
**Usage Examples:**
74

75
```javascript
76
// With Content-Type: application/json
77
typeis(req, ["json"]); // => 'json'
78
typeis(req, ["html", "json"]); // => 'json'
79
typeis(req, ["application/*"]); // => 'application/json'
80
typeis(req, ["html"]); // => false
81

82
// No body (no transfer-encoding or content-length)
83
typeis(req, ["json"]); // => null
84
```
85

86
### Media Type String Checking
87

88
Check if a media type string matches one or more types without requiring a request object.
89

90
```javascript { .api }
91
/**
92
 * Check if a media type matches one or more types
93
 * @param {String|Object} mediaType - Media type string or request object
94
 * @param {Array|String} types - Array of type strings or individual type arguments
95
 * @returns {String|false} First matching type or false if no match
96
 */
97
typeis.is(mediaType, types);
98
```
99

100
**Usage Examples:**
101

102
```javascript
103
const mediaType = "application/json";
104

105
typeis.is(mediaType, ["json"]); // => 'json'
106
typeis.is(mediaType, ["html", "json"]); // => 'json'
107
typeis.is(mediaType, ["application/*"]); // => 'application/json'
108
typeis.is(mediaType, ["html"]); // => false
109

110
// Can also accept request objects
111
typeis.is(req, ["json"]); // Uses req.headers['content-type']
112
```
113

114
### Request Body Detection
115

116
Check if an HTTP request has a body, regardless of the Content-Type header.
117

118
```javascript { .api }
119
/**
120
 * Check if a request has a request body
121
 * @param {Object} req - HTTP request object
122
 * @returns {Boolean} true if request has body (transfer-encoding or content-length headers)
123
 */
124
typeis.hasBody(req);
125
```
126

127
**Usage Examples:**
128

129
```javascript
130
if (typeis.hasBody(req)) {
131
  // Read the body, since there is one
132
  req.on("data", function (chunk) {
133
    // Handle data chunks
134
  });
135
}
136
```
137

138
### Type Normalization
139

140
Normalize a type string by expanding shortcuts and mapping file extensions to MIME types.
141

142
```javascript { .api }
143
/**
144
 * Normalize a type string
145
 * @param {String} type - Type string to normalize
146
 * @returns {String|false} Normalized MIME type or false if invalid
147
 */
148
typeis.normalize(type);
149
```
150

151
**Usage Examples:**
152

153
```javascript
154
typeis.normalize("json"); // => 'application/json'
155
typeis.normalize("urlencoded"); // => 'application/x-www-form-urlencoded'
156
typeis.normalize("multipart"); // => 'multipart/*'
157
typeis.normalize("+json"); // => '*/*+json'
158
typeis.normalize("text/html"); // => 'text/html' (pass-through)
159
typeis.normalize("unknown"); // => false
160
```
161

162
### MIME Type Matching
163

164
Match an expected MIME type pattern against an actual MIME type with wildcard support.
165

166
```javascript { .api }
167
/**
168
 * Match expected type against actual type with wildcard support
169
 * @param {String} expected - Expected MIME type pattern (can contain wildcards)
170
 * @param {String} actual - Actual MIME type to match against
171
 * @returns {Boolean} true if types match
172
 */
173
typeis.match(expected, actual);
174
```
175

176
**Usage Examples:**
177

178
```javascript
179
typeis.match("text/html", "text/html"); // => true
180
typeis.match("*/html", "text/html"); // => true
181
typeis.match("text/*", "text/html"); // => true
182
typeis.match("*/*", "text/html"); // => true
183
typeis.match("*/*+json", "application/x-custom+json"); // => true
184
typeis.match("text/html", "text/plain"); // => false
185
```
186

187
## Type Formats
188

189
Type-Is supports various type format patterns:
190

191
### File Extensions
192
```javascript
193
typeis(req, ["json", "html", "png"]); // Mapped to MIME types
194
typeis(req, [".json", ".html"]); // Extensions with dots
195
```
196

197
### Full MIME Types
198
```javascript
199
typeis(req, ["application/json", "text/html", "image/png"]);
200
```
201

202
### Wildcard Patterns
203
```javascript
204
typeis(req, ["text/*"]); // Any text type
205
typeis(req, ["*/json"]); // Any type with json subtype
206
typeis(req, ["*/*"]); // Any type
207
```
208

209
### Suffix Patterns
210
```javascript
211
typeis(req, ["+json"]); // Any type ending with +json
212
typeis(req, ["application/*+xml"]); // Application types ending with +xml
213
```
214

215
### Special Shortcuts
216
```javascript
217
typeis(req, ["urlencoded"]); // => 'application/x-www-form-urlencoded'
218
typeis(req, ["multipart"]); // => 'multipart/*'
219
```
220

221
## Error Handling
222

223
- **Invalid MIME types**: Return `false`
224
- **Non-string inputs to normalize**: Return `false`
225
- **Malformed type patterns**: Return `false`
226
- **Missing Content-Type header**: Return `false` (or `null` for requests without body)
227
- **Request without body**: Return `null` for main `typeis()` function
228

229
## Types
230

231
```javascript { .api }
232
// Request object structure (Node.js HTTP request)
233
interface Request {
234
  headers: {
235
    'content-type'?: string;
236
    'transfer-encoding'?: string;
237
    'content-length'?: string;
238
    [key: string]: string | undefined;
239
  };
240
}
241

242
// Type strings can be:
243
type TypeString = 
244
  | string          // File extension: 'json', 'html'
245
  | string          // MIME type: 'application/json', 'text/html'
246
  | string          // Wildcard: 'text/*', '*/json', '*/*'
247
  | string          // Suffix: '+json', 'application/*+xml'
248
  | string;         // Special: 'urlencoded', 'multipart'
249

250
// Function argument types
251
type TypesArgument = TypeString | TypeString[];
252
```