Skip to content

secondsky/claude-skills / plugins/cloudflare-durable-objects/skills/cloudflare-durable-objects

cloudflare-durable-objects

Verified

Cloudflare Durable Objects for stateful coordination and real-time apps. Use for chat, multiplayer games, WebSocket hibernation, or encountering class export, migration, alarm errors.

FileKindSize
SKILL.mdskill md21.6 KB
references/advanced-sql-patterns.mdmarkdown15.8 KB
references/alarms-api.mdmarkdown6.5 KB
references/best-practices.mdmarkdown8.5 KB
references/common-patterns.mdmarkdown16.7 KB
references/data-modeling.mdmarkdown16.9 KB
references/error-codes.mdmarkdown7.7 KB
references/gradual-deployments.mdmarkdown13.9 KB
references/migration-cheatsheet.mdmarkdown3.2 KB
references/migrations-guide.mdmarkdown7.3 KB
references/monitoring-debugging.mdmarkdown18.2 KB
references/performance-optimization.mdmarkdown16.2 KB
references/rpc-metadata.mdmarkdown16.9 KB
references/rpc-patterns.mdmarkdown6.5 KB
references/security-best-practices.mdmarkdown15.9 KB
references/state-api-reference.mdmarkdown6.0 KB
references/stubs-routing.mdmarkdown10.6 KB
references/top-errors.mdmarkdown10.2 KB
references/typescript-config.mdmarkdown8.3 KB
references/vitest-testing.mdmarkdown18.1 KB
references/websocket-hibernation.mdmarkdown6.3 KB
references/wrangler-commands.mdmarkdown3.4 KB
scripts/check-versions.shexecutablescript593 B
scripts/migration-generator.shexecutablescript13.4 KB
scripts/setup-vitest-do.shexecutablescript10.2 KB
scripts/validate-do-config.shexecutablescript10.0 KB
templates/alarms-api-do.tsscript6.1 KB
templates/basic-do.tsscript2.9 KB
templates/gradual-deployment-config.jsoncother10.4 KB
templates/location-hints.tsscript6.8 KB
templates/multi-do-coordination.tsscript7.8 KB
templates/package.jsonmanifest384 B
templates/rpc-metadata-do.tsscript10.8 KB
templates/rpc-vs-fetch.tsscript6.0 KB
templates/state-api-patterns.tsscript5.8 KB
templates/ttl-cleanup-do.tsscript17.6 KB
templates/vitest-do-test.tsscript12.3 KB
templates/websocket-hibernation-do.tsscript6.0 KB
templates/wrangler-do-config.jsoncother2.0 KB

references/state-api-reference.md

View on GitHub
# Durable Objects State API Reference

Complete reference for the State API (SQL and Key-Value storage).

---

## SQL API (SQLite Backend)

Access via `ctx.storage.sql` (requires SQLite backend in migration).

### `exec(query, ...params)`

Execute SQL query with optional parameters. Returns cursor.

```typescript
// Insert with RETURNING
const cursor = this.sql.exec(
  'INSERT INTO users (name, email) VALUES (?, ?) RETURNING id',
  'Alice',
  'alice@example.com'
);

// SELECT
const cursor = this.sql.exec('SELECT * FROM users WHERE id = ?', userId);

// UPDATE
this.sql.exec('UPDATE users SET email = ? WHERE id = ?', newEmail, userId);

// DELETE
this.sql.exec('DELETE FROM users WHERE id = ?', userId);
```

**Parameters:**
- `query` (string): SQL query with `?` placeholders
- `...params` (any[]): Values to bind to placeholders

**Returns:** `SqlCursor`

### Cursor Methods

```typescript
// Get single row (throws if 0 or >1 rows)
const row = cursor.one<{ id: number; name: string }>();

// Get single row (returns null if no rows)
const row = cursor.one<RowType>({ allowNone: true });

// Get all rows as array
const rows = cursor.toArray<RowType>();

// Iterate cursor
for (const row of cursor) {
  console.log(row.name);
}
```

### Transactions (Synchronous)

```typescript
this.ctx.storage.transactionSync(() => {
  this.sql.exec('INSERT INTO table1 ...');
  this.sql.exec('UPDATE table2 ...');
  // All or nothing - atomic
});
```

**CRITICAL:** Must be synchronous (no `async`/`await` inside).

---

## Key-Value API

Available on both SQLite and KV backends via `ctx.storage`.

### `get(key)` / `get(keys[])`

Get single or multiple values.

```typescript
// Get single value
const value = await this.ctx.storage.get<number>('count');

// Get multiple values (returns Map)
const map = await this.ctx.storage.get<string>(['key1', 'key2', 'key3']);

// Iterate Map
for (const [key, value] of map.entries()) {
  console.log(key, value);
}
```

