react-native-cloud-storage 1.4.2 → 1.5.0

package/src/RNCloudStorage.ts

@@ -1,137 +1,320 @@
-import { Platform } from 'react-native';
-import createRNCloudStorage from './createRNCloudStorage';
+import {
+  CloudStorageProvider,
+  CloudStorageScope,
+  type CloudStorageFileStat,
+  type CloudStorageProviderOptions,
+  type DeepRequired,
+} from './types/main';
+import type NativeRNCloudStorage 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';
-import { CloudStorageScope, type CloudStorageFileStat } from './types/main';
-import { verifyLeadingSlash } from './utils/helpers';
-
-const nativeInstance = createRNCloudStorage();
-let defaultScope = CloudStorageScope.AppData;
-
-const RNCloudStorage = {
-  getDefaultScope: () => defaultScope,
-  setDefaultScope: (scope: CloudStorageScope) => (defaultScope = scope),
-  getGoogleDriveAccessToken: () => GoogleDrive.accessToken,
-  setGoogleDriveAccessToken: (accessToken: string | null) => (GoogleDrive.accessToken = accessToken),
-  setThrowOnFilesWithSameName: (enable: boolean) => (GoogleDrive.throwOnFilesWithSameName = enable),
-  setTimeout: (timeout: number) => (GoogleDrive.timeout = timeout),
-  /* eslint-disable @typescript-eslint/no-unused-vars */
-  subscribeToFilesWithSameName:
-    Platform.OS === 'ios'
-      ? // @ts-expect-error - subscriber is undefined; just a mock
-        (subscriber: ({ path, fileIds }: { path: string; fileIds: string[] }) => void) => ({ remove: () => {} })
-      : (nativeInstance as GoogleDrive).subscribeToFilesWithSameName.bind(nativeInstance),
-  /* eslint-enable @typescript-eslint/no-unused-vars */
+
+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,
+  },
+};
+
+export default class RNCloudStorage {
+  private static defaultInstance: RNCloudStorage;
+  private provider: {
+    provider: CloudStorageProvider;
+    options: (typeof defaultProviderOptions)[keyof typeof defaultProviderOptions];
+  };
+  private cloudAvailabilityListeners: ((available: boolean) => void)[] = [];
+
+  //#region Constructor and configuration
+  /**
+   * Creates a new RNCloudStorage instance for the given provider.
+   * @param provider The provider to create the instance for. Defaults to the default provider for the current platform.
+   */
+  constructor(
+    provider?: CloudStorageProvider,
+    options?: CloudStorageProviderOptions[keyof CloudStorageProviderOptions]
+  ) {
+    if (provider && !isProviderSupported(provider)) {
+      throw new Error(`Provider ${provider} is not supported on the current platform.`);
+    }
+
+    this.provider = {
+      provider: provider ?? RNCloudStorage.getDefaultProvider(),
+      options: defaultProviderOptions[provider ?? RNCloudStorage.getDefaultProvider()],
+    };
+
+    this.setProvider(provider ?? RNCloudStorage.getDefaultProvider());
+    if (options) {
+      this.setProviderOptions(options);
+    }
+  }
+
+  private get nativeInstance(): NativeRNCloudStorage {
+    switch (this.provider.provider) {
+      case CloudStorageProvider.ICloud:
+        return (
+          nativeIosInstance ??
+          new Proxy(
+            {},
+            {
+              get() {
+                throw new Error(LINKING_ERROR);
+              },
+            }
+          )
+        );
+      default:
+        return new GoogleDrive(this.provider.options as DeepRequired<CloudStorageProviderOptions['googledrive']>);
+    }
+  }
+
+  /**
+   * Gets the default CloudStorageProvider for the current platform.
+   * @returns The default CloudStorageProvider.
+   */
+  static getDefaultProvider(): CloudStorageProvider {
+    switch (Platform.OS) {
+      case 'ios':
+        return CloudStorageProvider.ICloud;
+      default:
+        return CloudStorageProvider.GoogleDrive;
+    }
+  }
+
+  /**
+   * Gets the list of supported CloudStorageProviders on the current platform.
+   * @returns An array of supported CloudStorageProviders.
+   */
+  static getSupportedProviders(): CloudStorageProvider[] {
+    return Object.values(CloudStorageProvider).filter(isProviderSupported);
+  }
+
+  /**
+   * Gets the current CloudStorageProvider.
+   * @returns The current CloudStorageProvider.
+   */
+  getProvider(): CloudStorageProvider {
+    return this.provider.provider;
+  }
+
+  /**
+   * Sets the current CloudStorageProvider.
+   * @param provider The provider to set.
+   */
+  setProvider(provider: CloudStorageProvider): void {
+    if (!isProviderSupported(provider)) {
+      throw new Error(`Provider ${provider} is not supported on the current platform.`);
+    }
+
+    this.provider = {
+      provider,
+      options: defaultProviderOptions[provider],
+    };
+
+    // Emit an event to notify useIsCloudAvailable() hook consumers of the new cloud availability status
+    this.nativeInstance.isCloudAvailable().then((available) => {
+      this.cloudAvailabilityListeners.forEach((listener) => {
+        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) => {
+          listener(event.available);
+        });
+      });
+    }
+  }
+
+  /**
+   * Gets the current options for the current provider.
+   * @returns The current options for the current provider.
+   */
+  getProviderOptions(): CloudStorageProviderOptions[keyof CloudStorageProviderOptions] {
+    return this.provider.options;
+  }
 
