Skip to content

Latest commit

 

History

History
307 lines (252 loc) · 10.6 KB

CONSISTENCY_PLAN.md

File metadata and controls

307 lines (252 loc) · 10.6 KB

PatternKit API Consistency Plan

Executive Summary

This document outlines the gaps and inconsistencies found in the PatternKit library and the remediation plan to achieve 100% consistent, fluent, GoF-compliant implementations across all 23 design patterns.

Current State Analysis

Pattern Variant Matrix

Pattern Sync Result Sync Action Async Result Async Action in Params
Creational
Abstract Factory Yes N/A No N/A No
Builder Yes N/A No N/A No
Factory Yes N/A No N/A Yes
Prototype Yes N/A No N/A No
Singleton Yes N/A No N/A N/A
Structural
Adapter Yes No No No Yes
Bridge Yes No No No Yes
Composite Yes No No No Yes
Decorator Yes No No No NO
Facade Yes No No No Yes
Flyweight Yes N/A No N/A Yes
Proxy Yes No No No NO
Behavioral
Chain ResultChain ActionChain No No Yes
Command Yes N/A Yes N/A Yes
Interpreter Yes No No No No
Iterator/Flow Yes N/A Yes N/A N/A
Mediator Yes N/A Yes N/A Yes
Memento Yes N/A No N/A No
Observer Yes N/A Yes N/A Yes
State Yes N/A Yes N/A Yes
Strategy Yes Yes Yes No Yes
Template Yes No Yes No NO
TypeDispatcher Yes Yes Yes Yes Yes
Visitor (Fluent) Yes No No No N/A

Identified Issues

1. Missing Async Variants (High Priority)

  • Chain (both Action and Result)
  • Decorator
  • Proxy
  • Composite
  • Bridge
  • Adapter
  • Interpreter

2. Missing Action Variants (Medium Priority)

  • Template (ActionTemplate)
  • Decorator (ActionDecorator)
  • Proxy (ActionProxy)
  • Composite (ActionComposite)
  • Bridge (ActionBridge)
  • Adapter (ActionAdapter)
  • Interpreter (ActionInterpreter)
  • AsyncStrategy (AsyncActionStrategy)

3. Parameter Consistency Issues

  • Template<TContext, TResult> uses TContext context not in TContext
  • Decorator<TIn, TOut> uses TIn input not in TIn
  • Proxy<TIn, TOut> uses TIn input not in TIn

4. Method Naming Inconsistencies

  • TypeDispatcher uses Dispatch()
  • All other patterns use Execute()
  • Visitor uses Visit() (deprecated, should forward to TypeDispatcher.Dispatch)

5. Missing GoF-compliant Visitor

  • FluentVisitor needs completing (double dispatch with IVisitable)
  • Need async variants for FluentVisitor

Remediation Plan

Phase 1: API Consistency Fixes (Breaking Changes)

1.1 Standardize in Parameters

Update these patterns to use in parameters consistently:

  • Template: Execute(in TContext context)
  • Decorator: Execute(in TIn input)
  • Proxy: Execute(in TIn input)
  • Interpreter: Interpret(in IExpression, in TContext)

1.2 Standardize Method Names

Decision: Keep pattern-specific semantics where meaningful:

  • Execute() - Standard execution (Strategy, Chain, Template, etc.)
  • Dispatch() - Type-based dispatch (TypeDispatcher)
  • Visit() - True visitor pattern (FluentVisitor)
  • Interpret() - Expression evaluation (Interpreter)
  • Transition() - State changes (StateMachine)
  • Create() - Factory methods (Factory, AbstractFactory)

Phase 2: Missing Async Variants

Priority order (based on common async use cases):

2.1 High Priority

  • AsyncChain (both AsyncActionChain, AsyncResultChain)
  • AsyncDecorator
  • AsyncProxy
  • AsyncInterpreter

2.2 Medium Priority

  • AsyncComposite
  • AsyncBridge
  • AsyncAdapter

