{"_id":"@aldy505/kruonis","_rev":"1-20fe724e11b2a4857dd343fc87b47443","name":"@aldy505/kruonis","dist-tags":{"latest":"0.0.1"},"versions":{"0.0.1":{"name":"@aldy505/kruonis","version":"0.0.1","description":"A tool to perform benchmarks on TS","main":"dist/index.cjs","module":"dist/index.mjs","types":"dist/index.d.ts","exports":{".":{"import":"./dist/index.mjs","require":"./dist/index.cjs"},"./package.json":"./package.json","./*":"./*"},"scripts":{"build":"rollup -c","test":"mocha --timeout 15000 -r esbuild-register tests/*.test.ts","test-coverage":"nyc -r lcov -e .ts -x \"*.test.ts\" mocha --timeout 15000 -r esbuild-register tests/*.test.ts && nyc report --reporter=text-lcov | coveralls"},"repository":{"type":"git","url":"git+https://github.com/most-inesctec/kruonis.git"},"keywords":["benchmarks","performance","analysis","typescript","benchmark","time","measure"],"author":{"name":"most-inesctec"},"license":"MIT","bugs":{"url":"https://github.com/most-inesctec/kruonis/issues"},"homepage":"https://github.com/most-inesctec/kruonis#readme","dependencies":{"performance-now":"^2.1.0"},"devDependencies":{"@types/chai":"^4.2.21","@types/mocha":"^9.0.0","@types/node":"^16.6.2","chai":"^4.3.4","coveralls":"^3.1.1","esbuild":"^0.12.21","esbuild-register":"^3.0.0","mocha":"^9.0.3","nyc":"^15.1.0","rollup":"^2.56.2","rollup-plugin-typescript2":"^0.30.0","typedoc":"^0.21.6","typescript":"^4.3.5"},"gitHead":"9cb5a5184b6462c5dd838f62c0a22ad8d586afbc","_id":"@aldy505/kruonis@0.0.1","_nodeVersion":"16.6.2","_npmVersion":"7.20.6","dist":{"integrity":"sha512-ZfKzadNJw6g3nXZjK3sxFXum8J/vuf8YdHbESzNl04OBkQRtCtPxYHRzHwwIKc8sABcxbvu+0R9tPOkbIYXQaw==","shasum":"85fb8b03b5a5b47543ffbbac183db41b6e3ed938","tarball":"https://registry.npmjs.org/@aldy505/kruonis/-/kruonis-0.0.1.tgz","fileCount":16,"unpackedSize":33313,"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v3.0.13\r\nComment: https://openpgpjs.org\r\n\r\nwsFcBAEBCAAQBQJhH+f8CRA9TVsSAnZWagAA4q4QAJqh/h06lV8oq+WomB6t\nIogRDor6GEm+Deupgw22HcOD4qfKFuBg9T/NERzafAkdPOE58D/j8HVlTm3R\nhxw0qKBgLo96gdhqZphDaTHN9yRj5FhMWNztUyVk/pAYBzijzeZLUjz6kJXp\nXGSOKE6SSD+pvcXAeNVhAvhmLoRbn56/WJUJN2B1Z4Mj353G9+DByzqmgKu8\n8UEPqHpFCH0SsF1xfPAwC1dWdA+9/d4zG58kbAk4t7G6tCAwNUo4jcBOdbTW\n0dus9fkSSyRcZb2LgpnxzNs3pqYsKNBWHeta0H3YuUDdgB1WXdBrikn7beze\n2ov7b2nqqbeYswQCXWsv0VFImZC70MoJQ3PTb9YqOx19k05rZiM1hQoNB7sR\nYNcrooKow4mU4IJmy7QgoXg5Hpq7el2jQzpvz70hXec/s30Cyh2v4UgrPus6\nNEP2E7Vl0BusXnntDmD+DQwyJCm6dOEJCuJhdcWzd5+FVW0LZ018IeBYw/hS\nzE9NzkPcrIB/vrHp3wD4qkybP8NdeqsZJIQezS9e/5FIhOJACZYaRGCiCTae\n/QCOfwxzmw2wz8yJCVMSVaJKggtmW2NJ168q35t5fUBHjTJ2AFLQJWx4EY/L\nY+RRxirWyFFHf2XYbK0B/S675X4gu2j+Atnfr+ygv6e8oSkUcAOLdtKv8mCe\nSXwZ\r\n=o4qe\r\n-----END PGP SIGNATURE-----\r\n","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEUCIQDaEqg/Ac0/gqXhynOUhfqutYT0E8TJrJhY2e3+X6j5MQIgFhiio7HsmmqBLE1Afklsud9uilEwhfboIGIjCMUNWzY="}]},"_npmUser":{"name":"aldy505","email":"aldy505@tutanota.com"},"directories":{},"maintainers":[{"name":"aldy505","email":"aldy505@tutanota.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/kruonis_0.0.1_1629480956664_0.9679349689876775"},"_hasShrinkwrap":false}},"time":{"created":"2021-08-20T17:35:56.616Z","0.0.1":"2021-08-20T17:35:56.814Z","modified":"2022-04-04T12:36:41.505Z"},"maintainers":[{"name":"aldy505","email":"aldy505@tutanota.com"}],"description":"A tool to perform benchmarks on TS","homepage":"https://github.com/most-inesctec/kruonis#readme","keywords":["benchmarks","performance","analysis","typescript","benchmark","time","measure"],"repository":{"type":"git","url":"git+https://github.com/most-inesctec/kruonis.git"},"author":{"name":"most-inesctec"},"bugs":{"url":"https://github.com/most-inesctec/kruonis/issues"},"license":"MIT","readme":"# :hourglass: kruonis :hourglass:\n\nA tool to perform benchmarks on _TypeScript_.\n\n![npm](https://img.shields.io/npm/v/kruonis)\n![npm](https://img.shields.io/npm/dm/kruonis)\n![NPM](https://img.shields.io/npm/l/kruonis)\n[![BCH compliance](https://bettercodehub.com/edge/badge/most-inesctec/kruonis?branch=master)](https://bettercodehub.com/)\n[![Build Status](https://travis-ci.com/most-inesctec/kruonis.svg?token=J52cxsfW92GANe4gUJgy&branch=master)](https://travis-ci.com/most-inesctec/kruonis)\n[![Coverage Status](https://coveralls.io/repos/github/most-inesctec/kruonis/badge.svg?branch=master)](https://coveralls.io/github/most-inesctec/kruonis?branch=master)\n\n___Kruonis___ is an embodiment of the Lithuanian goddess of time, as essentially the tool measures the time it takes for code to run.\n\n## tl;dr\n\nA `Benchmark` is a set of `Tests`.\n\nWhen running a `Benchmark`, each `Test` is run several times (test _cycle_). \n\n_Kruonis_ summarizes the [statistiscs](https://github.com/most-inesctec/kruonis/blob/master/src/Stats/Stats.ts) of each cycle's performance among all cycles. \n\n__Note__: we use [performance-now](https://www.npmjs.com/package/performance-now) to measure performance.\n\n\n## Usage example\n\nFirst, import _kruonis_' main classes:\n\n```TypeScript\nimport { Benchmark, Test } from \"kruonis\";\n```\n\nThen, let's create a benchmark:\n\n```TypeScript\nlet benchmark = new Benchmark();\n```\n\nAdditionally, _kruonis_ lets you pass your benchmark properties as an object to the constructor, such as: \n\n```TypeScript\nbenchmark = new Benchmark({ 'maxCycles': 50, 'name': 'Benchmark', 'maxTime': 15 });\n```\n\nThe possible properties are available [here](https://github.com/most-inesctec/kruonis/blob/master/src/BenchmarkProperties.ts).\n\nWe can also define events for the benchmark class, such as:\n```TypeScript\nbenchmark\n    .on('onBegin', (benchmark: Benchmark) => {\n        // Code to run on the beginning of this benchmark\n        // Example:\n        console.log(\"Beginning of the benchmark\")\n    })\n    .on('onTestBegin', (benchmark: Benchmark, test: Test) => {\n        // Code to run on the end of the benchmark (on the end of all tests)\n        // Example:\n        console.log(\"Running test: \" + test.name)\n    })\n    .on('onTestEnd', (benchmark: Benchmark) => {\n        // Code to run on the end of the benchmark (on the end of all tests)\n        // Example:\n        console.log(\"The stats of the test that just ran are: \" + test.getStats())\n    })\n    .on('onEnd', (benchmark: Benchmark) => {\n        // Code to run on the end of the benchmark (on the end of all tests)\n        // Example:\n        console.log(\"Ended benchmark\")\n    });\n```\n\nA benchmark consists of a set of tests. Therefore, we can add tests to a benchmark. Each `Test` can also take events. For example:\n\n```TypeScript\n// Example object for test\nlet testArray: number[];\n\nbenchmark\n    .add(\n        new Test('exampleTest1', () => {\n            // Measure code performance of what goes here\n            // Example:\n            for (let i = 0; i < testArray.length; ++i)\n                testArray[i] *= testArray[i];\n        })\n        .on('onBegin', (test: Test) => {\n            // Code to execute on before starting the cycle loop\n            // Example:\n            testArray = [1, 2, 3, 4, 5, 6];\n        })\n        .on('onCycleBegin', (test: Test) => {\n            // Code to execute before each cycle\n            // Example:\n            console.log(\"Starting cycle\");\n        })\n        .on('onCycleEnd', (test: Test) => {\n            // Code to execute after each cycle ran\n            // Example:\n            testArray = [1, 2, 3, 4, 5, 6];\n        })\n        .on('onEnd', (test: Test) => {\n            // Test to execute after all cycles\n            // The Stats object with the cycle performances is now populated\n            // Example:\n            console.log(\"Finished running all cycles\");\n        })\n    )\n    .add(\n        // Add another test ...\n    );\n```\n\nAfter adding all tests, we can then run them using:\n```TypeScript\nbenchmark.run();\n```\n\nAfter running the benchmark we can obtain the statistics of each ran test in several ways:\n1. Using the return array of the `behcnmark.run()` method. Example:\n```TypeScript\nconst results: Array<[string, Stats]> = benchmark.run();\nfor(let result of results) {\n    console.log(\"Test name: \" + result[0]);\n    console.log(\"Test stats: \" + result[1]);\n}\n```\n2. Adding an event listener of the `onTestEnd` event to the benchmark.\n```TypeScript\nbenchmark.on('onTestEnd', (benchmark: Benchmark, test: Test) => {\n    console.log(\"Test name: \" + test.name);\n    console.log(\"Test stats: \" + test.getStats());\n}). run();\n```\n3. Adding an event listener of the `onEnd` event to the benchmark.\n```TypeScript\nbenchmark.on('onEnd', (benchmark: Benchmark) => {\n    for(let result of benchmark.getResults()) {\n        console.log(\"Test name: \" + result[0]);\n        console.log(\"Test stats: \" + result[1]);\n    }\n}). run();\n```\n4. Adding an identical event listener to all tests' `onEnd` events.\n```TypeScript\nbenchmark\n    .add(\n        new Test('exampleTest1', () => {\n            // Code\n        })\n        .on('onEnd', (test: Test) => {\n            console.log(\"Test name: \" + test.name);\n            console.log(\"Test stats: \" + test.getStats());\n        })\n    .add(\n        // Similar for other tests\n    ).run();\n}\n```\n\nThe Statistics outputted can be consulted [here](https://github.com/most-inesctec/kruonis/blob/master/src/Stats/Stats.ts). An example of a `Stats` object is:\n```TypeScript\n{\n    // The mean run time of the test\n    'mean': 11.4,\n    // The standard deviation\n    'std': 3.352610922848042,\n    // The number of ran cycles\n    'count': 10,\n    // The maximum time it took to run the test code\n    'max': 18,\n    // The maximum time it took to run the test code\n    'min': 6\n}\n```\n\n## How does it work?\n\nThe logic behind the `benchmark.run()` method (and the order in which the events are run) is:\n```python\n# Benchmark scope\nBenchmark.onBegin()\n\nfor each test of tests:\n    Benchmark.onTestBegin()\n\n    # Test scope\n    test.onBegin()\n\n    while(number of cycles < minCycles and\n          spent time on ran cycles < maxTime and\n          number of ran cycles < maxCycles)\n\n        # Cycle scope\n        test.onCycleBegin()\n\n        runTestCode()\n\n        test.onCycleEnd()\n\n    test.onEnd()\n    # Ended test\n\n    Benchmark.onTestEnd()\n\nBenchmark.onEnd()\n```\n","readmeFilename":"README.md"}