CSRF-X Auth Library - v1.0.3
    Preparing search index...

    Class AuthError

    Standard error class for all authentication operations.

    Extends the built-in Error and adds a typed error code, an optional context
    string, and a timestamp. Instances are frozen to prevent accidental mutation.

    try {
      throw new AuthError('Login failed', AuthErrorCode.LOGIN_FAILED, {
        cause: response,
        context: 'POST /login'
      });
    } catch (e) {
      console.error(e.getFormattedMessage());
    }

    @public

    0.1.1

    Hierarchy

    • Error
      • AuthError
    Index

    Constructors

    constructor

    Methods

    fromResponse fromUnknown fromStatus toJSON getFormattedMessage

    Properties

    code context? timestamp

    Constructors

    • Creates a new AuthError.

      Parameters

      • message: string

        Human‑readable error description (must be non‑empty string).

      • code: AuthErrorCode

        One of the predefined AuthErrorCode values.

      • Optionaloptions: { cause?: unknown; context?: string }

        Optional additional data.

        • Optionalcause?: unknown

          Underlying error or response object.

        • Optionalcontext?: string

          Short contextual string (will be trimmed).

      Returns AuthError

      If message is empty or not a string, or if code is invalid.

      new AuthError('CSRF token expired', AuthErrorCode.CSRF_EXPIRED, {
        context: 'GET /login',
        cause: previousError
      });

    Methods

    • Creates an AuthError from a fetch Response object.

      Maps the HTTP status code to an appropriate error code using
      HTTP_STATUS_CODE_MAP, falling back to defaultCode if no mapping exists.
      The error message includes the status and statusText, plus an optional context
      snippet.

      Parameters

      • response: Response

        The Response object from a failed fetch.

      • defaultCode: AuthErrorCode

        Fallback error code when no HTTP mapping is available.

      • Optionaloptions: { context?: string }

        Optional context string.

      Returns AuthError

      A new AuthError instance.

      If response is not a valid Response object or status is out of range.

      const res = await fetch('/api/login');
      if (!res.ok) {
        throw AuthError.fromResponse(res, AuthErrorCode.LOGIN_FAILED, {
          context: 'login attempt'
        });
      }

      @public

      0.1.1

    • Creates an AuthError from any unknown error value.

      Intelligently extracts a message and code based on error type:

      • DOMException with AbortError → TIMEOUT
      • TypeError with fetch in message → NETWORK_ERROR
      • Generic Error → inspects message for keywords "csrf", "network", "timeout"
      • String → uses first 200 characters

      Parameters

      • err: unknown

        The unknown error value (exception, string, etc.).

      • fallbackCode: AuthErrorCode = AuthErrorCode.UNKNOWN

        Code to use if none can be inferred (default: UNKNOWN).

      Returns AuthError

      A properly constructed AuthError.

      try {
        await fetch(...);
      } catch (err) {
        throw AuthError.fromUnknown(err);
      }

      @public

      0.1.1

    • Creates an AuthError from a raw HTTP status code and optional response body.

      Useful when you have only the status code and a text snippet (e.g., from a
      failed XMLHttpRequest or a non‑standard response).

      Parameters

      • status: number

        HTTP status code (100‑599).

      • Optionalbody: string

        Optional response body (first line, first 100 chars used).

      Returns AuthError

      A new AuthError instance.

      If status is out of valid range.

      throw AuthError.fromStatus(419, 'CSRF token mismatch');

      @public

      0.1.1

    • Converts the error to a plain JSON object for logging or serialization.

      Returns Record<string, unknown>

      An object containing name, message, code, context,
      timestamp, and a trimmed stack (first 3 lines).

      console.log(JSON.stringify(error.toJSON()));

      @public

      0.1.1

    • Returns a formatted, human‑readable error message.

      Format: [CODE] message | Context: ... | Cause: ...

      Returns string

      A single string combining code, message, optional context, and cause.

      console.error(error.getFormattedMessage());
      // Output: "[NETWORK_ERROR] Network error – check connectivity | Cause: TypeError: fetch failed"

      @public

      0.1.1

    Properties

    code: AuthErrorCode

    Machine‑readable error code.

    AuthErrorCode

    context?: string

    Optional additional context (e.g., URL, request ID, snippet).
    Automatically trimmed.

    timestamp: number

    Unix timestamp (milliseconds) when the error was created.

    Settings

    Member Visibility

    On This Page

    Constructors
    Methods
    Properties