DEV Community: Mohamad Reza Rajabi

TypeScript Types Are Not Enough: Building a Runtime API Contract Boundary

Mohamad Reza Rajabi — Tue, 01 Sep 2026 09:15:40 +0000

TypeScript gives us a lot of confidence.

We define types, interfaces, and function signatures. Our editor helps us catch mistakes before we even run the application.

But there is one important place where TypeScript cannot protect us:

Data coming from outside our application.

API responses are runtime data.

The backend can change. A field can be missing. A value can have a different type. An unexpected response can reach our frontend.

And TypeScript will not warn us.

The TypeScript Safety Illusion

Imagine we have a simple user type:

type User = {
  id: string;
  name: string;
};

Then we fetch a user:

const response = await fetch("/api/user");

const user = await response.json() as User;

Everything looks fine.

The editor is happy.
The build passes.

But what if the API returns:

{
  "id": 123
}

The problem is that TypeScript does not validate runtime values.

The as User syntax does not check anything. It only tells TypeScript:

"Trust me, this data has this shape."

But external data should not be trusted by default.

A Real Failure Scenario

Imagine we have a login endpoint.

Today, the backend returns:

{
  "accessToken": "abc123",
  "user": {
    "id": "1",
    "name": "John"
  }
}

The frontend has a matching type:

type LoginResponse = {
  accessToken: string;
  user: User;
};

Everything works.

But later, the backend changes the response:

{
  "token": "abc123",
  "user": {
    "id": "1",
    "name": "John"
  }
}

The application still builds successfully.

The bug appears later:

session.accessToken

becomes:

undefined

The problem is not TypeScript.

The problem is that the application accepted external data without verifying the contract.

API Responses Are Untrusted Data

A useful way to think about APIs is:

Before data enters our application, we should verify that it matches the contract we expect.

This is where runtime validation becomes useful.

The Simple Approach

A common approach is validating responses manually:

const response = await axios.get("/users");

const user = userSchema.parse(response.data);

This works.

But as the application grows, we start repeating the same pattern everywhere:

login()
logout()
getProfile()
getOrders()
updateUser()
...

Every API call needs:

request validation
response validation
error handling

At some point, validation itself becomes something that needs structure.

Creating an API Contract Boundary

Instead of validating every request manually, I created a small API wrapper responsible for this boundary.

The idea is simple:

The API layer receives schemas for both sides:

type ApiRequestOptions<TResponse, TData> = {
  requestSchema?: ApiSchema<TData>;
  responseSchema: ApiSchema<TResponse>;
};

Now API calls can define their contracts explicitly:

apiRequest({
  client,
  method: "post",
  url: "/staff/auth/login",
  data: payload,
  requestSchema: adminLoginSchema,
  responseSchema: adminLoginResponseSchema,
});

The feature does not need to know how validation happens.

It only defines the contract.

Keeping Contracts In A Shared Validation Layer

One important part of this approach is where the contracts live.

Instead of defining request and response shapes separately inside every feature, schemas are kept in a shared validation package.

For example:

import {
  adminLoginSchema,
  adminLoginResponseSchema,
} from "@app/validations/admin/auth";

Now the API call and the validation rules stay connected.

The API layer does not guess the shape of the data.

The contract defines it.

What The Boundary Actually Looks Like

Usually, we only think about validating responses.

But requests can be invalid too:

wrong field name
missing required value
incorrect format

Catching these problems before sending the request saves a round trip and makes the issue obvious immediately.

A simplified version of the API boundary looks like this:

async function apiRequest<TResponse, TData = unknown>({
  client,
  method,
  url,
  data,
  requestSchema,
  responseSchema,
}: ApiRequestOptions<TResponse, TData>): Promise<TResponse> {

  let requestData = data;

  if (requestSchema) {
    try {
      requestData = requestSchema.parse(data);
    } catch (error) {
      throw new ApiRequestValidationError(url, error);
    }
  }

  const response = await client.request({
    method,
    url,
    data: requestData,
  });

  try {
    return responseSchema.parse(response.data);
  } catch (error) {
    throw new ApiResponseValidationError(url, error);
  }
}

