storage.ts

/**
 * Storage Adapter for R2 Bucket
 * Typeclass-based abstraction for R2 storage operations
 */

// R2 Types are available globally from worker-configuration.d.ts (generated by Wrangler)
/**
 * Storage Adapter Interface - Typeclass for storage operations
 * This defines the contract that any storage implementation must satisfy
 */
export interface StorageAdapter<T> {
  /**
   * Put an object into storage
   * @param key - The key/path where to store the object
   * @param value - The value to store (will be serialized to JSON)
   * @param options - Optional storage options
   */
  put(key: string, value: T, options?: R2PutOptions): Promise<void>

  /**
   * Get an object from storage
   * @param key - The key/path of the object to retrieve
   * @returns The retrieved object or null if not found
   */
  get(key: string): Promise<T | null>

  /**
   * Delete an object from storage
   * @param key - The key/path of the object to delete
   */
  delete(key: string): Promise<void>

  /**
   * List objects in storage with optional prefix
   * @param options - List options including prefix
   * @returns List of objects with their keys
   */
  list(options?: R2ListOptions): Promise<R2Object[]>

  /**
   * Check if an object exists in storage
   * @param key - The key/path to check
   * @returns True if the object exists, false otherwise
   */
  exists(key: string): Promise<boolean>
}

/**
 * R2 Storage Adapter Implementation
 * Concrete implementation of StorageAdapter for Cloudflare R2
 */
export class R2StorageAdapter<T> implements StorageAdapter<T> {
  constructor(private readonly bucket: R2Bucket) {}

  async put(key: string, value: T, options?: R2PutOptions): Promise<void> {
    const serializedValue = JSON.stringify(value)
    await this.bucket.put(key, serializedValue, options)
  }

  async get(key: string): Promise<T | null> {
    const obj = await this.bucket.get(key)
    if (!obj) {
      return null
    }
    return JSON.parse(await obj.text()) as T
  }

  async delete(key: string): Promise<void> {
    await this.bucket.delete(key)
  }

  async list(options?: R2ListOptions): Promise<R2Object[]> {
    const result = await this.bucket.list(options)
    return result.objects
  }

  async exists(key: string): Promise<boolean> {
    // head() fetches only object metadata — no body download
    const obj = await this.bucket.head(key)
    return !!obj
  }

  /**
   * Get the underlying R2 bucket for advanced operations
   * This allows access to the raw R2 API when needed
   */
  getBucket(): R2Bucket {
    return this.bucket
  }
}

/**
 * Storage Adapter Constructor Function
 * Functional-style constructor for creating storage adapters
 * @param bucket - The R2 bucket to wrap
 * @returns A new StorageAdapter instance
 */
export function createStorageAdapter<T>(bucket: R2Bucket): StorageAdapter<T> {
  return new R2StorageAdapter<T>(bucket)
}

/**
 * Mock Storage Adapter for Testing
 * In-memory implementation for testing purposes
 */
export class MockStorageAdapter<T> implements StorageAdapter<T> {
  private store: Map<string, T> = new Map()

  async put(key: string, value: T, _options?: R2PutOptions): Promise<void> {
    this.store.set(key, value)
  }

  async get(key: string): Promise<T | null> {
    const value = this.store.get(key)
    return value ?? null
  }

  async delete(key: string): Promise<void> {
    this.store.delete(key)
  }

  async list(options?: R2ListOptions): Promise<R2Object[]> {
    const prefix = options?.prefix || ""
    const result: R2Object[] = []

    for (const [key, _value] of this.store.entries()) {
      if (key.startsWith(prefix)) {
        result.push({
          key,
          version: "mock-version",
          size: JSON.stringify(_value).length,
          etag: `"mock-etag-${key}"`,
          httpMetadata: { contentType: "application/json" } as R2HTTPMetadata,
          customMetadata: {},
          uploaded: new Date(),
          range: undefined,
        } as unknown as R2Object)
      }
    }

    return result
  }

  async exists(key: string): Promise<boolean> {
    return this.store.has(key)
  }

  /**
   * Clear all data in the mock store (for testing)
   */
  clear(): void {
    this.store.clear()
  }

  /**
   * Get all keys in the mock store (for testing)
   */
  getAllKeys(): string[] {
    return Array.from(this.store.keys())
  }
}

/**
 * Storage Adapter Typeclass Utilities
 * Higher-order functions for working with storage adapters
 */
export namespace Storage {
  /**
   * Apply a function to a value retrieved from storage
   * @param adapter - The storage adapter
   * @param key - The key to retrieve
   * @param fn - The function to apply
   */
  export async function withValue<T, R>(
    adapter: StorageAdapter<T>,
    key: string,
    fn: (value: T) => R,
  ): Promise<R | null> {
    const value = await adapter.get(key)
    return value ? fn(value) : null
  }

  /**
   * Update a value in storage using a transformation function
   * @param adapter - The storage adapter
   * @param key - The key to update
   * @param fn - The transformation function
   */
  export async function update<T>(
    adapter: StorageAdapter<T>,
    key: string,
    fn: (current: T | null) => T,
  ): Promise<void> {
    const current = await adapter.get(key)
    const updated = fn(current)
    await adapter.put(key, updated)
  }

  /**
   * Check if a value exists and meets a condition
   * @param adapter - The storage adapter
   * @param key - The key to check
   * @param predicate - The condition function
   */
  export async function existsWhere<T>(
    adapter: StorageAdapter<T>,
    key: string,
    predicate: (value: T) => boolean,
  ): Promise<boolean> {
    const value = await adapter.get(key)
    return !!value && predicate(value)
  }

  /**
   * Transaction-like operation for multiple storage operations
   * @param adapter - The storage adapter
   * @param operations - Array of operations to perform
   */
  export async function transaction<T>(
    adapter: StorageAdapter<T>,
    operations: Array<() => Promise<void>>,
  ): Promise<void> {
    for (const op of operations) {
      await op()
    }
  }
}