flexi-bench 0.0.0-alpha.1

package/LICENSE

@@ -0,0 +1,19 @@
+MIT License
+
+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/dist/api-types.d.ts

@@ -0,0 +1,24 @@
+import { Variation } from './variation';
+import { Benchmark } from './benchmark';
+export type MaybePromise<T> = T | Promise<T>;
+export type SetupMethod = (variation: Variation) => MaybePromise<void>;
+export type TeardownMethod = (variation: Variation) => MaybePromise<void>;
+export type ActionMethod = (variation: Variation) => MaybePromise<void>;
+export type EnvironmentVariableOptions = readonly (readonly [key: string, values: readonly string[]])[] | [key: string, values: string[]][];
+export type Result = {
+    label: string;
+    min: number;
+    max: number;
+    average: number;
+    p95: number;
+};
+export interface ProgressContext {
+    totalIterations?: number;
+    completedIterations: number;
+    timeout?: number;
+    timeElapsed: number;
+}
+export interface Reporter {
+    progress?: (name: string, progress: number, context: ProgressContext) => void;
+    report: (benchmark: Benchmark, results: Result[]) => void;
+}

package/dist/api-types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/benchmark.d.ts

@@ -0,0 +1,33 @@
+import { Variation } from './variation';
+import { Reporter } from './api-types';
+import { ActionMethod } from './api-types';
+import { TeardownMethod } from './api-types';
+import { SetupMethod } from './api-types';
+export declare class Benchmark {
+    name: string;
+    private setupMethods;
+    private teardownMethods;
+    private action?;
+    variations: Variation[];
+    private iterations?;
+    private timeout?;
+    private reporter;
+    constructor(name: string, options?: {
+        setup?: SetupMethod;
+        teardown?: TeardownMethod;
+        action?: ActionMethod;
+        iterations?: number;
+        timeout?: number;
+        reporter?: Reporter;
+    });
+    withVariation(name: string, builder: (variation: Variation) => Variation): this;
+    withVariations(variations: Variation[]): this;
+    withSetup(setup: () => void): this;
+    withTeardown(teardown: () => void): this;
+    withAction(action: () => void): this;
+    withIterations(iterations: number): this;
+    withTimeout(timeout: number): this;
+    withReporter(reporter: Reporter): this;
+    run(): Promise<void>;
+    private validate;
+}

package/dist/benchmark.js

