@laitszkin/apollo-toolkit 4.1.3 → 5.0.0

package/skills/design/references/module-boundary-adjustment.md

@@ -0,0 +1,126 @@
+# Module Boundary Adjustment (T3) — Patterns
+
+Changes that affect a module's public API, data contract, or cross-module coupling.
+Requires dedicated test coverage — define test strategy in CHECKLIST.md before implementing.
+
+## Extract Module from God Module
+
+A large module containing >2 distinct responsibilities is split along ownership or lifecycle boundaries.
+
+```yaml
+Before:
+  module: "order-service"
+  responsibilities: [payment, fulfillment, notification, audit]
+
+After:
+  module: "order-service"
+    responsibilities: [order lifecycle, payment orchestration]
+  module: "fulfillment-service"
+    responsibilities: [inventory check, shipping, tracking]
+  module: "notification-service"
+    responsibilities: [email, SMS, push for order events]
+```
+
+**Verification**:
+- Integration tests confirm cross-module interactions still produce the same business outcomes
+- Each new module has independent test coverage for its internal logic
+- Contracts between modules (events, data types) are versioned or explicit
+
+## Change to Cross-Module Data Contract
+
+Modifying the shape of data passed between modules — a field added, renamed, removed, or changed type.
+
+```typescript
+// Contract: events/order-fulfilled.ts
+// Before:
+interface OrderFulfilled {
+  orderId: string;
+  trackingNumber: string;
+  carrier: string;
+}
+
+// After:
+interface OrderFulfilled {
+  orderId: string;
+  trackingNumber: string;
+  carrier: 'fedex' | 'ups' | 'usps';  // narrowed from string
+  estimatedDelivery?: string;          // added optional field
+}
+```
+
+**Test obligations**:
+- Producer publishes all required fields
+- Consumer handles the new optional field gracefully (absence = backward compatible)
+- Consumer reject messages for invalid carrier values
+
+## Remodeling Invariant Enforcement
+
+An invariant previously enforced at the database or UI layer must move to the application module boundary.
+
+| Scenario | Approach |
+|---|---|
+| DB constraint moved to application | Add validation in service layer; dual-run until migration verified |
+| UI-only validation promoted to API | Add middleware guard; test both valid and invalid input |
+| Soft enforcement → hard enforcement | Roll out with logging first, then error-throwing after observation period |
+
+## Public API Signature Change
+
+A module's exported function, class, or type changes in a way that requires all callers to update.
+
+```typescript
+// Before:
+export function createUser(name: string, email: string, role: string): User;
+
+// After:
+export function createUser(params: CreateUserParams): User;
+// where CreateUserParams = { name: string; email: string; role: Role };
+```
+
+**Migration strategy** (choose one and document):
+1. **Deprecate-and-copy**: Old function marked `@deprecated` → new function added → callers migrate one by one → old function removed after N cycles
+2. **Shim layer**: A thin adapter maps new interface to old, or old to new, during a transition window
+3. **Flag gate**: Both implementations coexist behind a feature flag; toggle after callers are confirmed updated
+
+## Module-to-Event Boundary
+
+A direct RPC call between two modules migrates to event-driven communication.
+
+```typescript
+// Before: synchronous RPC
+// fulfillment.ts
+const notification = new NotificationService();
+notification.sendEmail(order.userEmail, 'Shipped');
+
+// After: event-driven
+// fulfillment.ts
+events.publish({ type: 'order.shipped', data: { orderId, userEmail } });
+// notification service subscribes to 'order.shipped' independently
+```
+
+**Test obligations**:
+- Integration test: publish event → assert subscriber executes expected side-effect
+- Contract test: event schema is agreed between publisher and subscriber
+- Resilience test: subscriber failure does not affect publisher health
+
+## Interface Extraction
+
+A class's public methods become an explicit interface to decouple callers from implementation.
+
+```typescript
+// Before:
+export class PaymentGateway {
+  async charge(amount: number, token: string) { ... }
+}
+
+// After:
+export interface PaymentProvider {
+  charge(amount: number, token: string): Promise<PaymentResult>;
+}
+export class StripeGateway implements PaymentProvider { ... }
+export class FakeGateway implements PaymentProvider { ... }  // for tests
+```
+
+**Verification**:
+- Unit tests pass against `FakeGateway`
+- Integration tests cover `StripeGateway` against sandbox
+- Existing callers are updated to depend on the interface, not the class

