chore: add benchmark framework with tatami-ng

README.md

@@ -1,3 +1,5 @@
+> **Part of [Tuulbelt](https://github.com/tuulbelt/tuulbelt)** — A collection of zero-dependency tools.
+
 # Structured Error Handler / `serr`
 
 [![Tests](https://github.com/tuulbelt/structured-error-handler/actions/workflows/test.yml/badge.svg)](https://github.com/tuulbelt/structured-error-handler/actions/workflows/test.yml)

benchmarks/index.bench.ts

@@ -0,0 +1,93 @@
+#!/usr/bin/env node --import tsx
+/**
+ * Structured Error Handler Benchmarks
+ *
+ * Measures performance of core operations using tatami-ng for statistical rigor.
+ *
+ * Run: npm run bench
+ *
+ * See: /docs/BENCHMARKING_STANDARDS.md
+ */
+
+import { bench, baseline, group, run } from 'tatami-ng';
+import { StructuredError, ErrorContext, toJSON, fromJSON } from '../src/index.ts';
+
+// Prevent dead code elimination
+let result: StructuredError | string | ErrorContext;
+
+// Sample data for benchmarking
+const simpleContext: ErrorContext = { operation: 'test' };
+const richContext: ErrorContext = {
+  operation: 'database.query',
+  userId: 'user-123',
+  requestId: 'req-456',
+  timestamp: Date.now(),
+  metadata: { table: 'users', query: 'SELECT * FROM users WHERE id = ?' },
+};
+
+// ============================================================================
+// Core Operations Benchmarks
+// ============================================================================
+
+group('Error Creation', () => {
+  baseline('create: simple error', () => {
+    result = new StructuredError('Something went wrong', 'GENERIC_ERROR');
+  });
+
+  bench('create: with simple context', () => {
+    result = new StructuredError('Operation failed', 'OP_FAILED', simpleContext);
+  });
+
+  bench('create: with rich context', () => {
+    result = new StructuredError('Database query failed', 'DB_ERROR', richContext);
+  });
+
+  bench('create: with cause chain', () => {
+    const cause = new Error('Connection timeout');
+    result = new StructuredError('Database error', 'DB_ERROR', richContext, cause);
+  });
+});
+
+group('Error Wrapping', () => {
+  const nativeError = new Error('Native error message');
+
+  baseline('wrap: native Error', () => {
+    result = StructuredError.wrap(nativeError);
+  });
+
+  bench('wrap: with context', () => {
+    result = StructuredError.wrap(nativeError, richContext);
+  });
+
+  bench('wrap: with code override', () => {
+    result = StructuredError.wrap(nativeError, richContext, 'WRAPPED_ERROR');
+  });
+});
+
+group('Serialization', () => {
+  const error = new StructuredError('Test error', 'TEST', richContext);
+
+  baseline('toJSON: serialize', () => {
+    result = toJSON(error);
+  });
+
+  bench('fromJSON: deserialize', () => {
+    const json = toJSON(error);
+    result = fromJSON(json);
+  });
+
+  bench('round-trip: serialize + deserialize', () => {
+    const json = toJSON(error);
+    result = fromJSON(json);
+  });
+});
+
+// ============================================================================
+// Run Benchmarks
+// ============================================================================
+
+await run({
+  units: false,
+  silent: false,
+  json: false,
+});

package.json

@@ -12,6 +12,7 @@
     "build": "tsc",
     "test": "node --import tsx --test test/index.test.ts",
     "test:watch": "node --import tsx --test --watch test/index.test.ts",
+    "bench": "node --import tsx benchmarks/index.bench.ts",
     "dogfood": "npm run dogfood:flaky && npm run dogfood:diff",
     "dogfood:flaky": "flaky --test 'npm test' --runs 10",
     "dogfood:diff": "npx tsx test/dogfood-diff.ts"
@@ -36,7 +37,8 @@
   },
   "devDependencies": {
     "@tuulbelt/test-flakiness-detector": "git+https://github.com/tuulbelt/test-flakiness-detector.git",
-    "@types/node": "^20.0.0",
+    "@types/node": "^20.19.27",
+    "tatami-ng": "^0.8.0",
     "tsx": "^4.7.0",
     "typescript": "^5.3.0"
   }