@pol-studios/powersync 1.0.25 → 1.0.32

package/dist/pol-attachment-queue-DqBvLAEY.d.ts

@@ -0,0 +1,255 @@
+import { AbstractAttachmentQueue, AttachmentQueueOptions, AttachmentRecord } from '@powersync/attachments';
+import { AbstractPowerSyncDatabase } from '@powersync/common';
+import { PlatformAdapter } from './platform/index.js';
+import { e as AttachmentStorageAdapter, c as AttachmentSourceConfig, h as UploadHandler, U as UploadConfig, i as DownloadConfig, a as PolAttachmentRecord, f as CompressionConfig, k as CacheConfig, t as UploadStatus, v as AttachmentSyncStats, d as AttachmentConfig } from './types-JCEhw2Lf.js';
+
+/**
+ * POL Attachment Queue
+ *
+ * Extends the official @powersync/attachments AbstractAttachmentQueue with
+ * POL-specific features:
+ * - Reactive watchPaths callback for attachment path sources
+ * - Durable upload queue with exponential backoff retry
+ * - FAILED_PERMANENT state for unrecoverable upload errors
+ * - Image compression integration
+ * - Upload callbacks (onUploadComplete, onUploadFailed)
+ *
+ * @example
+ * ```typescript
+ * const queue = new PolAttachmentQueue({
+ *   powersync: db,
+ *   storage: storageAdapter,
+ *   source: {
+ *     source: { type: 'supabase-bucket', bucket: 'project-assets' },
+ *     watchPaths: (db, supabase, onUpdate) => {
+ *       db.watch(
+ *         // Filter in the query - only emit paths you want to download
+ *         `SELECT storagePath FROM photos
+ *          WHERE storagePath IS NOT NULL
+ *          AND mediaType NOT LIKE 'video/%'`,
+ *         [],
+ *         { onResult: (r) => onUpdate(r.rows._array.map(row => row.storagePath)) }
+ *       );
+ *     },
+ *   },
+ * });
+ *
+ * await queue.init();
+ * ```
+ */
+
+/**
+ * Options for PolAttachmentQueue that extend the official AttachmentQueueOptions.
+ */
+interface PolAttachmentQueueOptions extends AttachmentQueueOptions {
+    platform: PlatformAdapter;
+    remoteStorage: AttachmentStorageAdapter;
+    /** Attachment source configuration with reactive watchPaths callback */
+    source: AttachmentSourceConfig;
+    /**
+     * Supabase client for passing to watchPaths callback.
+     * Required when using watchPaths (new API).
+     */
+    supabaseClient?: unknown;
+    uploadHandler?: UploadHandler;
+    uploadConfig?: Partial<UploadConfig>;
+    /** Download configuration for concurrency tuning */
+    downloadConfig?: Partial<DownloadConfig>;
+    onUploadComplete?: (record: PolAttachmentRecord) => Promise<void>;
+    onUploadFailed?: (record: PolAttachmentRecord, error: Error) => void;
+    compression?: Partial<CompressionConfig>;
+    cache?: Partial<CacheConfig>;
+}
+/**
+ * POL Attachment Queue that extends the official AbstractAttachmentQueue.
+ */
+declare class PolAttachmentQueue extends AbstractAttachmentQueue<PolAttachmentQueueOptions> {
+    private readonly platform;
+    private readonly polLogger;
+    private readonly source;
+    private readonly remoteStorage;
+    private readonly supabaseClient?;
+    private readonly uploadHandler?;
+    private readonly uploadConfig;
+    private readonly downloadConfig;
+    private readonly compressionConfig;
+    private readonly cacheConfig;
+    private _uploadState;
+    private _disposed;
+    private _initialized;
+    private _watchGeneration;
+    private _watchCleanup;
+    private _watchMutex;
+    private _networkListenerCleanup;
+    private _wasConnected;
+    private _cacheCapacityRetries;
+    private _progressCallbacks;
+    private _lastNotifyTime;
+    private _notifyTimer;
+    private _cachedStats;
+    private _cachedStatsTimestamp;
+    constructor(options: PolAttachmentQueueOptions);
+    watchUploads(): void;
+    /**
+     * Override parent's expireCache to disable count-based cache eviction.
+     *
+     * The parent implementation deletes SYNCED/ARCHIVED records beyond cacheLimit,
+     * which caused a bug where downloads would reset because:
+     * 1. expireCache deleted records beyond cacheLimit (default 100)
+     * 2. watchPaths still emitted those IDs
+     * 3. They got re-created as QUEUED_DOWNLOAD
+     * 4. Downloads restarted in an infinite loop
+     *
+     * Our implementation uses size-based cache limits only (via clearCache/cacheConfig.maxSize).
+     */
+    expireCache(): Promise<void>;
+    /**
+     * Override parent's watchDownloads to use concurrent downloads.
+     *
+     * The parent implementation downloads one file at a time.
+     * This override processes downloads in parallel batches for faster sync.
+     */
+    watchDownloads(): void;
+    /**
+     * Process pending downloads with concurrency control.
+     * Downloads multiple files in parallel based on downloadConfig.concurrency.
+     * Enforces cache size limits after each batch completes.
+     */
+    private _downloadRecordsConcurrent;
+    uploadAttachment(record: {
+        id: string;
+    }): Promise<boolean>;
+    watchAttachmentIds(): Promise<void>;
+    saveToQueue(record: Omit<AttachmentRecord, 'timestamp'>): Promise<AttachmentRecord>;
+    onAttachmentIdsChange(onUpdate: (ids: string[]) => void): void;
+    downloadRecord(record: AttachmentRecord): Promise<boolean>;
+    newAttachmentRecord(record?: Partial<AttachmentRecord>): Promise<AttachmentRecord>;
+    init(): Promise<void>;
+    /**
+     * Dispose the attachment queue and clean up resources.
+     * This method is synchronous to ensure callers don't need to await it,
+     * but it fires off async cleanup in the background for graceful shutdown.
+     */
+    dispose(): void;
+    /**
+     * Async cleanup that runs in the background after dispose().
+     * Waits for active upload promises to settle gracefully.
+     */
+    private _asyncCleanup;
+    queueUpload(options: {
+        storagePath: string;
+        sourceUri: string;
+        filename: string;
+        mediaType: string;
+        bucketId?: string;
+        metadata?: Record<string, unknown>;
+    }): Promise<void>;
+    getPendingUploads(): Promise<PolAttachmentRecord[]>;
+    getSoonestRetryTime(): Promise<number | null>;
+    getFailedPermanentUploads(): Promise<PolAttachmentRecord[]>;
+    getStaleUploads(): Promise<PolAttachmentRecord[]>;
+    getSyncedUploadsWithPendingCallback(): Promise<PolAttachmentRecord[]>;
+    clearUploadCallback(id: string): Promise<void>;
+    retryUpload(id: string): Promise<void>;
+    /**
+     * Reset all uploads in QUEUED_UPLOAD state so they retry immediately.
+     * This clears retry counts and errors, allowing uploads to be retried fresh.
+     *
+     * @returns The number of uploads that were reset
+     */
+    resetUploadRetries(): Promise<number>;
+    /**
+     * Trigger immediate retry of uploads WITHOUT resetting their retry count.
+     * This preserves backoff state for truly failing uploads while allowing
+     * uploads that were waiting for network to retry immediately.
+     *
+     * Only affects uploads that:
+     * - Are past their retry time (upload_next_retry_at <= now), OR
+     * - Have no retry time set (upload_next_retry_at IS NULL)
+     *
+     * @returns The number of uploads that will be retried
+     */
+    retryUploads(): Promise<number>;
+    deleteUpload(id: string): Promise<void>;
+    /**
+     * Re-queue an upload for an orphaned attachment.
+     * Use this when a database record exists with a storagePath but the file was never uploaded.
+     *
+     * This handles the case where:
+     * - User took a photo and the database record was created with a storagePath
+     * - The attachment queue record was created but disappeared before upload completed
+     * - The photo shows locally but was never uploaded to storage
+     *
+     * @param options.storagePath - The storage path (e.g., "projectId/fileId.jpg")
+     * @param options.localFileUri - URI to the local file to upload
+     * @param options.mediaType - MIME type of the file
+     * @param options.bucketId - Optional bucket ID for multi-bucket setups
+     * @returns true if upload was queued, false if already exists in valid state
+     */
+    requeueOrphanedUpload(options: {
+        storagePath: string;
+        localFileUri: string;
+        mediaType: string;
+        bucketId?: string;
+    }): Promise<boolean>;
+    getRecord(id: string): Promise<PolAttachmentRecord | null>;
+    getFailedUploads(): Promise<PolAttachmentRecord[]>;
+    retryFailedUpload(id: string): Promise<void>;
+    deleteFailedUpload(id: string): Promise<void>;
+    get activeUploads(): UploadStatus[];
+    pauseUploads(): void;
+    resumeUploads(): void;
+    clearCache(): Promise<void>;
+    cacheLocalFile(storagePath: string, sourceUri: string): Promise<void>;
+    getLocalUriForStoragePath(storagePath: string): Promise<string | null>;
+    /**
+     * Purge attachments by their IDs.
+     * Archives and deletes local files for the specified attachment IDs.
+     * Useful for edge cases where external code needs to force-remove attachments.
+     *
+     * @param ids - Array of attachment IDs to purge
+     */
+    purgeAttachments(ids: string[]): Promise<void>;
+    onProgress(callback: (stats: AttachmentSyncStats) => void): () => void;
+    getStats(): Promise<AttachmentSyncStats>;
+    /**
+     * Repair attachment sizes for synced records that have size=0.
+     * This backfills sizes from the actual file system for existing downloads.
+     * @returns Number of records repaired
+     */
+    repairAttachmentSizes(): Promise<number>;
+    private _getDownloadManagerDeps;
+    private _getUploadManagerDeps;
+    private _getCacheManagerDeps;
+    private _startUploadProcessing;
+    private _createTableIfNotExists;
+    private _migrateUploadColumns;
+    private _invalidateStatsCache;
+    private _getStatus;
+    private _notify;
+}
+/**
+ * Factory function options that combine AttachmentConfig with required runtime dependencies.
+ */
+interface CreateAttachmentQueueOptions extends AttachmentConfig {
+    /** Remote storage adapter for downloading/uploading files */
+    remoteStorage: AttachmentStorageAdapter;
+    /**
+     * Supabase client for passing to watchPaths callback.
+     * Required when using watchPaths (new API).
+     */
+    supabaseClient?: unknown;
+    /** Upload handler for processing uploads */
+    uploadHandler?: UploadHandler;
+    /** Upload configuration */
+    uploadConfig?: Partial<UploadConfig>;
+    /** Download configuration (concurrency, timeout) */
+    downloadConfig?: Partial<DownloadConfig>;
+    /** Compression configuration */
+    compression?: Partial<CompressionConfig>;
+    /** Cache configuration */
+    cache?: Partial<CacheConfig>;
+}
+declare function createPolAttachmentQueue(powersync: AbstractPowerSyncDatabase, platform: PlatformAdapter, config: CreateAttachmentQueueOptions): PolAttachmentQueue;
+
+export { PolAttachmentQueue as P, type PolAttachmentQueueOptions as a, createPolAttachmentQueue as c };