houser-js-utils
Version:
A comprehensive collection of TypeScript utility functions for common development tasks including array manipulation, string processing, date handling, random number generation, validation, and much more.
159 lines (158 loc) • 6.07 kB
TypeScript
/**
* @module JwtUtils
* @description A comprehensive collection of utility functions for working with JSON Web Tokens (JWT).
* Provides methods for decoding, parsing, validating, and managing JWT tokens including expiration checks,
* claim extraction, and token lifecycle management.
* @example
* ```typescript
* import { JwtUtils } from 'houser-js-utils';
*
* // Decode a JWT token
* const payload = JwtUtils.decodeToken(token);
*
* // Check if token is expired
* const isExpired = JwtUtils.isTokenExpired(token);
*
* // Get specific claim
* const userId = JwtUtils.getPayloadClaim(token, 'sub');
* ```
*/
/**
* Interface representing the structure of a JWT payload with standard claims.
*/
export interface JwtPayload {
/** Subject (user ID) */
sub?: string;
/** Issuer */
iss?: string;
/** Audience */
aud?: string;
/** Expiration time (Unix timestamp in seconds) */
exp?: number;
/** Not before time (Unix timestamp in seconds) */
nbf?: number;
/** Issued at time (Unix timestamp in seconds) */
iat?: number;
/** JWT ID */
jti?: string;
/** Additional custom claims */
[key: string]: any;
}
export declare const JwtUtils: {
/**
* Decodes and parses a JWT token into its payload object.
* @param token - The JWT token string to decode
* @returns The decoded JWT payload containing all claims
* @throws Error if token is invalid, malformed, or cannot be parsed
* @example
* ```typescript
* const token = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...';
* const payload = JwtUtils.decodeToken(token);
* console.log(payload.sub); // '1234567890'
* console.log(payload.exp); // 1234567890
* ```
*/
decodeToken(token: string): JwtPayload;
/**
* Extracts a specific claim value from a JWT token's payload.
* @param token - The JWT token string to parse
* @param claim - The name of the claim to retrieve
* @returns The claim value or undefined if the claim is not found
* @throws Error if token is invalid or cannot be parsed
* @example
* ```typescript
* const token = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...';
* const userId = JwtUtils.getPayloadClaim(token, 'sub'); // "1234567890"
* const role = JwtUtils.getPayloadClaim(token, 'role'); // "admin"
* const email = JwtUtils.getPayloadClaim(token, 'email'); // "user@example.com"
* ```
*/
getPayloadClaim(token: string, claim: string): any;
/**
* Calculates the time remaining until a JWT token expires.
* @param token - The JWT token to check for expiration
* @returns The time remaining in seconds, or null if no expiration time is set
* @throws Error if token is invalid or cannot be parsed
* @example
* ```typescript
* const token = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...';
* const timeRemaining = JwtUtils.getTokenTimeRemaining(token);
* if (timeRemaining !== null) {
* console.log(`Token expires in ${timeRemaining} seconds`);
* } else {
* console.log('Token has no expiration time');
* }
* ```
*/
getTokenTimeRemaining(token: string): number | null;
/**
* Validates if a string follows the correct JWT token format (three base64url-encoded parts).
* @param token - The string to validate as a JWT token
* @returns True if the string follows JWT format, false otherwise
* @example
* ```typescript
* const validToken = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.signature';
* const invalidToken = 'not.a.jwt.token';
*
* JwtUtils.isJwt(validToken); // true
* JwtUtils.isJwt(invalidToken); // false
* JwtUtils.isJwt('invalid'); // false
* ```
*/
isJwt(token: string): boolean;
/**
* Checks if the JWT token stored in localStorage will expire within the next hour.
* @returns True if token will expire within an hour, false if not expiring soon, null if no token exists
* @example
* ```typescript
* const result = JwtUtils.isTokenExpiringSoon();
* if (result === null) {
* console.log('No token found in localStorage');
* } else if (result) {
* console.log('Token expires soon - consider refreshing');
* } else {
* console.log('Token is still valid for more than an hour');
* }
* ```
*/
isTokenExpiringSoon(): boolean | null;
/**
* Determines if a JWT token has expired based on its expiration time claim.
* @param token - The JWT token string to check
* @returns True if the token is expired, false if still valid or has no expiration
* @throws Error if token is invalid or cannot be parsed
* @example
* ```typescript
* const token = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...';
*
* if (JwtUtils.isTokenExpired(token)) {
* console.log('Token has expired - please authenticate again');
* } else {
* console.log('Token is still valid');
* }
* ```
*/
isTokenExpired(token: string): boolean;
/**
* Performs comprehensive validation of a JWT token including expiration and required claims.
* @param token - The JWT token string to validate
* @param requiredClaims - Array of claim names that must be present in the token
* @returns True if token is valid, not expired, and contains all required claims
* @throws Error if token is invalid or cannot be parsed
* @example
* ```typescript
* const token = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...';
*
* // Basic validation (just check expiration)
* const isValid = JwtUtils.isValidToken(token);
*
* // Validation with required claims
* const isValidWithClaims = JwtUtils.isValidToken(token, ['sub', 'role', 'email']);
*
* if (isValidWithClaims) {
* console.log('Token is valid and has all required claims');
* }
* ```
*/
isValidToken(token: string, requiredClaims?: string[]): boolean;
};