ts-retoken

A lightweight, type-safe token refresh library for JavaScript/TypeScript applications. Zero dependencies, works with any frontend framework.

Features

• Type-safe: Full TypeScript support with generics for API response types
• Two storage modes: localStorage or HTTP-only cookie
• Configurable: Custom status codes, retry delays, and response parsing
• Proactive refresh: Refreshes tokens before they expire
• Request deduplication: Only one refresh request at a time
• Retry with backoff: Exponential backoff for failed refresh requests
• Cross-tab sync: Optional logout synchronization across browser tabs
• Zero dependencies: Uses native fetch API

Installation

npm install ts-retoken

Quick Start

import { createRetoken } from 'ts-retoken';

const retoken = createRetoken({
  refreshEndpoint: {
    url: 'https://api.example.com/auth/refresh',
    parseResponse: (data) => ({
      accessToken: data.access_token,
      refreshToken: data.refresh_token,
    }),
  },
  getAccessToken: () => localStorage.getItem('access_token'),
  getRefreshToken: () => localStorage.getItem('refresh_token'),
  setTokens: (tokens) => {
    localStorage.setItem('access_token', tokens.accessToken);
    localStorage.setItem('refresh_token', tokens.refreshToken);
  },
  clearTokens: () => localStorage.clear(),
  onAuthFailure: () => {
    window.location.href = '/login';
  },
});

// Use the fetch wrapper - handles token refresh automatically
const response = await retoken.fetch('/api/users/me');
const user = await response.json();

Storage Modes

Mode 1: localStorage (or any storage)

Provide getRefreshToken to use localStorage, sessionStorage, or any custom storage:

const retoken = createRetoken({
  refreshEndpoint: {
    url: '/api/auth/refresh',
    buildBody: (token) => JSON.stringify({ refresh_token: token }),
    parseResponse: (data) => ({
      accessToken: data.access_token,
      refreshToken: data.refresh_token,
    }),
  },
  getAccessToken: () => localStorage.getItem('access_token'),
  getRefreshToken: () => localStorage.getItem('refresh_token'),
  setTokens: (tokens) => {
    localStorage.setItem('access_token', tokens.accessToken);
    localStorage.setItem('refresh_token', tokens.refreshToken);
  },
  clearTokens: () => localStorage.clear(),
});

Mode 2: HTTP-only Cookie

Omit getRefreshToken for HTTP-only cookie mode. The refresh token is sent automatically via cookies:

const retoken = createRetoken({
  refreshEndpoint: {
    url: '/api/auth/refresh',
    credentials: 'include', // Send cookies with request
    parseResponse: (data) => ({
      accessToken: data.access_token,
      refreshToken: '', // Not needed in cookie mode
    }),
  },
  getAccessToken: () => localStorage.getItem('access_token'),
  // getRefreshToken OMITTED = cookie mode
  setTokens: (tokens) => {
    localStorage.setItem('access_token', tokens.accessToken);
  },
  clearTokens: () => localStorage.removeItem('access_token'),
});

Type-Safe API Responses

Use generics to get full TypeScript inference for your API response:

// Define your API response type
interface RefreshResponse {
  data: {
    access_token: string;
    refresh_token: string;
    expires_in: number;
  };
}

// Pass it as a generic parameter
const retoken = createRetoken<RefreshResponse>({
  refreshEndpoint: {
    url: '/api/auth/refresh',
    parseResponse: (data) => ({
      // 'data' is typed as RefreshResponse
      // TypeScript will autocomplete: data.data.access_token
      accessToken: data.data.access_token,
      refreshToken: data.data.refresh_token,
    }),
  },
  // ... other config
});

API Reference

createRetoken<TResponse>(config)

Creates a retoken instance with the provided configuration.

Config Options

| Option | Type | Required | Default | Description | |--------|------|----------|---------|-------------| | refreshEndpoint | RefreshEndpointConfig | Yes | - | Refresh endpoint configuration | | getAccessToken | () => string \| null | Yes | - | Function to get current access token | | getRefreshToken | () => string \| null | No | - | Function to get refresh token (omit for cookie mode) | | setTokens | (tokens: TokenPair) => void | Yes | - | Function to store new tokens | | clearTokens | () => void | Yes | - | Function to clear tokens on auth failure | | expirationLeeway | number | No | 60 | Seconds before expiration to refresh proactively | | retryStatuses | number[] | No | [401] | Status codes that trigger refresh + retry | | refreshFailureStatuses | number[] | No | [401, 403] | Refresh status codes that mean auth failed | | retry | RetryConfig | No | See below | Retry configuration | | crossTab | CrossTabConfig | No | { enabled: false } | Cross-tab sync configuration | | onAuthFailure | () => void | No | - | Callback when auth fails completely | | onTokenRefresh | (tokens: TokenPair) => void | No | - | Callback when tokens are refreshed |

