‹ Errors

Class

KeychainError

The error of every failed call of the package. Its code says why, in the same words on iOS and Android; the native code and domain are there for logs.

Import

import { KeychainError } from '@apexnative/keychain';

Every method of the package fails with a KeychainError: an async one rejects with it, a sync one throws it. Whatever the native side reports, an OSStatus, an LAError or a BiometricPrompt code, comes to JavaScript as one of the codes, so one switch handles both platforms. A missing item is not an error: it is null.

Usage

import { KeychainError, KeychainErrorCode } from '@apexnative/keychain';

try {
  return await vault.getItem('refreshToken');
} catch (error) {
  if (!(error instanceof KeychainError)) throw error;
  switch (error.code) {
    case KeychainErrorCode.UserCanceled:
      return showPasswordForm();
    case KeychainErrorCode.KeyInvalidated:
      return signInAgain();
    default:
      log(error.code, error.nativeCode, error.nativeDomain, error.message);
      throw error;
  }
}

Signature

class KeychainError extends Error {
  readonly code: KeychainErrorCode;
  readonly nativeCode?: number;
  readonly nativeDomain?: string;

  constructor(code: KeychainErrorCode, message: string, details?: KeychainErrorDetails);
}

Typeclass extends ErrorPlatformsiOSAndroid

Properties

Property	Type	Description
codeRequired	KeychainErrorCode	Why the call failed. See KeychainErrorCode.
messageRequired	string	What happened, in English, for logs and for the developer: it names the key, the option or the missing setting. Not meant for the user.
nativeCode	number	The native error behind the code, when there is one: an iOS OSStatus or LAError, an Android BiometricPrompt error code.
nativeDomain	string	Where nativeCode comes from, such as NSOSStatusErrorDomain or com.apple.LocalAuthentication.
cause	unknown	The error this one was made from, such as the rejection of the native call. Not enumerable.

name is 'KeychainError', and instanceof KeychainError holds however the code was compiled. isKeychainError checks the class and a code in one call.

Constructor

Parameter	Type	Description
codeRequired	KeychainErrorCode	The code.
messageRequired	string	The message.
details	KeychainErrorDetails	nativeCode, nativeDomain and cause. See KeychainErrorDetails.

The package makes its errors itself; an app makes one in tests and in its own wrappers, to fail the way the package does:

import { KeychainError, KeychainErrorCode } from '@apexnative/keychain';

const canceled = new KeychainError(KeychainErrorCode.UserCanceled, 'The user canceled the prompt.');

What becomes a KeychainError

• A check in JavaScript — a key, a value or an option that isn't valid — is INVALID_ARGUMENT, thrown before the native call.
• A native failure comes with its code. A code the package doesn't know becomes UNKNOWN, with the native code and domain kept.
• No native module — Expo Go, the web, an app not rebuilt after the install — is UNSUPPORTED, with a message that says how to fix it.

Error codes has every code: when it happens, the native error behind it, and what to do.

See also

KeychainErrorCodeEvery code, as constants and strings.isKeychainErrorThe check, with or without a code.ErrorsThe codes by kind, and handling a read.