@ac-bench/measure-resource 0.1.0

package/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2024-2026 Anthony Champagne and contributors
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -0,0 +1,25 @@
+# @ac-bench/measure-resource
+
+What an operation costs in bytes and CPU time, rather than in wall time.
+
+Wall time alone cannot tell you why something is fast. An implementation that
+wins by allocating freely looks identical to one that wins by doing less work —
+until the garbage collector runs under load. This reports CPU time, peak heap,
+bytes allocated, and garbage-collection count and pause time, so the two are
+distinguishable.
+
+```ts
+import { resourceCase, resourceCondition } from "@ac-bench/measure-resource";
+
+resourceCondition("parse 10k records", () => {
+  resourceCase("streaming", () => parseStreaming(input));
+  resourceCase("buffer whole document", () => parseBuffered(input));
+});
+```
+
+Results are reported in their own units alongside a duration measure, never
+converted into one.
+
+Host-bound: it reads Node's resource-usage and GC instrumentation.
+
+Run suites with the `measure` CLI from `@ac-bench/cli`.

package/dist/_counters.d.ts

@@ -0,0 +1,71 @@
+/** One reading of the counters every resource figure is derived from. */
+export type ResourceCounters = {
+    cpuUserUs: number;
+    cpuSystemUs: number;
+    heapUsedBytes: number;
+    externalBytes: number;
+    arrayBuffersBytes: number;
+    rssBytes: number;
+};
+/**
+ * Read twice per batch, so it allocates as little as the platform allows:
+ * `v8.getHeapStatistics()` is deliberately not called here — it builds the
+ * largest result of the three, and the only field wanted from it is a constant.
+ * See {@link readHeapLimitBytes}.
+ */
+export declare function readResourceCounters(): ResourceCounters;
+/** The heap ceiling this process was given, fixed for its lifetime. */
+export declare function readHeapLimitBytes(): number;
+/**
+ * Bytes a batch asked the allocator for, as the growth in everything the heap
+ * accounts for.
+ *
+ * Negative when a collection ran mid-batch and freed more than was allocated,
+ * which is why {@link forceCollection} is called before a batch rather than
+ * during it. Clamped at zero: a batch cannot allocate a negative amount, and
+ * reporting one would make a mean meaningless.
+ */
+export declare function allocatedBytes(before: ResourceCounters, after: ResourceCounters): number;
+export declare function cpuTimeMs(before: ResourceCounters, after: ResourceCounters): number;
+/** Whether the run was started with `--expose-gc`. */
+export declare function hasExposedCollector(): boolean;
+/**
+ * Collects, so a batch starts from a known floor and its growth is what it
+ * allocated rather than what the collector happened not to have reclaimed yet.
+ *
+ * A no-op without `--expose-gc`; callers warn rather than fail, since the
+ * numbers are still comparable between cases in the same run.
+ */
+export declare function forceCollection(): void;
+export type GcTotals = {
+    count: number;
+    pauseMs: number;
+};
+/**
+ * Whether this runtime actually delivers `"gc"` performance entries.
+ *
+ * `PerformanceObserver.supportedEntryTypes` lists `"gc"` on builds that never
+ * emit one — Node 26.8 does, and reports nothing even for a forced collection.
+ * Reporting the resulting zero as "no collections ran" would be a lie, so the
+ * capability is probed rather than assumed.
+ */
+export declare function canObserveGc(): boolean;
+/**
+ * Running totals of the collections observed since construction, or `null`
+ * where {@link canObserveGc} says the runtime cannot report them.
+ *
+ * A class because it owns a subscription that outlives any one reading: the
+ * observer must stay attached across every batch, and callers difference two
+ * readings rather than restarting it.
+ */
+export declare class GcRecorder {
+    private readonly observer;
+    private count_;
+    private pauseMs_;
+    constructor(observable: boolean);
+    read(): GcTotals | null;
+    [Symbol.dispose](): void;
+    private absorb_;
+}
+export declare function gcSince(before: GcTotals | null, after: GcTotals | null): GcTotals | null;
+//# sourceMappingURL=_counters.d.ts.map

package/dist/_counters.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"_counters.d.ts","sourceRoot":"","sources":["../src/_counters.ts"],"names":[],"mappings":"AAGA,yEAAyE;AACzE,MAAM,MAAM,gBAAgB,GAAG;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;IACtB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,QAAQ,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,oBAAoB,IAAI,gBAAgB,CAYvD;AAED,uEAAuE;AACvE,wBAAgB,kBAAkB,IAAI,MAAM,CAE3C;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAC7B,MAAM,EAAE,gBAAgB,EACxB,KAAK,EAAE,gBAAgB,GACrB,MAAM,CAQR;AAED,wBAAgB,SAAS,CACxB,MAAM,EAAE,gBAAgB,EACxB,KAAK,EAAE,gBAAgB,GACrB,MAAM,CAOR;AAED,sDAAsD;AACtD,wBAAgB,mBAAmB,IAAI,OAAO,CAE7C;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,IAAI,IAAI,CAEtC;AAED,MAAM,MAAM,QAAQ,GAAG;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF;;;;;;;GAOG;AACH,wBAAgB,YAAY,IAAI,OAAO,CActC;AAED;;;;;;;GAOG;AACH,qBAAa,UAAU;IACtB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA6B;IACtD,OAAO,CAAC,MAAM,CAAK;IACnB,OAAO,CAAC,QAAQ,CAAK;IAErB,YAAY,UAAU,EAAE,OAAO,EAU9B;IAED,IAAI,IAAI,QAAQ,GAAG,IAAI,CAWtB;IAED,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI,CAEvB;IAED,OAAO,CAAC,OAAO;CAMf;AAED,wBAAgB,OAAO,CACtB,MAAM,EAAE,QAAQ,GAAG,IAAI,EACvB,KAAK,EAAE,QAAQ,GAAG,IAAI,GACpB,QAAQ,GAAG,IAAI,CASjB"}

package/dist/_counters.js

@@ -0,0 +1,134 @@
+import { PerformanceObserver } from "node:perf_hooks";
+import v8 from "node:v8";
+/**
+ * Read twice per batch, so it allocates as little as the platform allows:
+ * `v8.getHeapStatistics()` is deliberately not called here — it builds the
+ * largest result of the three, and the only field wanted from it is a constant.
+ * See {@link readHeapLimitBytes}.
+ */
+export function readResourceCounters() {
+    const cpu = process.cpuUsage();
+    const memory = process.memoryUsage();
+    return {
+        cpuUserUs: cpu.user,
+        cpuSystemUs: cpu.system,
+        heapUsedBytes: memory.heapUsed,
+        externalBytes: memory.external,
+        arrayBuffersBytes: memory.arrayBuffers,
+        rssBytes: memory.rss,
+    };
+}
+/** The heap ceiling this process was given, fixed for its lifetime. */
+export function readHeapLimitBytes() {
+    return v8.getHeapStatistics().heap_size_limit;
+}
+/**
+ * Bytes a batch asked the allocator for, as the growth in everything the heap
+ * accounts for.
+ *
+ * Negative when a collection ran mid-batch and freed more than was allocated,
+ * which is why {@link forceCollection} is called before a batch rather than
+ * during it. Clamped at zero: a batch cannot allocate a negative amount, and
+ * reporting one would make a mean meaningless.
+ */
+export function allocatedBytes(before, after) {
+    const growth = after.heapUsedBytes -
+        before.heapUsedBytes +
+        (after.externalBytes - before.externalBytes) +
+        (after.arrayBuffersBytes - before.arrayBuffersBytes);
+    return Math.max(0, growth);
+}
+export function cpuTimeMs(before, after) {
+    return ((after.cpuUserUs -
+        before.cpuUserUs +
+        (after.cpuSystemUs - before.cpuSystemUs)) /
+        1000);
+}
+/** Whether the run was started with `--expose-gc`. */
+export function hasExposedCollector() {
+    return typeof globalThis.gc === "function";
+}
+/**
+ * Collects, so a batch starts from a known floor and its growth is what it
+ * allocated rather than what the collector happened not to have reclaimed yet.
+ *
+ * A no-op without `--expose-gc`; callers warn rather than fail, since the
+ * numbers are still comparable between cases in the same run.
+ */
+export function forceCollection() {
+    globalThis.gc?.();
+}
+/**
+ * Whether this runtime actually delivers `"gc"` performance entries.
+ *
+ * `PerformanceObserver.supportedEntryTypes` lists `"gc"` on builds that never
+ * emit one — Node 26.8 does, and reports nothing even for a forced collection.
+ * Reporting the resulting zero as "no collections ran" would be a lie, so the
+ * capability is probed rather than assumed.
+ */
+export function canObserveGc() {
+    if (!PerformanceObserver.supportedEntryTypes.includes("gc")) {
+        return false;
+    }
+    const probe = new PerformanceObserver(() => { });
+    try {
+        probe.observe({ entryTypes: ["gc"] });
+        forceCollection();
+        return probe.takeRecords().length > 0;
+    }
+    finally {
+        probe.disconnect();
+    }
+}
+/**
+ * Running totals of the collections observed since construction, or `null`
+ * where {@link canObserveGc} says the runtime cannot report them.
+ *
+ * A class because it owns a subscription that outlives any one reading: the
+ * observer must stay attached across every batch, and callers difference two
+ * readings rather than restarting it.
+ */
+export class GcRecorder {
+    observer;
+    count_ = 0;
+    pauseMs_ = 0;
+    constructor(observable) {
+        if (!observable) {
+            this.observer = null;
+            return;
+        }
+        this.observer = new PerformanceObserver((list) => {
+            this.absorb_(list.getEntries());
+        });
+        this.observer.observe({ entryTypes: ["gc"] });
+    }
+    read() {
+        if (!this.observer) {
+            return null;
+        }
+        // The observer's callback runs on the microtask queue, and a synchronous
+        // case never yields to it — so without draining here, a batch that
+        // collected repeatedly would report no collections at all.
+        this.absorb_(this.observer.takeRecords());
+        return { count: this.count_, pauseMs: this.pauseMs_ };
+    }
+    [Symbol.dispose]() {
+        this.observer?.disconnect();
+    }
+    absorb_(entries) {
+        for (let index = 0; index < entries.length; index++) {
+            this.count_++;
+            this.pauseMs_ += entries[index].duration;
+        }
+    }
+}
+export function gcSince(before, after) {
+    if (before === null || after === null) {
+        return null;
+    }
+    return {
+        count: after.count - before.count,
+        pauseMs: after.pauseMs - before.pauseMs,
+    };
+}
+//# sourceMappingURL=_counters.js.map

