gitx.do 0.0.1 → 0.0.3

package/dist/storage/r2-pack.d.ts

@@ -1,45 +1,140 @@
 /**
- * R2 Packfile Storage
- *
- * Manages Git packfiles stored in Cloudflare R2 object storage.
- * Provides functionality for:
- * - Uploading and downloading packfiles with their indices
- * - Multi-pack index (MIDX) for efficient object lookup across packs
- * - Concurrent access control with locking
- * - Pack verification and integrity checks
+ * @fileoverview R2 Packfile Storage Module
+ *
+ * This module manages Git packfiles stored in Cloudflare R2 object storage.
+ * It provides comprehensive functionality for:
+ *
+ * - **Uploading and downloading packfiles** with their indices using atomic operations
+ * - **Multi-pack index (MIDX)** for efficient object lookup across multiple packs
+ * - **Concurrent access control** with distributed locking using R2 conditional writes
+ * - **Pack verification** and integrity checks via SHA-1 checksums
+ * - **Atomic uploads** using a manifest-based pattern to ensure data consistency
+ *
+ * The module implements Git's packfile format (version 2 and 3) and provides
+ * both class-based (`R2PackStorage`) and standalone function APIs for flexibility.
+ *
+ * @module storage/r2-pack
+ *
+ * @example
+ * ```typescript
+ * // Using the class-based API
+ * const storage = new R2PackStorage({
+ *   bucket: myR2Bucket,
+ *   prefix: 'repos/my-repo/',
+ *   cacheSize: 100,
+ *   cacheTTL: 3600
+ * });
+ *
+ * // Upload a packfile
+ * const result = await storage.uploadPackfile(packData, indexData);
+ * console.log(`Uploaded pack: ${result.packId}`);
+ *
+ * // Download with verification
+ * const download = await storage.downloadPackfile(result.packId, {
+ *   verify: true,
+ *   includeIndex: true
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Using standalone functions
+ * const result = await uploadPackfile(bucket, packData, indexData, {
+ *   prefix: 'repos/my-repo/'
+ * });
+ *
+ * const packfiles = await listPackfiles(bucket, {
+ *   prefix: 'repos/my-repo/',
+ *   limit: 10
+ * });
+ * ```
  */
 /**
- * Configuration options for R2PackStorage
+ * Configuration options for R2PackStorage.
+ *
+ * @description
+ * Defines the configuration parameters for initializing an R2PackStorage instance.
+ * The bucket is required, while other options have sensible defaults.
+ *
+ * @example
+ * ```typescript
+ * const options: R2PackStorageOptions = {
+ *   bucket: env.MY_R2_BUCKET,
+ *   prefix: 'git-objects/',
+ *   cacheSize: 200,
+ *   cacheTTL: 7200
+ * };
+ * ```
  */
 export interface R2PackStorageOptions {
-    /** R2 bucket instance */
+    /**
+     * R2 bucket instance for storage operations.
+     * This is typically obtained from the Cloudflare Workers environment bindings.
+     */
     bucket: R2Bucket;
-    /** Optional prefix for all keys (e.g., 'repos/my-repo/') */
+    /**
+     * Optional prefix for all keys in the bucket.
+     * Use this to namespace packfiles for different repositories.
+     * @example 'repos/my-repo/' or 'org/project/'
+     */
     prefix?: string;
-    /** Maximum number of items to cache (default: 100) */
+    /**
+     * Maximum number of items to cache in memory.
+     * Used for caching multi-pack index and other frequently accessed data.
+     * @default 100
+     */
     cacheSize?: number;
-    /** Cache TTL in seconds (default: 3600) */
+    /**
+     * Cache TTL (Time To Live) in seconds.
+     * Cached items will be invalidated after this duration.
+     * @default 3600 (1 hour)
+     */
     cacheTTL?: number;
 }
 /**
- * Result of uploading a packfile
+ * Result returned after successfully uploading a packfile.
+ *
+ * @description
+ * Contains metadata about the uploaded packfile including its unique identifier,
+ * size information, checksum for verification, and timestamp.
+ *
+ * @example
+ * ```typescript
+ * const result = await storage.uploadPackfile(packData, indexData);
+ * console.log(`Pack ID: ${result.packId}`);
+ * console.log(`Objects: ${result.objectCount}`);
+ * console.log(`Size: ${result.packSize} bytes`);
+ * ```
  */
 export interface PackfileUploadResult {
-    /** Unique identifier for the packfile */
+    /** Unique identifier for the packfile (format: 'pack-{hex}') */
     packId: string;
     /** Size of the pack file in bytes */
     packSize: number;
     /** Size of the index file in bytes */
     indexSize: number;
-    /** SHA-1 checksum of the packfile */
+    /** SHA-1 checksum of the packfile for integrity verification */
     checksum: string;
-    /** Number of objects in the packfile */
+    /** Number of objects contained in the packfile */
     objectCount: number;
     /** Timestamp when the packfile was uploaded */
     uploadedAt: Date;
 }
 /**
- * Metadata about a stored packfile
+ * Metadata about a stored packfile.
+ *
+ * @description
+ * Provides comprehensive metadata about a packfile stored in R2,
+ * including size, object count, creation time, and checksum.
+ *
+ * @example
+ * ```typescript
+ * const metadata = await storage.getPackfileMetadata('pack-abc123');
+ * if (metadata) {
+ *   console.log(`Created: ${metadata.createdAt}`);
+ *   console.log(`Objects: ${metadata.objectCount}`);
+ * }
+ * ```
  */
 export interface PackfileMetadata {
     /** Unique identifier for the packfile */
@@ -56,44 +151,123 @@ export interface PackfileMetadata {
     checksum: string;
 }
 /**
- * Options for downloading a packfile
+ * Options for downloading a packfile.
+ *
+ * @description
+ * Configures the download behavior including whether to include the index,
+ * request byte ranges for partial reads, verify checksums, or throw on missing packs.
+ *
+ * @example
+ * ```typescript
+ * // Download with index and verification
+ * const result = await storage.downloadPackfile(packId, {
+ *   includeIndex: true,
+ *   verify: true
+ * });
+ *
+ * // Partial download (first 1MB)
+ * const partial = await storage.downloadPackfile(packId, {
+ *   byteRange: { start: 0, end: 1048575 }
+ * });
+ * ```
  */
 export interface DownloadPackfileOptions {
     /** Include the index file in the download */
     includeIndex?: boolean;
-    /** Byte range to download (for partial reads) */
+    /**
+     * Byte range to download for partial reads.
+     * Useful for streaming large packfiles or resuming interrupted downloads.
+     */
     byteRange?: {
         start: number;
         end: number;
     };
-    /** Verify checksum on download */
+    /**
+     * Verify checksum on download.
+     * When true, computes SHA-1 of downloaded data and compares with stored checksum.
+     */
     verify?: boolean;
-    /** Throw if packfile not found (default: false, returns null) */
+    /**
+     * Throw if packfile not found.
+     * When true, throws R2PackError instead of returning null.
+     * @default false
+     */
     required?: boolean;
 }
 /**
- * Result of downloading a packfile
+ * Result of downloading a packfile.
+ *
+ * @description
+ * Contains the downloaded packfile data and optionally the index data
+ * if `includeIndex` was specified in the download options.
+ *
+ * @example
+ * ```typescript
+ * const result = await storage.downloadPackfile(packId, { includeIndex: true });
+ * if (result) {
+ *   console.log(`Pack size: ${result.packData.length}`);
+ *   if (result.indexData) {
+ *     console.log(`Index size: ${result.indexData.length}`);
+ *   }
+ * }
+ * ```
  */
 export interface DownloadPackfileResult {
-    /** The packfile data */
+    /** The packfile data as a Uint8Array */
     packData: Uint8Array;
-    /** The index file data (if includeIndex was true) */
+    /** The index file data (only present if includeIndex was true) */
     indexData?: Uint8Array;
-    /** Whether the checksum was verified */
+    /** Whether the checksum was verified (only present if verify was true) */
     verified?: boolean;
 }
 /**
- * Options for uploading a packfile
+ * Options for uploading a packfile.
+ *
+ * @description
+ * Configures upload behavior including retry count and atomic upload settings.
+ *
+ * @example
+ * ```typescript
+ * const result = await storage.uploadPackfile(packData, indexData, {
+ *   retries: 5,
+ *   skipAtomic: false // Use atomic upload for safety
+ * });
+ * ```
  */
 export interface UploadPackfileOptions {
-    /** Number of retries on failure */
+    /**
+     * Number of retries on failure.
+     * Each retry uses exponential backoff.
+     */
     retries?: number;
-    /** Skip atomic upload (for testing/migration) */
+    /**
+     * Skip atomic upload pattern.
+     * Use only for testing or migration scenarios where atomicity is not required.
+     * @default false
+     */
     skipAtomic?: boolean;
 }
 /**
- * Pack manifest for atomic uploads
- * A manifest marks a pack as "complete" only after both pack and index are uploaded
+ * Pack manifest for atomic uploads.
+ *
+ * @description
+ * A manifest marks a pack as "complete" only after both pack and index are uploaded.
+ * This ensures atomic uploads where partial uploads are detected and can be cleaned up.
+ *
+ * The upload process follows these steps:
+ * 1. Upload pack and index to staging paths
+ * 2. Create manifest in 'staging' status
+ * 3. Copy from staging to final location
+ * 4. Update manifest to 'complete' status
+ * 5. Clean up staging files
+ *
+ * @example
+ * ```typescript
+ * const manifest = await storage.getPackManifest(packId);
+ * if (manifest?.status === 'complete') {
+ *   console.log('Pack upload is complete and verified');
+ * }
+ * ```
  */
 export interface PackManifest {
     /** Version of the manifest format */
@@ -110,109 +284,290 @@ export interface PackManifest {
     indexSize: number;
     /** Number of objects in the packfile */
     objectCount: number;
-    /** Timestamp when the pack was completed */
+    /** ISO 8601 timestamp when the pack was completed */
     completedAt: string;
-    /** Status: 'staging' during upload, 'complete' when done */
+    /**
+     * Upload status.
+     * - 'staging': Upload in progress
+     * - 'complete': Upload finished and verified
+     */
     status: 'staging' | 'complete';
 }
 /**
- * Entry in the multi-pack index
+ * Entry in the multi-pack index (MIDX).
+ *
+ * @description
+ * Represents a single object's location within the multi-pack index.
+ * Used for efficient O(log n) binary search across all objects in all packs.
+ *
+ * @example
+ * ```typescript
+ * const entry = lookupObjectInMultiPack(midx, objectId);
+ * if (entry) {
+ *   const packId = midx.packIds[entry.packIndex];
+ *   console.log(`Object found in pack ${packId} at offset ${entry.offset}`);
+ * }
+ * ```
  */
 export interface MultiPackIndexEntry {
     /** 40-character hex SHA-1 object ID */
     objectId: string;
     /** Index of the pack in the packIds array */
     packIndex: number;
-    /** Offset within the pack file */
+    /** Byte offset within the pack file where the object data begins */
     offset: number;
 }
 /**
- * Multi-pack index structure
+ * Multi-pack index (MIDX) structure.
+ *
+ * @description
+ * Provides a single index across multiple pack files for efficient object lookup.
+ * Entries are sorted by objectId to enable binary search.
+ *
+ * The MIDX format follows Git's multi-pack-index specification with:
+ * - MIDX signature (4 bytes)
+ * - Version number
+ * - Pack ID list
+ * - Sorted object entries
+ * - Trailing checksum
+ *
+ * @example
+ * ```typescript
+ * const midx = await storage.getMultiPackIndex();
+ * console.log(`Index contains ${midx.entries.length} objects across ${midx.packIds.length} packs`);
+ * ```
  */
 export interface MultiPackIndex {
     /** Version of the multi-pack index format */
     version: number;
-    /** Array of pack IDs in this index */
+    /** Array of pack IDs included in this index */
     packIds: string[];
     /** Sorted entries for all objects across all packs */
     entries: MultiPackIndexEntry[];
-    /** SHA-1 checksum of the index */
+    /** SHA-1 checksum of the index for integrity verification */
     checksum: Uint8Array;
 }
 /**
- * Handle for a distributed lock
- * Contains all information needed to release or refresh a lock
+ * Handle for a distributed lock.
+ *
+ * @description
+ * Contains all information needed to release or refresh a distributed lock.
+ * Locks are implemented using R2 conditional writes (ETags) for atomicity.
+ *
+ * @example
+ * ```typescript
+ * const handle = await storage.acquireDistributedLock('my-resource', 30000);
+ * if (handle) {
+ *   try {
+ *     // Do work while holding the lock
+ *     await storage.refreshDistributedLock(handle, 30000); // Extend TTL
+ *   } finally {
+ *     await storage.releaseDistributedLock(handle);
+ *   }
+ * }
+ * ```
  */
 export interface LockHandle {
-    /** Resource that is locked */
+    /** Resource identifier that is locked */
     resource: string;
-    /** Unique lock ID for this holder */
+    /** Unique lock ID for this holder (used for ownership verification) */
     lockId: string;
-    /** ETag for conditional operations */
+    /** ETag for conditional operations (ensures lock hasn't been modified) */
     etag: string;
-    /** When the lock expires (ms since epoch) */
+    /** When the lock expires (milliseconds since epoch) */
     expiresAt: number;
 }
 /**
- * Content stored in a lock file
+ * Content stored in a lock file.
+ *
+ * @description
+ * The JSON content stored in the R2 lock file. Used for lock ownership
+ * verification and debugging lock contention issues.
  */
 export interface LockFileContent {
-    /** Unique lock ID */
+    /** Unique lock ID for ownership verification */
     lockId: string;
     /** Resource being locked */
     resource: string;
-    /** When the lock expires (ms since epoch) */
+    /** When the lock expires (milliseconds since epoch) */
     expiresAt: number;
-    /** When the lock was acquired (ms since epoch) */
+    /** When the lock was acquired (milliseconds since epoch) */
     acquiredAt: number;
-    /** Worker/process identifier (for debugging) */
+    /** Worker/process identifier for debugging lock contention */
     holder?: string;
 }
 /**
- * Lock on a packfile for write operations
+ * Lock on a packfile for write operations.
+ *
+ * @description
+ * Provides methods to check lock status, release the lock, and optionally
+ * refresh the lock's TTL. Used to prevent concurrent modifications to packfiles.
+ *
+ * @example
+ * ```typescript
+ * const lock = await storage.acquireLock(packId, { ttl: 60000 });
+ * try {
+ *   // Perform operations on the packfile
+ *   if (!lock.isHeld()) {
+ *     throw new Error('Lock expired!');
+ *   }
+ * } finally {
+ *   await lock.release();
+ * }
+ * ```
  */
 export interface PackLock {
     /** Pack ID that is locked */
     packId: string;
-    /** Check if lock is still held */
+    /** Check if lock is still held (not expired and not released) */
     isHeld(): boolean;
-    /** Release the lock */
+    /** Release the lock, allowing other processes to acquire it */
     release(): Promise<void>;
-    /** Refresh the lock TTL (returns true if successful) */
+    /**
+     * Refresh the lock TTL.
+     * @returns true if refresh succeeded, false if lock was lost
+     */
     refresh?(): Promise<boolean>;
-    /** Get the underlying distributed lock handle */
+    /** Get the underlying distributed lock handle (for advanced use) */
     handle?: LockHandle;
 }
 /**
- * Options for acquiring a lock
+ * Options for acquiring a lock.
+ *
+ * @description
+ * Configures lock acquisition behavior including timeout, TTL, and holder identification.
+ *
+ * @example
+ * ```typescript
+ * const lock = await storage.acquireLock(packId, {
+ *   timeout: 10000,  // Wait up to 10 seconds
+ *   ttl: 30000,      // Lock expires after 30 seconds
+ *   holder: 'worker-1'
+ * });
+ * ```
  */
 export interface AcquireLockOptions {
-    /** Timeout in milliseconds to wait for lock */
+    /**
+     * Timeout in milliseconds to wait for lock acquisition.
+     * If 0, fails immediately if lock is held.
+     * @default 0
+     */
     timeout?: number;
-    /** TTL in milliseconds after which lock auto-expires */
+    /**
+     * TTL in milliseconds after which lock auto-expires.
+     * Prevents deadlocks if the holder crashes.
+     * @default 30000
+     */
     ttl?: number;
-    /** Worker/process identifier for debugging */
+    /** Worker/process identifier for debugging lock contention */
     holder?: string;
 }
 /**
- * Result of listing packfiles
+ * Result of listing packfiles.
+ *
+ * @description
+ * Contains the list of packfile metadata and an optional cursor for pagination.
+ *
+ * @example
+ * ```typescript
+ * let cursor: string | undefined;
+ * do {
+ *   const result = await storage.listPackfiles({ limit: 10, cursor });
+ *   for (const pack of result.items) {
+ *     console.log(pack.packId);
+ *   }
+ *   cursor = result.cursor;
+ * } while (cursor);
+ * ```
  */
 export interface ListPackfilesResult {
     /** Array of packfile metadata */
     items: PackfileMetadata[];
-    /** Cursor for pagination */
+    /** Cursor for fetching the next page of results */
     cursor?: string;
 }
 /**
- * Error thrown by R2 pack operations
+ * Error thrown by R2 pack operations.
+ *
+ * @description
+ * Custom error class for R2 packfile operations with error codes for
+ * programmatic error handling.
+ *
+ * Error codes:
+ * - `NOT_FOUND`: Packfile does not exist
+ * - `LOCKED`: Packfile is locked by another process
+ * - `INVALID_DATA`: Packfile format is invalid
+ * - `CHECKSUM_MISMATCH`: Checksum verification failed
+ * - `NETWORK_ERROR`: R2 network/connectivity issue
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await storage.downloadPackfile(packId, { required: true });
+ * } catch (error) {
+ *   if (error instanceof R2PackError) {
+ *     switch (error.code) {
+ *       case 'NOT_FOUND':
+ *         console.log('Pack does not exist');
+ *         break;
+ *       case 'CHECKSUM_MISMATCH':
+ *         console.log('Pack is corrupted');
+ *         break;
+ *     }
+ *   }
+ * }
+ * ```
  */
 export declare class R2PackError extends Error {
     readonly code: 'NOT_FOUND' | 'LOCKED' | 'INVALID_DATA' | 'CHECKSUM_MISMATCH' | 'NETWORK_ERROR';
     readonly packId?: string | undefined;
+    /**
+     * Creates a new R2PackError.
+     *
+     * @param message - Human-readable error message
+     * @param code - Error code for programmatic handling
+     * @param packId - Optional pack ID related to the error
+     */
     constructor(message: string, code: 'NOT_FOUND' | 'LOCKED' | 'INVALID_DATA' | 'CHECKSUM_MISMATCH' | 'NETWORK_ERROR', packId?: string | undefined);
 }
 /**
- * R2 Packfile Storage class
+ * R2 Packfile Storage class.
+ *
+ * @description
+ * Main class for managing Git packfiles in Cloudflare R2 object storage.
+ * Provides methods for uploading, downloading, listing, and managing packfiles
+ * with support for atomic uploads, distributed locking, and multi-pack indexing.
+ *
+ * @example
+ * ```typescript
+ * // Initialize storage
+ * const storage = new R2PackStorage({
+ *   bucket: env.GIT_BUCKET,
+ *   prefix: 'repos/my-repo/',
+ *   cacheSize: 100,
+ *   cacheTTL: 3600
+ * });
+ *
+ * // Upload a packfile atomically
+ * const result = await storage.uploadPackfile(packData, indexData);
+ *
+ * // Download with verification
+ * const download = await storage.downloadPackfile(result.packId, {
+ *   verify: true,
+ *   includeIndex: true
+ * });
+ *
+ * // List all packfiles
+ * const list = await storage.listPackfiles();
+ *
+ * // Acquire lock for write operations
+ * const lock = await storage.acquireLock(packId, { ttl: 30000 });
+ * try {
+ *   // Perform operations
+ * } finally {
+ *   await lock.release();
+ * }
+ * ```
  */
 export declare class R2PackStorage {
     private _bucket;
@@ -220,11 +575,27 @@ export declare class R2PackStorage {
     private _cacheTTL;
     private _midxCache;
     private _indexChecksums;
+    /**
+     * Creates a new R2PackStorage instance.
+     *
+     * @param options - Configuration options for the storage instance
+     *
+     * @example
+     * ```typescript
+     * const storage = new R2PackStorage({
+     *   bucket: env.MY_BUCKET,
+     *   prefix: 'repos/my-repo/',
+     *   cacheSize: 100,
+     *   cacheTTL: 3600
+     * });
+     * ```
+     */
     constructor(options: R2PackStorageOptions);
     private _buildKey;
     /**
-     * Upload a packfile and its index to R2 atomically
+     * Uploads a packfile and its index to R2 atomically.
      *
+     * @description
      * Uses a manifest-based pattern to ensure atomic uploads:
      * 1. Upload pack and index to staging paths
      * 2. Create manifest in 'staging' status
@@ -234,55 +605,224 @@ export declare class R2PackStorage {
      *
      * If the process fails at any point, the pack is not considered complete
      * until a valid manifest with status 'complete' exists.
+     *
+     * @param packData - Raw packfile bytes (must have valid PACK signature)
+     * @param indexData - Pack index file bytes
+     * @param options - Optional upload configuration
+     *
+     * @returns Upload result with pack ID, sizes, checksum, and object count
+     *
+     * @throws {R2PackError} With code 'INVALID_DATA' if packfile is invalid
+     * @throws {R2PackError} With code 'NETWORK_ERROR' if bucket is unavailable
+     *
+     * @example
+     * ```typescript
+     * const result = await storage.uploadPackfile(packData, indexData);
+     * console.log(`Uploaded: ${result.packId}`);
+     * console.log(`Objects: ${result.objectCount}`);
+     * console.log(`Checksum: ${result.checksum}`);
+     * ```
      */
     uploadPackfile(packData: Uint8Array, indexData: Uint8Array, options?: UploadPackfileOptions): Promise<PackfileUploadResult>;
     /**
-     * Get the manifest for a packfile
+     * Gets the manifest for a packfile.
+     *
+     * @description
+     * Retrieves the manifest JSON that tracks the upload status of a packfile.
+     * Returns null if no manifest exists (legacy packs or invalid pack ID).
+     *
+     * @param packId - Pack identifier to get manifest for
+     * @returns Pack manifest or null if not found
+     *
+     * @example
+     * ```typescript
+     * const manifest = await storage.getPackManifest('pack-abc123');
+     * if (manifest?.status === 'complete') {
+     *   console.log('Pack is ready for use');
+     * } else {
+     *   console.log('Pack upload is incomplete');
+     * }
+     * ```
      */
     getPackManifest(packId: string): Promise<PackManifest | null>;
     /**
-     * Check if a packfile upload is complete
+     * Checks if a packfile upload is complete.
      *
+     * @description
      * A pack is considered complete if:
      * 1. It has a manifest with status 'complete', OR
      * 2. It was uploaded before the atomic upload feature (legacy packs without manifest)
      *    AND both .pack and .idx files exist
+     *
+     * @param packId - Pack identifier to check
+     * @returns true if pack is complete and ready for use
+     *
+     * @example
+     * ```typescript
+     * if (await storage.isPackComplete(packId)) {
+     *   const data = await storage.downloadPackfile(packId);
+     * }
+     * ```
      */
     isPackComplete(packId: string): Promise<boolean>;
     /**
-     * Download a packfile from R2
+     * Downloads a packfile from R2.
+     *
+     * @description
+     * Downloads pack data with optional index file. Verifies pack completeness
+     * before downloading and optionally verifies checksum integrity.
+     *
+     * @param packId - Pack identifier to download
+     * @param options - Download options (includeIndex, verify, byteRange, required)
+     *
+     * @returns Download result with pack data, or null if not found (unless required=true)
+     *
+     * @throws {R2PackError} With code 'NOT_FOUND' if required=true and pack not found
+     * @throws {R2PackError} With code 'CHECKSUM_MISMATCH' if verify=true and verification fails
+     *
+     * @example
+     * ```typescript
+     * // Basic download
+     * const result = await storage.downloadPackfile(packId);
+     *
+     * // Download with verification and index
+     * const verified = await storage.downloadPackfile(packId, {
+     *   verify: true,
+     *   includeIndex: true
+     * });
+     *
+     * // Required download (throws if not found)
+     * const required = await storage.downloadPackfile(packId, { required: true });
+     * ```
      */
     downloadPackfile(packId: string, options?: DownloadPackfileOptions): Promise<DownloadPackfileResult | null>;
     /**
-     * Get metadata for a packfile
+     * Gets metadata for a packfile.
+     *
+     * @description
+     * Retrieves metadata about a packfile including size, object count,
+     * creation time, and checksum without downloading the full pack.
+     *
+     * @param packId - Pack identifier to get metadata for
+     * @returns Packfile metadata or null if not found
+     *
+     * @example
+     * ```typescript
+     * const metadata = await storage.getPackfileMetadata(packId);
+     * if (metadata) {
+     *   console.log(`Size: ${metadata.packSize} bytes`);
+     *   console.log(`Objects: ${metadata.objectCount}`);
+     * }
+     * ```
      */
     getPackfileMetadata(packId: string): Promise<PackfileMetadata | null>;
     /**
-     * List all packfiles
+     * Lists all packfiles in storage.
+     *
+     * @description
+     * Returns a paginated list of packfile metadata. Use the cursor for
+     * fetching subsequent pages of results.
+     *
+     * @param options - Pagination options (limit, cursor)
+     * @returns List of packfile metadata with optional cursor for pagination
+     *
+     * @example
+     * ```typescript
+     * // List first 10 packfiles
+     * const first = await storage.listPackfiles({ limit: 10 });
+     *
+     * // Get next page
+     * if (first.cursor) {
+     *   const next = await storage.listPackfiles({ limit: 10, cursor: first.cursor });
+     * }
+     * ```
      */
     listPackfiles(options?: {
         limit?: number;
         cursor?: string;
     }): Promise<ListPackfilesResult & PackfileMetadata[]>;
     /**
-     * Delete a packfile, its index, and manifest
+     * Deletes a packfile, its index, and manifest.
+     *
+     * @description
+     * Removes all files associated with a packfile and updates the
+     * multi-pack index if needed.
+     *
+     * @param packId - Pack identifier to delete
+     * @returns true if pack was deleted, false if it didn't exist
+     *
+     * @example
+     * ```typescript
+     * if (await storage.deletePackfile(packId)) {
+     *   console.log('Pack deleted successfully');
+     * } else {
+     *   console.log('Pack not found');
+     * }
+     * ```
      */
     deletePackfile(packId: string): Promise<boolean>;
     /**
-     * Download just the index file for a packfile
+     * Downloads just the index file for a packfile.
+     *
+     * @description
+     * Retrieves only the pack index file, useful for object lookups
+     * without downloading the full packfile.
+     *
+     * @param packId - Pack identifier to download index for
+     * @returns Index data or null if not found
+     *
+     * @example
+     * ```typescript
+     * const indexData = await storage.downloadIndex(packId);
+     * if (indexData) {
+     *   // Parse and use the index
+     * }
+     * ```
      */
     downloadIndex(packId: string): Promise<Uint8Array | null>;
     /**
-     * Upload a new index for an existing packfile
+     * Uploads a new index for an existing packfile.
+     *
+     * @description
+     * Replaces the index file for an existing packfile. Useful for
+     * regenerating corrupted indices or updating index format.
+     *
+     * @param packId - Pack identifier to upload index for
+     * @param indexData - New index file data
+     *
+     * @throws {R2PackError} With code 'NOT_FOUND' if packfile doesn't exist
+     *
+     * @example
+     * ```typescript
+     * const newIndex = generatePackIndex(packData);
+     * await storage.uploadIndex(packId, newIndex);
+     * ```
      */
     uploadIndex(packId: string, indexData: Uint8Array): Promise<void>;
     /**
-     * Verify that an index matches its packfile
+     * Verifies that an index matches its packfile.
+     *
+     * @description
+     * Compares the current index checksum against the stored checksum
+     * to detect corruption or tampering.
+     *
+     * @param packId - Pack identifier to verify index for
+     * @returns true if index is valid, false if missing or corrupted
+     *
+     * @example
+     * ```typescript
+     * if (await storage.verifyIndex(packId)) {
+     *   console.log('Index is valid');
+     * } else {
+     *   console.log('Index needs to be regenerated');
+     * }
+     * ```
      */
     verifyIndex(packId: string): Promise<boolean>;
     /**
-     * Clean up orphaned staging files
+     * Cleans up orphaned staging files.
      *
+     * @description
      * This should be called on startup to clean up any staging files
      * left behind by failed uploads. It will:
      * 1. List all files in the staging directory
@@ -290,68 +830,277 @@ export declare class R2PackStorage {
      * 3. If not complete, delete the staging files and any partial final files
      *
      * @returns Array of pack IDs that were cleaned up
+     *
+     * @example
+     * ```typescript
+     * // Call on worker startup
+     * const cleaned = await storage.cleanupOrphanedStagingFiles();
+     * if (cleaned.length > 0) {
+     *   console.log(`Cleaned up ${cleaned.length} orphaned uploads`);
+     * }
+     * ```
      */
     cleanupOrphanedStagingFiles(): Promise<string[]>;
     /**
-     * Rebuild the multi-pack index from all packfiles
+     * Rebuilds the multi-pack index from all packfiles.
+     *
+     * @description
+     * Creates a new MIDX by scanning all packfiles and building a sorted
+     * index of all objects. Call this after adding or removing packs.
+     *
+     * @example
+     * ```typescript
+     * await storage.rebuildMultiPackIndex();
+     * const midx = await storage.getMultiPackIndex();
+     * console.log(`Indexed ${midx.entries.length} objects`);
+     * ```
      */
     rebuildMultiPackIndex(): Promise<void>;
     /**
-     * Get the current multi-pack index
+     * Gets the current multi-pack index.
+     *
+     * @description
+     * Returns the MIDX from cache if available and not expired,
+     * otherwise fetches from R2. Returns an empty index if none exists.
+     *
+     * @returns Current multi-pack index
+     *
+     * @example
+     * ```typescript
+     * const midx = await storage.getMultiPackIndex();
+     * const entry = lookupObjectInMultiPack(midx, objectSha);
+     * if (entry) {
+     *   const packId = midx.packIds[entry.packIndex];
+     *   console.log(`Object is in pack ${packId}`);
+     * }
+     * ```
      */
     getMultiPackIndex(): Promise<MultiPackIndex>;
     /**
-     * Acquire a distributed lock on a resource using R2 conditional writes
+     * Acquires a distributed lock on a resource using R2 conditional writes.
+     *
+     * @description
+     * Uses R2's conditional write feature (ETags) to implement distributed locking.
+     * Locks automatically expire after the TTL to prevent deadlocks.
+     *
      * @param resource - Resource identifier to lock
-     * @param ttlMs - Time-to-live in milliseconds (default: 30000)
+     * @param ttlMs - Time-to-live in milliseconds
      * @param holder - Optional identifier for the lock holder (for debugging)
+     *
      * @returns LockHandle if acquired, null if lock is held by another process
+     *
+     * @example
+     * ```typescript
+     * const handle = await storage.acquireDistributedLock('my-resource', 30000, 'worker-1');
+     * if (handle) {
+     *   try {
+     *     // Do work while holding the lock
+     *   } finally {
+     *     await storage.releaseDistributedLock(handle);
+     *   }
+     * } else {
+     *   console.log('Could not acquire lock - resource is busy');
+     * }
+     * ```
      */
     acquireDistributedLock(resource: string, ttlMs?: number, holder?: string): Promise<LockHandle | null>;
     /**
-     * Release a distributed lock
+     * Releases a distributed lock.
+     *
+     * @description
+     * Releases the lock only if the caller still owns it (verified by lockId).
+     * Safe to call even if lock has expired or been taken by another process.
+     *
      * @param handle - Lock handle returned from acquireDistributedLock
+     *
+     * @example
+     * ```typescript
+     * const handle = await storage.acquireDistributedLock('resource');
+     * if (handle) {
+     *   try {
+     *     // Do work
+     *   } finally {
+     *     await storage.releaseDistributedLock(handle);
+     *   }
+     * }
+     * ```
      */
     releaseDistributedLock(handle: LockHandle): Promise<void>;
     /**
-     * Refresh a distributed lock to extend its TTL
+     * Refreshes a distributed lock to extend its TTL.
+     *
+     * @description
+     * Extends the lock's expiration time. Useful for long-running operations
+     * that need to hold the lock longer than the original TTL.
+     *
      * @param handle - Lock handle to refresh
-     * @param ttlMs - New TTL in milliseconds (default: 30000)
+     * @param ttlMs - New TTL in milliseconds
+     *
      * @returns true if refresh succeeded, false if lock was lost
+     *
+     * @example
+     * ```typescript
+     * const handle = await storage.acquireDistributedLock('resource', 30000);
+     * if (handle) {
+     *   // Do some work...
+     *
+     *   // Extend the lock for another 30 seconds
+     *   if (await storage.refreshDistributedLock(handle, 30000)) {
+     *     // Continue working
+     *   } else {
+     *     // Lock was lost, abort operation
+     *   }
+     * }
+     * ```
      */
     refreshDistributedLock(handle: LockHandle, ttlMs?: number): Promise<boolean>;
     /**
-     * Clean up expired locks from R2 storage
+     * Cleans up expired locks from R2 storage.
+     *
+     * @description
+     * Scans all lock files and removes those that have expired.
      * This should be called periodically to remove stale lock files
+     * left by crashed processes.
+     *
      * @returns Number of locks cleaned up
+     *
+     * @example
+     * ```typescript
+     * // Run periodically (e.g., every 5 minutes)
+     * const cleaned = await storage.cleanupExpiredLocks();
+     * console.log(`Cleaned up ${cleaned} expired locks`);
+     * ```
      */
     cleanupExpiredLocks(): Promise<number>;
     /**
-     * Acquire a lock on a packfile (backward-compatible wrapper)
-     * Uses distributed locking with R2 conditional writes
+     * Acquires a lock on a packfile (backward-compatible wrapper).
+     *
+     * @description
+     * High-level API for acquiring a pack lock with optional timeout.
+     * Uses distributed locking with R2 conditional writes internally.
+     *
+     * @param packId - Pack identifier to lock
+     * @param options - Lock acquisition options
+     *
+     * @returns PackLock interface for managing the lock
+     *
+     * @throws {R2PackError} With code 'LOCKED' if lock cannot be acquired
+     *
+     * @example
+     * ```typescript
+     * const lock = await storage.acquireLock(packId, {
+     *   timeout: 10000,
+     *   ttl: 30000,
+     *   holder: 'my-worker'
+     * });
+     *
+     * try {
+     *   // Perform pack operations
+     *   if (lock.refresh) {
+     *     await lock.refresh(); // Extend lock if needed
+     *   }
+     * } finally {
+     *   await lock.release();
+     * }
+     * ```
      */
     acquireLock(packId: string, options?: AcquireLockOptions): Promise<PackLock>;
 }
 /**
- * Upload a packfile to R2
+ * Uploads a packfile to R2.
+ *
+ * @description
+ * Standalone function for uploading a packfile. Creates a temporary
+ * R2PackStorage instance internally.
+ *
+ * @param bucket - R2 bucket instance
+ * @param packData - Raw packfile bytes
+ * @param indexData - Pack index file bytes
+ * @param options - Optional configuration including prefix
+ *
+ * @returns Upload result with pack ID, sizes, and checksum
+ *
+ * @throws {R2PackError} If packfile is invalid or upload fails
+ *
+ * @example
+ * ```typescript
+ * const result = await uploadPackfile(bucket, packData, indexData, {
+ *   prefix: 'repos/my-repo/'
+ * });
+ * console.log(`Uploaded: ${result.packId}`);
+ * ```
  */
 export declare function uploadPackfile(bucket: R2Bucket, packData: Uint8Array, indexData: Uint8Array, options?: {
     prefix?: string;
 }): Promise<PackfileUploadResult>;
 /**
- * Download a packfile from R2
+ * Downloads a packfile from R2.
+ *
+ * @description
+ * Standalone function for downloading a packfile. Creates a temporary
+ * R2PackStorage instance internally.
+ *
+ * @param bucket - R2 bucket instance
+ * @param packId - Pack identifier to download
+ * @param options - Download options and prefix
+ *
+ * @returns Download result or null if not found
+ *
+ * @throws {R2PackError} If required=true and pack not found, or verification fails
+ *
+ * @example
+ * ```typescript
+ * const result = await downloadPackfile(bucket, packId, {
+ *   prefix: 'repos/my-repo/',
+ *   verify: true
+ * });
+ * ```
  */
 export declare function downloadPackfile(bucket: R2Bucket, packId: string, options?: DownloadPackfileOptions & {
     prefix?: string;
 }): Promise<DownloadPackfileResult | null>;
 /**
- * Get packfile metadata
+ * Gets packfile metadata.
+ *
+ * @description
+ * Standalone function for retrieving packfile metadata without downloading
+ * the full pack.
+ *
+ * @param bucket - R2 bucket instance
+ * @param packId - Pack identifier
+ * @param options - Optional prefix configuration
+ *
+ * @returns Packfile metadata or null if not found
+ *
+ * @example
+ * ```typescript
+ * const metadata = await getPackfileMetadata(bucket, packId);
+ * if (metadata) {
+ *   console.log(`Objects: ${metadata.objectCount}`);
+ * }
+ * ```
  */
 export declare function getPackfileMetadata(bucket: R2Bucket, packId: string, options?: {
     prefix?: string;
 }): Promise<PackfileMetadata | null>;
 /**
- * List all packfiles
+ * Lists all packfiles.
+ *
+ * @description
+ * Standalone function for listing packfiles with pagination support.
+ *
+ * @param bucket - R2 bucket instance
+ * @param options - Prefix and pagination options
+ *
+ * @returns Array of packfile metadata
+ *
+ * @example
+ * ```typescript
+ * const packs = await listPackfiles(bucket, {
+ *   prefix: 'repos/my-repo/',
+ *   limit: 50
+ * });
+ * ```
  */
 export declare function listPackfiles(bucket: R2Bucket, options?: {
     prefix?: string;
@@ -359,34 +1108,148 @@ export declare function listPackfiles(bucket: R2Bucket, options?: {
     cursor?: string;
 }): Promise<PackfileMetadata[]>;
 /**
- * Delete a packfile
+ * Deletes a packfile.
+ *
+ * @description
+ * Standalone function for deleting a packfile and its associated files.
+ *
+ * @param bucket - R2 bucket instance
+ * @param packId - Pack identifier to delete
+ * @param options - Optional prefix configuration
+ *
+ * @returns true if deleted, false if not found
+ *
+ * @example
+ * ```typescript
+ * if (await deletePackfile(bucket, packId)) {
+ *   console.log('Deleted');
+ * }
+ * ```
  */
 export declare function deletePackfile(bucket: R2Bucket, packId: string, options?: {
     prefix?: string;
 }): Promise<boolean>;
 /**
- * Create a multi-pack index from all packfiles in the bucket
+ * Creates a multi-pack index from all packfiles in the bucket.
+ *
+ * @description
+ * Standalone function that rebuilds the MIDX and returns the result.
+ *
+ * @param bucket - R2 bucket instance
+ * @param options - Optional prefix configuration
+ *
+ * @returns The newly created multi-pack index
+ *
+ * @example
+ * ```typescript
+ * const midx = await createMultiPackIndex(bucket, { prefix: 'repos/my-repo/' });
+ * console.log(`Indexed ${midx.entries.length} objects`);
+ * ```
  */
 export declare function createMultiPackIndex(bucket: R2Bucket, options?: {
     prefix?: string;
 }): Promise<MultiPackIndex>;
 /**
- * Parse a multi-pack index from raw bytes
+ * Parses a multi-pack index from raw bytes.
+ *
+ * @description
+ * Deserializes the binary MIDX format into a MultiPackIndex structure.
+ * Validates the signature and format.
+ *
+ * @param data - Raw MIDX bytes
+ * @returns Parsed multi-pack index
+ *
+ * @throws {R2PackError} With code 'INVALID_DATA' if format is invalid
+ *
+ * @example
+ * ```typescript
+ * const midxData = await bucket.get('packs/multi-pack-index');
+ * if (midxData) {
+ *   const midx = parseMultiPackIndex(new Uint8Array(await midxData.arrayBuffer()));
+ *   console.log(`Contains ${midx.entries.length} objects`);
+ * }
+ * ```
  */
 export declare function parseMultiPackIndex(data: Uint8Array): MultiPackIndex;
 /**
- * Look up an object in the multi-pack index using binary search
+ * Looks up an object in the multi-pack index using binary search.
+ *
+ * @description
+ * Efficiently finds an object's location across all packs using O(log n)
+ * binary search on the sorted entries.
+ *
+ * @param midx - Multi-pack index to search
+ * @param objectId - 40-character hex SHA-1 object ID to find
+ *
+ * @returns Entry with pack index and offset, or null if not found
+ *
+ * @example
+ * ```typescript
+ * const midx = await storage.getMultiPackIndex();
+ * const entry = lookupObjectInMultiPack(midx, 'abc123...');
+ * if (entry) {
+ *   const packId = midx.packIds[entry.packIndex];
+ *   const offset = entry.offset;
+ *   console.log(`Found in ${packId} at offset ${offset}`);
+ * }
+ * ```
  */
 export declare function lookupObjectInMultiPack(midx: MultiPackIndex, objectId: string): MultiPackIndexEntry | null;
 /**
- * Acquire a lock on a packfile
+ * Acquires a lock on a packfile.
+ *
+ * @description
+ * Standalone function for acquiring a pack lock using distributed locking.
+ *
+ * @param bucket - R2 bucket instance
+ * @param packId - Pack identifier to lock
+ * @param options - Lock options and prefix
+ *
+ * @returns PackLock interface for managing the lock
+ *
+ * @throws {R2PackError} With code 'LOCKED' if lock cannot be acquired
+ *
+ * @example
+ * ```typescript
+ * const lock = await acquirePackLock(bucket, packId, {
+ *   prefix: 'repos/my-repo/',
+ *   timeout: 10000,
+ *   ttl: 30000
+ * });
+ *
+ * try {
+ *   // Do work
+ * } finally {
+ *   await lock.release();
+ * }
+ * ```
  */
 export declare function acquirePackLock(bucket: R2Bucket, packId: string, options?: AcquireLockOptions & {
     prefix?: string;
 }): Promise<PackLock>;
 /**
- * Release a lock on a packfile
- * Note: This function requires a valid PackLock with a handle to properly release distributed locks
+ * Releases a lock on a packfile.
+ *
+ * @description
+ * Standalone function for releasing a pack lock.
+ *
+ * Note: This function requires a valid PackLock with a handle to properly
+ * release distributed locks. For best results, use the lock.release() method
+ * on the PackLock object returned from acquirePackLock.
+ *
+ * @param bucket - R2 bucket instance
+ * @param packId - Pack identifier to unlock
+ * @param options - Optional prefix configuration
+ *
+ * @example
+ * ```typescript
+ * // Preferred: use lock.release()
+ * const lock = await acquirePackLock(bucket, packId);
+ * await lock.release();
+ *
+ * // Alternative: use standalone function (less safe)
+ * await releasePackLock(bucket, packId);
+ * ```
  */
 export declare function releasePackLock(bucket: R2Bucket, packId: string, options?: {
     prefix?: string;