package/skills/design/references/module-internal-restructuring.md

@@ -0,0 +1,132 @@
+# Module-Internal Restructuring (T2) — Patterns
+
+Restructuring that crosses files but stays within the same module boundary.
+Existing integration tests validate behavior — include in the design's task decomposition.
+
+## Extract Shared Logic
+
+A utility or helper repeated across multiple files within the same module.
+
+```typescript
+// Before
+// file-a.ts: const formatDate = (d) => ...;
+// file-b.ts: const formatDate = (d) => ...;
+
+// After
+// shared/date.ts: export const formatDate = (d) => ...;
+// file-a.ts, file-b.ts: import { formatDate } from '../shared/date';
+```
+
+**Placement**: Put shared utilities at the lowest level that all consumers can import without crossing module boundaries.
+
+**Verify**: Integration tests pass; grep confirms all callers updated.
+
+## Consolidate Scattered State
+
+State of the same concept spread across multiple files in the module.
+
+```typescript
+// Before
+// config.ts — export const API_TIMEOUT = 5000;
+// constants.ts — export const DEFAULT_TIMEOUT = 5000;
+// settings.ts — const timeout = process.env.API_TIMEOUT ?? 5000;
+
+// After
+// config.ts — all timeout definitions in one place:
+//   export const API_TIMEOUT = process.env.API_TIMEOUT ?? 5000;
+```
+
+**Rule of thumb**: If changing one value means updating N files, the state is scattered.
+
+## Reorganize File Boundaries
+
+A single file has grown to contain multiple concerns; split along cohesion lines.
+
+| Symptom | Split Strategy |
+|---|---|
+| File has "// validation" and "// formatting" section blocks | One file per concern |
+| File exports 8+ unrelated functions | Group by what they operate on |
+| File contains both types and logic | Types → `types.ts`, logic → `logic.ts` |
+| File has >300 lines and covers >3 distinct error scenarios | Split by failure mode |
+
+**Naming convention**: `{concern}.ts`, not `{concern}Utils.ts` — the file is the home, not a utility drawer.
+
+## Extract Function Group
+
+Several functions share a common prefix or operate on the same sub-concept.
+
+```typescript
+// Before
+// order-validator.ts
+//   function validateLineItem(item) { ... }
+//   function validateShipping(addr) { ... }
+//   function validatePromo(code) { ... }
+
+// After
+// order-validator.ts — orchestrates validation
+// validation/line-item.ts — validateLineItem
+// validation/shipping.ts — validateShipping
+// validation/promo.ts — validatePromo
+```
+
+## Flatten Function Chain
+
+A → B → C → D where each is a single-caller delegation.
+
+```typescript
+// Before
+function handleRequest(req) { return validate(parse(req)); }
+function validate(data) { return checkSchema(data); }
+function checkSchema(data) { return schema.parse(data); }
+
+// After
+function handleRequest(req) { return schema.parse(req); }
+```
+
+**Skip if** the chain exists for testability (each function individually mockable) — that's a valid reason.
+
+## Migrate to Early Data Validation
+
+Input validation scattered across processing steps → consolidated at the module boundary.
+
+```typescript
+// Before
+function process(data) {
+  const parsed = parse(data);           // validates format
+  const enriched = enrich(parsed);      // validates completeness
+  const saved = save(enriched);         // validates constraints
+}
+
+// After
+function process(data) {
+  const validated = validate(data);     // single validation pass
+  return save(parse(enrich(validated)));
+}
+```
+
+## Standardize Error Handling
+
+Mixed error patterns (throwing, returning `null`, returning `Result` types) unified within the module.
+
+| Inconsistent | Standardized |
+|---|---|
+| Some functions throw, some return null | All return `Result<T, E>` or all throw |
+| Some validate with `assert`, some with `if...throw` | Uniform validation pattern |
+| Callers don't know which errors to handle | Documented error types per function group |
+
+## Remove Implicit Module Coupling
+
+Two files in the same module import internal symbols from each other's implementation files rather than going through the module's index/barrel.
+
+```typescript
+// Before
+// features/orders/fulfill.ts
+//   import { picker } from './internal/warehouse';
+
+// After
+// features/orders/index.ts re-exports warehouse's public API
+// features/orders/fulfill.ts
+//   import { picker } from '../orders';  // through barrel
+```
+
+**Verify**: No file in the module imports from another file's private path — all go through the module boundary.