package/dist/_counters.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"_counters.js","sourceRoot":"","sources":["../src/_counters.ts"],"names":[],"mappings":"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"}

package/dist/_run-case.d.ts

@@ -0,0 +1,9 @@
+import { BenchCaseRunContext } from "@ac-bench/core/runner";
+import { MaybeAsyncCallable } from "@ac-kit/core";
+import { ResourceCaseOptions, ResourceConditionOptions } from "./options.js";
+export type ResourceCaseFn = MaybeAsyncCallable<[signal: AbortSignal]>;
+export type RunResourceCaseOptions = ResourceCaseOptions & {
+    conditionOptions?: ResourceConditionOptions;
+};
+export declare function runResourceCase(title: string, fn: ResourceCaseFn, context: BenchCaseRunContext, options?: RunResourceCaseOptions): Promise<void>;
+//# sourceMappingURL=_run-case.d.ts.map

package/dist/_run-case.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"_run-case.d.ts","sourceRoot":"","sources":["../src/_run-case.ts"],"names":[],"mappings":"AAAA,OAAO,EAEN,mBAAmB,EAKnB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAIN,kBAAkB,EAClB,MAAM,cAAc,CAAC;AAgBtB,OAAO,EAEN,mBAAmB,EACnB,wBAAwB,EAExB,MAAM,cAAc,CAAC;AAEtB,MAAM,MAAM,cAAc,GAAG,kBAAkB,CAAC,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC;AAEvE,MAAM,MAAM,sBAAsB,GAAG,mBAAmB,GAAG;IAC1D,gBAAgB,CAAC,EAAE,wBAAwB,CAAC;CAC5C,CAAC;AA0DF,wBAAsB,eAAe,CACpC,KAAK,EAAE,MAAM,EACb,EAAE,EAAE,cAAc,EAClB,OAAO,EAAE,mBAAmB,EAC5B,OAAO,CAAC,EAAE,sBAAsB,GAC9B,OAAO,CAAC,IAAI,CAAC,CA6Gf"}

package/dist/_run-case.js

@@ -0,0 +1,189 @@
+var __addDisposableResource = (this && this.__addDisposableResource) || function (env, value, async) {
+    if (value !== null && value !== void 0) {
+        if (typeof value !== "object" && typeof value !== "function") throw new TypeError("Object expected.");
+        var dispose, inner;
+        if (async) {
+            if (!Symbol.asyncDispose) throw new TypeError("Symbol.asyncDispose is not defined.");
+            dispose = value[Symbol.asyncDispose];
+        }
+        if (dispose === void 0) {
+            if (!Symbol.dispose) throw new TypeError("Symbol.dispose is not defined.");
+            dispose = value[Symbol.dispose];
+            if (async) inner = dispose;
+        }
+        if (typeof dispose !== "function") throw new TypeError("Object not disposable.");
+        if (inner) dispose = function() { try { inner.call(this); } catch (e) { return Promise.reject(e); } };
+        env.stack.push({ value: value, dispose: dispose, async: async });
+    }
+    else if (async) {
+        env.stack.push({ async: true });
+    }
+    return value;
+};
+var __disposeResources = (this && this.__disposeResources) || (function (SuppressedError) {
+    return function (env) {
+        function fail(e) {
+            env.error = env.hasError ? new SuppressedError(e, env.error, "An error was suppressed during disposal.") : e;
+            env.hasError = true;
+        }
+        var r, s = 0;
+        function next() {
+            while (r = env.stack.pop()) {
+                try {
+                    if (!r.async && s === 1) return s = 0, env.stack.push(r), Promise.resolve().then(next);
+                    if (r.dispose) {
+                        var result = r.dispose.call(r.value);
+                        if (r.async) return s |= 2, Promise.resolve(result).then(next, function(e) { fail(e); return next(); });
+                    }
+                    else s |= 1;
+                }
+                catch (e) {
+                    fail(e);
+                }
+            }
+            if (s === 1) return env.hasError ? Promise.reject(env.error) : Promise.resolve();
+            if (env.hasError) throw env.error;
+        }
+        return next();
+    };
+})(typeof SuppressedError === "function" ? SuppressedError : function (error, suppressed, message) {
+    var e = new Error(message);
+    return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
+});
+import { allOfPolicies, createProjectedPolicy, createRelativeErrorPolicy, createStabilityPolicy, Sampler, } from "@ac-bench/core/runner";
+import { defaults, formatError, isThenable, } from "@ac-kit/core";
+import { allocatedBytes, canObserveGc, cpuTimeMs, forceCollection, GcRecorder, gcSince, hasExposedCollector, readHeapLimitBytes, readResourceCounters, } from "./_counters.js";
+import { composeResourceBenchStatistics } from "./_statistics.js";
+import { detectResourceBenchWarnings } from "./_warnings.js";
+import { RESOURCE_SAMPLING_DEFAULTS, } from "./options.js";
+/**
+ * Runs one batch and returns what it cost, per operation.
+ *
+ * Nothing inside the timed loop may allocate, or the measure reports its own
+ * bookkeeping as the case's: `process.memoryUsage()` builds a result object per
+ * call, so the peak is tracked through `memoryUsage.rss()`, which returns a
+ * number, and the heap counters are read at the boundaries only.
+ *
+ * The collection before the batch is deliberately outside the measured window:
+ * it establishes the floor the growth is measured from, and its own cost is not
+ * part of what the case allocated.
+ */
+async function measureBatch_(fn, iterations, gc, signal) {
+    forceCollection();
+    const before = readResourceCounters();
+    const gcBefore = gc.read();
+    let rssPeakBytes = before.rssBytes;
+    for (let index = 0; index < iterations; index++) {
+        signal.throwIfAborted();
+        // Awaiting unconditionally would allocate promise machinery per iteration
+        // for a synchronous case, which is allocation this measure would then
+        // attribute to the case.
+        const returned = fn(signal);
+        if (isThenable(returned)) {
+            await returned;
+        }
+        const rss = process.memoryUsage.rss();
+        if (rss > rssPeakBytes) {
+            rssPeakBytes = rss;
+        }
+    }
+    const after = readResourceCounters();
+    const gcDelta = gcSince(gcBefore, gc.read());
+    return {
+        operations: iterations,
+        cpuTimeMs: cpuTimeMs(before, after) / iterations,
+        allocatedBytes: allocatedBytes(before, after) / iterations,
+        heapPeakBytes: Math.max(before.heapUsedBytes, after.heapUsedBytes),
+        rssBytes: rssPeakBytes,
+        gcCount: gcDelta === null ? null : gcDelta.count / iterations,
+        gcPauseMs: gcDelta === null ? null : gcDelta.pauseMs / iterations,
+    };
+}
+export async function runResourceCase(title, fn, context, options) {
+    const { signal } = context;
+    signal.throwIfAborted();
+    const sampling = defaults(options?.conditionOptions?.sampling ?? {}, RESOURCE_SAMPLING_DEFAULTS);
+    const tags = options?.tags ?? {};
+    const forcedCollection = hasExposedCollector();
+    const samples = [];
+    const heapLimitBytes = readHeapLimitBytes();
+    try {
+        const env_1 = { stack: [], error: void 0, hasError: false };
+        try {
+            await options?.setup?.(signal);
+            const gc = __addDisposableResource(env_1, new GcRecorder(canObserveGc()), false);
+            for (let iteration = 0; iteration < sampling.warmup; iteration++) {
+                signal.throwIfAborted();
+                await fn(signal);
+            }
+            const sampler = new Sampler(allOfPolicies([
+                createStabilityPolicy((sample) => [sample.allocatedBytes], {
+                    window: sampling.stableBatches,
+                    tolerance: sampling.allocationTolerance,
+                }),
+                createProjectedPolicy((sample) => sample.cpuTimeMs, createRelativeErrorPolicy({
+                    minRuns: sampling.minRuns,
+                    relativeError: sampling.relativeError,
+                    confidenceLevel: sampling.confidenceLevel,
+                    estimator: "median",
+                })),
+            ]), {
+                bounds: {
+                    minRuns: sampling.minRuns,
+                    maxRuns: sampling.maxRuns,
+                    minTimeMs: sampling.minTimeMs,
+                    maxTimeMs: sampling.maxTimeMs,
+                },
+                signal,
+                // One sample is one batch, and the sampler sizes the next batch in
+                // iterations — so this is the cost of one operation, not of the batch
+                // the sample came from.
+                costOf: (sample) => sample.cpuTimeMs,
+                targetBatchMs: sampling.targetBatchMs,
+            });
+            for (let size = sampler.nextBatch(); size !== null; size = sampler.nextBatch()) {
+                const startedAt = performance.now();
+                const sample = await measureBatch_(fn, size, gc, signal);
+                samples.push(sample);
+                sampler.observe([sample], performance.now() - startedAt);
+                context.progress(samples.length);
+            }
+        }
+        catch (e_1) {
+            env_1.error = e_1;
+            env_1.hasError = true;
+        }
+        finally {
+            __disposeResources(env_1);
+        }
+    }
+    catch (error) {
+        let failureMessage;
+        try {
+            await options?.teardown?.(signal);
+            failureMessage = formatError(error);
+        }
+        catch (tearDownError) {
+            failureMessage = formatError(new SuppressedError(tearDownError, error, "teardown failed after case failure"));
+        }
+        context.setCaseResult({
+            name: title,
+            tags,
+            statistics: null,
+            forcedCollection,
+            warnings: [],
+            failure: failureMessage,
+        });
+        return;
+    }
+    await options?.teardown?.(signal);
+    const statistics = composeResourceBenchStatistics(samples, heapLimitBytes);
+    context.setCaseResult({
+        name: title,
+        tags,
+        statistics,
+        forcedCollection,
+        warnings: detectResourceBenchWarnings(statistics, forcedCollection),
+    });
+}
+//# sourceMappingURL=_run-case.js.map

