1 | /// <reference types="node" />
|
2 |
|
3 | import { Stream, Writable } from "stream";
|
4 | import Formidable = require("./Formidable");
|
5 | import parsers = require("./parsers/index");
|
6 | import PersistentFile = require("./PersistentFile");
|
7 | import VolatileFile = require("./VolatileFile");
|
8 | import errors = require("./FormidableError");
|
9 |
|
10 | declare namespace formidable {
|
11 | type BufferEncoding =
|
12 | | "ascii"
|
13 | | "base64"
|
14 | | "binary"
|
15 | | "hex"
|
16 | | "latin1"
|
17 | | "ucs-2"
|
18 | | "ucs2"
|
19 | | "utf-8"
|
20 | | "utf16le"
|
21 | | "utf8";
|
22 |
|
23 | type EventNames =
|
24 | /**
|
25 | * Emitted when the request was aborted by the user. Right now this can be due to a 'timeout' or
|
26 | * 'close' event on the socket. After this event is emitted, an error event will follow. In the
|
27 | * future there will be a separate 'timeout' event (needs a change in the node core).
|
28 | *
|
29 | * @link https://github.com/node-formidable/formidable#aborted
|
30 | */
|
31 | | "aborted"
|
32 | /**
|
33 | * Emitted when the entire request has been received, and all contained files have finished
|
34 | * flushing to disk. This is a great place for you to send your response.
|
35 | *
|
36 | * @link https://github.com/node-formidable/formidable#end
|
37 | */
|
38 | | "end"
|
39 | /**
|
40 | * Emitted when there is an error processing the incoming form. A request that experiences an
|
41 | * error is automatically paused, you will have to manually call request.resume() if you want the
|
42 | * request to continue firing 'data' events.
|
43 | *
|
44 | * @link https://github.com/node-formidable/formidable#error
|
45 | */
|
46 | | "error"
|
47 | /**
|
48 | * Emitted whenever a field / value pair has been received.
|
49 | *
|
50 | * @link https://github.com/node-formidable/formidable#field
|
51 | */
|
52 | | "field"
|
53 | /**
|
54 | * Emitted whenever a field / file pair has been received. file is an instance of File.
|
55 | *
|
56 | * @link https://github.com/node-formidable/formidable#file-1
|
57 | */
|
58 | | "file"
|
59 | /**
|
60 | * Emitted whenever a new file is detected in the upload stream. Use this event if you want to
|
61 | * stream the file to somewhere else while buffering the upload on the file system.
|
62 | *
|
63 | * @link https://github.com/node-formidable/formidable#filebegin
|
64 | */
|
65 | | "fileBegin"
|
66 | | "headerEnd"
|
67 | | "headerField"
|
68 | | "headersEnd"
|
69 | | "headerValue"
|
70 | | "partBegin"
|
71 | | "partData"
|
72 | /**
|
73 | * Emitted after each incoming chunk of data that has been parsed. Can be used to roll your own
|
74 | * progress bar.
|
75 | *
|
76 | * @link https://github.com/node-formidable/formidable#progress
|
77 | */
|
78 | | "progress";
|
79 |
|
80 | interface Options {
|
81 | /**
|
82 | * sets encoding for incoming form fields
|
83 | *
|
84 | * @default 'utf-8'
|
85 | */
|
86 | encoding?: BufferEncoding | undefined;
|
87 |
|
88 | /**
|
89 | * the directory for placing file uploads in. You can move them later by using fs.rename()
|
90 | *
|
91 | * @default os.tmpdir()
|
92 | */
|
93 | uploadDir?: string | undefined;
|
94 |
|
95 | /**
|
96 | * to include the extensions of the original files or not
|
97 | *
|
98 | * @default false
|
99 | */
|
100 | keepExtensions?: boolean | undefined;
|
101 |
|
102 | /**
|
103 | * allow upload empty files
|
104 | *
|
105 | * @default true
|
106 | */
|
107 | allowEmptyFiles?: boolean | undefined;
|
108 |
|
109 | /**
|
110 | * the minium size of uploaded file
|
111 | *
|
112 | * @default 1
|
113 | */
|
114 | minFileSize?: number | undefined;
|
115 |
|
116 | /**
|
117 | * limit the amount of uploaded files, set Infinity for unlimited
|
118 | *
|
119 | * @default Infinity
|
120 | */
|
121 | maxFiles?: number | undefined;
|
122 |
|
123 | /**
|
124 | * limit the size of uploaded file
|
125 | *
|
126 | * @default 200 * 1024 * 1024
|
127 | */
|
128 | maxFileSize?: number | undefined;
|
129 |
|
130 | /**
|
131 | * limit the size of the batch of uploaded files
|
132 | *
|
133 | * @default options.maxFileSize
|
134 | */
|
135 | maxTotalFileSize?: number | undefined;
|
136 |
|
137 | /**
|
138 | * limit the number of fields, set 0 for unlimited
|
139 | *
|
140 | * @default 1000
|
141 | */
|
142 | maxFields?: number | undefined;
|
143 |
|
144 | /**
|
145 | * limit the amount of memory all fields together (except files) can allocate in bytes
|
146 | *
|
147 | * @default 20 * 1024 * 1024
|
148 | */
|
149 | maxFieldsSize?: number | undefined;
|
150 |
|
151 | /**
|
152 | * include checksums calculated for incoming files, set this to some hash algorithm, see
|
153 | * crypto.createHash for available algorithms
|
154 | *
|
155 | * @default false
|
156 | */
|
157 | hashAlgorithm?: string | false | undefined;
|
158 |
|
159 | /**
|
160 | * which by default writes to host machine file system every file parsed; The function should
|
161 | * return an instance of a Writable stream that will receive the uploaded file data. With this
|
162 | * option, you can have any custom behavior regarding where the uploaded file data will be
|
163 | * streamed for. If you are looking to write the file uploaded in other types of cloud storages
|
164 | * (AWS S3, Azure blob storage, Google cloud storage) or private file storage, this is the option
|
165 | * you're looking for. When this option is defined the default behavior of writing the file in the
|
166 | * host machine file system is lost.
|
167 | *
|
168 | * @default null
|
169 | */
|
170 | fileWriteStreamHandler?: ((file?: VolatileFile) => Writable) | undefined;
|
171 |
|
172 | /**
|
173 | * when you call the .parse method, the files argument (of the callback) will contain arrays of
|
174 | * files for inputs which submit multiple files using the HTML5 multiple attribute. Also, the
|
175 | * fields argument will contain arrays of values for fields that have names ending with '[]'
|
176 | *
|
177 | * @default false
|
178 | */
|
179 | multiples?: boolean | undefined;
|
180 |
|
181 | /**
|
182 | * If true, makes direct folder uploads possible.
|
183 | *
|
184 | * @default false
|
185 | */
|
186 | createDirsFromUploads?: boolean | undefined;
|
187 |
|
188 | /**
|
189 | * Use it to control newFilename. Must return a string. Will be joined with
|
190 | * options.uploadDir.
|
191 | *
|
192 | * @default undefined
|
193 | */
|
194 | filename?: (name: string, ext: string, part: Part, form: Formidable) => string;
|
195 |
|
196 | enabledPlugins?: string[] | undefined;
|
197 |
|
198 | filter?: (part: Part) => boolean;
|
199 | }
|
200 |
|
201 | type Fields<T extends string = string> = {
|
202 | readonly [Prop in T]?: string[];
|
203 | };
|
204 | type Files<U extends string = string> = {
|
205 | readonly [Prop in U]?: File[];
|
206 | };
|
207 |
|
208 | interface Part extends Stream {
|
209 | name: string | null;
|
210 | originalFilename: string | null;
|
211 | mimetype: string | null;
|
212 | }
|
213 |
|
214 | /**
|
215 | * @link https://github.com/node-formidable/formidable#file
|
216 | */
|
217 | interface FileJSON
|
218 | extends Pick<File, "size" | "filepath" | "originalFilename" | "mimetype" | "hash" | "newFilename">
|
219 | {
|
220 | length: number;
|
221 | mimetype: string | null;
|
222 | mtime: Date | null;
|
223 | }
|
224 |
|
225 | interface File {
|
226 | /**
|
227 | * The size of the uploaded file in bytes. If the file is still being uploaded (see `'fileBegin'`
|
228 | * event), this property says how many bytes of the file have been written to disk yet.
|
229 | */
|
230 | size: number;
|
231 |
|
232 | /**
|
233 | * The path this file is being written to. You can modify this in the `'fileBegin'` event in case
|
234 | * you are unhappy with the way formidable generates a temporary path for your files.
|
235 | */
|
236 | filepath: string;
|
237 |
|
238 | /**
|
239 | * The name this file had according to the uploading client.
|
240 | */
|
241 | originalFilename: string | null;
|
242 |
|
243 | /**
|
244 | * Calculated based on options provided
|
245 | */
|
246 | newFilename: string;
|
247 |
|
248 | /**
|
249 | * The mime type of this file, according to the uploading client.
|
250 | */
|
251 | mimetype: string | null;
|
252 |
|
253 | /**
|
254 | * A Date object (or `null`) containing the time this file was last written to. Mostly here for
|
255 | * compatibility with the [W3C File API Draft](http://dev.w3.org/2006/webapi/FileAPI/).
|
256 | */
|
257 | mtime?: Date | null | undefined;
|
258 |
|
259 | hashAlgorithm: false | "sha1" | "md5" | "sha256";
|
260 |
|
261 | /**
|
262 | * If `options.hashAlgorithm` calculation was set, you can read the hex digest out of this var
|
263 | * (at the end it will be a string).
|
264 | */
|
265 | hash?: string | null;
|
266 |
|
267 | /**
|
268 | * This method returns a JSON-representation of the file, allowing you to JSON.stringify() the
|
269 | * file which is useful for logging and responding to requests.
|
270 | *
|
271 | * @link https://github.com/node-formidable/formidable#filetojson
|
272 | */
|
273 | toJSON(): FileJSON;
|
274 |
|
275 | toString(): string;
|
276 | }
|
277 |
|
278 | interface EmitData {
|
279 | formname: any;
|
280 | key?: string | number | undefined;
|
281 | name: "fileBegin" | "file";
|
282 | value: File | string;
|
283 | }
|
284 |
|
285 | interface EventData {
|
286 | name: EventNames;
|
287 | buffer: string;
|
288 | end: string;
|
289 | formname: string;
|
290 | key: string;
|
291 | start: string;
|
292 | value: string;
|
293 | }
|
294 |
|
295 | type PluginFunction = (formidable: Formidable, options: Partial<Options>) => void;
|
296 |
|
297 | type MappedParsers = {
|
298 | [P in keyof typeof parsers]: typeof parsers[P];
|
299 | };
|
300 |
|
301 | type Plugins = ["octetstream", "querystring", "multipart", "json"];
|
302 |
|
303 | type Plugin = keyof { [K in Plugins[number]]: K };
|
304 |
|
305 | type DefaultOptions = Required<Omit<Options, "enabledPlugins">> & {
|
306 | enabledPlugins: EnabledPlugins;
|
307 | };
|
308 |
|
309 | type EnabledPlugins = {
|
310 | [P in Plugin]: PluginFunction;
|
311 | };
|
312 | }
|
313 |
|
314 | declare const formidable: {
|
315 | (options?: formidable.Options): Formidable;
|
316 | defaultOptions: formidable.DefaultOptions;
|
317 | enabledPlugins: formidable.EnabledPlugins;
|
318 | plugins: formidable.EnabledPlugins;
|
319 | errors: typeof errors;
|
320 | File: typeof PersistentFile;
|
321 | PersistentFile: typeof PersistentFile;
|
322 | VolatileFile: typeof VolatileFile;
|
323 | Formidable: typeof Formidable;
|
324 | formidable: (options?: formidable.Options) => Formidable;
|
325 | // alias
|
326 | IncomingForm: typeof Formidable;
|
327 | // parsers and mapped parsers
|
328 | parsers: typeof parsers;
|
329 | } & formidable.MappedParsers;
|
330 |
|
331 | export = formidable;
|