feat(bench): add comprehensive benchmarking system with CI/CD integration

- Add Vitest Bench benchmarks for performance tracking
- Create 4 benchmark suites: simple, complex, array, nested
- Add GitHub Actions workflow for automated benchmark execution
- Integrate github-action-benchmark for performance tracking
- Add benchmark documentation in reports/benchmarks-setup.md
- Update README with benchmark results
- Configure Vitest to output benchmark results as JSON
- Add npm scripts: bench, bench:watch
- Install tinybench dependency for benchmarking

Benchmark Results:
- Simple mapping: ~30M ops/sec (competitive with vanilla)
- Complex transformations: ~13M ops/sec
- Array operations: ~1M ops/sec (100 items)
- Deep nesting: ~2.5M ops/sec

Features:
- Automated execution on push and PR
- Performance regression alerts (150% threshold)
- Historical tracking and visualization
- Artifact storage (30 days retention)

Author: Isqanderm

.github/workflows/benchmark.yml

@@ -0,0 +1,65 @@
+name: Benchmark
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  deployments: write
+  pull-requests: write
+
+jobs:
+  benchmark:
+    name: Run Benchmarks
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build project
+        run: npm run build
+
+      - name: Run benchmarks
+        run: npm run bench
+
+      - name: Store benchmark result
+        uses: benchmark-action/github-action-benchmark@v1
+        with:
+          name: Vitest Benchmark
+          tool: 'benchmarkjs'
+          output-file-path: bench-results.json
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          auto-push: true
+          # Show alert with commit comment on detecting possible performance regression
+          alert-threshold: '150%'
+          comment-on-alert: true
+          fail-on-alert: false
+          alert-comment-cc-users: '@Isqanderm'
+          # Enable Job Summary for PRs
+          summary-always: true
+
+      - name: Upload benchmark results
+        uses: actions/upload-artifact@v4
+        with:
+          name: benchmark-results
+          path: bench-results.json
+          retention-days: 30
+

.gitignore

@@ -2,3 +2,4 @@
 node_modules
 coverage
 build
+bench-results.json

README.md

@@ -74,6 +74,17 @@ console.log(result); // { fullName: 'John Doe', isAdult: true }
 
 Performance of om-data-mapper is almost identical to a native, hand-written “vanilla” mapper—demonstrating near-native speeds even in “safe” mode. Enabling Unsafe Mode (useUnsafe: true) removes all try/catch overhead and pushes performance even higher.
 
