@node-cli/perf 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Arno Versini
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,78 @@
+# Node CLI perf package
+
+![npm](https://img.shields.io/npm/v/@node-cli/perf?label=version&logo=npm)
+
+> Performance tools for nodejs command-line applications.
+
+## Performance
+
+The class Performance is a wrapper around [nodejs Performance measurement APIs](https://nodejs.org/api/perf_hooks.html).
+
+It is intended for an extremely simple case:
+
+- start performance monitoring
+- do something that takes a while
+- stop performance monitoring
+- read how much time passed between start and stop (in milliseconds)
+- rinse and repeat
+
+### Methods
+
+| Method | Description                                      |
+| ------ | ------------------------------------------------ |
+| start  | Starts measuring performance                     |
+| stop   | Stops measuring performance and store the result |
+
+| Getter           | Type   | Description          |
+| ---------------- | ------ | -------------------- |
+| results          | Object |                      |
+| results.duration | Number | Time in milliseconds |
+
+### Examples
+
+#### Basic performance gathering
+
+```js
+import { Performance } from "@node-cli/perf;
+const perf = new Performance();
+
+// Somewhere in your code, you want to start measuring performance:
+perf.start();
+// Do long lasting actions
+(...)
+// When done, tell performance to stop:
+perf.stop();
+// The duration can now be found in the Performance class getter `results`:
+console.log(`It took ${perf.results.duration} milliseconds to run...`);
+```
+
+#### Multiple performance gatherings
+
+```js
+import { Performance } from "@node-cli/perf;
+const perf = new Performance();
+
+// Somewhere in your code, you want to start measuring performance:
+perf.start();
+// Do long lasting actions
+(...)
+// When done, tell performance to stop:
+perf.stop();
+// Save the results
+const res1 = perf.results.duration;
+
+// Further down in your code, start measuring another performance:
+perf.start();
+// Do other long lasting actions
+(...)
+// When done, tell performance to stop:
+perf.stop();
+// Save the results
+const res2 = perf.results.duration;
+
+// -> res1 and res2 will have 2 different duration results.
+```
+
+## License
+
+MIT © Arno Versini

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * @file Automatically generated by barrelsby.
+ */
+
+export * from "./index";

package/dist/index.js

@@ -0,0 +1,3 @@
+export * from "./performance.js";
+
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["export * from \"./performance.js\";\n"],"names":[],"mappings":"AAAA,cAAc,mBAAmB"}

package/dist/performance.d.ts

@@ -0,0 +1,15 @@
+/// <reference types="node" resolution-mode="require"/>
+import { PerformanceObserver } from "node:perf_hooks";
+export declare class Performance {
+    perfObserver: PerformanceObserver;
+    startMarkerName: any;
+    measureName: string;
+    constructor();
+    start(): void;
+    stop(): void;
+    static now(): number;
+    get now(): typeof Performance.now;
+    get results(): {
+        duration: number;
+    };
+}

package/dist/performance.js

@@ -0,0 +1,51 @@
+import { PerformanceObserver, performance } from "node:perf_hooks";
+import { Logger } from "@node-cli/logger";
+import { uniqueID } from "./unique-id.js";
+const logger = new Logger({
+    boring: process.env.NODE_ENV === "test"
+});
+export class Performance {
+    perfObserver;
+    startMarkerName;
+    measureName;
+    constructor(){
+        this.perfObserver = new PerformanceObserver(/* istanbul ignore next */ ()=>{
+            performance.clearMeasures();
+        });
+        this.perfObserver.observe({
+            type: "measure"
+        });
+    }
+    start() {
+        if (this.startMarkerName) {
+            logger.error("Performance.start() can only be called once");
+        } else {
+            this.startMarkerName = uniqueID();
+            performance.mark(this.startMarkerName);
+        }
+    }
+    stop() {
+        if (this.startMarkerName) {
+            const stopMarkerName = uniqueID();
+            this.measureName = `internal-${this.startMarkerName}-${stopMarkerName}`;
+            performance.mark(stopMarkerName);
+            performance.measure(this.measureName, this.startMarkerName, stopMarkerName);
+            this.startMarkerName = undefined;
+        } else {
+            logger.error("Performance.stop() can only be called once after Performance.start()");
+        }
+    }
+    static now() {
+        return performance?.now() * 1e6;
+    }
+    get now() {
+        return Performance.now;
+    }
+    get results() {
+        return {
+            duration: performance?.getEntriesByName(this.measureName)[0]?.duration || undefined
+        };
+    }
+}
+
+//# sourceMappingURL=performance.js.map

package/dist/performance.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/performance.ts"],"sourcesContent":["import { PerformanceObserver, performance } from \"node:perf_hooks\";\n\nimport { Logger } from \"@node-cli/logger\";\nimport { uniqueID } from \"./unique-id.js\";\n\nconst logger = new Logger({\n\tboring: process.env.NODE_ENV === \"test\",\n});\n\nexport class Performance {\n\tperfObserver: PerformanceObserver;\n\tstartMarkerName: any;\n\tmeasureName: string;\n\n\tconstructor() {\n\t\tthis.perfObserver = new PerformanceObserver(\n\t\t\t/* istanbul ignore next */ () => {\n\t\t\t\tperformance.clearMeasures();\n\t\t\t}\n\t\t);\n\t\tthis.perfObserver.observe({ type: \"measure\" });\n\t}\n\n\tstart() {\n\t\tif (this.startMarkerName) {\n\t\t\tlogger.error(\"Performance.start() can only be called once\");\n\t\t} else {\n\t\t\tthis.startMarkerName = uniqueID();\n\t\t\tperformance.mark(this.startMarkerName);\n\t\t}\n\t}\n\n\tstop() {\n\t\tif (this.startMarkerName) {\n\t\t\tconst stopMarkerName = uniqueID();\n\t\t\tthis.measureName = `internal-${this.startMarkerName}-${stopMarkerName}`;\n\n\t\t\tperformance.mark(stopMarkerName);\n\n\t\t\tperformance.measure(\n\t\t\t\tthis.measureName,\n\t\t\t\tthis.startMarkerName,\n\t\t\t\tstopMarkerName\n\t\t\t);\n\t\t\tthis.startMarkerName = undefined;\n\t\t} else {\n\t\t\tlogger.error(\n\t\t\t\t\"Performance.stop() can only be called once after Performance.start()\"\n\t\t\t);\n\t\t}\n\t}\n\n\tstatic now() {\n\t\treturn performance?.now() * 1e6;\n\t}\n\n\tget now() {\n\t\treturn Performance.now;\n\t}\n\n\tget results() {\n\t\treturn {\n\t\t\tduration:\n\t\t\t\tperformance?.getEntriesByName(this.measureName)[0]?.duration ||\n\t\t\t\tundefined,\n\t\t};\n\t}\n}\n"],"names":["PerformanceObserver","performance","Logger","uniqueID","logger","boring","process","env","NODE_ENV","Performance","perfObserver","startMarkerName","measureName","constructor","clearMeasures","observe","type","start","error","mark","stop","stopMarkerName","measure","undefined","now","results","duration","getEntriesByName"],"mappings":"AAAA,SAASA,mBAAmB,EAAEC,WAAW,QAAQ,kBAAkB;AAEnE,SAASC,MAAM,QAAQ,mBAAmB;AAC1C,SAASC,QAAQ,QAAQ,iBAAiB;AAE1C,MAAMC,SAAS,IAAIF,OAAO;IACzBG,QAAQC,QAAQC,IAAIC,aAAa;AAClC;AAEA,OAAO,MAAMC;IACZC,aAAkC;IAClCC,gBAAqB;IACrBC,YAAoB;IAEpBC,aAAc;QACb,IAAI,CAACH,eAAe,IAAIV,oBACvB,wBAAwB,GAAG;YAC1BC,YAAYa;QACb;QAED,IAAI,CAACJ,aAAaK,QAAQ;YAAEC,MAAM;QAAU;IAC7C;IAEAC,QAAQ;QACP,IAAI,IAAI,CAACN,iBAAiB;YACzBP,OAAOc,MAAM;QACd,OAAO;YACN,IAAI,CAACP,kBAAkBR;YACvBF,YAAYkB,KAAK,IAAI,CAACR;QACvB;IACD;IAEAS,OAAO;QACN,IAAI,IAAI,CAACT,iBAAiB;YACzB,MAAMU,iBAAiBlB;YACvB,IAAI,CAACS,cAAc,CAAC,SAAS,EAAE,IAAI,CAACD,gBAAgB,CAAC,EAAEU,eAAe,CAAC;YAEvEpB,YAAYkB,KAAKE;YAEjBpB,YAAYqB,QACX,IAAI,CAACV,aACL,IAAI,CAACD,iBACLU;YAED,IAAI,CAACV,kBAAkBY;QACxB,OAAO;YACNnB,OAAOc,MACN;QAEF;IACD;IAEA,OAAOM,MAAM;QACZ,OAAOvB,aAAauB,QAAQ;IAC7B;IAEA,IAAIA,MAAM;QACT,OAAOf,YAAYe;IACpB;IAEA,IAAIC,UAAU;QACb,OAAO;YACNC,UACCzB,aAAa0B,iBAAiB,IAAI,CAACf,YAAY,CAAC,EAAE,EAAEc,YACpDH;QACF;IACD;AACD"}

