‹ /migrate

Types

Types of migration

The report of a migration, the reasons an item is skipped, what an item becomes, how to name one old item, and the options of each function.

Section/migrateDraftIn the package, not released yet: the API can still change.

Import

import { type MigrationReport, type MigrationItem } from '@apexnative/keychain/migrate';

@apexnative/keychain/migrate also exports KeychainError, KeychainErrorCode and isKeychainError, the same as the main entry point, to check the errors of a report without a second import.

MigrationReport

type MigrationReport = {
  migrated: string[];
  skipped: SkippedItem[];
  warnings: Array<{ key: string; kind: MigrationKind; error: KeychainError }>;
};

What a migration did, item by item. Every item it found is in migrated or in skipped.

Field	Type	Description
migratedRequired	string[]	The keys of the items written to this package: the service or the server for react-native-keychain, the key for expo-secure-store.
skippedRequired	SkippedItem[]	The items not moved, each with its reason. See SkippedItem.
warningsRequired	Array<{ key, kind, error }>	Items that were written, and whose old item couldn't be removed or marked as moved: the data is safe in this package, the old item stays, and the next run skips it as exists.

SkippedItem

type SkippedItem = {
  key: string;
  kind: MigrationKind;
  reason: SkipReason;
  error?: KeychainError;
};

Field	Type	Description
keyRequired	string	react-native-keychain: the service or the server. expo-secure-store: the key.
kindRequired	MigrationKind	What the item would have become. See MigrationKind.
reasonRequired	SkipReason	Why it wasn't moved. See SkipReason.
error	KeychainError	For reason: 'error': what failed. A canceled prompt of migrateItem is USER_CANCELED.

SkipReason

type SkipReason = 'requiresAuth' | 'notFound' | 'exists' | 'error';

Reason	Means
'requiresAuth'	The old item is protected, and migrateFrom… never shows a prompt. migrateItem moves it
'notFound'	The old item is gone, or has no value
'exists'	The key is taken in this package, and nothing is overwritten; or an earlier run moved the item and kept it
'error'	Reading or writing failed; error says how

MigrationKind

type MigrationKind = 'genericPassword' | 'internetPassword' | 'secureStore';

Kind	The old item	Becomes
'genericPassword'	A generic password of react-native-keychain	The credentials of the storage whose service is the password's
'internetPassword'	Internet credentials of react-native-keychain	The credentials of into with server
'secureStore'	An item of expo-secure-store	The item with the same key in into

MigrationItem

type MigrationItem =
  | { library: 'reactNativeKeychain'; service?: string; server?: undefined }
  | { library: 'reactNativeKeychain'; server: string; service?: undefined }
  | { library: 'expoSecureStore'; key: string; keychainService?: string };

One old item, for migrateItem.

Item	Names
{ library: 'reactNativeKeychain' }	The generic password of rnk's default service
{ library: 'reactNativeKeychain', service: 'auth' }	The generic password of the service auth
{ library: 'reactNativeKeychain', server: 'api.example.com' }	The internet credentials of the server
{ library: 'expoSecureStore', key: 'token' }	The item token of expo-secure-store's default service: app on iOS, key_v1 on Android
{ library: 'expoSecureStore', key: 'token', keychainService: 'auth' }	The item token of the keychainService auth

Both service and server at once is INVALID_ARGUMENT.

MigrateFromReactNativeKeychainOptions

type MigrateFromReactNativeKeychainOptions = {
  services?: readonly string[];
  servers?: readonly string[];
  into?: Keychain;
  removeSource?: boolean;
  accessGroup?: string;
};

The options of migrateFromReactNativeKeychain, explained there.

MigrateFromExpoSecureStoreOptions

type MigrateFromExpoSecureStoreOptions = {
  keychainService?: string | readonly string[];
  into?: Keychain;
  removeSource?: boolean;
  accessGroup?: string;
};

The options of migrateFromExpoSecureStore, explained there.

MigrateItemOptions

type MigrateItemOptions = {
  prompt?: Prompt;
  setOptions?: Omit<SetOptions, 'label'>;
  into?: Keychain;
  removeSource?: boolean;
  accessGroup?: string;
};

The options of migrateItem, explained there.

An option name that isn't one of a function's is INVALID_ARGUMENT, as in the rest of the package.

See also

migrateFromReactNativeKeychainMoves rnk's items.migrateFromExpoSecureStoreMoves expo-secure-store's items.migrateItemMoves one item, with a prompt.