poku 1.10.1 → 1.11.0

package/README.md

@@ -60,6 +60,7 @@ Enjoying **Poku**? Consider giving him a star ⭐️
 <span>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</span><img width="16" height="16" alt="check" src="https://raw.githubusercontent.com/wellwelwel/poku/main/.github/assets/readme/check.svg"> No eval needed 🔐<br />
 <span>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</span><img width="16" height="16" alt="check" src="https://raw.githubusercontent.com/wellwelwel/poku/main/.github/assets/readme/check.svg"> No global state<br />
 <img width="16" height="16" alt="check" src="https://raw.githubusercontent.com/wellwelwel/poku/main/.github/assets/readme/check.svg"> **Parallel** and **Sequential** runs 🏃🏽🏃🏻<br />
+<img width="16" height="16" alt="check" src="https://raw.githubusercontent.com/wellwelwel/poku/main/.github/assets/readme/check.svg"> Easily handle **Background Services** and **Servers**, **Processes** and **Ports**<br />
 
 <img width="16" height="16" alt="check" src="https://raw.githubusercontent.com/wellwelwel/poku/main/.github/assets/readme/check.svg"> **Poku** is [**100%** documented](https://poku.io/docs)<br />
 <img width="16" height="16" alt="check" src="https://raw.githubusercontent.com/wellwelwel/poku/main/.github/assets/readme/check.svg"> Designed to be human-friendly<br />
@@ -187,10 +188,15 @@ deno run npm:poku
 
 ### Essentials
 
-- [**poku**](https://poku.io/docs/category/poku) (_test runner_)
-- [**assert**](https://poku.io/docs/documentation/assert) (_test assertion_)
-- [**startScript**](https://poku.io/docs/documentation/startScript) (_run `package.json` scripts in a background process_)
-- [**startService**](https://poku.io/docs/documentation/startService) (_run files in a background process_)
+- **Test**
+  - [**poku**](https://poku.io/docs/category/poku) (_test runner_)
+  - [**assert**](https://poku.io/docs/documentation/assert) (_test assertion_)
+- **Background Services**
+  - [**startScript**](https://poku.io/docs/documentation/startScript) (_run `package.json` scripts in a background process_)
+  - [**startService**](https://poku.io/docs/documentation/startService) (_run files in a background process_)
+- **Processes**
+  - [**kill**](https://poku.io/docs/documentation/processes/kill) (_terminate Ports, Port Ranges and PIDs_)
+  - [**getPIDs**](https://poku.io/docs/documentation/processes/get-pids) (_get all processes IDs using ports and port ranges_)
 
 ### Helpers
 

package/lib/@types/background-process.d.ts

@@ -43,5 +43,5 @@ export type StartServiceOptions = {
      */
     readonly platform?: Configs['platform'];
 } & BackgroundProcessOptions;
-export type End = (port?: number) => Promise<void>;
+export type End = (port?: number | number[]) => Promise<void>;
 export {};

package/lib/bin/index.js

@@ -1,5 +1,14 @@
 #! /usr/bin/env node
 "use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
 var _a, _b;
 Object.defineProperty(exports, "__esModule", { value: true });
 /* c8 ignore start */
@@ -14,19 +23,41 @@ const dirs = ((0, get_arg_js_1.hasArg)('include')
 const platform = (0, get_arg_js_1.getArg)('platform');
 const filter = (0, get_arg_js_1.getArg)('filter');
 const exclude = (0, get_arg_js_1.getArg)('exclude');
+const killPort = (0, get_arg_js_1.getArg)('kill-port');
+const killRange = (0, get_arg_js_1.getArg)('kill-range');
+const killPID = (0, get_arg_js_1.getArg)('kill-pid');
 const parallel = (0, get_arg_js_1.hasArg)('parallel');
 const quiet = (0, get_arg_js_1.hasArg)('quiet');
 const debug = (0, get_arg_js_1.hasArg)('debug');
 const failFast = (0, get_arg_js_1.hasArg)('fail-fast');
 if ((0, get_arg_js_1.hasArg)('log-success'))
     console.log(`The flag ${format_js_1.format.bold('--log-success')} is deprecated. Use ${format_js_1.format.bold('--debug')} instead.`);
-(0, index_js_1.poku)(dirs, {
-    platform: (0, get_runtime_js_1.platformIsValid)(platform) ? platform : undefined,
-    filter: filter ? new RegExp((0, list_files_js_1.escapeRegExp)(filter)) : undefined,
-    exclude: exclude ? new RegExp((0, list_files_js_1.escapeRegExp)(exclude)) : undefined,
-    parallel,
-    quiet,
-    debug,
-    failFast,
-});
+(() => __awaiter(void 0, void 0, void 0, function* () {
+    if (killPort) {
+        const ports = killPort.split(',').map((port) => Number(port));
+        yield index_js_1.kill.port(ports);
+    }
+    if (killRange) {
+        const ranges = killRange.split(',');
+        for (const range of ranges) {
+            const ports = range.split('-').map((port) => Number(port));
+            const startsAt = ports[0];
+            const endsAt = ports[1];
+            yield index_js_1.kill.range(startsAt, endsAt);
+        }
+    }
+    if (killPID) {
+        const PIDs = killPID.split(',').map((port) => Number(port));
+        yield index_js_1.kill.pid(PIDs);
+    }
+    yield (0, index_js_1.poku)(dirs, {
+        platform: (0, get_runtime_js_1.platformIsValid)(platform) ? platform : undefined,
+        filter: filter ? new RegExp((0, list_files_js_1.escapeRegExp)(filter)) : undefined,
+        exclude: exclude ? new RegExp((0, list_files_js_1.escapeRegExp)(exclude)) : undefined,
+        parallel,
+        quiet,
+        debug,
+        failFast,
+    });
+}))();
 /* c8 ignore stop */

package/lib/index.d.ts

@@ -7,6 +7,7 @@ export { beforeEach, afterEach } from './modules/each.js';
 export { publicListFiles as listFiles } from './modules/list-files.js';
 export { test } from './modules/test.js';
 export { startService, startScript } from './modules/create-service.js';
+export { getPIDs, kill } from './modules/processes.js';
 export type { Code } from './@types/code.js';
 export type { Configs } from './@types/poku.js';
 export type { Configs as ListFilesConfigs } from './@types/list-files.js';

package/lib/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.startScript = exports.startService = exports.test = exports.listFiles = exports.afterEach = exports.beforeEach = exports.assertPromise = exports.log = exports.describe = exports.assert = exports.exit = exports.poku = void 0;
+exports.kill = exports.getPIDs = exports.startScript = exports.startService = exports.test = exports.listFiles = exports.afterEach = exports.beforeEach = exports.assertPromise = exports.log = exports.describe = exports.assert = exports.exit = exports.poku = void 0;
 /* c8 ignore start */
 var poku_js_1 = require("./modules/poku.js");
 Object.defineProperty(exports, "poku", { enumerable: true, get: function () { return poku_js_1.poku; } });
@@ -23,4 +23,7 @@ Object.defineProperty(exports, "test", { enumerable: true, get: function () { re
 var create_service_js_1 = require("./modules/create-service.js");
 Object.defineProperty(exports, "startService", { enumerable: true, get: function () { return create_service_js_1.startService; } });
 Object.defineProperty(exports, "startScript", { enumerable: true, get: function () { return create_service_js_1.startScript; } });
+var processes_js_1 = require("./modules/processes.js");
+Object.defineProperty(exports, "getPIDs", { enumerable: true, get: function () { return processes_js_1.getPIDs; } });
+Object.defineProperty(exports, "kill", { enumerable: true, get: function () { return processes_js_1.kill; } });
 /* c8 ignore stop */

package/lib/modules/create-service.d.ts

@@ -15,10 +15,6 @@ export declare const startService: (file: string, options?: StartServiceOptions)
  * By default, it uses **npm**, but you can costumize it using the `runner` option.
  *
  * Useful for servers, APIs, etc.
- *
- * ---
- *
- * For **Bun**, please see https://github.com/oven-sh/bun/issues/11055
  */
 export declare const startScript: (script: string, options?: StartScriptOptions) => Promise<{
     end: End;

package/lib/modules/create-service.js

@@ -18,7 +18,7 @@ const node_child_process_1 = require("child_process");
 const runner_js_1 = require("../helpers/runner.js");
 const node_path_1 = __importDefault(require("path"));
 const list_files_js_1 = require("./list-files.js");
-const pid_js_1 = require("../services/pid.js");
+const processes_js_1 = require("./processes.js");
 const runningProcesses = new Map();
 /* c8 ignore start */
 node_process_1.default.once('SIGINT', () => __awaiter(void 0, void 0, void 0, function* () {
@@ -51,7 +51,7 @@ const backgroundProcess = (runtime, args, file, options) => new Promise((resolve
             try {
                 runningProcesses.delete(PID);
                 if (runner_js_1.isWindows) {
-                    pid_js_1.killPID.windows(PID);
+                    processes_js_1.kill.pid(PID);
                     return;
                 }
                 if (['bun', 'deno'].includes(runtime) ||
@@ -62,16 +62,7 @@ const backgroundProcess = (runtime, args, file, options) => new Promise((resolve
                     node_process_1.default.kill(-PID, 'SIGKILL');
                 if (port && ['bun', 'deno'].includes(runtime)) {
                     setTimeout(() => __awaiter(void 0, void 0, void 0, function* () {
-                        const PIDs = runner_js_1.isWindows
-                            ? yield pid_js_1.findPID.windows(port)
-                            : yield pid_js_1.findPID.unix(port);
-                        for (const subPID of PIDs) {
-                            if (!subPID)
-                                continue;
-                            runner_js_1.isWindows
-                                ? yield pid_js_1.killPID.windows(subPID)
-                                : yield pid_js_1.killPID.unix(subPID);
-                        }
+                        yield processes_js_1.kill.port(port);
                         resolve(undefined);
                         return;
                     }));
@@ -170,10 +161,6 @@ exports.startService = startService;
  * By default, it uses **npm**, but you can costumize it using the `runner` option.
  *
  * Useful for servers, APIs, etc.
- *
- * ---
- *
- * For **Bun**, please see https://github.com/oven-sh/bun/issues/11055
  */
 const startScript = (script, options) => __awaiter(void 0, void 0, void 0, function* () {
     const runner = (options === null || options === void 0 ? void 0 : options.runner) || 'npm';

package/lib/modules/processes.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Returns an array containing the ID of all processes listening to the specified port
+ */
+export declare const getPIDs: ((port: number | number[]) => Promise<number[]>) & {
+    /**
+     * Returns an array containing the ID of all processes listening to the specified range port
+     */
+    range: (startsAt: number, endsAt: number) => Promise<number[]>;
+};
+export declare const kill: {
+    /**
+     * Terminates the specified process ID
+     */
+    pid: (PID: number | number[]) => Promise<void>;
+    /**
+     * Terminates all processes listening on the specified port
+     */
+    port: (port: number | number[]) => Promise<void>;
+    /**
+     * Terminates all processes listening on the specified range ports
+     */
+    range: (startsAt: number, endsAt: number) => Promise<void>;
+};

package/lib/modules/processes.js

@@ -0,0 +1,77 @@
+"use strict";
+/* c8 ignore start */
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.kill = exports.getPIDs = void 0;
+const runner_js_1 = require("../helpers/runner.js");
+const pid_js_1 = require("../services/pid.js");
+const getPIDsByPorts = (port) => __awaiter(void 0, void 0, void 0, function* () {
+    const ports = (0, pid_js_1.setPortsAndPIDs)(port);
+    const PIDs = [];
+    yield Promise.all(ports.map((p) => __awaiter(void 0, void 0, void 0, function* () {
+        PIDs.push(...(yield (runner_js_1.isWindows
+            ? pid_js_1.getPIDs.windows(p)
+            : pid_js_1.getPIDs.unix(p))));
+    })));
+    return PIDs;
+});
+const getPIDsByRange = (startsAt, endsAt) => __awaiter(void 0, void 0, void 0, function* () {
+    const ports = (0, pid_js_1.populateRange)(startsAt, endsAt);
+    return yield (0, exports.getPIDs)(ports);
+});
+/**
+ * Returns an array containing the ID of all processes listening to the specified port
+ */
+exports.getPIDs = Object.assign(getPIDsByPorts, {
+    /**
+     * Returns an array containing the ID of all processes listening to the specified range port
+     */
+    range: getPIDsByRange,
+});
+const killPID = (PID) => __awaiter(void 0, void 0, void 0, function* () {
+    const PIDs = (0, pid_js_1.setPortsAndPIDs)(PID);
+    yield Promise.all(PIDs.map((p) => __awaiter(void 0, void 0, void 0, function* () {
+        runner_js_1.isWindows
+            ? yield pid_js_1.killPID.windows(p)
+            : yield pid_js_1.killPID.unix(p);
+    })));
+});
+const killPort = (port) => __awaiter(void 0, void 0, void 0, function* () {
+    const PIDs = yield (0, exports.getPIDs)(port);
+    for (const PID of PIDs) {
+        if (!PID)
+            continue;
+        yield killPID(PID);
+    }
+});
+const killRange = (startsAt, endsAt) => __awaiter(void 0, void 0, void 0, function* () {
+    const PIDs = yield exports.getPIDs.range(startsAt, endsAt);
+    for (const PID of PIDs) {
+        if (!PID)
+            continue;
+        yield killPID(PID);
+    }
+});
+exports.kill = {
+    /**
+     * Terminates the specified process ID
+     */
+    pid: killPID,
+    /**
+     * Terminates all processes listening on the specified port
+     */
+    port: killPort,
+    /**
+     * Terminates all processes listening on the specified range ports
+     */
+    range: killRange,
+};
+/* c8 ignore stop */

package/lib/services/pid.d.ts

@@ -1,8 +1,10 @@
+export declare const setPortsAndPIDs: (portOrPID: number | number[]) => number[];
+export declare const populateRange: (startsAt: number, endsAt: number) => number[];
 export declare const killPID: {
     unix: (PID: number) => Promise<void>;
     windows: (PID: number) => Promise<void>;
 };
-export declare const findPID: {
+export declare const getPIDs: {
     unix: (port: number) => Promise<number[]>;
     windows: (port: number) => Promise<number[]>;
 };

package/lib/services/pid.js

@@ -1,74 +1,86 @@
 "use strict";
 /* c8 ignore start */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.findPID = exports.killPID = void 0;
+exports.getPIDs = exports.killPID = exports.populateRange = exports.setPortsAndPIDs = void 0;
 const node_child_process_1 = require("child_process");
 const node_os_1 = require("os");
+const force_array_js_1 = require("../helpers/force-array.js");
+const setPortsAndPIDs = (portOrPID) => (0, force_array_js_1.forceArray)(portOrPID)
+    .map((p) => Number(p))
+    .filter((p) => !isNaN(p));
+exports.setPortsAndPIDs = setPortsAndPIDs;
+const populateRange = (startsAt, endsAt) => {
+    const first = Number(startsAt);
+    const last = Number(endsAt);
+    return Array.from({ length: last - first + 1 }, (_, i) => first + i);
+};
+exports.populateRange = populateRange;
 exports.killPID = {
     unix: (PID) => new Promise((resolve) => {
-        try {
-            const service = (0, node_child_process_1.spawn)('kill', ['-9', String(PID)]);
-            service.on('close', () => {
-                resolve(undefined);
-            });
-        }
-        catch (_a) {
+        const service = (0, node_child_process_1.spawn)('kill', ['-9', String(Number(PID))]);
+        service.on('close', () => {
             resolve(undefined);
-        }
+        });
     }),
     windows: (PID) => new Promise((resolve) => {
-        try {
-            const service = (0, node_child_process_1.spawn)('taskkill', ['/F', '/T', '/PID', String(PID)]);
-            service.on('close', () => {
-                resolve(undefined);
-            });
-        }
-        catch (_a) {
+        const service = (0, node_child_process_1.spawn)('taskkill', [
+            '/F',
+            '/T',
+            '/PID',
+            String(Number(PID)),
+        ]);
+        service.on('close', () => {
             resolve(undefined);
-        }
+        });
     }),
 };
-exports.findPID = {
+exports.getPIDs = {
     unix: (port) => new Promise((resolve) => {
-        try {
-            const PIDs = new Set();
-            const service = (0, node_child_process_1.spawn)('lsof', ['-t', '-i', `:${Number(port)}`]);
-            service.stdout.on('data', (data) => {
-                const output = data.toString().trim().split(node_os_1.EOL);
-                output.forEach((pid) => {
-                    if (pid)
-                        PIDs.add(Number(pid));
-                });
-                service.on('close', () => {
-                    resolve(Array.from(PIDs));
-                });
+        const PIDs = new Set();
+        const service = (0, node_child_process_1.spawn)('lsof', [
+            '-t',
+            '-i',
+            `:${Number(port)}`,
+            '-s',
+            'TCP:LISTEN',
+        ]);
+        service.stdout.on('data', (data) => {
+            const output = data.toString().trim().split(node_os_1.EOL);
+            output.forEach((pid) => {
+                if (pid)
+                    PIDs.add(Number(pid));
             });
-        }
-        catch (_a) { }
+        });
+        service.on('close', () => {
+            resolve(Array.from(PIDs));
+        });
     }),
     windows: (port) => new Promise((resolve) => {
-        try {
-            const PIDs = new Set();
-            const service = (0, node_child_process_1.spawn)('cmd.exe', [
-                '/c',
-                `netstat -aon | findstr :${Number(port)}`,
-            ]);
-            service.stdout.on('data', (data) => {
-                const output = data.toString().trim();
-                const lines = output.trim().split(node_os_1.EOL);
-                lines.map((line) => {
-                    const tokens = line.trim().split(/\s+/);
-                    PIDs.add(Number(tokens[4]));
-                });
-            });
-            service.on('close', () => {
-                resolve(Array.from(PIDs));
-            });
-            service.stderr.on('data', (data) => {
-                console.error(`Erro: ${data}`);
+        const PIDs = new Set();
+        const service = (0, node_child_process_1.spawn)('cmd.exe', [
+            '/c',
+            `netstat -aon | findstr :${Number(port)}`,
+        ]);
+        service.stdout.on('data', (data) => {
+            const output = data.toString().trim();
+            const lines = output.trim().split(node_os_1.EOL);
+            /**
+             * TODO: Chack line for "/:\d+\s+\w+\s+\d+\s+(\d+)/" regex match to safe support multiple Windows versions
+             * (Tested against ReDos Checker)
+             */
+            lines.map((line) => {
+                const tokens = line.trim().split(/\s+/);
+                const stateIndex = tokens.indexOf('LISTENING');
+                if (stateIndex !== -1 && tokens[stateIndex + 1]) {
+                    const pid = Number(tokens[stateIndex + 1]);
+                    if (!isNaN(pid))
+                        PIDs.add(pid);
+                }
             });
-        }
-        catch (_a) { }
+        });
+        service.on('close', () => {
+            resolve(Array.from(PIDs));
+        });
     }),
 };
 /* c8 ignore stop */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "poku",
-  "version": "1.10.1",
+  "version": "1.11.0",
   "description": "🐷 Poku makes testing easy for Node.js, Bun & Deno at the same time.",
   "main": "./lib/index.js",
   "scripts": {
@@ -83,8 +83,10 @@
     "files",
     "list-files",
     "tsx",
-    "fast",
-    "easy",
+    "kill",
+    "process",
+    "port",
+    "cross-platform",
     "poku",
     "pokujs"
   ],