+### Benchmark Results
+
+We use automated benchmarks to track performance across different scenarios:
+
+- **Simple Mapping**: ~30M ops/sec (competitive with vanilla)
+- **Complex Transformations**: ~13M ops/sec (with custom functions)
+- **Array Operations**: ~1M ops/sec (100 items)
+- **Deep Nesting**: ~2.4M ops/sec (4-level deep)
+
+All benchmarks run automatically on every commit via GitHub Actions. See [Benchmark Setup Guide](./reports/benchmarks-setup.md) for details.
+
 [![Benchmark Chart](https://raw.githubusercontent.com/Isqanderm/data-mapper/659ae4ac86f3a44bc16475867ad26efaa8dd6177/benchmarks/benckmarks.png)](https://raw.githubusercontent.com/Isqanderm/data-mapper/659ae4ac86f3a44bc16475867ad26efaa8dd6177/benchmarks/benckmarks.png)
 
 ## Features

bench/array.bench.ts

@@ -0,0 +1,45 @@
+import { bench, describe } from 'vitest';
+import { Mapper } from '../src';
+
+interface Item {
+  id: number;
+  name: string;
+  price: number;
+}
+
+interface ItemDTO {
+  itemId: number;
+  itemName: string;
+  cost: number;
+}
+
+const items: Item[] = Array.from({ length: 100 }, (_, i) => ({
+  id: i + 1,
+  name: `Item ${i + 1}`,
+  price: Math.random() * 100,
+}));
+
+const itemMapper = Mapper.create<Item, ItemDTO>({
+  itemId: 'id',
+  itemName: 'name',
+  cost: 'price',
+});
+
+function vanillaArrayMapper(items: Item[]): ItemDTO[] {
+  return items.map((item) => ({
+    itemId: item.id,
+    itemName: item.name,
+    cost: item.price,
+  }));
+}
+
+describe('Array Mapping Benchmark', () => {
+  bench('OmDataMapper - Map 100 items', () => {
+    items.map((item) => itemMapper.execute(item).result);
+  });
+
+  bench('Vanilla - Map 100 items', () => {
+    vanillaArrayMapper(items);
+  });
+});
+

bench/complex.bench.ts

@@ -0,0 +1,106 @@
+import { bench, describe } from 'vitest';
+import { Mapper } from '../src';
+
+interface ComplexSource {
+  id: number;
+  user: {
+    firstName: string;
+    lastName: string;
+    profile: {
+      age: number;
+      email: string;
+    };
+  };
+  orders: Array<{
+    orderId: number;
+    amount: number;
+    items: Array<{
+      productId: number;
+      quantity: number;
+    }>;
+  }>;
+  metadata: {
+    createdAt: string;
+    updatedAt: string;
+  };
+}
+
+interface ComplexTarget {
+  userId: number;
+  fullName: string;
+  age: number;
+  email: string;
+  orderIds: number[];
+  totalAmount: number;
+  productCount: number;
+  created: string;
+  updated: string;
+}
+
+const complexSourceData: ComplexSource = {
+  id: 1,
+  user: {
+    firstName: 'John',
+    lastName: 'Doe',
+    profile: {
+      age: 30,
+      email: 'john@example.com',
+    },
+  },
+  orders: [
+    {
+      orderId: 101,
+      amount: 250,
+      items: [
+        { productId: 1, quantity: 2 },
+        { productId: 2, quantity: 1 },
+      ],
+    },
+    {
+      orderId: 102,
+      amount: 150,
+      items: [{ productId: 3, quantity: 3 }],
+    },
+  ],
+  metadata: {
+    createdAt: '2024-01-01',
+    updatedAt: '2024-01-15',
+  },
+};
+
+const complexMapper = Mapper.create<ComplexSource, ComplexTarget>({
+  userId: 'id',
+  fullName: (src) => `${src.user.firstName} ${src.user.lastName}`,
+  age: 'user.profile.age',
+  email: 'user.profile.email',
+  orderIds: (src) => src.orders.map((o) => o.orderId),
+  totalAmount: (src) => src.orders.reduce((sum, o) => sum + o.amount, 0),
+  productCount: (src) => src.orders.reduce((sum, o) => sum + o.items.length, 0),
+  created: 'metadata.createdAt',
+  updated: 'metadata.updatedAt',
+});
+
+function vanillaComplexMapper(source: ComplexSource): ComplexTarget {
+  return {
+    userId: source.id,
+    fullName: `${source.user.firstName} ${source.user.lastName}`,
+    age: source.user.profile.age,
+    email: source.user.profile.email,
+    orderIds: source.orders.map((o) => o.orderId),
+    totalAmount: source.orders.reduce((sum, o) => sum + o.amount, 0),
+    productCount: source.orders.reduce((sum, o) => sum + o.items.length, 0),
+    created: source.metadata.createdAt,
+    updated: source.metadata.updatedAt,
+  };
+}
+
+describe('Complex Mapping Benchmark', () => {
+  bench('OmDataMapper - Complex mapping with transformers', () => {
+    complexMapper.execute(complexSourceData);
+  });
+
+  bench('Vanilla - Complex mapping with transformers', () => {
+    vanillaComplexMapper(complexSourceData);
+  });
+});
+

bench/nested.bench.ts

@@ -0,0 +1,72 @@
+import { bench, describe } from 'vitest';
+import { Mapper } from '../src';
+
+interface NestedSource {
+  level1: {
+    level2: {
+      level3: {
+        level4: {
+          value: string;
+          number: number;
+        };
+      };
+    };
+  };
+  array: Array<{
+    items: Array<{
+      data: string;
+    }>;
+  }>;
+}
+
+interface NestedTarget {
+  deepValue: string;
+  deepNumber: number;
+  flattenedData: string[];
+}
+
+const nestedSourceData: NestedSource = {
+  level1: {
+    level2: {
+      level3: {
+        level4: {
+          value: 'deep value',
+          number: 42,
+        },
+      },
+    },
+  },
+  array: [
+    {
+      items: [{ data: 'item1' }, { data: 'item2' }],
+    },
+    {
+      items: [{ data: 'item3' }],
+    },
+  ],
+};
+
+const nestedMapper = Mapper.create<NestedSource, NestedTarget>({
+  deepValue: 'level1.level2.level3.level4.value',
+  deepNumber: 'level1.level2.level3.level4.number',
+  flattenedData: (src) => src.array.flatMap((a) => a.items.map((i) => i.data)),
+});
+
+function vanillaNestedMapper(source: NestedSource): NestedTarget {
+  return {
+    deepValue: source.level1.level2.level3.level4.value,
+    deepNumber: source.level1.level2.level3.level4.number,
+    flattenedData: source.array.flatMap((a) => a.items.map((i) => i.data)),
+  };
+}
+
+describe('Nested Mapping Benchmark', () => {
+  bench('OmDataMapper - Deep nested access', () => {
+    nestedMapper.execute(nestedSourceData);
+  });
+
+  bench('Vanilla - Deep nested access', () => {
+    vanillaNestedMapper(nestedSourceData);
+  });
+});
+

bench/simple.bench.ts

@@ -0,0 +1,54 @@
+import { bench, describe } from 'vitest';
+import { Mapper } from '../src';
+
+interface Source {
+  id: number;
+  name: string;
+  details: {
+    age: number;
+    address: string;
+  };
+}
+
+interface Target {
+  userId: number;
+  fullName: string;
+  age: number;
+  location: string;
+}
+
+const sourceData: Source = {
+  id: 1,
+  name: 'John Doe',
+  details: {
+    age: 30,
+    address: '123 Main St',
+  },
+};
+
+const mapper = Mapper.create<Source, Target>({
+  userId: 'id',
+  fullName: 'name',
+  age: 'details.age',
+  location: 'details.address',
+});
+
+function vanillaMapper(source: Source): Target {
+  return {
+    userId: source.id,
+    fullName: source.name,
+    age: source.details.age,
+    location: source.details.address,
+  };
+}
+
+describe('Simple Mapping Benchmark', () => {
+  bench('OmDataMapper - Simple mapping', () => {
+    mapper.execute(sourceData);
+  });
+
+  bench('Vanilla - Simple mapping', () => {
+    vanillaMapper(sourceData);
+  });
+});
+