tomevault-io Serialization Patterns Skill
This skill covers data serialization and transformation for API responses.
When to Use
Use this skill when:
- Formatting API responses
- Transforming database models
- Hiding sensitive fields
- Normalizing data structures
Core Principle
SEPARATE INTERNAL FROM EXTERNAL - Internal models differ from API responses. Transform explicitly.
Basic Transformation
// src/serializers/user.ts
import { User } from '@prisma/client';
interface UserResponse {
id: string;
email: string;
name: string;
role: string;
createdAt: string;
}
export function serializeUser(user: User): UserResponse {
return {
id: user.id,
email: user.email,
name: user.name,
role: user.role,
createdAt: user.createdAt.toISOString(),
};
}
export function serializeUsers(users: User[]): UserResponse[] {
return users.map(serializeUser);
}
Class-Based Serializer
// src/serializers/base.ts
export abstract class Serializer<TModel, TResponse> {
abstract serialize(model: TModel): TResponse;
serializeMany(models: TModel[]): TResponse[] {
return models.map((model) => this.serialize(model));
}
}
// src/serializers/user.ts
import { User, Profile } from '@prisma/client';
import { Serializer } from './base';
interface UserResponse {
id: string;
email: string;
name: string;
profile: ProfileResponse | null;
}
interface ProfileResponse {
bio: string | null;
avatar: string | null;
}
type UserWithProfile = User & { profile: Profile | null };
export class UserSerializer extends Serializer<UserWithProfile, UserResponse> {
serialize(user: UserWithProfile): UserResponse {
return {
id: user.id,
email: user.email,
name: user.name,
profile: user.profile ? {
bio: user.profile.bio,
avatar: user.profile.avatar,
} : null,
};
}
}
// Usage
const serializer = new UserSerializer();
const response = serializer.serialize(user);
const responses = serializer.serializeMany(users);
Conditional Fields
interface UserResponse {
id: string;
email: string;
name: string;
role: string;
// Admin-only fields
lastLoginAt?: string;
loginCount?: number;
}
interface SerializeOptions {
includeAdminFields?: boolean;
}
export function serializeUser(
user: User,
options: SerializeOptions = {}
): UserResponse {
const base: UserResponse = {
id: user.id,
email: user.email,
name: user.name,
role: user.role,
};
if (options.includeAdminFields) {
return {
...base,
lastLoginAt: user.lastLoginAt?.toISOString(),
loginCount: user.loginCount,
};
}
return base;
}
Nested Serialization
// src/serializers/post.ts
import { Post, User, Tag } from '@prisma/client';
interface PostResponse {
id: string;
title: string;
slug: string;
content: string | null;
published: boolean;
author: AuthorResponse;
tags: TagResponse[];
createdAt: string;
updatedAt: string;
}
interface AuthorResponse {
id: string;
name: string;
}
interface TagResponse {
id: string;
name: string;
}
type PostWithRelations = Post & {
author: User;
tags: Tag[];
};
export function serializePost(post: PostWithRelations): PostResponse {
return {
id: post.id,
title: post.title,
slug: post.slug,
content: post.content,
published: post.published,
author: {
id: post.author.id,
name: post.author.name,
},
tags: post.tags.map((tag) => ({
id: tag.id,
name: tag.name,
})),
createdAt: post.createdAt.toISOString(),
updatedAt: post.updatedAt.toISOString(),
};
}
Paginated Response
// src/serializers/pagination.ts
interface PaginatedResponse<T> {
data: T[];
meta: {
total: number;
page: number;
perPage: number;
totalPages: number;
hasMore: boolean;
};
links: {
first: string;
prev: string | null;
next: string | null;
last: string;
};
}
interface PaginationInput {
items: unknown[];
total: number;
page: number;
perPage: number;
baseUrl: string;
}
export function serializePaginated<T>(
input: PaginationInput,
serializer: (item: unknown) => T
): PaginatedResponse<T> {
const { items, total, page, perPage, baseUrl } = input;
const totalPages = Math.ceil(total / perPage);
return {
data: items.map(serializer),
meta: {
total,
page,
perPage,
totalPages,
hasMore: page < totalPages,
},
links: {
first: `${baseUrl}?page=1&perPage=${perPage}`,
prev: page > 1 ? `${baseUrl}?page=${page - 1}&perPage=${perPage}` : null,
next: page < totalPages ? `${baseUrl}?page=${page + 1}&perPage=${perPage}` : null,
last: `${baseUrl}?page=${totalPages}&perPage=${perPage}`,
},
};
}
JSON:API Format
// src/serializers/jsonapi.ts
interface JsonApiResource<T> {
type: string;
id: string;
attributes: T;
relationships?: Record<string, JsonApiRelationship>;
}
interface JsonApiRelationship {
data: { type: string; id: string } | { type: string; id: string }[];
}
interface JsonApiResponse<T> {
data: JsonApiResource<T> | JsonApiResource<T>[];
included?: JsonApiResource<unknown>[];
}
export function toJsonApi<T extends { id: string }>(
type: string,
data: T
): JsonApiResource<Omit<T, 'id'>> {
const { id, ...attributes } = data;
return {
type,
id,
attributes: attributes as Omit<T, 'id'>,
};
}
// Usage
const user = { id: '1', name: 'John', email: 'john@example.com' };
const response = toJsonApi('user', user);
// { type: 'user', id: '1', attributes: { name: 'John', email: '...' } }
Hiding Sensitive Data
// src/serializers/sanitize.ts
type SensitiveFields = 'password' | 'passwordHash' | 'apiKey' | 'secret';
export function sanitize<T extends Record<string, unknown>>(
obj: T
): Omit<T, SensitiveFields> {
const sensitiveKeys: SensitiveFields[] = [
'password',
'passwordHash',
'apiKey',
'secret',
];
const result = { ...obj };
for (const key of sensitiveKeys) {
delete result[key];
}
return result as Omit<T, SensitiveFields>;
}
// With deep sanitization
export function deepSanitize<T>(obj: T): T {
if (obj === null || typeof obj !== 'object') {
return obj;
}
if (Array.isArray(obj)) {
return obj.map(deepSanitize) as T;
}
const sensitiveKeys = ['password', 'passwordHash', 'apiKey', 'secret'];
const result: Record<string, unknown> = {};
for (const [key, value] of Object.entries(obj)) {
if (!sensitiveKeys.includes(key)) {
result[key] = deepSanitize(value);
}
}
return result as T;
}
Date Formatting
// src/serializers/date.ts
export function toISOString(date: Date | null | undefined): string | null {
return date?.toISOString() ?? null;
}
export function toUnixTimestamp(date: Date | null | undefined): number | null {
return date ? Math.floor(date.getTime() / 1000) : null;
}
export function toRelativeTime(date: Date): string {
const now = new Date();
const diffMs = now.getTime() - date.getTime();
const diffSecs = Math.floor(diffMs / 1000);
const diffMins = Math.floor(diffSecs / 60);
const diffHours = Math.floor(diffMins / 60);
const diffDays = Math.floor(diffHours / 24);
if (diffDays > 0) return `${diffDays}d ago`;
if (diffHours > 0) return `${diffHours}h ago`;
if (diffMins > 0) return `${diffMins}m ago`;
return 'just now';
}
Response Envelope
// src/serializers/envelope.ts
interface SuccessResponse<T> {
success: true;
data: T;
}
interface ErrorResponse {
success: false;
error: {
code: string;
message: string;
details?: unknown;
};
}
type ApiResponse<T> = SuccessResponse<T> | ErrorResponse;
export function success<T>(data: T): SuccessResponse<T> {
return { success: true, data };
}
export function error(
code: string,
message: string,
details?: unknown
): ErrorResponse {
return {
success: false,
error: { code, message, details },
};
}
// Usage in routes
fastify.get('/users/:id', async (request, reply) => {
const user = await findUser(request.params.id);
if (!user) {
return reply.status(404).send(error('NOT_FOUND', 'User not found'));
}
return success(serializeUser(user));
});
Fastify Response Serialization
// Configure Fastify to use custom serializer
import { FastifyInstance } from 'fastify';
export function configureSerializers(fastify: FastifyInstance): void {
fastify.setReplySerializer((payload) => {
return JSON.stringify(payload, (key, value) => {
// Convert Dates to ISO strings
if (value instanceof Date) {
return value.toISOString();
}
// Convert BigInt to string
if (typeof value === 'bigint') {
return value.toString();
}
return value;
});
});
}
Best Practices
- Explicit transformation - Never return raw database models
- Type safety - Define response types explicitly
- Hide sensitive data - Remove passwords, keys, secrets
- Consistent format - Same structure across endpoints
- Date handling - Use ISO 8601 format
- Null handling - Be explicit about null vs undefined
Notes
- Serializers are pure functions
- Test serializers independently
- Document response formats in OpenAPI
- Consider versioned serializers for API versions
Converted and distributed by TomeVault — claim your Tome and manage your conversions.