@pol-studios/powersync 1.0.4 → 1.0.7

package/dist/attachments/index.d.ts

@@ -1,399 +1,109 @@
-import { A as AbstractPowerSyncDatabase } from '../types-afHtE1U_.js';
+import { e as AttachmentStorageAdapter } from '../pol-attachment-queue-C7YNXXhK.js';
+export { t as AttachmentRecord, A as AttachmentSourceConfig, q as AttachmentStatsRow, p as AttachmentSyncStats, o as AttachmentSyncStatus, h as CacheConfig, r as CacheFileRow, s as CachedSizeRow, C as CompressionConfig, i as DEFAULT_CACHE_CONFIG, D as DEFAULT_COMPRESSION_CONFIG, f as DEFAULT_UPLOAD_CONFIG, k as DownloadPhase, l as DownloadStatus, E as EvictRow, I as IdRow, P as PolAttachmentQueue, j as PolAttachmentQueueConfig, a as PolAttachmentQueueOptions, d as PolAttachmentRecord, b as PolAttachmentState, U as UploadConfig, g as UploadHandler, m as UploadPhase, n as UploadStatus, c as createPolAttachmentQueue } from '../pol-attachment-queue-C7YNXXhK.js';
+import { StorageAdapter, EncodingType } from '@powersync/attachments';
+export { ATTACHMENT_TABLE, AbstractAttachmentQueue, AttachmentState, AttachmentTable, AttachmentTableOptions, AttachmentQueueOptions as BaseAttachmentQueueOptions, DEFAULT_ATTACHMENT_QUEUE_OPTIONS, EncodingType, AttachmentRecord as OfficialAttachmentRecord, StorageAdapter } from '@powersync/attachments';
 import { PlatformAdapter } from '../platform/index.js';
+import '@powersync/common';
+import '../types-CDqWh56B.js';
 
 /**
- * Attachment Queue Types for @pol-studios/powersync
+ * POL Storage Adapter
  *
- * Defines interfaces for the attachment queue system that handles
- * offline file caching with download, compression, and eviction.
- */
-/**
- * State of an attachment in the queue.
- * NOTE: These do NOT match @powersync/attachments enum ordering (values 0-2 differ).
- */
-declare enum AttachmentState {
-    /** Waiting to be downloaded */
-    QUEUED_DOWNLOAD = 0,
-    /** Waiting for initial sync */
-    QUEUED_SYNC = 1,
-    /** Waiting to be uploaded */
-    QUEUED_UPLOAD = 2,
-    /** Fully synced (downloaded or uploaded) */
-    SYNCED = 3,
-    /** Archived (removed from sync but record kept) */
-    ARCHIVED = 4
-}
-/**
- * Record representing an attachment in the queue database.
- */
-interface AttachmentRecord {
-    /** Unique identifier (typically storage path) */
-    id: string;
-    /** Filename for display and type inference */
-    filename: string;
-    /** MIME type of the file */
-    media_type: string;
-    /** Current state in the queue */
-    state: AttachmentState;
-    /** Local file URI (set after download) */
-    local_uri?: string | null;
-    /** File size in bytes */
-    size?: number;
-    /** Timestamp when the attachment was created */
-    timestamp?: number;
-}
-/**
- * Configuration for the source table that contains attachment references.
- * This makes the attachment queue reusable across different tables/projects.
- */
-interface AttachmentSourceConfig {
-    /**
-     * Table name containing attachment references.
-     * @example "EquipmentUnitMediaContent"
-     */
-    table: string;
-    /**
-     * Column containing the storage path / attachment ID.
-     * @example "storagePath"
-     */
-    idColumn: string;
-    /**
-     * Column to order by for "newest first" downloads.
-     * Set to null to skip ordering.
-     * @example "takenOn"
-     */
-    orderByColumn: string | null;
-    /**
-     * Optional filter config to exclude attachments from archived/unsynced projects.
-     * When set, the attachment query JOINs through intermediary tables to ensure
-     * only attachments belonging to synced projects are downloaded.
-     */
-    projectFilter?: {
-        /** Foreign key column in the source table (e.g., "equipmentUnitId") */
-        foreignKey: string;
-        /** Intermediary table to JOIN through (e.g., "EquipmentFixtureUnit") */
-        intermediaryTable: string;
-        /** Column in intermediary table that links to ProjectDatabase (e.g., "projectDatabaseId") */
-        projectForeignKey: string;
-    };
-}
-/**
- * Interface for attachment storage operations (e.g., Supabase Storage).
+ * Implements the official @powersync/attachments StorageAdapter interface,
+ * bridging our PlatformAdapter file system and remote storage adapters.
+ *
+ * This adapter combines:
+ * - Local file operations via PlatformAdapter.fileSystem
+ * - Remote upload/download via AttachmentStorageAdapter (e.g., Supabase)
  */
