@pol-studios/powersync 1.0.7 → 1.0.10

package/dist/CacheSettingsManager-uz-kbnRH.d.ts

@@ -0,0 +1,461 @@
+import { c as SupabaseStorageOptions, a as StorageBackend, D as DownloadResult, S as SupabaseStorage, d as SupabaseClient } from './types-D0WcHrq6.js';
+import { LoggerAdapter, FileSystemAdapter, AsyncStorageAdapter } from './platform/index.js';
+
+/**
+ * Supabase Storage Backend for @pol-studios/powersync
+ *
+ * Unified storage implementation using Supabase Storage.
+ * Handles both web (Blob) and native (file URI) downloads.
+ *
+ * @example
+ * ```typescript
+ * import { createSupabaseStorage } from '@pol-studios/powersync/storage';
+ *
+ * const storage = createSupabaseStorage({
+ *   client: supabaseClient,
+ *   defaultBucket: 'attachments',
+ *   fileSystem: platform.fileSystem, // Required for native
+ * });
+ *
+ * // Download
+ * const result = await storage.download('photos/image.jpg');
+ * if (result.type === 'file') {
+ *   // Native: zero-copy file path
+ *   console.log('Downloaded to:', result.uri);
+ * } else {
+ *   // Web: Blob in memory
+ *   console.log('Downloaded blob:', result.data.size, 'bytes');
+ * }
+ *
+ * // Upload with progress
+ * await storage.upload('photos/new.jpg', 'file:///local/path.jpg', 'image/jpeg', {
+ *   onProgress: ({ loaded, total }) => {
+ *     console.log(`Progress: ${Math.round(loaded / total * 100)}%`);
+ *   },
+ * });
+ * ```
+ */
+
+/**
+ * Create a Supabase storage backend.
+ *
+ * @param options - Configuration options
+ * @returns StorageBackend implementation
+ */
+declare function createSupabaseStorage(options: SupabaseStorageOptions): StorageBackend;
+/**
+ * Type guard to check if download result is a file URI.
+ */
+declare function isFileResult(result: DownloadResult): result is {
+    type: 'file';
+    uri: string;
+};
+/**
+ * Type guard to check if download result is a blob.
+ */
+declare function isBlobResult(result: DownloadResult): result is {
+    type: 'blob';
+    data: Blob;
+};
+
+/**
+ * Utilities for detecting storage authentication errors.
+ *
+ * These utilities help identify when a storage operation failed due to
+ * authentication issues (expired tokens, invalid sessions, etc.) that
+ * can often be resolved by refreshing the user's session.
+ *
+ * NOTE: This is a copy of the utility from @pol-studios/db/storage.
+ * We maintain a separate copy here to avoid circular dependencies between
+ * @pol-studios/powersync and @pol-studios/db.
+ */
+/**
+ * Check if a storage error is an authentication error.
+ *
+ * These errors can often be fixed by refreshing the session.
+ *
+ * @param error - The error to check (typically from Supabase Storage operations)
+ * @returns true if the error appears to be authentication-related
+ *
+ * @example
+ * ```typescript
+ * const { data, error } = await storage.createSignedUrl(path, 3600);
+ * if (error && isStorageAuthError(error)) {
+ *   await supabase.auth.refreshSession();
+ *   // Retry the request...
+ * }
+ * ```
+ */
+declare function isStorageAuthError(error: unknown): boolean;
+/**
+ * Extract a meaningful error message from a storage error.
+ *
+ * Supabase Storage errors may have different structures:
+ * - Standard Error with `.message` property
+ * - StorageError with `.message` and optional `.error` property
+ * - Response-like object with `status`, `statusText`, `url` properties
+ * - Plain string
+ *
+ * This function handles all these cases and returns a human-readable message.
+ *
+ * @param error - The error to extract a message from
+ * @returns A human-readable error message
+ *
+ * @example
+ * ```typescript
+ * const { data, error } = await storage.createSignedUrl(path, 3600);
+ * if (error) {
+ *   console.error(getStorageErrorMessage(error));
+ *   // "Invalid path format" or "Object not found" etc.
+ * }
+ * ```
+ */
+declare function getStorageErrorMessage(error: unknown): string;
+/**
+ * Normalize a storage path by removing leading slashes.
+ *
+ * Supabase Storage expects paths without leading slashes.
+ * This function ensures the path is properly formatted.
+ *
+ * @param path - The storage path to normalize
+ * @returns The normalized path without leading slashes
+ *
+ * @example
+ * ```typescript
+ * normalizeStoragePath('/foo/bar.jpg'); // 'foo/bar.jpg'
+ * normalizeStoragePath('foo/bar.jpg');  // 'foo/bar.jpg'
+ * normalizeStoragePath('//foo/bar.jpg'); // 'foo/bar.jpg'
+ * ```
+ */
+declare function normalizeStoragePath(path: string): string;
+
+/**
+ * Supabase Storage Adapter for @pol-studios/powersync
+ *
+ * Implements the unified SupabaseStorage interface for attachment operations.
+ * Uses Supabase Storage with platform-agnostic file system operations.
+ *
+ * Key features:
+ * - Memory-efficient downloads using signed URLs + native file system
+ * - Multi-bucket support via BucketConfig/BucketResolver
+ * - Platform-agnostic via FileSystemAdapter interface
+ * - Implements unified SupabaseStorage interface
+ */
+
+/**
+ * Supabase Storage adapter implementing the unified SupabaseStorage interface.
+ *
+ * Uses PlatformAdapter's fileSystem for I/O operations to remain platform-agnostic.
+ *
+ * IMPORTANT: This adapter downloads files using signed URLs + platform file system
+ * operations to avoid loading entire files into memory. This prevents OOM crashes
+ * on large files that occurred with the previous blob-based approach.
+ *
+ * @example
+ * ```typescript
+ * const adapter = new SupabaseStorageAdapter(
+ *   {
+ *     client: supabaseClient,
+ *     defaultBucket: 'attachments',
+ *     bucketMap: new Map([['avatars/', 'user-avatars']]),
+ *   },
+ *   platform.fileSystem
+ * );
+ *
+ * // Download returns file:// URI
+ * const localUri = await adapter.download('photos/image.jpg');
+ *
+ * // Upload from local file
+ * await adapter.upload('photos/new.jpg', localUri, 'image/jpeg');
+ *
+ * // Delete from remote storage
+ * await adapter.delete('photos/old.jpg');
+ * ```
+ */
+/**
+ * Image transform options for Supabase Storage.
+ * Used to compress/resize images on download via Supabase's transform feature.
+ */
+interface ImageTransformOptions {
+    /** Enable image transformation (default: true) */
+    enabled?: boolean;
+    /** Image width in pixels (default: 2048) */
+    width?: number;
+    /** Image height in pixels (optional, maintains aspect ratio if omitted) */
+    height?: number;
+    /** Compression quality 1-100 (default: 70) */
+    quality?: number;
+    /** Output format (default: 'origin' to keep original format) */
+    format?: 'origin' | 'avif' | 'webp';
+    /** Resize mode (default: 'contain') */
+    resize?: 'cover' | 'contain' | 'fill';
+}
+/**
+ * Options for SupabaseStorageAdapter constructor.
+ */
+interface SupabaseStorageAdapterOptions {
+    client: SupabaseClient;
+    defaultBucket: string;
+    bucketMap?: Map<string, string>;
+    bucketResolver?: (storagePath: string) => string | undefined;
+    signedUrlExpiry?: number;
+    logger?: LoggerAdapter;
+    /** Image transform options for compression on download */
+    imageTransform?: ImageTransformOptions;
+}
+declare class SupabaseStorageAdapter implements SupabaseStorage {
+    private client;
+    private defaultBucket;
+    private bucketMap?;
+    private bucketResolver?;
+    private signedUrlExpiry;
+    private fileSystem?;
+    private logger?;
+    private imageTransform?;
+    constructor(options: SupabaseStorageAdapterOptions, fileSystem?: FileSystemAdapter);
+    /**
+     * Update image transform options (can be set after construction).
+     */
+    setImageTransform(options: ImageTransformOptions): void;
+    /**
+     * Check if a file path is an image that supports transformation.
+     */
+    private isTransformableImage;
+    /**
+     * Set the file system adapter (can be set after construction).
+     */
+    setFileSystem(fileSystem: FileSystemAdapter): void;
+    /**
+     * Resolve the storage bucket for a given file path.
+     */
+    resolveBucket(filePath: string): string;
+    /**
+     * Download a file from Supabase Storage and return as a file:// URI.
+     *
+     * Uses streaming download to a temp file to avoid loading the entire file
+     * into memory. This prevents OOM crashes and FileReader hangs that occur
+     * with blob-based downloads in React Native after ~115 downloads.
+     *
+     * Implements SupabaseStorage.download
+     *
+     * @param path - Remote storage path
+     * @returns file:// URI pointing to the downloaded temp file
+     */
+    download(path: string): Promise<string>;
+    /**
+     * Download a file from Supabase Storage to a specific local path.
+     *
+     * Uses the platform's streaming downloadFile method to avoid loading
+     * the entire file into memory (prevents OOM on large files).
+     *
+     * @param remotePath - Remote storage path
+     * @param localPath - Local file path to write to
+     */
+    downloadToPath(remotePath: string, localPath: string): Promise<void>;
+    /**
+     * Upload a local file to Supabase Storage.
+     *
+     * Implements SupabaseStorage.upload
+     *
+     * @param path - Remote storage path
+     * @param localUri - Local file:// URI to upload from
+     * @param mediaType - MIME type of the file
+     * @param signal - Optional AbortSignal for cancellation
+     */
+    upload(path: string, localUri: string, mediaType: string, signal?: AbortSignal): Promise<void>;
+    /**
+     * Delete a file from Supabase Storage.
+     *
+     * Implements SupabaseStorage.delete
+     *
+     * @param path - Remote storage path to delete
+     */
+    delete(path: string): Promise<void>;
+    /**
+     * Get a signed download URL for a remote file.
+     *
+     * Includes session refresh logic to handle stale tokens during background downloads.
+     * If the initial request fails with an auth error (400/401/403), refreshes the session
+     * and retries once.
+     */
+    getDownloadUrl(remotePath: string): Promise<string>;
+    /**
+     * Check if a file exists in remote storage.
+     */
+    exists(remotePath: string): Promise<boolean>;
+    /**
+     * Download a file from remote storage.
+     * Alias for download() - for backward compatibility with AttachmentStorageAdapter interface.
+     *
+     * @param filePath - Remote storage path
+     * @returns file:// URI pointing to the downloaded temp file
+     */
+    downloadFile(filePath: string): Promise<string>;
+    /**
+     * Write data to a local file.
+     */
+    writeFile(fileURI: string, data: string, options?: {
+        encoding?: 'utf8' | 'base64';
+    }): Promise<void>;
+    /**
+     * Read data from a local file.
+     */
+    readFile(fileURI: string, options?: {
+        encoding?: 'utf8' | 'base64';
+        mediaType?: string;
+    }): Promise<ArrayBuffer>;
+    /**
+     * Delete a local file.
+     */
+    deleteFile(uri: string, _options?: {
+        filename?: string;
+    }): Promise<void>;
+    /**
+     * Check if a local file exists.
+     */
+    fileExists(fileURI: string): Promise<boolean>;
+    /**
+     * Create a directory.
+     */
+    makeDir(uri: string): Promise<void>;
+    /**
+     * Copy a file.
+     */
+    copyFile(sourceUri: string, targetUri: string): Promise<void>;
+    /**
+     * Get the user storage directory.
+     */
+    getUserStorageDirectory(): string;
+}
+/**
+ * Create a SupabaseStorageAdapter with simplified configuration.
+ *
+ * @example
+ * ```typescript
+ * const adapter = createSupabaseStorageAdapter(
+ *   supabaseClient,
+ *   'attachments',
+ *   platform.fileSystem
+ * );
+ * ```
+ */
+declare function createSupabaseStorageAdapter(client: SupabaseClient, defaultBucket: string, fileSystem?: FileSystemAdapter, options?: {
+    bucketMap?: Map<string, string>;
+    bucketResolver?: (storagePath: string) => string | undefined;
+    signedUrlExpiry?: number;
+    logger?: LoggerAdapter;
+}): SupabaseStorageAdapter;
+
+/**
+ * Cache Settings Types for @pol-studios/powersync
+ *
+ * Defines types for cache configuration storage.
+ * Note: UI-specific options (labels, descriptions) should be defined in the app.
+ */
+/**
+ * Cache settings stored via AsyncStorageAdapter.
+ */
+interface CacheSettings {
+    /**
+     * Maximum cache size in megabytes.
+     * A value of 0 indicates unlimited cache size.
+     */
+    maxCacheSizeMb: number;
+    /**
+     * Compression quality for cached images (0.0 to 1.0).
+     * Higher values mean better quality but larger file sizes.
+     */
+    compressionQuality: number;
+}
+/**
+ * Options for creating a CacheSettingsManager.
+ */
+interface CacheSettingsManagerOptions {
+    /**
+     * Prefix for storage keys.
+     * Useful for namespacing when multiple apps share storage.
+     * @default '@pol-studios/cache'
+     */
+    storageKeyPrefix?: string;
+    /**
+     * Default values for cache settings.
+     */
+    defaults?: Partial<CacheSettings>;
+}
+/**
+ * Default cache settings values.
+ */
+declare const DEFAULT_CACHE_SETTINGS: CacheSettings;
+
+/**
+ * Cache Settings Manager for @pol-studios/powersync
+ *
+ * Manages persistence of cache settings via AsyncStorageAdapter.
+ * Uses platform-agnostic storage interface for cross-platform support.
+ */
+
+/**
+ * Manages cache settings persistence using AsyncStorageAdapter.
+ *
+ * @example
+ * ```typescript
+ * const manager = new CacheSettingsManager(platform.storage, {
+ *   storageKeyPrefix: '@myapp/cache',
+ *   defaults: { maxCacheSizeMb: 2048 },
+ * });
+ *
+ * const settings = await manager.getSettings();
+ * await manager.setMaxCacheSizeMb(1024);
+ * ```
+ */
+declare class CacheSettingsManager {
+    private storage;
+    private keyPrefix;
+    private defaults;
+    constructor(storage: AsyncStorageAdapter, options?: CacheSettingsManagerOptions);
+    /**
+     * Get the full storage key for a setting.
+     */
+    private getKey;
+    /**
+     * Get all cache settings.
+     */
+    getSettings(): Promise<CacheSettings>;
+    /**
+     * Get the maximum cache size in megabytes.
+     * Returns 0 for unlimited.
+     */
+    getMaxCacheSizeMb(): Promise<number>;
+    /**
+     * Set the maximum cache size in megabytes.
+     * Use 0 for unlimited.
+     *
+     * @param mb - Maximum cache size in megabytes
+     */
+    setMaxCacheSizeMb(mb: number): Promise<void>;
+    /**
+     * Get the maximum cache size in bytes.
+     * Returns Number.MAX_SAFE_INTEGER for unlimited.
+     */
+    getMaxCacheSizeBytes(): Promise<number>;
+    /**
+     * Get the compression quality (0.0 to 1.0).
+     */
+    getCompressionQuality(): Promise<number>;
+    /**
+     * Set the compression quality.
+     *
+     * @param quality - Compression quality (0.0 to 1.0)
+     */
+    setCompressionQuality(quality: number): Promise<void>;
+    /**
+     * Reset all settings to defaults.
+     */
+    resetToDefaults(): Promise<void>;
+    /**
+     * Clear all stored settings.
+     */
+    clear(): Promise<void>;
+}
+
+export { CacheSettingsManager as C, DEFAULT_CACHE_SETTINGS as D, type ImageTransformOptions as I, SupabaseStorageAdapter as S, isBlobResult as a, isStorageAuthError as b, createSupabaseStorage as c, createSupabaseStorageAdapter as d, type SupabaseStorageAdapterOptions as e, type CacheSettings as f, getStorageErrorMessage as g, type CacheSettingsManagerOptions as h, isFileResult as i, normalizeStoragePath as n };