feat: add TypeScript types (#15)

package.json

@@ -3,6 +3,7 @@
   "description": "tinyspawn is a minimalistic wrapper around child_process",
   "homepage": "https://github.com/microlinkhq/tinyspawn",
   "version": "1.2.14",
+  "types": "src/index.d.ts",
   "main": "src/index.js",
   "author": {
     "email": "hello@microlink.io",
@@ -56,7 +57,8 @@
     "simple-git-hooks": "latest",
     "standard": "latest",
     "standard-markdown": "latest",
-    "standard-version": "latest"
+    "standard-version": "latest",
+    "tsd": "latest"
   },
   "engines": {
     "node": ">= 18"
@@ -68,7 +70,7 @@
     "clean": "rm -rf node_modules",
     "contributors": "(npx git-authors-cli && npx finepack && git add package.json && git commit -m 'build: contributors' --no-verify) || true",
     "coverage": "c8 report --reporter=text-lcov > coverage/lcov.info",
-    "lint": "standard",
+    "lint": "standard && tsd",
     "postrelease": "npm run release:tags && npm run release:github && (ci-publish || npm publish --access=public)",
     "prerelease": "npm run update:check",
     "pretest": "npm run lint",
@@ -102,5 +104,8 @@
   "simple-git-hooks": {
     "commit-msg": "npx commitlint --edit",
     "pre-commit": "npx nano-staged"
+  },
+  "tsd": {
+    "directory": "test"
   }
 }

src/index.d.ts

@@ -0,0 +1,21 @@
+import { ChildProcess, SpawnOptions } from 'child_process';
+
+interface ExtendOptions extends SpawnOptions {
+  json?: boolean;
+}
+
+interface ResolvedSubprocess extends Omit<ChildProcess, 'stdout' | 'stderr'> {
+  stdout: string;
+  stderr: string;
+}
+
+interface SubprocessPromise extends Promise<ResolvedSubprocess>, ChildProcess {}
+
+declare function extend(defaults?: ExtendOptions): (input: string, args?: string[] | ExtendOptions, options?: ExtendOptions) => SubprocessPromise;
+
+declare const $: ReturnType<typeof extend> & {
+  extend: typeof extend;
+  json: ReturnType<typeof extend>;
+};
+
+export = $;

test/index.js

@@ -1,6 +1,5 @@
 'use strict'
 
-const { setTimeout } = require('timers/promises')
 const { execSync } = require('child_process')
 const { Writable } = require('stream')
 const { EOL } = require('os')
@@ -22,19 +21,6 @@ test('meaningful errors', async t => {
   t.is(error.killed, false)
 })
 
-test.skip('control process lifecycle', async t => {
-  t.plan(2)
-  try {
-    const subprocess = $('sleep 100')
-    await setTimeout(500)
-    subprocess.kill('SIGKILL')
-    await subprocess
-  } catch (error) {
-    t.is(error.killed, true)
-    t.is(error.signalCode, 'SIGKILL')
-  }
-})
-
 test.serial('run a command', async t => {
   {
     const result = await $('echo hello world')

test/index.test-d.ts

@@ -0,0 +1,29 @@
+import $ from '..'
+
+/* basic */
+
+const promise = $('curl https://www.youtube.com/watch?v=6xKWiCMKKJg')
+
+// at this point it's a child_process instance
+promise.kill()
+promise.ref()
+promise.unref()
+
+const result = await promise
+
+// after that stdout/stderr are available as string values
+
+console.log(result.stdout)
+console.log(result.stderr)
+
+console.log(result.connected)
+console.log(result.signalCode)
+console.log(result.exitCode)
+console.log(result.killed)
+console.log(result.spawnfile)
+console.log(result.spawnargs)
+console.log(result.pid)
+console.log(result.stdin)
+console.log(result.stdout)
+console.log(result.stderr)
+console.log(result.stdin)