From 3678dff8c00cc592bd4ae0a0277aa468e51355d3 Mon Sep 17 00:00:00 2001 From: Adam Voss Date: Wed, 19 Jul 2017 20:35:32 -0500 Subject: [PATCH 1/3] Add TypeScript type declaration file This provides completion information for users of both JavaScript and TypeScript with supported editors. This also allows TypeScript users to have type checking and be able to use the library when strict checking is enabled (which is the default for new TS projects). --- index.d.ts | 159 +++++++++++++++++++++++++++++++++++++++++++++++++++ package.json | 1 + 2 files changed, 160 insertions(+) create mode 100644 index.d.ts diff --git a/index.d.ts b/index.d.ts new file mode 100644 index 00000000..2cc0098d --- /dev/null +++ b/index.d.ts @@ -0,0 +1,159 @@ +// Type definitions for fast-csv 2.4 +// Project: http://c2fo.github.com/fast-csv/index.html +// Documentations comments derived from https://github.com/C2FO/fast-csv/blob/master/README.md + +/*~ Note that ES6 modules cannot directly export callable functions. + *~ This file should be imported using the CommonJS-style: + *~ import x = require('someLibrary'); + *~ + *~ Refer to the documentation to understand common + *~ workarounds for this limitation of ES6 modules. + */ + +/// +import * as stream from 'stream'; + +export = fast_csv; + +declare function fast_csv(): ParserStream; + +declare namespace fast_csv { + // Circular reference from fast_csv + function parse(): ParserStream; + + /* Intentionally omitted, because it is not documented by the project and + * the implementation currently creates a FormattingStream + */ + // function createReadStream(options?: ParsingOptions): ParserStream; + + function createWriteStream(options?: FormattingOptions): CsvTransformStream; + + function format(options?: FormattingOptions): CsvTransformStream; + + function fromPath(location: string, options?: ParsingOptions): ParserStream; + + function fromStream(stream: NodeJS.ReadableStream, options?: ParsingOptions): ParserStream; + + function fromString(string: string, options?: ParsingOptions): ParserStream; + + function write(arr: any[], options: FormattingOptions | undefined, ws?: NodeJS.WritableStream): CsvTransformStream; + + function writeToBuffer(arr: Buffer, options: FormattingOptions | undefined, cb: ((error: any, next?: any) => void)): void; + + function writeToPath(path: string, arr: any[], options?: FormattingOptions): stream.Writable; + + function writeToStream(ws: T, arr: any[], options?: FormattingOptions): T; + + function writeToString(arr: any[], options: FormattingOptions | undefined, cb: ((error: any, next?: any) => void)): void; +} + +declare class ParserStream extends stream.Transform { + validate(f: ((data: any, cb: (error: any, next?: any) => void) => void) | ((data: any) => boolean)): ParserStream; + transform(f: ((data: any, cb: (error: any, next?: any) => void) => void) | ((data: any) => any)): ParserStream; +} + +declare class CsvTransformStream extends stream.Transform { + transform(f: ((data: any, cb: (error: any, next?: any) => void) => void) | ((data: any) => boolean)): CsvTransformStream; +} + +interface HeaderQuoteOptions { + [headerName: string]: boolean; +} + +interface FormattingOptions extends GeneralOptions { + /** + * function that accepts a row and returns a transformed one to be written. + */ + transform?: ((row: any) => any) | ((row: any, callback: (error: any, next?: any) => void) => void); + + /** + * Specify an alternate row delimiter (i.e `\r\n`) + */ + rowDelimiter?: string; + + /** + * If `true` then all headers will be quoted. + * If it is an object then each key that has a true value will be quoted + * If it is an array then each item in the array that is true will have the header at the corresponding index quoted + */ + quoteHeaders?: boolean | HeaderQuoteOptions | boolean[]; + + /** + * If `true` then columns and headers will be quoted (unless `quoteHeaders` is specified). + * If it is an object then each key that has a true value will be quoted (unless `quoteHeaders` is specified) + * If it is an array then each item in the array that is true will have the column at the corresponding index quoted (unless `quoteHeaders` is specified) + */ + quoteColumns?: boolean | HeaderQuoteOptions | boolean[]; +} + +interface ParsingOptions extends GeneralOptions { + /** + * If you want to trim all values parsed set to `true` + */ + trim?: boolean; + + /** + * If you want to right trim all values parsed set to `true`. + */ + rtrim?: boolean; + + /** + * If you want to left trim all values parsed set to `true`. + */ + ltrim?: boolean; + + /** + * If your CSV contains comments you can use this option to ignore lines that begin with the specified character (e.g. `#`) + */ + comment?: string; +} + +interface GeneralOptions { + /** + * Ensure that data events have an object emitted rather than the stringified version set to false to have a stringified buffer + */ + objectMode?: boolean; + + /** + * Set to `true` if you expect the first line of your CSV to contain headers + * Alternately, you can specify an array of headers to use. + * You can also specify a sparse array to omit some of the columns. + */ + headers?: boolean | string[] | Array; + + /** + * If you wish to ignore empty rows. + */ + ignoreEmpty?: boolean; + + /** + * If you want to discard columns that do not map to a header. + */ + discardUnmappedColumns?: boolean; + + /** + * If you want to consider empty lines/lines with too few fields as errors - Only to be used with `headers=true` + */ + strictColumnHandling?: boolean; + + /** + * If you want the first line of the file to be removed and replaced by the one provided in the `headers` option - Only to be used with `headers=[String]` + */ + renameHeaders?: boolean; + + /** + * If your data uses an alternate delimiter such as ; or \t. + */ + delimiter?: string; + + /** + * The character to use to escape values that contain a delimiter. If you set to `null` then all quoting will be ignored + */ + quote?: string; + + /** + * The character to use when escaping a value that is `quoted` and contains a `quote` character. + * i.e: 'First,"Name"'; + */ + escape?: string; +} diff --git a/package.json b/package.json index d71de13a..86e37a36 100644 --- a/package.json +++ b/package.json @@ -3,6 +3,7 @@ "version": "2.4.0", "description": "CSV parser and writer", "main": "index.js", + "types": "index.d.ts", "scripts": { "test": "grunt jshint it" }, From 25e648cf65c18008a8cbcd29ae2948c9b4c87935 Mon Sep 17 00:00:00 2001 From: Adam Voss Date: Wed, 19 Jul 2017 22:33:43 -0500 Subject: [PATCH 2/3] Specify more specific types for callback parameters --- index.d.ts | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/index.d.ts b/index.d.ts index 2cc0098d..0f7058b1 100644 --- a/index.d.ts +++ b/index.d.ts @@ -38,13 +38,13 @@ declare namespace fast_csv { function write(arr: any[], options: FormattingOptions | undefined, ws?: NodeJS.WritableStream): CsvTransformStream; - function writeToBuffer(arr: Buffer, options: FormattingOptions | undefined, cb: ((error: any, next?: any) => void)): void; + function writeToBuffer(arr: Buffer, options: FormattingOptions | undefined, cb: ((error: any, result: Buffer) => void)): void; function writeToPath(path: string, arr: any[], options?: FormattingOptions): stream.Writable; function writeToStream(ws: T, arr: any[], options?: FormattingOptions): T; - function writeToString(arr: any[], options: FormattingOptions | undefined, cb: ((error: any, next?: any) => void)): void; + function writeToString(arr: any[], options: FormattingOptions | undefined, cb: ((error: any, result: string) => void)): void; } declare class ParserStream extends stream.Transform { From 8ef0e936ca7d9871c19bb9440e910e5d10abfd4a Mon Sep 17 00:00:00 2001 From: Eric Kidd Date: Fri, 21 Jul 2017 15:03:18 -0500 Subject: [PATCH 3/3] Correct parameters for `parse` in type definition Committer's note: @emk explicitly outlined these changed on GitHub, set him as author in way of attribution. --- index.d.ts | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/index.d.ts b/index.d.ts index 0f7058b1..7c7c63cf 100644 --- a/index.d.ts +++ b/index.d.ts @@ -15,11 +15,11 @@ import * as stream from 'stream'; export = fast_csv; -declare function fast_csv(): ParserStream; +declare function fast_csv(options?: ParsingOptions): ParserStream; declare namespace fast_csv { // Circular reference from fast_csv - function parse(): ParserStream; + function parse(options?: ParsingOptions): ParserStream; /* Intentionally omitted, because it is not documented by the project and * the implementation currently creates a FormattingStream