package/dist/_run-case.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"_run-case.js","sourceRoot":"","sources":["../src/_run-case.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,OAAO,EACN,aAAa,EAEb,qBAAqB,EACrB,yBAAyB,EACzB,qBAAqB,EACrB,OAAO,GACP,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACN,QAAQ,EACR,WAAW,EACX,UAAU,GAEV,MAAM,cAAc,CAAC;AAEtB,OAAO,EACN,cAAc,EACd,YAAY,EACZ,SAAS,EACT,eAAe,EACf,UAAU,EACV,OAAO,EACP,mBAAmB,EACnB,kBAAkB,EAClB,oBAAoB,GACpB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,8BAA8B,EAAE,MAAM,kBAAkB,CAAC;AAElE,OAAO,EAAE,2BAA2B,EAAE,MAAM,gBAAgB,CAAC;AAC7D,OAAO,EACN,0BAA0B,GAI1B,MAAM,cAAc,CAAC;AAQtB;;;;;;;;;;;GAWG;AACH,KAAK,UAAU,aAAa,CAC3B,EAAkB,EAClB,UAAkB,EAClB,EAAc,EACd,MAAmB;IAEnB,eAAe,EAAE,CAAC;IAElB,MAAM,MAAM,GAAG,oBAAoB,EAAE,CAAC;IACtC,MAAM,QAAQ,GAAG,EAAE,CAAC,IAAI,EAAE,CAAC;IAE3B,IAAI,YAAY,GAAG,MAAM,CAAC,QAAQ,CAAC;IAEnC,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,UAAU,EAAE,KAAK,EAAE,EAAE,CAAC;QACjD,MAAM,CAAC,cAAc,EAAE,CAAC;QAExB,0EAA0E;QAC1E,sEAAsE;QACtE,yBAAyB;QACzB,MAAM,QAAQ,GAAG,EAAE,CAAC,MAAM,CAAC,CAAC;QAC5B,IAAI,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC1B,MAAM,QAAQ,CAAC;QAChB,CAAC;QAED,MAAM,GAAG,GAAG,OAAO,CAAC,WAAW,CAAC,GAAG,EAAE,CAAC;QACtC,IAAI,GAAG,GAAG,YAAY,EAAE,CAAC;YACxB,YAAY,GAAG,GAAG,CAAC;QACpB,CAAC;IACF,CAAC;IAED,MAAM,KAAK,GAAG,oBAAoB,EAAE,CAAC;IACrC,MAAM,OAAO,GAAG,OAAO,CAAC,QAAQ,EAAE,EAAE,CAAC,IAAI,EAAE,CAAC,CAAC;IAE7C,OAAO;QACN,UAAU,EAAE,UAAU;QACtB,SAAS,EAAE,SAAS,CAAC,MAAM,EAAE,KAAK,CAAC,GAAG,UAAU;QAChD,cAAc,EAAE,cAAc,CAAC,MAAM,EAAE,KAAK,CAAC,GAAG,UAAU;QAC1D,aAAa,EAAE,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,aAAa,EAAE,KAAK,CAAC,aAAa,CAAC;QAClE,QAAQ,EAAE,YAAY;QACtB,OAAO,EAAE,OAAO,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,GAAG,UAAU;QAC7D,SAAS,EAAE,OAAO,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,GAAG,UAAU;KACjE,CAAC;AACH,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,eAAe,CACpC,KAAa,EACb,EAAkB,EAClB,OAA4B,EAC5B,OAAgC;IAEhC,MAAM,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC;IAC3B,MAAM,CAAC,cAAc,EAAE,CAAC;IAExB,MAAM,QAAQ,GAAG,QAAQ,CACxB,OAAO,EAAE,gBAAgB,EAAE,QAAQ,IAAI,EAAE,EACzC,0BAA0B,CAC1B,CAAC;IACF,MAAM,IAAI,GAAG,OAAO,EAAE,IAAI,IAAI,EAAE,CAAC;IACjC,MAAM,gBAAgB,GAAG,mBAAmB,EAAE,CAAC;IAE/C,MAAM,OAAO,GAA0B,EAAE,CAAC;IAC1C,MAAM,cAAc,GAAG,kBAAkB,EAAE,CAAC;IAE5C,IAAI,CAAC;;;YACJ,MAAM,OAAO,EAAE,KAAK,EAAE,CAAC,MAAM,CAAC,CAAC;YAE/B,MAAM,EAAE,kCAAG,IAAI,UAAU,CAAC,YAAY,EAAE,CAAC,QAAA,CAAC;YAE1C,KAAK,IAAI,SAAS,GAAG,CAAC,EAAE,SAAS,GAAG,QAAQ,CAAC,MAAM,EAAE,SAAS,EAAE,EAAE,CAAC;gBAClE,MAAM,CAAC,cAAc,EAAE,CAAC;gBACxB,MAAM,EAAE,CAAC,MAAM,CAAC,CAAC;YAClB,CAAC;YAED,MAAM,OAAO,GAAG,IAAI,OAAO,CAC1B,aAAa,CAAC;gBACb,qBAAqB,CACpB,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,cAAc,CAAC,EACnC;oBACC,MAAM,EAAE,QAAQ,CAAC,aAAa;oBAC9B,SAAS,EAAE,QAAQ,CAAC,mBAAmB;iBACvC,CACD;gBACD,qBAAqB,CACpB,CAAC,MAA2B,EAAE,EAAE,CAAC,MAAM,CAAC,SAAS,EACjD,yBAAyB,CAAC;oBACzB,OAAO,EAAE,QAAQ,CAAC,OAAO;oBACzB,aAAa,EAAE,QAAQ,CAAC,aAAa;oBACrC,eAAe,EAAE,QAAQ,CAAC,eAAe;oBACzC,SAAS,EAAE,QAAQ;iBACnB,CAAC,CACF;aACD,CAAC,EACF;gBACC,MAAM,EAAE;oBACP,OAAO,EAAE,QAAQ,CAAC,OAAO;oBACzB,OAAO,EAAE,QAAQ,CAAC,OAAO;oBACzB,SAAS,EAAE,QAAQ,CAAC,SAAS;oBAC7B,SAAS,EAAE,QAAQ,CAAC,SAAS;iBAC7B;gBACD,MAAM;gBACN,mEAAmE;gBACnE,sEAAsE;gBACtE,wBAAwB;gBACxB,MAAM,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,SAAS;gBACpC,aAAa,EAAE,QAAQ,CAAC,aAAa;aACrC,CACD,CAAC;YAEF,KACC,IAAI,IAAI,GAAG,OAAO,CAAC,SAAS,EAAE,EAC9B,IAAI,KAAK,IAAI,EACb,IAAI,GAAG,OAAO,CAAC,SAAS,EAAE,EACzB,CAAC;gBACF,MAAM,SAAS,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC;gBACpC,MAAM,MAAM,GAAG,MAAM,aAAa,CAAC,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,MAAM,CAAC,CAAC;gBAEzD,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;gBACrB,OAAO,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC,CAAC;gBACzD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;YAClC,CAAC;;;;;;;;;IACF,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QAChB,IAAI,cAAsB,CAAC;QAC3B,IAAI,CAAC;YACJ,MAAM,OAAO,EAAE,QAAQ,EAAE,CAAC,MAAM,CAAC,CAAC;YAElC,cAAc,GAAG,WAAW,CAAC,KAAK,CAAC,CAAC;QACrC,CAAC;QAAC,OAAO,aAAa,EAAE,CAAC;YACxB,cAAc,GAAG,WAAW,CAC3B,IAAI,eAAe,CAClB,aAAa,EACb,KAAK,EACL,oCAAoC,CACpC,CACD,CAAC;QACH,CAAC;QAED,OAAO,CAAC,aAAa,CAAC;YACrB,IAAI,EAAE,KAAK;YACX,IAAI;YACJ,UAAU,EAAE,IAAI;YAChB,gBAAgB;YAChB,QAAQ,EAAE,EAAE;YACZ,OAAO,EAAE,cAAc;SACc,CAAC,CAAC;QACxC,OAAO;IACR,CAAC;IAED,MAAM,OAAO,EAAE,QAAQ,EAAE,CAAC,MAAM,CAAC,CAAC;IAElC,MAAM,UAAU,GAAG,8BAA8B,CAAC,OAAO,EAAE,cAAc,CAAC,CAAC;IAE3E,OAAO,CAAC,aAAa,CAAC;QACrB,IAAI,EAAE,KAAK;QACX,IAAI;QACJ,UAAU;QACV,gBAAgB;QAChB,QAAQ,EAAE,2BAA2B,CAAC,UAAU,EAAE,gBAAgB,CAAC;KAC9B,CAAC,CAAC;AACzC,CAAC"}

