refactor: fixed & improved CloudStorage static & instance API

docs/docs/api/CloudStorage.md

@@ -4,7 +4,9 @@ sidebar_position: 1
 
 # CloudStorage
 
-The `CloudStorage` provides the core functionality of the library. File operations loosely follow the conventions of Node's `fs`.
+The `CloudStorage` class provides the core functionality of the library. File operations loosely follow the conventions of Node's `fs`.
+
+The class can both be used as a static class and be instantiated. This means you can use both `CloudStorage.readFile()` and `cloudStorageInstance.readFile()`. The former will use a default cloud storage provider based on the platform, while the latter will use a provider of your choice. [Learn more](../guides/using-multiple-providers). All file system operations are available on both the static class and instances, while the available configuration methods differ between the two (see below).
 
 ```ts
 import { CloudStorage } from 'react-native-cloud-storage';
@@ -24,32 +26,37 @@ When a method takes a `path` parameter, you should provide a full path with a le
 
 :::caution
 
-When creating files or directories, always make sure that all directories in the tree already exist. Otherwise the library will throw a [`CloudStorageErrorCode.DIRECTORY_NOT_FOUND`](./enums/CloudStorageErrorCode).
+When creating files or directories, always make sure that all parent directories in the tree already exist. Otherwise the library will throw a [`CloudStorageErrorCode.DIRECTORY_NOT_FOUND`](./enums/CloudStorageErrorCode).
 
 :::
 
-## Configuration methods
+## Constructor
 
-### `getProvider()`
+### `new CloudStorage(provider, options)`
 
-Gets the cloud storage provider currently in use.
+Creates a new `CloudStorage` instance using the given provider.
 
-**Returns**: The currently used [`CloudStorageProvider`](./enums/CloudStorageProvider).
+**Parameters**:
 
-### `getProviderInstance(provider)`
+- `provider` ([`CloudStorageProvider`](./enums/CloudStorageProvider)): Optional. The provider to use. Defaults to the default provider of the current platform.
+- `options` (`object`): Optional. The options to set for the provider. [See here](./enums/CloudStorageProvider#provider-options) for a list of available options per provider.
 
-Gets a new instance of the `CloudStorage` API, forcing the use of the given provider. This is useful when you want to use multiple providers in the same app.
+## Configuration methods
 
-For more info, [see here](../guides/using-multiple-providers).
+### `getProvider()`
 
-**Parameters**:
+- **Available on static class**: ❌ No (the static default instance will use the default provider of the current platform)
+- **Available on instances**: ✅ Yes
 
-- `provider` ([`CloudStorageProvider`](./enums/CloudStorageProvider)): Required. The provider to use.
+Gets the cloud storage provider currently in use.
 
-**Returns**: A new instance of the `CloudStorage` API. This instance will only include the [cloud operation methods](#cloud-operations) and not the configuration methods.
+**Returns**: The currently used [`CloudStorageProvider`](./enums/CloudStorageProvider).
 
 ### `getProviderOptions(provider)`
 
+- **Available on static class**: ✅ Yes
+- **Available on instances**: ✅ Yes
+
 Gets the currently set options of the given provider.
 
 **Parameters**:
@@ -60,12 +67,18 @@ Gets the currently set options of the given provider.
 
 ### `getSupportedProviders()`
 
+- **Available on static class**: ✅ Yes
+- **Available on instances**: ❌ No
+
 Gets the list of supported cloud storage providers on the current platform.
 
 **Returns**: An array of [`CloudStorageProvider`](./enums/CloudStorageProvider) values.
 
 ### `setProvider(provider)`
 
+- **Available on static class**: ❌ No (the static default instance will use the default provider of the current platform)
+- **Available on instances**: ✅ Yes
+
 Sets the cloud storage provider to use.
 
 :::tip
@@ -92,18 +105,22 @@ CloudStorage.setProvider(
 
 **Returns**: `void`.
 
-### `setProviderOptions(provider, options)`
+### `setProviderOptions(options)`
 
-Sets the options of the given provider. For a list of available options per provider, [see here](./enums/CloudStorageProvider#provider-options).
+- **Available on static class**: ✅ Yes
+- **Available on instances**: ✅ Yes
+
+Sets the options of the current provider. For a list of available options per provider, [see here](./enums/CloudStorageProvider#provider-options).
 
 **Parameters**:
 
-- `provider` ([`CloudStorageProvider`](./enums/CloudStorageProvider)): Required. The provider to set the options of.
-- `options` (`object`): Required. The options to set.
+- `options` (`object`): Required. The options to set. [See here](./enums/CloudStorageProvider#provider-options) for a list of available options per provider.
 
 **Returns**: `void`.
 
-## Cloud operations
+## File system operations
+
+All file system operations are available on both the static class and instances. When using the static class, the operation will be performed using the default provider (or the provider set via [`setProvider()`](#setproviderprovider)).
 
 ### `appendFile(path, data, scope)`
 
@@ -113,7 +130,7 @@ Appends the data to the file at the given path. Creates the file if it doesn't e
 
 - `path` (`string`): Required. The path including the filename to append data to.
 - `content` (`string`): Required. The content to append.
-- `scope` ([`CloudStorageScope`](./enums/CloudStorageScope)): Optional. The storage scope (documents/app data) to use. Defaults to [`CloudStorageScope.AppData`](./enums/CloudStorageScope), unless the default scope has been changed via [`setProviderOptions()`](#setprovideroptionsprovider-options).
+- `scope` ([`CloudStorageScope`](./enums/CloudStorageScope)): Optional. The storage scope (documents/app data) to use. Defaults to [`CloudStorageScope.AppData`](./enums/CloudStorageScope), unless the default scope has been changed via [`setProviderOptions()`](#setprovideroptionsoptions).
 
 **Returns**: A `Promise` that resolves to `void` once the data has been appended.
 
@@ -124,7 +141,7 @@ When a file has been uploaded to iCloud, it is not immediately synced across dev
 **Parameters**:
 
 - `path` (`string`): Required. The path including the filename to download.
-- `scope` ([`CloudStorageScope`](./enums/CloudStorageScope)): Optional. The storage scope (documents/app data) to use. Defaults to [`CloudStorageScope.AppData`](./enums/CloudStorageScope), unless the default scope has been changed via [`setProviderOptions()`](#setprovideroptionsprovider-options).
+- `scope` ([`CloudStorageScope`](./enums/CloudStorageScope)): Optional. The storage scope (documents/app data) to use. Defaults to [`CloudStorageScope.AppData`](./enums/CloudStorageScope), unless the default scope has been changed via [`setProviderOptions()`](#setprovideroptionsoptions).
 
 **Returns**: A `Promise` that resolves to `void` once the download has been triggered.
 
@@ -135,15 +152,15 @@ Tests whether or not the file or directory at the given path exists.
 **Parameters**:
 
 - `path` (`string`): Required. The path to test.
-- `scope` ([`CloudStorageScope`](./enums/CloudStorageScope)): Optional. The storage scope (documents/app data) to use. Defaults to [`CloudStorageScope.AppData`](./enums/CloudStorageScope), unless the default scope has been changed via [`setProviderOptions()`](#setprovideroptionsprovider-options).
+- `scope` ([`CloudStorageScope`](./enums/CloudStorageScope)): Optional. The storage scope (documents/app data) to use. Defaults to [`CloudStorageScope.AppData`](./enums/CloudStorageScope), unless the default scope has been changed via [`setProviderOptions()`](#setprovideroptionsoptions).
 
 **Returns**: A `Promise` that resolves to a `boolean`. `true` if a file or directory exists at the given path, `false` otherwise.
 
 ### `isCloudAvailable()`
 
 Tests whether or not the cloud storage is available.
 When using iCloud, this actually verifies with the system whether or not iCloud is available. This might not be the case right at app launch or when the user is not logged into iCloud.
-For Google Drive, this simply checks whether or not an access token has been set using [setGoogleDriveAccessToken](#setgoogledriveaccesstokenaccesstoken).
+For Google Drive, this simply checks whether or not an access token has been set within the provider options.
 
 **Returns**: A `Promise` that resolves to a `boolean`. `true` if the cloud storage is available, `false` otherwise.
 
@@ -154,7 +171,7 @@ Creates a new directory at the given path.
 **Parameters**:
 
 - `path` (`string`): Required. The path of the new directory to create. All parent directories must already exist.
-- `scope` ([`CloudStorageScope`](./enums/CloudStorageScope)): Optional. The storage scope (documents/app data) to use. Defaults to [`CloudStorageScope.AppData`](./enums/CloudStorageScope), unless the default scope has been changed via [`setProviderOptions()`](#setprovideroptionsprovider-options).
+- `scope` ([`CloudStorageScope`](./enums/CloudStorageScope)): Optional. The storage scope (documents/app data) to use. Defaults to [`CloudStorageScope.AppData`](./enums/CloudStorageScope), unless the default scope has been changed via [`setProviderOptions()`](#setprovideroptionsoptions).
 
 **Returns**: A `Promise` that resolves once the directory has been created.
 
@@ -165,7 +182,7 @@ Reads the files and directories contained in the directory at the given path. Do
 **Parameters**:
 
 - `path` (`string`): Required. The full pathname of the directory to read.
-- `scope` ([`CloudStorageScope`](./enums/CloudStorageScope)): Optional. The storage scope (documents/app data) to use. Defaults to [`CloudStorageScope.AppData`](./enums/CloudStorageScope), unless the default scope has been changed via [`setProviderOptions()`](#setprovideroptionsprovider-options).
+- `scope` ([`CloudStorageScope`](./enums/CloudStorageScope)): Optional. The storage scope (documents/app data) to use. Defaults to [`CloudStorageScope.AppData`](./enums/CloudStorageScope), unless the default scope has been changed via [`setProviderOptions()`](#setprovideroptionsoptions).
 
 **Returns**: A `Promise` that resolves to an array of `string`s containing the names of the files and directories in the given directory.
 
@@ -176,7 +193,7 @@ Reads the file at the given path into a `string`.
 **Parameters**:
 
 - `path` (`string`): Required. The full pathname of the file to read.
-- `scope` ([`CloudStorageScope`](./enums/CloudStorageScope)): Optional. The storage scope (documents/app data) to use. Defaults to [`CloudStorageScope.AppData`](./enums/CloudStorageScope), unless the default scope has been changed via [`setProviderOptions()`](#setprovideroptionsprovider-options).
+- `scope` ([`CloudStorageScope`](./enums/CloudStorageScope)): Optional. The storage scope (documents/app data) to use. Defaults to [`CloudStorageScope.AppData`](./enums/CloudStorageScope), unless the default scope has been changed via [`setProviderOptions()`](#setprovideroptionsoptions).
 
 **Returns**: A `Promise` that resolves to a `string` containing the file's content.
 
@@ -188,7 +205,7 @@ Deletes the directory at the given path. Can optionally delete the directory inc
 
 - `path` (`string`): Required. The full pathname of the directory to delete.
 - `options` (`{ recursive?: boolean }`): Optional. An object containing the `recursive` property which, if set to `true`, will delete the directory including all its contents (recursively). If set to `false` (or omitted), the library will throw a [`CloudStorageErrorCode.DIRECTORY_NOT_EMPTY`](./enums/CloudStorageErrorCode) if the directory is not empty. Defaults to `{ recursive: false }`.
-- `scope` ([`CloudStorageScope`](./enums/CloudStorageScope)): Optional. The storage scope (documents/app data) to use. Defaults to [`CloudStorageScope.AppData`](./enums/CloudStorageScope), unless the default scope has been changed via [`setProviderOptions()`](#setprovideroptionsprovider-options).
+- `scope` ([`CloudStorageScope`](./enums/CloudStorageScope)): Optional. The storage scope (documents/app data) to use. Defaults to [`CloudStorageScope.AppData`](./enums/CloudStorageScope), unless the default scope has been changed via [`setProviderOptions()`](#setprovideroptionsoptions).
 
 **Returns**: A `Promise` that resolves once the directory has been deleted.
 
@@ -199,7 +216,7 @@ Gets several file statistics of the file at the given path.
 **Parameters**:
 
 - `path` (`string`): Required. The full pathname of the file to stat.
-- `scope` ([`CloudStorageScope`](./enums/CloudStorageScope)): Optional. The storage scope (documents/app data) to use. Defaults to [`CloudStorageScope.AppData`](./enums/CloudStorageScope), unless the default scope has been changed via [`setProviderOptions()`](#setprovideroptionsprovider-options).
+- `scope` ([`CloudStorageScope`](./enums/CloudStorageScope)): Optional. The storage scope (documents/app data) to use. Defaults to [`CloudStorageScope.AppData`](./enums/CloudStorageScope), unless the default scope has been changed via [`setProviderOptions()`](#setprovideroptionsoptions).
 
 **Returns**: A `Promise` that resolves to [`CloudStorageFileStat`](./interfaces/CloudStorageFileStat) object containing the statistics.
 
@@ -210,7 +227,7 @@ Deletes the file at the given path.
 **Parameters**:
 
 - `path` (`string`): Required. The full pathname of the file to delete.
-- `scope` ([`CloudStorageScope`](./enums/CloudStorageScope)): Optional. The storage scope (documents/app data) to use. Defaults to [`CloudStorageScope.AppData`](./enums/CloudStorageScope), unless the default scope has been changed via [`setProviderOptions()`](#setprovideroptionsprovider-options).
+- `scope` ([`CloudStorageScope`](./enums/CloudStorageScope)): Optional. The storage scope (documents/app data) to use. Defaults to [`CloudStorageScope.AppData`](./enums/CloudStorageScope), unless the default scope has been changed via [`setProviderOptions()`](#setprovideroptionsoptions).
 
 **Returns**: A `Promise` that resolves to `void` once the file has been deleted.
 
@@ -222,6 +239,6 @@ Writes the data to the given path. Creates the file if it doesn't exist yet and
 
 - `path` (`string`): Required. The path including the filename to write to.
 - `content` (`string`): Required. The content to write.
-- `scope` ([`CloudStorageScope`](./enums/CloudStorageScope)): Optional. The storage scope (documents/app data) to use. Defaults to [`CloudStorageScope.AppData`](./enums/CloudStorageScope), unless the default scope has been changed via [`setProviderOptions()`](#setprovideroptionsprovider-options).
+- `scope` ([`CloudStorageScope`](./enums/CloudStorageScope)): Optional. The storage scope (documents/app data) to use. Defaults to [`CloudStorageScope.AppData`](./enums/CloudStorageScope), unless the default scope has been changed via [`setProviderOptions()`](#setprovideroptionsoptions).
 
 **Returns**: A `Promise` that resolves to `void` once the file has been written.

docs/docs/api/enums/CloudStorageProvider.md

@@ -29,7 +29,7 @@ CloudStorage.setProvider('googledrive');
 
 ## Provider options
 
-The provider options can be set via [`setProviderOptions()`](../CloudStorage#setprovideroptionsprovider-options). The following options are available:
+The provider options can be set via [`setProviderOptions()`](../CloudStorage#setprovideroptionsoptions). The following options are available:
 
 ### `CloudStorageProvider.ICloud`
 

docs/docs/api/enums/CloudStorageScope.md

@@ -6,7 +6,7 @@ sidebar_position: 2
 
 `CloudStorageScope` is a TypeScript enum containing the possible values for the `scope` parameters of the rest of the API.
 
-Available scopes are `documents` and `app_data`. When using `documents`, data will be stored in the user-visible root directory of the cloud storage. When using `app_data`, the directory for app-specific data, usually hidden from the user, will be used. By default, all methods will use the `app_data` scope. This can either be overriden by explicitly providing a scope to the method or by setting a default scope on the provider using [`setProviderOptions({ scope })`](../CloudStorage#setprovideroptionsprovider-options).
+Available scopes are `documents` and `app_data`. When using `documents`, data will be stored in the user-visible root directory of the cloud storage. When using `app_data`, the directory for app-specific data, usually hidden from the user, will be used. By default, all methods will use the `app_data` scope. This can either be overriden by explicitly providing a scope to the method or by setting a default scope on the provider using [`setProviderOptions({ scope })`](../CloudStorage#setprovideroptionsoptions).
 
 ```ts
 import { CloudStorageScope } from 'react-native-cloud-storage';