RefreshEndpointConfig

| Option | Type | Required | Default | Description | |--------|------|----------|---------|-------------| | url | string | Yes | - | Full URL to refresh endpoint | | method | 'POST' \| 'PUT' | No | 'POST' | HTTP method | | credentials | RequestCredentials | No | 'same-origin' | Fetch credentials mode | | headers | Record<string, string> | No | - | Additional headers | | buildBody | (token: string) => BodyInit | No | JSON with refresh_token | Build request body | | parseResponse | (response: TResponse) => TokenPair | Yes | - | Parse response to TokenPair |

RetryConfig

| Option | Type | Default | Description | |--------|------|---------|-------------| | delays | number[] | [3000, 6000, 12000] | Delays between retries (ms) | | skipOnClientError | boolean | true | Skip retry on 4xx errors |

CrossTabConfig

| Option | Type | Default | Description | |--------|------|---------|-------------| | enabled | boolean | false | Enable cross-tab sync | | channelName | string | 'ts-retoken-auth' | BroadcastChannel name |

RetokenInstance

The object returned by createRetoken():

| Method | Type | Description | |--------|------|-------------| | fetch | (url: string, options?: RetokenFetchOptions) => Promise<Response> | Fetch wrapper with auto-refresh | | fetchJson | <T>(url: string, options?: RetokenFetchJsonOptions) => Promise<T> | Type-safe fetch that returns parsed JSON | | refreshToken | () => Promise<TokenPair> | Manually trigger token refresh | | isTokenExpiringSoon | () => boolean | Check if access token expires soon | | parseTokenExpiration | (token: string) => number \| null | Parse JWT expiration (ms) | | broadcastLogout | () => void | Broadcast logout to other tabs | | destroy | () => void | Cleanup resources |

RetokenFetchOptions

Options for the fetch wrapper (extends RequestInit):

| Option | Type | Default | Description | |--------|------|---------|-------------| | headers | Record<string, string> | - | Request headers | | skipProactiveRefresh | boolean | false | Skip proactive token refresh | | skipRetry | boolean | false | Skip retry on retryStatuses |

RetokenFetchJsonOptions

Options for the fetchJson wrapper (extends RetokenFetchOptions):

| Option | Type | Default | Description | |--------|------|---------|-------------| | expectedStatuses | number[] | [200, 201] | HTTP status codes that indicate success |

fetchJson<T>(url, options)

Type-safe fetch wrapper that returns parsed JSON with automatic token management.

Features:

• Proactively refreshes token if expiring soon (unless skipProactiveRefresh is true)
• Retries with a new token on 401 responses (unless skipRetry is true)
• Parses response body as JSON with full type safety
• Throws FetchError for unexpected HTTP status codes
• Returns null for 204 No Content responses

Basic Usage:

interface User {
  id: string;
  name: string;
  email: string;
}

// GET request - response is typed as User
const user = await retoken.fetchJson<User>('/api/users/me');
console.log(user.name); // Fully typed

POST Request with Custom Status Codes:

interface CreateUserResponse {
  id: string;
  createdAt: string;
}

const newUser = await retoken.fetchJson<CreateUserResponse>('/api/users', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ name: 'John', email: '[email protected]' }),
  expectedStatuses: [201], // Only 201 is considered success
});

Error Handling:

import { FetchError } from 'ts-retoken';

try {
  const data = await retoken.fetchJson<SomeType>('/api/resource');
} catch (error) {
  if (error instanceof FetchError) {
    console.log(error.message); // "Request failed with status 404"
    console.log(error.status);  // 404
    console.log(error.body);    // Parsed error response body (if JSON)
  }
}

FetchError Properties:

| Property | Type | Description | |----------|------|-------------| | message | string | Error message including status code | | status | number | HTTP status code | | body | unknown | Parsed response body (if JSON) or null |

Standalone Utilities

import { isTokenExpiringSoon, parseTokenExpiration, RefreshError } from 'ts-retoken';

// Check if token expires within 60 seconds
const expiring = isTokenExpiringSoon(token, 60);

// Parse expiration timestamp from JWT
const expiresAt = parseTokenExpiration(token); // milliseconds or null

// RefreshError has a status property
try {
  await retoken.refreshToken();
} catch (error) {
  if (error instanceof RefreshError) {
    console.log('Refresh failed with status:', error.status);
  }
}

