<UserCard user={{ id: 'u_123', name: 'Ari' }} />

The value exists in one runtime,
but the receiving runtime cannot faithfully reconstruct its meaning.

What is the smallest stable representation of this domain fact
that another runtime can safely interpret?

class Money {
  constructor(private cents: number, private currency: string) {}

  format(locale: string) {
    return new Intl.NumberFormat(locale, {
      style: 'currency',
      currency: this.currency,
    }).format(this.cents / 100);
  }
}

return new Money(1299, 'USD');

type MoneyDTO = {
  amountMinor: number;
  currency: 'USD' | 'EUR' | 'IDR';
};

return {
  amountMinor: 1299,
  currency: 'USD',
} satisfies MoneyDTO;

Do not export runtime objects across execution boundaries.
Export stable representations.

Can this value be understood without the originating runtime?

// Server Component
import UserMenu from './UserMenu';

export default async function Header() {
  const session = await getSession();

  return (
    <UserMenu
      session={session}
      onLogout={() => logout()} // ❌ normal function crossing to Client Component
    />
  );
}

// actions.ts
'use server';

export async function logoutAction() {
  await logoutCurrentSession();
}

// Server Component
import UserMenu from './UserMenu';
import { logoutAction } from './actions';

export default async function Header() {
  const session = await getSessionDTO();

  return <UserMenu session={session} logoutAction={logoutAction} />;
}

// UserMenu.tsx
'use client';

export function UserMenu({
  session,
  logoutAction,
}: {
  session: SessionDTO;
  logoutAction: () => Promise<void>;
}) {
  return (
    <form action={logoutAction}>
      <button>Log out</button>
    </form>
  );
}

Make it JSON-serializable.

const value = {
  createdAt: new Date(),
  ids: new Set(['a', 'b']),
  amount: 10n,
};

JSON.stringify(value);
// Date becomes a string through toJSON
// Set becomes {}
// BigInt throws unless converted

type InvoiceDTO = {
  id: string;
  number: string;
  status: 'draft' | 'issued' | 'paid' | 'void';
  total: {
    amountMinor: number;
    currency: string;
  };
  issuedAt: string | null;
  version: number;
};

type InvoiceDetailView = {
  invoice: InvoiceDTO;
  permissions: {
    canEdit: boolean;
    canVoid: boolean;
    canSendReminder: boolean;
  };
  timeline: Array<{
    id: string;
    type: 'created' | 'issued' | 'payment_received' | 'voided';
    at: string;
    actorName: string;
  }>;
};

type UpdateInvoiceCommand = {
  invoiceId: string;
  expectedVersion: number;
  patch: {
    dueDate?: string | null;
    notes?: string | null;
  };
  idempotencyKey: string;
};

type UpdateInvoiceResult =
  | {
      ok: true;
      invoice: InvoiceDTO;
      invalidated: Array<QueryAddress>;
    }
  | {
      ok: false;
      code: 'VALIDATION_FAILED';
      fieldErrors: Record<string, string[]>;
    }
  | {
      ok: false;
      code: 'VERSION_CONFLICT';
      current: InvoiceDTO;
    };

This value belongs to a runtime, not to the network contract.

runtime state stays local
portable representation crosses boundary
receiver reconstructs local runtime helpers if needed

type TaskDTO = {
  dueAt: Date;
};

type TaskDTO = {
  dueAt: string; // ISO instant, e.g. 2026-07-07T10:30:00.000Z
};

type LeaveRequestDTO = {
  startDate: string; // YYYY-MM-DD, no time zone conversion
  endDate: string;   // YYYY-MM-DD
};

function parseInstant(value: string): Date {
  const date = new Date(value);

  if (Number.isNaN(date.getTime())) {
    throw new Error(`Invalid instant: ${value}`);
  }

  return date;
}

An instant is not a calendar date.
A calendar date is not a local datetime.
A local datetime is not a timezone-aware instant.