package/dist/unique-id.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Generate a random number to append to an `id` string.
+ *
+ * NOTE: we are still using the good old lodash uniqueId when
+ * the code is not in production, so that the results are a
+ * little bit more consistent tests after test instead of
+ * being completely random, so that they do not break
+ * potential snapshot tests.
+ *
+ * @param {String} prefix - When a prefix is provided, the
+ *                          function will return a random
+ *                          number appended to the provided
+ *                          prefix.
+ *
+ * @returns {String} - Returns a string with random numbers.
+ */
+export declare const uniqueID: (prefix?: string) => string;

package/dist/unique-id.js

@@ -0,0 +1,26 @@
+import _ from "lodash";
+/**
+ * Generate a random number to append to an `id` string.
+ *
+ * NOTE: we are still using the good old lodash uniqueId when
+ * the code is not in production, so that the results are a
+ * little bit more consistent tests after test instead of
+ * being completely random, so that they do not break
+ * potential snapshot tests.
+ *
+ * @param {String} prefix - When a prefix is provided, the
+ *                          function will return a random
+ *                          number appended to the provided
+ *                          prefix.
+ *
+ * @returns {String} - Returns a string with random numbers.
+ */ export const uniqueID = (prefix)=>{
+    if (process.env.NODE_ENV !== "production") {
+        return _.uniqueId(prefix);
+    }
+    // Extract the decimal part
+    const randomNumber = `${Math.random()}`.split(".")[1];
+    return prefix ? `${prefix}${randomNumber}` : randomNumber;
+};
+
+//# sourceMappingURL=unique-id.js.map