package/dist/_statistics.d.ts

@@ -0,0 +1,15 @@
+import { ResourceBenchSample, ResourceBenchStatistics } from "./_types.js";
+/**
+ * Summarise per-batch resource samples.
+ *
+ * Rates are medians because a batch that happened to absorb a collection is a
+ * heavy right tail, exactly as with timings. Peaks are maxima because the
+ * question they answer is what had to fit in memory, not what typically did.
+ *
+ * @param samples Per-operation costs, one entry per batch.
+ * @param heapLimitBytes The heap ceiling this process was given.
+ * @returns The computed statistics.
+ * @throws {RangeError} If `samples` is empty.
+ */
+export declare function composeResourceBenchStatistics(samples: readonly ResourceBenchSample[], heapLimitBytes: number): ResourceBenchStatistics;
+//# sourceMappingURL=_statistics.d.ts.map

package/dist/_statistics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"_statistics.d.ts","sourceRoot":"","sources":["../src/_statistics.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,mBAAmB,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AAkB3E;;;;;;;;;;;GAWG;AACH,wBAAgB,8BAA8B,CAC7C,OAAO,EAAE,SAAS,mBAAmB,EAAE,EACvC,cAAc,EAAE,MAAM,GACpB,uBAAuB,CAwCzB"}

package/dist/_statistics.js

@@ -0,0 +1,54 @@
+import { maxBy } from "@ac-kit/algo";
+import { median, sumBy } from "@ac-kit/math-stats";
+function medianBy_(samples, valueOf) {
+    return median(Array.from(samples, valueOf));
+}
+function maxValueBy_(samples, valueOf) {
+    const peak = maxBy(samples, valueOf);
+    return peak === null ? 0 : valueOf(peak);
+}
+/**
+ * Summarise per-batch resource samples.
+ *
+ * Rates are medians because a batch that happened to absorb a collection is a
+ * heavy right tail, exactly as with timings. Peaks are maxima because the
+ * question they answer is what had to fit in memory, not what typically did.
+ *
+ * @param samples Per-operation costs, one entry per batch.
+ * @param heapLimitBytes The heap ceiling this process was given.
+ * @returns The computed statistics.
+ * @throws {RangeError} If `samples` is empty.
+ */
+export function composeResourceBenchStatistics(samples, heapLimitBytes) {
+    if (samples.length === 0) {
+        throw new RangeError("Cannot summarise an empty sample set");
+    }
+    const cpuTimeMs = medianBy_(samples, (sample) => sample.cpuTimeMs);
+    const heapPeakBytes = maxValueBy_(samples, (sample) => sample.heapPeakBytes);
+    // One `null` means the runtime never reports collections, so the whole
+    // series is absent rather than zero.
+    const observedGc = samples[0]?.gcPauseMs !== null;
+    const gcPauseMs = observedGc
+        ? medianBy_(samples, (sample) => sample.gcPauseMs ?? 0)
+        : null;
+    const gcCount = observedGc
+        ? medianBy_(samples, (sample) => sample.gcCount ?? 0)
+        : null;
+    // Ratios come from the totals rather than from the medians, so a collection
+    // that landed in one batch is not divided by another batch's CPU time.
+    const totalCpuTimeMs = sumBy(samples, (sample) => sample.cpuTimeMs);
+    const totalGcPauseMs = sumBy(samples, (sample) => sample.gcPauseMs ?? 0);
+    return {
+        samples: samples.length,
+        operations: sumBy(samples, (sample) => sample.operations),
+        cpuTimeMs,
+        allocatedBytes: medianBy_(samples, (sample) => sample.allocatedBytes),
+        gcPauseMs,
+        gcCount,
+        heapPeakBytes,
+        rssPeakBytes: maxValueBy_(samples, (sample) => sample.rssBytes),
+        heapLimitRatio: heapLimitBytes > 0 ? heapPeakBytes / heapLimitBytes : 0,
+        gcTimeRatio: observedGc && totalCpuTimeMs > 0 ? totalGcPauseMs / totalCpuTimeMs : null,
+    };
+}
+//# sourceMappingURL=_statistics.js.map

package/dist/_statistics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"_statistics.js","sourceRoot":"","sources":["../src/_statistics.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AAErC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAInD,SAAS,SAAS,CACjB,OAAuC,EACvC,OAAgD;IAEhD,OAAO,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC;AAC7C,CAAC;AAED,SAAS,WAAW,CACnB,OAAuC,EACvC,OAAgD;IAEhD,MAAM,IAAI,GAAG,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IAErC,OAAO,IAAI,KAAK,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;AAC1C,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,8BAA8B,CAC7C,OAAuC,EACvC,cAAsB;IAEtB,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC1B,MAAM,IAAI,UAAU,CAAC,sCAAsC,CAAC,CAAC;IAC9D,CAAC;IAED,MAAM,SAAS,GAAG,SAAS,CAAC,OAAO,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IACnE,MAAM,aAAa,GAAG,WAAW,CAAC,OAAO,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC;IAE7E,uEAAuE;IACvE,qCAAqC;IACrC,MAAM,UAAU,GAAG,OAAO,CAAC,CAAC,CAAC,EAAE,SAAS,KAAK,IAAI,CAAC;IAElD,MAAM,SAAS,GAAG,UAAU;QAC3B,CAAC,CAAC,SAAS,CAAC,OAAO,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,SAAS,IAAI,CAAC,CAAC;QACvD,CAAC,CAAC,IAAI,CAAC;IACR,MAAM,OAAO,GAAG,UAAU;QACzB,CAAC,CAAC,SAAS,CAAC,OAAO,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,OAAO,IAAI,CAAC,CAAC;QACrD,CAAC,CAAC,IAAI,CAAC;IAER,4EAA4E;IAC5E,uEAAuE;IACvE,MAAM,cAAc,GAAG,KAAK,CAAC,OAAO,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IACpE,MAAM,cAAc,GAAG,KAAK,CAAC,OAAO,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,SAAS,IAAI,CAAC,CAAC,CAAC;IAEzE,OAAO;QACN,OAAO,EAAE,OAAO,CAAC,MAAM;QACvB,UAAU,EAAE,KAAK,CAAC,OAAO,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,UAAU,CAAC;QAEzD,SAAS;QACT,cAAc,EAAE,SAAS,CAAC,OAAO,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,cAAc,CAAC;QACrE,SAAS;QACT,OAAO;QAEP,aAAa;QACb,YAAY,EAAE,WAAW,CAAC,OAAO,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC;QAE/D,cAAc,EAAE,cAAc,GAAG,CAAC,CAAC,CAAC,CAAC,aAAa,GAAG,cAAc,CAAC,CAAC,CAAC,CAAC;QACvE,WAAW,EACV,UAAU,IAAI,cAAc,GAAG,CAAC,CAAC,CAAC,CAAC,cAAc,GAAG,cAAc,CAAC,CAAC,CAAC,IAAI;KAC1E,CAAC;AACH,CAAC"}