**Parameters:**
- `key` (string): Key to retrieve
- `keys` (string[]): Array of keys to retrieve

**Returns:** Promise<value> or Promise<Map<string, value>>

### `put(key, value)` / `put(entries)`

Put single or multiple values.

```typescript
// Put single value
await this.ctx.storage.put('count', 42);

// Put multiple values
await this.ctx.storage.put({
  key1: 'value1',
  key2: 'value2',
  key3: 'value3',
});
```

**Parameters:**
- `key` (string): Key to store
- `value` (any): Value to store (must be serializable)
- `entries` (Record<string, any>): Object with key-value pairs

**Returns:** Promise<void>

### `delete(key)` / `delete(keys[])`

Delete single or multiple keys.

```typescript
// Delete single key
await this.ctx.storage.delete('key1');

// Delete multiple keys
await this.ctx.storage.delete(['key1', 'key2', 'key3']);
```

**Returns:** Promise<boolean> (true if deleted)

### `list(options)`

List keys with optional filtering.

```typescript
// List all keys
const map = await this.ctx.storage.list();

// List with prefix
const map = await this.ctx.storage.list({ prefix: 'user:' });

// List with limit
const map = await this.ctx.storage.list({ limit: 100 });

// List in reverse order
const map = await this.ctx.storage.list({ reverse: true });

// List with start/end range
const map = await this.ctx.storage.list({
  start: 'user:a',
  end: 'user:z',
});
```

**Parameters:**
- `prefix` (string): Filter keys by prefix
- `limit` (number): Max keys to return
- `reverse` (boolean): Reverse order
- `start` (string): Start key (inclusive)
- `end` (string): End key (exclusive)

**Returns:** Promise<Map<string, any>>

### `deleteAll()`

Delete all storage (DO will cease to exist after shutdown).

```typescript
// Delete alarm first
await this.ctx.storage.deleteAlarm();

// Delete all storage
await this.ctx.storage.deleteAll();
```

**CRITICAL:**
- ✅ Atomic on SQLite backend
- ⚠️ May be partial on KV backend

**Returns:** Promise<void>

### `transaction(callback)`

Async transaction for KV operations.

```typescript
await this.ctx.storage.transaction(async (txn) => {
  const value = await txn.get('count');
  await txn.put('count', value + 1);
  await txn.put('lastUpdate', Date.now());
  // All or nothing
});
```

**Returns:** Promise<any> (callback return value)

---

## Alarms API

### `setAlarm(time)`

Schedule alarm to fire at specific time.

```typescript
// Fire in 60 seconds
await this.ctx.storage.setAlarm(Date.now() + 60000);

// Fire at specific date
await this.ctx.storage.setAlarm(new Date('2025-12-31T23:59:59Z'));
```

**Parameters:**
- `time` (number | Date): Timestamp or Date to fire

**Returns:** Promise<void>

### `getAlarm()`

Get current alarm time (null if not set).

```typescript
const alarmTime = await this.ctx.storage.getAlarm();

if (alarmTime) {
  console.log(`Alarm scheduled for ${new Date(alarmTime).toISOString()}`);
}
```

**Returns:** Promise<number | null>

### `deleteAlarm()`

Delete scheduled alarm.

```typescript
await this.ctx.storage.deleteAlarm();
```

**Returns:** Promise<void>

---

## Storage Limits

| Backend | Max Storage | deleteAll() Atomic |
|---------|-------------|-------------------|
| SQLite | 1 GB | ✅ Yes |
| KV | 128 MB | ❌ No (may be partial) |

---

## Best Practices

✅ **Always use parameterized queries** (SQL)
```typescript
// ✅ CORRECT
this.sql.exec('SELECT * FROM users WHERE id = ?', userId);

// ❌ WRONG (SQL injection risk)
this.sql.exec(`SELECT * FROM users WHERE id = ${userId}`);
```

✅ **Use transactions for multi-step operations**
```typescript
this.ctx.storage.transactionSync(() => {
  this.sql.exec('INSERT ...');
  this.sql.exec('UPDATE ...');
});
```

✅ **Create indexes for frequently queried columns**
```typescript
this.sql.exec('CREATE INDEX idx_user_email ON users(email)');
```

✅ **Monitor storage size** (approach 1GB limit)
```typescript
const size = await this.estimateStorageSize();
if (size > 900_000_000) {  // 900MB
  await this.cleanup();
}
```

---

**Official Docs**:
- SQL API: https://developers.cloudflare.com/durable-objects/api/sqlite-storage-api/
- KV API: https://developers.cloudflare.com/durable-objects/api/legacy-kv-storage-api/
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 196kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 193kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 193kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 193kUpdated Claude CodeCodexVerifiedInstall