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.
Restrict columns to keyof T.
Update onRecord / on_record to take and return type T.

Fix #278
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 = string[]> = (err: CsvError | undefined, records: T[] | undefined, info?: Info) => void;
 
 export interface Parser extends stream.Transform {}
 
@@ -36,14 +36,14 @@ export type CastingFunction = (value: string, context: CastingContext) => any;
 
 export type CastingDateFunction = (value: string, context: CastingContext) => Date;
 
-export type ColumnOption = string | undefined | null | false | { name: string };
+export type ColumnOption<K = string> = K | undefined | null | false | { name: K };
 
 /*
 Note, could not `extends stream.TransformOptions` because encoding can be
 BufferEncoding and undefined as well as null which is not defined in the
 extended type.
 */
-export interface Options {
+export interface Options<T = string[]> {
     /**
      * If true, the parser will attempt to convert read data types to native types.
      * @deprecated Use {@link cast}
@@ -77,7 +77,10 @@ export interface Options {
      * default to null,
      * affect the result data set in the sense that records will be objects instead of arrays.
      */
-    columns?: ColumnOption[] | boolean | ((record: any) => ColumnOption[]);
+    columns?:
+        boolean |
+        ColumnOption<T extends string[] ? string : keyof T>[] |
+        ((record: T) => ColumnOption<T extends string[] ? string : keyof T>[]);
     /**
      * Convert values into an array of values when columns are activated and
      * when multiple columns of the same name are found.
@@ -142,8 +145,8 @@ export interface Options {
     /**
      * Alter and filter records by executing a user defined function.
      */
-    on_record?: (record: any, context: CastingContext) => any;
-    onRecord?: (record: any, context: CastingContext) => any;
+    on_record?: (record: T, context: CastingContext) => T | null | undefined;
+    onRecord?: (record: T, context: CastingContext) => T | null | undefined;
     /**
      * Optional character surrounding a field, one character only, defaults to double quotes.
      */
@@ -274,9 +277,17 @@ 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;
+type OptionsWithColumns<T> = Omit<Options<T>, 'columns'> & {
+    columns: Exclude<Options['columns'], undefined | false>
+}
+
+declare function parse<T = unknown>(input: string | Buffer, options: OptionsWithColumns<T>, callback?: Callback<T>): Parser;
+declare function parse(input: string | Buffer, options: Options, callback?: Callback): Parser;
+
+declare function parse<T = unknown>(options: OptionsWithColumns<T>, callback?: Callback<T>): Parser;
+declare function parse(options: Options, callback?: Callback): Parser;
+
+declare function parse(input: string | Buffer, callback?: Callback): Parser;
 declare function parse(callback?: Callback): Parser;
 
 // export default 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<T> = Omit<Options<T>, 'columns'> & {
+  columns: Exclude<Options['columns'], undefined | false>
+}
+
+declare function parse<T = unknown>(input: Buffer | string, options: OptionsWithColumns<T>): 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,21 @@ import {
   ColumnOption, Options, Info, CsvErrorCode, CsvError
 } from '../lib/sync.js'
 
-describe('API Types', () => {
+describe('API Types - Sync', () => {
+  type Person = {name: string, age: number}
 
   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 +91,29 @@ 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', () => {
+      const data: Person[] = parse<Person>("", {
+        columns: true
+      })
+    })
+  })
+
 })

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

@@ -1,9 +1,9 @@
 
 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', () => {
+  type Person = {name: string, age: number}
 
   describe('stream/callback API', () => {
 
@@ -52,40 +52,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 = {
@@ -175,16 +151,22 @@ describe('API Types', () => {
       options.columns = true
       options.columns = []
       options.columns = ['string', undefined, null, false, {name: 'column-name'}]
-      options.columns = (record: string[]) => {
+      options.columns = (record) => {
         const fields: string[] = record.map( (field: string) => {
           return field.toUpperCase()
         })
         return fields
       }
-      options.columns = (record: string[]) => {
+      options.columns = (record) => {
         record
         return ['string', undefined, null, false, {name: 'column-name'}]
       }
+
+      const typedOptions: Options<Person> = {}
+      typedOptions.columns = ['age', undefined, null, false, {name: 'name'}]
+      typedOptions.columns = (record) => {
+        return ['age']
+      }
     })
 
     it('group_columns_by_name', () => {
@@ -252,9 +234,17 @@ describe('API Types', () => {
     it('on_record', () => {
       const options: Options = {}
       options.on_record = (record, {lines}) =>
-        [lines, record[0]]
+        [lines.toString(), record[0]]
       options.onRecord = (record, {lines}) =>
-        [lines, record[0]]
+        [lines.toString(), record[0]]
+
+      const typedOptions: Options<Person> = {}
+      typedOptions.on_record = (record) => {
+        return {...record, name: 'John Doe'}
+      }
+      typedOptions.onRecord = (record) => {
+        return {...record, name: 'John Doe'}
+      }
     })
 
     it('quote', () => {
@@ -395,4 +385,37 @@ 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) => {
+      parse<Person>("", {
+        columns: true
+      }, (error, records: Person[] | undefined) => {
+        next(error)
+      })
+    })
+  })
+
 })