Add manual type overrides

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 4d3b97a14d93a545b7b975e0483d6d171172d7e9..c7968d7b4568c81f89961c3534cd4185a5debbdd 100644 (file)
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -12,6 +12,8 @@ npm run types:check
 
 All reasonable type issues (i.e., those not resulting from limitations of `tsc`) should be fixed.
 
+To work around `tsc` limitations, add manual type definitions in `./npm/ambient.d.ts`. These type definitions are appended to the output of `tsc` and override the `tsc` outputs if there are conflicts.
+
 ## 2. Tests
 
 Run tests:

diff --git a/npm/ambient.d.ts b/npm/ambient.d.ts
new file mode 100644 (file)
index 0000000..5d50ce6
--- /dev/null
+++ b/npm/ambient.d.ts
@@ -0,0 +1,48 @@
+/** Manual type overrides */
+
+// TypeScript does not support setting a return type on a class constructor.
+// Workaround:
+// - Instead of a class, use a const and inherit an interface (the const and the interface can use the same name for convenience)
+// - Declare the constructors as overloaded `new` functions
+// - Put static methods in the constant definition
+// - Put instance methods in the interface definition
+// See https://github.com/microsoft/TypeScript/issues/27594
+// Workaround source: https://github.com/microsoft/TypeScript/issues/27594#issuecomment-566836640
+
+import { ReadableStream, WritableStream, TransformStream } from 'node:stream/web';
+
+interface CSVReader {}
+
+/**
+ * A simple streaming parser for CSV files.
+ *
+ * Each chunk is one row of the CSV file as an `Array<string>`.
+ */
+export declare const CSVReader: {
+  new(path: PathLike, options?: CSVReaderOptions): CSVReader & ReadableStream<Array<string>>;
+  new(path?: null): CSVReader & TransformStream<string, Array<string>>;
+}
+
+interface CSVWriter {
+  status: CSVWriterStatus;
+}
+
+/**
+ * Write a streamed CSV file to disk.
+ *
+ * A simple wrapper around Node.js's [`fs.writeFile`](https://nodejs.org/api/fs.html#fspromiseswritefilefile-data-options) to write
+ * streamed data to a file. If the input data is JSON, the data is converted to a string representing a RFC 4180 CSV record. If the
+ * data is not JSON (e.g., if it is already converted to a CSV string), the data is written to the CSV file directly.
+ */
+export declare const CSVWriter: {
+  /**
+  * Convert a JavaScript array into a CSV string.
+  *
+  * @param {Array<string>} arr An array of strings representing one row of a CSV file.
+  * @returns {string} A string representing one row of a CSV file, with character escaping and line endings compliant with
+  * [RFC 4180](https://www.ietf.org/rfc/rfc4180.txt).
+  */
+  arrayToCSVString(arr: Array<string>): string;
+  new(path: PathLike): CSVWriter & WritableStream<any>;
+  new(path?: null): CSVWriter & TransformStream<Array<string>, string>;
+}

diff --git a/npm/posttypes.js b/npm/posttypes.js
new file mode 100644 (file)
index 0000000..d418686
--- /dev/null
+++ b/npm/posttypes.js
@@ -0,0 +1,7 @@
+import { appendFile, readFile } from 'node:fs/promises';
+
+// Inject manually-defined types to work around TypeScript limitations. Note that a re-export
+// will not work, the overrides MUST be defined within the top-level index.d.ts to work.
+const ambient = await readFile('./npm/ambient.d.ts');
+await appendFile('./types/index.d.ts', '\n\n');
+await appendFile('./types/index.d.ts', ambient);

diff --git a/package.json b/package.json
index d58c3c286c427143005f7cedc0c9cfba0275e562..06a97d1a181bce4fe7c85f3f03ded78731faf09b 100644 (file)
--- a/package.json
+++ b/package.json
@@ -39,6 +39,7 @@
   },
   "scripts": {
     "types": "tsc",
+    "posttypes": "node ./npm/posttypes.js",
     "types:check": "tsc --noEmit --checkJS",
     "test": "node --test --test-skip-pattern=\"/^large:/\"",
     "test:large": "node --test --test-name-pattern=\"/^large:/\" --expose-gc",