Bucket

The Bucket component provides object storage functionality for your Raindrop applications. You can store files of various types and retrieve them using unique keys.

Buckets support multiple file formats including ReadableStream, ArrayBuffer, ArrayBufferView, string, null, and Blob types. Each stored object includes metadata such as size, etag, upload timestamp, and optional custom metadata.

The component offers flexible listing capabilities with pagination, prefix filtering, and delimiter-based grouping. This makes it suitable for organizing files in hierarchical structures similar to traditional file systems.

Creating

Add a bucket to your application manifest to enable file storage:

application "demo-app" {
    bucket "file-storage" {}
}

The bucket becomes available through environment bindings in your application code. You can create multiple buckets with different names for organizing different types of content.

Accessing

Access your bucket through the environment binding in request handlers:

export default async function handler(request: Request, env: Env) {
    // Store a file
    const fileObject = await env.FILE_STORAGE.put('documents/readme.txt', 'Hello world');

    // Retrieve the file
    const retrieved = await env.FILE_STORAGE.get('documents/readme.txt');

    return new Response(await retrieved?.text());
}

Core Concepts

Main Interfaces

• Bucket - Primary interface for storage operations
• BucketObject - Metadata for stored objects
• BucketObjectBody - Object with readable content
• BucketListOptions - Configuration for listing operations

Core Data Types

BucketObject

interface BucketObject {
    readonly key: string;          // Object identifier
    readonly version: string;      // Object version
    readonly size: number;         // Size in bytes
    readonly etag: string;         // Entity tag for caching
    readonly httpEtag: string;     // HTTP-formatted etag
    readonly checksums: BucketChecksums;  // Hash values
    readonly uploaded: Date;       // Upload timestamp
    readonly httpMetadata?: BucketHTTPMetadata;  // HTTP headers
    readonly customMetadata?: Record<string, string>;  // User metadata
    readonly range?: BucketRange;  // Partial content range
    readonly storageClass: string; // Storage tier
}

BucketObjectBody

interface BucketObjectBody extends BucketObject {
    get body(): ReadableStream;    // Stream for reading content
    get bodyUsed(): boolean;       // Whether stream was consumed
    arrayBuffer(): Promise<ArrayBuffer>;  // Read as array buffer
    text(): Promise<string>;       // Read as text
    json<T>(): Promise<T>;         // Parse as JSON
    blob(): Promise<Blob>;         // Read as blob
}

BucketListOptions

interface BucketListOptions {
    limit?: number;        // Max items to return (default: 250)
    prefix?: string;       // Filter by key prefix
    cursor?: string;       // Pagination token
    delimiter?: string;    // Group by delimiter (default: /)
    startAfter?: string;   // Start listing after this key
}

System Limits

• Maximum file size: 5GB
• Default list limit: 250 objects
• Default delimiter: /

head

Input

head(key: string): Promise<BucketObject | null>

Output

// Returns object metadata without downloading content
Promise<BucketObject | null>

Example

Check if a file exists and get its metadata:

// Get file metadata without downloading
const metadata = await env.FILE_STORAGE.head('documents/readme.txt');

if (metadata) {
    console.log(`File size: ${metadata.size} bytes`);
    console.log(`Uploaded: ${metadata.uploaded}`);
}

get

Input

get(key: string, options?: BucketGetOptions): Promise<BucketObjectBody | null>

Output

// Returns object with readable content
Promise<BucketObjectBody | null>

Example

Retrieve and read file content:

// Download file with content
const file = await env.FILE_STORAGE.get('documents/readme.txt');

if (file) {
    const content = await file.text();
    console.log(content);
}

put

Input

put(
    key: string,
    value: ReadableStream | ArrayBuffer | ArrayBufferView | string | null | Blob,
    options?: BucketPutOptions
): Promise<BucketObject>

Output

// Returns metadata for the stored object
Promise<BucketObject>

Example

Store content with custom metadata:

// Store file with metadata
const stored = await env.FILE_STORAGE.put('documents/readme.txt', 'Hello world', {
    customMetadata: { author: 'user123', category: 'docs' },
    httpMetadata: { contentType: 'text/plain' }
});

console.log(`Stored with etag: ${stored.etag}`);

delete

Input

delete(keys: string | string[]): Promise<void>

Output

// Resolves when deletion completes
Promise<void>

Example

Remove single or multiple files:

// Delete single file
await env.FILE_STORAGE.delete('documents/readme.txt');

// Delete multiple files
await env.FILE_STORAGE.delete([
    'documents/file1.txt',
    'documents/file2.txt'
]);

list

Input

list(options?: BucketListOptions): Promise<BucketObjects>

Output

// Returns objects and pagination info
Promise<BucketObjects>

Example

List files with prefix filtering:

// List files in documents folder
const result = await env.FILE_STORAGE.list({
    prefix: 'documents/',
    limit: 10
});

result.objects.forEach(obj => {
    console.log(`${obj.key}: ${obj.size} bytes`);
});

// Handle pagination
if (result.truncated) {
    const nextPage = await env.FILE_STORAGE.list({
        prefix: 'documents/',
        cursor: result.cursor
    });
}