Astro 4 for tRPC: The Hidden Cost of cross-platform for Teams

// Benchmark: superjson vs raw JSON serialization
// Run with: npx tsx benchmark-serialization.ts
import { execSync } from 'child_process';
import Superjson from 'superjson';

interface ProductVariant {
  id: string;
  sku: string;
  price: number;
  currency: string;
  available: boolean;
  metadata: Record<string, string | number | boolean>;
  createdAt: Date;
  updatedAt: Date | null;
}

interface Product {
  id: string;
  name: string;
  description: string;
  variants: ProductVariant[];
  tags: string[];
  pricing: {
    basePrice: number;
    discountPercent: number | null;
    finalPrice: number;
    tier: 'standard' | 'premium' | 'enterprise';
  };
}

// Generate 1,200 realistic product objects
function generateProducts(count: number): Product[] {
  const products: Product[] = [];
  const tiers = ['standard', 'premium', 'enterprise'] as const;
  const currencies = ['USD', 'EUR', 'GBP', 'JPY'];

  for (let i = 0; i < count; i++) {
    const variantCount = Math.floor(Math.random() * 5) + 1;
    const variants: ProductVariant[] = [];

    for (let v = 0; v < variantCount; v++) {
      variants.push({
        id: `var-${i}-${v}`,
        sku: `SKU-${String(i).padStart(4, '0')}-${v}`,
        price: Math.round((Math.random() * 500 + 9.99) * 100) / 100,
        currency: currencies[Math.floor(Math.random() * currencies.length)],
        available: Math.random() > 0.15,
        metadata: {
          color: ['red', 'blue', 'green', 'black'][Math.floor(Math.random() * 4)],
          weight: +(Math.random() * 10).toFixed(2),
          origin: ['US', 'EU', 'ASIA'][Math.floor(Math.random() * 3)],
          warehouseId: `WH-${Math.floor(Math.random() * 20)}`,
        },
        createdAt: new Date(Date.now() - Math.random() * 31536000000),
        updatedAt: Math.random() > 0.3 ? new Date() : null,
      });
    }

    products.push({
      id: `prod-${String(i).padStart(5, '0')}`,
      name: `Product ${i}`,
      description: `High-quality product description for item ${i} with details.`,
      variants,
      tags: ['electronics', 'sale', 'new-arrival'].filter(() => Math.random() > 0.4),
      pricing: {
        basePrice: Math.round((Math.random() * 400 + 29.99) * 100) / 100,
        discountPercent: Math.random() > 0.5 ? Math.floor(Math.random() * 30) + 5 : null,
        finalPrice: Math.round((Math.random() * 400 + 29.99) * 100) / 100,
        tier: tiers[Math.floor(Math.random() * tiers.length)],
      },
    });
  }
  return products;
}

// Benchmark runner with error handling
function benchmark(label: string, fn: () => void, iterations: number = 1000): void {
  try {
    const times: number[] = [];

    for (let i = 0; i < iterations; i++) {
      const start = performance.now();
      fn();
      const end = performance.now();
      times.push(end - start);
    }

    times.sort((a, b) => a - b);
    const sum = times.reduce((acc, t) => acc + t, 0);
    const mean = sum / times.length;
    const p50 = times[Math.floor(times.length * 0.5)];
    const p95 = times[Math.floor(times.length * 0.95)];
    const p99 = times[Math.floor(times.length * 0.99)];

    console.log(`\n${label} (${iterations} iterations):`);
    console.log(`  Mean:   ${mean.toFixed(3)}ms`);
    console.log(`  P50:    ${p50.toFixed(3)}ms`);
    console.log(`  P95:    ${p95.toFixed(3)}ms`);
    console.log(`  P99:    ${p99.toFixed(3)}ms`);
    console.log(`  Total:  ${sum.toFixed(3)}ms`);
  } catch (error) {
    console.error(`Benchmark "${label}" failed:`, error instanceof Error ? error.message : error);
    process.exit(1);
  }
}

// Run benchmarks
const products = generateProducts(1200);

benchmark('JSON.stringify + JSON.parse', () => {
  const serialized = JSON.stringify(products);
  const deserialized = JSON.parse(serialized);
  // Touch a date to confirm it's a string, not a Date object
  void deserialized[0].variants[0].createdAt;
});

benchmark('Superjson serialize + deserialize', () => {
  const result = Superjson.serialize(products);
  const deserialized = Superjson.deserialize(result);
  // Confirm Date objects are preserved
  const date = deserialized[0].variants[0].createdAt;
  if (!(date instanceof Date)) {
    throw new Error('Superjson failed to preserve Date type');
  }
});

// Payload size comparison
const jsonPayload = JSON.stringify(products);
const superjsonPayload = Superjson.serialize(products);
const jsonSize = Buffer.byteLength(jsonPayload, 'utf8');
const sjSize = Buffer.byteLength(JSON.stringify(superjsonPayload), 'utf8');