@@ -0,0 +1,189 @@
+"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());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Benchmark = void 0;
+const console_reporter_1 = require("./console-reporter");
+const variation_1 = require("./variation");
+class Benchmark {
+    constructor(name, options) {
+        this.name = name;
+        this.setupMethods = [];
+        this.teardownMethods = [];
+        this.variations = [];
+        if (options === null || options === void 0 ? void 0 : options.action) {
+            this.action = options.action;
+        }
+        if (options === null || options === void 0 ? void 0 : options.setup) {
+            this.setupMethods.push(options.setup);
+        }
+        if (options === null || options === void 0 ? void 0 : options.teardown) {
+            this.teardownMethods.push(options.teardown);
+        }
+        if (options === null || options === void 0 ? void 0 : options.iterations) {
+            this.iterations = options.iterations;
+        }
+        if (options === null || options === void 0 ? void 0 : options.timeout) {
+            this.timeout = options.timeout;
+        }
+        this.reporter = (options === null || options === void 0 ? void 0 : options.reporter) || new console_reporter_1.ConsoleReporter();
+    }
+    withVariation(name, builder) {
+        this.variations.push(builder(new variation_1.Variation(name)));
+        return this;
+    }
+    withVariations(variations) {
+        this.variations.push(...variations);
+        return this;
+    }
+    withSetup(setup) {
+        this.setupMethods.push(setup);
+        return this;
+    }
+    withTeardown(teardown) {
+        this.teardownMethods.push(teardown);
+        return this;
+    }
+    withAction(action) {
+        this.action = action;
+        return this;
+    }
+    withIterations(iterations) {
+        this.iterations = iterations;
+        return this;
+    }
+    withTimeout(timeout) {
+        this.timeout = timeout;
+        return this;
+    }
+    withReporter(reporter) {
+        this.reporter = reporter;
+        return this;
+    }
+    run() {
+        return __awaiter(this, void 0, void 0, function* () {
+            this.validate();
+            let results = [];
+            if (this.variations.length === 0) {
+                this.variations.push(new variation_1.Variation('default'));
+            }
+            const totalIterations = this.iterations
+                ? this.variations.length * this.iterations
+                : undefined;
+            const startTime = performance.now();
+            let totalCompletedIterations = 0;
+            for (let variationIndex = 0; variationIndex < this.variations.length; variationIndex++) {
+                const variation = this.variations[variationIndex];
+                const timings = [];
+                // SETUP
+                const oldEnv = Object.assign({}, process.env);
+                process.env = Object.assign(Object.assign({}, process.env), variation.environment);
+                for (const setup of this.setupMethods) {
+                    yield setup(variation);
+                }
+                for (const setup of variation.setupMethods) {
+                    yield setup(variation);
+                }
+                // ACT
+                const benchmarkThis = this;
+                yield new Promise((resolve, reject) => __awaiter(this, void 0, void 0, function* () {
+                    let completedIterations = 0;
+                    let timeout = benchmarkThis.timeout
+                        ? setTimeout(() => {
+                            running = false;
+                            if ((benchmarkThis === null || benchmarkThis === void 0 ? void 0 : benchmarkThis.iterations) &&
+                                completedIterations < benchmarkThis.iterations) {
+                                reject('Timeout');
+                            }
+                            resolve();
+                        }, benchmarkThis.timeout)
+                        : null;
+                    let running = true;
+                    while (running) {
+                        const a = performance.now();
+                        if (variation.action) {
+                            yield variation.action(variation);
+                        }
+                        else if (this.action) {
+                            yield this.action(variation);
+                        }
+                        const b = performance.now();
+                        const duration = b - a;
+                        completedIterations++;
+                        totalCompletedIterations++;
+                        timings.push(duration);
+                        if (this.reporter.progress &&
+                            totalIterations &&
+                            benchmarkThis.iterations) {
+                            this.reporter.progress(variation.name, totalCompletedIterations / totalIterations, {
+                                timeElapsed: performance.now() - startTime,
+                                totalIterations,
+                                completedIterations: totalCompletedIterations,
+                                timeout: benchmarkThis.timeout,
+                            });
+                        }
+                        if ((benchmarkThis === null || benchmarkThis === void 0 ? void 0 : benchmarkThis.iterations) &&
+                            completedIterations >= benchmarkThis.iterations) {
+                            running = false;
+                            if (timeout) {
+                                clearTimeout(timeout);
+                            }
+                            resolve();
+                        }
+                    }
+                }));
+                if (this.reporter.progress && !totalIterations) {
+                    this.reporter.progress(variation.name, variationIndex / this.variations.length, {
+                        timeElapsed: performance.now() - startTime,
+                        timeout: this.timeout,
+                        completedIterations: totalCompletedIterations,
+                    });
+                }
+                // TEARDOWN
+                for (const teardown of variation.teardownMethods) {
+                    yield teardown(variation);
+                }
+                for (const teardown of this.teardownMethods) {
+                    yield teardown(variation);
+                }
+                process.env = oldEnv;
+                // REPORT
+                const min = Math.min(...timings);
+                const max = Math.max(...timings);
+                const sum = timings.reduce((a, b) => a + b, 0);
+                const average = sum / timings.length;
+                const sortedTimings = [...timings].sort((a, b) => a - b);
+                const p95 = sortedTimings[Math.floor(sortedTimings.length * 0.95)];
+                results.push({
+                    label: variation.name,
+                    min,
+                    max,
+                    average,
+                    p95,
+                });
+            }
+            this.reporter.report(this, results);
+        });
+    }
+    validate() {
+        if (!this.action) {
+            const missingActions = this.variations.filter((v) => !v.action);
+            if (missingActions.length > 0) {
+                throw new Error(`Missing action for variations: ${missingActions
+                    .map((v) => v.name)
+                    .join(', ')}`);
+            }
+            else {
+                throw new Error(`Benchmark ${this.name} is missing an action`);
+            }
+        }
+    }
+}
+exports.Benchmark = Benchmark;

package/dist/console-reporter.d.ts

@@ -0,0 +1,8 @@
+import { Result, Reporter, ProgressContext } from './api-types';
+import { Benchmark } from './benchmark';
+export declare class ConsoleReporter implements Reporter {
+    private bar;
+    constructor();
+    progress(name: string, percent: number, context: ProgressContext): void;
+    report(benchmark: Benchmark, results: Result[]): void;
+}