The flow is always the same:

Validate what goes out.
Send the request.
Validate what comes back.

Making Contract Failures Explicit

Instead of throwing generic errors, validation failures get their own error types.

For example:

export class ApiResponseValidationError extends Error {
  constructor(
    public readonly url: string,
    public override readonly cause: unknown,
  ) {
    super(`API response does not match the contract for ${url}.`);
    this.name = "ApiResponseValidationError";
  }
}

Now the application can understand what happened without inspecting error messages.

A response validation failure is not the same as:

a network failure
a timeout
a server error

The failure itself carries meaning.

Validation Errors Are Not All The Same

Validation tells us that something is wrong.

But knowing that something failed is only half of the problem.

We also need to understand why it failed.

A validation problem is different from a network problem.

For example:

type ClientErrorKind =
  | "api_request_validation"
  | "api_response_validation"
  | "api_network_error"
  | "api_timeout"
  | "api_server_error";

This distinction helps debugging.

Instead of seeing:

API failed

we can understand:

Response shape changed

or:

Network request timed out

or:

Frontend sent invalid data

A consistent error model means the UI does not need to understand every possible failure source.

The API layer handles that complexity.

Error Reporting Should Also Be Safe

When adding error reporting, there is another problem:

Logs can accidentally expose sensitive information.

Errors might contain:

tokens
passwords
emails
phone numbers

So before reporting errors, sensitive values should be sanitized.

Example:

Bearer eyJhbGci...

becomes:

Bearer [REDACTED]

Observability is useful, but it should not create another security problem.

The Final Flow

The final architecture looks like this:

Conclusion

TypeScript is great at protecting our code.

But it cannot protect us from data crossing the application boundary.

APIs are runtime data, and runtime data needs runtime validation.

Adding a contract boundary between the API and the application helps us:

catch integration issues earlier
prevent invalid data from reaching application state
make errors easier to understand
build more reliable frontend systems

This approach also changed the way I think about frontend architecture:

API boundaries are not just places where data enters the application.

They are places where trust should be established.

The goal is not to eliminate every possible bug.

The goal is to make failures happen closer to their source, where they are easier to detect and fix.

Preventing Refresh Token Race Conditions in Frontend Applications

Mohamad Reza Rajabi — Sat, 29 Aug 2026 12:31:08 +0000

Race conditions are not limited to backend systems or multithreaded code.

They can also happen in frontend applications whenever multiple asynchronous operations interact with the same state or resource.

What Is a Race Condition?

A race condition happens when the result of an application depends on the timing or completion order of concurrent operations.

In frontend applications, this can happen with things like:

API requests
Promises
user interactions
timers
state updates

For example, imagine an autocomplete input:

Request A: search("r")
Request B: search("react")

If Request B finishes first but Request A finishes later, the older result may overwrite the newer one.

A useful pattern to watch for is:

Multiple async operations + shared state/resource + timing matters

One simple question can help identify these situations:

What happens if this operation starts again before the previous one finishes?

For example:

async function refreshToken() {
  // ...
}

What happens if several API requests call refreshToken() before the first refresh has completed?

That's the race condition we're going to look at next.

The Token Refresh Race Condition

Imagine the user has an expired access token and the frontend sends several API requests at almost the same time:

GET /profile
GET /orders
GET /notifications

All of them are sent with the same expired token, so the server responds with 401 Unauthorized.

A naive interceptor might handle every 401 like this:

if (error.response?.status === 401) {
  await refreshToken();
}

The problem is that each failed request runs this logic independently.

So instead of one refresh request, we may end up with:

All three requests are trying to update the same authentication state at nearly the same time.

Depending on how the backend handles refresh tokens, this can lead to unnecessary requests, inconsistent token state, or even intermittent authentication failures.

What we actually want is:

The first request should start the refresh operation, while the others wait for the same result.

This is where a shared Promise becomes useful.

Solving It with a Shared Promise

The key idea is simple:

If a refresh is already in progress, don't start another one. Wait for the existing refresh instead.

