@untestutils/perf 0.5.0

package/dist/types.d.mts

@@ -0,0 +1,172 @@
+export type BundleClass = "code" | "asset" | "other";
+export type BundleSize = {
+	total: number;
+	code: number;
+	asset: number;
+	other: number;
+	/** Per top-level dir name → bytes */
+	byDir: Record<string, number>;
+};
+export type ProcessMetrics = {
+	maxMemoryMb: number;
+	minMemoryMb: number;
+	avgMemoryMb: number;
+	maxCpuPct: number;
+	minCpuPct: number;
+	avgCpuPct: number;
+};
+export type AutocannonResult = {
+	requests: {
+		average: number;
+		mean: number;
+		total: number;
+	};
+	latency: {
+		average: number;
+		mean: number;
+		min: number;
+		max: number;
+		p50: number;
+		p97_5: number;
+		p99: number;
+	};
+	throughput: {
+		average: number;
+	};
+	errors: number;
+};
+export type ArtillerySummary = {
+	min: number;
+	max: number;
+	count: number;
+	mean: number;
+	p50: number;
+	median: number;
+	p75: number;
+	p90: number;
+	p95: number;
+	p99: number;
+	p999: number;
+};
+export type ArtilleryResult = {
+	aggregate: {
+		counters: Record<string, number | undefined>;
+		rates: Record<string, number | undefined>;
+		firstMetricAt: number;
+		lastMetricAt: number;
+		summaries: Record<string, ArtillerySummary>;
+		histograms: Record<string, ArtillerySummary>;
+	};
+	intermediate?: Array<{
+		counters: Record<string, number>;
+		rates: Record<string, number | null | undefined>;
+		period?: string;
+		summaries?: Record<string, ArtillerySummary>;
+		histograms?: Record<string, ArtillerySummary>;
+	}>;
+};
+export type BuildMetrics = ProcessMetrics & {
+	buildTimeSec: number;
+	bundle?: BundleSize;
+};
+export type LoadMetrics = ProcessMetrics & {
+	durationSec?: number;
+	responseTimeAvg?: number;
+	responseTimeMin?: number;
+	responseTimeMax?: number;
+	responseTimeP50?: number;
+	responseTimeP95?: number;
+	responseTimeP99?: number;
+	requestsPerSecond?: number;
+	errorRate?: number;
+	autocannon?: AutocannonResult;
+	artillery?: ArtilleryResult;
+};
+export type PerfTargetResult = {
+	id: string;
+	label: string;
+	build: BuildMetrics;
+	load?: LoadMetrics;
+};
+export type SpawnSpec = {
+	command: string;
+	args?: string[];
+	cwd?: string;
+	env?: Record<string, string>;
+};
+export type PerfTargetBuild = SpawnSpec & {
+	/** Filter stdout lines to log (default: high-signal only) */
+	logFilter?: (line: string) => boolean;
+};
+export type PerfTargetStart = SpawnSpec & {
+	port: number;
+	host?: string;
+	readyPath?: string;
+	readyTimeoutMs?: number;
+};
+export type PerfTargetLoad = {
+	/** Paths for documentation / future multi-url; autocannon hits base URL */
+	paths?: string[];
+	/** `true` = defaults; object = overrides. Omitted = skip autocannon. */
+	autocannon?: boolean | {
+		connections?: number;
+		durationSec?: number;
+	};
+	artillery?: {
+		config: string;
+	};
+};
+export type PerfTargetBundle = {
+	/** Absolute or root-relative dirs to walk after build */
+	dirs: string[];
+	classify?: (absPath: string) => BundleClass;
+};
+export type PerfTarget = {
+	id: string;
+	label?: string;
+	root: string;
+	build: PerfTargetBuild;
+	start: PerfTargetStart;
+	load?: PerfTargetLoad;
+	bundle?: PerfTargetBundle;
+};
+export type PerfReporterContext = {
+	suite: PerfSuite;
+	results: PerfTargetResult[];
+	runs: number;
+	skipLoad: boolean;
+};
+export type PerfReporter = {
+	name: string;
+	onStart?: (suite: PerfSuite) => void | Promise<void>;
+	onTarget?: (result: PerfTargetResult) => void | Promise<void>;
+	onEnd?: (ctx: PerfReporterContext) => void | Promise<void>;
+};
+export type PerfThresholds = {
+	buildTimeSec?: number;
+	maxMemoryMb?: number;
+	requestsPerSecond?: number;
+	responseTimeP95?: number;
+	errorRate?: number;
+};
+export type PerfSuite = {
+	/** Absolute or cwd-relative output for JSON / temp load artifacts */
+	artifactsDir?: string;
+	runs?: number;
+	skipLoad?: boolean;
+	coolDownMs?: number;
+	targets: PerfTarget[];
+	beforeAll?: (suite: PerfSuite) => void | Promise<void>;
+	beforeTarget?: (target: PerfTarget) => void | Promise<void>;
+	afterTarget?: (target: PerfTarget, result: PerfTargetResult) => void | Promise<void>;
+	reporters?: PerfReporter[];
+	thresholds?: PerfThresholds;
+	/** Select subset by id or label prefix */
+	only?: string | string[];
+};
+export type RunPerfOptions = {
+	runs?: number;
+	skipLoad?: boolean;
+	only?: string | string[];
+	json?: boolean;
+};

package/dist/types.d.ts