console.log(`\n--- Payload Size Comparison ---`);
console.log(`JSON payload size:        ${(jsonSize / 1024).toFixed(1)} KB`);
console.log(`Superjson payload size:   ${(sjSize / 1024).toFixed(1)} KB`);
console.log(`Overhead:                 ${(((sjSize - jsonSize) / jsonSize) * 100).toFixed(1)}%`);

// src/server/trpc/setup.ts
// Full tRPC server setup for Astro 4 with OpenAPI export
import { createTRPCContext } from '@/server/trpc/context';
import { appRouter } from '@/server/trpc/router';
import { fetchRequestHandler } from '@trpc/server/adapters/fetch';
import { OpenAPIHono } from '@trpc/server/adapters/openapi';
import { Hono } from 'hono';
import { cors } from 'hono/cors';
import { z } from 'zod';

// Create the tRPC context — this is where auth and DB connections live
export async function createContext(req: Request): Promise<Context> {
  const session = await validateSession(req.headers.get('cookie'));
  return {
    session,
    db: getDatabaseConnection(),
    req,
  };
}

// Define a reusable error formatter that handles
// validation errors, auth errors, and unknown exceptions
const errorFormatter = ({ shape, type }: { shape: any; type: string }) => {
  console.error(`[tRPC ${type}]`, shape.message);
  // Never leak internal details to the client
  if (type === 'INTERNAL_SERVER_ERROR') {
    return {
      ...shape,
      message: 'An unexpected error occurred',
      code: 'INTERNAL_SERVER_ERROR',
      data: undefined, // Strip stack traces and DB errors
    };
  }
  return shape;
};

// Build the Hono app with CORS for cross-origin API consumers
const app = new Hono()
  .use(
    '/api/*',
    cors({
      origin: ['https://app.example.com', 'https://admin.example.com'],
      allowHeaders: ['Content-Type', 'Authorization'],
      allowMethods: ['POST', 'GET', 'OPTIONS'],
      exposeHeaders: ['Content-Encoding'],
      maxAge: 86400,
    })
  );

// Mount tRPC as a fetch handler for Astro's server islands
app.all('/api/trpc/:path*', async (c) => {
  try {
    const response = await fetchRequestHandler({
      endpoint: '/api/trpc',
      req: c.req.raw,
      router: appRouter,
      createContext,
      onError({ error, type, path, input, shape }) {
        // Structured error logging for observability
        console.error(`[tRPC error] type=${type} path=${path}`, {
          message: error.message,
          code: error.code,
          input: input instanceof Error ? input.message : JSON.stringify(input),
        });
        return shape;
      },
      batching: {
        enabled: true, // Enable request batching for waterfall reduction
      },
    });
    return new Response(response.body, {
      status: response.status,
      headers: response.headers,
    });
  } catch (err) {
    console.error('Unhandled tRPC fetch error:', err);
    return new Response(JSON.stringify({ error: 'Internal error' }), {
      status: 500,
      headers: { 'Content-Type': 'application/json' },
    });
  }
});

// Mount OpenAPI handler for non-TypeScript consumers
// This is where the hidden cost lives: maintaining a parallel
// schema that must stay in sync with the tRPC router
const openapiApp = new OpenAPIHono({
  router: appRouter,
  exposeErrorDetails: process.env.NODE_ENV !== 'production',
});

// Register OpenAPI endpoint at /api/openapi
app.route('/api/openapi', openapiApp);

export default app;

// Context type used throughout the application
interface Context {
  session: Session | null;
  db: DatabaseConnection;
  req: Request;
}

// src/pages/dashboard.astro
// This page demonstrates the waterfall problem: each island
// independently calls the tRPC server, adding serial round-trips
---
import { getServerSideContext } from '@/server/trpc/context';
import { createServerSideHelpers } from '@trpc/react/server';
import { appRouter } from '@/server/trpc/router';
import UserProfile from '@/components/UserProfile.astro';
import RevenueChart from '@/components/RevenueChart.astro';
import RecentOrders from '@/components/RecentOrders.astro';

// Each of these components triggers a SEPARATE tRPC call
// through the fetch adapter — three serial round-trips total
const ctx = await getServerSideContext(Astro.request);
const helpers = createServerSideHelpers({ router: appRouter, ctx });

// Prefetch all data in parallel to mitigate the waterfall
// This pattern is required but NOT documented in Astro+tRPC guides
const [user, revenue, orders] = await Promise.all([
  helpers.user.getById.fetch('current'),
  helpers.analytics.getRevenue.fetch({ period: '30d' }),
  helpers.orders.list.fetch({ limit: 10, status: 'recent' }),
]).catch((err) => {
  // Global error boundary: if any tRPC call fails,
  // fall back to skeleton UI rather than crashing the page
  console.error('tRPC prefetch failed:', err);
  return [null, null, null];
});
---

