@schilling.mark.a/software-methodology 1.0.0

package/clean-code/references/behavioral-patterns.md

@@ -0,0 +1,329 @@
+# Behavioral Patterns
+
+Patterns for managing communication and responsibility between objects.
+
+---
+
+## Strategy
+
+**When to use:**
+- A family of algorithms exists, and any one can be selected at runtime
+- A class has a behavior that varies based on a condition, implemented as an if/else or switch
+- You want to isolate each algorithm's implementation in its own class
+
+**Smell that triggers it:**
+```
+class InvoicePrinter:
+  print(invoice):
+    if format == "pdf":
+      // 30 lines of PDF logic
+    elif format == "html":
+      // 25 lines of HTML logic
+    elif format == "csv":
+      // 20 lines of CSV logic        ← new format = edit this class
+```
+
+**Solution:**
+```
+interface PrintStrategy:
+  print(invoice): output
+
+class PDFPrintStrategy implements PrintStrategy:
+  print(invoice): // PDF logic
+
+class HTMLPrintStrategy implements PrintStrategy:
+  print(invoice): // HTML logic
+
+class InvoicePrinter:
+  constructor(strategy: PrintStrategy)
+  print(invoice): return this.strategy.print(invoice)
+
+// Swap strategy at runtime
+printer = new InvoicePrinter(new PDFPrintStrategy())
+printer.print(invoice)
+
+printer = new InvoicePrinter(new HTMLPrintStrategy())
+printer.print(invoice)
+```
+
+**Key insight:** Strategy is the most commonly needed behavioral pattern. Whenever you see a method with branching logic that selects between algorithms, Strategy is almost certainly the answer. New algorithm = new class, zero edits to existing code.
+
+---
+
+## Command
+
+**When to use:**
+- You need to encapsulate an action as an object
+- You need undo/redo capability
+- You need to queue, log, or sequence operations
+- You want to decouple the object that performs the action from the object that triggers it
+
+**Smell that triggers it:**
+- A UI button or API endpoint directly calls business logic
+- You need a history of operations (for undo, audit trail, or replay)
+- You need to schedule actions for later execution
+
+**Solution:**
+```
+interface Command:
+  execute()
+  undo()
+
+class AddLineItemCommand implements Command:
+  constructor(invoice, lineItem)
+  execute():
+    this.invoice.addLineItem(this.lineItem)
+  undo():
+    this.invoice.removeLineItem(this.lineItem)
+
+class ApplyDiscountCommand implements Command:
+  constructor(invoice, discount)
+  private previousDiscount: Discount
+
+  execute():
+    this.previousDiscount = this.invoice.getDiscount()
+    this.invoice.setDiscount(this.discount)
+  undo():
+    this.invoice.setDiscount(this.previousDiscount)
+
+// Command history enables undo
+class InvoiceEditor:
+  private history: Command[] = []
+
+  execute(command: Command):
+    command.execute()
+    this.history.push(command)
+
+  undo():
+    lastCommand = this.history.pop()
+    lastCommand.undo()
+
+// Usage
+editor.execute(new AddLineItemCommand(invoice, consulting))
+editor.execute(new ApplyDiscountCommand(invoice, tenPercent))
+editor.undo()  ← removes discount
+editor.undo()  ← removes line item
+```
+
+**Key insight:** Each command is a self-contained unit of work. The history stack makes undo trivial. The same pattern works for audit logging — just persist the commands instead of discarding them.
+
+---
+
+## Observer
+
+**When to use:**
+- An object's state change should notify one or more other objects
+- The number of interested parties is unknown or varies at runtime
+- You want loose coupling between the thing that changed and the things that react
+
+**Smell that triggers it:**
+- A method that directly calls multiple other systems after doing its work
+- Adding a new reaction to an event requires editing the source class
+
+**Solution:**
+```
+interface Observer:
+  update(event: Event)
+
+interface Observable:
+  subscribe(observer: Observer)
+  unsubscribe(observer: Observer)
+  notify(event: Event)
+
+class Invoice implements Observable:
+  private observers: Observer[] = []
+
+  subscribe(observer): this.observers.push(observer)
+  unsubscribe(observer): this.observers = this.observers.filter(o => o !== observer)
+
+  notify(event):
+    this.observers.forEach(o => o.update(event))
+
+  markPaid(transactionId):
+    this.status = "paid"
+    this.notify(new InvoicePaidEvent(this, transactionId))
+
+// Observers — each handles one concern
+class EmailNotifier implements Observer:
+  update(event):
+    if event is InvoicePaidEvent:
+      sendConfirmationEmail(event.invoice.customer)
+
+class AccountingSync implements Observer:
+  update(event):
+    if event is InvoicePaidEvent:
+      syncToAccountingSystem(event.invoice)
+
+class AuditLogger implements Observer:
+  update(event):
+    logEvent(event)
+
+// Wire up at startup
+invoice.subscribe(new EmailNotifier())
+invoice.subscribe(new AccountingSync())
+invoice.subscribe(new AuditLogger())
+```
+
+**Key insight:** `Invoice` knows nothing about email, accounting, or audit logging. New reaction = new observer class + wire it up. Zero changes to `Invoice`.
+
+---
+
+## State
+
+**When to use:**
+- An object's behavior changes based on its internal state
+- A large if/else or switch block checks state and branches behavior
+- State transitions have rules that should be enforced
+
+**Smell that triggers it:**
+```
+class Invoice:
+  pay():
+    if this.status == "draft":
+      throw Error("Cannot pay a draft")
+    if this.status == "paid":
+      throw Error("Already paid")
+    if this.status == "cancelled":
+      throw Error("Cannot pay cancelled invoice")
+    this.status = "paid"     ← state logic scattered through every method
+```
+
+**Solution:**
+```
+interface InvoiceState:
+  pay(invoice)
+  cancel(invoice)
+  send(invoice)
+
+class DraftState implements InvoiceState:
+  pay(invoice): throw Error("Finalize the invoice before payment")
+  cancel(invoice): invoice.setState(new CancelledState())
+  send(invoice): invoice.setState(new SentState())
+
+class SentState implements InvoiceState:
+  pay(invoice): invoice.setState(new PaidState())
+  cancel(invoice): invoice.setState(new CancelledState())
+  send(invoice): throw Error("Already sent")
+
+class PaidState implements InvoiceState:
+  pay(invoice): throw Error("Already paid")
+  cancel(invoice): throw Error("Cannot cancel a paid invoice")
+  send(invoice): throw Error("Already paid")
+
+class CancelledState implements InvoiceState:
+  pay(invoice): throw Error("Cannot pay a cancelled invoice")
+  cancel(invoice): throw Error("Already cancelled")
+  send(invoice): throw Error("Cannot send a cancelled invoice")
+
+class Invoice:
+  private state: InvoiceState = new DraftState()
+  setState(state): this.state = state
+  pay(): this.state.pay(this)         ← delegates entirely to state object
+  cancel(): this.state.cancel(this)
+  send(): this.state.send(this)
+```
+
+**Key insight:** Each state is a class. Valid transitions are explicit. Invalid transitions throw immediately. Adding a new state means one new class. The `Invoice` class itself never changes.
+
+---
+
+## Chain of Responsibility
+
+**When to use:**
+- A request must pass through a sequence of handlers until one handles it
+- The set of handlers or their order may vary at runtime
+- Each handler decides whether to handle the request or pass it along
+
+**Smell that triggers it:**
+- A series of if/else checks where each check either handles the case or falls through to the next
+- Validation logic that applies multiple rules in sequence
+
+**Solution:**
+```
+abstract class ValidationHandler:
+  private next: ValidationHandler
+
+  setNext(handler: ValidationHandler): ValidationHandler
+    this.next = handler
+    return handler
+
+  validate(invoice): ValidationResult
+    if this.next:
+      return this.next.validate(invoice)
+    return ValidationResult.pass()
+
+class CustomerExistsHandler extends ValidationHandler:
+  validate(invoice):
+    if not customerExists(invoice.customerId):
+      return ValidationResult.fail("Customer not found")
+    return super.validate(invoice)      ← pass to next handler
+
+class LineItemsRequiredHandler extends ValidationHandler:
+  validate(invoice):
+    if invoice.lineItems.length == 0:
+      return ValidationResult.fail("At least one line item required")
+    return super.validate(invoice)
+
+class MaxAmountHandler extends ValidationHandler:
+  validate(invoice):
+    if invoice.total() > maxAllowed:
+      return ValidationResult.fail("Exceeds maximum amount")
+    return super.validate(invoice)
+
+// Wire the chain
+customerCheck = new CustomerExistsHandler()
+lineItemCheck = new LineItemsRequiredHandler()
+amountCheck = new MaxAmountHandler()
+
+customerCheck.setNext(lineItemCheck).setNext(amountCheck)
+
+// Validate — passes through chain until failure or all pass
+result = customerCheck.validate(invoice)
+```
+
+**Key insight:** Each handler has one responsibility. New validation rule = one new handler class, inserted into the chain. Order is controlled at wiring time.
+
+---
+
+## Template Method
+
+**When to use:**
+- Multiple classes share the same algorithm skeleton but differ in specific steps
+- You want to enforce an algorithm's structure while letting subclasses customize individual steps
+
+**Smell that triggers it:**
+- Copy-pasted methods across classes that differ only in one or two steps
+- An algorithm where the sequence of steps is fixed but the implementation of each step varies
+
+**Solution:**
+```
+abstract class InvoiceExporter:
+  // Template method — defines the algorithm skeleton. Final = cannot be overridden.
+  export(invoice): final
+    data = this.extractData(invoice)       ← step 1: subclass implements
+    validated = this.validate(data)        ← step 2: subclass implements
+    formatted = this.format(validated)     ← step 3: subclass implements
+    this.output(formatted)                 ← step 4: subclass implements
+    return formatted
+
+  abstract extractData(invoice): ExportData
+  abstract validate(data): ExportData
+  abstract format(data): string
+  abstract output(formatted): void
+
+class PDFExporter extends InvoiceExporter:
+  extractData(invoice): // PDF-specific extraction
+  validate(data): // PDF-specific validation
+  format(data): // PDF rendering
+  output(formatted): // Write to PDF file
+
+class CSVExporter extends InvoiceExporter:
+  extractData(invoice): // CSV-specific extraction
+  validate(data): // CSV-specific validation
+  format(data): // CSV formatting
+  output(formatted): // Write to CSV file
+```
+
+**Key insight:** The algorithm sequence (extract → validate → format → output) is defined once in the base class. Each exporter only implements the steps. If the sequence needs to change, it changes in one place.
+
+**Note:** Template Method uses inheritance. If you find yourself wanting the same flexibility without inheritance, Strategy achieves the same result with composition — generally preferred in modern code.

