clearable-object

Clearable Object

A simple library for adding clear functionality to Cloudflare Durable Objects. Supports clearing storage and alarms with optional authentication.

Installation

npm i clearable-object

Quick Start

Decorator Pattern (Recommended)

import { Clearable } from "clearable-object";

@Clearable({ secret: "user:pass", isPublic: false })
export class MyDurableObject extends DurableObject {
  // Automatically adds GET /clear endpoint
}

Manual Integration

import { Clear } from "clearable-object";

export class MyDurableObject extends DurableObject {
  clear = new Clear(this, { secret: "user:pass" });

  async fetch(request: Request) {
    const url = new URL(request.url);

    if (url.pathname === "/clear") {
      const result = await this.clear.clear();
      return new Response(JSON.stringify(result));
    }
    // ... your logic
  }
}

Endpoints (Decorator)

• GET /clear - Clear all data (storage and alarm)
• GET /clear?storage=false - Skip clearing storage
• GET /clear?alarm=false - Skip clearing alarm

API Methods

Clear All Data

await clear.clear({
  clearStorage: true, // Clear Durable Object storage
  clearAlarm: true, // Clear scheduled alarm
});

Check Authentication

const isAuthorized = clear.checkAuth(request);

Get Unauthorized Response

return clear.unauthorizedResponse();

Response Format

interface ClearResult {
  success: boolean;
  storageCleared: boolean; // Whether storage was cleared
  alarmCleared: boolean; // Whether alarm was cleared
  errors?: string[]; // Any errors encountered
  warnings?: string[]; // Any warnings
}

Configuration Options

interface ClearOptions {
  secret?: string; // Authentication secret
  isPublic?: boolean; // Allow unauthenticated access
}

Authentication

Configure with secret option. Supports Basic Auth and API key query parameter.

Basic Auth

curl -u user:pass https://your-worker.com/clear

API Key Query Parameter

curl https://your-worker.com/clear?apiKey=user:pass

Configuration Examples

// Require authentication
@Clearable({ secret: "myuser:mypass" })

// Public access (no auth required)
@Clearable({ isPublic: true })

// No auth, not public (will reject all requests)
@Clearable()

Safety Features

• Graceful Error Handling: Storage and alarm clearing failures are handled independently
• Detailed Reporting: Know exactly what was cleared and what failed
• Flexible Options: Choose what to clear via query parameters
• Authentication: Protect destructive operations with Basic Auth or API keys

Use Cases

• Development: Quick reset during testing
• Maintenance: Clean up corrupted data
• Migration: Prepare for fresh data import
• Debugging: Clear state to isolate issues

Example Responses

Successful Clear

{
  "success": true,
  "storageCleared": true,
  "alarmCleared": true
}

Partial Success with Warnings

{
  "success": true,
  "storageCleared": true,
  "alarmCleared": false,
  "warnings": ["No alarm was set to clear"]
}

Authentication Error

{
  "error": "Unauthorized",
  "message": "Valid authentication required"
}

TypeScript Support

Full TypeScript support with proper type definitions for all methods and responses.

import { Clear, ClearResult, ClearOptions } from "clearable-object";

const clear = new Clear(durableObject, options);
const result: ClearResult = await clear.clear();