<!-- Each island renders independently, but data was prefetched above -->
<UserProfile client:load user={user} />
<RevenueChart client:visible data={revenue} />
<RecentOrders client:visible orders={orders} />

// src/server/trpc/router.ts
// tRPC router with comprehensive error handling, input validation,
// and rate limiting metadata for production deployments
import { createTRPCRouter, protectedProcedure, publicProcedure } from '@/server/trpc/trpc';
import { z } from 'zod';
import { TRPCError } from '@trpc/server';
import { Ratelimit } from '@upstash/ratelimit';
import { Redis } from '@upstash/redis';

// Rate limiter: 100 requests per 60 seconds per user
const ratelimit = new Ratelimit({
  redis: Redis.fromEnv(),
  limiter: Ratelimit.slidingWindow(100, '60 s'),
  analytics: true,
});

// Reusable pagination schema — every list procedure uses this
const paginationInput = z.object({
  page: z.number().int().min(1).default(1),
  limit: z.number().int().min(1).max(100).default(20),
  sortBy: z.enum(['createdAt', 'updatedAt', 'name']).default('createdAt'),
  sortDir: z.enum(['asc', 'desc']).default('desc'),
});

export const appRouter = createTRPCRouter({
  // Public procedures still need input validation and error boundaries
  auth: createTRPCRouter({
    login: publicProcedure
      .input(z.object({ email: z.string().email(), password: z.string().min(8) }))
      .mutation(async ({ input, ctx }) => {
        try {
          const user = await ctx.db.user.findUnique({
            where: { email: input.email.toLowerCase() },
          });
          if (!user) {
            throw new TRPCError({ code: 'UNAUTHORIZED', message: 'Invalid credentials' });
          }
          const valid = await ctx.bcrypt.compare(input.password, user.passwordHash);
          if (!valid) {
            throw new TRPCError({ code: 'UNAUTHORIZED', message: 'Invalid credentials' });
          }
          const token = await ctx.jwt.sign({ sub: user.id, role: user.role });
          return { token, user: { id: user.id, name: user.name, email: user.email } };
        } catch (error) {
          if (error instanceof TRPCError) throw error;
          // Log unexpected DB errors but return generic message
          ctx.logger.error('Login mutation failed', { error, email: input.email });
          throw new TRPCError({ code: 'INTERNAL_SERVER_ERROR' });
        }
      }),
  }),

  user: createTRPCRouter({
    getById: protectedProcedure
      .input(z.string())
      .query(async ({ input: userId, ctx }) => {
        // Enforce authorization: users can only access their own profile
        // unless they have admin role
        if (ctx.session.user.id !== userId && ctx.session.user.role !== 'admin') {
          throw new TRPCError({ code: 'FORBIDDEN' });
        }
        const user = await ctx.db.user.findUnique({
          where: { id: userId },
          include: { profile: true, roles: true },
        });
        if (!user) {
          throw new TRPCError({ code: 'NOT_FOUND', message: 'User not found' });
        }
        return user;
      }),
  }),

  analytics: createTRPCRouter({
    getRevenue: protectedProcedure
      .input(z.object({ period: z.enum(['7d', '30d', '90d', '1y']) }))
      .query(async ({ input, ctx }) => {
        // Apply rate limiting at the procedure level
        const { success } = await ratelimit.limit(ctx.session.user.id);
        if (!success) {
          throw new TRPCError({ code: 'TOO_MANY_REQUESTS' });
        }
        try {
          const revenue = await ctx.db.transaction.aggregate({
            where: {
              createdAt: {
                gte: new Date(Date.now() - getPeriodMs(input.period)),
              },
            },
            _sum: { amount: true },
            _count: true,
            _avg: { amount: true },
          });
          return {
            total: revenue._sum.amount || 0,
            count: revenue._count,
            average: revenue._avg.amount || 0,
            period: input.period,
          };
        } catch (error) {
          ctx.logger.error('Revenue aggregation failed', { error, period: input.period });
          throw new TRPCError({ code: 'INTERNAL_SERVER_ERROR' });
        }
      }),
  }),

  orders: createTRPCRouter({
    list: protectedProcedure
      .input(paginationInput)
      .query(async ({ input, ctx }) => {
        const offset = (input.page - 1) * input.limit;
        const [orders, totalCount] = await Promise.all([
          ctx.db.order.findMany({
            take: input.limit,
            skip: offset,
            orderBy: { [input.sortBy]: input.sortDir },
            include: { items: true, customer: true },
          }),
          ctx.db.order.count(),
        ]);
        return {
          data: orders,
          meta: {
            totalPages: Math.ceil(totalCount / input.limit),
            currentPage: input.page,
            totalItems: totalCount,
            hasNextPage: offset + input.limit < totalCount,
          },
        };
      }),
  }),
});

