@pol-studios/powersync 1.0.0

package/dist/platform/index.d.ts

@@ -0,0 +1,280 @@
+import { A as AbstractPowerSyncDatabase } from '../types-afHtE1U_.js';
+
+/**
+ * Platform Adapter Types for @pol-studios/powersync
+ *
+ * This module defines the interfaces that platform-specific adapters must implement.
+ * Consumers provide an adapter for their platform (React Native or Web) that handles
+ * platform-specific operations like file system access, async storage, and network status.
+ */
+
+/**
+ * Options for creating a PowerSync database instance
+ */
+interface DatabaseOptions {
+    /** Database file name (e.g., "pol-offline.db") */
+    dbFilename: string;
+    /** PowerSync schema definition */
+    schema: unknown;
+    /** Optional: Encryption key for SQLite */
+    encryptionKey?: string;
+}
+/**
+ * Information about a file or directory
+ */
+interface FileInfo {
+    /** Whether the file/directory exists */
+    exists: boolean;
+    /** Size in bytes (0 for directories) */
+    size: number;
+    /** Last modification time */
+    modificationTime?: Date;
+    /** Whether this is a directory */
+    isDirectory: boolean;
+}
+/**
+ * File system operations interface.
+ *
+ * React Native: Implemented using expo-file-system
+ * Web: Implemented using IndexedDB or Cache API
+ */
+interface FileSystemAdapter {
+    /**
+     * Read a file's contents
+     * @param uri - The file URI/path
+     * @param encoding - How to encode the result ('base64' or 'utf8')
+     */
+    readFile(uri: string, encoding?: 'base64' | 'utf8'): Promise<string>;
+    /**
+     * Write data to a file (creates parent directories if needed)
+     * @param uri - The file URI/path
+     * @param data - The data to write
+     * @param encoding - How the data is encoded ('base64' or 'utf8')
+     */
+    writeFile(uri: string, data: string, encoding?: 'base64' | 'utf8'): Promise<void>;
+    /**
+     * Delete a file
+     * @param uri - The file URI/path
+     */
+    deleteFile(uri: string): Promise<void>;
+    /**
+     * Copy a file from source to destination
+     * @param source - Source file URI/path
+     * @param destination - Destination file URI/path
+     */
+    copyFile(source: string, destination: string): Promise<void>;
+    /**
+     * Move a file from source to destination
+     * @param source - Source file URI/path
+     * @param destination - Destination file URI/path
+     */
+    moveFile(source: string, destination: string): Promise<void>;
+    /**
+     * Get information about a file or directory
+     * @param uri - The file URI/path
+     * @returns File info or null if it doesn't exist
+     */
+    getFileInfo(uri: string): Promise<FileInfo | null>;
+    /**
+     * Create a directory
+     * @param uri - The directory URI/path
+     * @param options - Options for directory creation
+     */
+    makeDirectory(uri: string, options?: {
+        intermediates?: boolean;
+    }): Promise<void>;
+    /**
+     * Get the documents directory path for this platform
+     */
+    getDocumentsDirectory(): string;
+    /**
+     * Get the cache directory path for this platform
+     */
+    getCacheDirectory(): string;
+    /**
+     * Get the free disk space in bytes
+     */
+    getFreeDiskSpace(): Promise<number>;
+}
+/**
+ * Key-value storage interface for persisting preferences and state.
+ *
+ * React Native: Implemented using @react-native-async-storage/async-storage
+ * Web: Implemented using localStorage
+ */
+interface AsyncStorageAdapter {
+    /**
+     * Get a value by key
+     * @param key - The storage key
+     * @returns The stored value or null if not found
+     */
+    getItem(key: string): Promise<string | null>;
+    /**
+     * Set a value by key
+     * @param key - The storage key
+     * @param value - The value to store
+     */
+    setItem(key: string, value: string): Promise<void>;
+    /**
+     * Remove a value by key
+     * @param key - The storage key
+     */
+    removeItem(key: string): Promise<void>;
+    /**
+     * Get multiple values by keys
+     * @param keys - Array of storage keys
+     * @returns Array of [key, value] tuples
+     */
+    multiGet(keys: string[]): Promise<[string, string | null][]>;
+    /**
+     * Set multiple values
+     * @param entries - Array of [key, value] tuples
+     */
+    multiSet(entries: [string, string][]): Promise<void>;
+}
+/** Network connection types */
+type ConnectionType = 'wifi' | 'cellular' | 'ethernet' | 'unknown' | 'none';
+/**
+ * Network connectivity monitoring interface.
+ *
+ * React Native: Implemented using @react-native-community/netinfo
+ * Web: Implemented using navigator.onLine + online/offline events
+ */
+interface NetworkAdapter {
+    /**
+     * Check if the device is currently connected to the internet
+     */
+    isConnected(): Promise<boolean>;
+    /**
+     * Get the current connection type
+     */
+    getConnectionType(): Promise<ConnectionType>;
+    /**
+     * Add a listener for connection status changes
+     * @param callback - Called when connection status changes
+     * @returns Unsubscribe function
+     */
+    addConnectionListener(callback: (isConnected: boolean) => void): () => void;
+}
+/**
+ * Logging interface for debugging and monitoring.
+ * Allows consumers to use their existing logging infrastructure.
+ */
+interface LoggerAdapter {
+    /**
+     * Log a debug message (verbose, for development)
+     */
+    debug(message: string, ...args: unknown[]): void;
+    /**
+     * Log an info message (general information)
+     */
+    info(message: string, ...args: unknown[]): void;
+    /**
+     * Log a warning message (potential issues)
+     */
+    warn(message: string, ...args: unknown[]): void;
+    /**
+     * Log an error message (failures)
+     */
+    error(message: string, ...args: unknown[]): void;
+}
+/**
+ * Result of an image compression operation
+ */
+interface CompressedImage {
+    /** URI/path to the compressed image */
+    uri: string;
+    /** Width of the compressed image in pixels */
+    width: number;
+    /** Height of the compressed image in pixels */
+    height: number;
+}
+/**
+ * Options for image compression
+ */
+interface CompressionOptions {
+    /** Compression quality (0.0 to 1.0, where 1.0 is best quality) */
+    quality: number;
+    /** Maximum width in pixels (will scale down if larger) */
+    maxWidth?: number;
+    /** Maximum height in pixels (will scale down if larger) */
+    maxHeight?: number;
+    /** Output format */
+    format?: 'jpeg' | 'png' | 'webp';
+}
+/**
+ * Image processing interface for attachment compression.
+ *
+ * React Native: Implemented using expo-image-manipulator
+ * Web: Implemented using canvas API
+ *
+ * This is optional - if not provided, attachments won't be compressed.
+ */
+interface ImageProcessorAdapter {
+    /**
+     * Compress an image
+     * @param uri - The source image URI/path
+     * @param options - Compression options
+     * @returns The compressed image result
+     */
+    compress(uri: string, options: CompressionOptions): Promise<CompressedImage>;
+}
+/**
+ * Platform-specific adapter that consumers must provide.
+ * This allows the package to work across React Native and Web.
+ *
+ * @example React Native
+ * ```typescript
+ * import { createNativePlatformAdapter } from '@pol-studios/powersync/platform';
+ *
+ * const platform = createNativePlatformAdapter(logger);
+ * ```
+ *
+ * @example Web
+ * ```typescript
+ * import { createWebPlatformAdapter } from '@pol-studios/powersync/platform';
+ *
+ * const platform = createWebPlatformAdapter(logger);
+ * ```
+ */
+interface PlatformAdapter {
+    /**
+     * Create a PowerSync database instance for this platform.
+     *
+     * React Native: Uses PowerSyncDatabase from @powersync/react-native
+     * Web: Uses PowerSyncDatabase from @powersync/web
+     *
+     * @param options - Database creation options
+     * @returns Initialized PowerSync database
+     */
+    createDatabase(options: DatabaseOptions): Promise<AbstractPowerSyncDatabase>;
+    /**
+     * File system operations for attachment caching.
+     */
+    fileSystem: FileSystemAdapter;
+    /**
+     * Key-value storage for preferences and metrics persistence.
+     */
+    storage: AsyncStorageAdapter;
+    /**
+     * Network connectivity monitoring.
+     */
+    network: NetworkAdapter;
+    /**
+     * Logging interface.
+     */
+    logger: LoggerAdapter;
+    /**
+     * Optional: Image compression for attachment optimization.
+     * If not provided, attachments won't be compressed.
+     */
+    imageProcessor?: ImageProcessorAdapter;
+}
+/** Supported platform types */
+type PlatformType = 'react-native' | 'web' | 'unknown';
+/**
+ * Detect the current platform based on environment
+ */
+declare function detectPlatform(): PlatformType;
+
+export { type AsyncStorageAdapter, type CompressedImage, type CompressionOptions, type ConnectionType, type DatabaseOptions, type FileInfo, type FileSystemAdapter, type ImageProcessorAdapter, type LoggerAdapter, type NetworkAdapter, type PlatformAdapter, type PlatformType, detectPlatform };

