feat: add TypeScript types (#23)

Author: fjc0k

.github/workflows/ci.yml

@@ -15,4 +15,4 @@ jobs:
     uses: artusjs/github-actions/.github/workflows/node-test.yml@v1
     with:
       os: 'ubuntu-latest, macos-latest'
-      version: '14, 16, 18'
+      version: '14, 16, 18, 20'

.github/workflows/release.yml

@@ -1,11 +1,9 @@
 name: Release
 
 on:
-  # 合并后自动发布
   push:
     branches: [ master ]
 
-  # 手动发布
   workflow_dispatch: {}
 
 jobs:

package.json

@@ -3,14 +3,17 @@
   "version": "1.2.0",
   "description": "A multipart/form-data encoded stream, helper for file upload.",
   "main": "lib/formstream.js",
+  "types": "types/formstream.d.ts",
   "files": [
-    "lib"
+    "lib",
+    "types/formstream.d.ts"
   ],
   "scripts": {
     "test": "egg-bin test",
     "cov": "egg-bin cov",
-    "ci": "npm run lint && npm run cov",
-    "lint": "jshint ."
+    "ci": "npm run lint && npm run tsd && npm run cov",
+    "lint": "jshint .",
+    "tsd": "tsd"
   },
   "repository": {
     "type": "git",
@@ -31,12 +34,14 @@
     "pause-stream": "~0.0.11"
   },
   "devDependencies": {
+    "@types/node": "^20.4.3",
     "connect-multiparty": "1",
     "egg-bin": "^5.6.1",
     "express": "^4.16.4",
     "jshint": "^2.13.6",
     "pedding": "1",
     "should": "4",
+    "tsd": "^0.28.1",
     "urllib": "2"
   },
   "author": "fengmk2 <fengmk2@gmail.com> (https://github.com/fengmk2)",

types/formstream.d.ts

@@ -0,0 +1,72 @@
+import { Readable, Stream } from 'stream'
+
+declare class FormStream extends Stream {
+  /**
+   * Add a normal field to the form.
+   *
+   * @param name Name of field
+   * @param value Value of field
+   */
+  field(name: string, value: string): this
+
+  /**
+   * Add a local file to be uploaded to the form.
+   *
+   * @param name Name of file field
+   * @param filepath Local path of the file to be uploaded
+   * @param filename Name of the file (will be the base name of filepath if empty)
+   * @param filesize Size of the file (will not generate Content-Length header if not specified)
+   */
+  file(
+    name: string,
+    filepath: string,
+    filename?: string,
+    filesize?: number,
+  ): this
+
+  /**
+   * Add a buffer as a file to upload.
+   *
+   * @param name Name of field
+   * @param buffer The buffer to be uploaded
+   * @param filename The file name that tells the remote server
+   * @param contentType Content-Type (aka. MIME Type) of content (will be infered with filename if empty)
+   */
+  buffer(
+    name: string,
+    buffer: Buffer,
+    filename: string,
+    contentType?: string,
+  ): this
+
+  /**
+   * Add a readable stream as a file to upload. Event 'error' will be emitted if an error occured.
+   *
+   * @param name Name of field
+   * @param stream A readable stream to be piped
+   * @param filename The file name that tells the remote server
+   * @param contentType Content-Type (aka. MIME Type) of content (will be infered with filename if empty)
+   * @param size Size of the stream (will not generate Content-Length header if not specified)
+   */
+  stream(
+    name: string,
+    stream: Readable,
+    filename: string,
+    contentType?: string,
+    size?: number,
+  ): this
+
+  /**
+   * Get headers for the request.
+   *
+   * @param additionalHeaders Additional headers
+   */
+  headers(additionalHeaders?: Record<string, any>): Record<string, any>
+}
+
+declare const formStream: {
+  new (): FormStream
+  (): FormStream
+}
+
+export = formStream

types/formstream.test-d.ts

@@ -0,0 +1,46 @@
+import formStream from '..'
+import { Readable } from 'stream'
+
+const fs = formStream()
+const fsNew = new formStream()
+
+// @ts-expect-error
+fs.field('id')
+// @ts-expect-error
+fs.field('id', 1)
+fs.field('id', '1')
+
+// @ts-expect-error
+fs.file('avatar')
+// @ts-expect-error
+fs.file('avatar', 1)
+fs.file('avatar', './avatar.png')
+fs.file('avatar', './avatar.png', 'avatar.png')
+fs.file('avatar', './avatar.png', 'avatar.png', 1000)
+
+// @ts-expect-error
+fs.buffer('content')
+// @ts-expect-error
+fs.buffer('content', Buffer.from('123'))
+// @ts-expect-error
+fs.buffer('content', '123', '123.txt')
+fs.buffer('content', Buffer.from('123'), '123.txt')
+fs.buffer('content', Buffer.from('123'), '123.txt', 'text/plain')
+
+// @ts-expect-error
+fs.stream('file')
+// @ts-expect-error
+fs.stream('file', Readable.from('123'))
+// @ts-expect-error
+fs.stream('file', '123', '123.txt')
+fs.stream('file', Readable.from('123'), '123.txt')
+fs.stream('file', Readable.from('123'), '123.txt', 'text/plain')
+fs.stream('file', Readable.from('123'), '123.txt', 'text/plain', 1000)
+
+fs.headers()
+// @ts-expect-error
+fs.headers(1)
+fs.headers({})
+fs.headers({
+  'x-token': 'xxxx',
+})