CloudKVStorage

Stores small string values in iCloud or an emulated Google Drive key-value store.

The default CloudStorage and CloudKVStorage instances share provider configuration. Configure either static API to update both defaults. Construct an instance to use independent options.

iCloud synchronization requires the key-value store entitlement. Google Drive stores one hidden JSON document in the app data folder.

Constructors

Constructor

new CloudKVStorage(
  provider?: CloudStorageProvider,
  options?: CloudStorageProviderOptionsValue,
): RNCloudKVStorage;

Creates a standalone key-value storage instance.

Parameters

Parameter	Type	Description
`provider?`	`CloudStorageProvider`	The provider to use. Defaults to iCloud on iOS and Google Drive elsewhere.
`options?`	`CloudStorageProviderOptionsValue`	Options for the selected provider.

Returns

RNCloudKVStorage

Throws

CloudStorageError with ERR_KV_NOT_SUPPORTED when the provider is unavailable.

Methods

clear()

clear(): Promise<void>;

Removes all values from the store. On iCloud this clears the app's complete ubiquitous key-value store, including values written outside this library.

Returns

Promise<void>

getAllItems()

getAllItems(): Promise<Record<string, string>>;

Returns

Promise<Record<string, string>>

All key-value pairs as an object.

getAllKeys()

getAllKeys(): Promise<string[]>;

Returns

Promise<string[]>

All keys in the store.

getItem()

getItem(key: string): Promise<string | null>;

Gets a value.

Parameters

Parameter	Type	Description
`key`	`string`	The key to read.

Returns

Promise<string | null>

The stored string, or null when the key does not exist.

Throws

CloudStorageError with ERR_KV_INVALID_KEY when the key is invalid.

getProvider()

getProvider(): CloudStorageProvider;

Returns

CloudStorageProvider

The current provider.

getProviderOptions()

getProviderOptions(): CloudStorageProviderOptionsValue;

Returns

CloudStorageProviderOptionsValue

The current provider options.

multiGet()

multiGet(keys: string[]): Promise<[string, string | null][]>;

Gets multiple values in input order.

Parameters

Parameter	Type	Description
`keys`	`string`[]	The keys to read.

Returns

Promise<[string, string | null][]>

A tuple for each key and its string value or null.

multiRemove()

multiRemove(keys: string[]): Promise<void>;

Removes multiple values in order.

Parameters

Parameter	Type	Description
`keys`	`string`[]	The keys to remove.

Returns

Promise<void>

multiSet()

multiSet(entries: [string, string][]): Promise<void>;

Sets multiple values in order.

Parameters

Parameter	Type	Description
`entries`	[`string`, `string`][]	Key-value tuples to write.

Returns

Promise<void>

removeItem()

removeItem(key: string): Promise<void>;

Removes a value.

Parameters

Parameter	Type	Description
`key`	`string`	The key to remove.

Returns

Promise<void>

Throws

CloudStorageError with ERR_KV_INVALID_KEY when the key is invalid.

setItem()

setItem(key: string, value: string): Promise<void>;

Sets a string value.

Parameters

Parameter	Type	Description
`key`	`string`	The key to write.
`value`	`string`	The string to store.

Returns

Promise<void>

Throws

CloudStorageError when the key is invalid or a store limit is exceeded.

setProvider()

setProvider(provider: CloudStorageProvider): void;

Sets the provider and resets its options. Calling this on the default instance updates the shared CloudStorage configuration.

Parameters

Parameter	Type	Description
`provider`	`CloudStorageProvider`	The provider to use.

Returns

void

Throws

CloudStorageError with ERR_KV_NOT_SUPPORTED when the provider is unavailable.

setProviderOptions()

setProviderOptions(
  options: CloudStorageProviderOptionsValue,
): void;

Merges options into the current options. Calling this on the default instance updates the shared CloudStorage configuration.

Parameters

Parameter	Type	Description
`options`	`CloudStorageProviderOptionsValue`	The provider options to merge.

Returns

void

subscribeToExternalChanges()

subscribeToExternalChanges(
  listener: (event: CloudKVExternalChangeEvent) => void,
): void;

Subscribes to external key-value changes. Google Drive requires kvPollInterval.

Parameters

Parameter	Type	Description
`listener`	(`event`: `CloudKVExternalChangeEvent`) => `void`	The function to call after an external change.

Returns

void

sync()

sync(): Promise<boolean>;

Flushes or refreshes the provider store. iCloud schedules an upload but does not force a server round-trip. Google Drive fetches the remote document again.

Returns

Promise<boolean>