type PriceDTO = {
  amount: number; // 19.99
};

type MoneyDTO = {
  amountMinor: number;
  currency: 'IDR' | 'USD' | 'EUR';
};

type MoneyDTO = {
  amountMinor: string; // arbitrary precision integer encoded as decimal string
  currency: string;
};

type CaseStatus = 'open' | 'closed';

under_review
escalated
archived

type KnownCaseStatus = 'open' | 'closed' | 'under_review' | 'escalated';

type CaseStatus = KnownCaseStatus | 'unknown';

function parseCaseStatus(raw: string): CaseStatus {
  switch (raw) {
    case 'open':
    case 'closed':
    case 'under_review':
    case 'escalated':
      return raw;
    default:
      return 'unknown';
  }
}

field absent
field present with null
field present with undefined
field present with empty string
field present with empty array

type UpdateProfilePatch = {
  displayName?: string;       // absent = do not change
  avatarUrl?: string | null;  // null = remove avatar
};

JSON.stringify({ a: undefined, b: null });
// {"b":null}

function toUpdateProfileBody(input: UpdateProfilePatch) {
  const body: Record<string, unknown> = {};

  if ('displayName' in input) body.displayName = input.displayName;
  if ('avatarUrl' in input) body.avatarUrl = input.avatarUrl;

  return body;
}

return { ok: false, error: new Error('Invalid amount') };

type Problem = {
  type: string;
  title: string;
  status: number;
  code: string;
  detail?: string;
  traceId?: string;
  fieldErrors?: Record<string, string[]>;
};

export class AppError extends Error {
  constructor(readonly problem: Problem) {
    super(problem.title);
  }
}

const user = await db.user.findUnique({
  where: { id },
  include: {
    salary: true,
    disciplinaryNotes: true,
    internalRiskScore: true,
  },
});

return user;

function toEmployeeCardDTO(user: Employee, viewer: Viewer): EmployeeCardDTO {
  return {
    id: user.id,
    name: user.name,
    title: user.title,
    avatarUrl: user.avatarUrl,
    canMessage: can(viewer, 'message', user),
  };
}

Do not serialize what the client is not allowed to know.

It ran on the server, so it is safe.

What did the server serialize into the client-visible payload?

export async function getInvoice(id: string) {
  return prisma.invoice.findUnique({
    where: { id },
    include: { customer: true, auditEvents: true },
  });
}

export async function getInvoiceDTO(id: string, viewer: Viewer): Promise<InvoiceDTO> {
  const invoice = await prisma.invoice.findUniqueOrThrow({
    where: { id },
    include: {
      customer: true,
    },
  });

  authorize(viewer, 'invoice.read', invoice);

  return {
    id: invoice.id,
    number: invoice.number,
    status: invoice.status,
    customer: {
      id: invoice.customer.id,
      name: invoice.customer.displayName,
    },
    total: {
      amountMinor: invoice.totalMinor,
      currency: invoice.currency,
    },
    issuedAt: invoice.issuedAt?.toISOString() ?? null,
    version: invoice.version,
  };
}

class CaseWorkflow {
  constructor(private caseRecord: CaseRecord) {}

  canEscalate(viewer: Viewer) {
    return this.caseRecord.status === 'open' && viewer.role === 'manager';
  }

  nextActions(viewer: Viewer) {
    // complex logic
  }
}

type CaseWorkflowView = {
  caseId: string;
  status: string;
  availableActions: Array<{
    type: 'assign' | 'escalate' | 'close';
    label: string;
    disabledReason?: string;
  }>;
};

function getPrimaryAction(view: CaseWorkflowView) {
  return view.availableActions.find((action) => !action.disabledReason) ?? null;
}

Case -> Parties -> Cases -> Parties

type CaseGraphDTO = {
  entities: {
    cases: Record<string, CaseDTO>;
    parties: Record<string, PartyDTO>;
  };
  result: {
    caseId: string;
    partyIds: string[];
  };
};

