@ac-bench/measure-duration 0.1.0

package/dist/spawn-overhead.d.ts

@@ -0,0 +1,59 @@
+import { DurationStatistics } from "./_types.js";
+export interface SpawnOverheadOptions {
+    /** Unmeasured invocations run first. Defaults to 3. */
+    warmup?: number;
+    /** Measured invocations. Defaults to 20. */
+    runs?: number;
+}
+/**
+ * The do-nothing equivalent of a command being benchmarked.
+ *
+ * To subtract spawn cost honestly, this must start the same binary and do the
+ * same unavoidable setup as the real command, minus the work under test. For
+ * `python3 -c "<protocol code>"` the right baseline is `python3 -c "import
+ * smtplib"`, not `python3 --version`: interpreter startup is only part of the
+ * cost, module import is the rest.
+ */
+export interface SpawnBaseline {
+    /** Label used in reports, and matched against a case's `tags.language`. */
+    name: string;
+    /** Executable to run. Resolved on `PATH`; never passed through a shell. */
+    command: string;
+    /** Arguments producing the cheapest meaningful invocation. */
+    args?: readonly string[];
+}
+/**
+ * Measure how long it takes to start and stop a command that does nothing.
+ *
+ * A benchmark that spawns a process per iteration includes this cost in every
+ * sample, while an in-process contender pays none of it. Measuring it makes the
+ * bias visible and lets reports show an adjusted figure.
+ *
+ * @param command Executable to run. Resolved on `PATH`; never passed through a
+ *   shell.
+ * @param args Arguments producing the cheapest meaningful invocation.
+ * @param options Sampling policy.
+ * @returns Statistics over the measured invocations.
+ * @throws {Error} If the command cannot be executed at all.
+ */
+export declare function measureSpawnOverhead(command: string, args: readonly string[], options?: SpawnOverheadOptions): Promise<DurationStatistics>;
+/**
+ * Floor cost of spawning any process from this runtime.
+ *
+ * Useful as a sanity check: a per-binary overhead below this value means the
+ * measurement is noise.
+ *
+ * @param options Sampling policy.
+ * @returns Statistics for the cheapest process the platform can start.
+ */
+export declare function measureBaselineSpawn(options?: SpawnOverheadOptions): Promise<DurationStatistics>;
+/**
+ * Measure spawn overhead for several commands.
+ *
+ * @param baselines One entry per binary used by the condition.
+ * @param options Sampling policy applied to each.
+ * @returns Overheads keyed by {@link SpawnBaseline.name}. A command that cannot
+ *   be executed is omitted rather than failing the calibration.
+ */
+export declare function calibrateSpawnOverhead(baselines: readonly SpawnBaseline[], options?: SpawnOverheadOptions): Promise<Map<string, DurationStatistics>>;
+//# sourceMappingURL=spawn-overhead.d.ts.map

package/dist/spawn-overhead.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spawn-overhead.d.ts","sourceRoot":"","sources":["../src/spawn-overhead.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEjD,MAAM,WAAW,oBAAoB;IACpC,uDAAuD;IACvD,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB,4CAA4C;IAC5C,IAAI,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,aAAa;IAC7B,2EAA2E;IAC3E,IAAI,EAAE,MAAM,CAAC;IAEb,2EAA2E;IAC3E,OAAO,EAAE,MAAM,CAAC;IAEhB,8DAA8D;IAC9D,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACzB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,oBAAoB,CACzC,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,OAAO,CAAC,EAAE,oBAAoB,GAC5B,OAAO,CAAC,kBAAkB,CAAC,CAiB7B;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CACnC,OAAO,GAAE,oBAAyB,GAChC,OAAO,CAAC,kBAAkB,CAAC,CAI7B;AAED;;;;;;;GAOG;AACH,wBAAsB,sBAAsB,CAC3C,SAAS,EAAE,SAAS,aAAa,EAAE,EACnC,OAAO,CAAC,EAAE,oBAAoB,GAC5B,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC,CAiB1C"}

package/dist/spawn-overhead.js

