From 0d03ac9480ed4f39e62d483953fe38d6f0ecfa76 Mon Sep 17 00:00:00 2001 From: Ardis Lu Date: Wed, 29 Jan 2025 21:28:20 -0800 Subject: [PATCH] Improve type documentation --- src/core.js | 19 ++++++++++++++----- test/utils.js | 4 ++-- 2 files changed, 16 insertions(+), 7 deletions(-) diff --git a/src/core.js b/src/core.js index 64f3c69..03cac7f 100644 --- a/src/core.js +++ b/src/core.js @@ -143,7 +143,7 @@ export class CSVReader extends ReadableStream { */ /** - * A row or rows of output CSV data, or null to skip a row. + * A row or rows of output CSV data, or `null` to skip a row. * @typedef {Array>|Array|string|null} TransformationOutput */ @@ -151,7 +151,16 @@ export class CSVReader extends ReadableStream { * A function to process a row or rows of CSV data from `CSVReader`. * @callback TransformationFunction * @param {TransformationInput} row A row or rows of input CSV data before transformation. - * @returns {TransformationOutput} A row or rows of output CSV data after transformation, or null to skip a row. + * @returns {TransformationOutput|Promise} A row or rows of output CSV data after transformation, or `null` to skip a row. + */ + +/** + * A function to handle errors thrown by a transformation function. + * @callback TransformationErrorFunction + * @param {TransformationInput} row The row passed to the transformation function which threw the error. + * @param {Error} error The error thrown by the transformation function. + * @param {TransformationFunction} fn The transformation function itself. This argument can be used to retry a transformation. + * @returns {TransformationOutput|Promise} A row or rows of output CSV data, or `null` to skip this row. */ /** @@ -167,9 +176,9 @@ export class CSVReader extends ReadableStream { * using `JSON.parse()` before being sent to `fn()`. The default value is `false`. * @property {boolean} [rawOutput=false] Set to `true` to send the raw return value of `fn()` to the next stream. Otherwise, the return value of * `fn()` will be serialized using `JSON.stringify()` before being sent to the next stream. The default value is `false`. - * @property {null|function(TransformationInput,Error,TransformationFunction):TransformationOutput} [onError=null] Set to a function to catch - * errors thrown by the transformation function. The input data, the error that was thrown, and the transformation function itself will be passed - * to the `onError` function. The default value is `null` (errors will not be caught). + * @property {null|TransformationErrorFunction} [onError=null] Set to a function to catch errors thrown by the transformation function. The + * input data, the error that was thrown, and the transformation function itself will be passed to the `onError` function. The default value + * is `null` (errors will not be caught). * @property {number} [maxBatchSize=1] The maximum number of rows that will be passed to the transformation function per function call (greedy). * The default value is `1`. * @property {number} [maxConcurrent=1] The maximum concurrent executions of the transformation function (greedy). The transformation function diff --git a/test/utils.js b/test/utils.js index 69dd8c1..9a5f6ac 100644 --- a/test/utils.js +++ b/test/utils.js @@ -47,9 +47,9 @@ export async function csvStreamEqual(stream, csv) { /** * A `WritableStream` version of `csvStreamEqual`. Compares each field in a CSV stream with a given - * array, assuming each chunk of the stream is a serialized `Array` representing a row of a CSV. + * array, assuming each chunk of the stream is a serialized `Array` representing a row of a CSV. * - * @param {Array>} csv A 2-D array representing the CSV file, where each inner array + * @param {Array>} csv A 2-D array representing the CSV file, where each inner array * is a row of the CSV. * @returns {WritableStream} A `WritableStream` sink of a CSV stream that will be compared against the given array. */ -- 2.47.3