2.3 Low Priority (factory patterns rarely need async)

  • AsyncFactory (for async creation)
  • AsyncAbstractFactory

Phase 3: Missing Action Variants

3.1 High Priority

  • ActionTemplate / AsyncActionTemplate
  • ActionDecorator / AsyncActionDecorator
  • ActionProxy / AsyncActionProxy
  • AsyncActionStrategy

3.2 Medium Priority

  • ActionComposite / AsyncActionComposite
  • ActionBridge / AsyncActionBridge
  • ActionAdapter / AsyncActionAdapter
  • ActionInterpreter / AsyncActionInterpreter

Phase 4: FluentVisitor Completion

  • Complete FluentVisitor with full double-dispatch support
  • Add AsyncFluentVisitor
  • Add ActionFluentVisitor
  • Add AsyncActionFluentVisitor

Phase 5: Tests and Documentation

For each new variant:

  • Add comprehensive unit tests
  • Add BDD-style scenario tests
  • Update XML documentation
  • Add usage examples

Implementation Order

Iteration 1: Core Consistency

  1. Fix in parameter consistency in Template, Decorator, Proxy
  2. Add AsyncActionStrategy (completes Strategy family)
  3. Add ActionTemplate / AsyncActionTemplate
  4. Tests for above

Iteration 2: Async Chain & Decorator

  1. AsyncActionChain
  2. AsyncResultChain
  3. AsyncDecorator
  4. ActionDecorator / AsyncActionDecorator
  5. Tests for above

Iteration 3: Async Proxy & Interpreter

  1. AsyncProxy
  2. ActionProxy / AsyncActionProxy
  3. AsyncInterpreter
  4. ActionInterpreter / AsyncActionInterpreter
  5. Tests for above

Iteration 4: Structural Patterns

  1. AsyncComposite / ActionComposite / AsyncActionComposite
  2. AsyncBridge / ActionBridge / AsyncActionBridge
  3. AsyncAdapter / ActionAdapter / AsyncActionAdapter
  4. Tests for above

Iteration 5: FluentVisitor

  1. Complete FluentVisitor
  2. AsyncFluentVisitor
  3. ActionFluentVisitor / AsyncActionFluentVisitor
  4. Tests for above

Iteration 6: Final Polish

  1. API consistency review
  2. Documentation updates
  3. Example updates
  4. Final test pass

Design Principles (Applied Consistently)

  1. Fluent Builder Pattern: All patterns use .Create() → Builder → .Build()
  2. Immutability: Built instances are immutable and thread-safe
  3. Allocation-light: Minimize allocations on hot paths
  4. in Parameters: Use in for read-only struct parameters
  5. ref Parameters: Use ref only when mutation is required (e.g., StateMachine state)
  6. Delegates: Define pattern-specific delegate types for clarity
  7. Try Pattern: Provide TryXxx() variants that don't throw
  8. Async/Await: Use ValueTask for potentially synchronous completions
  9. Cancellation: Accept CancellationToken in async variants
  10. Naming: {Pattern}<T>, Action{Pattern}<T>, Async{Pattern}<T>, AsyncAction{Pattern}<T>

File Structure Convention

src/PatternKit.Core/
├── Behavioral/
│   ├── {Pattern}/
│   │   ├── {Pattern}.cs              # Sync result variant
│   │   ├── Action{Pattern}.cs        # Sync action variant
│   │   ├── Async{Pattern}.cs         # Async result variant
│   │   └── AsyncAction{Pattern}.cs   # Async action variant

Success Criteria

  • All 23 GoF patterns implemented
  • All patterns have consistent sync/async and result/action variants where applicable
  • All patterns use in parameters consistently (Note: Hooks need mutable context - correct design)
  • All patterns have fluent builder APIs
  • All patterns are immutable and thread-safe after Build()
  • All patterns have comprehensive tests
  • All patterns have XML documentation
  • All tests pass on net8.0, net9.0, net10.0

Completion Status (December 2025)

Completed Implementations

