Skip to content

feat(decorator): implemented the decorator pattern. #49

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
JerrettDavis merged 1 commit into from
Oct 7, 2025
Merged

feat(decorator): implemented the decorator pattern. #49

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
123 changes: 38 additions & 85 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -311,96 +311,49 @@ var registry = Prototype<string, User>.Create()
var guest = registry.Create("missing-key"); // falls back to default (guest)
```

---

## 📦 Patterns (Planned & In Progress)

PatternKit will grow to cover **Creational**, **Structural**, and **Behavioral** patterns with fluent, discoverable APIs:

| Category | Patterns ✓ = implemented |
| -------------- |----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **Creational** | [Factory](docs/patterns/creational/factory/factory.md) ✓ • [Composer](docs/patterns/creational/builder/composer.md) ✓ • [ChainBuilder](docs/patterns/creational/builder/chainbuilder.md) ✓ • [BranchBuilder](docs/patterns/creational/builder/chainbuilder.md) ✓ • [MutableBuilder](docs/patterns/creational/builder/mutablebuilder.md) ✓ • [Prototype](docs/patterns/creational/prototype/prototype.md) ✓ • [Singleton](docs/patterns/creational/singleton/singleton.md) ✓ |
| **Structural** | [Adapter](docs/patterns/structural/adapter/fluent-adapter.md) ✓ • [Bridge](docs/patterns/structural/bridge/bridge.md) ✓ • [Composite](docs/patterns/structural/composite/composite.md) ✓ • Decorator (planned) • Facade (planned) • Flyweight (planned) • Proxy (planned) |
| **Behavioral** | [Strategy](docs/patterns/behavioral/strategy/strategy.md) ✓ • [TryStrategy](docs/patterns/behavioral/strategy/trystrategy.md) ✓ • [ActionStrategy](docs/patterns/behavioral/strategy/actionstrategy.md) ✓ • [ActionChain](docs/patterns/behavioral/chain/actionchain.md) ✓ • [ResultChain](docs/patterns/behavioral/chain/resultchain.md) ✓ • [ReplayableSequence](docs/patterns/behavioral/iterator/replayablesequence.md) ✓ • [WindowSequence](docs/patterns/behavioral/iterator/windowsequence.md) ✓ • Command (planned) • Mediator (planned) • Memento (planned) • Observer (planned) • State (planned) • Template Method (planned) • Visitor (planned) |

Each pattern will ship with:

* A **fluent API** (`.When(...)`, `.Then(...)`, `.Finally(...)`, etc.)
* **Source-generated boilerplate** where possible.
* **DocFX-ready documentation** and **TinyBDD tests**.

---

## 🧪 Testing Philosophy

All patterns are validated with **[TinyBDD](https://github.com/jerrettdavis/TinyBdd)** and xUnit:

### Decorator (fluent wrapping & extension)
```csharp
[Feature("Strategy")]
public class StrategyTests : TinyBddXunitBase
{
[Scenario("Positive/negative classification")]
[Fact]
public async Task ClassificationWorks()
{
await Given("a strategy with three branches", BuildStrategy)
.When("executing with 5", s => s.Execute(5))
.Then("result should be 'positive'", r => r == "positive")
.AssertPassed();
}
}
```

We keep tests **behavior-driven**, **readable**, and **high coverage**.

---


## 💡 Design Goals

* **Declarative:** Favor expression-based and fluent APIs over imperative setup.
* **Minimalism:** Prefer single-responsibility types and low ceremony.
* **Performance:** Allocation-free handlers, `in` parameters, ahead-of-time friendly.
* **Discoverability:** IntelliSense-first APIs; easy to read, easy to write.
* **Testability:** TinyBDD integration and mocks built-in where applicable.

---

## 🛠 Requirements

* **.NET 9.0 or later** (we use `in` parameters and modern generic features).
* C# 12 features enabled (`readonly struct`, static lambdas, etc.).

---

## 📚 Documentation

Full API documentation is published with **DocFX** (coming soon).
Each type and member ships with XML docs, examples, and cross-links between patterns.

---

## 🤝 Contributing

We welcome issues, discussions, and PRs.
Focus areas:

* Adding new patterns (start with Behavioral for max impact)
* Improving fluent builder syntax and source generator coverage
* Writing TinyBDD test scenarios for edge cases
using PatternKit.Structural.Decorator;

// Add logging to any operation
var calculator = Decorator<int, int>.Create(static x => x * x)
.Around((x, next) => {
Console.WriteLine($"Input: {x}");
var result = next(x);
Console.WriteLine($"Output: {result}");
return result;
})
.Build();

---
var squared = calculator.Execute(7); // Logs: Input: 7, Output: 49

// Add caching
var cache = new Dictionary<int, int>();
var cachedOp = Decorator<int, int>.Create(x => ExpensiveComputation(x))
.Around((x, next) => {
if (cache.TryGetValue(x, out var cached))
return cached;
var result = next(x);
cache[x] = result;
return result;
})
.Build();

## 📄 License
// Chain multiple decorators: validation + transformation
var validated = Decorator<int, int>.Create(static x => 100 / x)
.Before(static x => x == 0 ? throw new ArgumentException("Cannot be zero") : x)
.After(static (input, result) => result + input)
.Build();

MIT — see [LICENSE](LICENSE) for details.
var output = validated.Execute(5); // (100 / 5) + 5 = 25
```