docs/docs/api/hooks/useCloudFile.md

@@ -15,7 +15,8 @@ import { useCloudFile } from 'react-native-cloud-storage';
 **Parameters**:
 
 - `path` (`string`): Required. The full pathname of the file to use. See [the definition of this parameter in `CloudStorage`](../CloudStorage#path).
-- `scope` ([`CloudStorageScope`](../enums/CloudStorageScope)): Optional. The storage scope (documents/app data) to use. Defaults to [`CloudStorageScope.AppData`](../enums/CloudStorageScope), unless the default scope of the provider has been changed via [`setProviderOptions()`](../CloudStorage#setprovideroptionsprovider-options).
+- `scope` ([`CloudStorageScope`](../enums/CloudStorageScope)): Optional. The storage scope (documents/app data) to use. Defaults to [`CloudStorageScope.AppData`](../enums/CloudStorageScope), unless the default scope of the provider has been changed via [`setProviderOptions()`](../CloudStorage#setprovideroptionsoptions).
+- `cloudStorageInstance` ([`CloudStorage`](../CloudStorage)): Optional. An instance of [`CloudStorage`](../CloudStorage). If not specified, the default static instance will be used.
 
 **Returns**: An object containing the following properties:
 

docs/docs/api/hooks/useIsCloudAvailable.md

@@ -4,7 +4,7 @@ sidebar_position: 2
 
 # useIsCloudAvailable
 
-The `useIsCloudAvailable` hook listens to changes in the availability of the cloud storage. For iCloud, it listens to native system events that notify you once iCloud becomes available or unavailable. The iCloud storage might become unavailable when, for example, the user logs out of iCloud. On Google Drive, this hook simply listens to changes of the access token set via [`setProviderOptions()`](../CloudStorage#setprovideroptionsprovider-options) and returns `true` if an access token is set, `false` otherwise.
+The `useIsCloudAvailable` hook listens to changes in the availability of the cloud storage. For iCloud, it listens to native system events that notify you once iCloud becomes available or unavailable. The iCloud storage might become unavailable when, for example, the user logs out of iCloud. On Google Drive, this hook simply listens to changes of the access token set via [`setProviderOptions()`](../CloudStorage#setprovideroptionsoptions) and returns `true` if an access token is set, `false` otherwise.
 
 This is helpful when you want to read from the cloud storage on app launch, as reading from iCloud without waiting for the storage to be available will block the main thread.
 
@@ -14,4 +14,8 @@ import { useIsCloudAvailable } from 'react-native-cloud-storage';
 
 ## API
 
+**Parameters**:
+
+- `cloudStorageInstance` ([`CloudStorage`](../CloudStorage)): Optional. An instance of [`CloudStorage`](../CloudStorage). If not specified, the default static instance will be used.
+
 **Returns**: A `boolean` which is `true` if the cloud storage is online, `false` otherwise. For a more specific definition, ([see here](../CloudStorage#iscloudavailable))