package/dist/platform/index.js

@@ -0,0 +1,14 @@
+// src/platform/types.ts
+function detectPlatform() {
+  if (typeof navigator !== "undefined" && navigator.product === "ReactNative") {
+    return "react-native";
+  }
+  if (typeof window !== "undefined" && typeof document !== "undefined") {
+    return "web";
+  }
+  return "unknown";
+}
+export {
+  detectPlatform
+};
+//# sourceMappingURL=index.js.map

package/dist/platform/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/platform/types.ts"],"sourcesContent":["/**\n * Platform Adapter Types for @pol-studios/powersync\n *\n * This module defines the interfaces that platform-specific adapters must implement.\n * Consumers provide an adapter for their platform (React Native or Web) that handles\n * platform-specific operations like file system access, async storage, and network status.\n */\n\nimport type { AbstractPowerSyncDatabase } from '../core/types';\n\n// ─── Database Factory Options ────────────────────────────────────────────────\n\n/**\n * Options for creating a PowerSync database instance\n */\nexport interface DatabaseOptions {\n  /** Database file name (e.g., \"pol-offline.db\") */\n  dbFilename: string;\n  /** PowerSync schema definition */\n  schema: unknown; // Schema type from @powersync/common\n  /** Optional: Encryption key for SQLite */\n  encryptionKey?: string;\n}\n\n// ─── File System Adapter ─────────────────────────────────────────────────────\n\n/**\n * Information about a file or directory\n */\nexport interface FileInfo {\n  /** Whether the file/directory exists */\n  exists: boolean;\n  /** Size in bytes (0 for directories) */\n  size: number;\n  /** Last modification time */\n  modificationTime?: Date;\n  /** Whether this is a directory */\n  isDirectory: boolean;\n}\n\n/**\n * File system operations interface.\n *\n * React Native: Implemented using expo-file-system\n * Web: Implemented using IndexedDB or Cache API\n */\nexport interface FileSystemAdapter {\n  /**\n   * Read a file's contents\n   * @param uri - The file URI/path\n   * @param encoding - How to encode the result ('base64' or 'utf8')\n   */\n  readFile(uri: string, encoding?: 'base64' | 'utf8'): Promise<string>;\n\n  /**\n   * Write data to a file (creates parent directories if needed)\n   * @param uri - The file URI/path\n   * @param data - The data to write\n   * @param encoding - How the data is encoded ('base64' or 'utf8')\n   */\n  writeFile(uri: string, data: string, encoding?: 'base64' | 'utf8'): Promise<void>;\n\n  /**\n   * Delete a file\n   * @param uri - The file URI/path\n   */\n  deleteFile(uri: string): Promise<void>;\n\n  /**\n   * Copy a file from source to destination\n   * @param source - Source file URI/path\n   * @param destination - Destination file URI/path\n   */\n  copyFile(source: string, destination: string): Promise<void>;\n\n  /**\n   * Move a file from source to destination\n   * @param source - Source file URI/path\n   * @param destination - Destination file URI/path\n   */\n  moveFile(source: string, destination: string): Promise<void>;\n\n  /**\n   * Get information about a file or directory\n   * @param uri - The file URI/path\n   * @returns File info or null if it doesn't exist\n   */\n  getFileInfo(uri: string): Promise<FileInfo | null>;\n\n  /**\n   * Create a directory\n   * @param uri - The directory URI/path\n   * @param options - Options for directory creation\n   */\n  makeDirectory(uri: string, options?: { intermediates?: boolean }): Promise<void>;\n\n  /**\n   * Get the documents directory path for this platform\n   */\n  getDocumentsDirectory(): string;\n\n  /**\n   * Get the cache directory path for this platform\n   */\n  getCacheDirectory(): string;\n\n  /**\n   * Get the free disk space in bytes\n   */\n  getFreeDiskSpace(): Promise<number>;\n}\n\n// ─── Async Storage Adapter ───────────────────────────────────────────────────\n\n/**\n * Key-value storage interface for persisting preferences and state.\n *\n * React Native: Implemented using @react-native-async-storage/async-storage\n * Web: Implemented using localStorage\n */\nexport interface AsyncStorageAdapter {\n  /**\n   * Get a value by key\n   * @param key - The storage key\n   * @returns The stored value or null if not found\n   */\n  getItem(key: string): Promise<string | null>;\n\n  /**\n   * Set a value by key\n   * @param key - The storage key\n   * @param value - The value to store\n   */\n  setItem(key: string, value: string): Promise<void>;\n\n  /**\n   * Remove a value by key\n   * @param key - The storage key\n   */\n  removeItem(key: string): Promise<void>;\n\n  /**\n   * Get multiple values by keys\n   * @param keys - Array of storage keys\n   * @returns Array of [key, value] tuples\n   */\n  multiGet(keys: string[]): Promise<[string, string | null][]>;\n\n  /**\n   * Set multiple values\n   * @param entries - Array of [key, value] tuples\n   */\n  multiSet(entries: [string, string][]): Promise<void>;\n}\n\n// ─── Network Adapter ─────────────────────────────────────────────────────────\n\n/** Network connection types */\nexport type ConnectionType = 'wifi' | 'cellular' | 'ethernet' | 'unknown' | 'none';\n\n/**\n * Network connectivity monitoring interface.\n *\n * React Native: Implemented using @react-native-community/netinfo\n * Web: Implemented using navigator.onLine + online/offline events\n */\nexport interface NetworkAdapter {\n  /**\n   * Check if the device is currently connected to the internet\n   */\n  isConnected(): Promise<boolean>;\n\n  /**\n   * Get the current connection type\n   */\n  getConnectionType(): Promise<ConnectionType>;\n\n  /**\n   * Add a listener for connection status changes\n   * @param callback - Called when connection status changes\n   * @returns Unsubscribe function\n   */\n  addConnectionListener(callback: (isConnected: boolean) => void): () => void;\n}\n\n// ─── Logger Adapter ──────────────────────────────────────────────────────────\n\n/**\n * Logging interface for debugging and monitoring.\n * Allows consumers to use their existing logging infrastructure.\n */\nexport interface LoggerAdapter {\n  /**\n   * Log a debug message (verbose, for development)\n   */\n  debug(message: string, ...args: unknown[]): void;\n\n  /**\n   * Log an info message (general information)\n   */\n  info(message: string, ...args: unknown[]): void;\n\n  /**\n   * Log a warning message (potential issues)\n   */\n  warn(message: string, ...args: unknown[]): void;\n\n  /**\n   * Log an error message (failures)\n   */\n  error(message: string, ...args: unknown[]): void;\n}\n\n// ─── Image Processor Adapter ─────────────────────────────────────────────────\n\n/**\n * Result of an image compression operation\n */\nexport interface CompressedImage {\n  /** URI/path to the compressed image */\n  uri: string;\n  /** Width of the compressed image in pixels */\n  width: number;\n  /** Height of the compressed image in pixels */\n  height: number;\n}\n\n/**\n * Options for image compression\n */\nexport interface CompressionOptions {\n  /** Compression quality (0.0 to 1.0, where 1.0 is best quality) */\n  quality: number;\n  /** Maximum width in pixels (will scale down if larger) */\n  maxWidth?: number;\n  /** Maximum height in pixels (will scale down if larger) */\n  maxHeight?: number;\n  /** Output format */\n  format?: 'jpeg' | 'png' | 'webp';\n}\n\n/**\n * Image processing interface for attachment compression.\n *\n * React Native: Implemented using expo-image-manipulator\n * Web: Implemented using canvas API\n *\n * This is optional - if not provided, attachments won't be compressed.\n */\nexport interface ImageProcessorAdapter {\n  /**\n   * Compress an image\n   * @param uri - The source image URI/path\n   * @param options - Compression options\n   * @returns The compressed image result\n   */\n  compress(uri: string, options: CompressionOptions): Promise<CompressedImage>;\n}\n\n// ─── Main Platform Adapter Interface ─────────────────────────────────────────\n\n/**\n * Platform-specific adapter that consumers must provide.\n * This allows the package to work across React Native and Web.\n *\n * @example React Native\n * ```typescript\n * import { createNativePlatformAdapter } from '@pol-studios/powersync/platform';\n *\n * const platform = createNativePlatformAdapter(logger);\n * ```\n *\n * @example Web\n * ```typescript\n * import { createWebPlatformAdapter } from '@pol-studios/powersync/platform';\n *\n * const platform = createWebPlatformAdapter(logger);\n * ```\n */\nexport interface PlatformAdapter {\n  /**\n   * Create a PowerSync database instance for this platform.\n   *\n   * React Native: Uses PowerSyncDatabase from @powersync/react-native\n   * Web: Uses PowerSyncDatabase from @powersync/web\n   *\n   * @param options - Database creation options\n   * @returns Initialized PowerSync database\n   */\n  createDatabase(options: DatabaseOptions): Promise<AbstractPowerSyncDatabase>;\n\n  /**\n   * File system operations for attachment caching.\n   */\n  fileSystem: FileSystemAdapter;\n\n  /**\n   * Key-value storage for preferences and metrics persistence.\n   */\n  storage: AsyncStorageAdapter;\n\n  /**\n   * Network connectivity monitoring.\n   */\n  network: NetworkAdapter;\n\n  /**\n   * Logging interface.\n   */\n  logger: LoggerAdapter;\n\n  /**\n   * Optional: Image compression for attachment optimization.\n   * If not provided, attachments won't be compressed.\n   */\n  imageProcessor?: ImageProcessorAdapter;\n}\n\n// ─── Platform Detection ──────────────────────────────────────────────────────\n\n/** Supported platform types */\nexport type PlatformType = 'react-native' | 'web' | 'unknown';\n\n/**\n * Detect the current platform based on environment\n */\nexport function detectPlatform(): PlatformType {\n  // Check for React Native\n  if (typeof navigator !== 'undefined' && navigator.product === 'ReactNative') {\n    return 'react-native';\n  }\n\n  // Check for browser environment\n  if (typeof window !== 'undefined' && typeof document !== 'undefined') {\n    return 'web';\n  }\n\n  return 'unknown';\n}\n"],"mappings":";AAsUO,SAAS,iBAA+B;AAE7C,MAAI,OAAO,cAAc,eAAe,UAAU,YAAY,eAAe;AAC3E,WAAO;AAAA,EACT;AAGA,MAAI,OAAO,WAAW,eAAe,OAAO,aAAa,aAAa;AACpE,WAAO;AAAA,EACT;AAEA,SAAO;AACT;","names":[]}