Behavioral Patterns - New Variants Added:

  • AsyncActionStrategy - Async action strategy pattern
  • ActionTemplate - Sync action template method pattern
  • AsyncActionTemplate - Async action template method pattern
  • AsyncResultChain - Async result chain (first-match-wins)
  • AsyncActionChain - Async action chain (middleware-style)
  • ActionDecorator - Sync action decorator
  • AsyncDecorator - Async result decorator
  • AsyncActionDecorator - Async action decorator
  • ActionProxy - Sync action proxy
  • AsyncProxy - Async result proxy
  • AsyncActionProxy - Async action proxy
  • AsyncInterpreter - Async expression interpreter
  • ActionInterpreter - Sync action interpreter
  • AsyncActionInterpreter - Async action interpreter

Structural Patterns - New Variants Added:

  • AsyncComposite - Async composite pattern
  • ActionComposite - Sync action composite
  • AsyncActionComposite - Async action composite
  • AsyncBridge - Async bridge pattern
  • ActionBridge - Sync action bridge
  • AsyncActionBridge - Async action bridge
  • AsyncAdapter - Async adapter pattern

Visitor Pattern - New Variants Added:

  • IAsyncVisitable - Interface for async visitable elements
  • IAsyncVisitor - Interface for async visitors
  • AsyncFluentVisitor - Async fluent visitor
  • AsyncFluentActionVisitor - Async action visitor

Test Summary

  • Total Tests: 1,579 tests (344 PatternKit.Tests × 3 frameworks + 21 Generator.Tests × 3 + 167 Examples.Tests × 3)
  • All Passing: net8.0, net9.0, net10.0

Files Created

src/PatternKit.Core/Behavioral/Strategy/AsyncActionStrategy.cs
src/PatternKit.Core/Behavioral/Template/ActionTemplate.cs
src/PatternKit.Core/Behavioral/Template/AsyncActionTemplate.cs
src/PatternKit.Core/Behavioral/Chain/AsyncResultChain.cs
src/PatternKit.Core/Behavioral/Chain/AsyncActionChain.cs
src/PatternKit.Core/Structural/Decorator/ActionDecorator.cs
src/PatternKit.Core/Structural/Decorator/AsyncDecorator.cs
src/PatternKit.Core/Structural/Decorator/AsyncActionDecorator.cs
src/PatternKit.Core/Structural/Proxy/ActionProxy.cs
src/PatternKit.Core/Structural/Proxy/AsyncProxy.cs
src/PatternKit.Core/Structural/Proxy/AsyncActionProxy.cs
src/PatternKit.Core/Behavioral/Interpreter/AsyncInterpreter.cs
src/PatternKit.Core/Behavioral/Interpreter/ActionInterpreter.cs
src/PatternKit.Core/Behavioral/Interpreter/AsyncActionInterpreter.cs
src/PatternKit.Core/Structural/Composite/AsyncComposite.cs
src/PatternKit.Core/Structural/Composite/ActionComposite.cs
src/PatternKit.Core/Structural/Composite/AsyncActionComposite.cs
src/PatternKit.Core/Structural/Bridge/AsyncBridge.cs
src/PatternKit.Core/Structural/Bridge/ActionBridge.cs
src/PatternKit.Core/Structural/Bridge/AsyncActionBridge.cs
src/PatternKit.Core/Structural/Adapter/AsyncAdapter.cs
src/PatternKit.Core/Behavioral/Visitor/IAsyncVisitable.cs
src/PatternKit.Core/Behavioral/Visitor/IAsyncVisitor.cs
src/PatternKit.Core/Behavioral/Visitor/AsyncFluentVisitor.cs

Test Files Added

test/PatternKit.Tests/Behavioral/Strategy/AsyncActionStrategyTests.cs
test/PatternKit.Tests/Behavioral/Interpreter/AsyncInterpreterTests.cs
test/PatternKit.Tests/Structural/AsyncCompositeTests.cs
test/PatternKit.Tests/Structural/AsyncBridgeTests.cs