PL_IMPROVEMENTS

Pragmatica Core - Improvements Backlog

Scope

• Track library-level utilities that support this technology (aspects, helpers, docs). Business logic stays in app repos; aspects/utilities live in PL.

Aspect Primitives (decorators over Fn1<Out, In>)

• CompositeAspect
  • Compose multiple aspect decorators with explicit order; returns a single decorated Fn1.
  • Helpers: compose(listOf(aspects)), andThen(a, b), around(step, aspects…).
• TimeoutAspect
  • Result and Promise variants; per-attempt timeout when combined with Retry.
  • Policies: Duration, fail-fast vs fallback, deadline propagation.
• RetryAspect (exists; extend)
  • Backoff (exp/jitter), retry classifier, max attempts; per-attempt timeout interop.
  • Result/Promise parity; idempotency hint flag.
• CircuitBreakerAspect (exists; extend)
  • Result/Promise parity; standard metrics hooks; half-open strategy.
• RateLimitAspect
  • Token/leaky buckets; per-key limiting; async wait vs fail-fast.
• BulkheadAspect
  • Semaphore/queueing; queue length policy; backpressure signal.
• CacheAspect
  • Sync/async cache; key derivation; TTL/TTI; stampede protection.
• DeduplicationAspect
  • Idempotency-key based coalescing; window policy.
• MetricsAspect
  • RED metrics; low-cardinality labels (operation, useCase, step, outcome).
• LoggingAspect
  • Structured logs; correlation id propagation; success/failure summaries only.
• DeadlineAspect
  • Carry deadline through chain; convert to timeouts locally.
• CancellationAspect
  • Cancellation token; cooperative cancellation hooks for Promise.

Variant Strategy

• Some aspects should exist in two variants (Result and Promise) when both sync and async domains benefit (e.g., Metrics, Logging, Timeout in rare sync contexts).
• I/O‑specific aspects (e.g., Retry, CircuitBreaker, RateLimit, Bulkhead, Deadline, Cancellation) are Promise‑only by default.
• Option/T aspects are generally no‑ops unless purely observational (metrics/logging); prioritize Promise and Result surfaces first.

Core Utilities

• Aspect type
  • Decorator shape: Fn1<Out, In> -> Fn1<Out, In>, where Out ∈ {T, Option, Result, Promise}.
  • Provide Result/Promise helpers; Option/T aspects are no-ops unless purely observational (metrics/logging).
• Config strategy
  • Policies as records; allow static configs and Supplier per-call overrides.
• Error types
  • Standard technical Causes: Timeout, RateLimited, CircuitOpen, Cancelled.
• Promise integration
  • Ensure Promise.all works with decorated steps; docs for per-attempt vs global timeouts.
• Result utilities
  • Document CompositeCause accumulation; trace() integration with aspects.

Docs & Examples

• Usage patterns: withTimeout(policy, step), withRetry(policy, step), compose(aspects…).
• Recommended orderings: retry(with per-attempt timeout(step)); circuit-breaker outside; rate-limit outermost; metrics/logging outermost.
• Testing: aspects tested in isolation; business tests remain aspect-agnostic.

Open Questions

• Config discovery: local explicit policy vs environment (Context) injection.
• Idempotency: where to host utilities (dedup aspect vs domain pattern guidance).