Whether the synchronization request completed.

unsubscribeFromExternalChanges()

unsubscribeFromExternalChanges(
  listener: (event: CloudKVExternalChangeEvent) => void,
): void;

Removes an external-change listener.

Parameters

Parameter	Type	Description
`listener`	(`event`: `CloudKVExternalChangeEvent`) => `void`	The same function passed to subscribeToExternalChanges.

Returns

void

clear()

static clear(): Promise<void>;

Removes all values from the default instance. On iCloud this clears the app's complete ubiquitous key-value store, including values written outside this library.

Returns

Promise<void>

getAllItems()

static getAllItems(): Promise<Record<string, string>>;

Returns

Promise<Record<string, string>>

All key-value pairs from the default instance.

getAllKeys()

static getAllKeys(): Promise<string[]>;

Returns

Promise<string[]>

All keys from the default instance.

getDefaultInstance()

static getDefaultInstance(): RNCloudKVStorage;

Returns

RNCloudKVStorage

The default instance that shares CloudStorage configuration.

getItem()

static getItem(key: string): Promise<string | null>;

Gets a value from the default instance.

Parameters

Parameter	Type	Description
`key`	`string`	The key to read.

Returns

Promise<string | null>

The stored string, or null when the key does not exist.

getProvider()

static getProvider(): CloudStorageProvider;

Returns

CloudStorageProvider

The shared default provider.

getProviderOptions()

static getProviderOptions(): CloudStorageProviderOptionsValue;

Returns

CloudStorageProviderOptionsValue

The shared default provider options.

getSupportLevel()

static getSupportLevel(
  provider: CloudStorageProvider,
): CloudKVSupportLevel;

Gets the key-value storage support level for a provider on the current platform.

Parameters

Parameter	Type	Description
`provider`	`CloudStorageProvider`	The provider to check.

Returns

CloudKVSupportLevel

Whether support is native, emulated, or unavailable.

multiGet()

static multiGet(keys: string[]): Promise<[string, string | null][]>;

Gets multiple values from the default instance.

Parameters

Parameter	Type	Description
`keys`	`string`[]	The keys to read.

Returns

Promise<[string, string | null][]>

A tuple for each key and its string value or null.

multiRemove()

static multiRemove(keys: string[]): Promise<void>;

Removes multiple values from the default instance.

Parameters

Parameter	Type	Description
`keys`	`string`[]	The keys to remove.

Returns

Promise<void>

multiSet()

static multiSet(entries: [string, string][]): Promise<void>;

Sets multiple values on the default instance.

Parameters

Parameter	Type	Description
`entries`	[`string`, `string`][]	Key-value tuples to write.

Returns

Promise<void>

removeItem()

static removeItem(key: string): Promise<void>;

Removes a value from the default instance.

Parameters

Parameter	Type	Description
`key`	`string`	The key to remove.

Returns

Promise<void>

setItem()

static setItem(key: string, value: string): Promise<void>;

Sets a value on the default instance.

Parameters

Parameter	Type	Description
`key`	`string`	The key to write.
`value`	`string`	The string to store.

Returns

Promise<void>

setProvider()

static setProvider(provider: CloudStorageProvider): void;

Sets the shared default provider for CloudStorage and CloudKVStorage and resets its options.

Parameters

Parameter	Type	Description
`provider`	`CloudStorageProvider`	The provider to use.

Returns

void

setProviderOptions()

static setProviderOptions(
  options: CloudStorageProviderOptionsValue,
): void;

Merges options into the shared default provider options used by CloudStorage and CloudKVStorage.

Parameters

Parameter	Type	Description
`options`	`CloudStorageProviderOptionsValue`	The provider options to merge.

Returns

void

subscribeToExternalChanges()

static subscribeToExternalChanges(
  listener: (event: CloudKVExternalChangeEvent) => void,
): void;

Subscribes to external changes on the default instance.

Parameters

Parameter	Type	Description
`listener`	(`event`: `CloudKVExternalChangeEvent`) => `void`	The function to call after an external change.

Returns

void

sync()

static sync(): Promise<boolean>;

Returns

Promise<boolean>

Whether synchronization of the default instance completed.

unsubscribeFromExternalChanges()

static unsubscribeFromExternalChanges(
  listener: (event: CloudKVExternalChangeEvent) => void,
): void;

Removes an external-change listener from the default instance.

Parameters

Parameter	Type	Description
`listener`	(`event`: `CloudKVExternalChangeEvent`) => `void`	The same function passed to subscribeToExternalChanges.

Returns

void

On this page