package/dist/_types.d.ts

@@ -0,0 +1,91 @@
+import * as z from "zod/mini";
+/**
+ * One batch's cost, already divided by the operations it ran, so every sample
+ * is directly comparable regardless of how the sampler sized its batches.
+ */
+export declare const resourceBenchSampleSchema: z.ZodMiniObject<{
+    operations: z.ZodMiniNumber<number>;
+    cpuTimeMs: z.ZodMiniNumber<number>;
+    allocatedBytes: z.ZodMiniNumber<number>;
+    heapPeakBytes: z.ZodMiniNumber<number>;
+    rssBytes: z.ZodMiniNumber<number>;
+    gcCount: z.ZodMiniNullable<z.ZodMiniNumber<number>>;
+    gcPauseMs: z.ZodMiniNullable<z.ZodMiniNumber<number>>;
+}, z.core.$strip>;
+export type ResourceBenchSample = z.infer<typeof resourceBenchSampleSchema>;
+declare const resourceBenchStatisticsSchema: z.ZodMiniObject<{
+    samples: z.ZodMiniNumber<number>;
+    operations: z.ZodMiniNumber<number>;
+    cpuTimeMs: z.ZodMiniNumber<number>;
+    allocatedBytes: z.ZodMiniNumber<number>;
+    gcPauseMs: z.ZodMiniNullable<z.ZodMiniNumber<number>>;
+    gcCount: z.ZodMiniNullable<z.ZodMiniNumber<number>>;
+    heapPeakBytes: z.ZodMiniNumber<number>;
+    rssPeakBytes: z.ZodMiniNumber<number>;
+    heapLimitRatio: z.ZodMiniNumber<number>;
+    gcTimeRatio: z.ZodMiniNullable<z.ZodMiniNumber<number>>;
+}, z.core.$strip>;
+export type ResourceBenchStatistics = z.infer<typeof resourceBenchStatisticsSchema>;
+export declare const resourceBenchRunCaseResultSchema: z.ZodMiniObject<{
+    name: z.ZodMiniString<string>;
+    tags: z.ZodMiniRecord<z.ZodMiniString<string>, z.ZodMiniString<string>>;
+    statistics: z.ZodMiniNullable<z.ZodMiniObject<{
+        samples: z.ZodMiniNumber<number>;
+        operations: z.ZodMiniNumber<number>;
+        cpuTimeMs: z.ZodMiniNumber<number>;
+        allocatedBytes: z.ZodMiniNumber<number>;
+        gcPauseMs: z.ZodMiniNullable<z.ZodMiniNumber<number>>;
+        gcCount: z.ZodMiniNullable<z.ZodMiniNumber<number>>;
+        heapPeakBytes: z.ZodMiniNumber<number>;
+        rssPeakBytes: z.ZodMiniNumber<number>;
+        heapLimitRatio: z.ZodMiniNumber<number>;
+        gcTimeRatio: z.ZodMiniNullable<z.ZodMiniNumber<number>>;
+    }, z.core.$strip>>;
+    forcedCollection: z.ZodMiniBoolean<boolean>;
+    warnings: z.ZodMiniArray<z.ZodMiniObject<{
+        kind: z.ZodMiniEnum<{
+            "below-resolution": "below-resolution";
+            "gc-bound": "gc-bound";
+            "heap-pressure": "heap-pressure";
+            "no-forced-collection": "no-forced-collection";
+            "too-few-samples": "too-few-samples";
+        }>;
+        message: z.ZodMiniString<string>;
+    }, z.core.$strip>>;
+    failure: z.ZodMiniOptional<z.ZodMiniString<string>>;
+}, z.core.$strip>;
+export type ResourceBenchRunCaseResult = z.infer<typeof resourceBenchRunCaseResultSchema>;
+export declare const resourceBenchRunConditionResultSchema: z.ZodMiniObject<{
+    title: z.ZodMiniString<string>;
+    results: z.ZodMiniArray<z.ZodMiniObject<{
+        name: z.ZodMiniString<string>;
+        tags: z.ZodMiniRecord<z.ZodMiniString<string>, z.ZodMiniString<string>>;
+        statistics: z.ZodMiniNullable<z.ZodMiniObject<{
+            samples: z.ZodMiniNumber<number>;
+            operations: z.ZodMiniNumber<number>;
+            cpuTimeMs: z.ZodMiniNumber<number>;
+            allocatedBytes: z.ZodMiniNumber<number>;
+            gcPauseMs: z.ZodMiniNullable<z.ZodMiniNumber<number>>;
+            gcCount: z.ZodMiniNullable<z.ZodMiniNumber<number>>;
+            heapPeakBytes: z.ZodMiniNumber<number>;
+            rssPeakBytes: z.ZodMiniNumber<number>;
+            heapLimitRatio: z.ZodMiniNumber<number>;
+            gcTimeRatio: z.ZodMiniNullable<z.ZodMiniNumber<number>>;
+        }, z.core.$strip>>;
+        forcedCollection: z.ZodMiniBoolean<boolean>;
+        warnings: z.ZodMiniArray<z.ZodMiniObject<{
+            kind: z.ZodMiniEnum<{
+                "below-resolution": "below-resolution";
+                "gc-bound": "gc-bound";
+                "heap-pressure": "heap-pressure";
+                "no-forced-collection": "no-forced-collection";
+                "too-few-samples": "too-few-samples";
+            }>;
+            message: z.ZodMiniString<string>;
+        }, z.core.$strip>>;
+        failure: z.ZodMiniOptional<z.ZodMiniString<string>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type ResourceBenchRunConditionResult = z.infer<typeof resourceBenchRunConditionResultSchema>;
+export {};
+//# sourceMappingURL=_types.d.ts.map

package/dist/_types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"_types.d.ts","sourceRoot":"","sources":["../src/_types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,UAAU,CAAC;AAI9B;;;GAGG;AACH,eAAO,MAAM,yBAAyB;;;;;;;;iBASpC,CAAC;AACH,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAE5E,QAAA,MAAM,6BAA6B;;;;;;;;;;;iBAmBjC,CAAC;AACH,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,KAAK,CAC5C,OAAO,6BAA6B,CACpC,CAAC;AAEF,eAAO,MAAM,gCAAgC;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAc3C,CAAC;AACH,MAAM,MAAM,0BAA0B,GAAG,CAAC,CAAC,KAAK,CAC/C,OAAO,gCAAgC,CACvC,CAAC;AAEF,eAAO,MAAM,qCAAqC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAGhD,CAAC;AACH,MAAM,MAAM,+BAA+B,GAAG,CAAC,CAAC,KAAK,CACpD,OAAO,qCAAqC,CAC5C,CAAC"}

package/dist/_types.js

@@ -0,0 +1,48 @@
+import * as z from "zod/mini";
+import { resourceBenchWarningSchema } from "./_warnings.js";
+/**
+ * One batch's cost, already divided by the operations it ran, so every sample
+ * is directly comparable regardless of how the sampler sized its batches.
+ */
+export const resourceBenchSampleSchema = z.object({
+    operations: z.number(),
+    cpuTimeMs: z.number(),
+    allocatedBytes: z.number(),
+    heapPeakBytes: z.number(),
+    rssBytes: z.number(),
+    /** `null` where the runtime does not report collections. */
+    gcCount: z.nullable(z.number()),
+    gcPauseMs: z.nullable(z.number()),
+});
+const resourceBenchStatisticsSchema = z.object({
+    samples: z.number(),
+    operations: z.number(),
+    /** Medians, per operation, except the peaks which are maxima over the run. */
+    cpuTimeMs: z.number(),
+    allocatedBytes: z.number(),
+    /** `null` where the runtime does not report collections. */
+    gcPauseMs: z.nullable(z.number()),
+    gcCount: z.nullable(z.number()),
+    heapPeakBytes: z.number(),
+    rssPeakBytes: z.number(),
+    /** Share of the heap limit the peak reached, in [0, 1]. */
+    heapLimitRatio: z.number(),
+    /** Fraction of the CPU time spent collecting, in [0, 1], or `null`. */
+    gcTimeRatio: z.nullable(z.number()),
+});
+export const resourceBenchRunCaseResultSchema = z.object({
+    name: z.string(),
+    tags: z.record(z.string(), z.string()),
+    /** `null` when the case failed. */
+    statistics: z.nullable(resourceBenchStatisticsSchema),
+    /** Whether `--expose-gc` was available, so the numbers can be read fairly. */
+    forcedCollection: z.boolean(),
+    warnings: z.array(resourceBenchWarningSchema),
+    /** Present when the case threw. */
+    failure: z.optional(z.string()),
+});
+export const resourceBenchRunConditionResultSchema = z.object({
+    title: z.string(),
+    results: z.array(resourceBenchRunCaseResultSchema),
+});
+//# sourceMappingURL=_types.js.map

package/dist/_types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"_types.js","sourceRoot":"","sources":["../src/_types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,UAAU,CAAC;AAE9B,OAAO,EAAE,0BAA0B,EAAE,MAAM,gBAAgB,CAAC;AAE5D;;;GAGG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,CAAC,CAAC,MAAM,CAAC;IACjD,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE;IACtB,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;IACrB,cAAc,EAAE,CAAC,CAAC,MAAM,EAAE;IAC1B,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE;IACzB,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE;IACpB,4DAA4D;IAC5D,OAAO,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;IAC/B,SAAS,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;CACjC,CAAC,CAAC;AAGH,MAAM,6BAA6B,GAAG,CAAC,CAAC,MAAM,CAAC;IAC9C,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE;IACnB,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE;IAEtB,8EAA8E;IAC9E,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;IACrB,cAAc,EAAE,CAAC,CAAC,MAAM,EAAE;IAC1B,4DAA4D;IAC5D,SAAS,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;IACjC,OAAO,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;IAE/B,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE;IACzB,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE;IAExB,2DAA2D;IAC3D,cAAc,EAAE,CAAC,CAAC,MAAM,EAAE;IAE1B,uEAAuE;IACvE,WAAW,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;CACnC,CAAC,CAAC;AAKH,MAAM,CAAC,MAAM,gCAAgC,GAAG,CAAC,CAAC,MAAM,CAAC;IACxD,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;IAChB,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC;IAEtC,mCAAmC;IACnC,UAAU,EAAE,CAAC,CAAC,QAAQ,CAAC,6BAA6B,CAAC;IAErD,8EAA8E;IAC9E,gBAAgB,EAAE,CAAC,CAAC,OAAO,EAAE;IAE7B,QAAQ,EAAE,CAAC,CAAC,KAAK,CAAC,0BAA0B,CAAC;IAE7C,mCAAmC;IACnC,OAAO,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;CAC/B,CAAC,CAAC;AAKH,MAAM,CAAC,MAAM,qCAAqC,GAAG,CAAC,CAAC,MAAM,CAAC;IAC7D,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE;IACjB,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,gCAAgC,CAAC;CAClD,CAAC,CAAC"}

package/dist/_warnings.d.ts

@@ -0,0 +1,23 @@
+import * as z from "zod/mini";
+import { ResourceBenchStatistics } from "./_types.js";
+export declare const resourceBenchWarningKindSchema: z.ZodMiniEnum<{
+    "below-resolution": "below-resolution";
+    "gc-bound": "gc-bound";
+    "heap-pressure": "heap-pressure";
+    "no-forced-collection": "no-forced-collection";
+    "too-few-samples": "too-few-samples";
+}>;
+export type ResourceBenchWarningKind = z.infer<typeof resourceBenchWarningKindSchema>;
+export declare const resourceBenchWarningSchema: z.ZodMiniObject<{
+    kind: z.ZodMiniEnum<{
+        "below-resolution": "below-resolution";
+        "gc-bound": "gc-bound";
+        "heap-pressure": "heap-pressure";
+        "no-forced-collection": "no-forced-collection";
+        "too-few-samples": "too-few-samples";
+    }>;
+    message: z.ZodMiniString<string>;
+}, z.core.$strip>;
+export type ResourceBenchWarning = z.infer<typeof resourceBenchWarningSchema>;
+export declare function detectResourceBenchWarnings(statistics: ResourceBenchStatistics, forcedCollection: boolean): ResourceBenchWarning[];
+//# sourceMappingURL=_warnings.d.ts.map

package/dist/_warnings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"_warnings.d.ts","sourceRoot":"","sources":["../src/_warnings.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,UAAU,CAAC;AAE9B,OAAO,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AAWtD,eAAO,MAAM,8BAA8B;;;;;;EAMzC,CAAC;AACH,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,KAAK,CAC7C,OAAO,8BAA8B,CACrC,CAAC;AAEF,eAAO,MAAM,0BAA0B;;;;;;;;;iBAGrC,CAAC;AACH,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAC;AAE9E,wBAAgB,2BAA2B,CAC1C,UAAU,EAAE,uBAAuB,EACnC,gBAAgB,EAAE,OAAO,GACvB,oBAAoB,EAAE,CA4CxB"}

package/dist/_warnings.js

@@ -0,0 +1,54 @@
+import * as z from "zod/mini";
+/** Share of the heap limit above which a peak is worth flagging. */
+const HEAP_PRESSURE_RATIO_ = 0.8;
+/** Share of CPU time spent collecting above which the case is GC-bound. */
+const GC_BOUND_RATIO_ = 0.25;
+/** Below this many bytes per operation, allocation is below what GC resolves. */
+const ALLOCATION_RESOLUTION_BYTES_ = 8;
+export const resourceBenchWarningKindSchema = z.enum([
+    "no-forced-collection",
+    "heap-pressure",
+    "gc-bound",
+    "below-resolution",
+    "too-few-samples",
+]);
+export const resourceBenchWarningSchema = z.object({
+    kind: resourceBenchWarningKindSchema,
+    message: z.string(),
+});
+export function detectResourceBenchWarnings(statistics, forcedCollection) {
+    const warnings = [];
+    if (!forcedCollection) {
+        warnings.push({
+            kind: "no-forced-collection",
+            message: "run without --expose-gc: allocation includes whatever the collector had not yet reclaimed, so compare cases within this run only",
+        });
+    }
+    if (statistics.samples < 5) {
+        warnings.push({
+            kind: "too-few-samples",
+            message: `only ${statistics.samples} batches; the allocation figure has not been shown to settle`,
+        });
+    }
+    if (statistics.heapLimitRatio >= HEAP_PRESSURE_RATIO_) {
+        warnings.push({
+            kind: "heap-pressure",
+            message: `peak heap reached ${(statistics.heapLimitRatio * 100).toFixed(0)}% of the limit; the collector was working against the case and the timing reflects that`,
+        });
+    }
+    if (statistics.gcTimeRatio !== null &&
+        statistics.gcTimeRatio >= GC_BOUND_RATIO_) {
+        warnings.push({
+            kind: "gc-bound",
+            message: `${(statistics.gcTimeRatio * 100).toFixed(0)}% of CPU time was spent collecting; this case is bound by what it allocates, not by what it computes`,
+        });
+    }
+    if (statistics.allocatedBytes < ALLOCATION_RESOLUTION_BYTES_) {
+        warnings.push({
+            kind: "below-resolution",
+            message: "allocation per operation is at the limit of what the heap counters resolve; treat as zero",
+        });
+    }
+    return warnings;
+}
+//# sourceMappingURL=_warnings.js.map

package/dist/_warnings.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"_warnings.js","sourceRoot":"","sources":["../src/_warnings.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,UAAU,CAAC;AAI9B,oEAAoE;AACpE,MAAM,oBAAoB,GAAG,GAAG,CAAC;AAEjC,2EAA2E;AAC3E,MAAM,eAAe,GAAG,IAAI,CAAC;AAE7B,iFAAiF;AACjF,MAAM,4BAA4B,GAAG,CAAC,CAAC;AAEvC,MAAM,CAAC,MAAM,8BAA8B,GAAG,CAAC,CAAC,IAAI,CAAC;IACpD,sBAAsB;IACtB,eAAe;IACf,UAAU;IACV,kBAAkB;IAClB,iBAAiB;CACjB,CAAC,CAAC;AAKH,MAAM,CAAC,MAAM,0BAA0B,GAAG,CAAC,CAAC,MAAM,CAAC;IAClD,IAAI,EAAE,8BAA8B;IACpC,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE;CACnB,CAAC,CAAC;AAGH,MAAM,UAAU,2BAA2B,CAC1C,UAAmC,EACnC,gBAAyB;IAEzB,MAAM,QAAQ,GAA2B,EAAE,CAAC;IAE5C,IAAI,CAAC,gBAAgB,EAAE,CAAC;QACvB,QAAQ,CAAC,IAAI,CAAC;YACb,IAAI,EAAE,sBAAsB;YAC5B,OAAO,EACN,kIAAkI;SACnI,CAAC,CAAC;IACJ,CAAC;IAED,IAAI,UAAU,CAAC,OAAO,GAAG,CAAC,EAAE,CAAC;QAC5B,QAAQ,CAAC,IAAI,CAAC;YACb,IAAI,EAAE,iBAAiB;YACvB,OAAO,EAAE,QAAQ,UAAU,CAAC,OAAO,8DAA8D;SACjG,CAAC,CAAC;IACJ,CAAC;IAED,IAAI,UAAU,CAAC,cAAc,IAAI,oBAAoB,EAAE,CAAC;QACvD,QAAQ,CAAC,IAAI,CAAC;YACb,IAAI,EAAE,eAAe;YACrB,OAAO,EAAE,qBAAqB,CAAC,UAAU,CAAC,cAAc,GAAG,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,yFAAyF;SACnK,CAAC,CAAC;IACJ,CAAC;IAED,IACC,UAAU,CAAC,WAAW,KAAK,IAAI;QAC/B,UAAU,CAAC,WAAW,IAAI,eAAe,EACxC,CAAC;QACF,QAAQ,CAAC,IAAI,CAAC;YACb,IAAI,EAAE,UAAU;YAChB,OAAO,EAAE,GAAG,CAAC,UAAU,CAAC,WAAW,GAAG,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,sGAAsG;SAC3J,CAAC,CAAC;IACJ,CAAC;IAED,IAAI,UAAU,CAAC,cAAc,GAAG,4BAA4B,EAAE,CAAC;QAC9D,QAAQ,CAAC,IAAI,CAAC;YACb,IAAI,EAAE,kBAAkB;YACxB,OAAO,EACN,2FAA2F;SAC5F,CAAC,CAAC;IACJ,CAAC;IAED,OAAO,QAAQ,CAAC;AACjB,CAAC"}

package/dist/decl.d.ts

@@ -0,0 +1,8 @@
+import { MaybeAsyncCallableNoArgs } from "@ac-kit/core";
+import { ResourceCaseFn } from "./_run-case.js";
+import { ResourceCaseOptions, ResourceConditionOptions } from "./options.js";
+export declare function resourceCondition(title: string, fn: MaybeAsyncCallableNoArgs): void;
+export declare function resourceCondition(title: string, options: ResourceConditionOptions, fn: MaybeAsyncCallableNoArgs): void;
+export declare function resourceCase(title: string, fn: ResourceCaseFn): void;
+export declare function resourceCase(title: string, options: ResourceCaseOptions, fn: ResourceCaseFn): void;
+//# sourceMappingURL=decl.d.ts.map

package/dist/decl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decl.d.ts","sourceRoot":"","sources":["../src/decl.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,wBAAwB,EAAE,MAAM,cAAc,CAAC;AAExD,OAAO,EAAE,cAAc,EAAmB,MAAM,gBAAgB,CAAC;AACjE,OAAO,EAAE,mBAAmB,EAAE,wBAAwB,EAAE,MAAM,cAAc,CAAC;AAE7E,wBAAgB,iBAAiB,CAChC,KAAK,EAAE,MAAM,EACb,EAAE,EAAE,wBAAwB,GAC1B,IAAI,CAAC;AACR,wBAAgB,iBAAiB,CAChC,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,wBAAwB,EACjC,EAAE,EAAE,wBAAwB,GAC1B,IAAI,CAAC;AAgBR,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,cAAc,GAAG,IAAI,CAAC;AACtE,wBAAgB,YAAY,CAC3B,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,mBAAmB,EAC5B,EAAE,EAAE,cAAc,GAChB,IAAI,CAAC"}

package/dist/decl.js

@@ -0,0 +1,20 @@
+import { registerCase, registerCondition } from "@ac-bench/core/runner";
+import { runResourceCase } from "./_run-case.js";
+export function resourceCondition(title, optionsOrFn, fn) {
+    const [options, callback] = typeof optionsOrFn === "function"
+        ? [undefined, optionsOrFn]
+        : [optionsOrFn, fn];
+    registerCondition("resource", title, callback, {
+        additionalRunArgs: [options],
+    });
+}
+export function resourceCase(title, optionsOrFn, fn) {
+    const isOptionsForm = typeof optionsOrFn !== "function";
+    const options = isOptionsForm ? optionsOrFn : undefined;
+    const caseFn = isOptionsForm ? fn : optionsOrFn;
+    registerCase("resource", title, (context, conditionOptions) => runResourceCase(title, caseFn, context, {
+        ...options,
+        conditionOptions,
+    }));
+}
+//# sourceMappingURL=decl.js.map

package/dist/decl.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"decl.js","sourceRoot":"","sources":["../src/decl.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAGxE,OAAO,EAAkB,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAYjE,MAAM,UAAU,iBAAiB,CAChC,KAAa,EACb,WAAgE,EAChE,EAA6B;IAE7B,MAAM,CAAC,OAAO,EAAE,QAAQ,CAAC,GACxB,OAAO,WAAW,KAAK,UAAU;QAChC,CAAC,CAAC,CAAC,SAAS,EAAE,WAAW,CAAC;QAC1B,CAAC,CAAC,CAAC,WAAW,EAAE,EAAG,CAAC,CAAC;IAEvB,iBAAiB,CAAC,UAAU,EAAE,KAAK,EAAE,QAAQ,EAAE;QAC9C,iBAAiB,EAAE,CAAC,OAAO,CAAC;KAC5B,CAAC,CAAC;AACJ,CAAC;AAQD,MAAM,UAAU,YAAY,CAC3B,KAAa,EACb,WAAiD,EACjD,EAAmB;IAEnB,MAAM,aAAa,GAAG,OAAO,WAAW,KAAK,UAAU,CAAC;IACxD,MAAM,OAAO,GAAG,aAAa,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,SAAS,CAAC;IACxD,MAAM,MAAM,GAAG,aAAa,CAAC,CAAC,CAAC,EAAG,CAAC,CAAC,CAAC,WAAW,CAAC;IAEjD,YAAY,CACX,UAAU,EACV,KAAK,EACL,CAAC,OAAO,EAAE,gBAAgB,EAAE,EAAE,CAC7B,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE;QACvC,GAAG,OAAO;QACV,gBAAgB;KAChB,CAAC,CACH,CAAC;AACH,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { afterAll, afterEach, beforeAll, beforeEach, } from "@ac-bench/core/runner";
+export * from "./decl.js";
+export * from "./options.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,QAAQ,EACR,SAAS,EACT,SAAS,EACT,UAAU,GACV,MAAM,uBAAuB,CAAC;AAC/B,cAAc,WAAW,CAAC;AAC1B,cAAc,cAAc,CAAC"}

package/dist/index.js

@@ -0,0 +1,4 @@
+export { afterAll, afterEach, beforeAll, beforeEach, } from "@ac-bench/core/runner";
+export * from "./decl.js";
+export * from "./options.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,QAAQ,EACR,SAAS,EACT,SAAS,EACT,UAAU,GACV,MAAM,uBAAuB,CAAC;AAC/B,cAAc,WAAW,CAAC;AAC1B,cAAc,cAAc,CAAC"}

package/dist/options.d.ts

@@ -0,0 +1,46 @@
+import { CaseCommonOptions, SamplingBounds } from "@ac-bench/core/runner";
+export type ResourceSampling = SamplingBounds & {
+    /** Batches run and discarded first, letting the JIT settle. Defaults to 2. */
+    warmup: number;
+    /**
+     * How tight the interval around CPU time must be before sampling stops.
+     *
+     * The byte counters are judged by settling instead, since a count that never
+     * varies has no interval worth tightening.
+     */
+    relativeError: number | "auto" | "off";
+    /** Confidence level for the CPU-time interval. Defaults to 0.95. */
+    confidenceLevel: number;
+    /**
+     * Relative spread within which the byte counters count as settled. Defaults
+     * to 0.02 — a heap delta repeats to within a fraction of a percent, not to
+     * the byte.
+     */
+    allocationTolerance: number;
+    /** Batches whose byte counters must agree before stopping. Defaults to 3. */
+    stableBatches: number;
+    /**
+     * Work one batch should amount to, in milliseconds. Defaults to 50 — far
+     * longer than a duration measure wants, because the counters are read once
+     * per batch and that cost is divided by the operations in it. A batch of one
+     * reports the measure's own bookkeeping as the case's allocation.
+     */
+    targetBatchMs: number;
+};
+export declare const RESOURCE_SAMPLING_DEFAULTS: {
+    readonly warmup: 2;
+    readonly minRuns: 10;
+    readonly maxRuns: 2000;
+    readonly minTimeMs: 250;
+    readonly maxTimeMs: 10000;
+    readonly relativeError: "auto";
+    readonly confidenceLevel: 0.95;
+    readonly allocationTolerance: 0.02;
+    readonly stableBatches: 3;
+    readonly targetBatchMs: 50;
+};
+export type ResourceConditionOptions = {
+    sampling?: Partial<ResourceSampling>;
+};
+export type ResourceCaseOptions = CaseCommonOptions;
+//# sourceMappingURL=options.d.ts.map

package/dist/options.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"options.d.ts","sourceRoot":"","sources":["../src/options.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAE1E,MAAM,MAAM,gBAAgB,GAAG,cAAc,GAAG;IAC/C,8EAA8E;IAC9E,MAAM,EAAE,MAAM,CAAC;IAEf;;;;;OAKG;IACH,aAAa,EAAE,MAAM,GAAG,MAAM,GAAG,KAAK,CAAC;IAEvC,oEAAoE;IACpE,eAAe,EAAE,MAAM,CAAC;IAExB;;;;OAIG;IACH,mBAAmB,EAAE,MAAM,CAAC;IAE5B,6EAA6E;IAC7E,aAAa,EAAE,MAAM,CAAC;IAEtB;;;;;OAKG;IACH,aAAa,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF,eAAO,MAAM,0BAA0B;qBAC9B,CAAC;sBACA,EAAE;sBACF,IAAI;wBACF,GAAG;wBACH,KAAM;4BACF,MAAM;8BACJ,IAAI;kCACA,IAAI;4BACV,CAAC;4BACD,EAAE;CACmB,CAAC;AAEtC,MAAM,MAAM,wBAAwB,GAAG;IACtC,QAAQ,CAAC,EAAE,OAAO,CAAC,gBAAgB,CAAC,CAAC;CACrC,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG,iBAAiB,CAAC"}

package/dist/options.js

@@ -0,0 +1,13 @@
+export const RESOURCE_SAMPLING_DEFAULTS = {
+    warmup: 2,
+    minRuns: 10,
+    maxRuns: 2000,
+    minTimeMs: 250,
+    maxTimeMs: 10000,
+    relativeError: "auto",
+    confidenceLevel: 0.95,
+    allocationTolerance: 0.02,
+    stableBatches: 3,
+    targetBatchMs: 50,
+};
+//# sourceMappingURL=options.js.map

package/dist/options.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"options.js","sourceRoot":"","sources":["../src/options.ts"],"names":[],"mappings":"AAoCA,MAAM,CAAC,MAAM,0BAA0B,GAAG;IACzC,MAAM,EAAE,CAAC;IACT,OAAO,EAAE,EAAE;IACX,OAAO,EAAE,IAAI;IACb,SAAS,EAAE,GAAG;IACd,SAAS,EAAE,KAAM;IACjB,aAAa,EAAE,MAAM;IACrB,eAAe,EAAE,IAAI;IACrB,mBAAmB,EAAE,IAAI;IACzB,aAAa,EAAE,CAAC;IAChB,aAAa,EAAE,EAAE;CACmB,CAAC"}

