From cd27c0b50584e078a10338ef0c37282255f3f9ca Mon Sep 17 00:00:00 2001 From: Remy Sharp Date: Sat, 25 May 2024 10:48:53 +0100 Subject: [PATCH] fix: add types to help with required nodemon usage (#2204) --- .github/workflows/node.js.yml | 2 +- .github/workflows/release.yml | 2 +- index.d.ts | 126 ++++++++++++++++++++++++++++++++++ jsconfig.json | 7 ++ lib/nodemon.js | 4 ++ package.json | 1 + 6 files changed, 140 insertions(+), 2 deletions(-) create mode 100644 index.d.ts create mode 100644 jsconfig.json diff --git a/.github/workflows/node.js.yml b/.github/workflows/node.js.yml index 7629d907..5af7f9e1 100644 --- a/.github/workflows/node.js.yml +++ b/.github/workflows/node.js.yml @@ -15,7 +15,7 @@ jobs: strategy: matrix: - node-version: [10.x, 12.x, 18.x] + node-version: [18.x] # See supported Node.js release schedule at https://nodejs.org/en/about/releases/ steps: diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 07706003..c2ac4d79 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -19,7 +19,7 @@ jobs: uses: actions/setup-node@v4 with: cache: npm - node-version: 16 + node-version: 18 - name: Install dependencies run: npm ci - name: Release diff --git a/index.d.ts b/index.d.ts new file mode 100644 index 00000000..4b146e5d --- /dev/null +++ b/index.d.ts @@ -0,0 +1,126 @@ +type NodemonEventHandler = + | 'start' + | 'crash' + | 'exit' + | 'quit' + | 'restart' + | 'config:update' + | 'log' + | 'readable' + | 'stdout' + | 'stderr'; + +type NodemonEventListener = { + on(event: 'start' | 'crash' | 'readable', listener: () => void): Nodemon; + on(event: 'log', listener: (e: NodemonEventLog) => void): Nodemon; + on(event: 'stdout' | 'stderr', listener: (e: string) => void): Nodemon; + on(event: 'restart', listener: (e?: NodemonEventRestart) => void): Nodemon; + on(event: 'quit', listener: (e?: NodemonEventQuit) => void): Nodemon; + on(event: 'exit', listener: (e?: NodemonEventExit) => void): Nodemon; + on( + event: 'config:update', + listener: (e?: NodemonEventConfig) => void + ): Nodemon; +}; + +type Nodemon = { + (options?: NodemonSettings): Nodemon; + on(event: 'start' | 'crash', listener: () => void): Nodemon; + on(event: 'log', listener: (e: NodemonEventLog) => void): Nodemon; + on(event: 'restart', listener: (e?: NodemonEventRestart) => void): Nodemon; + on(event: 'quit', listener: (e?: NodemonEventQuit) => void): Nodemon; + on(event: 'exit', listener: (e?: NodemonEventExit) => void): Nodemon; + on( + event: 'config:update', + listener: (e?: NodemonEventConfig) => void + ): Nodemon; + + // this is repeated because VS Code doesn't autocomplete otherwise + addEventListener(event: 'start' | 'crash', listener: () => void): Nodemon; + addEventListener( + event: 'log', + listener: (e: NodemonEventLog) => void + ): Nodemon; + addEventListener( + event: 'restart', + listener: (e?: NodemonEventRestart) => void + ): Nodemon; + addEventListener( + event: 'quit', + listener: (e?: NodemonEventQuit) => void + ): Nodemon; + addEventListener( + event: 'exit', + listener: (e?: NodemonEventExit) => void + ): Nodemon; + addEventListener( + event: 'config:update', + listener: (e?: NodemonEventConfig) => void + ): Nodemon; + + once(event: 'start' | 'crash', listener: () => void): Nodemon; + once(event: 'log', listener: (e: NodemonEventLog) => void): Nodemon; + once(event: 'restart', listener: (e?: NodemonEventRestart) => void): Nodemon; + once(event: 'quit', listener: (e?: NodemonEventQuit) => void): Nodemon; + once(event: 'exit', listener: (e?: NodemonEventExit) => void): Nodemon; + once( + event: 'config:update', + listener: (e?: NodemonEventConfig) => void + ): Nodemon; + + removeAllListeners(event: NodemonEventHandler): Nodemon; + emit(type: NodemonEventHandler, event?: any): Nodemon; + reset(callback: Function): Nodemon; + restart(): Nodemon; + config: NodemonSettings; +}; + +type NodemonEventLog = { + /** + detail*: what you get with nodemon --verbose. + status: subprocess starting, restarting. + fail: is the subprocess crashing. + error: is a nodemon system error. + */ + type: 'detail' | 'log' | 'status' | 'error' | 'fail'; + /** the plain text message */ + message: String; + /** contains the terminal escape codes to add colour, plus the "[nodemon]" prefix */ + colour: String; +}; + +interface NodemonEventRestart { + matched?: { + result: string[]; + total: number; + }; +} + +type NodemonEventQuit = 143 | 130; +type NodemonEventExit = number; + +// TODO: Define the type of NodemonEventConfig +type NodemonEventConfig = any; + +interface NodemonSettings { + /* restartable defaults to "rs" as a string the user enters */ + restartable?: false | String; + colours?: Boolean; + execMap?: { [key: string]: string }; + ignoreRoot?: string[]; + watch?: string[]; + stdin?: boolean; + runOnChangeOnly?: boolean; + verbose?: boolean; + signal?: string; + stdout?: boolean; + watchOptions?: WatchOptions; +} + +interface WatchOptions { + ignorePermissionErrors: boolean; + ignored: string; + persistent: boolean; + usePolling: boolean; + interval: number; +} diff --git a/jsconfig.json b/jsconfig.json new file mode 100644 index 00000000..d77141cb --- /dev/null +++ b/jsconfig.json @@ -0,0 +1,7 @@ +{ + "compilerOptions": { + "typeRoots": ["./index.d.ts", "./node_modules/@types"], + "checkJs": true + }, + "exclude": ["node_modules"] +} diff --git a/lib/nodemon.js b/lib/nodemon.js index ce649cb6..278ea658 100644 --- a/lib/nodemon.js +++ b/lib/nodemon.js @@ -16,6 +16,10 @@ var eventHandlers = {}; // stable module API config.required = utils.isRequired; +/** + * @param {NodemonSettings} settings + * @returns {Nodemon} + */ function nodemon(settings) { bus.emit('boot'); nodemon.reset(); diff --git a/package.json b/package.json index e887374b..63a03822 100644 --- a/package.json +++ b/package.json @@ -27,6 +27,7 @@ "terminal" ], "license": "MIT", + "types": "./index.d.ts", "main": "./lib/nodemon", "scripts": { "commitmsg": "commitlint -e",