+  /**
+   * Sets the options for the current provider.
+   * @param options The options to set for the provider.
+   */
+  setProviderOptions(options: CloudStorageProviderOptions[keyof CloudStorageProviderOptions]): void {
+    const newOptions = Object.fromEntries(Object.entries(options).filter(([_, v]) => v !== undefined));
+    this.provider.options = {
+      ...this.provider.options,
+      ...newOptions,
+    };
+
+    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) => {
+        listener(
+          !!(newOptions as Required<CloudStorageProviderOptions[CloudStorageProvider.GoogleDrive]>).accessToken?.length
+        );
+      });
+    }
+  }
+
+  subscribeToCloudAvailability(listener: (available: boolean) => void): void {
+    this.cloudAvailabilityListeners.push(listener);
+  }
+
+  unsubscribeFromCloudAvailability(listener: (available: boolean) => void): void {
+    this.cloudAvailabilityListeners = this.cloudAvailabilityListeners.filter((l) => l !== listener);
+  }
+  //#endregion
+
+  //#region File system operations
   /**
    * Tests whether or not the cloud storage is available. Always returns true for Google Drive. iCloud may be
    * unavailable right after app launch or if the user is not logged in.
    * @returns A promise that resolves to true if the cloud storage is available, false otherwise.
    */
-  isCloudAvailable: async (): Promise<boolean> => {
-    return nativeInstance.isCloudAvailable();
-  },
+  isCloudAvailable(): Promise<boolean> {
+    return this.nativeInstance.isCloudAvailable();
+  }
 
   /**
    * Appends the data to the file at the given path, creating the file if it doesn't exist.
    * @param path The file to append to.
    * @param data The data to append.
-   * @param scope The directory scope the path is in. Defaults to the set default scope.
+   * @param scope The directory scope the path is in. Defaults to the default scope set for the current provider.
    * @returns A promise that resolves when the data has been appended.
    */
-  appendFile: (path: string, data: string, scope?: CloudStorageScope): Promise<void> => {
-    return nativeInstance.appendToFile(verifyLeadingSlash(path), data, scope ?? defaultScope);
-  },
+  appendFile(path: string, data: string, scope?: CloudStorageScope): Promise<void> {
+    return this.nativeInstance.appendToFile(path, data, scope ?? this.provider.options.scope);
+  }
 
   /**
    * Tests whether or not the file at the given path exists.
    * @param path The path to test.
-   * @param scope The directory scope the path is in. Defaults to the set default scope.
+   * @param scope The directory scope the path is in. Defaults to set default scope set for the current provider.
    * @returns A promise that resolves to true if the path exists, false otherwise.
    */
-  exists: (path: string, scope?: CloudStorageScope): Promise<boolean> => {
-    return nativeInstance.fileExists(verifyLeadingSlash(path), scope ?? defaultScope);
-  },
+  exists(path: string, scope?: CloudStorageScope): Promise<boolean> {
+    return this.nativeInstance.fileExists(path, scope ?? this.provider.options.scope);
+  }
 
   /**
    * Writes to the file at the given path, creating it if it doesn't exist or overwriting it if it does.
    * @param path The file to write to.
    * @param data The data to write.
-   * @param scope The directory scope the path is in. Defaults to the set default scope.
+   * @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 written.
    */
