Backend and Frontend Converters (Mappers)

Guide on decoupling API contracts and internal application data models using mappings (DTO -> Domain Model).

Data Mapping Architecture

Benefits: Converters isolate the UI from backend changes, allow data formatting (dates, enums), and guarantee layer-level type safety.

Entity Converters File Structure

Naming Conventions

Converters:
Located in the converters/ folder. Files are named following the [entity-name].converters.ts pattern. They use types from the sibling folder for data transformation.
Types and Interfaces:
Located in the types folder. Must be divided into *.backend.interface.ts (raw DTOs) and *.interface.ts (UI models). All types are exported via index.ts.

01Mapping to Frontend (Domain Model)

Transforming raw backend data (snake_case, strings instead of dates) into camelCase and typed objects for the UI. mapToFrontend is the most critical stage.

converters/booking-order.converters.ts

import { formatDate } from "@/shared/lib/utils";
import { type IEntityBackend, type IEntity } from "../types";

export const mapEntityToFrontend = (
	data: IEntityBackend
): IEntity => ({
	id: data.id,
	fullName: data.full_name,
	dateCreated: formatDate(data.created_at),
	status: data.status_code
});

02Mapping to Backend (DTO)

Preparing data before sending. Used when creating or updating entities to return to the DTO format expected by the API.

converters/booking-order.converters.ts

import { 
    type IEntityBackend, 
    type IEntity 
} from "../types";

export const mapEntityToBackend = (
	data: Partial<IEntity>
): Partial<IEntityBackend> => ({
	id: data.id,
	full_name: data.fullName,
	created_at: data.dateCreated,
	status_code: data.status
});

03Filter Conversion

A special case of mapping search filter state into query parameters. Allows convenient array joining, handling empty values, and API-specific formats.

converters/booking-order.converters.ts

import { type IEntityFilters } from "../types";

export const mapEntityFiltersToBackend = (
	filters: IEntityFilters
) => ({
	page: filters.page,
	limit: filters.limit,
	search: filters.search || undefined,
	status: filters.status.length > 0 
        ? filters.status.join(",") 
        : undefined
});

04RTK Query Integration

Converters are injected directly into endpoint definitions: transformResponse for data retrieval and query (params/body) for data submission.

api/[entity-name].service.ts

import { authApi } from "@/entities/auth/api/auth.api";
import { 
    mapEntityFiltersToBackend, 
    mapEntityPaginatedToFrontend,
    mapEntityToBackend
} from "../converters";

export const entityApi = authApi.injectEndpoints({
	endpoints: (builder) => ({
		getEntities: builder.query<TResponse, TFilters>({
			query: (filters) => ({
				url: "/entity/list",
				params: mapEntityFiltersToBackend(filters)
			}),
			transformResponse: (response: TResponseBackend) => 
                mapEntityPaginatedToFrontend(response)
		}),
        updateEntity: builder.mutation<void, TEntity>({
			query: (body) => ({
				url: "/entity/update",
				method: "POST",
				body: mapEntityToBackend(body)
			})
		})
	})
});

01Mapping to Frontend (Domain Model)

Transforming raw backend data (snake_case, strings instead of dates) into camelCase and typed objects for the UI. mapToFrontend is the most critical stage.

converters/booking-order.converters.ts

import { formatDate } from "@/shared/lib/utils";
import { type IEntityBackend, type IEntity } from "../types";

export const mapEntityToFrontend = (
	data: IEntityBackend
): IEntity => ({
	id: data.id,
	fullName: data.full_name,
	dateCreated: formatDate(data.created_at),
	status: data.status_code
});

02Mapping to Backend (DTO)

Preparing data before sending. Used when creating or updating entities to return to the DTO format expected by the API.

converters/booking-order.converters.ts

import { 
    type IEntityBackend, 
    type IEntity 
} from "../types";

export const mapEntityToBackend = (
	data: Partial<IEntity>
): Partial<IEntityBackend> => ({
	id: data.id,
	full_name: data.fullName,
	created_at: data.dateCreated,
	status_code: data.status
});

03Filter Conversion

A special case of mapping search filter state into query parameters. Allows convenient array joining, handling empty values, and API-specific formats.

converters/booking-order.converters.ts

import { type IEntityFilters } from "../types";

export const mapEntityFiltersToBackend = (
	filters: IEntityFilters
) => ({
	page: filters.page,
	limit: filters.limit,
	search: filters.search || undefined,
	status: filters.status.length > 0 
        ? filters.status.join(",") 
        : undefined
});

04RTK Query Integration

Converters are injected directly into endpoint definitions: transformResponse for data retrieval and query (params/body) for data submission.

api/[entity-name].service.ts

import { authApi } from "@/entities/auth/api/auth.api";
import { 
    mapEntityFiltersToBackend, 
    mapEntityPaginatedToFrontend,
    mapEntityToBackend
} from "../converters";

export const entityApi = authApi.injectEndpoints({
	endpoints: (builder) => ({
		getEntities: builder.query<TResponse, TFilters>({
			query: (filters) => ({
				url: "/entity/list",
				params: mapEntityFiltersToBackend(filters)
			}),
			transformResponse: (response: TResponseBackend) => 
                mapEntityPaginatedToFrontend(response)
		}),
        updateEntity: builder.mutation<void, TEntity>({
			query: (body) => ({
				url: "/entity/update",
				method: "POST",
				body: mapEntityToBackend(body)
			})
		})
	})
});