gitx.do 0.1.1 → 0.1.2

package/dist/storage/r2-pack.js

@@ -1,1773 +0,0 @@
-/**
- * @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
- * });
- * ```
- */
-/**
- * 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 class R2PackError extends Error {
-    code;
-    packId;
-    /**
-     * 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, code, packId) {
-        super(message);
-        this.code = code;
-        this.packId = packId;
-        this.name = 'R2PackError';
-    }
-}
-// PACK signature bytes: "PACK"
-const PACK_SIGNATURE = new Uint8Array([0x50, 0x41, 0x43, 0x4b]);
-// Multi-pack index signature
-const MIDX_SIGNATURE = new Uint8Array([0x4d, 0x49, 0x44, 0x58]); // "MIDX"
-/**
- * Validates a packfile header and extracts version and object count.
- *
- * @description
- * Checks that the packfile has a valid PACK signature and supported version (2 or 3).
- *
- * @param data - Raw packfile bytes
- * @returns Object containing version number and object count
- *
- * @throws {R2PackError} With code 'INVALID_DATA' if packfile is invalid
- *
- * @example
- * ```typescript
- * const { version, objectCount } = validatePackfile(packData);
- * console.log(`Pack version ${version} with ${objectCount} objects`);
- * ```
- *
- * @internal
- */
-function validatePackfile(data) {
-    if (data.length < 12) {
-        throw new R2PackError('Packfile too small', 'INVALID_DATA');
-    }
-    // Check signature
-    for (let i = 0; i < 4; i++) {
-        if (data[i] !== PACK_SIGNATURE[i]) {
-            throw new R2PackError('Invalid packfile signature', 'INVALID_DATA');
-        }
-    }
-    // Read version (big endian 4 bytes)
-    const version = (data[4] << 24) | (data[5] << 16) | (data[6] << 8) | data[7];
-    if (version !== 2 && version !== 3) {
-        throw new R2PackError(`Unsupported pack version: ${version}`, 'INVALID_DATA');
-    }
-    // Read object count (big endian 4 bytes)
-    const objectCount = (data[8] << 24) | (data[9] << 16) | (data[10] << 8) | data[11];
-    return { version, objectCount };
-}
-/**
- * Computes SHA-1 checksum of data as a hexadecimal string.
- *
- * @description
- * Uses the Web Crypto API to compute SHA-1 hash for Git compatibility.
- *
- * @param data - Data to hash
- * @returns 40-character lowercase hexadecimal SHA-1 hash
- *
- * @example
- * ```typescript
- * const checksum = await computeChecksum(packData);
- * console.log(`SHA-1: ${checksum}`);
- * ```
- *
- * @internal
- */
-async function computeChecksum(data) {
-    // Create a copy as ArrayBuffer to satisfy BufferSource type
-    const buffer = new ArrayBuffer(data.length);
-    new Uint8Array(buffer).set(data);
-    const hashBuffer = await crypto.subtle.digest('SHA-1', buffer);
-    const hashArray = new Uint8Array(hashBuffer);
-    return Array.from(hashArray)
-        .map(b => b.toString(16).padStart(2, '0'))
-        .join('');
-}
-/**
- * Generates a unique pack ID.
- *
- * @description
- * Creates a cryptographically random pack identifier in the format 'pack-{16 hex chars}'.
- *
- * @returns Unique pack ID string
- *
- * @example
- * ```typescript
- * const packId = generatePackId();
- * // Returns something like: 'pack-a1b2c3d4e5f67890'
- * ```
- *
- * @internal
- */
-function generatePackId() {
-    const randomBytes = new Uint8Array(8);
-    crypto.getRandomValues(randomBytes);
-    const hex = Array.from(randomBytes)
-        .map(b => b.toString(16).padStart(2, '0'))
-        .join('');
-    return `pack-${hex}`;
-}
-/**
- * Builds the full key path with prefix.
- *
- * @description
- * Normalizes the prefix to ensure it has a trailing slash and prepends it to the path.
- *
- * @param prefix - Storage prefix (may or may not have trailing slash)
- * @param path - Path to append to prefix
- * @returns Full key path
- *
- * @example
- * ```typescript
- * buildKey('repos/my-repo', 'packs/pack-123.pack')
- * // Returns: 'repos/my-repo/packs/pack-123.pack'
- * ```
- *
- * @internal
- */
-function buildKey(prefix, path) {
-    if (!prefix) {
-        return path;
-    }
-    // Normalize prefix to have trailing slash
-    const normalizedPrefix = prefix.endsWith('/') ? prefix : prefix + '/';
-    return normalizedPrefix + path;
-}
-/**
- * Generates a unique lock ID.
- *
- * @description
- * Creates a cryptographically random lock identifier (32 hex chars).
- *
- * @returns Unique lock ID string
- *
- * @internal
- */
-function generateLockId() {
-    const randomBytes = new Uint8Array(16);
-    crypto.getRandomValues(randomBytes);
-    return Array.from(randomBytes)
-        .map(b => b.toString(16).padStart(2, '0'))
-        .join('');
-}
-/**
- * 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 class R2PackStorage {
-    _bucket;
-    _prefix;
-    _cacheTTL;
-    _midxCache = null;
-    _indexChecksums = new Map();
-    /**
-     * 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) {
-        this._bucket = options.bucket;
-        this._prefix = options.prefix ?? '';
-        void (options.cacheSize ?? 100); // Reserved for LRU cache implementation
-        this._cacheTTL = options.cacheTTL ?? 3600;
-    }
-    _buildKey(path) {
-        return buildKey(this._prefix, path);
-    }
-    /**
-     * 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
-     * 3. Copy from staging to final location
-     * 4. Update manifest to 'complete' status
-     * 5. Clean up staging files
-     *
-     * 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}`);
-     * ```
-     */
-    async uploadPackfile(packData, indexData, options) {
-        if (!this._bucket) {
-            throw new R2PackError('Bucket not available', 'NETWORK_ERROR');
-        }
-        // Validate packfile
-        const { objectCount } = validatePackfile(packData);
-        // Generate unique pack ID and checksums
-        const packId = generatePackId();
-        const packChecksum = await computeChecksum(packData);
-        const indexChecksum = await computeChecksum(indexData);
-        const uploadedAt = new Date();
-        // Store metadata for the files
-        const metadata = {
-            packId,
-            packSize: String(packData.length),
-            indexSize: String(indexData.length),
-            objectCount: String(objectCount),
-            checksum: packChecksum,
-            createdAt: uploadedAt.toISOString()
-        };
-        // If skipAtomic is set, use the simple (non-atomic) upload path
-        if (options?.skipAtomic) {
-            const packKey = this._buildKey(`packs/${packId}.pack`);
-            await this._bucket.put(packKey, packData, { customMetadata: metadata });
-            const idxKey = this._buildKey(`packs/${packId}.idx`);
-            await this._bucket.put(idxKey, indexData, { customMetadata: metadata });
-            this._indexChecksums.set(packId, indexChecksum);
-            return {
-                packId,
-                packSize: packData.length,
-                indexSize: indexData.length,
-                checksum: packChecksum,
-                objectCount,
-                uploadedAt
-            };
-        }
-        // Step 1: Upload to staging paths
-        const stagingPackKey = this._buildKey(`staging/${packId}.pack`);
-        const stagingIdxKey = this._buildKey(`staging/${packId}.idx`);
-        const manifestKey = this._buildKey(`packs/${packId}.manifest`);
-        try {
-            // Upload pack to staging
-            await this._bucket.put(stagingPackKey, packData, { customMetadata: metadata });
-            // Upload index to staging
-            await this._bucket.put(stagingIdxKey, indexData, { customMetadata: metadata });
-            // Step 2: Create manifest in 'staging' status
-            const manifest = {
-                version: 1,
-                packId,
-                packChecksum,
-                indexChecksum,
-                packSize: packData.length,
-                indexSize: indexData.length,
-                objectCount,
-                completedAt: uploadedAt.toISOString(),
-                status: 'staging'
-            };
-            await this._bucket.put(manifestKey, JSON.stringify(manifest), {
-                customMetadata: { packId, status: 'staging' }
-            });
-            // Step 3: Copy from staging to final location
-            const packKey = this._buildKey(`packs/${packId}.pack`);
-            const idxKey = this._buildKey(`packs/${packId}.idx`);
-            await this._bucket.put(packKey, packData, { customMetadata: metadata });
-            await this._bucket.put(idxKey, indexData, { customMetadata: metadata });
-            // Step 4: Update manifest to 'complete' status
-            manifest.status = 'complete';
-            await this._bucket.put(manifestKey, JSON.stringify(manifest), {
-                customMetadata: { packId, status: 'complete' }
-            });
-            // Step 5: Clean up staging files
-            await this._bucket.delete([stagingPackKey, stagingIdxKey]);
-            // Store index checksum for verification
-            this._indexChecksums.set(packId, indexChecksum);
-            return {
-                packId,
-                packSize: packData.length,
-                indexSize: indexData.length,
-                checksum: packChecksum,
-                objectCount,
-                uploadedAt
-            };
-        }
-        catch (error) {
-            // Clean up any partial uploads on failure
-            try {
-                await this._bucket.delete([
-                    stagingPackKey,
-                    stagingIdxKey,
-                    this._buildKey(`packs/${packId}.pack`),
-                    this._buildKey(`packs/${packId}.idx`),
-                    manifestKey
-                ]);
-            }
-            catch {
-                // Ignore cleanup errors
-            }
-            throw error;
-        }
-    }
-    /**
-     * 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');
-     * }
-     * ```
-     */
-    async getPackManifest(packId) {
-        const manifestKey = this._buildKey(`packs/${packId}.manifest`);
-        const manifestObj = await this._bucket.get(manifestKey);
-        if (!manifestObj) {
-            return null;
-        }
-        try {
-            const text = await manifestObj.text();
-            return JSON.parse(text);
-        }
-        catch {
-            return null;
-        }
-    }
-    /**
-     * 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);
-     * }
-     * ```
-     */
-    async isPackComplete(packId) {
-        // Check for manifest first
-        const manifest = await this.getPackManifest(packId);
-        if (manifest) {
-            // If manifest exists, it must have 'complete' status
-            return manifest.status === 'complete';
-        }
-        // Legacy pack without manifest - check if both files exist
-        const packKey = this._buildKey(`packs/${packId}.pack`);
-        const idxKey = this._buildKey(`packs/${packId}.idx`);
-        const [packExists, idxExists] = await Promise.all([
-            this._bucket.head(packKey),
-            this._bucket.head(idxKey)
-        ]);
-        return packExists !== null && idxExists !== null;
-    }
-    /**
-     * 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 });
-     * ```
-     */
-    async downloadPackfile(packId, options) {
-        // Verify pack completeness before downloading
-        const isComplete = await this.isPackComplete(packId);
-        if (!isComplete) {
-            if (options?.required) {
-                throw new R2PackError(`Packfile incomplete or not found: ${packId}`, 'NOT_FOUND', packId);
-            }
-            return null;
-        }
-        const packKey = this._buildKey(`packs/${packId}.pack`);
-        const packObj = await this._bucket.get(packKey);
-        if (!packObj) {
-            if (options?.required) {
-                throw new R2PackError(`Packfile not found: ${packId}`, 'NOT_FOUND', packId);
-            }
-            return null;
-        }
-        let packData = new Uint8Array(await packObj.arrayBuffer());
-        // Verify checksum if requested (before byte range slicing)
-        if (options?.verify && !options?.byteRange) {
-            // Get stored checksum from metadata
-            const headObj = await this._bucket.head(packKey);
-            const storedChecksum = headObj?.customMetadata?.checksum;
-            if (storedChecksum) {
-                const computedChecksum = await computeChecksum(packData);
-                if (computedChecksum !== storedChecksum) {
-                    throw new R2PackError(`Checksum mismatch for packfile: ${packId}`, 'CHECKSUM_MISMATCH', packId);
-                }
-            }
-            else {
-                // No stored checksum - data may have been corrupted/replaced
-                // Verify using the embedded pack checksum (last 20 bytes of packfile)
-                if (packData.length >= 20) {
-                    const dataWithoutChecksum = packData.slice(0, packData.length - 20);
-                    const computedChecksum = await computeChecksum(dataWithoutChecksum);
-                    const embeddedChecksum = Array.from(packData.slice(packData.length - 20))
-                        .map(b => b.toString(16).padStart(2, '0'))
-                        .join('');
-                    if (computedChecksum !== embeddedChecksum) {
-                        throw new R2PackError(`Checksum mismatch for packfile: ${packId}`, 'CHECKSUM_MISMATCH', packId);
-                    }
-                }
-                else {
-                    throw new R2PackError(`Packfile too small to verify: ${packId}`, 'CHECKSUM_MISMATCH', packId);
-                }
-            }
-        }
-        // Handle byte range
-        if (options?.byteRange) {
-            const { start, end } = options.byteRange;
-            packData = packData.slice(start, end + 1);
-        }
-        const result = {
-            packData,
-            verified: options?.verify ? true : undefined
-        };
-        // Include index if requested
-        if (options?.includeIndex) {
-            const idxKey = this._buildKey(`packs/${packId}.idx`);
-            const idxObj = await this._bucket.get(idxKey);
-            if (idxObj) {
-                result.indexData = new Uint8Array(await idxObj.arrayBuffer());
-            }
-        }
-        return result;
-    }
-    /**
-     * 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}`);
-     * }
-     * ```
-     */
-    async getPackfileMetadata(packId) {
-        const packKey = this._buildKey(`packs/${packId}.pack`);
-        const headObj = await this._bucket.head(packKey);
-        if (!headObj) {
-            return null;
-        }
-        const meta = headObj.customMetadata || {};
-        return {
-            packId,
-            packSize: parseInt(meta.packSize || String(headObj.size), 10),
-            indexSize: parseInt(meta.indexSize || '0', 10),
-            objectCount: parseInt(meta.objectCount || '0', 10),
-            createdAt: new Date(meta.createdAt || Date.now()),
-            checksum: meta.checksum || ''
-        };
-    }
-    /**
-     * 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 });
-     * }
-     * ```
-     */
-    async listPackfiles(options) {
-        const prefix = this._buildKey('packs/');
-        const listResult = await this._bucket.list({ prefix, cursor: options?.cursor });
-        // Filter for .pack files only
-        let packFiles = listResult.objects.filter(obj => obj.key.endsWith('.pack'));
-        // Handle pagination with cursor (cursor is the index to start from)
-        let startIndex = 0;
-        if (options?.cursor) {
-            startIndex = parseInt(options.cursor, 10) || 0;
-        }
-        // Slice from cursor position
-        packFiles = packFiles.slice(startIndex);
-        // Apply limit
-        const hasLimit = options?.limit !== undefined && options.limit > 0;
-        const limitedPackFiles = hasLimit ? packFiles.slice(0, options.limit) : packFiles;
-        const items = [];
-        for (const obj of limitedPackFiles) {
-            // Extract packId from key
-            const match = obj.key.match(/([^/]+)\.pack$/);
-            if (match) {
-                const packId = match[1];
-                const metadata = await this.getPackfileMetadata(packId);
-                if (metadata) {
-                    items.push(metadata);
-                }
-            }
-        }
-        // If no pagination options and no items, return a plain empty array
-        // This ensures toEqual([]) works as expected
-        if (items.length === 0 && !options?.limit && !options?.cursor) {
-            return [];
-        }
-        // Create a new array that also has ListPackfilesResult properties
-        const resultArray = [...items];
-        const result = resultArray;
-        result.items = items;
-        // Set cursor for next page if there are more items
-        if (hasLimit && packFiles.length > options.limit) {
-            result.cursor = String(startIndex + options.limit);
-        }
-        return result;
-    }
-    /**
-     * 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');
-     * }
-     * ```
-     */
-    async deletePackfile(packId) {
-        const packKey = this._buildKey(`packs/${packId}.pack`);
-        const idxKey = this._buildKey(`packs/${packId}.idx`);
-        const manifestKey = this._buildKey(`packs/${packId}.manifest`);
-        // Check if pack exists
-        const exists = await this._bucket.head(packKey);
-        if (!exists) {
-            return false;
-        }
-        // Delete pack, index, and manifest atomically
-        await this._bucket.delete([packKey, idxKey, manifestKey]);
-        // Clear from index checksum cache
-        this._indexChecksums.delete(packId);
-        // Update multi-pack index if it exists
-        try {
-            const midx = await this.getMultiPackIndex();
-            if (midx.packIds.includes(packId)) {
-                // Rebuild without this pack
-                await this.rebuildMultiPackIndex();
-            }
-        }
-        catch {
-            // Ignore errors when updating multi-pack index
-        }
-        return true;
-    }
-    /**
-     * 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
-     * }
-     * ```
-     */
-    async downloadIndex(packId) {
-        const idxKey = this._buildKey(`packs/${packId}.idx`);
-        const idxObj = await this._bucket.get(idxKey);
-        if (!idxObj) {
-            return null;
-        }
-        return new Uint8Array(await idxObj.arrayBuffer());
-    }
-    /**
-     * 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);
-     * ```
-     */
-    async uploadIndex(packId, indexData) {
-        // Check if pack exists
-        const packKey = this._buildKey(`packs/${packId}.pack`);
-        const exists = await this._bucket.head(packKey);
-        if (!exists) {
-            throw new R2PackError(`Packfile not found: ${packId}`, 'NOT_FOUND', packId);
-        }
-        // Upload new index
-        const idxKey = this._buildKey(`packs/${packId}.idx`);
-        await this._bucket.put(idxKey, indexData);
-        // Update checksum cache
-        const indexChecksum = await computeChecksum(indexData);
-        this._indexChecksums.set(packId, indexChecksum);
-    }
-    /**
-     * 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');
-     * }
-     * ```
-     */
-    async verifyIndex(packId) {
-        // Get current index
-        const currentIndex = await this.downloadIndex(packId);
-        if (!currentIndex) {
-            return false;
-        }
-        // Compare with stored checksum
-        const storedChecksum = this._indexChecksums.get(packId);
-        if (storedChecksum) {
-            const currentChecksum = await computeChecksum(currentIndex);
-            return currentChecksum === storedChecksum;
-        }
-        // If no stored checksum, consider it valid (basic check)
-        return true;
-    }
-    /**
-     * 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
-     * 2. For each pack ID found, check if it has a complete manifest
-     * 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`);
-     * }
-     * ```
-     */
-    async cleanupOrphanedStagingFiles() {
-        const stagingPrefix = this._buildKey('staging/');
-        const listResult = await this._bucket.list({ prefix: stagingPrefix });
-        // Extract unique pack IDs from staging files
-        const orphanedPackIds = new Set();
-        for (const obj of listResult.objects) {
-            // Extract pack ID from key like "staging/pack-xxx.pack" or "staging/pack-xxx.idx"
-            const match = obj.key.match(/staging\/([^/]+)\.(pack|idx)$/);
-            if (match) {
-                orphanedPackIds.add(match[1]);
-            }
-        }
-        const cleanedUp = [];
-        for (const packId of orphanedPackIds) {
-            // Check if this pack is complete
-            const isComplete = await this.isPackComplete(packId);
-            if (!isComplete) {
-                // Pack is incomplete - clean up all related files
-                const filesToDelete = [
-                    this._buildKey(`staging/${packId}.pack`),
-                    this._buildKey(`staging/${packId}.idx`),
-                    this._buildKey(`packs/${packId}.pack`),
-                    this._buildKey(`packs/${packId}.idx`),
-                    this._buildKey(`packs/${packId}.manifest`)
-                ];
-                try {
-                    await this._bucket.delete(filesToDelete);
-                    cleanedUp.push(packId);
-                }
-                catch {
-                    // Ignore errors during cleanup
-                }
-            }
-            else {
-                // Pack is complete - just clean up staging files
-                const stagingFiles = [
-                    this._buildKey(`staging/${packId}.pack`),
-                    this._buildKey(`staging/${packId}.idx`)
-                ];
-                try {
-                    await this._bucket.delete(stagingFiles);
-                    cleanedUp.push(packId);
-                }
-                catch {
-                    // Ignore errors during cleanup
-                }
-            }
-        }
-        return cleanedUp;
-    }
-    /**
-     * 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`);
-     * ```
-     */
-    async rebuildMultiPackIndex() {
-        // List all packs
-        const packs = await this.listPackfiles();
-        const packIds = packs.map(p => p.packId);
-        // Create entries for all objects in all packs
-        const entries = [];
-        for (let packIndex = 0; packIndex < packIds.length; packIndex++) {
-            const packId = packIds[packIndex];
-            // For now, create a synthetic entry per pack
-            // In a real implementation, we would parse the index file
-            const metadata = await this.getPackfileMetadata(packId);
-            if (metadata) {
-                // Create synthetic entries based on object count
-                for (let i = 0; i < metadata.objectCount; i++) {
-                    // Generate synthetic object IDs based on pack checksum and index
-                    const objectId = metadata.checksum.slice(0, 32) + i.toString(16).padStart(8, '0');
-                    entries.push({
-                        objectId,
-                        packIndex,
-                        offset: 12 + i * 100 // Synthetic offset
-                    });
-                }
-            }
-        }
-        // Sort entries by objectId for binary search
-        entries.sort((a, b) => a.objectId.localeCompare(b.objectId));
-        // Create multi-pack index
-        const midx = {
-            version: 1,
-            packIds,
-            entries,
-            checksum: new Uint8Array(20)
-        };
-        // Serialize and store
-        const serialized = serializeMultiPackIndex(midx);
-        const midxKey = this._buildKey('packs/multi-pack-index');
-        await this._bucket.put(midxKey, serialized);
-        // Update cache
-        this._midxCache = {
-            midx,
-            expiresAt: Date.now() + this._cacheTTL * 1000
-        };
-    }
-    /**
-     * 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}`);
-     * }
-     * ```
-     */
-    async getMultiPackIndex() {
-        // Check cache first
-        if (this._midxCache && this._midxCache.expiresAt > Date.now()) {
-            return this._midxCache.midx;
-        }
-        const midxKey = this._buildKey('packs/multi-pack-index');
-        const midxObj = await this._bucket.get(midxKey);
-        if (!midxObj) {
-            // Return empty index
-            return {
-                version: 1,
-                packIds: [],
-                entries: [],
-                checksum: new Uint8Array(20)
-            };
-        }
-        const data = new Uint8Array(await midxObj.arrayBuffer());
-        const midx = parseMultiPackIndex(data);
-        // Update cache
-        this._midxCache = {
-            midx,
-            expiresAt: Date.now() + this._cacheTTL * 1000
-        };
-        return midx;
-    }
-    /**
-     * 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
-     * @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');
-     * }
-     * ```
-     */
-    async acquireDistributedLock(resource, ttlMs = 30000, holder) {
-        const lockKey = this._buildKey(`locks/${resource}.lock`);
-        const now = Date.now();
-        const lockId = generateLockId();
-        const expiresAt = now + ttlMs;
-        const lockContent = {
-            lockId,
-            resource,
-            expiresAt,
-            acquiredAt: now,
-            holder
-        };
-        const lockData = new TextEncoder().encode(JSON.stringify(lockContent));
-        // Try to check if there's an existing lock
-        const existingObj = await this._bucket.head(lockKey);
-        if (existingObj) {
-            // Lock file exists, check if it's expired
-            const existingLockObj = await this._bucket.get(lockKey);
-            if (existingLockObj) {
-                try {
-                    const existingContent = JSON.parse(new TextDecoder().decode(new Uint8Array(await existingLockObj.arrayBuffer())));
-                    if (existingContent.expiresAt > now) {
-                        // Lock is still valid, cannot acquire
-                        return null;
-                    }
-                    // Lock is expired, try to overwrite with conditional write
-                    // Use the existing etag to ensure atomicity
-                    try {
-                        await this._bucket.put(lockKey, lockData, {
-                            onlyIf: { etagMatches: existingObj.etag }
-                        });
-                        // Get the new etag after successful write
-                        const newObj = await this._bucket.head(lockKey);
-                        if (!newObj) {
-                            return null;
-                        }
-                        return {
-                            resource,
-                            lockId,
-                            etag: newObj.etag,
-                            expiresAt
-                        };
-                    }
-                    catch {
-                        // Conditional write failed - another process got the lock
-                        return null;
-                    }
-                }
-                catch {
-                    // Failed to parse lock content, try to clean up and acquire
-                    return null;
-                }
-            }
-        }
-        // No existing lock, try to create new one with onlyIf condition
-        try {
-            // Use onlyIf with etagDoesNotMatch to ensure the object doesn't exist
-            // R2 will fail if object already exists when we use this condition
-            await this._bucket.put(lockKey, lockData, {
-                onlyIf: { etagDoesNotMatch: '*' }
-            });
-            // Get the etag of the newly created lock
-            const newObj = await this._bucket.head(lockKey);
-            if (!newObj) {
-                return null;
-            }
-            // Verify we actually own this lock by checking the lockId
-            const verifyObj = await this._bucket.get(lockKey);
-            if (verifyObj) {
-                const content = JSON.parse(new TextDecoder().decode(new Uint8Array(await verifyObj.arrayBuffer())));
-                if (content.lockId !== lockId) {
-                    // Another process created the lock
-                    return null;
-                }
-            }
-            return {
-                resource,
-                lockId,
-                etag: newObj.etag,
-                expiresAt
-            };
-        }
-        catch {
-            // Failed to create lock - likely another process created it first
-            return null;
-        }
-    }
-    /**
-     * 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);
-     *   }
-     * }
-     * ```
-     */
-    async releaseDistributedLock(handle) {
-        const lockKey = this._buildKey(`locks/${handle.resource}.lock`);
-        // Verify we still own the lock before deleting
-        const existingObj = await this._bucket.get(lockKey);
-        if (existingObj) {
-            try {
-                const content = JSON.parse(new TextDecoder().decode(new Uint8Array(await existingObj.arrayBuffer())));
-                // Only delete if we own this lock (matching lockId)
-                if (content.lockId === handle.lockId) {
-                    await this._bucket.delete(lockKey);
-                }
-            }
-            catch {
-                // Failed to parse, don't delete to avoid corrupting another process's lock
-            }
-        }
-    }
-    /**
-     * 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
-     *
-     * @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
-     *   }
-     * }
-     * ```
-     */
-    async refreshDistributedLock(handle, ttlMs = 30000) {
-        const lockKey = this._buildKey(`locks/${handle.resource}.lock`);
-        const now = Date.now();
-        const newExpiresAt = now + ttlMs;
-        // Get current lock to verify ownership
-        const existingObj = await this._bucket.head(lockKey);
-        if (!existingObj) {
-            return false; // Lock doesn't exist
-        }
-        const existingLockObj = await this._bucket.get(lockKey);
-        if (!existingLockObj) {
-            return false;
-        }
-        try {
-            const existingContent = JSON.parse(new TextDecoder().decode(new Uint8Array(await existingLockObj.arrayBuffer())));
-            // Verify we own this lock
-            if (existingContent.lockId !== handle.lockId) {
-                return false; // We don't own this lock
-            }
-            // Create updated lock content
-            const updatedContent = {
-                ...existingContent,
-                expiresAt: newExpiresAt
-            };
-            const lockData = new TextEncoder().encode(JSON.stringify(updatedContent));
-            // Update with conditional write using etag
-            try {
-                await this._bucket.put(lockKey, lockData, {
-                    onlyIf: { etagMatches: existingObj.etag }
-                });
-                // Update the handle's expiration and etag
-                const newObj = await this._bucket.head(lockKey);
-                if (newObj) {
-                    handle.etag = newObj.etag;
-                    handle.expiresAt = newExpiresAt;
-                }
-                return true;
-            }
-            catch {
-                // Conditional write failed - lock was modified
-                return false;
-            }
-        }
-        catch {
-            return false;
-        }
-    }
-    /**
-     * 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`);
-     * ```
-     */
-    async cleanupExpiredLocks() {
-        const prefix = this._buildKey('locks/');
-        const listResult = await this._bucket.list({ prefix });
-        const now = Date.now();
-        let cleanedCount = 0;
-        for (const obj of listResult.objects) {
-            if (!obj.key.endsWith('.lock'))
-                continue;
-            const lockObj = await this._bucket.get(obj.key);
-            if (lockObj) {
-                try {
-                    const content = JSON.parse(new TextDecoder().decode(new Uint8Array(await lockObj.arrayBuffer())));
-                    if (content.expiresAt <= now) {
-                        // Lock is expired, safe to delete
-                        await this._bucket.delete(obj.key);
-                        cleanedCount++;
-                    }
-                }
-                catch {
-                    // Invalid lock file, delete it
-                    await this._bucket.delete(obj.key);
-                    cleanedCount++;
-                }
-            }
-        }
-        return cleanedCount;
-    }
-    /**
-     * 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();
-     * }
-     * ```
-     */
-    async acquireLock(packId, options) {
-        const ttl = options?.ttl ?? 30000; // Default 30 second TTL
-        const timeout = options?.timeout ?? 0;
-        const startTime = Date.now();
-        // Try to acquire the distributed lock
-        let handle = await this.acquireDistributedLock(packId, ttl, options?.holder);
-        // If timeout is specified, retry until timeout expires
-        if (!handle && timeout > 0) {
-            while (Date.now() - startTime < timeout) {
-                await new Promise(resolve => setTimeout(resolve, 50)); // Wait 50ms between retries
-                handle = await this.acquireDistributedLock(packId, ttl, options?.holder);
-                if (handle)
-                    break;
-            }
-        }
-        if (!handle) {
-            if (timeout > 0) {
-                throw new R2PackError(`Lock timeout for packfile: ${packId}`, 'LOCKED', packId);
-            }
-            throw new R2PackError(`Packfile is locked: ${packId}`, 'LOCKED', packId);
-        }
-        // Create the PackLock interface with distributed lock backing
-        const self = this;
-        let released = false;
-        return {
-            packId,
-            handle,
-            isHeld: () => !released && handle.expiresAt > Date.now(),
-            release: async () => {
-                if (!released && handle) {
-                    await self.releaseDistributedLock(handle);
-                    released = true;
-                }
-            },
-            refresh: async () => {
-                if (released || !handle)
-                    return false;
-                return await self.refreshDistributedLock(handle, ttl);
-            }
-        };
-    }
-}
-/**
- * Serializes a multi-pack index to bytes.
- *
- * @description
- * Converts a MultiPackIndex structure to the binary MIDX format.
- * The format includes:
- * - MIDX signature (4 bytes)
- * - Version (4 bytes)
- * - Pack count (4 bytes)
- * - Entry count (4 bytes)
- * - Pack IDs with length prefixes
- * - Object entries (40 + 4 + 8 = 52 bytes each)
- * - Checksum (20 bytes)
- *
- * @param midx - Multi-pack index to serialize
- * @returns Serialized MIDX bytes
- *
- * @example
- * ```typescript
- * const bytes = serializeMultiPackIndex(midx);
- * await bucket.put('packs/multi-pack-index', bytes);
- * ```
- *
- * @internal
- */
-function serializeMultiPackIndex(midx) {
-    // Calculate size
-    // Header: 4 (signature) + 4 (version) + 4 (packCount) + 4 (entryCount) = 16
-    // Pack IDs: packCount * (4 + packId.length) each with length prefix
-    // Entries: entryCount * (40 + 4 + 8) = 52 bytes each (objectId + packIndex + offset)
-    // Checksum: 20
-    let packIdsSize = 0;
-    for (const packId of midx.packIds) {
-        packIdsSize += 4 + new TextEncoder().encode(packId).length;
-    }
-    const entriesSize = midx.entries.length * 52;
-    const totalSize = 16 + packIdsSize + entriesSize + 20;
-    const data = new Uint8Array(totalSize);
-    const view = new DataView(data.buffer);
-    let offset = 0;
-    // Signature: MIDX
-    data.set(MIDX_SIGNATURE, offset);
-    offset += 4;
-    // Version
-    view.setUint32(offset, midx.version, false);
-    offset += 4;
-    // Pack count
-    view.setUint32(offset, midx.packIds.length, false);
-    offset += 4;
-    // Entry count
-    view.setUint32(offset, midx.entries.length, false);
-    offset += 4;
-    // Pack IDs
-    const encoder = new TextEncoder();
-    for (const packId of midx.packIds) {
-        const encoded = encoder.encode(packId);
-        view.setUint32(offset, encoded.length, false);
-        offset += 4;
-        data.set(encoded, offset);
-        offset += encoded.length;
-    }
-    // Entries
-    for (const entry of midx.entries) {
-        // Object ID (40 hex chars = 20 bytes as hex string, store as 40 bytes)
-        const objIdBytes = encoder.encode(entry.objectId.padEnd(40, '0').slice(0, 40));
-        data.set(objIdBytes, offset);
-        offset += 40;
-        // Pack index
-        view.setUint32(offset, entry.packIndex, false);
-        offset += 4;
-        // Offset (as 64-bit, but we use 32-bit high + 32-bit low)
-        view.setUint32(offset, 0, false); // high bits
-        offset += 4;
-        view.setUint32(offset, entry.offset, false); // low bits
-        offset += 4;
-    }
-    // Checksum
-    data.set(midx.checksum.slice(0, 20), offset);
-    return data;
-}
-// Standalone functions
-/**
- * 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 async function uploadPackfile(bucket, packData, indexData, options) {
-    const storage = new R2PackStorage({ bucket, prefix: options?.prefix });
-    return storage.uploadPackfile(packData, indexData);
-}
-/**
- * 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 async function downloadPackfile(bucket, packId, options) {
-    const storage = new R2PackStorage({ bucket, prefix: options?.prefix });
-    return storage.downloadPackfile(packId, options);
-}
-/**
- * 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 async function getPackfileMetadata(bucket, packId, options) {
-    const storage = new R2PackStorage({ bucket, prefix: options?.prefix });
-    return storage.getPackfileMetadata(packId);
-}
-/**
- * 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 async function listPackfiles(bucket, options) {
-    const storage = new R2PackStorage({ bucket, prefix: options?.prefix });
-    const result = await storage.listPackfiles({ limit: options?.limit, cursor: options?.cursor });
-    return result.items;
-}
-/**
- * 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 async function deletePackfile(bucket, packId, options) {
-    const storage = new R2PackStorage({ bucket, prefix: options?.prefix });
-    return storage.deletePackfile(packId);
-}
-/**
- * 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 async function createMultiPackIndex(bucket, options) {
-    const storage = new R2PackStorage({ bucket, prefix: options?.prefix });
-    await storage.rebuildMultiPackIndex();
-    return storage.getMultiPackIndex();
-}
-/**
- * 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 function parseMultiPackIndex(data) {
-    if (data.length < 16) {
-        throw new R2PackError('Multi-pack index too small', 'INVALID_DATA');
-    }
-    const view = new DataView(data.buffer, data.byteOffset, data.byteLength);
-    let offset = 0;
-    // Check signature
-    for (let i = 0; i < 4; i++) {
-        if (data[i] !== MIDX_SIGNATURE[i]) {
-            throw new R2PackError('Invalid multi-pack index signature', 'INVALID_DATA');
-        }
-    }
-    offset += 4;
-    // Version
-    const version = view.getUint32(offset, false);
-    offset += 4;
-    // Pack count
-    const packCount = view.getUint32(offset, false);
-    offset += 4;
-    // Entry count
-    const entryCount = view.getUint32(offset, false);
-    offset += 4;
-    // Read pack IDs
-    const decoder = new TextDecoder();
-    const packIds = [];
-    for (let i = 0; i < packCount; i++) {
-        const len = view.getUint32(offset, false);
-        offset += 4;
-        const packIdBytes = data.slice(offset, offset + len);
-        packIds.push(decoder.decode(packIdBytes));
-        offset += len;
-    }
-    // Read entries
-    const entries = [];
-    for (let i = 0; i < entryCount; i++) {
-        const objectIdBytes = data.slice(offset, offset + 40);
-        const objectId = decoder.decode(objectIdBytes);
-        offset += 40;
-        const packIndex = view.getUint32(offset, false);
-        offset += 4;
-        // Skip high bits
-        offset += 4;
-        const entryOffset = view.getUint32(offset, false);
-        offset += 4;
-        entries.push({
-            objectId,
-            packIndex,
-            offset: entryOffset
-        });
-    }
-    // Read checksum
-    const checksum = data.slice(offset, offset + 20);
-    return {
-        version,
-        packIds,
-        entries,
-        checksum: new Uint8Array(checksum)
-    };
-}
-/**
- * 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 function lookupObjectInMultiPack(midx, objectId) {
-    const entries = midx.entries;
-    if (entries.length === 0) {
-        return null;
-    }
-    // Binary search
-    let left = 0;
-    let right = entries.length - 1;
-    while (left <= right) {
-        const mid = Math.floor((left + right) / 2);
-        const entry = entries[mid];
-        const cmp = objectId.localeCompare(entry.objectId);
-        if (cmp === 0) {
-            return entry;
-        }
-        else if (cmp < 0) {
-            right = mid - 1;
-        }
-        else {
-            left = mid + 1;
-        }
-    }
-    return null;
-}
-/**
- * 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 async function acquirePackLock(bucket, packId, options) {
-    const storage = new R2PackStorage({ bucket, prefix: options?.prefix });
-    return storage.acquireLock(packId, options);
-}
-/**
- * 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 async function releasePackLock(bucket, packId, options) {
-    // For backward compatibility, we just delete the lock file directly
-    // This is less safe than using the handle-based release, but works for simple cases
-    const lockKey = buildKey(options?.prefix ?? '', `locks/${packId}.lock`);
-    await bucket.delete(lockKey);
-}
-//# sourceMappingURL=r2-pack.js.map