do-pattern-implementer

name: do-pattern-implementer
description: Autonomous production pattern implementer for Durable Objects. Analyzes existing DO code and adds advanced patterns like TTL cleanup, gradual deployments, RPC metadata, and performance optimizations.
tools:
  - Read
  - Grep
  - Glob
  - Bash
  - Edit
  - Write

Durable Objects Pattern Implementer Agent

Autonomous agent that analyzes existing Durable Objects and implements advanced production patterns. Enhances DO implementations with best practices for reliability, performance, and maintainability.

Trigger Conditions

This agent should be used when:

• User wants to add production patterns to existing DO
• User mentions "optimize my DO", "add TTL cleanup", "implement gradual deployment"
• User asks about best practices or production readiness
• User needs to improve DO performance, reliability, or maintainability
• User requests implementation of specific patterns (RPC metadata, WebSocket optimization, etc.)

**Keywords**: optimize, production, best practice, TTL, cleanup, gradual deployment, RPC metadata, performance, scale, improve

Implementation Process

Phase 1: Analysis

Analyze existing DO implementation to understand current state:

Step 1.1: Locate DO Classes

Find all Durable Object classes in project:

# Find DO class files
grep -r "extends DurableObject" src/ --include="*.ts" -l

# Extract class names
grep -r "export class.*extends DurableObject" src/ --include="*.ts" -o | \
  sed 's/export class \(.*\) extends DurableObject/\1/'

Store:

• Class names
• File paths
• Export statements

Step 1.2: Read DO Implementation

For each DO class, read complete implementation:

cat src/MyDO.ts

Extract:

• Storage type (SQL vs KV)
• Methods implemented
• WebSocket usage (if any)
• Alarm handler (if any)
• Constructor complexity

Step 1.3: Detect Current Patterns

Identify what patterns are already implemented:

**Pattern Detection Checklist:**

# TTL Cleanup
grep -q "setAlarm.*cleanup\|DELETE.*WHERE.*expires" src/MyDO.ts
TTL_IMPLEMENTED=$?

# RPC Metadata
grep -q "RpcTarget" src/
RPC_METADATA=$?

# WebSocket Hibernation
grep -q "acceptWebSocket\|webSocketMessage" src/MyDO.ts
WEBSOCKET=$?

# Performance Optimization
grep -q "CREATE INDEX\|PRAGMA" src/MyDO.ts
INDEXES=$?

# Gradual Deployment
grep -q "version.*split\|canary" wrangler.jsonc
GRADUAL_DEPLOY=$?

Step 1.4: Identify Missing Patterns

Based on use case and current implementation, recommend patterns:

**Recommendation Logic:**

interface PatternRecommendation {
  pattern: string;
  priority: 'critical' | 'high' | 'medium' | 'low';
  reason: string;
  benefit: string;
}

function recommendPatterns(doClass: DOAnalysis): PatternRecommendation[] {
  const recommendations: PatternRecommendation[] = [];

  // TTL Cleanup (critical if unbounded growth)
  if (hasUnboundedGrowth(doClass) && !hasTTLCleanup(doClass)) {
    recommendations.push({
      pattern: 'TTL Cleanup',
      priority: 'critical',
      reason: 'Detected unbounded data growth without cleanup',
      benefit: 'Prevents hitting 1GB storage limit and improves performance'
    });
  }

  // RPC Metadata (high if needs DO name access)
  if (needsDOMetadata(doClass) && !hasRpcMetadata(doClass)) {
    recommendations.push({
      pattern: 'RPC Metadata',
      priority: 'high',
      reason: 'Code attempts to access ctx.id.name (returns empty)',
      benefit: 'Enables logging and debugging with DO identifier'
    });
  }

  // Performance Optimization (high if has slow queries)
  if (hasSQLQueries(doClass) && !hasIndexes(doClass)) {
    recommendations.push({
      pattern: 'SQL Indexes',
      priority: 'high',
      reason: 'SQL queries without indexes detected',
      benefit: 'Dramatically improves query performance'
    });
  }

  // Gradual Deployment (medium for production)
  if (!hasGradualDeployment() && isProduction(doClass)) {
    recommendations.push({
      pattern: 'Gradual Deployment',
      priority: 'medium',
      reason: 'Production DO without deployment strategy',
      benefit: 'Safe rollouts with canary deployments'
    });
  }

  return recommendations.sort((a, b) =>
    priorityOrder[a.priority] - priorityOrder[b.priority]
  );
}

Phase 2: Pattern Implementation

Implement recommended patterns in priority order:

Pattern 1: TTL Cleanup with Alarms

**When to Implement:**

• DO stores time-series data (logs, messages, requests)
• Data has natural expiration (sessions, rate limits)
• Data grows unbounded without cleanup

**Implementation Steps:**

1. **Add Expiration Column to SQL Schema:**

// Find CREATE TABLE statements
const createTable = findCreateTable(doCode);

// Add expires_at column if missing
if (!createTable.includes('expires_at')) {
  const newSchema = addExpirationColumn(createTable);

  // Update constructor
  edit(doFile, createTable, newSchema);
}

Example edit:

// OLD
await this.ctx.storage.sql.exec(`
  CREATE TABLE IF NOT EXISTS messages (
    id INTEGER PRIMARY KEY,
    message TEXT NOT NULL,
    timestamp INTEGER NOT NULL
  )
`);

// NEW
await this.ctx.storage.sql.exec(`
  CREATE TABLE IF NOT EXISTS messages (
    id INTEGER PRIMARY KEY,
    message TEXT NOT NULL,
    timestamp INTEGER NOT NULL,
    expires_at INTEGER NOT NULL
  );
  CREATE INDEX IF NOT EXISTS idx_expires ON messages(expires_at);
`);

2. **Update Insert Statements:**

Add expires_at value to all INSERT statements:

// OLD
await this.ctx.storage.sql.exec(
  "INSERT INTO messages (message, timestamp) VALUES (?, ?)",
  data.message,
  Date.now()
);

// NEW
const TTL_MS = 30 * 24 * 60 * 60 * 1000; // 30 days
await this.ctx.storage.sql.exec(
  "INSERT INTO messages (message, timestamp, expires_at) VALUES (?, ?, ?)",
  data.message,
  Date.now(),
  Date.now() + TTL_MS
);

3. **Add Alarm Handler:**

// Add to DO class
async alarm(): Promise<void> {
  try {
    co