package/dist/platform/index.native.d.ts

@@ -0,0 +1,37 @@
+import { LoggerAdapter, PlatformAdapter } from './index.js';
+import '../types-afHtE1U_.js';
+
+/**
+ * React Native Platform Adapter for @pol-studios/powersync
+ *
+ * Implements the PlatformAdapter interface using React Native specific APIs:
+ * - @powersync/react-native for SQLite database
+ * - expo-file-system for file operations
+ * - @react-native-async-storage/async-storage for key-value storage
+ * - @react-native-community/netinfo for network monitoring
+ * - expo-image-manipulator for image compression
+ */
+
+/**
+ * Create a React Native platform adapter
+ *
+ * @param logger - Logger implementation to use
+ * @returns Platform adapter configured for React Native
+ *
+ * @example
+ * ```typescript
+ * import { createNativePlatformAdapter } from '@pol-studios/powersync/platform';
+ *
+ * const logger = {
+ *   debug: console.log,
+ *   info: console.log,
+ *   warn: console.warn,
+ *   error: console.error,
+ * };
+ *
+ * const platform = createNativePlatformAdapter(logger);
+ * ```
+ */
+declare function createNativePlatformAdapter(logger: LoggerAdapter): PlatformAdapter;
+
+export { LoggerAdapter, PlatformAdapter, createNativePlatformAdapter };