@@ -0,0 +1,80 @@
+import { isNodeErrorWithCode, spawnProcess } from "@ac-kit/node";
+import { summarise } from "./_statistics.js";
+/**
+ * Measure how long it takes to start and stop a command that does nothing.
+ *
+ * A benchmark that spawns a process per iteration includes this cost in every
+ * sample, while an in-process contender pays none of it. Measuring it makes the
+ * bias visible and lets reports show an adjusted figure.
+ *
+ * @param command Executable to run. Resolved on `PATH`; never passed through a
+ *   shell.
+ * @param args Arguments producing the cheapest meaningful invocation.
+ * @param options Sampling policy.
+ * @returns Statistics over the measured invocations.
+ * @throws {Error} If the command cannot be executed at all.
+ */
+export async function measureSpawnOverhead(command, args, options) {
+    const warmup = options?.warmup ?? 3;
+    const runs = options?.runs ?? 20;
+    for (let iteration = 0; iteration < warmup; iteration++) {
+        await invoke_(command, args);
+    }
+    const samples = [];
+    for (let iteration = 0; iteration < runs; iteration++) {
+        const began = performance.now();
+        await invoke_(command, args);
+        samples.push(performance.now() - began);
+    }
+    return summarise(samples);
+}
+/**
+ * Floor cost of spawning any process from this runtime.
+ *
+ * Useful as a sanity check: a per-binary overhead below this value means the
+ * measurement is noise.
+ *
+ * @param options Sampling policy.
+ * @returns Statistics for the cheapest process the platform can start.
+ */
+export function measureBaselineSpawn(options = {}) {
+    return process.platform === "win32"
+        ? measureSpawnOverhead("cmd", ["/c", "exit"], options)
+        : measureSpawnOverhead("true", [], options);
+}
+/**
+ * Measure spawn overhead for several commands.
+ *
+ * @param baselines One entry per binary used by the condition.
+ * @param options Sampling policy applied to each.
+ * @returns Overheads keyed by {@link SpawnBaseline.name}. A command that cannot
+ *   be executed is omitted rather than failing the calibration.
+ */
+export async function calibrateSpawnOverhead(baselines, options) {
+    const overheads = new Map();
+    for (const baseline of baselines) {
+        try {
+            overheads.set(baseline.name, await measureSpawnOverhead(baseline.command, baseline.args ?? [], options));
+        }
+        catch {
+            // An unavailable binary is reported by its own benchmark case.
+        }
+    }
+    return overheads;
+}
+/**
+ * Runs `command`, tolerating a nonzero exit — the process still started and
+ * stopped, which is what spawn-overhead measurement cares about.
+ */
+async function invoke_(command, args) {
+    try {
+        await spawnProcess(command, args);
+    }
+    catch (error) {
+        if (isNodeErrorWithCode(error, "ENOENT")) {
+            throw new Error(`Command not found: ${command}`);
+        }
+        // A non-zero exit is acceptable; the process still started and stopped.
+    }
+}
+//# sourceMappingURL=spawn-overhead.js.map

package/dist/spawn-overhead.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spawn-overhead.js","sourceRoot":"","sources":["../src/spawn-overhead.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAEjE,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AA+B7C;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACzC,OAAe,EACf,IAAuB,EACvB,OAA8B;IAE9B,MAAM,MAAM,GAAG,OAAO,EAAE,MAAM,IAAI,CAAC,CAAC;IACpC,MAAM,IAAI,GAAG,OAAO,EAAE,IAAI,IAAI,EAAE,CAAC;IAEjC,KAAK,IAAI,SAAS,GAAG,CAAC,EAAE,SAAS,GAAG,MAAM,EAAE,SAAS,EAAE,EAAE,CAAC;QACzD,MAAM,OAAO,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;IAC9B,CAAC;IAED,MAAM,OAAO,GAAa,EAAE,CAAC;IAE7B,KAAK,IAAI,SAAS,GAAG,CAAC,EAAE,SAAS,GAAG,IAAI,EAAE,SAAS,EAAE,EAAE,CAAC;QACvD,MAAM,KAAK,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC;QAChC,MAAM,OAAO,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;QAC7B,OAAO,CAAC,IAAI,CAAC,WAAW,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,CAAC;IACzC,CAAC;IAED,OAAO,SAAS,CAAC,OAAO,CAAC,CAAC;AAC3B,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,oBAAoB,CACnC,OAAO,GAAyB,EAAE;IAElC,OAAO,OAAO,CAAC,QAAQ,KAAK,OAAO;QAClC,CAAC,CAAC,oBAAoB,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,EAAE,OAAO,CAAC;QACtD,CAAC,CAAC,oBAAoB,CAAC,MAAM,EAAE,EAAE,EAAE,OAAO,CAAC,CAAC;AAC9C,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAC3C,SAAmC,EACnC,OAA8B;IAE9B,MAAM,SAAS,GAAG,IAAI,GAAG,EAA8B,CAAC;IACxD,KAAK,MAAM,QAAQ,IAAI,SAAS,EAAE,CAAC;QAClC,IAAI,CAAC;YACJ,SAAS,CAAC,GAAG,CACZ,QAAQ,CAAC,IAAI,EACb,MAAM,oBAAoB,CACzB,QAAQ,CAAC,OAAO,EAChB,QAAQ,CAAC,IAAI,IAAI,EAAE,EACnB,OAAO,CACP,CACD,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;YACR,+DAA+D;QAChE,CAAC;IACF,CAAC;IACD,OAAO,SAAS,CAAC;AAClB,CAAC;AAED;;;GAGG;AACH,KAAK,UAAU,OAAO,CACrB,OAAe,EACf,IAAuB;IAEvB,IAAI,CAAC;QACJ,MAAM,YAAY,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;IACnC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QAChB,IAAI,mBAAmB,CAAC,KAAK,EAAE,QAAQ,CAAC,EAAE,CAAC;YAC1C,MAAM,IAAI,KAAK,CAAC,sBAAsB,OAAO,EAAE,CAAC,CAAC;QAClD,CAAC;QACD,wEAAwE;IACzE,CAAC;AACF,CAAC"}

