npm - @girardmedia/bootspring - Versions diffs - 3.3.2 → 3.4.0 - Mend

@girardmedia/bootspring 3.3.2 → 3.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (171) hide show

package/assets/agents/accessibility-auditor.md +39 -0
package/assets/agents/api-designer.md +40 -0
package/assets/agents/auth-implementer.md +64 -0
package/assets/agents/bug-hunter.md +42 -0
package/assets/agents/bundle-analyzer.md +40 -0
package/assets/agents/cache-optimizer.md +55 -0
package/assets/agents/changelog-writer.md +55 -0
package/assets/agents/ci-cd-builder.md +40 -0
package/assets/agents/code-explainer.md +39 -0
package/assets/agents/code-reviewer.md +39 -0
package/assets/agents/cost-optimizer.md +57 -0
package/assets/agents/cron-scheduler.md +51 -0
package/assets/agents/data-seeder.md +56 -0
package/assets/agents/database-architect.md +40 -0
package/assets/agents/dependency-updater.md +40 -0
package/assets/agents/deploy-checker.md +40 -0
package/assets/agents/docker-optimizer.md +40 -0
package/assets/agents/documentation-writer.md +40 -0
package/assets/agents/email-builder.md +55 -0
package/assets/agents/env-setup.md +40 -0
package/assets/agents/error-handler.md +40 -0
package/assets/agents/eslint-fixer.md +46 -0
package/assets/agents/feature-flagger.md +69 -0
package/assets/agents/git-detective.md +39 -0
package/assets/agents/graphql-builder.md +60 -0
package/assets/agents/incident-responder.md +59 -0
package/assets/agents/log-analyzer.md +39 -0
package/assets/agents/migration-planner.md +41 -0
package/assets/agents/monorepo-navigator.md +39 -0
package/assets/agents/nextjs-expert.md +57 -0
package/assets/agents/notification-builder.md +56 -0
package/assets/agents/onboarding-guide.md +39 -0
package/assets/agents/performance-profiler.md +40 -0
package/assets/agents/prisma-expert.md +57 -0
package/assets/agents/rate-limiter.md +58 -0
package/assets/agents/react-expert.md +58 -0
package/assets/agents/refactorer.md +42 -0
package/assets/agents/regex-builder.md +46 -0
package/assets/agents/release-manager.md +40 -0
package/assets/agents/s3-manager.md +58 -0
package/assets/agents/schema-validator.md +40 -0
package/assets/agents/search-builder.md +62 -0
package/assets/agents/security-auditor.md +39 -0
package/assets/agents/sitemap-generator.md +53 -0
package/assets/agents/stripe-integrator.md +59 -0
package/assets/agents/tailwind-expert.md +55 -0
package/assets/agents/tech-debt-tracker.md +39 -0
package/assets/agents/test-writer.md +42 -0
package/assets/agents/type-fixer.md +45 -0
package/assets/agents/webhook-builder.md +54 -0
package/assets/rules/cpp.md +53 -0
package/assets/rules/css.md +52 -0
package/assets/rules/go.md +50 -0
package/assets/rules/html.md +52 -0
package/assets/rules/java.md +51 -0
package/assets/rules/kotlin.md +50 -0
package/assets/rules/php.md +51 -0
package/assets/rules/python.md +51 -0
package/assets/rules/ruby.md +51 -0
package/assets/rules/rust.md +49 -0
package/assets/rules/shell.md +52 -0
package/assets/rules/sql.md +49 -0
package/assets/rules/swift.md +50 -0
package/assets/rules/typescript.md +52 -0
package/assets/rules/yaml-json.md +51 -0
package/assets/skills/accessibility.md +210 -0
package/assets/skills/agent-patterns.md +387 -0
package/assets/skills/ai-integration.md +263 -0
package/assets/skills/animation-patterns.md +224 -0
package/assets/skills/api-design.md +218 -0
package/assets/skills/api-gateway.md +341 -0
package/assets/skills/api-versioning.md +226 -0
package/assets/skills/astro-patterns.md +233 -0
package/assets/skills/auth-patterns.md +248 -0
package/assets/skills/aws-patterns.md +171 -0
package/assets/skills/background-jobs.md +162 -0
package/assets/skills/browser-extensions.md +309 -0
package/assets/skills/caching-patterns.md +253 -0
package/assets/skills/ci-cd.md +251 -0
package/assets/skills/cli-development.md +296 -0
package/assets/skills/code-review.md +185 -0
package/assets/skills/cron-patterns.md +327 -0
package/assets/skills/data-fetching.md +231 -0
package/assets/skills/database-migrations.md +346 -0
package/assets/skills/database-patterns.md +219 -0
package/assets/skills/debugging.md +281 -0
package/assets/skills/design-system.md +289 -0
package/assets/skills/django-patterns.md +182 -0
package/assets/skills/docker-patterns.md +235 -0
package/assets/skills/e2e-testing.md +287 -0
package/assets/skills/edge-computing.md +268 -0
package/assets/skills/electron-patterns.md +266 -0
package/assets/skills/email-templates.md +206 -0
package/assets/skills/error-handling.md +265 -0
package/assets/skills/event-driven.md +232 -0
package/assets/skills/express-patterns.md +239 -0
package/assets/skills/fastapi-patterns.md +198 -0
package/assets/skills/feature-flags.md +212 -0
package/assets/skills/figma-to-code.md +298 -0
package/assets/skills/file-upload.md +228 -0
package/assets/skills/forms-patterns.md +264 -0
package/assets/skills/gcp-patterns.md +189 -0
package/assets/skills/git-workflow.md +187 -0
package/assets/skills/golang-patterns.md +185 -0
package/assets/skills/graphql-patterns.md +244 -0
package/assets/skills/i18n-patterns.md +172 -0
package/assets/skills/image-processing.md +350 -0
package/assets/skills/java-springboot.md +226 -0
package/assets/skills/kotlin-patterns.md +207 -0
package/assets/skills/kubernetes-patterns.md +326 -0
package/assets/skills/laravel-patterns.md +261 -0
package/assets/skills/llm-fine-tuning.md +335 -0
package/assets/skills/load-testing.md +303 -0
package/assets/skills/logging-observability.md +228 -0
package/assets/skills/markdown-processing.md +318 -0
package/assets/skills/mcp-server-patterns.md +292 -0
package/assets/skills/microservices.md +272 -0
package/assets/skills/migration-patterns.md +239 -0
package/assets/skills/mongodb-patterns.md +189 -0
package/assets/skills/monorepo-patterns.md +287 -0
package/assets/skills/nextjs-app-router.md +237 -0
package/assets/skills/notification-patterns.md +348 -0
package/assets/skills/oauth-patterns.md +246 -0
package/assets/skills/payment-integration.md +222 -0
package/assets/skills/pdf-generation.md +307 -0
package/assets/skills/performance-optimization.md +277 -0
package/assets/skills/php-patterns.md +210 -0
package/assets/skills/prisma-patterns.md +241 -0
package/assets/skills/prompt-engineering.md +193 -0
package/assets/skills/pwa-patterns.md +247 -0
package/assets/skills/python-patterns.md +158 -0
package/assets/skills/python-testing.md +172 -0
package/assets/skills/queue-patterns.md +295 -0
package/assets/skills/rag-patterns.md +159 -0
package/assets/skills/rate-limiting.md +319 -0
package/assets/skills/react-components.md +201 -0
package/assets/skills/react-native-patterns.md +299 -0
package/assets/skills/real-time-patterns.md +181 -0
package/assets/skills/redis-patterns.md +188 -0
package/assets/skills/refactoring.md +218 -0
package/assets/skills/regex-patterns.md +191 -0
package/assets/skills/remix-patterns.md +262 -0
package/assets/skills/responsive-design.md +199 -0
package/assets/skills/ruby-rails-patterns.md +178 -0
package/assets/skills/rust-patterns.md +211 -0
package/assets/skills/search-patterns.md +227 -0
package/assets/skills/security-hardening.md +237 -0
package/assets/skills/seo-patterns.md +179 -0
package/assets/skills/serverless-patterns.md +223 -0
package/assets/skills/sql-optimization.md +154 -0
package/assets/skills/state-management.md +254 -0
package/assets/skills/storybook-patterns.md +330 -0
package/assets/skills/svelte-patterns.md +258 -0
package/assets/skills/swift-patterns.md +227 -0
package/assets/skills/tailwind-patterns.md +272 -0
package/assets/skills/tdd-workflow.md +199 -0
package/assets/skills/terraform-patterns.md +270 -0
package/assets/skills/testing-react.md +240 -0
package/assets/skills/testing-vitest.md +232 -0
package/assets/skills/typescript-strict.md +159 -0
package/assets/skills/video-processing.md +340 -0
package/assets/skills/vue-patterns.md +247 -0
package/assets/skills/web-workers.md +327 -0
package/assets/skills/webhooks-patterns.md +283 -0
package/assets/skills/websocket-patterns.md +306 -0
package/dist/cli/index.js +941 -958
package/dist/core/index.d.ts +341 -11
package/dist/core.js +58 -95
package/dist/mcp/index.d.ts +33 -1
package/dist/mcp-server.js +177 -255
package/package.json +4 -1