package/clean-code/references/creational-patterns.md

@@ -0,0 +1,197 @@
+# Creational Patterns
+
+Patterns for controlling how objects are created.
+
+---
+
+## Factory Method
+
+**When to use:**
+- Object creation logic is complex or varies based on a condition
+- You need to decouple the caller from the concrete class being created
+- A new type of object can be added without changing the creation site
+
+**Smell that triggers it:**
+```
+if type == "pdf":
+  doc = new PDFExporter()
+elif type == "csv":
+  doc = new CSVExporter()
+elif type == "xlsx":            ← new type = edit this block
+  doc = new XLSXExporter()
+```
+
+**Solution:**
+```
+interface Exporter:
+  export(data)
+
+class ExporterFactory:
+  static create(type: string): Exporter
+    registry = { "pdf": PDFExporter, "csv": CSVExporter, "xlsx": XLSXExporter }
+    return new registry[type]()
+
+// Usage — caller knows nothing about concrete types
+exporter = ExporterFactory.create(requestedFormat)
+exporter.export(invoiceData)
+```
+
+**Key insight:** Adding a new format means adding a new class and registering it. The calling code never changes.
+
+---
+
+## Abstract Factory
+
+**When to use:**
+- You need to create families of related objects that must be used together
+- The system should be independent of how its products are created
+- A "theme" or "variant" determines which set of objects is created
+
+**Smell that triggers it:**
+- Multiple factory methods that always get called together
+- Objects that must be consistent with each other (e.g., a UI theme where button, input, and modal must all match)
+
+**Solution:**
+```
+interface UIFactory:
+  createButton(): Button
+  createInput(): Input
+  createModal(): Modal
+
+class DarkThemeFactory implements UIFactory:
+  createButton(): return new DarkButton()
+  createInput(): return new DarkInput()
+  createModal(): return new DarkModal()
+
+class LightThemeFactory implements UIFactory:
+  createButton(): return new LightButton()
+  createInput(): return new LightInput()
+  createModal(): return new LightModal()
+
+// App receives a factory — knows nothing about theme internals
+class App:
+  constructor(factory: UIFactory)
+    this.button = factory.createButton()
+    this.input = factory.createInput()
+```
+
+**Key insight:** New theme = new factory class. The rest of the application is completely unaware.
+
+---
+
+## Builder
+
+**When to use:**
+- An object requires many parameters, most of which are optional
+- Construction requires a specific sequence of steps
+- The same construction process can produce different representations
+
+**Smell that triggers it:**
+```
+// Telescoping constructor — grows with every optional field
+invoice = new Invoice(customer, date, null, null, "standard", null, true)
+// What does the 5th null mean? Nobody knows.
+```
+
+**Solution:**
+```
+class InvoiceBuilder:
+  private invoice = new Invoice()
+
+  setCustomer(customer): this.invoice.customer = customer; return this
+  setDueDate(date): this.invoice.dueDate = date; return this
+  setTaxRule(rule): this.invoice.taxRule = rule; return this
+  setDiscount(discount): this.invoice.discount = discount; return this
+  markAsPriority(): this.invoice.priority = true; return this
+
+  build(): Invoice
+    validate(this.invoice)        ← enforce required fields here
+    return this.invoice
+
+// Usage — reads like a specification
+invoice = new InvoiceBuilder()
+  .setCustomer(acmeCorp)
+  .setDueDate(nextMonth)
+  .setTaxRule(standardRate)
+  .markAsPriority()
+  .build()
+```
+
+**Key insight:** Each step is named. Optional fields are simply omitted. Validation happens at `build()`, not scattered across constructors.
+
+**Test usage:** Builders are especially valuable in test fixtures. A `TestInvoiceBuilder` can set sensible defaults, and each test overrides only what it needs:
+```
+// Test only cares about discount behavior — everything else is default
+invoice = TestInvoiceBuilder.defaults().setDiscount(0.15).build()
+```
+
+---
+
+## Singleton
+
+**When to use:**
+- Exactly one instance must exist and be globally accessible
+- The instance controls access to a shared resource (config, logger, registry)
+
+**Smell that triggers it:**
+- Multiple places trying to create the same resource independently
+- Need for a single shared state across the application
+
+**Solution:**
+```
+class Configuration:
+  private static instance: Configuration
+  private settings: Map
+
+  private constructor():          ← private — nobody else can create one
+    this.settings = loadFromFile()
+
+  static getInstance(): Configuration
+    if not this.instance:
+      this.instance = new Configuration()
+    return this.instance
+
+  get(key: string): string
+    return this.settings[key]
+```
+
+**Warning:** Singleton is the most abused pattern. Do NOT use it for:
+- Database connections (use a connection pool instead)
+- Services that could benefit from multiple instances
+- Anything that makes unit testing harder
+
+If you find yourself reaching for Singleton to solve a dependency problem, DIP (from `references/solid.md`) is almost certainly the right answer instead.
+
+---
+
+## Prototype
+
+**When to use:**
+- Creating new objects is expensive and you have an existing instance to clone
+- The class hierarchy mirrors the variety of objects you want to create
+
+**Smell that triggers it:**
+- Object creation involves heavy initialization (network call, file read, complex calculation)
+- You need many similar objects that differ only slightly
+
+**Solution:**
+```
+interface Cloneable:
+  clone(): self
+
+class InvoiceTemplate implements Cloneable:
+  clone(): 
+    copy = new InvoiceTemplate()
+    copy.taxRule = this.taxRule
+    copy.paymentTerms = this.paymentTerms
+    copy.header = this.header
+    return copy
+
+// Usage — clone and customize, skip expensive setup
+template = standardInvoiceTemplate
+newInvoice = template.clone()
+newInvoice.setCustomer(acmeCorp)
+newInvoice.addLineItem(consultingService)
+```
+
+**Key insight:** Useful when you have template objects and need many variations quickly. Less common than Factory or Builder — apply only when creation cost is genuinely high.