-  writeFile: (path: string, data: string, scope?: CloudStorageScope): Promise<void> => {
-    return nativeInstance.createFile(verifyLeadingSlash(path), data, scope ?? defaultScope, true);
-  },
+  writeFile(path: string, data: string, scope?: CloudStorageScope): Promise<void> {
+    return this.nativeInstance.createFile(path, data, scope ?? this.provider.options.scope, true);
+  }
 
   /**
    * Creates a new directory at the given path.
    * @param path The directory to create.
-   * @param scope The directory scope the path is in. Defaults to the set default scope.
+   * @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 directory has been created.
    */
-  mkdir: (path: string, scope?: CloudStorageScope): Promise<void> => {
-    return nativeInstance.createDirectory(verifyLeadingSlash(path), scope ?? defaultScope);
-  },
+  mkdir(path: string, scope?: CloudStorageScope): Promise<void> {
+    return this.nativeInstance.createDirectory(path, scope ?? this.provider.options.scope);
+  }
 
   /**
    * Lists the contents of the directory at the given path.
    * @param path The directory to list.
-   * @param scope The directory scope the path is in. Defaults to the set default scope.
+   * @param scope The directory scope the path is in. Defaults to set default scope set for the current provider.
    * @returns A promise that resolves to an array of file names, excluding '.' and '..'.
    */
-  readdir: (path: string, scope?: CloudStorageScope): Promise<string[]> => {
-    return nativeInstance.listFiles(verifyLeadingSlash(path), scope ?? defaultScope);
-  },
+  readdir(path: string, scope?: CloudStorageScope): Promise<string[]> {
+    return this.nativeInstance.listFiles(path, scope ?? this.provider.options.scope);
+  }
 
   /**
    * Reads the contents of the file at the given path.
    * @param path The file to read.
-   * @param scope The directory scope the path is in. Defaults to the set default scope.
+   * @param scope The directory scope the path is in. Defaults to set default scope set for the current provider.
    * @returns A promise that resolves to the contents of the file.
    */
-  readFile: (path: string, scope?: CloudStorageScope): Promise<string> => {
-    return nativeInstance.readFile(verifyLeadingSlash(path), scope ?? defaultScope);
-  },
+  readFile(path: string, scope?: CloudStorageScope): Promise<string> {
+    return this.nativeInstance.readFile(path, scope ?? this.provider.options.scope);
+  }
 
   /**
-   * Downloads the file at the given path from iCloud. Does not have any effect on Google Drive.
+   * Downloads the file at the given path. Does not have any effect on Google Drive.
    * @param path The file to trigger the download for.
-   * @param scope The directory scope the path is in. Defaults to the set default scope.
+   * @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.
    */
-  downloadFile: (path: string, scope?: CloudStorageScope): Promise<void> => {
-    return nativeInstance.downloadFile(verifyLeadingSlash(path), scope ?? defaultScope);
-  },
+  downloadFile(path: string, scope?: CloudStorageScope): Promise<void> {
+    return this.nativeInstance.downloadFile(path, scope ?? this.provider.options.scope);
+  }
 
   /**
    * Deletes the file at the given path.
    * @param path The file to delete.
-   * @param scope The directory scope the path is in. Defaults to the set default scope.
+   * @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 deleted.
    */
-  unlink: (path: string, scope?: CloudStorageScope): Promise<void> => {
-    return nativeInstance.deleteFile(verifyLeadingSlash(path), scope ?? defaultScope);
-  },
+  unlink(path: string, scope?: CloudStorageScope): Promise<void> {
+    return this.nativeInstance.deleteFile(path, scope ?? this.provider.options.scope);
+  }
 
   /**
    * Deletes the directory at the given path.
    * @param path The directory to delete.
    * @param options Options for the delete operation. Defaults to { recursive: false }.
-   * @param scope The directory scope the path is in. Defaults to the set default scope.
+   * @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 directory has been deleted.
    */
