feat: initial implementation of generic type-safe dispatcher with middleware support

- Adds Registry and SealedRegistry types for handler registration and dispatch
- Supports type-safe generic handlers via Go generics
- Includes composable Middleware and MiddlewareFunc pattern
- Zero allocations on dispatch (steady state)
- SealedRegistry is lock-free and concurrency-safe

Author: IAmRadek

.github/workflows/go-quality.yml

@@ -0,0 +1,51 @@
+name: Go Quality Checks
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  quality-checks:
+    name: Code Quality
+    runs-on: ubuntu-latest
+    steps:
+      - name: Set up Go
+        uses: actions/setup-go@v4
+        with:
+          go-version: 1.24
+          cache: true
+
+      - name: Check out code
+        uses: actions/checkout@v3
+
+      - name: Run golangci-lint
+        uses: golangci/golangci-lint-action@v8
+
+      - name: Run tests
+        run: |
+          go test -v ./...
+
+      - name: Install govulncheck
+        run: |
+          go install golang.org/x/vuln/cmd/govulncheck@latest
+
+      - name: Verify go.mod is tidy
+        run: |
+          go mod tidy
+          git diff --exit-code go.mod|| (echo "Please run 'go mod tidy' and commit the changes" && exit 1)
+
+      - name: Check formatting
+        run: |
+          go fmt ./...
+          git diff --exit-code || (echo "Please run 'go fmt ./...' and commit the changes" && exit 1)
+
+      - name: Run go vet
+        run: |
+          go vet ./...
+
+      - name: Run govulncheck
+        run: |
+          govulncheck ./...
+

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 struct0x
+Copyright (c) 2025 Radosław Dejnek
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -1 +1,173 @@
-# dispatcher
+# Dispatcher
+
+A high-performance, type-safe dispatcher for Go.
+
+[![Go Reference](https://pkg.go.dev/badge/github.com/struct0x/dispatcher.svg)](https://pkg.go.dev/github.com/struct0x/dispatcher)
+
+## Overview
+
+Dispatcher is a Go library that provides a fast and efficient way to route values to their appropriate handlers based on type.
+It's designed with performance in mind,
+offering both thread-safe and immutable variants with different performance characteristics.
+
+## Features
+
+- **Type Safety**: Compile-time type safety with generic handlers
+- **Zero Allocations**: Dispatch operations produce zero allocations in steady state
+- **High Performance**: Optimized for concurrent access patterns
+- **Middleware Support**: Chainable middleware for cross-cutting concerns
+- **Two Registry Types**:
+  - `Registry`: Thread-safe, dynamic registration
+  - `SealedRegistry`: Immutable, zero mutex overhead
+
+## Installation
+
+```bash
+go get github.com/struct0x/dispatcher
+```
+
+## Usage
+
+### Basic Example
+
+```go
+package main
+
+import (
+    "context"
+    "fmt"
+    "log"
+
+    "github.com/struct0x/dispatcher"
+)
+
+type UserCreated struct {
+    ID   int
+    Name string
+}
+
+type OrderPlaced struct {
+    OrderID string
+    Amount  float64
+}
+
+func main() {
+    // Create a new registry
+    reg := dispatcher.NewRegistry()
+
+    // Register handlers for different types
+    dispatcher.Register[UserCreated](reg, func(ctx context.Context, event UserCreated) error {
+        fmt.Printf("User created: %s (ID: %d)\n", event.Name, event.ID)
+        return nil
+    })
+
+    dispatcher.Register[OrderPlaced](reg, func(ctx context.Context, event OrderPlaced) error {
+        fmt.Printf("Order placed: %s for $%.2f\n", event.OrderID, event.Amount)
+        return nil
+    })
+
+    // Dispatch events
+    ctx := context.Background()
+
+    if err := dispatcher.Dispatch(reg, ctx, UserCreated{ID: 1, Name: "Alice"}); err != nil {
+        log.Fatal(err)
+    }
+
+    if err := dispatcher.Dispatch(reg, ctx, OrderPlaced{OrderID: "ORD-001", Amount: 99.99}); err != nil {
+        log.Fatal(err)
+    }
+}
+```
+
+### Using Middleware
+
+```go
+// Define middleware
+loggingMiddleware := func(next dispatcher.HandlerFunc[UserCreated]) dispatcher.HandlerFunc[UserCreated] {
+    return func(ctx context.Context, event UserCreated) error {
+        fmt.Printf("Processing user: %s\n", event.Name)
+        err := next(ctx, event)
+        fmt.Printf("Finished processing user: %s\n", event.Name)
+        return err
+    }
+}
+
+// Register with middleware
+dispatcher.Register[UserCreated](reg, handler, loggingMiddleware)
+```
+
+### Sealed Registry for Maximum Performance
+
+```go
+// After registering all handlers, seal the registry for better performance
+sealedReg := reg.Seal()
+
+// SealedRegistry has zero mutex overhead
+if err := dispatcher.Dispatch(sealedReg, ctx, UserCreated{ID: 2, Name: "Bob"}); err != nil {
+    log.Fatal(err)
+}
+```
+
+## Performance
+
+Dispatcher is optimized for high-performance scenarios:
+
+- **Zero Allocations**: Dispatch operations after initialization produce zero allocations
+- **Concurrent Safe**: `Registry` can be used safely across goroutines
+- **Sealed Optimization**: `SealedRegistry` eliminates all mutex overhead
+- **Benchmark Results** (Apple M2 Max):
+  - `Registry`:
+    - 1 CPU: 21.46 ns/op
+    - 4 CPU: 64.80 ns/op
+    - 8 CPU: 122.0 ns/op
+  - `SealedRegistry`:
+    - 1 CPU: 14.59 ns/op
+    - 4 CPU: 28.95 ns/op
+    - 8 CPU: 45.53 ns/op
+
+*Note: Performance may vary based on your system and workload. Run benchmarks on your target system for accurate measurements.*
+
+Run benchmarks with:
+```bash
+go test -bench=. -benchmem
+```
+
+## How It Works
+
+1. **Registration**: Handlers are registered for specific types using Go generics
+2. **Type Mapping**: Types are mapped to handlers using `reflecgt.Type` as keys
+3. **Dispatch**: Values are routed to appropriate handlers based on their runtime type
+4. **Middleware Chain**: Middleware is applied in the order provided during registration
+
+## API Reference
+
+### Core Types
+
+- `dispatcher.Registry`: Thread-safe registry for dynamic handler registration
+- `dispatcher.SealedRegistry`: Immutable registry with zero mutex overhead
+- `dispatcher.HandlerFunc[T]`: Type-safe handler function
+- `dispatcher.Middleware[T]`: Type-safe middleware function
+
+### Core Functions
+
+- `dispatcher.NewRegistry()`: Creates a new thread-safe registry
+- `dispatcher.Register[T](reg, handler, middleware...)`: Registers a handler for type T
+  - ⚠️ If called multiple times for the same type `T`, later registrations overwrite earlier ones.
+- `dispatcher.Dispatch(reg, ctx, value)`: Dispatches a value to its registered handler
+- `registry.Seal()`: Creates a sealed immutable copy of a registry
+
+## Use Cases
+
+- **Event-driven architectures**
+- **Message routing systems**
+- **Command handlers in CQRS**
+- **Plugin systems**
+- **Any scenario requiring type-based dispatch**
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.

bench_test.go

@@ -0,0 +1,59 @@
+package dispatcher_test
+
+import (
+	"context"
+	"runtime"
+	"sync/atomic"
+	"testing"
+
+	"github.com/struct0x/dispatcher"
+)
+
+type Foo struct {
+	ID   int
+	Name string
+}
+
+var reg = dispatcher.NewRegistry()
+var sealed *dispatcher.SealedRegistry
+
+var u64Sink uint64
+
+func init() {
+	dispatcher.Register[Foo](reg, func(ctx context.Context, foo Foo) error {
+		atomic.AddUint64(&u64Sink, uint64(1))
+		return nil
+	})
+
+	sealed = reg.Seal()
+}
+
+func BenchmarkDispatch(b *testing.B) {
+	ctx := b.Context()
+
+	b.SetParallelism(runtime.GOMAXPROCS(0))
+	b.ReportAllocs()
+	b.ResetTimer()
+
+	b.RunParallel(func(b *testing.PB) {
+		var localErr error
+		for b.Next() {
+			localErr = dispatcher.Dispatch(reg, ctx, Foo{ID: 123, Name: "Bench"})
+		}
+		_ = localErr
+	})
+}
+
+func BenchmarkDispatchSealed(b *testing.B) {
+	ctx := b.Context()
+
+	b.ReportAllocs()
+	b.ResetTimer()
+	b.RunParallel(func(b *testing.PB) {
+		var localErr error
+		for b.Next() {
+			localErr = dispatcher.Dispatch(sealed, ctx, Foo{ID: 123, Name: "Bench"})
+		}
+		_ = localErr
+	})
+}

dispatcher.go

@@ -0,0 +1,21 @@
+// Package dispatcher provides a generic, type-safe function dispatcher with optional middleware.
+// It enables runtime dispatching of values to registered handlers based on their concrete type.
+package dispatcher
+
+import (
+	"context"
+	"reflect"
+)
+
+type dispatcher interface {
+	call(p reflect.Type, ctx context.Context, v any) error
+}
+
+type handlerFuncAny func(ctx context.Context, val any) error
+
+// Dispatch dispatches the given value to a registered handler based on its concrete type.
+// It returns ErrHandlerNotFound if no handler is registered for the value's type.
+func Dispatch(disp dispatcher, ctx context.Context, v any) error {
+	typ := reflect.TypeOf(v)
+	return disp.call(typ, ctx, v)
+}