fix: Improve File and FormData types declarations. (nodejs#1042)

* Fixes for `File` and `FormData` types declarations.

1. `FormData`:
  * Declare class methods as they should be;
  * Minor fixes for methods documentation in code;
  * Remove unnecessary constructor declaration;
  * Remove unnecessary part from FormData class description;
2. `File`:
  * Replace getters with readonly properties;
  * Remove `File.stream()` method, because `File` inherits `Blob` which already has this method;
  * `FileOptions` interface inherits `BlobOptions` from `@types/node` declarations;

* Minor fix for File constructor types delcaration: Update fileBits description and rename name to fileName.

* Rename arguments in FormData.forEach type declarations.

* Rename ctx argument to thisArg in FormData.forEach() method to match MDN documentation.

types/file.d.ts

@@ -1,13 +1,9 @@
-// based on https://unpkg.com/browse/formdata-node@4.0.1/@type/File.d.ts (MIT)
+// Based on https://github.com/octet-stream/form-data/blob/2d0f0dc371517444ce1f22cdde13f51995d0953a/lib/File.ts (MIT)
 /// <reference types="node" />
 
-import { Blob } from 'buffer'
+import { Blob, BlobOptions } from 'buffer'
 
-export interface FileOptions {
-  /**
-   * Returns the media type ([`MIME`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types)) of the file represented by a `File` object.
-   */
-  type?: string
+export interface FileOptions extends BlobOptions {
   /**
    * The last modified date of the file as the number of milliseconds since the Unix epoch (January 1, 1970 at midnight). Files without a known last modified date return the current date.
    */
@@ -18,21 +14,21 @@ export declare class File extends Blob {
   /**
    * Creates a new File instance.
    *
-   * @param fileBits An `Array` strings, or [`Buffer`](https://nodejs.org/dist/latest/docs/api/buffer.html#buffer_class_buffer), [`ArrayBuffer`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer), [`ArrayBufferView`](https://developer.mozilla.org/en-US/docs/Web/API/ArrayBufferView), [`Blob`](https://developer.mozilla.org/en-US/docs/Web/API/Blob) objects, or a mix of any of such objects, that will be put inside the [`File`](https://developer.mozilla.org/en-US/docs/Web/API/File).
-   * @param name The name of the file.
+   * @param fileBits An `Array` strings, or [`ArrayBuffer`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer), [`ArrayBufferView`](https://developer.mozilla.org/en-US/docs/Web/API/ArrayBufferView), [`Blob`](https://developer.mozilla.org/en-US/docs/Web/API/Blob) objects, or a mix of any of such objects, that will be put inside the [`File`](https://developer.mozilla.org/en-US/docs/Web/API/File).
+   * @param fileName The name of the file.
    * @param options An options object containing optional attributes for the file.
    */
-  constructor (fileBits: ReadonlyArray<string | NodeJS.ArrayBufferView | Blob>, name: string, options?: FileOptions)
+  constructor(fileBits: ReadonlyArray<string | NodeJS.ArrayBufferView | Blob>, fileName: string, options?: FileOptions)
+
   /**
    * Name of the file referenced by the File object.
    */
-  get name (): string
+  readonly name: string
+
   /**
    * The last modified date of the file as the number of milliseconds since the Unix epoch (January 1, 1970 at midnight). Files without a known last modified date return the current date.
    */
-  get lastModified (): number
-  get [Symbol.toStringTag] (): string
-  stream (): {
-    [Symbol.asyncIterator]: () => AsyncIterableIterator<Uint8Array>
-  }
+  readonly lastModified: number
+
+  readonly [Symbol.toStringTag]: string
 }

types/formdata.d.ts

@@ -1,4 +1,4 @@
-// based on https://unpkg.com/browse/formdata-node@4.0.1/@type/FormData.d.ts (MIT)
+// Based on https://github.com/octet-stream/form-data/blob/2d0f0dc371517444ce1f22cdde13f51995d0953a/lib/FormData.ts (MIT)
 /// <reference types="node" />
 
 import { File } from './file'
@@ -10,12 +10,8 @@ declare type FormDataEntryValue = string | File
 
 /**
  * Provides a way to easily construct a set of key/value pairs representing form fields and their values, which can then be easily sent using fetch().
- *
- * Note that this object is not a part of Node.js, so you might need to check if an HTTP client of your choice support spec-compliant FormData.
- * However, if your HTTP client does not support FormData, you can use [`form-data-encoder`](https://npmjs.com/package/form-data-encoder) package to handle "multipart/form-data" encoding.
  */
 export declare class FormData {
-  constructor ()
   /**
    * Appends a new value onto an existing key inside a FormData object,
    * or adds the key if it does not already exist.
@@ -25,20 +21,22 @@ export declare class FormData {
    * @param name The name of the field whose data is contained in `value`.
    * @param value The field's value. This can be [`Blob`](https://developer.mozilla.org/en-US/docs/Web/API/Blob)
     or [`File`](https://developer.mozilla.org/en-US/docs/Web/API/File). If none of these are specified the value is converted to a string.
-   * @param filename The filename reported to the server, when a Blob or File is passed as the second parameter. The default filename for Blob objects is "blob". The default filename for File objects is the file's filename.
+   * @param fileName The filename reported to the server, when a Blob or File is passed as the second parameter. The default filename for Blob objects is "blob". The default filename for File objects is the file's filename.
    */
-  readonly append: (name: string, value: unknown, filename?: string) => void
+  append(name: string, value: unknown, fileName?: string): void
+
   /**
    * Set a new value for an existing key inside FormData,
    * or add the new field if it does not already exist.
    *
    * @param name The name of the field whose data is contained in `value`.
    * @param value The field's value. This can be [`Blob`](https://developer.mozilla.org/en-US/docs/Web/API/Blob)
     or [`File`](https://developer.mozilla.org/en-US/docs/Web/API/File). If none of these are specified the value is converted to a string.
-   * @param filename The filename reported to the server, when a Blob or File is passed as the second parameter. The default filename for Blob objects is "blob". The default filename for File objects is the file's filename.
+   * @param fileName The filename reported to the server, when a Blob or File is passed as the second parameter. The default filename for Blob objects is "blob". The default filename for File objects is the file's filename.
    *
    */
-  readonly set: (name: string, value: unknown, filename?: string) => void
+  set(name: string, value: unknown, fileName?: string): void
+
   /**
    * Returns the first value associated with a given key from within a `FormData` object.
    * If you expect multiple values and want all of them, use the `getAll()` method instead.
@@ -47,51 +45,60 @@ export declare class FormData {
    *
    * @returns A `FormDataEntryValue` containing the value. If the key doesn't exist, the method returns null.
    */
-  readonly get: (name: string) => FormDataEntryValue | null
+  get(name: string): FormDataEntryValue | null
+
   /**
    * Returns all the values associated with a given key from within a `FormData` object.
    *
    * @param {string} name A name of the value you want to retrieve.
    *
    * @returns An array of `FormDataEntryValue` whose key matches the value passed in the `name` parameter. If the key doesn't exist, the method returns an empty list.
    */
-  readonly getAll: (name: string) => FormDataEntryValue[]
+  getAll(name: string): FormDataEntryValue[]
+
   /**
    * Returns a boolean stating whether a `FormData` object contains a certain key.
    *
    * @param name A string representing the name of the key you want to test for.
    *
    * @return A boolean value.
    */
-  readonly has: (name: string) => boolean
+  has(name: string): boolean
+
   /**
    * Deletes a key and its value(s) from a `FormData` object.
    *
    * @param name The name of the key you want to delete.
    */
-  readonly delete: (name: string) => void
+  delete(name: string): void
+
   /**
    * Returns an [`iterator`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols) allowing to go through all keys contained in this `FormData` object.
    * Each key is a `string`.
    */
-  readonly keys: () => Generator<string>
+  keys(): Generator<string>
+
   /**
    * Returns an [`iterator`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols) allowing to go through the `FormData` key/value pairs.
    * The key of each pair is a string; the value is a [`FormDataValue`](https://developer.mozilla.org/en-US/docs/Web/API/FormDataEntryValue).
    */
-  readonly entries: () => Generator<[string, FormDataEntryValue]>
+  entries(): Generator<[string, FormDataEntryValue]>
+
   /**
    * Returns an [`iterator`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols) allowing to go through all values contained in this object `FormData` object.
    * Each value is a [`FormDataValue`](https://developer.mozilla.org/en-US/docs/Web/API/FormDataEntryValue).
    */
-  readonly values: () => Generator<FormDataEntryValue>
+  values(): Generator<FormDataEntryValue>
+
   /**
    * An alias for FormData#entries()
    */
-  readonly [Symbol.iterator]: () => Generator<[string, FormDataEntryValue], any, unknown>
+  [Symbol.iterator](): Generator<[string, FormDataEntryValue], void>
+
   /**
    * Executes given callback function for each field of the FormData instance
    */
-  readonly forEach: (fn: (value: FormDataEntryValue, key: string, fd: FormData) => void, ctx?: unknown) => void
-  get [Symbol.toStringTag] (): string
+  forEach(callback: (value: FormDataEntryValue, key: string, formData: FormData) => void, thisArg?: unknown): void
+
+  readonly [Symbol.toStringTag]: string
 }