package/dist/console-reporter.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConsoleReporter = void 0;
+const cli_progress_1 = require("cli-progress");
+class ConsoleReporter {
+    constructor() {
+        this.bar = new cli_progress_1.SingleBar({
+            format: 'Running: {label}\n{bar} {percentage}% | {value}/{total} - ETA: {eta}s',
+            barCompleteChar: '\u2588',
+            barIncompleteChar: '\u2591',
+            hideCursor: true,
+        });
+    }
+    progress(name, percent, context) {
+        var _a;
+        if (!this.bar.isActive) {
+            this.bar.start((_a = context.totalIterations) !== null && _a !== void 0 ? _a : 100, 0);
+        }
+        this.bar.update(context.completedIterations, { label: name });
+        process.stdout.moveCursor(0, -1);
+        // console.log(`Progress: ${name} ${Math.round(percent * 10000) / 100}%`);
+    }
+    report(benchmark, results) {
+        this.bar.stop();
+        process.stdout.moveCursor(0, -1);
+        process.stdout.clearScreenDown();
+        console.log(`Benchmark: ${benchmark.name}`);
+        console.table(results);
+    }
+}
+exports.ConsoleReporter = ConsoleReporter;

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from './api-types';
+export * from './benchmark';
+export * from './variation';
+export * from './console-reporter';

package/dist/index.js

@@ -0,0 +1,20 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./api-types"), exports);
+__exportStar(require("./benchmark"), exports);
+__exportStar(require("./variation"), exports);
+__exportStar(require("./console-reporter"), exports);

package/dist/variation.d.ts

@@ -0,0 +1,15 @@
+import { SetupMethod, TeardownMethod, ActionMethod, EnvironmentVariableOptions } from './api-types';
+export declare class Variation {
+    name: string;
+    setupMethods: SetupMethod[];
+    teardownMethods: TeardownMethod[];
+    environment: Partial<NodeJS.ProcessEnv>;
+    action?: ActionMethod;
+    constructor(name: string);
+    static FromEnvironmentVariables(variables: EnvironmentVariableOptions): Variation[];
+    withSetup(setup: SetupMethod): this;
+    withTeardown(teardown: TeardownMethod): this;
+    withEnvironmentVariables(env: Partial<NodeJS.ProcessEnv>): this;
+    withEnvironmentVariable(name: string, value: string): this;
+    withAction(action: ActionMethod): this;
+}

package/dist/variation.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Variation = void 0;
+class Variation {
+    constructor(name) {
+        this.name = name;
+        this.setupMethods = [];
+        this.teardownMethods = [];
+        this.environment = {};
+    }
+    static FromEnvironmentVariables(variables) {
+        const combinations = variables.reduce((acc, [name, values]) => {
+            return acc.flatMap((accItem) => {
+                return values.map((value) => {
+                    return [...accItem, [name, value]];
+                });
+            });
+        }, [[]]);
+        return combinations.map((combination) => {
+            const label = JSON.stringify(combination);
+            return new Variation(label).withEnvironmentVariables(Object.fromEntries(combination));
+        });
+    }
+    withSetup(setup) {
+        this.setupMethods.push(setup);
+        return this;
+    }
+    withTeardown(teardown) {
+        this.teardownMethods.push(teardown);
+        return this;
+    }
+    withEnvironmentVariables(env) {
+        this.environment = Object.assign(Object.assign({}, this.environment), env);
+        return this;
+    }
+    withEnvironmentVariable(name, value) {
+        this.environment[name] = value;
+        return this;
+    }
+    withAction(action) {
+        this.action = action;
+        return this;
+    }
+}
+exports.Variation = Variation;

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "flexi-bench",
+  "version": "0.0.0-alpha.1",
+  "description": "",
+  "main": "dist/index.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "build": "tsc -p tsconfig.json",
+    "format": "prettier --write src"
+  },
+  "author": "",
+  "license": "ISC",
+  "devDependencies": {
+    "@nx/js": "^19.4.2",
+    "@swc-node/register": "~1.9.1",
+    "@swc/core": "~1.5.7",
+    "@swc/helpers": "~0.5.11",
+    "nx": "19.4.2"
+  },
+  "nx": {},
+  "dependencies": {
+    "@types/cli-progress": "^3.11.6",
+    "@types/node": "^20.14.10",
+    "cli-progress": "^3.12.0",
+    "prettier": "^3.3.2",
+    "typescript": "^5.5.3"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "package.json"
+  ]
+}