1 | // Type definitions for PapaParse 5.3
|
2 | // Project: https://github.com/mholt/PapaParse
|
3 | // Definitions by: Pedro Flemming <https://github.com/torpedro>
|
4 | // Rain Shen <https://github.com/rainshen49>
|
5 | // João Loff <https://github.com/jfloff>
|
6 | // John Reilly <https://github.com/johnnyreilly>
|
7 | // Alberto Restifo <https://github.com/albertorestifo>
|
8 | // Janne Liuhtonen <https://github.com/jliuhtonen>
|
9 | // Raphaël Barbazza <https://github.com/rbarbazz>
|
10 | // Piotr Błażejewicz <https://github.com/peterblazejewicz>
|
11 | // Emmanuel Gautier <https://github.com/emmanuelgautier>
|
12 | // Opportunity Liu <https://github.com/OpportunityLiu>
|
13 | // Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped
|
14 |
|
15 | /// <reference types="node" />
|
16 |
|
17 | export as namespace Papa;
|
18 |
|
19 | /**
|
20 | * Parse local files
|
21 | * @param file a File object obtained from the DOM.
|
22 | * @param config a config object which contains a callback.
|
23 | * @returns Doesn't return anything. Results are provided asynchronously to a callback function.
|
24 | */
|
25 | // tslint:disable-next-line: no-unnecessary-generics
|
26 | export function parse<T, TFile extends LocalFile = LocalFile>(file: TFile, config: ParseLocalConfig<T, TFile>): void;
|
27 | /**
|
28 | * Parse remote files
|
29 | * @param url the path or URL to the file to download.
|
30 | * @param config a config object.
|
31 | * @returns Doesn't return anything. Results are provided asynchronously to a callback function.
|
32 | */
|
33 | // tslint:disable-next-line: no-unnecessary-generics
|
34 | export function parse<T>(url: string, config: ParseRemoteConfig<T>): void;
|
35 | /**
|
36 | * Parse string in web worker
|
37 | * @param csvString a string of delimited text to be parsed.
|
38 | * @param config an optional config object.
|
39 | * @returns Doesn't return anything. Results are provided asynchronously to a callback function.
|
40 | */
|
41 | // tslint:disable-next-line: no-unnecessary-generics unified-signatures
|
42 | export function parse<T>(csvString: string, config: ParseWorkerConfig<T> & { download?: false | undefined }): void;
|
43 | /**
|
44 | * Parse string
|
45 | * @param csvString a string of delimited text to be parsed.
|
46 | * @param config an optional config object.
|
47 | * @returns a parse results object
|
48 | */
|
49 | export function parse<T>(
|
50 | csvString: string,
|
51 | config?: ParseConfig<T> & { download?: false | undefined; worker?: false | undefined },
|
52 | ): ParseResult<T>;
|
53 | /**
|
54 | * Parse string, remote files or local files
|
55 | * @param source data to be parsed.
|
56 | * @param config a config object.
|
57 | * @returns Doesn't return anything. Results are provided asynchronously to a callback function.
|
58 | */
|
59 | export function parse<T>(
|
60 | source: LocalFile | string,
|
61 | config: ParseLocalConfig<T, LocalFile> &
|
62 | (
|
63 | | (ParseConfig<T> & { download?: false | undefined; worker?: false | undefined })
|
64 | | (ParseWorkerConfig<T> & { download?: false | undefined })
|
65 | | ParseRemoteConfig<T>
|
66 | ),
|
67 | ): void;
|
68 | /**
|
69 | * Parse in a node streaming style
|
70 | * @param stream `NODE_STREAM_INPUT`
|
71 | * @param config a config object.
|
72 | * @returns a node stream.
|
73 | *
|
74 | * @see https://github.com/mholt/PapaParse#papa-parse-for-node
|
75 | */
|
76 | export function parse(stream: typeof NODE_STREAM_INPUT, config?: ParseConfig): NodeJS.ReadWriteStream;
|
77 |
|
78 | /**
|
79 | * Unparses javascript data objects and returns a csv string
|
80 | * @param data can be one of: An array of arrays; An array of objects; An object explicitly defining `fields` and `data`
|
81 | * @param config an optional config object
|
82 | */
|
83 | export function unparse<T>(data: T[] | UnparseObject<T>, config?: UnparseConfig): string;
|
84 |
|
85 | /**
|
86 | * Read-Only Properties
|
87 | */
|
88 |
|
89 | /** An array of characters that are not allowed as delimiters. `\r`, `\n`, `"`, `\ufeff` */
|
90 | export const BAD_DELIMITERS: ReadonlyArray<string>;
|
91 |
|
92 | /** The true delimiter. Invisible. ASCII code 30. Should be doing the job we strangely rely upon commas and tabs for. */
|
93 | export const RECORD_SEP: '\x1E';
|
94 |
|
95 | /** Also sometimes used as a delimiting character. ASCII code 31. */
|
96 | export const UNIT_SEP: '\x1F';
|
97 | /**
|
98 | * Whether or not the browser supports HTML5 Web Workers.
|
99 | * If false, `worker: true` will have no effect.
|
100 | */
|
101 | export const WORKERS_SUPPORTED: boolean;
|
102 |
|
103 | /**
|
104 | * When passed to Papa Parse a Readable stream is returned.
|
105 | */
|
106 | export const NODE_STREAM_INPUT: unique symbol;
|
107 |
|
108 | /**
|
109 | * Configurable Properties
|
110 | */
|
111 |
|
112 | /**
|
113 | * The size in bytes of each file chunk. Used when streaming files obtained from the DOM that exist on the local computer. Default 10 MB.
|
114 | * @default 10485760
|
115 | */
|
116 | export let LocalChunkSize: number;
|
117 |
|
118 | /**
|
119 | * Same as `LocalChunkSize`, but for downloading files from remote locations. Default 5 MB.
|
120 | * @default 5242880
|
121 | */
|
122 | export let RemoteChunkSize: number;
|
123 |
|
124 | /**
|
125 | * The delimiter used when it is left unspecified and cannot be detected automatically. Default is comma.
|
126 | * @default ','
|
127 | */
|
128 | export let DefaultDelimiter: string;
|
129 |
|
130 | /** File object */
|
131 | export type LocalFile = Blob | NodeJS.ReadableStream;
|
132 |
|
133 | /**
|
134 | * On Papa there are actually more classes exposed
|
135 | * but none of them are officially documented
|
136 | * Since we can interact with the Parser from one of the callbacks
|
137 | * I have included the API for this class.
|
138 | */
|
139 | export class Parser {
|
140 | constructor(config: ParseConfig);
|
141 |
|
142 | parse(input: string, baseIndex: number, ignoreLastRow: boolean): any;
|
143 |
|
144 | // Sets the abort flag
|
145 | abort(): void;
|
146 |
|
147 | // Gets the cursor position
|
148 | getCharIndex(): number;
|
149 |
|
150 | pause(): void;
|
151 | resume(): void;
|
152 | }
|
153 |
|
154 | export interface ParseConfig<T = any, TInput = undefined> {
|
155 | /**
|
156 | * The delimiting character.
|
157 | * Leave blank to auto-detect from a list of most common delimiters, or any values passed in through `delimitersToGuess`.
|
158 | * It can be a string or a function.
|
159 | * If a string, it can be of any length (so multi-character delimiters are supported).
|
160 | * If a function, it must accept the input as first parameter and it must return a string which will be used as delimiter.
|
161 | * In both cases it cannot be found in `Papa.BAD_DELIMITERS`.
|
162 | * @default // auto-detect
|
163 | */
|
164 | delimiter?: string | ((input: string) => string) | undefined;
|
165 | /**
|
166 | * The newline sequence. Leave blank to auto-detect. Must be one of `\r`, `\n`, or `\r\n`.
|
167 | * @default // auto-detect
|
168 | */
|
169 | newline?: '\r' | '\n' | '\r\n' | undefined;
|
170 | /**
|
171 | * The character used to quote fields. The quoting of all fields is not mandatory. Any field which is not quoted will correctly read.
|
172 | * @default '"'
|
173 | */
|
174 | quoteChar?: string | undefined;
|
175 | /**
|
176 | * The character used to escape the quote character within a field.
|
177 | * If not set, this option will default to the value of `quoteChar`,
|
178 | * meaning that the default escaping of quote character within a quoted field is using the quote character two times.
|
179 | * (e.g. `"column with ""quotes"" in text"`)
|
180 | * @default '"'
|
181 | */
|
182 | escapeChar?: string | undefined;
|
183 | /**
|
184 | * If `true`, the first row of parsed data will be interpreted as field names.
|
185 | * An array of field names will be returned in meta, and each row of data will be an object of values keyed by field name instead of a simple array.
|
186 | * Rows with a different number of fields from the header row will produce an error.
|
187 | * Warning: Duplicate field names will overwrite values in previous fields having the same name.
|
188 | * @default false
|
189 | */
|
190 | header?: boolean | undefined;
|
191 | /**
|
192 | * A function to apply on each header. Requires header to be true. The function receives the header as its first argument and the index as second.
|
193 | */
|
194 | transformHeader?(header: string, index: number): string;
|
195 | /**
|
196 | * If `true`, numeric and boolean data will be converted to their type instead of remaining strings.
|
197 | * Numeric data must conform to the definition of a decimal literal.
|
198 | * Numerical values greater than 2^53 or less than -2^53 will not be converted to numbers to preserve precision.
|
199 | * European-formatted numbers must have commas and dots swapped.
|
200 | * If also accepts an object or a function.
|
201 | * If object it's values should be a boolean to indicate if dynamic typing should be applied for each column number (or header name if using headers).
|
202 | * If it's a function, it should return a boolean value for each field number (or name if using headers) which will be passed as first argument.
|
203 | * @default false
|
204 | */
|
205 | dynamicTyping?:
|
206 | | boolean
|
207 | | { [headerName: string]: boolean; [columnNumber: number]: boolean }
|
208 | | ((field: string | number) => boolean)
|
209 | | undefined;
|
210 | /** If > 0, only that many rows will be parsed. */
|
211 | preview?: number | undefined;
|
212 | /**
|
213 | * A string that indicates a comment (for example, "#" or "//").
|
214 | * When Papa encounters a line starting with this string, it will skip the line.
|
215 | * @default false
|
216 | */
|
217 | comments?: false | string | undefined;
|
218 | /**
|
219 | * If `true`, lines that are completely empty (those which evaluate to an empty string) will be skipped.
|
220 | * If set to `'greedy'`, lines that don't have any content (those which have only whitespace after parsing) will also be skipped.
|
221 | * @default false
|
222 | */
|
223 | skipEmptyLines?: boolean | 'greedy' | undefined;
|
224 | /**
|
225 | * Fast mode speeds up parsing significantly for large inputs.
|
226 | * However, it only works when the input has no quoted fields.
|
227 | * Fast mode will automatically be enabled if no " characters appear in the input.
|
228 | * You can force fast mode either way by setting it to true or false.
|
229 | */
|
230 | fastMode?: boolean | undefined;
|
231 | /**
|
232 | * A function to apply on each value.
|
233 | * The function receives the value as its first argument and the column number or header name when enabled as its second argument.
|
234 | * The return value of the function will replace the value it received.
|
235 | * The transform function is applied before `dynamicTyping`.
|
236 | */
|
237 | transform?(value: string, field: string | number): any;
|
238 | /**
|
239 | * An array of delimiters to guess from if the delimiter option is not set.
|
240 | * @default [',', '\t', '|', ';', Papa.RECORD_SEP, Papa.UNIT_SEP]
|
241 | */
|
242 | delimitersToGuess?: string[] | undefined;
|
243 | /**
|
244 | * To stream the input, define a callback function.
|
245 | * Streaming is necessary for large files which would otherwise crash the browser.
|
246 | * You can call parser.abort() to abort parsing.
|
247 | * And, except when using a Web Worker, you can call parser.pause() to pause it, and parser.resume() to resume.
|
248 | */
|
249 | step?(results: ParseStepResult<T>, parser: Parser): void;
|
250 | /**
|
251 | * The callback to execute when parsing is complete.
|
252 | * It receives the parse results. If parsing a local file, the File is passed in, too.
|
253 | * When streaming, parse results are not available in this callback.
|
254 | */
|
255 | complete?(results: ParseResult<T>, file: TInput): void;
|
256 | /**
|
257 | * A function to execute before parsing the first chunk.
|
258 | * Can be used with chunk or step streaming modes.
|
259 | * The function receives as an argument the chunk about to be parsed, and it may return a modified chunk to parse.
|
260 | * This is useful for stripping header lines (as long as the header fits in a single chunk).
|
261 | */
|
262 | beforeFirstChunk?(chunk: string): string | void;
|
263 | }
|
264 |
|
265 | export interface ParseWorkerConfig<T = any> extends ParseConfig<T> {
|
266 | /**
|
267 | * Whether or not to use a worker thread.
|
268 | * Using a worker will keep your page reactive, but may be slightly slower.
|
269 | */
|
270 | worker: true;
|
271 | /**
|
272 | * The callback to execute when parsing is complete.
|
273 | * It receives the parse results. If parsing a local file, the File is passed in, too.
|
274 | * When streaming, parse results are not available in this callback.
|
275 | */
|
276 | complete(results: ParseResult<T>): void;
|
277 | }
|
278 |
|
279 | export interface ParseAsyncConfig<T = any, TInput = undefined> extends ParseConfig<T, TInput> {
|
280 | /**
|
281 | * Whether or not to use a worker thread.
|
282 | * Using a worker will keep your page reactive, but may be slightly slower.
|
283 | * @default false
|
284 | */
|
285 | worker?: boolean | undefined;
|
286 | /**
|
287 | * Overrides `Papa.LocalChunkSize` and `Papa.RemoteChunkSize`.
|
288 | */
|
289 | chunkSize?: number | undefined;
|
290 | /**
|
291 | * A callback function, identical to `step`, which activates streaming.
|
292 | * However, this function is executed after every chunk of the file is loaded and parsed rather than every row.
|
293 | * Works only with local and remote files.
|
294 | * Do not use both `chunk` and `step` callbacks together.
|
295 | */
|
296 | chunk?(results: ParseResult<T>, parser: Parser): void;
|
297 | /**
|
298 | * A callback to execute if FileReader encounters an error.
|
299 | * The function is passed two arguments: the error and the File.
|
300 | */
|
301 | error?(error: Error, file: TInput): void;
|
302 | /** @inheritdoc */
|
303 | complete(results: ParseResult<T>, file: TInput): void;
|
304 | }
|
305 |
|
306 | export interface ParseLocalConfig<T = any, TInput = undefined> extends ParseAsyncConfig<T, TInput> {
|
307 | /** The encoding to use when opening local files. If specified, it must be a value supported by the FileReader API. */
|
308 | encoding?: string | undefined;
|
309 | }
|
310 |
|
311 | export interface ParseRemoteConfig<T = any> extends ParseAsyncConfig<T, string> {
|
312 | /**
|
313 | * This indicates that the string you passed as the first argument to `parse()`
|
314 | * is actually a URL from which to download a file and parse its contents.
|
315 | */
|
316 | download: true;
|
317 | /**
|
318 | * If defined, should be an object that describes the headers.
|
319 | * @example { 'Authorization': 'token 123345678901234567890' }
|
320 | * @default undefined
|
321 | */
|
322 | downloadRequestHeaders?: { [headerName: string]: string } | undefined;
|
323 | /**
|
324 | * Use POST request on the URL of the download option. The value passed will be set as the body of the request.
|
325 | * @default undefined
|
326 | */
|
327 | downloadRequestBody?: Blob | BufferSource | FormData | URLSearchParams | string | undefined;
|
328 | /**
|
329 | * A boolean value passed directly into XMLHttpRequest's "withCredentials" property.
|
330 | * @default undefined
|
331 | */
|
332 | withCredentials?: boolean | undefined;
|
333 | }
|
334 |
|
335 | export interface UnparseConfig {
|
336 | /**
|
337 | * If `true`, forces all fields to be enclosed in quotes.
|
338 | * If an array of `true`/`false` values, specifies which fields should be force-quoted (first boolean is for the first column, second boolean for the second column, ...).
|
339 | * A function that returns a boolean values can be used to determine the quotes value of a cell.
|
340 | * This function accepts the cell value and column index as parameters.
|
341 | * Note that this option is ignored for `undefined`, `null` and `date-object` values.
|
342 | * The option `escapeFormulae` also takes precedence over this.
|
343 | *
|
344 | * @default false
|
345 | */
|
346 | quotes?: boolean | boolean[] | ((value: any, columnIndex: number) => boolean) | undefined;
|
347 | /**
|
348 | * The character used to quote fields.
|
349 | * @default '"'
|
350 | */
|
351 | quoteChar?: string | undefined;
|
352 | /**
|
353 | * The character used to escape `quoteChar` inside field values.
|
354 | * @default '"'
|
355 | */
|
356 | escapeChar?: string | undefined;
|
357 | /**
|
358 | * The delimiting character. Multi-character delimiters are supported. It must not be found in `Papa.BAD_DELIMITERS`.
|
359 | * @default ','
|
360 | */
|
361 | delimiter?: string | undefined;
|
362 | /**
|
363 | * If `false`, will omit the header row.
|
364 | * If `data` is an array of arrays this option is ignored.
|
365 | * If `data` is an array of objects the keys of the first object are the header row.
|
366 | * If `data` is an object with the `keys` fields and `data` the `fields` are the header row.
|
367 | * @default true
|
368 | */
|
369 | header?: boolean | undefined;
|
370 | /**
|
371 | * The character used to determine newline sequence.
|
372 | * @default '\r\n'
|
373 | */
|
374 | newline?: string | undefined;
|
375 | /**
|
376 | * If `true`, lines that are completely empty (those which evaluate to an empty string) will be skipped.
|
377 | * If set to `'greedy'`, lines that don't have any content (those which have only whitespace after parsing) will also be skipped.
|
378 | * @default false
|
379 | */
|
380 | skipEmptyLines?: boolean | 'greedy' | undefined;
|
381 | /**
|
382 | * If `data` is an array of objects this option can be used to manually specify the keys (columns) you expect in the objects.
|
383 | * If not set the keys of the first objects are used as column.
|
384 | * @default undefined
|
385 | */
|
386 | columns?: string[] | undefined;
|
387 | /**
|
388 | * If `true`, field values that begin with `=`, `+`, `-`, or `@`,
|
389 | * will be prepended with a ` to defend against [injection attacks](https://www.contextis.com/en/blog/comma-separated-vulnerabilities),
|
390 | * because Excel and LibreOffice will automatically parse such cells as formulae.
|
391 | * @default false
|
392 | */
|
393 | escapeFormulae?: boolean | RegExp | undefined;
|
394 | }
|
395 |
|
396 | export interface UnparseObject<T> {
|
397 | fields: string[];
|
398 | data: T[];
|
399 | }
|
400 |
|
401 | /** Error structure */
|
402 | export interface ParseError {
|
403 | /** A generalization of the error */
|
404 | type: 'Quotes' | 'Delimiter' | 'FieldMismatch';
|
405 | /** Standardized error code */
|
406 | code: 'MissingQuotes' | 'UndetectableDelimiter' | 'TooFewFields' | 'TooManyFields';
|
407 | /** Human-readable details */
|
408 | message: string;
|
409 | /** Row index of parsed data where error is */
|
410 | row: number;
|
411 | }
|
412 |
|
413 | export interface ParseMeta {
|
414 | /** Delimiter used */
|
415 | delimiter: string;
|
416 | /** Line break sequence used */
|
417 | linebreak: string;
|
418 | /** Whether process was aborted */
|
419 | aborted: boolean;
|
420 | /** Array of field names */
|
421 | fields?: string[] | undefined;
|
422 | /** Whether preview consumed all input */
|
423 | truncated: boolean;
|
424 | cursor: number;
|
425 | }
|
426 |
|
427 | /**
|
428 | * A parse result always contains three objects: data, errors, and meta.
|
429 | * Data and errors are arrays, and meta is an object. In the step callback, the data array will only contain one element.
|
430 | */
|
431 | export interface ParseStepResult<T> {
|
432 | /**
|
433 | * In the step callback, the data array will only contain one element.
|
434 | */
|
435 | data: T;
|
436 | /** an array of errors. */
|
437 | errors: ParseError[];
|
438 | /**
|
439 | * contains extra information about the parse, such as delimiter used,
|
440 | * the newline sequence, whether the process was aborted, etc.
|
441 | * Properties in this object are not guaranteed to exist in all situations.
|
442 | */
|
443 | meta: ParseMeta;
|
444 | }
|
445 |
|
446 | /**
|
447 | * A parse result always contains three objects: data, errors, and meta.
|
448 | * Data and errors are arrays, and meta is an object. In the step callback, the data array will only contain one element.
|
449 | */
|
450 | export interface ParseResult<T> {
|
451 | /**
|
452 | * an array of rows. If header is false, rows are arrays; otherwise they are objects of data keyed by the field name.
|
453 | */
|
454 | data: T[];
|
455 | /** an array of errors. */
|
456 | errors: ParseError[];
|
457 | /**
|
458 | * contains extra information about the parse, such as delimiter used,
|
459 | * the newline sequence, whether the process was aborted, etc.
|
460 | * Properties in this object are not guaranteed to exist in all situations.
|
461 | */
|
462 | meta: ParseMeta;
|
463 | }
|
464 |
|
\ | No newline at end of file |