fix(d3-fetch): update signatures and expand JSDoc comments (#23378)

* fix(d3-fetch):  update signatures and expand JSDoc comments

* fix(image): init object is not request init, but rather initializes image element properties
* fix(json): add generic parameter to allow return type casting
* fix(csv, dsv, tsv): overload signatures to be more specific about return type (with or without row parsing function).
* fix(csv, dsv, tsv): update row parsing function signature to be in line with parser signature in d3-dsv, which is called under the hood.
* chore(tslint): add tslint rules to allow signature overloading and single-use generic
* doc(*) Expand JSDoc comments
* chore(tests): update tests

* chore(d3-fetch): add validation reference patch release version

types/d3-fetch/d3-fetch-tests.ts

@@ -11,28 +11,41 @@ const init: RequestInit = {};
 
 let p1: Promise<Blob> = d3Fetch.blob(url);
 p1 = d3Fetch.blob(url, init);
+
 let p2: Promise<ArrayBuffer> = d3Fetch.buffer(url);
 p2 = d3Fetch.buffer(url, init);
+
 let p3: Promise<HTMLImageElement> = d3Fetch.image(url);
-p3 = d3Fetch.image(url, init);
+const imageProperties = {
+    width: '300px',
+    height: '500px'
+};
+p3 = d3Fetch.image(url, imageProperties);
+
 let p4: Promise<any> = d3Fetch.json(url);
 p4 = d3Fetch.json(url, init);
+let p5: Promise<MyType> = d3Fetch.json<MyType>(url);
+p5 = d3Fetch.json<MyType>(url, init);
 
 let myString: Promise<string>;
 myString = d3Fetch.text(url);
 myString = d3Fetch.text(url, init);
 
-const parseRow = (d: {}) => {
-    const myType: MyType = { foo: 'foo' };
+const parseRow = (rawRow: DSVRowString, index: number, columns: string[]): (MyType | undefined | null) => {
+    const myType: MyType | null = rawRow['foo'] ? { foo: rawRow['foo'] + '+ bar' } : null;
     return myType;
 };
+let promise1: Promise<DSVParsedArray<DSVRowString>>;
 let promise2: Promise<DSVParsedArray<MyType>>;
-promise2 = d3Fetch.csv<MyType>(url);
-promise2 = d3Fetch.csv<MyType>(url, init);
+promise1 = d3Fetch.csv(url);
+promise1 = d3Fetch.csv(url, init);
+promise2 = d3Fetch.csv<MyType>(url, parseRow);
 promise2 = d3Fetch.csv<MyType>(url, init, parseRow);
-promise2 = d3Fetch.dsv<MyType>(';', url);
-promise2 = d3Fetch.dsv<MyType>(';', url, init);
+promise1 = d3Fetch.dsv(';', url);
+promise1 = d3Fetch.dsv(';', url, init);
+promise2 = d3Fetch.dsv<MyType>(';', url, parseRow);
 promise2 = d3Fetch.dsv<MyType>(';', url, init, parseRow);
-promise2 = d3Fetch.tsv<MyType>(url);
-promise2 = d3Fetch.tsv<MyType>(url, init);
+promise1 = d3Fetch.tsv(url);
+promise1 = d3Fetch.tsv(url, init);
+promise2 = d3Fetch.tsv<MyType>(url, parseRow);
 promise2 = d3Fetch.tsv<MyType>(url, init, parseRow);

types/d3-fetch/index.d.ts

@@ -3,40 +3,234 @@
 // Definitions by: Hugues Stefanski <https://github.com/ledragon>
 // Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped
 // TypeScript Version: 2.2
+
+// Last module patch version validated against: 1.0.1
+
 import { DSVParsedArray, DSVRowString, DSVRowAny } from 'd3-dsv';
 
-/** Fetches the binary file at the specified input URL as a Blob. If init is specified, it is passed along to the underlying call to fetch. */
+/**
+ * Fetches the binary file at the specified input URL and returns it as a Promise of a Blob.
+ * If init is specified, it is passed along to the underlying call to fetch.
+ *
+ * @param url A valid URL string.
+ * @param init An optional request initialization object.
+ */
 export function blob(url: string, init?: RequestInit): Promise<Blob>;
-/** Fetches the binary file at the specified input URL as an ArrayBuffer. If init is specified, it is passed along to the underlying call to fetch. */
+
+/**
+ * Fetches the binary file at the specified input URL and returns it as a Promise of an ArrayBuffer.
+ * If init is specified, it is passed along to the underlying call to fetch.
+ *
+ * @param url A valid URL string.
+ * @param init An optional request initialization object.
+ */
 export function buffer(url: string, init?: RequestInit): Promise<ArrayBuffer>;
 
-/** Equivalent to d3.dsv with the comma character as the delimiter. */
-export function csv<ParsedRow extends DSVRowAny>(
+/**
+ * Fetches the CSV file at the specified input URL and returns
+ * a promise of an array of objects representing the parsed rows. The values of the properties of the parsed row
+ * objects are represented as strings.
+ *
+ * If init is specified, it is passed along to the underlying call to fetch.
+ *
+ * @param url A valid URL string.
+ * @param init An optional request initialization object.
+ */
+export function csv(
     url: string,
     init?: RequestInit,
-    row?: (d: DSVRowAny) => ParsedRow
+): Promise<DSVParsedArray<DSVRowString>>;
+/**
+ * Fetches the CSV file at the specified input URL and returns
+ * a promise of an array of objects representing the parsed rows.
+ *
+ * The specified row conversion function is used to map and filter row objects to a more-specific representation;
+ * see dsv.csvParse for details.
+ *
+ * The generic parameter describes the type of the object representation of a parsed row.
+ *
+ * @param url A valid URL string.
+ * @param row A row conversion function which is invoked for each row, being passed an object representing the current row (d),
+ * the index (i) starting at zero for the first non-header row, and the array of column names. If the returned value is null or undefined,
+ * the row is skipped and will be ommitted from the array returned by dsv.csvParse; otherwise, the returned value defines the corresponding row object.
+ * In effect, row is similar to applying a map and filter operator to the returned rows.
+ */
+export function csv<ParsedRow extends DSVRowAny>(
+    url: string,
+    row: (rawRow: DSVRowString, index: number, columns: string[]) => ParsedRow | undefined | null
+): Promise<DSVParsedArray<ParsedRow>>;
+/**
+ * Fetches the CSV file at the specified input URL and returns
+ * a promise of an array of objects representing the parsed rows.
+ *
+ * The init object is passed along to the underlying call to fetch.
+ *
+ * The specified row conversion function is used to map and filter row objects to a more-specific representation;
+ * see dsv.csvParse for details.
+ *
+ * The generic parameter describes the type of the object representation of a parsed row.
+ *
+ * @param url A valid URL string.
+ * @param init An request initialization object.
+ * @param row A row conversion function which is invoked for each row, being passed an object representing the current row (d),
+ * the index (i) starting at zero for the first non-header row, and the array of column names. If the returned value is null or undefined,
+ * the row is skipped and will be ommitted from the array returned by dsv.csvParse; otherwise, the returned value defines the corresponding row object.
+ * In effect, row is similar to applying a map and filter operator to the returned rows.
+ */
+export function csv<ParsedRow extends DSVRowAny>(
+    url: string,
+    init: RequestInit,
+    row: (rawRow: DSVRowString, index: number, columns: string[]) => ParsedRow | undefined | null
 ): Promise<DSVParsedArray<ParsedRow>>;
 
-/** Fetches the DSV file at the specified input URL. */
-export function dsv<ParsedRow extends DSVRowAny>(
+/**
+ * Fetches the DSV file with the specified delimiter character at the specified input URL and returns
+ * a promise of an array of objects representing the parsed rows. The values of the properties of the parsed row
+ * objects are represented as strings.
+ *
+ * If init is specified, it is passed along to the underlying call to fetch.
+ *
+ * @param delimiter The delimiter character used in the DSV file to be fetched.
+ * @param url A valid URL string.
+ * @param init An optional request initialization object.
+ */
+export function dsv(
     delimiter: string,
     url: string,
     init?: RequestInit,
-    row?: (d: DSVRowAny) => ParsedRow
+): Promise<DSVParsedArray<DSVRowString>>;
+/**
+ * Fetches the DSV file with the specified delimiter character at the specified input URL and returns
+ * a promise of an array of objects representing the parsed rows.
+ *
+ * The specified row conversion function is used to map and filter row objects to a more-specific representation;
+ * see dsv.parse for details.
+ *
+ * The generic parameter describes the type of the object representation of a parsed row.
+ *
+ * @param delimiter The delimiter character used in the DSV file to be fetched.
+ * @param url A valid URL string.
+ * @param row A row conversion function which is invoked for each row, being passed an object representing the current row (d),
+ * the index (i) starting at zero for the first non-header row, and the array of column names. If the returned value is null or undefined,
+ * the row is skipped and will be ommitted from the array returned by dsv.parse; otherwise, the returned value defines the corresponding row object.
+ * In effect, row is similar to applying a map and filter operator to the returned rows.
+ */
+export function dsv<ParsedRow extends DSVRowAny>(
+    delimiter: string,
+    url: string,
+    row: (rawRow: DSVRowString, index: number, columns: string[]) => ParsedRow | undefined | null
+): Promise<DSVParsedArray<ParsedRow>>;
+/**
+ * Fetches the DSV file with the specified delimiter character at the specified input URL and returns
+ * a promise of an array of objects representing the parsed rows.
+ *
+ * The init object is passed along to the underlying call to fetch.
+ *
+ * The specified row conversion function is used to map and filter row objects to a more-specific representation;
+ * see dsv.parse for details.
+ *
+ * The generic parameter describes the type of the object representation of a parsed row.
+ *
+ * @param delimiter The delimiter character used in the DSV file to be fetched.
+ * @param url A valid URL string.
+ * @param init An request initialization object.
+ * @param row A row conversion function which is invoked for each row, being passed an object representing the current row (d),
+ * the index (i) starting at zero for the first non-header row, and the array of column names. If the returned value is null or undefined,
+ * the row is skipped and will be ommitted from the array returned by dsv.parse; otherwise, the returned value defines the corresponding row object.
+ * In effect, row is similar to applying a map and filter operator to the returned rows.
+ */
+export function dsv<ParsedRow extends DSVRowAny>(
+    delimiter: string,
+    url: string,
+    init: RequestInit,
+    row: (rawRow: DSVRowString, index: number, columns: string[]) => ParsedRow | undefined | null
 ): Promise<DSVParsedArray<ParsedRow>>;
 
-/** Fetches the image at the specified input URL. If init is specified, it is passed along to the underlying call to fetch. */
-export function image(url: string, init?: RequestInit): Promise<HTMLImageElement>;
+/**
+ * Fetches the image at the specified input URL and returns a promise of an HTML image element.
+ *
+ * If init is specified, sets any additional properties on the image before loading.
+ *
+ * @param url A valid URL string.
+ * @param init An optional object of image properties to set.
+ */
+export function image(url: string, init?: {[key: string]: any}): Promise<HTMLImageElement>;
 
-/** Fetches the json file at the specified input URL. If init is specified, it is passed along to the underlying call to fetch. */
-export function json(url: string, init?: RequestInit): Promise<{}>;
+/**
+ * Fetches the json file at the specified input URL and returns it as a Promise of a parsed JSON object.
+ *
+ * If init is specified, it is passed along to the underlying call to fetch.
+ *
+ * The generic parameter describes the type of the object parsed from the returned JSON.
+ *
+ * @param url A valid URL string.
+ * @param init An optional request initialization object.
+ */
+export function json<ParsedJSONObject extends any>(url: string, init?: RequestInit): Promise<ParsedJSONObject>;
 
-/** Fetches the text file at the specified input URL. If init is specified, it is passed along to the underlying call to fetch. */
+/**
+ * Fetches the text file at the specified input URL and returns it as a Promise of a string.
+ *
+ * If init is specified, it is passed along to the underlying call to fetch.
+ *
+ * @param url A valid URL string.
+ * @param init An optional request initialization object.
+ */
 export function text(url: string, init?: RequestInit): Promise<string>;
 
-/** Equivalent to d3.dsv with the tab character as the delimiter. */
-export function tsv<ParsedRow extends DSVRowAny>(
+/**
+ * Fetches the TSV file at the specified input URL and returns
+ * a promise of an array of objects representing the parsed rows.
+ *
+ * If init is specified, it is passed along to the underlying call to fetch.
+ *
+ * @param url A valid URL string.
+ * @param init An optional request initialization object.
+ */
+export function tsv(
     url: string,
     init?: RequestInit,
-    row?: (d: DSVRowAny) => ParsedRow
+): Promise<DSVParsedArray<DSVRowString>>;
+/**
+ * Fetches the TSV file at the specified input URL and returns
+ * a promise of an array of objects representing the parsed rows. The values of the properties of the parsed row
+ * objects are represented as strings.
+ *
+ * The specified row conversion function is used to map and filter row objects to a more-specific representation;
+ * see dsv.tsvParse for details.
+ *
+ * The generic parameter describes the type of the object representation of a parsed row.
+ *
+ * @param url A valid URL string.
+ * @param row A row conversion function which is invoked for each row, being passed an object representing the current row (d),
+ * the index (i) starting at zero for the first non-header row, and the array of column names. If the returned value is null or undefined,
+ * the row is skipped and will be ommitted from the array returned by dsv.tsvParse; otherwise, the returned value defines the corresponding row object.
+ * In effect, row is similar to applying a map and filter operator to the returned rows.
+ */
+export function tsv<ParsedRow extends DSVRowAny>(
+    url: string,
+    row: (rawRow: DSVRowString, index: number, columns: string[]) => ParsedRow | undefined | null
+): Promise<DSVParsedArray<ParsedRow>>;
+/**
+ * Fetches the TSV file at the specified input URL and returns
+ * a promise of an array of objects representing the parsed rows.
+ *
+ * The init object is passed along to the underlying call to fetch.
+ *
+ * The specified row conversion function is used to map and filter row objects to a more-specific representation;
+ * see dsv.tsvParse for details.
+ *
+ * The generic parameter describes the type of the object representation of a parsed row.
+ *
+ * @param url A valid URL string.
+ * @param init An request initialization object.
+ * @param row A row conversion function which is invoked for each row, being passed an object representing the current row (d),
+ * the index (i) starting at zero for the first non-header row, and the array of column names. If the returned value is null or undefined,
+ * the row is skipped and will be ommitted from the array returned by dsv.tsvParse; otherwise, the returned value defines the corresponding row object.
+ * In effect, row is similar to applying a map and filter operator to the returned rows.
+ */
+export function tsv<ParsedRow extends DSVRowAny>(
+    url: string,
+    init: RequestInit,
+    row: (rawRow: DSVRowString, index: number, columns: string[]) => ParsedRow | undefined | null
 ): Promise<DSVParsedArray<ParsedRow>>;

types/d3-fetch/tslint.json

@@ -1 +1,7 @@
-{ "extends": "dtslint/dt.json" }
+{
+    "extends": "dtslint/dt.json",
+    "rules": {
+        "unified-signatures": false,
+        "no-unnecessary-generics": false
+    }
+}