package/dist/plugin.d.ts

@@ -0,0 +1,3 @@
+declare const _default: import("@ac-bench/core/plugin").MeasurePlugin;
+export default _default;
+//# sourceMappingURL=plugin.d.ts.map

package/dist/plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":""}

package/dist/plugin.js

@@ -0,0 +1,151 @@
+import { defineMeasurePlugin, MeasureResultValidationError, } from "@ac-bench/core/plugin";
+import { BYTE, MILLISECOND } from "@ac-kit/model-dataset";
+import * as z from "zod/mini";
+import { resourceBenchRunCaseResultSchema, resourceBenchRunConditionResultSchema, } from "./_types.js";
+const MEASURE_ID = "resource";
+function parseCaseResult_(value) {
+    const result = resourceBenchRunCaseResultSchema.safeParse(value);
+    if (!result.success) {
+        throw new MeasureResultValidationError(MEASURE_ID, z.prettifyError(result.error));
+    }
+    return result.data;
+}
+function parseConditionResult_(value) {
+    const result = resourceBenchRunConditionResultSchema.safeParse(value);
+    if (!result.success) {
+        throw new MeasureResultValidationError(MEASURE_ID, z.prettifyError(result.error));
+    }
+    return result.data;
+}
+const BYTE_FORMAT = { maximumFractionDigits: 0 };
+const MS_FORMAT = { minimumFractionDigits: 4, maximumFractionDigits: 4 };
+const RATIO_FORMAT = { style: "percent", maximumFractionDigits: 1 };
+const FIELDS = [
+    { name: "case", kind: "nominal", title: "case" },
+    {
+        name: "allocatedBytes",
+        kind: "quantitative",
+        title: "alloc/op",
+        unit: BYTE,
+        direction: "lower-is-better",
+        format: BYTE_FORMAT,
+    },
+    {
+        name: "cpuTimeMs",
+        kind: "quantitative",
+        title: "cpu/op",
+        unit: MILLISECOND,
+        direction: "lower-is-better",
+        format: MS_FORMAT,
+    },
+    {
+        name: "heapPeakBytes",
+        kind: "quantitative",
+        title: "heap peak",
+        unit: BYTE,
+        direction: "lower-is-better",
+        format: BYTE_FORMAT,
+    },
+    {
+        name: "rssPeakBytes",
+        kind: "quantitative",
+        title: "rss peak",
+        unit: BYTE,
+        direction: "lower-is-better",
+        format: BYTE_FORMAT,
+    },
+    {
+        name: "gcPauseMs",
+        kind: "quantitative",
+        title: "gc/op",
+        unit: MILLISECOND,
+        direction: "lower-is-better",
+        format: MS_FORMAT,
+    },
+    {
+        name: "gcTimeRatio",
+        kind: "quantitative",
+        title: "gc share",
+        direction: "lower-is-better",
+        format: RATIO_FORMAT,
+    },
+    {
+        name: "samples",
+        kind: "quantitative",
+        title: "n",
+        format: { maximumFractionDigits: 0 },
+    },
+    { name: "status", kind: "nominal", title: "status" },
+];
+function caseRow_(result) {
+    const stats = result.statistics;
+    if (!stats) {
+        return [
+            result.name,
+            null,
+            null,
+            null,
+            null,
+            null,
+            null,
+            null,
+            `FAILED: ${result.failure ?? "unknown"}`,
+        ];
+    }
+    return [
+        result.name,
+        stats.allocatedBytes,
+        stats.cpuTimeMs,
+        stats.heapPeakBytes,
+        stats.rssPeakBytes,
+        stats.gcPauseMs,
+        stats.gcTimeRatio,
+        stats.samples,
+        result.forcedCollection ? null : "no --expose-gc",
+    ];
+}
+export default defineMeasurePlugin({
+    id: MEASURE_ID,
+    label: "Resource",
+    parseCaseResult: parseCaseResult_,
+    parseConditionResult: parseConditionResult_,
+    fields: FIELDS,
+    caseRow: caseRow_,
+    // Bytes allocated is the figure this measure exists to compare, and it is
+    // deterministic enough to order cases by without an interval.
+    comparison: { field: "allocatedBytes" },
+    warnings: (result) => {
+        const diagnostics = [];
+        if (result.failure) {
+            diagnostics.push({
+                severity: "error",
+                code: "case-failed",
+                message: result.failure,
+            });
+        }
+        for (const warning of result.warnings) {
+            diagnostics.push({
+                severity: "warning",
+                code: warning.kind,
+                message: warning.message,
+            });
+        }
+        return diagnostics;
+    },
+    // A shared process makes heap attribution impossible — case A's garbage is
+    // in case B's heap — so each case gets its own, and interleaving rounds
+    // would defeat the same thing at a coarser grain.
+    scheduling: {
+        rounds: "one",
+        grouping: "case",
+        execArgv: ["--expose-gc"],
+    },
+    // Each execution measured its own process's heap. Pooling them would average
+    // two heaps that never coexisted, so the first is reported as it stands.
+    pool: (executions) => executions[0].result,
+    toJsonCase: (result) => result,
+    toJsonCondition: (result) => ({
+        resourceConditions: [{ kind: "resource", ...result }],
+    }),
+});
+//# sourceMappingURL=plugin.js.map