package/assets/skills/email-templates.md ADDED Viewed

@@ -0,0 +1,206 @@
+---
+name: email-templates
+description: Email template patterns with MJML, inline styles, responsive emails, preview text, and testing across clients.
+---
+# Email Templates
+## When to Use
+Apply when building transactional or marketing emails. Email HTML is stuck in 2005 -- Outlook uses Word's rendering engine, Gmail strips `<style>` tags, and every client has different quirks. Use MJML to write maintainable markup that compiles to battle-tested HTML. Test in Litmus or Email on Acid before sending.
+## How It Works
+### MJML -- Write Emails Without Suffering
+MJML compiles to responsive, cross-client HTML:
+```xml
+<mjml>
+  <mj-head>
+    <mj-attributes>
+      <mj-all font-family="Helvetica, Arial, sans-serif" />
+      <mj-text font-size="16px" line-height="1.5" color="#374151" />
+    </mj-attributes>
+    <mj-preview>Your order #1234 has shipped</mj-preview>
+  </mj-head>
+  <mj-body background-color="#f9fafb">
+    <mj-section background-color="#ffffff" border-radius="8px" padding="32px">
+      <mj-column>
+        <mj-image src="https://example.com/logo.png" width="120px" alt="Logo" />
+        <mj-text font-size="24px" font-weight="700" padding-top="24px">
+          Your order has shipped!
+        </mj-text>
+        <mj-text>
+          Hi {{name}}, your order #{{orderId}} is on its way.
+          Expected delivery: {{deliveryDate}}.
+        </mj-text>
+        <mj-button background-color="#2563eb" color="#ffffff"
+          href="{{trackingUrl}}" border-radius="6px" font-size="16px">
+          Track Your Package
+        </mj-button>
+      </mj-column>
+    </mj-section>
+    <mj-section padding="16px">
+      <mj-column>
+        <mj-text font-size="12px" color="#9ca3af" align="center">
+          You received this because you placed an order at Example Store.
+          <a href="{{unsubscribeUrl}}">Unsubscribe</a>
+        </mj-text>
+      </mj-column>
+    </mj-section>
+  </mj-body>
+</mjml>
+```
+Compile with: `npx mjml input.mjml -o output.html`
+### React Email -- Component-Based Templates
+```tsx
+import {
+  Body, Container, Head, Heading, Html,
+  Preview, Section, Text, Button, Img,
+} from "@react-email/components";
+interface OrderShippedProps {
+  name: string;
+  orderId: string;
+  trackingUrl: string;
+}
+export function OrderShipped({ name, orderId, trackingUrl }: OrderShippedProps) {
+  return (
+    <Html>
+      <Head />
+      <Preview>Your order #{orderId} has shipped</Preview>
+      <Body style={{ backgroundColor: "#f9fafb", fontFamily: "Helvetica, Arial, sans-serif" }}>
+        <Container style={{ maxWidth: 600, margin: "0 auto", padding: 32 }}>
+          <Img src="https://example.com/logo.png" width={120} alt="Logo" />
+          <Heading style={{ fontSize: 24, marginTop: 24 }}>
+            Your order has shipped!
+          </Heading>
+          <Text style={{ fontSize: 16, lineHeight: 1.5, color: "#374151" }}>
+            Hi {name}, your order #{orderId} is on its way.
+          </Text>
+          <Section style={{ textAlign: "center", marginTop: 24 }}>
+            <Button
+              href={trackingUrl}
+              style={{
+                backgroundColor: "#2563eb",
+                color: "#ffffff",
+                padding: "12px 24px",
+                borderRadius: 6,
+                fontSize: 16,
+                textDecoration: "none",
+              }}
+            >
+              Track Your Package
+            </Button>
+          </Section>
+        </Container>
+      </Body>
+    </Html>
+  );
+}
+```
+### Sending with Nodemailer + Template Rendering
+```typescript
+import nodemailer from "nodemailer";
+import mjml2html from "mjml";
+import Handlebars from "handlebars";
+import { readFileSync } from "fs";
+const transporter = nodemailer.createTransport({
+  host: process.env.SMTP_HOST,
+  port: 587,
+  auth: { user: process.env.SMTP_USER, pass: process.env.SMTP_PASS },
+});
+async function sendOrderShipped(to: string, data: OrderData) {
+  const mjmlTemplate = readFileSync("templates/order-shipped.mjml", "utf-8");
+  const compiled = Handlebars.compile(mjmlTemplate);
+  const mjmlOutput = compiled(data);
+  const { html } = mjml2html(mjmlOutput);
+  await transporter.sendMail({
+    from: '"Example Store" <orders@example.com>',
+    to,
+    subject: `Your order #${data.orderId} has shipped`,
+    html,
+    text: `Hi ${data.name}, your order #${data.orderId} has shipped. Track it: ${data.trackingUrl}`,
+  });
+}
+```
+### Preview Text Hack
+The preview text appears in the inbox list. Control it, or clients will grab the first visible text:
+```html
+<!-- Preview text visible in inbox, hidden in email body -->
+<div style="display: none; max-height: 0; overflow: hidden;">
+  Your order #1234 has shipped -- arriving Thursday.
+  <!-- Pad with whitespace to prevent body text from appearing -->
+  &nbsp;&zwnj;&nbsp;&zwnj;&nbsp;&zwnj;&nbsp;&zwnj;&nbsp;&zwnj;
+</div>
+```
+### Dark Mode Support
+```html
+<style>
+  @media (prefers-color-scheme: dark) {
+    .email-body { background-color: #1f2937 !important; }
+    .email-text { color: #f3f4f6 !important; }
+    .email-card { background-color: #374151 !important; }
+  }
+</style>
+<!-- Fallback for clients that strip style tags -->
+<meta name="color-scheme" content="light dark" />
+<meta name="supported-color-schemes" content="light dark" />
+```
+### Testing Strategy
+```typescript
+import { render } from "@react-email/render";
+describe("OrderShipped email", () => {
+  it("renders with required props", () => {
+    const html = render(
+      <OrderShipped name="Alice" orderId="1234" trackingUrl="https://track.example.com/1234" />
+    );
+    expect(html).toContain("Your order has shipped");
+    expect(html).toContain("Alice");
+    expect(html).toContain("track.example.com/1234");
+  });
+  it("includes unsubscribe link", () => {
+    const html = render(<OrderShipped {...defaultProps} />);
+    expect(html).toContain("Unsubscribe");
+  });
+});
+```
+## Examples
+| Pattern | When | Result |
+|---------|------|--------|
+| MJML templates | Marketing emails, newsletters | Cross-client responsive |
+| React Email | Transactional, typed props | Component reuse, TypeScript |
+| Preview text | All emails | Control inbox preview line |
+| Dark mode meta | Modern clients | Respects user preference |
+| Plain text fallback | Accessibility, spam filters | Better deliverability |
+| Litmus/Email on Acid | Pre-send QA | Catch rendering bugs |
+## Checklist
+- [ ] Templates use MJML or React Email, not hand-written table HTML
+- [ ] Every email has a plain text fallback
+- [ ] Preview text is explicitly set, not auto-generated from body
+- [ ] CTA buttons use bulletproof button technique (not just `<a>`)
+- [ ] Images have alt text and explicit width/height
+- [ ] Unsubscribe link present in every marketing email (CAN-SPAM)
+- [ ] Dark mode handled with `prefers-color-scheme` and meta tags
+- [ ] Tested in Gmail, Outlook, Apple Mail, and Yahoo before launch

package/assets/skills/error-handling.md ADDED Viewed

@@ -0,0 +1,265 @@
+---
+name: error-handling
+description: Handle errors gracefully with Result types, retry logic, circuit breakers, and structured logging.
+---
+# Error Handling Patterns
+## When to Use
+Apply these patterns in every service, API, and CLI tool. The default — throwing
+exceptions and hoping a catch block somewhere handles them — leads to crashed
+processes, lost data, and unreadable logs. Explicit error handling is not
+overhead; it's how reliable software works.
+## How It Works
+### 1. Result Types — Errors as Values
+Make errors part of the return type so callers can't ignore them.
+```typescript
+type Result<T, E = Error> =
+  | { ok: true; value: T }
+  | { ok: false; error: E };
+function ok<T>(value: T): Result<T, never> {
+  return { ok: true, value };
+}
+function err<E>(error: E): Result<never, E> {
+  return { ok: false, error };
+}
+```
+Usage:
+```typescript
+function parseConfig(raw: string): Result<Config, ParseError> {
+  try {
+    const data = JSON.parse(raw);
+    if (!data.apiUrl) return err(new ParseError('Missing apiUrl'));
+    return ok(data as Config);
+  } catch {
+    return err(new ParseError('Invalid JSON'));
+  }
+}
+const result = parseConfig(input);
+if (!result.ok) {
+  logger.error('Config parse failed', { error: result.error.message });
+  process.exit(1);
+}
+// result.value is narrowed to Config here
+```
+### 2. Custom Error Classes
+Categorize errors so handlers can react differently to different failures.
+```typescript
+class AppError extends Error {
+  constructor(
+    message: string,
+    public readonly code: string,
+    public readonly statusCode: number = 500,
+    public readonly isOperational: boolean = true,
+  ) {
+    super(message);
+    this.name = this.constructor.name;
+  }
+}
+class NotFoundError extends AppError {
+  constructor(resource: string, id: string) {
+    super(`${resource} ${id} not found`, 'NOT_FOUND', 404);
+  }
+}
+class ValidationError extends AppError {
+  constructor(public readonly fields: Record<string, string>) {
+    super('Validation failed', 'VALIDATION_ERROR', 400);
+  }
+}
+class ExternalServiceError extends AppError {
+  constructor(service: string, cause?: Error) {
+    super(`${service} unavailable`, 'EXTERNAL_SERVICE_ERROR', 502, true);
+    this.cause = cause;
+  }
+}
+```
+### 3. Error Boundaries in Express
+Centralize error handling in one middleware.
+```typescript
+// Must be registered last, with 4 parameters
+app.use((err: Error, req: Request, res: Response, next: NextFunction) => {
+  if (err instanceof AppError && err.isOperational) {
+    logger.warn('Operational error', {
+      code: err.code,
+      message: err.message,
+      path: req.path,
+    });
+    return res.status(err.statusCode).json({
+      error: { code: err.code, message: err.message },
+    });
+  }
+  // Unexpected errors — log full stack, return generic message
+  logger.error('Unhandled error', {
+    error: err.message,
+    stack: err.stack,
+    path: req.path,
+  });
+  res.status(500).json({
+    error: { code: 'INTERNAL_ERROR', message: 'An unexpected error occurred' },
+  });
+});
+```
+### 4. Retry with Exponential Backoff
+Retry transient failures (network timeouts, rate limits) with increasing delays.
+```typescript
+async function retry<T>(
+  fn: () => Promise<T>,
+  options: { maxAttempts?: number; baseDelayMs?: number; maxDelayMs?: number } = {},
+): Promise<T> {
+  const { maxAttempts = 3, baseDelayMs = 200, maxDelayMs = 10000 } = options;
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    try {
+      return await fn();
+    } catch (error) {
+      if (attempt === maxAttempts) throw error;
+      const delay = Math.min(
+        baseDelayMs * Math.pow(2, attempt - 1) + Math.random() * 100,
+        maxDelayMs,
+      );
+      await new Promise((resolve) => setTimeout(resolve, delay));
+    }
+  }
+  throw new Error('Unreachable');
+}
+// Usage
+const data = await retry(() => fetchFromAPI('/users'), { maxAttempts: 3 });
+```
+Add jitter (the `Math.random()` part) to prevent thundering herds.
+### 5. Circuit Breaker
+Stop calling a failing service to let it recover.
+```typescript
+class CircuitBreaker {
+  private failures = 0;
+  private lastFailure = 0;
+  private state: 'closed' | 'open' | 'half-open' = 'closed';
+  constructor(
+    private readonly threshold: number = 5,
+    private readonly resetTimeMs: number = 30000,
+  ) {}
+  async call<T>(fn: () => Promise<T>): Promise<T> {
+    if (this.state === 'open') {
+      if (Date.now() - this.lastFailure > this.resetTimeMs) {
+        this.state = 'half-open';
+      } else {
+        throw new Error('Circuit breaker is open');
+      }
+    }
+    try {
+      const result = await fn();
+      this.onSuccess();
+      return result;
+    } catch (error) {
+      this.onFailure();
+      throw error;
+    }
+  }
+  private onSuccess() {
+    this.failures = 0;
+    this.state = 'closed';
+  }
+  private onFailure() {
+    this.failures++;
+    this.lastFailure = Date.now();
+    if (this.failures >= this.threshold) {
+      this.state = 'open';
+    }
+  }
+}
+const paymentBreaker = new CircuitBreaker(5, 30000);
+const charge = await paymentBreaker.call(() => stripe.charges.create(params));
+```
+### 6. Structured Logging
+Log machine-parseable JSON, not random strings.
+```typescript
+// Bad
+console.log(`User ${userId} failed to login: ${error.message}`);
+// Good
+logger.warn('Login failed', {
+  userId,
+  error: error.message,
+  code: error.code,
+  ip: req.ip,
+  timestamp: new Date().toISOString(),
+});
+```
+Use log levels consistently:
+| Level | Use |
+|-------|-----|
+| `error` | Unexpected failures requiring investigation |
+| `warn` | Expected failures (auth denied, validation) |
+| `info` | Significant business events (order created, deploy started) |
+| `debug` | Developer troubleshooting details (only in dev) |
+### 7. Graceful Shutdown
+```typescript
+process.on('SIGTERM', async () => {
+  logger.info('SIGTERM received, shutting down gracefully');
+  server.close();
+  await db.$disconnect();
+  await cache.quit();
+  process.exit(0);
+});
+```
+## Examples
+| Failure type | Pattern | Recovery |
+|-------------|---------|----------|
+| Invalid input | Validation error + 400 | Immediate feedback to caller |
+| Missing resource | Not found error + 404 | Caller adjusts request |
+| Network timeout | Retry with backoff | Auto-recover after delay |
+| Persistent outage | Circuit breaker | Fail fast, serve cached/degraded |
+| Unknown crash | Global error handler | Log, alert, restart |
+## Checklist
+- [ ] Functions that can fail return `Result<T, E>` or throw typed errors, never raw strings
+- [ ] Custom error classes include `code`, `statusCode`, and `isOperational`
+- [ ] Express has a centralized error middleware registered last
+- [ ] External calls use retry with exponential backoff and jitter
+- [ ] Critical dependencies have circuit breakers
+- [ ] All log output is structured JSON with consistent fields
+- [ ] Graceful shutdown handlers close connections before exiting
+- [ ] Production errors never leak stack traces or internal details to clients

package/assets/skills/event-driven.md ADDED Viewed

@@ -0,0 +1,232 @@
+---
+name: event-driven
+description: Event-driven architecture with pub/sub, event bus, CQRS, event sourcing, and dead letter queues.
+---
+# Event-Driven Architecture
+## When to Use
+Apply when services need to communicate without tight coupling, when you need audit trails of every state change, or when read and write workloads have different scaling needs. Event-driven architecture decouples producers from consumers, enabling independent scaling, temporal decoupling, and easier system evolution.
+## How It Works
+### In-Process Event Bus
+Start simple with a typed event emitter before reaching for message brokers:
+```typescript
+type EventHandler<T = unknown> = (payload: T) => void | Promise<void>;
+interface AppEvents {
+  "order.created": { orderId: string; userId: string; total: number };
+  "order.shipped": { orderId: string; trackingNumber: string };
+  "user.registered": { userId: string; email: string };
+}
+class TypedEventBus {
+  private handlers = new Map<string, EventHandler[]>();
+  on<K extends keyof AppEvents>(event: K, handler: EventHandler<AppEvents[K]>): void {
+    const list = this.handlers.get(event as string) ?? [];
+    list.push(handler as EventHandler);
+    this.handlers.set(event as string, list);
+  }
+  async emit<K extends keyof AppEvents>(event: K, payload: AppEvents[K]): Promise<void> {
+    const handlers = this.handlers.get(event as string) ?? [];
+    await Promise.allSettled(handlers.map((h) => h(payload)));
+  }
+}
+const bus = new TypedEventBus();
+bus.on("order.created", async (data) => sendConfirmationEmail(data.userId, data.orderId));
+bus.on("order.created", async (data) => updateInventory(data.orderId));
+bus.on("order.created", async (data) => trackAnalytics("order_created", data));
+```
+### Distributed Pub/Sub with Redis Streams
+```typescript
+import { Redis } from "ioredis";
+const redis = new Redis();
+// Producer
+async function publishEvent(stream: string, event: Record<string, string>) {
+  await redis.xadd(stream, "*", ...Object.entries(event).flat());
+}
+await publishEvent("orders", {
+  type: "order.created",
+  orderId: "o_123",
+  payload: JSON.stringify({ userId: "u_456", total: 99.99 }),
+});
+// Consumer group -- each service gets every event exactly once
+await redis.xgroup("CREATE", "orders", "email-service", "0", "MKSTREAM").catch(() => {});
+async function consumeEvents(group: string, consumer: string) {
+  while (true) {
+    const results = await redis.xreadgroup(
+      "GROUP", group, consumer, "COUNT", 10, "BLOCK", 5000, "STREAMS", "orders", ">"
+    );
+    if (!results) continue;
+    for (const [, messages] of results) {
+      for (const [id, fields] of messages) {
+        await processEvent(Object.fromEntries(chunked(fields, 2)));
+        await redis.xack("orders", group, id);
+      }
+    }
+  }
+}
+```
+### CQRS -- Command Query Responsibility Segregation
+Separate write models from read models:
+```typescript
+// Command side -- handles writes, enforces business rules
+class OrderCommandHandler {
+  async createOrder(cmd: CreateOrderCommand): Promise<string> {
+    const order = Order.create(cmd.userId, cmd.items);
+    await this.orderRepo.save(order);
+    await this.eventBus.emit("order.created", {
+      orderId: order.id,
+      userId: cmd.userId,
+      total: order.total,
+    });
+    return order.id;
+  }
+}
+// Query side -- denormalized read model updated by events
+class OrderReadModel {
+  async onOrderCreated(event: OrderCreatedEvent) {
+    await this.readDb.insert("order_summaries", {
+      orderId: event.orderId,
+      userId: event.userId,
+      total: event.total,
+      status: "pending",
+      createdAt: event.timestamp,
+    });
+  }
+  async getOrderSummaries(userId: string) {
+    return this.readDb.query(
+      "SELECT * FROM order_summaries WHERE user_id = $1 ORDER BY created_at DESC",
+      [userId]
+    );
+  }
+}
+```
+### Event Sourcing
+Store events as the source of truth, derive state by replaying:
+```typescript
+type OrderEvent =
+  | { type: "OrderCreated"; orderId: string; items: OrderItem[]; timestamp: string }
+  | { type: "PaymentReceived"; orderId: string; amount: number; timestamp: string }
+  | { type: "OrderShipped"; orderId: string; trackingId: string; timestamp: string };
+function buildOrderState(events: OrderEvent[]): OrderState {
+  return events.reduce((state, event) => {
+    switch (event.type) {
+      case "OrderCreated":
+        return { ...state, id: event.orderId, items: event.items, status: "pending" };
+      case "PaymentReceived":
+        return { ...state, status: "paid", paidAmount: event.amount };
+      case "OrderShipped":
+        return { ...state, status: "shipped", trackingId: event.trackingId };
+    }
+  }, {} as OrderState);
+}
+// Append-only event store
+async function appendEvent(aggregateId: string, event: OrderEvent): Promise<void> {
+  await db.query(
+    "INSERT INTO events (id, aggregate_id, type, data, timestamp) VALUES ($1, $2, $3, $4, $5)",
+    [crypto.randomUUID(), aggregateId, event.type, JSON.stringify(event), event.timestamp]
+  );
+}
+```
+### Dead Letter Queue
+Handle failed messages without losing them:
+```typescript
+async function processWithDLQ(
+  message: QueueMessage,
+  handler: (msg: QueueMessage) => Promise<void>,
+  maxRetries = 3
+) {
+  const retryCount = message.attributes?.retryCount ?? 0;
+  try {
+    await handler(message);
+  } catch (err) {
+    if (retryCount < maxRetries) {
+      await queue.send({
+        ...message,
+        attributes: { retryCount: retryCount + 1 },
+        delaySeconds: Math.pow(2, retryCount) * 10,
+      });
+    } else {
+      await dlq.send({
+        originalMessage: message,
+        error: (err as Error).message,
+        failedAt: new Date().toISOString(),
+      });
+      logger.error({ messageId: message.id }, "Sent to DLQ after max retries");
+    }
+  }
+}
+```
+### Idempotent Event Handlers
+Events may be delivered more than once. Make handlers safe to re-run:
+```typescript
+async function idempotentHandler(
+  eventId: string,
+  handler: () => Promise<void>
+): Promise<void> {
+  const acquired = await redis.set(`processed:${eventId}`, "1", "NX", "EX", 86400);
+  if (!acquired) {
+    logger.info({ eventId }, "Already processed, skipping");
+    return;
+  }
+  await handler();
+}
+// Or use database constraints
+await db.query(
+  `INSERT INTO shipment_notifications (order_id, sent_at)
+   VALUES ($1, NOW()) ON CONFLICT (order_id) DO NOTHING`,
+  [orderId]
+);
+```
+## Examples
+| Pattern | When | Result |
+|---------|------|--------|
+| In-process event bus | Monolith | Decoupled handlers, zero latency |
+| Pub/Sub (Redis/RabbitMQ) | Microservices | Cross-service communication |
+| CQRS | Different read/write scaling | Optimized read models |
+| Event sourcing | Audit trail, financial systems | Complete history, replay |
+| Dead letter queue | Failed message handling | No lost messages |
+| Idempotency | At-least-once delivery | Exactly-once processing |
+## Checklist
+- [ ] Events named in past tense (`order.created`, not `create.order`)
+- [ ] Every event has ID, timestamp, and aggregate ID
+- [ ] Consumers are idempotent (safe to process same event twice)
+- [ ] Dead letter queues configured for all subscriptions
+- [ ] Event schemas versioned for backward compatibility
+- [ ] CQRS read models documented as eventually consistent
+- [ ] Event store indexed on aggregate_id + version
+- [ ] Failed events trigger alerts, not silent data loss