package/package.json

@@ -0,0 +1,77 @@
+{
+  "name": "@ac-bench/measure-duration",
+  "version": "0.1.0",
+  "description": "Duration measure for @ac-bench: adaptive sampling, duration statistics and quality warnings for outliers, high variance and overhead dominance.",
+  "keywords": [
+    "benchmark",
+    "duration",
+    "sampling",
+    "statistics"
+  ],
+  "homepage": "https://github.com/anthochamp/node-essentials/tree/main/bench/measure-duration#readme",
+  "bugs": {
+    "url": "https://github.com/anthochamp/node-essentials/issues"
+  },
+  "license": "BSD-3-Clause",
+  "author": "Anthony Champagne <dev@anthonychampagne.fr>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/anthochamp/node-essentials.git",
+    "directory": "bench/measure-duration"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "exports": {
+    ".": "./dist/index.js",
+    "./plugin": "./dist/plugin.js",
+    "./iteration-child": "./dist/iteration-child.js"
+  },
+  "publishConfig": {
+    "main": "./dist/index.js",
+    "exports": {
+      ".": "./dist/index.js",
+      "./plugin": "./dist/plugin.js",
+      "./iteration-child": "./dist/iteration-child.js"
+    },
+    "access": "public"
+  },
+  "scripts": {
+    "compile": "tsc -p ./tsconfig.build.json --outDir dist",
+    "compile:check": "tsc -noEmit -p ./tsconfig.json",
+    "clean": "rimraf dist",
+    "build": "yarn clean && yarn compile",
+    "test": "yarn run -T vitest run",
+    "prepack": "yarn build"
+  },
+  "dependencies": {
+    "@ac-bench/core": "^0.1.0",
+    "@ac-bench/util": "^0.1.0",
+    "@ac-kit/app-report": "^0.1.0",
+    "@ac-kit/app-system": "^0.1.0",
+    "@ac-kit/core": "^0.1.0",
+    "@ac-kit/math-stats": "^0.1.0",
+    "@ac-kit/model-dataset": "^0.1.0",
+    "@ac-kit/node": "^0.1.0",
+    "@types/node": "^26.5.1",
+    "zod": "^4.5.4"
+  },
+  "devDependencies": {
+    "@ac-kit/tsconfig": "0.1.0",
+    "@ac-kit/typedoc-config": "0.1.0",
+    "@ac-kit/vitest-config": "0.1.0",
+    "@typescript/native": "typescript@7.0.2",
+    "rimraf": "6.1.3",
+    "tsx": "4.23.12",
+    "typedoc": "0.28.20",
+    "typescript": "@typescript/typescript6@6.0.2",
+    "vite": "8.3.0",
+    "vitest": "5.0.0"
+  },
+  "engines": {
+    "node": ">=24"
+  }
+}