// Helper to convert period string to milliseconds
function getPeriodMs(period: string): number {
  const map: Record<string, number> = {
    '7d': 7 * 24 * 60 * 60 * 1000,
    '30d': 30 * 24 * 60 * 60 * 1000,
    '90d': 90 * 24 * 60 * 60 * 1000,
    '1y': 365 * 24 * 60 * 60 * 1000,
  };
  return map[period] ?? 0;
}

// src/server/trpc/dual-transport.ts
import { initTRPC } from '@trpc/server';
import Superjson from 'superjson';
import type { Context } from './context';

const t = initTRPC.context<Context>().create({
  // Internal web client: superjson for rich types
  transformer: Superjson,
  errorFormatter({ shape }) {
    return shape;
  },
});

// Reusable strict JSON transformer for mobile/partner consumers
const jsonTransformer = {
  serialize: (obj: unknown) => JSON.stringify(obj),
  deserialize: (obj: string) => JSON.parse(obj) as unknown,
};

// Export both the router and a method to create
// a strict handler for external consumers
export { t };
export { jsonTransformer };

// Usage: create a second fetch handler with jsonTransformer
// for your /api/v1/ endpoints that serve React Native or Flutter

// src/pages/dashboard.astro — Correct batched prefetch pattern
---
import { createServerSideHelpers } from '@trpc/react/server';
import { appRouter } from '@/server/trpc/router';
import { getServerSideContext } from '@/server/trpc/context';
import DashboardShell from '@/components/DashboardShell.astro';
import MetricsCard from '@/components/MetricsCard.astro';
import ActivityFeed from '@/components/ActivityFeed.client.tsx';

// Create shared context once
const ctx = await getServerSideContext(Astro.request);
const helpers = createServerSideHelpers({ router: appRouter, ctx });

// Batch ALL tRPC calls in a single Promise.all
// This is the critical pattern — without it, each prefetch is sequential
const [{ users, activeSessions }, { totalRevenue, growthRate }, recentActivity] =
  await Promise.all([
    helpers.admin.getDashboardStats.fetch(),
    helpers.analytics.getRevenue.fetch({ period: '30d' }),
    helpers.activity.list.fetch({ limit: 25 }),
  ]).catch((error) => {
    // If any call fails, log it and return safe defaults
    // rather than crashing the entire page
    console.error('Dashboard prefetch failed:', error);
    return [{ users: [], activeSessions: 0 }, { totalRevenue: 0, growthRate: 0 }, []];
  });
---

<DashboardShell>
  <MetricsCard client:load users={users} sessions={activeSessions} />
  <MetricsCard client:load revenue={totalRevenue} growth={growthRate} />
  <ActivityFeed client:visible items={recentActivity} />
</DashboardShell>

// scripts/generate-openapi.mjs
// Automated OpenAPI spec generation with superjson normalization
import { OpenApiBuilder } from '@trpc/openapi';
import { appRouter } from '../src/server/trpc/router';
import { writeFileSync } from 'fs';
import Superjson from 'superjson';

// Generate the raw OpenAPI document from the tRPC router
const document = OpenApiBuilder.create(appRouter).build();

// Post-process: normalize superjson types so external
// consumers see standard JSON Schema types
function normalizeSuperjsonSchema(schema) {
  if (!schema || typeof schema !== 'object') return schema;

  // Recursively walk the schema object
  for (const key of Object.keys(schema)) {
    if (schema[key]?.type === 'string' && schema[key]?.format === 'Date') {
      // Convert superjson Date to standard string with format hint
      schema[key] = { type: 'string', format: 'date-time', example: '2024-01-15T09:30:00Z' };
    }
    if (schema[key]?.type === 'string' && schema[key]?.format === 'BigInt') {
      // Convert superjson BigInt to string (safe for JSON)
      schema[key] = { type: 'string', pattern: '^[0-9]+$', example: '9007199254740991' };
    }
    // Recurse into nested objects
    if (schema[key]?.properties) {
      schema[key].properties = normalizeSuperjsonSchema(schema[key].properties);
    }
    if (schema[key]?.items) {
      schema[key].items = normalizeSuperjsonSchema(schema[key].items);
    }
  }
  return schema;
}

const normalizedDoc = normalizeSuperjsonSchema(document);

// Write the final spec
const outputPath = './openapi/spec.json';
writeFileSync(outputPath, JSON.stringify(normalizedDoc, null, 2));
console.log(`OpenAPI spec written to ${outputPath}`);
console.log(`Endpoints documented: ${Object.keys(normalizedDoc.paths ?? {}).length}`);