-interface AttachmentStorageAdapter {
-    /**
-     * Download a file from remote storage.
-     * @param filePath - The storage path of the file
-     * @returns The file data as a Blob or base64 string
-     */
-    downloadFile(filePath: string): Promise<Blob | string>;
+
+interface PolStorageAdapterOptions {
     /**
-     * Upload a file to remote storage (optional - not all queues need upload).
-     * @param filePath - The storage path to upload to
-     * @param data - The file data to upload
+     * Platform adapter for local file system operations.
      */
-    uploadFile?(filePath: string, data: Blob | string): Promise<void>;
+    platform: PlatformAdapter;
     /**
-     * Delete a file from remote storage (optional).
-     * @param filePath - The storage path of the file
+     * Remote storage adapter for upload/download operations.
      */
-    deleteFile?(filePath: string): Promise<void>;
+    remoteStorage: AttachmentStorageAdapter;
     /**
-     * Resolve the storage bucket for a file path.
-     * Allows routing different files to different buckets.
-     * @param filePath - The file path to resolve
-     * @returns The bucket name
+     * Base directory name for attachments within the cache directory.
+     * Defaults to 'attachments'.
      */
-    resolveBucket?(filePath: string): string;
-}
-/**
- * Configuration for image compression.
- */
-interface CompressionConfig {
-    /** Enable compression (default: true) */
-    enabled: boolean;
-    /** Compression quality 0.0-1.0 (default: 0.7) */
-    quality: number;
-    /** Max width before resizing (default: 2048) */
-    maxWidth: number;
-    /** Skip files under this size in bytes (default: 100KB) */
-    skipSizeBytes: number;
-    /** Skip if already under this size in bytes (default: 300KB) */
-    targetSizeBytes: number;
+    attachmentDirectoryName?: string;
 }
 /**
- * Default compression configuration.
- */
-declare const DEFAULT_COMPRESSION_CONFIG: CompressionConfig;
-/**
- * Configuration for the download engine.
- */
-interface DownloadConfig {
-    /** Maximum concurrent downloads (default: 50) */
-    concurrency: number;
-    /** Download timeout per file in ms (default: 60000) */
-    timeoutMs: number;
-    /** Retry delay between batches in ms (default: 5000) */
-    retryDelayMs: number;
-}
-/**
- * Default download configuration.
- */
-declare const DEFAULT_DOWNLOAD_CONFIG: DownloadConfig;
-/**
- * Configuration for cache management.
- */
-interface CacheConfig {
-    /** Maximum cache size in bytes (default: 5GB) */
-    maxSize: number;
-    /** Stop downloads at this percentage of max (default: 0.95 = 95%) */
-    downloadStopThreshold: number;
-    /** Trigger eviction at this percentage (default: 1.0 = 100%) */
-    evictionTriggerThreshold: number;
-}
-/**
- * Default cache configuration.
- */
-declare const DEFAULT_CACHE_CONFIG: CacheConfig;
-/**
- * Full configuration for the attachment queue.
- */
-interface AttachmentQueueConfig {
-    /** Source table configuration */
-    source: AttachmentSourceConfig;
-    /** Storage adapter for downloading files */
-    storage: AttachmentStorageAdapter;
-    /** Table name for storing attachment records (default: "photo_attachments") */
-    attachmentTableName?: string;
-    /** Perform initial sync on initialization (default: true) */
-    performInitialSync?: boolean;
-    /** Download configuration */
-    download?: Partial<DownloadConfig>;
-    /** Cache configuration */
-    cache?: Partial<CacheConfig>;
-    /** Compression configuration */
-    compression?: Partial<CompressionConfig>;
-    /**
-     * Called when a download fails.
-     * Return { retry: true } to retry, { retry: false } to skip.
-     */
-    onDownloadError?: (attachment: AttachmentRecord, error: Error) => Promise<{
-        retry: boolean;
-    }>;
-    /**
-     * Called when sync progress changes.
-     */
-    onProgress?: (stats: AttachmentSyncStats) => void;
-}
-/**
- * Current phase of a download operation.
- */
-type DownloadPhase = 'downloading' | 'compressing' | 'complete' | 'error';
-/**
- * Status of an individual download.
- */
-interface DownloadStatus {
-    /** Attachment ID */
-    id: string;
-    /** Filename being downloaded */
-    filename: string;
-    /** Current phase */
-    phase: DownloadPhase;
-}
-/**
- * Why downloads are stopped (if not actively syncing).
- */
-type AttachmentSyncStatus = 'syncing' | 'paused' | 'cache_full' | 'complete';
-/**
- * Statistics about the attachment sync progress.
- */
-interface AttachmentSyncStats {
-    /** Number of attachments that have been downloaded */
-    syncedCount: number;
-    /** Total size of synced attachments in bytes */
-    syncedSize: number;
-    /** Number of attachments waiting to be downloaded */
-    pendingCount: number;
-    /** Total expected attachments (synced + pending) */
-    totalExpected: number;
-    /** Maximum cache size in bytes */
-    maxCacheSize: number;
-    /** Current compression quality (0.1 to 1.0) */
-    compressionQuality: number;
-    /** Current sync status */
-    status: AttachmentSyncStatus;
-    /** Whether downloads are paused */
-    isPaused: boolean;
-    /** Whether currently processing downloads */
-    isProcessing: boolean;
-    /** Currently active downloads */
-    activeDownloads: DownloadStatus[];
-}
-/** Row from stats query */
-interface AttachmentStatsRow {
-    state: number;
-    cnt: number;
-    sz: number;
-}
-/** Row for cache file operations */
-interface CacheFileRow {
-    id: string;
-    local_uri: string;
-}
-/** Row for eviction operations */
-interface EvictRow {
-    id: string;
-    local_uri: string;
-    size: number;
-}
-/** Row for cached size queries */
-interface CachedSizeRow {
-    total: number;
-}
-/** Row for ID queries */
-interface IdRow {
-    id: string;
-}
-
-/**
- * Attachment Queue for @pol-studios/powersync
+ * Storage adapter that implements the official @powersync/attachments interface.
  *
- * Platform-agnostic attachment queue that handles:
- * - Parallel downloads with configurable concurrency
- * - Cache management with eviction
- * - Image compression
- * - Pause/resume functionality
- * - Progress tracking
- */
-
-/**
- * Platform-agnostic attachment queue for offline file caching.
+ * Combines local file system operations (via PlatformAdapter) with remote
+ * storage operations (via AttachmentStorageAdapter like Supabase).
  *
  * @example
  * ```typescript
- * const queue = new AttachmentQueue({
- *   powersync: db,
+ * const storageAdapter = new PolStorageAdapter({
  *   platform: platformAdapter,
- *   config: {
- *     source: {
- *       table: 'EquipmentUnitMediaContent',
- *       idColumn: 'storagePath',
- *       orderByColumn: 'takenOn',
- *     },
- *     storage: storageAdapter,
- *   },
+ *   remoteStorage: supabaseStorageAdapter,
  * });
- *
- * await queue.init();
  * ```
  */
-declare class AttachmentQueue {
-    private readonly powersync;
+declare class PolStorageAdapter implements StorageAdapter {
     private readonly platform;
-    private readonly config;
-    private readonly logger;
-    private readonly tableName;
-    private readonly concurrency;
-    private readonly downloadTimeoutMs;
-    private readonly retryDelayMs;
-    private readonly downloadStopThreshold;
-    private readonly evictionTriggerThreshold;
-    private _initialized;
-    private _paused;
-    private _processing;
-    private _cacheFull;
-    private _resumeRequested;
-    private _maxCacheSize;
-    private _compressionQuality;
-    private _abort;
-    private _downloads;
-    private _cachedSize;
-    private _cachedSizeTimestamp;
-    private _cachedStats;
-    private _cachedStatsTimestamp;
-    private _lastNotifyTime;
-    private _notifyTimer;
-    private _progressCallbacks;
-    private _watcherInterval;
-    constructor(options: {
-        powersync: AbstractPowerSyncDatabase;
-        platform: PlatformAdapter;
-        config: AttachmentQueueConfig;
-    });
-    /**
-     * Initialize the attachment queue.
-     * Creates the attachment table if needed and starts watching for downloads.
-     */
-    init(): Promise<void>;
-    /**
-     * Dispose the attachment queue.
-     */
-    dispose(): void;
+    private readonly remoteStorage;
+    private readonly attachmentDirectoryName;
+    private readonly userStorageDirectory;
+    constructor(options: PolStorageAdapterOptions);
     /**
-     * Subscribe to real-time progress updates.
-     * Returns an unsubscribe function.
+     * Upload a file to remote storage.
      */
-    onProgress(callback: (stats: AttachmentSyncStats) => void): () => void;
-    /** Whether downloads are paused */
-    get paused(): boolean;
-    /** Whether currently processing downloads */
-    get processing(): boolean;
+    uploadFile(filePath: string, data: ArrayBuffer, options?: {
+        mediaType?: string;
+    }): Promise<void>;
     /**
-     * Set the maximum cache size.
+     * Download a file from remote storage.
      */
-    setMaxCacheSize(bytes: number): Promise<void>;
+    downloadFile(filePath: string): Promise<Blob>;
     /**
-     * Set the compression quality (0.1 to 1.0).
+     * Write data to a local file.
      */
-    setCompressionQuality(quality: number): void;
-    /** Get the current compression quality */
-    getCompressionQuality(): number;
+    writeFile(fileUri: string, base64Data: string, options?: {
+        encoding?: EncodingType;
+    }): Promise<void>;
     /**
-     * Pause downloads.
+     * Read a local file's contents.
      */
-    pause(): void;
+    readFile(fileUri: string, options?: {
+        encoding?: EncodingType;
+        mediaType?: string;
+    }): Promise<ArrayBuffer>;
     /**
-     * Resume downloads.
+     * Delete a local file.
      */
-    resume(): void;
+    deleteFile(uri: string, _options?: {
+        filename?: string;
+    }): Promise<void>;
     /**
-     * Get current sync statistics.
+     * Check if a local file exists.
      */
-    getStats(): Promise<AttachmentSyncStats>;
+    fileExists(fileUri: string): Promise<boolean>;
     /**
-     * Clear all cached files and re-queue for download.
+     * Create a directory (with intermediate directories).
      */
-    clearCache(): Promise<void>;
+    makeDir(uri: string): Promise<void>;
     /**
-     * Get an attachment record by ID.
+     * Copy a file from source to destination.
      */
-    getRecord(id: string): Promise<AttachmentRecord | null>;
+    copyFile(sourceUri: string, targetUri: string): Promise<void>;
     /**
-     * Get the local file URI for an attachment.
+     * Get the user's storage directory for attachments.
+     * Returns the cache directory path ending with '/'.
      */
-    getLocalUri(localPath: string): string;
+    getUserStorageDirectory(): string;
     /**
-     * Cache a local file (e.g. one just uploaded) into the attachment cache.
-     * This avoids a redundant download by copying the source file directly
-     * into the cache directory and marking it as SYNCED.
+     * Warning 8: Optimized base64 encoding using batch processing.
+     * Processes in chunks of 1024 bytes for better performance with large files.
      */
-    cacheLocalFile(storagePath: string, sourceUri: string): Promise<void>;
-    private _startDownloadWatcher;
-    private _syncAttachmentIds;
-    private _startDownloads;
-    private _downloadOne;
-    private _batchUpdateSizes;
-    private _getIdsToDownload;
-    private _evictIfNeeded;
-    private _compressImage;
-    private _isImage;
-    private _getStatus;
-    private _getCachedSizeWithCache;
-    private _orderByNewest;
-    private _sleep;
-    private _withTimeout;
-    private _blobToBase64;
-    private _notify;
+    private _arrayBufferToBase64;
+    private _base64ToArrayBuffer;
 }
 
-export { AttachmentQueue, type AttachmentQueueConfig, type AttachmentRecord, type AttachmentSourceConfig, AttachmentState, type AttachmentStatsRow, type AttachmentStorageAdapter, type AttachmentSyncStats, type AttachmentSyncStatus, type CacheConfig, type CacheFileRow, type CachedSizeRow, type CompressionConfig, DEFAULT_CACHE_CONFIG, DEFAULT_COMPRESSION_CONFIG, DEFAULT_DOWNLOAD_CONFIG, type DownloadConfig, type DownloadPhase, type DownloadStatus, type EvictRow, type IdRow };
+export { AttachmentStorageAdapter, PolStorageAdapter, type PolStorageAdapterOptions };

package/dist/attachments/index.js

@@ -1,16 +1,34 @@
-import "../chunk-32OLICZO.js";
+import "../chunk-GKF7TOMT.js";
 import {
-  AttachmentQueue,
+  ATTACHMENT_TABLE,
+  AbstractAttachmentQueue,
   AttachmentState,
+  AttachmentTable,
+  DEFAULT_ATTACHMENT_QUEUE_OPTIONS,
   DEFAULT_CACHE_CONFIG,
   DEFAULT_COMPRESSION_CONFIG,
-  DEFAULT_DOWNLOAD_CONFIG
-} from "../chunk-V6LJ6MR2.js";
+  DEFAULT_UPLOAD_CONFIG,
+  EncodingType,
+  PolAttachmentQueue,
+  PolAttachmentState,
+  PolStorageAdapter,
+  createPolAttachmentQueue
+} from "../chunk-ZEOKPWUC.js";
+import "../chunk-FV2HXEIY.js";
+import "../chunk-DGUM43GV.js";
 export {
-  AttachmentQueue,
+  ATTACHMENT_TABLE,
+  AbstractAttachmentQueue,
   AttachmentState,
+  AttachmentTable,
+  DEFAULT_ATTACHMENT_QUEUE_OPTIONS,
   DEFAULT_CACHE_CONFIG,
   DEFAULT_COMPRESSION_CONFIG,
-  DEFAULT_DOWNLOAD_CONFIG
+  DEFAULT_UPLOAD_CONFIG,
+  EncodingType,
+  PolAttachmentQueue,
+  PolAttachmentState,
+  PolStorageAdapter,
+  createPolAttachmentQueue
 };
 //# sourceMappingURL=index.js.map

package/dist/{types-Cd7RhNqf.d.ts → background-sync-ChCXW-EV.d.ts}

@@ -1,4 +1,4 @@
-import { a as SyncStatus, S as SyncMode, e as SyncMetrics, b as ConnectionHealth, f as SyncError } from './types-afHtE1U_.js';
+import { a as SyncStatus, S as SyncMode, e as SyncMetrics, b as ConnectionHealth, f as SyncError } from './types-CDqWh56B.js';
 
 /**
  * Sync Module Types for @pol-studios/powersync
@@ -221,4 +221,55 @@ type SyncEventListener = (event: SyncEvent) => void;
  */
 type Unsubscribe = () => void;
 
-export type { HealthMonitorOptions as H, MetricsCollectorOptions as M, PowerSyncRawStatus as P, SyncScope as S, Unsubscribe as U, SyncStatusState as a, SyncStatusTrackerOptions as b, SyncControlActions as c, SyncOperationData as d, HealthCheckResult as e, SyncEvent as f, SyncEventListener as g };
+interface BackgroundSyncOptions {
+    /** Task name (default: "powersync-background-sync") */
+    taskName?: string;
+    /** Minimum interval in minutes (default: 15) */
+    minimumInterval?: number;
+    /** Called when background sync starts */
+    onSyncStart?: () => Promise<void>;
+    /** Called when background sync completes */
+    onSyncComplete?: () => void;
+    /** Called on error */
+    onError?: (error: Error) => void;
+}
+interface BackgroundSyncSystem {
+    /** Initialize PowerSync and connect */
+    init: () => Promise<void>;
+    /** Disconnect PowerSync */
+    disconnect: () => Promise<void>;
+    /** Check if PowerSync is connected */
+    isConnected: () => boolean;
+    /** Get the PowerSync database instance */
+    getDatabase: () => any;
+    /** Register status change listener, returns unsubscribe function (REQUIRED) */
+    onStatusChange: (callback: (status: {
+        lastSyncedAt?: Date;
+        downloading: boolean;
+        uploading: boolean;
+    }) => void) => () => void;
+}
+/**
+ * Define the background sync task.
+ * Must be called at module load time (outside of components).
+ */
+declare function defineBackgroundSyncTask(getSystem: () => BackgroundSyncSystem | null, options?: BackgroundSyncOptions): string;
+/**
+ * Initialize background sync with AppState management.
+ * Registers task when app goes to background, unregisters when active.
+ */
+declare function initializeBackgroundSync(appReadyPromise: Promise<void>, options?: BackgroundSyncOptions): Promise<() => void>;
+/**
+ * Manually register the background sync task.
+ */
+declare function registerBackgroundSync(options?: BackgroundSyncOptions): Promise<void>;
+/**
+ * Manually unregister the background sync task.
+ */
+declare function unregisterBackgroundSync(taskName?: string): Promise<void>;
+/**
+ * Check if background sync task is registered.
+ */
+declare function isBackgroundSyncRegistered(taskName?: string): Promise<boolean>;
+
+export { type BackgroundSyncOptions as B, type HealthMonitorOptions as H, type MetricsCollectorOptions as M, type PowerSyncRawStatus as P, type SyncScope as S, type Unsubscribe as U, type SyncStatusState as a, type SyncStatusTrackerOptions as b, type SyncControlActions as c, type SyncOperationData as d, type HealthCheckResult as e, type SyncEvent as f, type SyncEventListener as g, type BackgroundSyncSystem as h, defineBackgroundSyncTask as i, initializeBackgroundSync as j, isBackgroundSyncRegistered as k, registerBackgroundSync as r, unregisterBackgroundSync as u };