-  rmdir: (path: string, options?: { recursive?: boolean }, scope?: CloudStorageScope): Promise<void> => {
-    return nativeInstance.deleteDirectory(verifyLeadingSlash(path), options?.recursive ?? false, scope ?? defaultScope);
-  },
+  rmdir(path: string, options?: { recursive?: boolean }, scope?: CloudStorageScope): Promise<void> {
+    return this.nativeInstance.deleteDirectory(path, options?.recursive ?? false, scope ?? this.provider.options.scope);
+  }
 
   /**
    * Gets the size, creation time, and modification time of the file at the given path.
    * @param path The file to stat.
-   * @param scope The directory scope the path is in. Defaults to the set default scope.
+   * @param scope The directory scope the path is in. Defaults to set default scope set for the current provider.
    * @returns A promise that resolves to the CloudStorageFileStat object.
    */
-  stat: async (path: string, scope?: CloudStorageScope): Promise<CloudStorageFileStat> => {
-    const native = await nativeInstance.statFile(verifyLeadingSlash(path), scope ?? defaultScope);
+  async stat(path: string, scope?: CloudStorageScope): Promise<CloudStorageFileStat> {
+    const native = await this.nativeInstance.statFile(path, scope ?? this.provider.options.scope);
 
     return {
       ...native,
@@ -140,7 +323,143 @@ const RNCloudStorage = {
       isDirectory: () => native.isDirectory,
       isFile: () => native.isFile,
     };
-  },
-};
+  }
+  //#endregion
+
+  //#region Static methods for default static instance
+  static getDefaultInstance(): RNCloudStorage {
+    if (!RNCloudStorage.defaultInstance) {
+      RNCloudStorage.defaultInstance = new RNCloudStorage();
+    }
+    return RNCloudStorage.defaultInstance;
+  }
+
+  /**
+   * Gets the current options for the provider of the default static instance.
+   * @returns The current options for the provider of the default static instance.
+   */
+  static getProviderOptions(): CloudStorageProviderOptions[keyof CloudStorageProviderOptions] {
+    return RNCloudStorage.getDefaultInstance().getProviderOptions();
+  }
+
+  /**
+   * Sets the options for the provider of the default static instance.
+   * @param options The options to set for the provider of the default static instance.
+   */
+  static setProviderOptions(options: CloudStorageProviderOptions[keyof CloudStorageProviderOptions]): void {
+    RNCloudStorage.getDefaultInstance().setProviderOptions(options);
+  }
+
+  /**
+   * Tests whether or not the file at the given path exists in the provider of the default static instance.
+   * @param path The path to test.
+   * @param scope The directory scope the path is in. Defaults to set default scope set for the current provider.
+   * @returns A promise that resolves to true if the path exists, false otherwise.
+   */
+  static exists(path: string, scope?: CloudStorageScope): Promise<boolean> {
+    return RNCloudStorage.getDefaultInstance().exists(path, scope);
+  }
+
+  /**
+   * Tests whether or not the cloud storage is available for the provider of the default static instance. Always returns true for Google Drive. iCloud may be
+   * unavailable right after app launch or if the user is not logged in.
+   * @returns A promise that resolves to true if the cloud storage is available, false otherwise.
+   */
+  static isCloudAvailable(): Promise<boolean> {
+    return RNCloudStorage.getDefaultInstance().isCloudAvailable();
+  }
+
+  /**
+   * Appends the data to the file at the given path in the provider of the default static instance, creating the file if it doesn't exist.
+   * @param path The file to append to.
+   * @param data The data to append.
+   * @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 when the data has been appended.
+   */
+  static appendFile(path: string, data: string, scope?: CloudStorageScope): Promise<void> {
+    return RNCloudStorage.getDefaultInstance().appendFile(path, data, scope);
+  }
+
+  /**
+   * Writes to the file at 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 path The file to write to.
+   * @param data The data to write.
+   * @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 when the file has been written.
+   */
+  static writeFile(path: string, data: string, scope?: CloudStorageScope): Promise<void> {
+    return RNCloudStorage.getDefaultInstance().writeFile(path, data, scope);
+  }
+
+  /**
+   * Creates a new directory at the given path in the provider of the default static instance.
+   * @param path The directory to create.
+   * @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 when the directory has been created.
+   */
+  static mkdir(path: string, scope?: CloudStorageScope): Promise<void> {
+    return RNCloudStorage.getDefaultInstance().mkdir(path, scope);
+  }
+
+  /**
+   * Lists the contents of the directory at the given path in the provider of the default static instance.
+   * @param path The directory to list.
+   * @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 to an array of file names, excluding '.' and '..'.
+   */
+  static readdir(path: string, scope?: CloudStorageScope): Promise<string[]> {
+    return RNCloudStorage.getDefaultInstance().readdir(path, scope);
+  }
 
