react-native-cloud-storage 2.2.1 → 2.3.0

package/src/{RNCloudStorage.ts → cloud-storage.ts}

@@ -5,60 +5,19 @@ import {
   type CloudStorageProviderOptions,
   type DeepRequired,
 } from './types/main';
-import type NativeRNCloudStorage from './types/native';
+import { NativeCloudStorageErrorCode, type NativeStorage } from './types/native';
 import { isProviderSupported } from './utils/helpers';
 import { NativeEventEmitter, NativeModules, Platform } from 'react-native';
-import CloudStorageError from './utils/CloudStorageError';
-import { CloudStorageErrorCode } from './types/native';
-import GoogleDrive from './google-drive';
-
-const LINKING_ERROR =
-  `The package 'react-native-cloud-storage' doesn't seem to be linked. Make sure: \n\n` +
-  Platform.select({ ios: "- You have run 'pod install'\n", default: '' }) +
-  '- You rebuilt the app after installing the package\n' +
-  '- You are not using Expo Go\n';
-
-// proxy NativeModules.CloudStorage to catch any errors thrown by the native module and wrap them in a CloudStorageError
-const nativeIosInstance = NativeModules.CloudStorage
-  ? new Proxy(NativeModules.CloudStorage, {
-      get(target: NativeRNCloudStorage, prop: keyof NativeRNCloudStorage) {
-        const originalFunction = target[prop];
-        if (typeof originalFunction === 'function') {
-          return async (...args: any[]) => {
-            try {
-              // @ts-expect-error - we can't know the types of the functions and their arguments
-              return await originalFunction(...args);
-            } catch (error: any) {
-              if (error?.code && Object.values(CloudStorageErrorCode).includes(error.code)) {
-                throw new CloudStorageError(error?.message || '', error.code as CloudStorageErrorCode);
-              } else {
-                throw new CloudStorageError('Unknown error', CloudStorageErrorCode.UNKNOWN, error);
-              }
-            }
-          };
-        }
-        return originalFunction;
-      },
-    })
-  : null;
-
-const defaultProviderOptions: DeepRequired<CloudStorageProviderOptions> = {
-  [CloudStorageProvider.ICloud]: {
-    scope: CloudStorageScope.AppData,
-  },
-  [CloudStorageProvider.GoogleDrive]: {
-    scope: CloudStorageScope.AppData,
-    accessToken: null,
-    strictFilenames: false,
-    timeout: 3000,
-  },
-};
+import GoogleDrive from './storages/google-drive';
+import { NativeCloudKit } from './storages/cloudkit';
+import { DEFAULT_PROVIDER_OPTIONS, LINKING_ERROR } from './utils/constants';
+import CloudStorageError from './utils/cloud-storage-error';
 
 export default class RNCloudStorage {
   private static defaultInstance: RNCloudStorage;
   private provider: {
     provider: CloudStorageProvider;
-    options: (typeof defaultProviderOptions)[keyof typeof defaultProviderOptions];
+    options: (typeof DEFAULT_PROVIDER_OPTIONS)[keyof typeof DEFAULT_PROVIDER_OPTIONS];
   };
   private cloudAvailabilityListeners: ((available: boolean) => void)[] = [];
 
@@ -77,7 +36,7 @@ export default class RNCloudStorage {
 
     this.provider = {
       provider: provider ?? RNCloudStorage.getDefaultProvider(),
-      options: defaultProviderOptions[provider ?? RNCloudStorage.getDefaultProvider()],
+      options: DEFAULT_PROVIDER_OPTIONS[provider ?? RNCloudStorage.getDefaultProvider()],
     };
 
     this.setProvider(provider ?? RNCloudStorage.getDefaultProvider());
@@ -86,22 +45,24 @@ export default class RNCloudStorage {
     }
   }
 
-  private get nativeInstance(): NativeRNCloudStorage {
+  private get nativeStorage(): NativeStorage {
     switch (this.provider.provider) {
-      case CloudStorageProvider.ICloud:
+      case CloudStorageProvider.ICloud: {
         return (
-          nativeIosInstance ??
-          new Proxy(
+          NativeCloudKit ??
+          (new Proxy(
             {},
             {
               get() {
                 throw new Error(LINKING_ERROR);
               },
             }
-          )
+          ) as NativeStorage)
         );
-      default:
+      }
+      default: {
         return new GoogleDrive(this.provider.options as DeepRequired<CloudStorageProviderOptions['googledrive']>);
+      }
     }
   }
 
@@ -111,10 +72,12 @@ export default class RNCloudStorage {
    */
   static getDefaultProvider(): CloudStorageProvider {
     switch (Platform.OS) {
-      case 'ios':
+      case 'ios': {
         return CloudStorageProvider.ICloud;
-      default:
+      }
+      default: {
         return CloudStorageProvider.GoogleDrive;
+      }
     }
   }
 
@@ -123,7 +86,7 @@ export default class RNCloudStorage {
    * @returns An array of supported CloudStorageProviders.
    */
   static getSupportedProviders(): CloudStorageProvider[] {
-    return Object.values(CloudStorageProvider).filter(isProviderSupported);
+    return Object.values(CloudStorageProvider).filter((provider) => isProviderSupported(provider));
   }
 
   /**
@@ -145,23 +108,23 @@ export default class RNCloudStorage {
 
     this.provider = {
       provider,
-      options: defaultProviderOptions[provider],
+      options: DEFAULT_PROVIDER_OPTIONS[provider],
     };
 
     // Emit an event to notify useIsCloudAvailable() hook consumers of the new cloud availability status
-    this.nativeInstance.isCloudAvailable().then((available) => {
-      this.cloudAvailabilityListeners.forEach((listener) => {
+    this.nativeStorage.isCloudAvailable().then((available) => {
+      for (const listener of this.cloudAvailabilityListeners) {
         listener(available);
-      });
+      }
     });
 
     if (provider === CloudStorageProvider.ICloud) {
       // Listen to native cloud availability change events
       const eventEmitter = new NativeEventEmitter(NativeModules.CloudStorageEventEmitter);
       eventEmitter.addListener('RNCloudStorage.cloud.availability-changed', (event: { available: boolean }) => {
-        this.cloudAvailabilityListeners.forEach((listener) => {
+        for (const listener of this.cloudAvailabilityListeners) {
           listener(event.available);
-        });
+        }
       });
     }
   }
@@ -187,11 +150,11 @@ export default class RNCloudStorage {
 
     if (this.provider.provider === CloudStorageProvider.GoogleDrive && 'accessToken' in newOptions) {
       // Emit an event to notify useIsCloudAvailable() hook consumers of the new cloud availability status
-      this.cloudAvailabilityListeners.forEach((listener) => {
+      for (const listener of this.cloudAvailabilityListeners) {
         listener(
           !!(newOptions as Required<CloudStorageProviderOptions[CloudStorageProvider.GoogleDrive]>).accessToken?.length
         );
-      });
+      }
     }
   }
 
@@ -211,7 +174,7 @@ export default class RNCloudStorage {
    * @returns A promise that resolves to true if the cloud storage is available, false otherwise.
    */
   isCloudAvailable(): Promise<boolean> {
-    return this.nativeInstance.isCloudAvailable();
+    return this.nativeStorage.isCloudAvailable();
   }
 
   /**
@@ -222,7 +185,7 @@ export default class RNCloudStorage {
    * @returns A promise that resolves when the data has been appended.
    */
   appendFile(path: string, data: string, scope?: CloudStorageScope): Promise<void> {
-    return this.nativeInstance.appendToFile(path, data, scope ?? this.provider.options.scope);
+    return this.nativeStorage.appendToFile(path, data, scope ?? this.provider.options.scope);
   }
 
   /**
@@ -232,7 +195,7 @@ export default class RNCloudStorage {
    * @returns A promise that resolves to true if the path exists, false otherwise.
    */
   exists(path: string, scope?: CloudStorageScope): Promise<boolean> {
-    return this.nativeInstance.fileExists(path, scope ?? this.provider.options.scope);
+    return this.nativeStorage.fileExists(path, scope ?? this.provider.options.scope);
   }
 
   /**
@@ -243,7 +206,7 @@ export default class RNCloudStorage {
    * @returns A promise that resolves when the file has been written.
    */
   writeFile(path: string, data: string, scope?: CloudStorageScope): Promise<void> {
-    return this.nativeInstance.createFile(path, data, scope ?? this.provider.options.scope, true);
+    return this.nativeStorage.createFile(path, data, scope ?? this.provider.options.scope, true);
   }
 
   /**
@@ -253,7 +216,7 @@ export default class RNCloudStorage {
    * @returns A promise that resolves when the directory has been created.
    */
   mkdir(path: string, scope?: CloudStorageScope): Promise<void> {
-    return this.nativeInstance.createDirectory(path, scope ?? this.provider.options.scope);
+    return this.nativeStorage.createDirectory(path, scope ?? this.provider.options.scope);
   }
 
   /**
@@ -263,7 +226,7 @@ export default class RNCloudStorage {
    * @returns A promise that resolves to an array of file names, excluding '.' and '..'.
    */
   readdir(path: string, scope?: CloudStorageScope): Promise<string[]> {
-    return this.nativeInstance.listFiles(path, scope ?? this.provider.options.scope);
+    return this.nativeStorage.listFiles(path, scope ?? this.provider.options.scope);
   }
 
   /**
@@ -273,17 +236,72 @@ export default class RNCloudStorage {
    * @returns A promise that resolves to the contents of the file.
    */
   readFile(path: string, scope?: CloudStorageScope): Promise<string> {
-    return this.nativeInstance.readFile(path, scope ?? this.provider.options.scope);
+    return this.nativeStorage.readFile(path, scope ?? this.provider.options.scope);
   }
 
   /**
-   * Downloads the file at the given path. Does not have any effect on Google Drive.
-   * @param path The file to trigger the download for.
+   * Triggers synchronization for the file at the given path. Does not have any effect on Google Drive.
+   * @param path The file to trigger synchronization for.
    * @param scope The directory scope the path is in. Defaults to set default scope set for the current provider.
-   * @returns A promise that resolves once the download has been triggered.
+   * @returns A promise that resolves once the synchronization has been triggered.
    */
-  downloadFile(path: string, scope?: CloudStorageScope): Promise<void> {
-    return this.nativeInstance.downloadFile(path, scope ?? this.provider.options.scope);
+  triggerSync(path: string, scope?: CloudStorageScope): Promise<void> {
+    return this.nativeStorage.triggerSync(path, scope ?? this.provider.options.scope);
+  }
+
+  /**
+   * Uploads the file at the given local path to the given path, creating it if it doesn't exist or overwriting it if it does.
+   * @param remotePath The remote path to upload to.
+   * @param localPath The local path of the file to upload.
+   * @param options The options for the upload. Must contain a `mimeType` property.
+   * @param scope The directory scope the path is in. Defaults to set default scope set for the current provider.
+   * @returns A promise that resolves when the file has been uploaded.
+   */
+  uploadFile(
+    remotePath: string,
+    localPath: string,
+    options: { mimeType: string },
+    scope?: CloudStorageScope
+  ): Promise<void> {
+    return this.nativeStorage.uploadFile(
+      remotePath,
+      localPath,
+      options.mimeType,
+      scope ?? this.provider.options.scope,
+      true
+    );
+  }
+
+  /**
+   * Triggers synchronization for the file at the given path. Does not have any effect on Google Drive.
+   * @param path The file to trigger synchronization for.
+   * @param scope The directory scope the path is in. Defaults to set default scope set for the current provider.
+   * @returns A promise that resolves once the synchronization has been triggered.
+   * @deprecated Use `triggerSync` instead.
+   */
+  downloadFile(path: string, scope?: CloudStorageScope): Promise<void>;
+  /**
+   * Downloads the cloud file at the given remote path to the given local path.
+   * @param remotePath The remote path of the file to download from the cloud.
+   * @param localPath The local path to download the cloud file to.
+   * @param scope The directory scope the path is in. Defaults to set default scope set for the current provider.
+   */
+  downloadFile(remotePath: string, localPath: string, scope?: CloudStorageScope): Promise<void>;
+  downloadFile(remotePathOrPath: string, localPathOrScope?: string, scope?: CloudStorageScope): Promise<void> {
+    if (
+      !localPathOrScope ||
+      (!scope &&
+        typeof localPathOrScope === 'string' &&
+        Object.values(CloudStorageScope).includes(localPathOrScope as CloudStorageScope))
+    ) {
+      // deprecated `triggerSync` call
+      return this.triggerSync(remotePathOrPath, scope);
+    }
+
+    if (!localPathOrScope) {
+      throw new CloudStorageError('Invalid arguments provided to downloadFile', NativeCloudStorageErrorCode.UNKNOWN);
+    }
+    return this.nativeStorage.downloadFile(remotePathOrPath, localPathOrScope, scope ?? this.provider.options.scope);
   }
 
   /**
@@ -293,7 +311,7 @@ export default class RNCloudStorage {
    * @returns A promise that resolves when the file has been deleted.
    */
   unlink(path: string, scope?: CloudStorageScope): Promise<void> {
-    return this.nativeInstance.deleteFile(path, scope ?? this.provider.options.scope);
+    return this.nativeStorage.deleteFile(path, scope ?? this.provider.options.scope);
   }
 
   /**
@@ -304,7 +322,7 @@ export default class RNCloudStorage {
    * @returns A promise that resolves when the directory has been deleted.
    */
   rmdir(path: string, options?: { recursive?: boolean }, scope?: CloudStorageScope): Promise<void> {
-    return this.nativeInstance.deleteDirectory(path, options?.recursive ?? false, scope ?? this.provider.options.scope);
+    return this.nativeStorage.deleteDirectory(path, options?.recursive ?? false, scope ?? this.provider.options.scope);
   }
 
   /**
@@ -314,7 +332,7 @@ export default class RNCloudStorage {
    * @returns A promise that resolves to the CloudStorageFileStat object.
    */
   async stat(path: string, scope?: CloudStorageScope): Promise<CloudStorageFileStat> {
-    const native = await this.nativeInstance.statFile(path, scope ?? this.provider.options.scope);
+    const native = await this.nativeStorage.statFile(path, scope ?? this.provider.options.scope);
 
     return {
       ...native,
@@ -438,13 +456,57 @@ export default class RNCloudStorage {
   }
 
   /**
-   * Downloads the file at the given path in the provider of the default static instance. Does not have any effect on Google Drive.
-   * @param path The file to trigger the download for.
+   * Triggers synchronization for the file at the given path in the provider of the default static instance. Does not have any effect on Google Drive.
+   * @param path The file to trigger synchronization for.
    * @param scope The directory scope the path is in. Defaults to the default scope set for the default static instance.
-   * @returns A promise that resolves once the download has been triggered.
+   * @returns A promise that resolves once the synchronization has been triggered.
+   */
+  static triggerSync(path: string, scope?: CloudStorageScope): Promise<void> {
+    return RNCloudStorage.getDefaultInstance().triggerSync(path, scope);
+  }
+
+  /**
+   * Uploads the file at the given local path to the given path in the provider of the default static instance, creating it if it doesn't exist or overwriting it if it does.
+   * @param remotePath The remote path to upload to.
+   * @param localPath The local path of the file to upload.
+   * @param options The options for the upload. Must contain a `mimeType` property.
+   * @param scope The directory scope the path is in. Defaults to set default scope set for the current provider.
+   * @returns A promise that resolves when the file has been uploaded.
    */
-  static downloadFile(path: string, scope?: CloudStorageScope): Promise<void> {
-    return RNCloudStorage.getDefaultInstance().downloadFile(path, scope);
+  static uploadFile(
+    remotePath: string,
+    localPath: string,
+    options: { mimeType: string },
+    scope?: CloudStorageScope
+  ): Promise<void> {
+    return RNCloudStorage.getDefaultInstance().uploadFile(remotePath, localPath, options, scope);
+  }
+
+  /**
+   * Triggers synchronization for the file at the given path in the provider of the default static instance. Does not have any effect on Google Drive.
+   * @param path The file to trigger synchronization for.
+   * @param scope The directory scope the path is in. Defaults to set default scope set for the current provider.
+   * @returns A promise that resolves once the synchronization has been triggered.
+   * @deprecated Use `triggerSync` instead.
+   */
+  static downloadFile(path: string, scope?: CloudStorageScope): Promise<void>;
+  /**
+   * Downloads the cloud file at the given remote path to the given local path.
+   * @param remotePath The remote path of the file to download from the cloud.
+   * @param localPath The local path to download the cloud file to.
+   * @param scope The directory scope the path is in. Defaults to set default scope set for the current provider.
+   */
+  static downloadFile(remotePath: string, localPath: string, scope?: CloudStorageScope): Promise<void>;
+  static downloadFile(remotePathOrPath: string, localPathOrScope?: string, scope?: CloudStorageScope): Promise<void> {
+    if (typeof scope === 'string') {
+      if (!localPathOrScope) {
+        throw new CloudStorageError('Invalid arguments provided to downloadFile', NativeCloudStorageErrorCode.UNKNOWN);
+      }
+      return RNCloudStorage.getDefaultInstance().downloadFile(remotePathOrPath, localPathOrScope, scope);
+    } else {
+      // deprecated `triggerSync` call
+      return RNCloudStorage.getDefaultInstance().triggerSync(remotePathOrPath, scope);
+    }
   }
 
   /**

package/src/expo-plugin/{withRNCloudStorage.ts → index.ts}

@@ -1,8 +1,8 @@
 import type { RNCloudStorageConfigPluginOptions } from './types';
-import withRNCloudStorageIos from './withRNCloudStorageIos';
+import withRNCloudStorageIos from './ios';
 import type { ConfigPlugin } from '@expo/config-plugins';
 
-// Android config plugin not needed as there's no native code to configure.
+// Android config plugin not needed as there's nothing to configure.
 
 const withRNCloudStorage: ConfigPlugin<RNCloudStorageConfigPluginOptions> = (config, options) =>
   withRNCloudStorageIos(config, options);

package/src/hooks/{useCloudFile.ts → use-cloud-file.ts}

@@ -1,5 +1,5 @@
 import type { CloudStorageScope } from '../types/main';
-import RNCloudStorage from '../RNCloudStorage';
+import RNCloudStorage from '../cloud-storage';
 import { useCallback, useEffect, useState } from 'react';
 
 /**
@@ -39,19 +39,37 @@ export const useCloudFile = (path: string, scope?: CloudStorageScope, cloudStora
     setContent(null);
   }, [path, scope, instance]);
 
-  const download = useCallback(async () => {
-    await instance.downloadFile(path, scope);
+  const sync = useCallback(async () => {
+    await instance.triggerSync(path, scope);
   }, [path, scope, instance]);
 
   return {
+    /**
+     * The content of the file.
+     */
     content,
+    /**
+     * Reads the file from the cloud.
+     */
     read,
+    /**
+     * Writes new content to the file.
+     */
     write,
+    /**
+     * Deletes the file.
+     */
     remove,
     /**
-     * Downloads the file from iCloud to the device. Needed if the file hasn't been synced yet. Has no effect on
-     * Google Drive.
+     * Triggers synchronization for the file. Needed if the file hasn't been synced yet from iCloud.
+     * Has no effect on Google Drive.
+     */
+    sync,
+    /**
+     * Triggers synchronization for the file. Needed if the file hasn't been synced yet from iCloud.
+     * Has no effect on Google Drive.
+     * @deprecated Use `sync` instead.
      */
-    download,
+    download: sync,
   };
 };

package/src/hooks/{useIsCloudAvailable.ts → use-is-cloud-available.ts}

@@ -1,5 +1,5 @@
 import { useCallback, useEffect, useState } from 'react';
-import RNCloudStorage from '../RNCloudStorage';
+import RNCloudStorage from '../cloud-storage';
 
 /**
  * A hook that tests whether or not the cloud storage is available.

package/src/index.ts

@@ -1,8 +1,7 @@
-import RNCloudStorage from './RNCloudStorage';
-import { CloudStorageErrorCode } from './types/native';
 export * from './types/main';
-export * from './hooks/useCloudFile';
-export * from './hooks/useIsCloudAvailable';
-import CloudStorageError from './utils/CloudStorageError';
+export * from './hooks/use-cloud-file';
+export * from './hooks/use-is-cloud-available';
 
-export { RNCloudStorage as CloudStorage, CloudStorageError, CloudStorageErrorCode };
+export { NativeCloudStorageErrorCode as CloudStorageErrorCode } from './types/native';
+export { default as CloudStorageError } from './utils/cloud-storage-error';
+export { default as CloudStorage } from './cloud-storage';

package/src/storages/cloudkit.ts

@@ -0,0 +1,5 @@
+import { NativeModules } from 'react-native';
+import { NativeStorage } from '../types/native';
+import { createProxiedNativeModule } from '../utils/native';
+
+export const NativeCloudKit = createProxiedNativeModule<NativeStorage>(NativeModules.CloudStorageCloudKit);