We can keep the current refresh operation in a shared Promise:

let refreshPromise: Promise<RefreshSessionData> | null = null;

function refreshSession() {
  if (!refreshPromise) {
    refreshPromise = requestNewSession().finally(() => {
      refreshPromise = null;
    });
  }

  return refreshPromise;
}

The first caller sees refreshPromise === null and starts the refresh.

While that request is still pending, every other caller receives the same Promise instead of creating another refresh request.

Once the refresh succeeds or fails, finally() resets refreshPromise back to null, so a future token expiration can start a new refresh normally.

This gives us the behavior we wanted:

One refresh operation, multiple consumers waiting for its result.

Now let's plug this into an Axios response interceptor.

Using It Inside an Axios Interceptor

Now we need to connect the shared refresh logic to our API requests.

With Axios, a response interceptor is a good place to detect 401 Unauthorized responses and recover from them.

A simplified version looks like this:

apiClient.interceptors.response.use(
  (response) => response,
  async (error) => {
    if (error.response?.status !== 401) {
      return Promise.reject(error);
    }

    const originalRequest = error.config;

    if (originalRequest._retry) {
      return Promise.reject(error);
    }

    originalRequest._retry = true;

    const session = await refreshSession();

    originalRequest.headers.Authorization =
      `Bearer ${session.accessToken}`;

    return apiClient(originalRequest);
  },
);

The flow is straightforward:

Because refreshSession() uses the shared Promise from the previous section, multiple 401 responses can reach this interceptor at the same time without starting multiple refresh calls.

The _retry flag is also important. It prevents the same request from entering an infinite 401 → refresh → retry loop if the retried request is still unauthorized.

In a production implementation, we should also avoid running this logic for the refresh endpoint itself or for endpoints that should never trigger token refresh.

At this point, concurrent 401 responses are coordinated correctly.

But there is still one subtle race condition left: what if a 401 arrives after another request has already refreshed the token?

Handling a Late `401`

There is one more edge case worth handling.

Imagine two requests are sent with the same expired token.

Request A fails first and refreshes the token successfully.

By the time Request B receives its 401, the application already has a newer access token.

If we blindly refresh on every 401, Request B would trigger another unnecessary refresh.

This can be more than just an unnecessary network call.

In systems that use refresh token rotation, the first successful refresh may invalidate the previous refresh token. A second refresh triggered by a stale 401 can then fail and, depending on the backend's session policy, may result in an unexpected session failure or even force the user to log in again.

Instead, we can compare the token used by the failed request with the token we currently have:

const failedAccessToken = getAccessTokenFromRequest(originalRequest);
const currentAccessToken = tokenStore.getAccessToken();

if (
  currentAccessToken &&
  currentAccessToken !== failedAccessToken
) {
  attachAccessToken(originalRequest, currentAccessToken);
  return apiClient(originalRequest);
}

If the tokens are different, another request has already refreshed the session.

So instead of refreshing again, we simply retry the failed request with the newer token.

This small check avoids redundant refresh calls caused by stale responses.

What If the Refresh Itself Fails?

So far, we've assumed the refresh request succeeds.

But the refresh token itself may also be expired, revoked, or invalid.

Because all concurrent requests are waiting for the same refreshPromise, they will all receive the same rejection if the refresh fails.

However, there is an important detail:

Session-level side effects should happen inside the shared refresh operation — not inside every waiting request.

For example:

async function requestNewSession() {
  try {
    const response = await publicClient.post("/auth/refresh");

    tokenStore.setAccessToken(response.data.accessToken);

    return response.data;
  } catch (error) {
    if (isUnauthorizedApiError(error)) {
      tokenStore.clearAccessToken();
      tokenStore.notifyUnauthorized();
    }

    throw error;
  }
}

This is important because not every refresh failure necessarily means the session is invalid.

A temporary network failure or server error may be recoverable, while an unauthorized refresh response usually means the session can no longer be restored.

By keeping these session-level side effects inside the shared refresh operation, an unrecoverable authentication failure clears the session once, while every request waiting for that Promise receives the same rejection.