@@ -0,0 +1,173 @@
+export type BundleClass = 'code' | 'asset' | 'other';
+export type BundleSize = {
+    total: number;
+    code: number;
+    asset: number;
+    other: number;
+    /** Per top-level dir name → bytes */
+    byDir: Record<string, number>;
+};
+export type ProcessMetrics = {
+    maxMemoryMb: number;
+    minMemoryMb: number;
+    avgMemoryMb: number;
+    maxCpuPct: number;
+    minCpuPct: number;
+    avgCpuPct: number;
+};
+export type AutocannonResult = {
+    requests: {
+        average: number;
+        mean: number;
+        total: number;
+    };
+    latency: {
+        average: number;
+        mean: number;
+        min: number;
+        max: number;
+        p50: number;
+        p97_5: number;
+        p99: number;
+    };
+    throughput: {
+        average: number;
+    };
+    errors: number;
+};
+export type ArtillerySummary = {
+    min: number;
+    max: number;
+    count: number;
+    mean: number;
+    p50: number;
+    median: number;
+    p75: number;
+    p90: number;
+    p95: number;
+    p99: number;
+    p999: number;
+};
+export type ArtilleryResult = {
+    aggregate: {
+        counters: Record<string, number | undefined>;
+        rates: Record<string, number | undefined>;
+        firstMetricAt: number;
+        lastMetricAt: number;
+        summaries: Record<string, ArtillerySummary>;
+        histograms: Record<string, ArtillerySummary>;
+    };
+    intermediate?: Array<{
+        counters: Record<string, number>;
+        rates: Record<string, number | null | undefined>;
+        period?: string;
+        summaries?: Record<string, ArtillerySummary>;
+        histograms?: Record<string, ArtillerySummary>;
+    }>;
+};
+export type BuildMetrics = ProcessMetrics & {
+    buildTimeSec: number;
+    bundle?: BundleSize;
+};
+export type LoadMetrics = ProcessMetrics & {
+    durationSec?: number;
+    responseTimeAvg?: number;
+    responseTimeMin?: number;
+    responseTimeMax?: number;
+    responseTimeP50?: number;
+    responseTimeP95?: number;
+    responseTimeP99?: number;
+    requestsPerSecond?: number;
+    errorRate?: number;
+    autocannon?: AutocannonResult;
+    artillery?: ArtilleryResult;
+};
+export type PerfTargetResult = {
+    id: string;
+    label: string;
+    build: BuildMetrics;
+    load?: LoadMetrics;
+};
+export type SpawnSpec = {
+    command: string;
+    args?: string[];
+    cwd?: string;
+    env?: Record<string, string>;
+};
+export type PerfTargetBuild = SpawnSpec & {
+    /** Filter stdout lines to log (default: high-signal only) */
+    logFilter?: (line: string) => boolean;
+};
+export type PerfTargetStart = SpawnSpec & {
+    port: number;
+    host?: string;
+    readyPath?: string;
+    readyTimeoutMs?: number;
+};
+export type PerfTargetLoad = {
+    /** Paths for documentation / future multi-url; autocannon hits base URL */
+    paths?: string[];
+    /** `true` = defaults; object = overrides. Omitted = skip autocannon. */
+    autocannon?: boolean | {
+        connections?: number;
+        durationSec?: number;
+    };
+    artillery?: {
+        config: string;
+    };
+};
+export type PerfTargetBundle = {
+    /** Absolute or root-relative dirs to walk after build */
+    dirs: string[];
+    classify?: (absPath: string) => BundleClass;
+};
+export type PerfTarget = {
+    id: string;
+    label?: string;
+    root: string;
+    build: PerfTargetBuild;
+    start: PerfTargetStart;
+    load?: PerfTargetLoad;
+    bundle?: PerfTargetBundle;
+};
+export type PerfReporterContext = {
+    suite: PerfSuite;
+    results: PerfTargetResult[];
+    runs: number;
+    skipLoad: boolean;
+};
+export type PerfReporter = {
+    name: string;
+    onStart?: (suite: PerfSuite) => void | Promise<void>;
+    onTarget?: (result: PerfTargetResult) => void | Promise<void>;
+    onEnd?: (ctx: PerfReporterContext) => void | Promise<void>;
+};
+export type PerfThresholds = {
+    buildTimeSec?: number;
+    maxMemoryMb?: number;
+    requestsPerSecond?: number;
+    responseTimeP95?: number;
+    errorRate?: number;
+};
+export type PerfSuite = {
+    /** Absolute or cwd-relative output for JSON / temp load artifacts */
+    artifactsDir?: string;
+    runs?: number;
+    skipLoad?: boolean;
+    coolDownMs?: number;
+    targets: PerfTarget[];
+    beforeAll?: (suite: PerfSuite) => void | Promise<void>;
+    beforeTarget?: (target: PerfTarget) => void | Promise<void>;
+    afterTarget?: (target: PerfTarget, result: PerfTargetResult) => void | Promise<void>;
+    reporters?: PerfReporter[];
+    thresholds?: PerfThresholds;
+    /** Select subset by id or label prefix */
+    only?: string | string[];
+};
+export type RunPerfOptions = {
+    runs?: number;
+    skipLoad?: boolean;
+    only?: string | string[];
+    json?: boolean;
+};
+//# 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":"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"}

package/dist/types.mjs

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@untestutils/perf",
+  "version": "0.5.0",
+  "description": "Build + load performance harness for recipe/fixture targets",
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "default": "./dist/index.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "pathe": "^2.0.3",
+    "@untestutils/core": "0.5.0"
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.1",
+    "publint": "^0.3.24",
+    "typescript": "^6.0.3",
+    "obuild": "^0.4.40"
+  },
+  "peerDependencies": {
+    "artillery": "*",
+    "autocannon": "*"
+  },
+  "peerDependenciesMeta": {
+    "autocannon": {
+      "optional": true
+    },
+    "artillery": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "MIT",
+  "homepage": "https://s00d.github.io/untestutils/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/s00d/untestutils.git",
+    "directory": "packages/perf"
+  },
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "build": "obuild && tsc -p tsconfig.build.json",
+    "publint": "publint --strict"
+  }
+}