package/dist/platform/index.native.js

@@ -0,0 +1,7 @@
+import {
+  createNativePlatformAdapter
+} from "../chunk-4FJVBR3X.js";
+export {
+  createNativePlatformAdapter
+};
+//# sourceMappingURL=index.native.js.map

package/dist/platform/index.native.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/platform/index.web.d.ts

@@ -0,0 +1,37 @@
+import { LoggerAdapter, PlatformAdapter } from './index.js';
+import '../types-afHtE1U_.js';
+
+/**
+ * Web Platform Adapter for @pol-studios/powersync
+ *
+ * Implements the PlatformAdapter interface using Web APIs:
+ * - @powersync/web for SQLite database (via wa-sqlite)
+ * - IndexedDB for file storage (via idb-keyval pattern)
+ * - localStorage for key-value storage
+ * - navigator.onLine + events for network monitoring
+ * - Canvas API for image compression
+ */
+
+/**
+ * Create a Web platform adapter
+ *
+ * @param logger - Logger implementation to use
+ * @returns Platform adapter configured for Web/PWA
+ *
+ * @example
+ * ```typescript
+ * import { createWebPlatformAdapter } from '@pol-studios/powersync/platform';
+ *
+ * const logger = {
+ *   debug: console.log,
+ *   info: console.log,
+ *   warn: console.warn,
+ *   error: console.error,
+ * };
+ *
+ * const platform = createWebPlatformAdapter(logger);
+ * ```
+ */
+declare function createWebPlatformAdapter(logger: LoggerAdapter): PlatformAdapter;
+
+export { LoggerAdapter, PlatformAdapter, createWebPlatformAdapter };

package/dist/platform/index.web.js

@@ -0,0 +1,7 @@
+import {
+  createWebPlatformAdapter
+} from "../chunk-BJ36QDFN.js";
+export {
+  createWebPlatformAdapter
+};
+//# sourceMappingURL=index.web.js.map

package/dist/platform/index.web.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}