@alapandas03/token-refresher

A lightweight, customizable service for handling API requests with automatic token refresh capabilities. Perfect for applications requiring JWT or OAuth2 token management.

Features

• Automatic token refresh on 401 errors
• Smart request queuing during token refresh to prevent token race conditions
• Configurable token storage (localStorage, sessionStorage, or custom storage)
• Support for all HTTP methods (GET, POST, PUT, DELETE)
• Fully customizable refresh token endpoint
• Works in both browser and Node.js environments
• Built on top of Axios for reliable HTTP requests

Installation

npm install @alapandas03/token-refresher

Quick Start

const TokenRefresher = require('@alapandas03/token-refresher');

const api = new TokenRefresher({
    baseURL: 'https://api.example.com',
    refreshTokenEndpoint: '/auth/refresh'
});

// Example usage
async function fetchUserProfile() {
    try {
        const response = await api.get('/user/profile');
        return response.data;
    } catch (error) {
        console.error('Error:', error);
    }
}

Advanced Usage

1. Custom Token Storage

You can customize where and how tokens are stored by providing custom functions:

const api = new TokenRefresher({
    baseURL: 'https://api.example.com',
    refreshTokenEndpoint: '/auth/refresh',
    // Custom token management functions
    getAccessToken: () => sessionStorage.getItem('my-access-token'),
    getRefreshToken: () => sessionStorage.getItem('my-refresh-token'),
    setAccessToken: (token) => sessionStorage.setItem('my-access-token', token),
    clearTokens: () => {
        sessionStorage.removeItem('my-access-token');
        sessionStorage.removeItem('my-refresh-token');
    }
});

2. Handling Failed Token Refresh

The service automatically handles token refresh failures:

• Clears existing tokens
• Rejects all queued requests
• Throws an error that you can catch to redirect to login

try {
    const response = await api.get('/protected-endpoint');
    return response.data;
} catch (error) {
    if (error.response?.status === 401) {
        // Token refresh failed, redirect to login
        window.location.href = '/login';
    }
}

3. Making Authenticated Requests

// GET request
const getData = await api.get('/endpoint');

// POST request with data
const postData = await api.post('/endpoint', {
    key: 'value'
});

// PUT request
const putData = await api.put('/endpoint', {
    key: 'updated value'
});

// DELETE request
const deleteData = await api.delete('/endpoint');

4. Configuration Options

const api = new TokenRefresher({
    // Required options
    baseURL: 'https://api.example.com',
    refreshTokenEndpoint: '/auth/refresh',

    // Optional token management (defaults to localStorage)
    getAccessToken: () => customStorage.getToken(),
    getRefreshToken: () => customStorage.getRefreshToken(),
    setAccessToken: (token) => customStorage.setToken(token),
    clearTokens: () => customStorage.clear(),

    // Additional axios config options
    timeout: 5000,
    headers: {
        'Custom-Header': 'value'
    }
});

Common Use Cases

1. Single Page Applications (SPA)

   • Automatic token refresh without interrupting user experience
   • Queued requests continue automatically after token refresh

2. Mobile-First Applications

   • Efficient token management for intermittent connections
   • Customizable storage for mobile-specific requirements

3. Microservices Architecture

   • Consistent token management across multiple service calls
   • Centralized refresh token handling

4. OAuth2 Implementations

   • Perfect for handling OAuth2 access/refresh token flows
   • Automatic token refresh on expiration

Error Handling

The service handles various scenarios:

try {
    const response = await api.get('/endpoint');
    // Success handling
} catch (error) {
    if (error.response) {
        // Server responded with error status
        console.error('Server Error:', error.response.status);
    } else if (error.request) {
        // Request was made but no response
        console.error('Network Error');
    } else {
        // Error in request configuration
        console.error('Request Error:', error.message);
    }
}

Best Practices

1. Token Storage

   • Use secure storage methods (HttpOnly cookies for refresh tokens)
   • Consider using sessionStorage for access tokens in browsers

2. Error Handling

   • Implement proper error boundaries
   • Handle token refresh failures gracefully

3. Security

   • Never store sensitive tokens in localStorage
   • Implement proper CSRF protection

License

MIT

Contributing

Contributions welcome! Please read the contributing guidelines before making a pull request.