package/dist/plugin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.js","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "@ac-bench/measure-resource",
+  "version": "0.1.0",
+  "description": "Resource measure for @ac-bench: CPU time, peak heap, bytes allocated, and garbage-collection count and pause time.",
+  "keywords": [
+    "allocation",
+    "benchmark",
+    "cpu",
+    "gc",
+    "memory"
+  ],
+  "homepage": "https://github.com/anthochamp/node-essentials/tree/main/bench/measure-resource#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-resource"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "exports": {
+    ".": "./dist/index.js",
+    "./plugin": "./dist/plugin.js"
+  },
+  "publishConfig": {
+    "main": "./dist/index.js",
+    "exports": {
+      ".": "./dist/index.js",
+      "./plugin": "./dist/plugin.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-kit/algo": "^0.1.0",
+    "@ac-kit/app-report": "^0.1.0",
+    "@ac-kit/core": "^0.1.0",
+    "@ac-kit/math-stats": "^0.1.0",
+    "@ac-kit/model-dataset": "^0.1.0",
+    "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",
+    "@types/node": "26.5.1",
+    "@typescript/native": "typescript@7.0.2",
+    "rimraf": "6.1.3",
+    "typedoc": "0.28.20",
+    "typescript": "@typescript/typescript6@6.0.2",
+    "vite": "8.3.0",
+    "vitest": "5.0.0"
+  },
+  "engines": {
+    "node": ">=24"
+  }
+}