-export default RNCloudStorage;
+  /**
+   * Reads the contents of the file at the given path in the provider of the default static instance.
+   * @param path The file to read.
+   * @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 to the contents of the file.
+   */
+  static readFile(path: string, scope?: CloudStorageScope): Promise<string> {
+    return RNCloudStorage.getDefaultInstance().readFile(path, scope);
+  }
+
+  /**
+   * 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.
+   * @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.
+   */
+  static downloadFile(path: string, scope?: CloudStorageScope): Promise<void> {
+    return RNCloudStorage.getDefaultInstance().downloadFile(path, scope);
+  }
+
+  /**
+   * Deletes the file at the given path in the provider of the default static instance.
+   * @param path The file to delete.
+   * @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 when the file has been deleted.
+   */
+  static unlink(path: string, scope?: CloudStorageScope): Promise<void> {
+    return RNCloudStorage.getDefaultInstance().unlink(path, scope);
+  }
+
+  /**
+   * Deletes the directory at the given path in the provider of the default static instance.
+   * @param path The directory to delete.
+   * @param options Options for the delete operation. Defaults to { recursive: false }.
+   * @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 when the directory has been deleted.
+   */
+  static rmdir(path: string, options?: { recursive?: boolean }, scope?: CloudStorageScope): Promise<void> {
+    return RNCloudStorage.getDefaultInstance().rmdir(path, options, scope);
+  }
+
+  /**
+   * Gets the size, creation time, and modification time of the file at the given path in the provider of the default static instance.
+   * @param path The file to stat.
+   * @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 to the CloudStorageFileStat object.
+   */
+  static stat(path: string, scope?: CloudStorageScope): Promise<CloudStorageFileStat> {
+    return RNCloudStorage.getDefaultInstance().stat(path, scope);
+  }
+  //#endregion
+}

package/src/google-drive/client.ts

@@ -1,3 +1,4 @@
+import { type CloudStorageProviderOptions, type DeepRequired } from '../types/main';
 import {
   MimeTypes,
   type GoogleDriveFile,
@@ -24,13 +25,11 @@ export class GoogleDriveHttpError extends Error {
 // TODO: fetch timeout
 // TODO: properly handle errors
 export default class GoogleDriveApiClient {
-  public accessToken: string;
-  public timeout: number;
   private _fetchTimeout: any;
+  private options: DeepRequired<CloudStorageProviderOptions['googledrive']>;
 
-  constructor(accessToken: string = '') {
-    this.accessToken = accessToken;
-    this.timeout = 3000;
+  constructor(options: DeepRequired<CloudStorageProviderOptions['googledrive']>) {
+    this.options = options;
   }
 
   private buildQueryString(query: object): string {
@@ -52,6 +51,8 @@ export default class GoogleDriveApiClient {
     operation: `/${string}`,
     { queryParameters, baseUrl, ...options }: RequestInit & { queryParameters?: object; baseUrl?: string } = {}
   ): Promise<T> {
+    const { timeout, accessToken } = this.options;
+
     let path = `${baseUrl ?? BASE_URL}${operation}`;
     if (queryParameters) {
       path += this.buildQueryString(queryParameters);
@@ -60,12 +61,12 @@ export default class GoogleDriveApiClient {
     const abortController: AbortController = new AbortController();
     this._fetchTimeout = setTimeout(() => {
       abortController.abort();
-    }, this.timeout);
+    }, timeout);
     const response = await fetch(path, {
       ...options,
       headers: {
         ...options.headers,
-        Authorization: `Bearer ${this.accessToken}`,
+        Authorization: `Bearer ${accessToken}`,
       },
       signal: abortController.signal,
     });