VaultError

Purpose

vault-error.ts defines VaultError, the concrete SuaveplanError subclass thrown by every public path in @suaveplan/vault. It binds the runtime instance to a VaultErrorCode from the stable code registry and tags every instance with a unique brand symbol so duck-typed peers cannot impersonate a VaultError across module or worker boundaries.

This package follows the same shape as @suaveplan/vault-sync's VaultSyncError and @suaveplan/crypto-vault's CryptoVaultError: subclass SuaveplanError once, parameterise on the package's code-union, and add a brand-symbol type guard. Consumer code in the password-manager UI, browser extension, and desktop shell can pattern-match on err instanceof VaultError and switch over err.code without worrying about colliding with a foreign error class.

Features

Subclass of SuaveplanError<VaultErrorCode> — inherits structured fields (code, messageKey, cause, context).
Unique-symbol brand attached at construction — survives instanceof failures across realms.
VaultError.is(value) static type guard — safe across iframe / worker boundaries.
Forwards SuaveplanErrorOptions to the base class so cause, context, and i18n metadata flow through unchanged.

Usage: Basic Example

import { VAULT_CODES, VaultError } from "@suaveplan/vault/errors";

throw new VaultError(VAULT_CODES.LOCKED, "error.vault.locked");

Usage: Advanced Example

import { VAULT_CODES, VaultError } from "@suaveplan/vault/errors";

try {
    await vault.items.create({ title: "" });
} catch (err) {
    if (VaultError.is(err) && err.code === VAULT_CODES["ITEM.VALIDATION_FAILED"]) {
        // Surface the missing-field reason from `err.context` to the form.
        showValidationErrors(err.context);
        return;
    }
    throw err;
}

API Reference

class VaultError extends SuaveplanError<VaultErrorCode> — concrete error class.
- constructor(code: VaultErrorCode, messageKey: string, options?: SuaveplanErrorOptions) — instantiate with one of the codes in VAULT_CODES and an i18n message key.
- static is(value: unknown): value is VaultError — brand-aware type guard.

Implementation Notes

The brand symbol is a unique symbol declared module-locally; it cannot be reproduced from outside this file even with full source access.
The constructor sets the brand property after calling super() so the inherited code, messageKey, and context fields are populated normally.
The static is(value) guard checks both instanceof VaultError and the brand property — this defends against subclasses or polyfills that satisfy instanceof but were not minted by this package.
Throwing VaultError is the only way the package signals a recoverable failure to callers; lifecycle, item, attachment, share, sync, and opaque-handle paths all use this class.

2.9 KiB Raw Blame History