package/skills/design/references/module-internal-simplification.md

@@ -0,0 +1,164 @@
+# Module-Internal Simplification (T1) — Patterns
+
+Simplifications confined to a single function or file that do not change the module's public API.
+Existing unit tests validate behavioral preservation — these are the safest refactorings.
+
+## Guard Clause Extraction
+
+Replace nested conditionals with early returns.
+
+```typescript
+// Before
+function processOrder(order) {
+  if (order) {
+    if (order.isPaid) {
+      if (!order.isCancelled) {
+        // main logic
+      }
+    }
+  }
+}
+
+// After
+function processOrder(order) {
+  if (!order) return;
+  if (!order.isPaid) return;
+  if (order.isCancelled) return;
+  // main logic
+}
+```
+
+**Test coverage**: All code paths already exercised by unit tests.
+**Verify**: `npm test -- --related <file>`
+
+## Dead Code Removal
+
+Remove unused exports, unreachable branches, and commented-out blocks.
+
+```typescript
+// Before
+export function legacyFormatter(data) { /* no callers found */ }
+function process() {
+  // if (experimental) { ... }  // commented out 6 months ago
+}
+
+// After
+// Remove legacyFormatter entirely
+function process() { /* clean body */ }
+```
+
+**Verify**: `grep -r "legacyFormatter" src/` confirms zero callers; tests still pass.
+
+## Predicate Simplification
+
+Collapse duplicated or tautological conditions.
+
+```typescript
+// Before
+if (user != null && user !== undefined && user.role != null) { ... }
+
+// After
+if (user?.role) { ... }
+```
+
+## Inline Redundant Variable
+
+A variable that exists solely to hold a single-use expression.
+
+```typescript
+// Before
+const now = Date.now();
+log(now);
+
+// After
+log(Date.now());
+```
+
+**Does not apply when** the variable name carries meaning that clarifies the expression.
+
+## Switch-to-Map / Switch-to-Polymorphism
+
+Replace long switch statements with lookup maps.
+
+```typescript
+// Before
+function format(type, value) {
+  switch (type) {
+    case 'date': return formatDate(value);
+    case 'currency': return formatCurrency(value);
+    case 'percent': return formatPercent(value);
+    default: return String(value);
+  }
+}
+
+// After
+const FORMATTERS = {
+  date: formatDate,
+  currency: formatCurrency,
+  percent: formatPercent,
+};
+function format(type, value) {
+  return (FORMATTERS[type] ?? String)(value);
+}
+```
+
+## Remove Redundant Branch
+
+When a branch body is identical to the fallback, merge.
+
+```typescript
+// Before
+function greet(name) {
+  if (name) {
+    return `Hello, ${name}!`;
+  }
+  return `Hello, world!`;
+}
+
+// After
+function greet(name) {
+  return `Hello, ${name || 'world'}!`;
+}
+```
+
+## Flatten Unnecessary Async
+
+A function declared `async` but containing no `await` calls.
+
+```typescript
+// Before
+async function getVersion() {
+  return pkg.version;
+}
+
+// After
+function getVersion() {
+  return pkg.version;
+}
+```
+
+**Skip if** the function is an interface/abstract override that must return a Promise for polymorphic consistency.
+
+## Merge Adjacent Operations
+
+Two sequential loops or filter-map chains over the same collection.
+
+```typescript
+// Before
+const active = users.filter(u => u.active);
+const names = active.map(u => u.name);
+
+// After
+const names = users.filter(u => u.active).map(u => u.name);
+```
+
+## Remove Accidental Complexity
+
+Extraneous indirection introduced by premature abstraction or framework boilerplate.
+
+| Anti-pattern | Refactored |
+|---|---|
+| Single-function class that holds no state | Convert to plain function |
+| Wrapper function that only adds logging | Inline logging at call site |
+| Factory that always produces the same concrete type | Use constructor directly |
+| Interface with exactly one implementation | Remove interface, keep implementation |