type CaseDetailDTO = {
  id: string;
  title: string;
  parties: Array<{
    id: string;
    name: string;
    role: string;
  }>;
  relatedCasesPreview: Array<{
    id: string;
    title: string;
  }>;
  hasMoreRelatedCases: boolean;
};

await updateProfile({
  name,
  avatarFile, // ❌ not a normal DTO field
});

<form action={updateProfileAction} encType="multipart/form-data">
  <input name="displayName" />
  <input name="avatar" type="file" />
  <button>Save</button>
</form>

type FileAttachmentDTO = {
  id: string;
  filename: string;
  contentType: string;
  sizeBytes: number;
  downloadUrl: string;
  expiresAt: string;
};

'use server';

export async function updateCase(caseRecord: CaseRecord, user: User, patch: any) {
  // ...
}

'use server';

export async function updateCaseAction(input: UpdateCaseInput): Promise<UpdateCaseResult> {
  const viewer = await requireViewer();
  const command = parseUpdateCaseInput(input);

  return updateCaseUseCase(viewer, command);
}

type UpdateCaseInput = {
  caseId: string;
  expectedVersion: number;
  patch: {
    title?: string;
    priority?: 'low' | 'normal' | 'high';
  };
  idempotencyKey: string;
};

type ParseResult<T> =
  | { ok: true; value: T }
  | { ok: false; issues: Array<{ path: string; message: string }> };

function parseUpdateCaseInput(raw: unknown): ParseResult<UpdateCaseInput> {
  // Use Zod, Valibot, ArkType, Effect Schema, io-ts, or your internal parser.
  // The point here is boundary validation, not the library.
  return validateUpdateCaseInput(raw);
}

'use server';

export async function updateCaseAction(raw: unknown): Promise<UpdateCaseResult> {
  const parsed = parseUpdateCaseInput(raw);

  if (!parsed.ok) {
    return {
      ok: false,
      code: 'VALIDATION_FAILED',
      fieldErrors: toFieldErrors(parsed.issues),
    };
  }

  const viewer = await requireViewer();
  return updateCase(viewer, parsed.value);
}

async function getCase(id: string): Promise<CaseDTO> {
  const json = await api.get(`/cases/${id}`).json();
  return parseCaseDTO(json);
}

server query cache snapshot -> serialized bootstrap payload -> client query cache

queryClient.setQueryData(['invoice', id], new InvoiceModel(raw));

queryClient.setQueryData(['invoice', id], invoiceDTO);

function useInvoiceModel(id: string) {
  const query = useInvoice(id);

  return {
    ...query,
    model: query.data ? createInvoiceViewModel(query.data) : undefined,
  };
}

type PersistedCacheEnvelope = {
  schemaVersion: 3;
  appBuildId: string;
  userId: string;
  tenantId: string;
  createdAt: string;
  expiresAt: string;
  payload: unknown;
};

function shouldRestoreCache(envelope: PersistedCacheEnvelope, session: SessionDTO) {
  if (envelope.schemaVersion !== 3) return false;
  if (envelope.userId !== session.userId) return false;
  if (envelope.tenantId !== session.tenantId) return false;
  if (Date.parse(envelope.expiresAt) < Date.now()) return false;

  return true;
}

export function Clock({ now }: { now: Date }) {
  return <span>{now.toLocaleString()}</span>;
}

export function Clock({ iso, formatted }: { iso: string; formatted: string }) {
  return <time dateTime={iso}>{formatted}</time>;
}

'use client';

export function ClientLocalTime({ iso }: { iso: string }) {
  const [text, setText] = useState<string | null>(null);

  useEffect(() => {
    setText(new Intl.DateTimeFormat(undefined, {
      dateStyle: 'medium',
      timeStyle: 'short',
    }).format(new Date(iso)));
  }, [iso]);

  return <time dateTime={iso}>{text ?? '—'}</time>;
}

Is the first paint server-owned or client-localized?

/domain
  case.ts              // domain logic, may use classes internally
