1 | // Type definitions for multer 1.4
|
2 | // Project: https://github.com/expressjs/multer
|
3 | // Definitions by: jt000 <https://github.com/jt000>
|
4 | // vilicvane <https://github.com/vilic>
|
5 | // David Broder-Rodgers <https://github.com/DavidBR-SW>
|
6 | // Michael Ledin <https://github.com/mxl>
|
7 | // HyunSeob Lee <https://github.com/hyunseob>
|
8 | // Pierre Tchuente <https://github.com/PierreTchuente>
|
9 | // Oliver Emery <https://github.com/thrymgjol>
|
10 | // Piotr Błażejewicz <https://github.com/peterblazejewicz>
|
11 | // Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped
|
12 | import { Request, RequestHandler } from 'express';
|
13 | import { Readable } from 'stream';
|
14 |
|
15 | declare global {
|
16 | namespace Express {
|
17 | namespace Multer {
|
18 | /** Object containing file metadata and access information. */
|
19 | interface File {
|
20 | /** Name of the form field associated with this file. */
|
21 | fieldname: string;
|
22 | /** Name of the file on the uploader's computer. */
|
23 | originalname: string;
|
24 | /**
|
25 | * Value of the `Content-Transfer-Encoding` header for this file.
|
26 | * @deprecated since July 2015
|
27 | * @see RFC 7578, Section 4.7
|
28 | */
|
29 | encoding: string;
|
30 | /** Value of the `Content-Type` header for this file. */
|
31 | mimetype: string;
|
32 | /** Size of the file in bytes. */
|
33 | size: number;
|
34 | /**
|
35 | * A readable stream of this file. Only available to the `_handleFile`
|
36 | * callback for custom `StorageEngine`s.
|
37 | */
|
38 | stream: Readable;
|
39 | /** `DiskStorage` only: Directory to which this file has been uploaded. */
|
40 | destination: string;
|
41 | /** `DiskStorage` only: Name of this file within `destination`. */
|
42 | filename: string;
|
43 | /** `DiskStorage` only: Full path to the uploaded file. */
|
44 | path: string;
|
45 | /** `MemoryStorage` only: A Buffer containing the entire file. */
|
46 | buffer: Buffer;
|
47 | }
|
48 | }
|
49 |
|
50 | interface Request {
|
51 | /** `Multer.File` object populated by `single()` middleware. */
|
52 | file: Multer.File;
|
53 | /**
|
54 | * Array or dictionary of `Multer.File` object populated by `array()`,
|
55 | * `fields()`, and `any()` middleware.
|
56 | */
|
57 | files: {
|
58 | [fieldname: string]: Multer.File[];
|
59 | } | Multer.File[];
|
60 | }
|
61 | }
|
62 | }
|
63 |
|
64 | /**
|
65 | * Returns a Multer instance that provides several methods for generating
|
66 | * middleware that process files uploaded in `multipart/form-data` format.
|
67 | *
|
68 | * The `StorageEngine` specified in `storage` will be used to store files. If
|
69 | * `storage` is not set and `dest` is, files will be stored in `dest` on the
|
70 | * local file system with random names. If neither are set, files will be stored
|
71 | * in memory.
|
72 | *
|
73 | * In addition to files, all generated middleware process all text fields in
|
74 | * the request. For each non-file field, the `Request.body` object will be
|
75 | * populated with an entry mapping the field name to its string value, or array
|
76 | * of string values if multiple fields share the same name.
|
77 | */
|
78 | declare function multer(options?: multer.Options): multer.Multer;
|
79 |
|
80 | declare namespace multer {
|
81 | /**
|
82 | * @see {@link https://github.com/expressjs/multer#api}
|
83 | */
|
84 | interface Multer {
|
85 | /**
|
86 | * Returns middleware that processes a single file associated with the
|
87 | * given form field.
|
88 | *
|
89 | * The `Request` object will be populated with a `file` object containing
|
90 | * information about the processed file.
|
91 | *
|
92 | * @param fieldName Name of the multipart form field to process.
|
93 | */
|
94 | single(fieldName: string): RequestHandler;
|
95 | /**
|
96 | * Returns middleware that processes multiple files sharing the same field
|
97 | * name.
|
98 | *
|
99 | * The `Request` object will be populated with a `files` array containing
|
100 | * an information object for each processed file.
|
101 | *
|
102 | * @param fieldName Shared name of the multipart form fields to process.
|
103 | * @param maxCount Optional. Maximum number of files to process. (default: Infinity)
|
104 | * @throws `MulterError('LIMIT_UNEXPECTED_FILE')` if more than `maxCount` files are associated with `fieldName`
|
105 | */
|
106 | array(fieldName: string, maxCount?: number): RequestHandler;
|
107 | /**
|
108 | * Returns middleware that processes multiple files associated with the
|
109 | * given form fields.
|
110 | *
|
111 | * The `Request` object will be populated with a `files` object which
|
112 | * maps each field name to an array of the associated file information
|
113 | * objects.
|
114 | *
|
115 | * @param fields Array of `Field` objects describing multipart form fields to process.
|
116 | * @throws `MulterError('LIMIT_UNEXPECTED_FILE')` if more than `maxCount` files are associated with `fieldName` for any field.
|
117 | */
|
118 | fields(fields: ReadonlyArray<Field>): RequestHandler;
|
119 | /**
|
120 | * Returns middleware that processes all files contained in the multipart
|
121 | * request.
|
122 | *
|
123 | * The `Request` object will be populated with a `files` array containing
|
124 | * an information object for each processed file.
|
125 | */
|
126 | any(): RequestHandler;
|
127 | /**
|
128 | * Returns middleware that accepts only non-file multipart form fields.
|
129 | *
|
130 | * @throws `MulterError('LIMIT_UNEXPECTED_FILE')` if any file is encountered.
|
131 | */
|
132 | none(): RequestHandler;
|
133 | }
|
134 |
|
135 | /**
|
136 | * Returns a `StorageEngine` implementation configured to store files on
|
137 | * the local file system.
|
138 | *
|
139 | * A string or function may be specified to determine the destination
|
140 | * directory, and a function to determine filenames. If no options are set,
|
141 | * files will be stored in the system's temporary directory with random 32
|
142 | * character filenames.
|
143 | */
|
144 | function diskStorage(options: DiskStorageOptions): StorageEngine;
|
145 |
|
146 | /**
|
147 | * Returns a `StorageEngine` implementation configured to store files in
|
148 | * memory as `Buffer` objects.
|
149 | */
|
150 | function memoryStorage(): StorageEngine;
|
151 |
|
152 | type ErrorCode =
|
153 | | 'LIMIT_PART_COUNT'
|
154 | | 'LIMIT_FILE_SIZE'
|
155 | | 'LIMIT_FILE_COUNT'
|
156 | | 'LIMIT_FIELD_KEY'
|
157 | | 'LIMIT_FIELD_VALUE'
|
158 | | 'LIMIT_FIELD_COUNT'
|
159 | | 'LIMIT_UNEXPECTED_FILE';
|
160 |
|
161 | class MulterError extends Error {
|
162 | constructor(code: ErrorCode, field?: string);
|
163 | /** Name of the MulterError constructor. */
|
164 | name: string;
|
165 | /** Identifying error code. */
|
166 | code: ErrorCode;
|
167 | /** Descriptive error message. */
|
168 | message: string;
|
169 | /** Name of the multipart form field associated with this error. */
|
170 | field?: string;
|
171 | }
|
172 |
|
173 | /**
|
174 | * a function to control which files should be uploaded and which should be skipped
|
175 | * pass a boolean to indicate if the file should be accepted
|
176 | * pass an error if something goes wrong
|
177 | */
|
178 | interface FileFilterCallback {
|
179 | (error: Error): void;
|
180 | (error: null, acceptFile: boolean): void;
|
181 | }
|
182 |
|
183 | /** Options for initializing a Multer instance. */
|
184 | interface Options {
|
185 | /**
|
186 | * A `StorageEngine` responsible for processing files uploaded via Multer.
|
187 | * Takes precedence over `dest`.
|
188 | */
|
189 | storage?: StorageEngine;
|
190 | /**
|
191 | * The destination directory for uploaded files. If `storage` is not set
|
192 | * and `dest` is, Multer will create a `DiskStorage` instance configured
|
193 | * to store files at `dest` with random filenames.
|
194 | *
|
195 | * Ignored if `storage` is set.
|
196 | */
|
197 | dest?: string;
|
198 | /**
|
199 | * An object specifying various limits on incoming data. This object is
|
200 | * passed to Busboy directly, and the details of properties can be found
|
201 | * at https://github.com/mscdex/busboy#busboy-methods.
|
202 | */
|
203 | limits?: {
|
204 | /** Maximum size of each form field name in bytes. (Default: 100) */
|
205 | fieldNameSize?: number;
|
206 | /** Maximum size of each form field value in bytes. (Default: 1048576) */
|
207 | fieldSize?: number;
|
208 | /** Maximum number of non-file form fields. (Default: Infinity) */
|
209 | fields?: number;
|
210 | /** Maximum size of each file in bytes. (Default: Infinity) */
|
211 | fileSize?: number;
|
212 | /** Maximum number of file fields. (Default: Infinity) */
|
213 | files?: number;
|
214 | /** Maximum number of parts (non-file fields + files). (Default: Infinity) */
|
215 | parts?: number;
|
216 | /** Maximum number of headers. (Default: 2000) */
|
217 | headerPairs?: number;
|
218 | };
|
219 | /** Preserve the full path of the original filename rather than the basename. (Default: false) */
|
220 | preservePath?: boolean;
|
221 | /**
|
222 | * Optional function to control which files are uploaded. This is called
|
223 | * for every file that is processed.
|
224 | *
|
225 | * @param req The Express `Request` object.
|
226 | * @param file Object containing information about the processed file.
|
227 | * @param callback a function to control which files should be uploaded and which should be skipped.
|
228 | */
|
229 | fileFilter?(
|
230 | req: Request,
|
231 | file: Express.Multer.File,
|
232 | callback: FileFilterCallback,
|
233 | ): void;
|
234 | }
|
235 |
|
236 | /**
|
237 | * Implementations of this interface are responsible for storing files
|
238 | * encountered by Multer and returning information on how to access them
|
239 | * once stored. Implementations must also provide a method for removing
|
240 | * files in the event that an error occurs.
|
241 | */
|
242 | interface StorageEngine {
|
243 | /**
|
244 | * Store the file described by `file`, then invoke the callback with
|
245 | * information about the stored file.
|
246 | *
|
247 | * File contents are available as a stream via `file.stream`. Information
|
248 | * passed to the callback will be merged with `file` for subsequent
|
249 | * middleware.
|
250 | *
|
251 | * @param req The Express `Request` object.
|
252 | * @param file Object with `stream`, `fieldname`, `originalname`, `encoding`, and `mimetype` defined.
|
253 | * @param callback Callback to specify file information.
|
254 | */
|
255 | _handleFile(
|
256 | req: Request,
|
257 | file: Express.Multer.File,
|
258 | callback: (error?: any, info?: Partial<Express.Multer.File>) => void
|
259 | ): void;
|
260 | /**
|
261 | * Remove the file described by `file`, then invoke the callback with.
|
262 | *
|
263 | * `file` contains all the properties available to `_handleFile`, as
|
264 | * well as those returned by `_handleFile`.
|
265 | *
|
266 | * @param req The Express `Request` object.
|
267 | * @param file Object containing information about the processed file.
|
268 | * @param callback Callback to indicate completion.
|
269 | */
|
270 | _removeFile(
|
271 | req: Request,
|
272 | file: Express.Multer.File,
|
273 | callback: (error: Error | null) => void
|
274 | ): void;
|
275 | }
|
276 |
|
277 | interface DiskStorageOptions {
|
278 | /**
|
279 | * A string or function that determines the destination path for uploaded
|
280 | * files. If a string is passed and the directory does not exist, Multer
|
281 | * attempts to create it recursively. If neither a string or a function
|
282 | * is passed, the destination defaults to `os.tmpdir()`.
|
283 | *
|
284 | * @param req The Express `Request` object.
|
285 | * @param file Object containing information about the processed file.
|
286 | * @param callback Callback to determine the destination path.
|
287 | */
|
288 | destination?: string | ((
|
289 | req: Request,
|
290 | file: Express.Multer.File,
|
291 | callback: (error: Error | null, destination: string) => void
|
292 | ) => void);
|
293 | /**
|
294 | * A function that determines the name of the uploaded file. If nothing
|
295 | * is passed, Multer will generate a 32 character pseudorandom hex string
|
296 | * with no extension.
|
297 | *
|
298 | * @param req The Express `Request` object.
|
299 | * @param file Object containing information about the processed file.
|
300 | * @param callback Callback to determine the name of the uploaded file.
|
301 | */
|
302 | filename?(
|
303 | req: Request,
|
304 | file: Express.Multer.File,
|
305 | callback: (error: Error | null, filename: string) => void
|
306 | ): void;
|
307 | }
|
308 |
|
309 | /**
|
310 | * An object describing a field name and the maximum number of files with
|
311 | * that field name to accept.
|
312 | */
|
313 | interface Field {
|
314 | /** The field name. */
|
315 | name: string;
|
316 | /** Optional maximum number of files per field to accept. (Default: Infinity) */
|
317 | maxCount?: number;
|
318 | }
|
319 | }
|
320 |
|
321 | export = multer;
|