---

## ❤️ Inspiration

PatternKit is inspired by:
## 📚 Patterns Table
| Category | Patterns ✓ = implemented |
| -------------- |----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **Creational** | [Factory](docs/patterns/creational/factory/factory.md) ✓ • [Composer](docs/patterns/creational/builder/composer.md) ✓ • [ChainBuilder](docs/patterns/creational/builder/chainbuilder.md) ✓ • [BranchBuilder](docs/patterns/creational/builder/chainbuilder.md) ✓ • [MutableBuilder](docs/patterns/creational/builder/mutablebuilder.md) ✓ • [Prototype](docs/patterns/creational/prototype/prototype.md) ✓ • [Singleton](docs/patterns/creational/singleton/singleton.md) ✓ |
| **Structural** | [Adapter](docs/patterns/structural/adapter/fluent-adapter.md) ✓ • [Bridge](docs/patterns/structural/bridge/bridge.md) ✓ • [Composite](docs/patterns/structural/composite/composite.md) ✓ • [Decorator](docs/patterns/structural/decorator/decorator.md) ✓ • Facade (planned) • Flyweight (planned) • Proxy (planned) |
| **Behavioral** | [Strategy](docs/patterns/behavioral/strategy/strategy.md) ✓ • [TryStrategy](docs/patterns/behavioral/strategy/trystrategy.md) ✓ • [ActionStrategy](docs/patterns/behavioral/strategy/actionstrategy.md) ✓ • [ActionChain](docs/patterns/behavioral/chain/actionchain.md) ✓ • [ResultChain](docs/patterns/behavioral/chain/resultchain.md) ✓ • [ReplayableSequence](docs/patterns/behavioral/iterator/replayablesequence.md) ✓ • [WindowSequence](docs/patterns/behavioral/iterator/windowsequence.md) ✓ • Command (planned) • Mediator (planned) • Memento (planned) • Observer (planned) • State (planned) • Template Method (planned) • Visitor (planned) |

* The **Gang of Four** design patterns
* Fluent APIs from **ASP.NET Core**, **System.Linq**, and modern libraries
* The desire to make patterns **readable**, **performant**, and **fun** to use in 2025+
12 changes: 8 additions & 4 deletions docs/examples/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,19 +2,20 @@

Welcome! This section collects small, focused demos that show **how to compose behaviors with PatternKit**—without sprawling frameworks, if/else ladders, or tangled control flow. Each demo is production-shaped, tiny, and easy to lift into your own code.

## What you’ll see
## What you'll see

* **First-match-wins strategies** for branching without `if` chains.
* **Branchless action chains** for rule packs (logging, pre-auth, discounts, tax).
* **Fluent decorators** for layering functionality (tax, discounts, rounding, logging) without inheritance.
* **Pipelines** built declaratively and tested end-to-end.
* **Config-driven composition** (DI + `IOptions`) so ops can re-order rules without redeploys.
* **Strategy-based coercion** for turning “whatever came in” into the types you actually want.
* **Strategy-based coercion** for turning "whatever came in" into the types you actually want.
* **Ultra-minimal HTTP routing** to illustrate middleware vs. routes vs. negotiation.

## Demos in this section

* **Composed, Preference-Aware Notification Strategy (Email/SMS/Push/IM)**
Shows how to layer a user’s channel preferences, failover, and throttling into a composable **Strategy** without `switch`es. Good template for “try X, else Y” flows (alerts, KYC, etc.).
Shows how to layer a user's channel preferences, failover, and throttling into a composable **Strategy** without `switch`es. Good template for "try X, else Y" flows (alerts, KYC, etc.).

* **Auth & Logging Chain**
A tiny `ActionChain<HttpRequest>` showing **request ID logging**, an **auth short-circuit** for `/admin/*`, and the subtleties of **`.ThenContinue` vs `.ThenStop` vs `Finally`** (strict-stop semantics by default).
Expand All @@ -29,7 +30,10 @@ Welcome! This section collects small, focused demos that show **how to compose b
Same business shape as above, but wired via DI + `IOptions<PipelineOptions>`. Discounts/rounding/tenders are discovered and **ordered from config**, making the pipeline operationally tunable.

* **Minimal Web Request Router**
A tiny “API gateway” that separates **first-match middleware** (side effects/logging/auth) from **first-match routes** and **content negotiation**. A crisp example of Strategy patterns in an HTTP-ish setting.
A tiny "API gateway" that separates **first-match middleware** (side effects/logging/auth) from **first-match routes** and **content negotiation**. A crisp example of Strategy patterns in an HTTP-ish setting.

* **Payment Processor — Fluent Decorator Pattern for Point of Sale**
Demonstrates the **Decorator** pattern for building flexible payment processors. Shows how to layer tax calculation, promotional discounts, loyalty programs, employee benefits, and rounding strategies on a base processor—**no inheritance hierarchies**. Includes five real-world processors (simple, retail, e-commerce, cash register, birthday special) with full test coverage. Perfect for understanding decorator execution order and composition patterns.

## How to run

Expand Down
Loading
Loading