The refresh operation is shared, so its session-level failure handling should be shared too.

Testing the Race Condition

Race conditions are timing-dependent, so we should not rely on network timing and simply hope that concurrent requests overlap during the test.

For these tests, I used Vitest together with custom Axios adapters, which lets the test control the request lifecycle without making real network calls.

The important part is controlling exactly when the refresh request is allowed to finish.

For that, I use a small deferred() helper:

function deferred<T>() {
  let resolve!: (value: T | PromiseLike<T>) => void;
  let reject!: (reason?: unknown) => void;

  const promise = new Promise<T>((res, rej) => {
    resolve = res;
    reject = rej;
  });

  return { promise, resolve, reject };
}

This gives the test manual control over a Promise.

Now we can intentionally keep the refresh request pending:

const refreshGate = deferred<void>();
let refreshCalls = 0;

const { apiClient } = setupClients(async (config) => {
  refreshCalls += 1;

  await refreshGate.promise;

  return successfulRefresh(config);
});

Then we fire several requests at almost the same time:

const requests = [
  apiClient.get("/resource/1"),
  apiClient.get("/resource/2"),
  apiClient.get("/resource/3"),
];

Because the refresh request is still blocked, all three requests can enter the 401 recovery flow while the same refresh operation is still pending.

At that point, we verify that only one refresh has started:

await vi.waitFor(() => {
  expect(refreshCalls).toBe(1);
});

Then we allow the refresh to complete:

refreshGate.resolve();

Finally, we verify that all original requests recover successfully and that the refresh endpoint was still called only once:

await expect(
  Promise.all(requests),
).resolves.toHaveLength(3);

expect(refreshCalls).toBe(1);

The failure path should be tested too.

For the failure case, we configure the refresh request to reject and verify that every request waiting for the shared Promise fails while only one refresh attempt is made.

const refreshError = new Error("Session expired");
let refreshCalls = 0;

const { apiClient } = setupClients(async () => {
  refreshCalls += 1;
  throw refreshError;
});

const results = await Promise.allSettled([
  apiClient.get("/resource/1"),
  apiClient.get("/resource/2"),
]);

expect(results).toEqual([
  expect.objectContaining({ status: "rejected" }),
  expect.objectContaining({ status: "rejected" }),
]);

expect(refreshCalls).toBe(1);

The important idea is that we are not only testing the final result.

We are deliberately controlling the timing of asynchronous operations to reproduce the concurrency scenario we want to protect against.

The late-401 case can be tested the same way by delaying one API response until another request has already completed the token refresh.

Conclusion

Race conditions in frontend applications are often hidden behind asynchronous behavior.

A useful question to keep in mind is:

What happens if this operation starts again before the previous one finishes?

In our token-refresh flow, multiple 401 responses were competing to refresh the same authentication state.

A shared Promise allowed those requests to coordinate around a single refresh operation, while comparing the failed token with the current token handled late 401 responses without triggering unnecessary refreshes.

We also made sure that refresh failures are handled inside the shared operation itself, so session-level side effects such as clearing authentication state happen only once while every waiting request receives the same failure.

The important part is not just the token-refresh implementation.

It is learning to recognize when multiple asynchronous operations are competing over the same resource because that is where race conditions often begin.

DEV Community: Mohamad Reza Rajabi

TypeScript Types Are Not Enough: Building a Runtime API Contract Boundary

The TypeScript Safety Illusion

A Real Failure Scenario

API Responses Are Untrusted Data

The Simple Approach

Creating an API Contract Boundary

Keeping Contracts In A Shared Validation Layer

What The Boundary Actually Looks Like

Making Contract Failures Explicit

Validation Errors Are Not All The Same

Error Reporting Should Also Be Safe

The Final Flow

Conclusion

Preventing Refresh Token Race Conditions in Frontend Applications

What Is a Race Condition?

The Token Refresh Race Condition

Solving It with a Shared Promise

Using It Inside an Axios Interceptor

Handling a Late 401

What If the Refresh Itself Fails?

Testing the Race Condition

Conclusion

Handling a Late `401`