package/dist/unique-id.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/unique-id.ts"],"sourcesContent":["import _ from \"lodash\";\n\n/**\n * Generate a random number to append to an `id` string.\n *\n * NOTE: we are still using the good old lodash uniqueId when\n * the code is not in production, so that the results are a\n * little bit more consistent tests after test instead of\n * being completely random, so that they do not break\n * potential snapshot tests.\n *\n * @param {String} prefix - When a prefix is provided, the\n *                          function will return a random\n *                          number appended to the provided\n *                          prefix.\n *\n * @returns {String} - Returns a string with random numbers.\n */\nexport const uniqueID = (prefix?: string): string => {\n\tif (process.env.NODE_ENV !== \"production\") {\n\t\treturn _.uniqueId(prefix);\n\t}\n\t// Extract the decimal part\n\tconst randomNumber = `${Math.random()}`.split(\".\")[1];\n\treturn prefix ? `${prefix}${randomNumber}` : randomNumber;\n};\n"],"names":["_","uniqueID","prefix","process","env","NODE_ENV","uniqueId","randomNumber","Math","random","split"],"mappings":"AAAA,OAAOA,OAAO,SAAS;AAEvB;;;;;;;;;;;;;;;CAeC,GACD,OAAO,MAAMC,WAAW,CAACC;IACxB,IAAIC,QAAQC,IAAIC,aAAa,cAAc;QAC1C,OAAOL,EAAEM,SAASJ;IACnB;IACA,2BAA2B;IAC3B,MAAMK,eAAe,CAAC,EAAEC,KAAKC,SAAS,CAAC,CAACC,MAAM,IAAI,CAAC,EAAE;IACrD,OAAOR,SAAS,CAAC,EAAEA,OAAO,EAAEK,aAAa,CAAC,GAAGA;AAC9C,EAAE"}

package/package.json

@@ -0,0 +1,32 @@
+{
+	"name": "@node-cli/perf",
+	"version": "1.0.0",
+	"license": "MIT",
+	"author": "Arno Versini",
+	"description": "Set of performance tools for Node.js",
+	"type": "module",
+	"exports": "./dist/index.js",
+	"files": [
+		"dist"
+	],
+	"node": ">=16",
+	"dependencies": {
+		"@node-cli/logger": ">=1.0.0",
+		"lodash": "4.17.21"
+	},
+	"scripts": {
+		"build": "yarn run clean && yarn run build:types && yarn run build:js && yarn run build:barrel",
+		"build:barrel": "barrelsby --delete --directory dist --pattern \"**/*.d.ts\" --name \"index.d\"",
+		"build:js": "swc --source-maps --out-dir dist src",
+		"build:types": "tsc",
+		"clean": "rimraf dist types coverage",
+		"lint": "prettier --write \"src/*.ts\" && eslint --fix \"src/*.ts\"",
+		"test": "cross-env-shell NODE_OPTIONS=--experimental-vm-modules jest",
+		"test:coverage": "npm run test -- --coverage",
+		"watch": "swc --watch --out-dir dist src"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"gitHead": "231e9a91b395b50b9ddb0b4fe6f8663a50f141a5"
+}