Advanced Examples

With React

// lib/auth.ts
import { createRetoken, TokenPair } from 'ts-retoken';

// Mutable callback holder for React hooks integration
export const authCallbacks = {
  onAuthFailure: () => {},
  onTokenRefresh: (_tokens: TokenPair) => {},
};

export const retoken = createRetoken({
  refreshEndpoint: {
    url: `${import.meta.env.VITE_API_URL}/auth/refresh`,
    parseResponse: (data) => ({
      accessToken: data.access_token,
      refreshToken: data.refresh_token,
    }),
  },
  getAccessToken: () => localStorage.getItem('access_token'),
  getRefreshToken: () => localStorage.getItem('refresh_token'),
  setTokens: (tokens) => {
    localStorage.setItem('access_token', tokens.accessToken);
    localStorage.setItem('refresh_token', tokens.refreshToken);
  },
  clearTokens: () => localStorage.clear(),
  crossTab: { enabled: true },
  // Delegate to mutable callbacks
  onAuthFailure: () => authCallbacks.onAuthFailure(),
  onTokenRefresh: (tokens) => authCallbacks.onTokenRefresh(tokens),
});

// AuthProvider.tsx - Set callbacks with React hooks
import { useEffect } from 'react';
import { useNavigate } from 'react-router-dom';
import { authCallbacks } from './auth';

export function AuthProvider({ children }: { children: React.ReactNode }) {
  const navigate = useNavigate();

  useEffect(() => {
    authCallbacks.onAuthFailure = () => {
      navigate('/login');
    };

    return () => {
      authCallbacks.onAuthFailure = () => {};
    };
  }, [navigate]);

  return <>{children}</>;
}

// Use in components
const users = await retoken.fetch('/api/users').then(r => r.json());

With Vue

// composables/useAuth.ts
import { createRetoken } from 'ts-retoken';
import { ref, onUnmounted } from 'vue';

const accessToken = ref<string | null>(localStorage.getItem('access_token'));

export const retoken = createRetoken({
  refreshEndpoint: {
    url: '/api/auth/refresh',
    parseResponse: (data) => ({
      accessToken: data.access_token,
      refreshToken: data.refresh_token,
    }),
  },
  getAccessToken: () => accessToken.value,
  getRefreshToken: () => localStorage.getItem('refresh_token'),
  setTokens: (tokens) => {
    accessToken.value = tokens.accessToken;
    localStorage.setItem('access_token', tokens.accessToken);
    localStorage.setItem('refresh_token', tokens.refreshToken);
  },
  clearTokens: () => {
    accessToken.value = null;
    localStorage.clear();
  },
});

export function useAuth() {
  onUnmounted(() => retoken.destroy());
  return { fetch: retoken.fetch, isTokenExpiringSoon: retoken.isTokenExpiringSoon };
}

Manual Token Refresh

Use with your own HTTP client (axios, ky, etc.):

import { createRetoken } from 'ts-retoken';
import axios from 'axios';

const retoken = createRetoken({ /* config */ });

// Ensure valid token before axios request
async function apiRequest(url: string) {
  if (retoken.isTokenExpiringSoon()) {
    await retoken.refreshToken();
  }

  return axios.get(url, {
    headers: {
      Authorization: `Bearer ${localStorage.getItem('access_token')}`,
    },
  });
}

Custom Retry Configuration

const retoken = createRetoken({
  // ...
  retry: {
    delays: [1000, 2000, 4000, 8000], // 4 retries
    skipOnClientError: true,
  },
  expirationLeeway: 30, // Refresh 30s before expiration
});

Custom Status Codes

const retoken = createRetoken({
  // ...

  // Original request: which statuses trigger refresh + retry
  retryStatuses: [401, 403],

  // Refresh request: which statuses mean "auth failed completely"
  refreshFailureStatuses: [401, 403, 422],
});

How It Works

1. Proactive Refresh: Before each request, checks if the access token expires within expirationLeeway seconds. If so, refreshes the token first.

2. Fallback Refresh: If the request returns a status in retryStatuses (default: 401), attempts to refresh the token and retries the request.

3. Request Deduplication: If multiple requests trigger a refresh simultaneously, only one refresh request is made. All pending requests wait for the same refresh promise.

4. Retry with Backoff: Failed refresh requests are retried with exponential backoff (default: 3s, 6s, 12s). Client errors (4xx) are not retried.

5. Auth Failure: When the refresh request returns a status in refreshFailureStatuses, onAuthFailure is called and no more retries are attempted.

License

MIT