/server
  caseRepository.ts    // database/ORM
  casePolicy.ts        // authorization
  caseMapper.ts        // domain -> DTO/view model
  caseActions.ts       // Server Functions / route actions
/client
  caseApi.ts           // fetch client / generated client
  caseQueries.ts       // query keys/hooks
  caseViewModel.ts     // client-side helpers
/shared
  caseContracts.ts     // DTO/input/result types + parsers

export function toCaseDetailDTO(
  record: CaseRecord,
  viewer: Viewer,
): CaseDetailDTO {
  return {
    id: record.id,
    title: record.title,
    status: record.status,
    priority: record.priority,
    version: record.version,
    createdAt: record.createdAt.toISOString(),
    permissions: {
      canEdit: can(viewer, 'case.edit', record),
      canClose: can(viewer, 'case.close', record),
    },
  };
}

export function assertSerializableDTO(value: unknown): void {
  // In real systems, use a contract schema or a stricter internal test helper.
  JSON.stringify(value);
}

it('serializes case detail DTO without runtime leakage', () => {
  const dto = toCaseDetailDTO(makeCaseRecord(), makeViewer());

  expect(() => assertSerializableDTO(dto)).not.toThrow();
  expect(dto).not.toHaveProperty('internalRiskScore');
});

type Brand<T, Name extends string> = T & { readonly __brand: Name };

export type ISOInstant = Brand<string, 'ISOInstant'>;
export type CalendarDate = Brand<string, 'CalendarDate'>;
export type IdempotencyKey = Brand<string, 'IdempotencyKey'>;

export function toISOInstant(date: Date): ISOInstant {
  return date.toISOString() as ISOInstant;
}

export function parseISOInstant(value: string): ISOInstant {
  const time = Date.parse(value);

  if (Number.isNaN(time)) {
    throw new Error(`Invalid ISO instant: ${value}`);
  }

  return value as ISOInstant;
}

type AuditEventDTO = {
  id: string;
  at: ISOInstant;
  actorId: string;
  action: string;
};

'use server';

export async function approveCase(input: { caseId: string; approverId: string }) {
  await db.case.update({
    where: { id: input.caseId },
    data: { approvedBy: input.approverId },
  });
}

'use server';

export async function approveCase(input: { caseId: string; expectedVersion: number }) {
  const viewer = await requireViewer();
  const parsed = parseApproveCaseInput(input);
  const record = await loadCase(parsed.caseId);

  authorize(viewer, 'case.approve', record);

  return approveCaseUseCase({
    viewerId: viewer.id,
    caseId: parsed.caseId,
    expectedVersion: parsed.expectedVersion,
  });
}

TypeError: invoice.formatTotal is not a function

Server returned class instance; client received plain object or unsupported payload.

Return DTO; reconstruct helper client-side if needed.

Due date shifts by one day for users in some timezone.

Calendar date encoded as datetime instant.

Represent date-only values as YYYY-MM-DD and avoid timezone conversion.

Internal field visible in network payload even though UI hides it.

ORM entity serialized directly.

Use authorization-aware DTO mapper and contract tests.

After logout/login, user sees previous user's cached data.

Persisted cache not scoped by user/tenant/session.

Version, scope, expire, and clear persisted cache on auth boundary changes.

Client receives generic success but does not know what to update.

Command result lacks canonical updated resource or invalidation hints.

Return explicit command result with updated DTO and conflict/error variants.

// Server side
const record = await loadRecord(id);
const dto = toDTO(record, viewer);
const safe = parseDTO(dto); // yes, validate your own mapper in tests or critical paths
return safe;

// Client side
const dto = parseDTO(await response.json());
const view = createClientViewModel(dto);

domain object -> DTO -> serialized value -> DTO -> local view model

domain object magically appears in the browser

Can I somehow serialize this object?

What stable fact should the other runtime know?

server render -> HTML/data transfer -> browser parse -> hydration -> interactive app