cloudflare-kv:optimize

/cloudflare-kv:optimize - Analyze and Optimize KV Usage

This command analyzes Worker code for KV usage patterns and provides actionable optimization recommendations to improve performance and reduce costs.

What This Command Does

1. Analyzes Code Patterns

   • Scans Worker files for KV operations
   • Identifies get(), put(), delete(), list() calls
   • Detects missing optimizations

2. Checks Best Practices

   • TTL usage on put() operations
   • cacheTtl usage on get() operations
   • Error handling patterns
   • Bulk operation opportunities
   • waitUntil() for async writes

3. Generates Report

   • Critical issues (must fix)
   • Warnings (should fix)
   • Optimizations (nice to have)
   • Code examples for each issue
   • Estimated cost/performance impact

How to Use

Analyze Single File

/cloudflare-kv:optimize src/index.ts

Analyze Multiple Files

Run multiple times for different files:

/cloudflare-kv:optimize src/index.ts
/cloudflare-kv:optimize src/api/routes.ts
/cloudflare-kv:optimize src/lib/kv-utils.ts

Interactive Mode

If no file specified, command will:

1. Search for common Worker files (src/index.ts, index.js, worker.ts)
2. List found files
3. Ask which to analyze

/cloudflare-kv:optimize

Implementation

Execute the analysis script from the cloudflare-kv skill:

${CLAUDE_PLUGIN_ROOT}/scripts/analyze-kv-usage.sh <worker-file>

The script performs static code analysis to detect:

• Missing TTL/expiration on put()
• Missing cacheTtl on get()
• Lack of error handling
• Sequential operations that could be parallel
• Missing pagination on list()
• Opportunities for waitUntil()
• JSON.stringify usage for objects

Example Output

Cloudflare Workers KV - Usage Analyzer
======================================

Analyzing: src/index.ts

KV Operations Found:
  - get():    15
  - put():    8
  - delete(): 3
  - list():   2

Issue Check 1: Missing TTL on put() operations
----------------------------------------------
⚠ 5 put() operation(s) without TTL/expiration
  Issue: Data will persist indefinitely, increasing storage costs
  Fix: Add expirationTtl or expiration to put() calls

  Example:
    await env.KV.put('key', 'value', { expirationTtl: 3600 });

Issue Check 2: Missing cacheTtl on get() operations
---------------------------------------------------
⚠ 12 get() operation(s) without cacheTtl
  Issue: Missing edge caching optimization
  Fix: Add cacheTtl for frequently-read data (min 60 seconds)

  Example:
    const value = await env.KV.get('key', { cacheTtl: 300 });

Issue Check 3: Missing error handling
-------------------------------------
✗ No try-catch blocks found
  Issue: KV operations can fail (rate limits, network errors)
  Fix: Wrap KV operations in try-catch

  Example:
    try {
      const value = await env.KV.get('key');
    } catch (error) {
      console.error('KV error:', error);
      // Handle gracefully
    }

Issue Check 4: Sequential get() calls (bulk read opportunity)
-------------------------------------------------------------
⚠ Multiple sequential await get() calls detected
  Issue: Each get() counts as separate operation
  Fix: Consider using Promise.all() for parallel reads

  Example:
    const [val1, val2, val3] = await Promise.all([
      env.KV.get('key1'),
      env.KV.get('key2'),
      env.KV.get('key3')
    ]);

========================================
Summary
========================================

Critical Issues:   1
Warnings:          3
Optimizations:     2

⚠ Critical issues found

Please address critical issues before deploying to production.

For more details, see:
  - references/best-practices.md
  - references/performance-tuning.md