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