feat(csv-parse): add generic type argument

This is based on the columns option.
When falsy, the records are string[][].
When defined, the records are T[], T defaulting to unknown.

Fix #407

Author: tusbar

packages/csv-parse/lib/index.d.ts

@@ -4,7 +4,7 @@
 
 import * as stream from "stream";
 
-export type Callback = (err: CsvError | undefined, records: any | undefined, info: Info) => void;
+export type Callback<T = unknown> = (err: CsvError | undefined, records: T[] | undefined, info?: Info) => void;
 
 export interface Parser extends stream.Transform {}
 
@@ -274,10 +274,18 @@ export class CsvError extends Error {
     constructor(code: CsvErrorCode, message: string | string[], options?: Options, ...contexts: any[]);
 }
 
-declare function parse(input: Buffer | string, options?: Options, callback?: Callback): Parser;
-declare function parse(input: Buffer | string, callback?: Callback): Parser;
-declare function parse(options?: Options, callback?: Callback): Parser;
-declare function parse(callback?: Callback): Parser;
+type OptionsWithColumns = Omit<Options, 'columns'> & {
+    columns: Exclude<Options['columns'], undefined | false>
+}
+
+declare function parse<T = unknown>(input: string | Buffer, options: OptionsWithColumns, callback?: Callback<T>): Parser;
+declare function parse<T = unknown>(input: string | Buffer, options: Options, callback?: Callback<string[]>): Parser;
+
+declare function parse<T = unknown>(options: OptionsWithColumns, callback?: Callback<T>): Parser;
+declare function parse<T = unknown>(options: Options, callback?: Callback<string[]>): Parser;
+
+declare function parse(input: string | Buffer, callback?: Callback<string[]>): Parser;
+declare function parse(callback?: Callback<string[]>): Parser;
 
 // export default parse;
 export { parse }

packages/csv-parse/lib/sync.d.ts

@@ -1,7 +1,14 @@
 
 import { Options } from './index.js';
 
-declare function parse(input: Buffer | string, options?: Options): any;
+type OptionsWithColumns = Omit<Options, 'columns'> & {
+  columns: Exclude<Options['columns'], undefined | false>
+}
+
+declare function parse<T = unknown>(input: Buffer | string, options: OptionsWithColumns): T[];
+declare function parse(input: Buffer | string, options: Options): string[][];
+declare function parse(input: Buffer | string): string[][];
+
 // export default parse;
 export { parse };
 

packages/csv-parse/test/api.types.sync.ts

@@ -6,19 +6,20 @@ import {
   ColumnOption, Options, Info, CsvErrorCode, CsvError
 } from '../lib/sync.js'
 
-describe('API Types', () => {
+describe('API Types - Sync', () => {
 
   it('respect parse signature', () => {
     // No argument
     parse("")
     parse("", {})
     parse(Buffer.from(""))
     parse(Buffer.from(""), {})
+    parse(Buffer.from(""), {columns: true})
   })
 
   it('return records', () => {
     try {
-      const records: object = parse("")
+      const records = parse("")
       typeof records
     }catch (err){
       if (err instanceof CsvError){
@@ -89,5 +90,31 @@ describe('API Types', () => {
     };
     return info;
   })
-  
+
+  describe('Generic types', () => {
+    it('Exposes string[][] if columns is not specified', () => {
+      const data: string[][] = parse("", {})
+    })
+
+    it('Exposes string[][] if columns is falsy', () => {
+      const data: string[][] = parse("", {
+        columns: false
+      })
+    })
+
+    it('Exposes unknown[] if columns is specified as boolean', () => {
+      const data: unknown[] = parse("", {
+        columns: true
+      })
+    })
+
+    it('Exposes T[] if columns is specified', () => {
+      type Person = {name: string, age: number}
+
+      const data: Person[] = parse<Person>("", {
+        columns: true
+      })
+    })
+  })
+
 })

packages/csv-parse/test/api.types.ts

@@ -1,7 +1,6 @@
 
 import 'should'
 import { parse, CastingContext, Info, Options, Parser, CsvError } from '../lib/index.js'
-import { parse as parse_sync } from '../lib/sync.js'
 
 describe('API Types', () => {
 
@@ -52,40 +51,16 @@ describe('API Types', () => {
     })
 
     it('Receive Callback', (next) => {
-      parse('a\nb', function(err: Error|undefined, records: object, info: Info){
+      parse('a\nb', function(err, records, info){
         if(err !== undefined){
-          records.should.eql([['a'], ['b']])
-          info.records.should.eql(2)
+          records!.should.eql([['a'], ['b']])
+          info!.records.should.eql(2)
         }
         next(err)
       })
     })
-    
-  })
-  
-  describe('sync api', () => {
-  
-    it('respect parse signature', () => {
-      // No argument
-      parse_sync("")
-      parse_sync("", {})
-      parse_sync(Buffer.from(""))
-      parse_sync(Buffer.from(""), {})
-    })
-    
-    it('return records', () => {
-      try {
-        const records: object = parse_sync("")
-        typeof records
-      }catch (err){
-        if (err instanceof CsvError){
-          err.message
-        }
-      }
-    })
-    
   })
-  
+
   describe('Info', () => {
 
     const fakeinfo = {
@@ -395,4 +370,39 @@ describe('API Types', () => {
       })
     })
   })
+
+  describe('Generic types', () => {
+    it('Exposes string[][] if columns is not specified', (next) => {
+      parse("", {}, (error, records: string[][] | undefined)  => {
+        next(error)
+      })
+    })
+
+    it('Exposes string[][] if columns is falsy', (next) => {
+      parse("", {
+        columns: false
+      }, (error, records: string[][] | undefined) => {
+        next(error)
+      })
+    })
+
+    it('Exposes unknown[] if columns is specified as boolean', (next) => {
+      parse("", {
+        columns: true
+      }, (error, records: unknown[] | undefined) => {
+        next(error)
+      })
+    })
+
+    it('Exposes T[] if columns is specified', (next) => {
+      type Person = {name: string, age: number}
+
+      parse<Person>("", {
+        columns: true
+      }, (error, records: Person[] | undefined) => {
+        next(error)
+      })
+    })
+  })
+
 })