unjwt 0.5.39 → 0.6.0

package/dist/_chunks/error.d.mts

@@ -0,0 +1,67 @@
+//#region src/core/error.d.ts
+/**
+* All known error codes thrown by unjwt.
+*
+* Code naming follows the JOSE spec hierarchy:
+*   ERR_JWT_*  — RFC 7519 JSON Web Token claim validation
+*   ERR_JWS_*  — RFC 7515 JSON Web Signature
+*   ERR_JWE_*  — RFC 7516 JSON Web Encryption
+*   ERR_JWK_*  — RFC 7517 JSON Web Key
+*/
+type JWTErrorCode = "ERR_JWT_EXPIRED" | "ERR_JWT_NBF" | "ERR_JWT_CLAIM_INVALID" | "ERR_JWT_CLAIM_MISSING" | "ERR_JWS_INVALID" | "ERR_JWS_SIGNATURE_INVALID" | "ERR_JWS_ALG_NOT_ALLOWED" | "ERR_JWE_INVALID" | "ERR_JWE_DECRYPTION_FAILED" | "ERR_JWE_ALG_NOT_ALLOWED" | "ERR_JWK_INVALID" | "ERR_JWK_KEY_NOT_FOUND" | (string & {});
+/**
+* Maps known error codes to their structured `cause` shapes.
+* Only codes that carry decoded context beyond the message appear here.
+* Extend this interface when new structured causes are introduced.
+*/
+interface JWTErrorCauseMap {
+  /** Decoded claims available at the point the lifetime check failed. */
+  ERR_JWT_EXPIRED: {
+    jti?: string;
+    iat?: number;
+    exp?: number;
+  };
+}
+/**
+* Base error class for all unjwt errors. Every error thrown by the library is
+* an instance of `JWTError`, so a single `instanceof` check is sufficient to
+* distinguish library errors from other thrown values. Use the `code` property
+* (or the `isJWTError` type guard) to narrow to a specific error condition.
+*
+* @example
+* import { JWTError, isJWTError } from "unjwt/jws";
+*
+* try {
+*   await verify(token, key);
+* } catch (err) {
+*   if (isJWTError(err, "ERR_JWT_EXPIRED")) {
+*     console.log(err.cause.jti); // string | undefined
+*   }
+* }
+*/
+declare class JWTError<TCode extends JWTErrorCode = JWTErrorCode> extends Error {
+  readonly code: TCode;
+  override readonly cause?: unknown;
+  constructor(message: string, code: TCode, cause?: unknown);
+}
+/**
+* Type guard that narrows `error` to `JWTError`.
+*
+* When called with a code that is a key of `JWTErrorCauseMap`, the return
+* type is additionally narrowed to include the structured `cause` shape for
+* that code. When called with any other `JWTErrorCode`, `code` is narrowed
+* but `cause` remains `unknown`. When called without a code, narrows only to
+* `JWTError`.
+*
+* @example
+* if (isJWTError(err, "ERR_JWT_EXPIRED")) {
+*   err.cause.jti // string | undefined  ✓
+* }
+*/
+declare function isJWTError<T extends keyof JWTErrorCauseMap>(error: unknown, code: T): error is JWTError<T> & {
+  cause: JWTErrorCauseMap[T];
+};
+declare function isJWTError<T extends JWTErrorCode>(error: unknown, code: T): error is JWTError<T>;
+declare function isJWTError(error: unknown): error is JWTError;
+//#endregion
+export { isJWTError as i, JWTErrorCauseMap as n, JWTErrorCode as r, JWTError as t };