Full-Stack Type Safety in 2026 – The Ultimate Guide

// packages/db/schema.ts
// Database schema — the single source of truth for all types in the system.
// All downstream types are inferred from here. Nothing is manually mirrored.

import {
  pgTable,
  serial,
  text,
  integer,
  timestamp,
  boolean,
  numeric,
  index,
} from 'drizzle-orm/pg-core';
import { createInsertSchema, createSelectSchema } from 'drizzle-zod';
import { z } from 'zod';

// ---------------------------------------------------------------
// Table definitions
// ---------------------------------------------------------------

export const users = pgTable(
  'users',
  {
    id: serial('id').primaryKey(),
    email: text('email').notNull().unique(),
    name: text('name').notNull(),
    // Stored as integer: 2 means 2 decimal places (e.g., USD cents display)
    currencyPrecision: integer('currency_precision').notNull().default(2),
    isActive: boolean('is_active').notNull().default(true),
    createdAt: timestamp('created_at').notNull().defaultNow(),
    updatedAt: timestamp('updated_at').notNull().defaultNow(),
  },
  (table) => ({
    emailIdx: index('users_email_idx').on(table.email),
  })
);

export const transactions = pgTable(
  'transactions',
  {
    id: serial('id').primaryKey(),
    userId: integer('user_id')
      .notNull()
      .references(() => users.id),
    // numeric columns are typed as string by Drizzle — correct for financial values
    // JavaScript floats cannot represent large decimals precisely
    amount: numeric('amount', { precision: 12, scale: 2 }).notNull(),
    currency: text('currency').notNull().default('USD'),
    status: text('status', {
      enum: ['pending', 'completed', 'failed', 'refunded'],
    }).notNull(),
    metadata: text('metadata'), // JSON stored as text
    createdAt: timestamp('created_at').notNull().defaultNow(),
  },
  (table) => ({
    userIdIdx: index('transactions_user_id_idx').on(table.userId),
    statusIdx: index('transactions_status_idx').on(table.status),
  })
);

// ---------------------------------------------------------------
// Inferred types — derived from schema, never manually written
// ---------------------------------------------------------------

export type User = typeof users.$inferSelect;
export type NewUser = typeof users.$inferInsert;
export type Transaction = typeof transactions.$inferSelect;
export type NewTransaction = typeof transactions.$inferInsert;

// Transaction['amount'] is string — Drizzle types numeric as string
// Transaction['createdAt'] is Date — Drizzle types timestamp as Date
// These differ from their JSON-serialized forms and must be handled
// explicitly in the API output layer (see Layer 2)

// ---------------------------------------------------------------
// Zod schemas derived from Drizzle schema via drizzle-zod
// drizzle-zod ^0.5 — refinements receive a Zod field schema
// and return an augmented schema
// ---------------------------------------------------------------

export const userSelectSchema = createSelectSchema(users, {
  // createdAt and updatedAt are Date objects from Drizzle
  // No refinement needed here — the select schema reflects the DB reality
});

export const userInsertSchema = createInsertSchema(users, {
  email: (schema) => schema.email('Must be a valid email address'),
  name: (schema) => schema.min(1, 'Name is required').max(255, 'Name too long'),
  // currencyPrecision defaults to 2 — constrain to valid range
  currencyPrecision: (schema) =>
    schema
      .int('Must be an integer')
      .min(0, 'Precision cannot be negative')
      .max(8, 'Precision cannot exceed 8'),
});

export const transactionSelectSchema = createSelectSchema(transactions);

export const transactionInsertSchema = createInsertSchema(transactions, {
  // amount is string (numeric column) — validate as decimal string
  amount: () =>
    z
      .string()
      .regex(/^\d+(\.\d{1,2})?$/, 'Amount must be a valid decimal with up to 2 places'),
  currency: (schema) =>
    schema.length(3, 'Currency must be a 3-character ISO 4217 code').toUpperCase(),
});

// ---------------------------------------------------------------
// Branded types — semantic safety beyond primitive types
//
// Branded types prevent accidental interchange of structurally
// identical values. UserId and TransactionId are both number,
// but TypeScript treats them as incompatible types.
//
// The unique symbol brand is stronger than string brands:
// it cannot be forged with `42 as UserId` from outside this module
// because the symbol is not exported.
// ---------------------------------------------------------------

declare const UserIdBrand: unique symbol;
declare const TransactionIdBrand: unique symbol;
declare const CurrencyCodeBrand: unique symbol;
declare const CurrencyPrecisionBrand: unique symbol;

export type UserId = number & { readonly [UserIdBrand]: typeof UserIdBrand };
export type TransactionId = number & {
  readonly [TransactionIdBrand]: typeof TransactionIdBrand;
};
export type CurrencyCode = string & {
  readonly [CurrencyCodeBrand]: typeof CurrencyCodeBrand;
};
export type CurrencyPrecision = number & {
  readonly [CurrencyPrecisionBrand]: typeof CurrencyPrecisionBrand;
};

// Constructor functions validate before casting.
// These are the only places in the codebase where casting to branded types is allowed.

export function toUserId(id: number): UserId {
  if (!Number.isInteger(id) || id <= 0) {
    throw new Error(`Invalid UserId: ${id} — must be a positive integer`);
  }
  return id as unknown as UserId;
}

export function toTransactionId(id: number): TransactionId {
  if (!Number.isInteger(id) || id <= 0) {
    throw new Error(`Invalid TransactionId: ${id} — must be a positive integer`);
  }
  return id as unknown as TransactionId;
}

export function toCurrencyCode(code: string): CurrencyCode {
  if (!/^[A-Z]{3}$/.test(code)) {
    throw new Error(
      `Invalid CurrencyCode: "${code}" — must be a 3-letter uppercase ISO 4217 code`
    );
  }
  return code as unknown as CurrencyCode;
}

export function toCurrencyPrecision(precision: number): CurrencyPrecision {
  if (!Number.isInteger(precision) || precision < 0 || precision > 8) {
    throw new Error(
      `Invalid CurrencyPrecision: ${precision} — must be an integer between 0 and 8`
    );
  }
  return precision as unknown as CurrencyPrecision;
}

// packages/api/validation.ts
// Boundary validation for all four critical boundaries.
//
// The Date serialization gap:
// Drizzle returns timestamp columns as Date objects.
// JSON serialization converts Date to ISO string.
// Output Zod schemas must handle both forms — the field
// arrives as Date from the DB, but leaves as string in the JSON response.
// The coercedDateToISOString helper below handles this explicitly.

import { z } from 'zod';
import {
  toUserId,
  toTransactionId,
  toCurrencyCode,
  type UserId,
  type TransactionId,
  type CurrencyCode,
} from '@company/db';

// ---------------------------------------------------------------
// Date serialization helper
// Use this for every timestamp field in output schemas.
// Accepts a Date object (from Drizzle) or ISO string (already serialized)
// and always produces an ISO string for the JSON response.
// ---------------------------------------------------------------

export const coercedDateToISOString = z
  .union([
    z.date().transform((d) => d.toISOString()),
    z.string().datetime(),
  ])
  .describe('Timestamp — accepts Date or ISO string, always outputs ISO string');

// ---------------------------------------------------------------
// BOUNDARY 1: API input validation
// Validates data arriving from the client before it touches the database.
// .transform() casts validated primitives to branded types.
// ---------------------------------------------------------------

export const CreateTransactionInput = z.object({
  // Transform validated integer to branded UserId
  userId: z
    .number()
    .int('User ID must be an integer')
    .positive('User ID must be positive')
    .transform(toUserId),
  // amount arrives as a number from the client form
  // We convert to string for storage (numeric column)
  amount: z
    .number()
    .positive('Amount must be positive')
    .multipleOf(0.01, 'Amount cannot have more than 2 decimal places')
    .transform((n) => n.toFixed(2)),
  // Transform and validate ISO 4217 currency code
  currency: z
    .string()
    .length(3, 'Currency must be a 3-character ISO 4217 code')
    .transform((s) => s.toUpperCase())
    .transform(toCurrencyCode),
  metadata: z.record(z.string(), z.unknown()).optional(),
});

export type CreateTransactionInput = z.infer<typeof CreateTransactionInput>;
// CreateTransactionInput.userId is UserId (branded)
// CreateTransactionInput.currency is CurrencyCode (branded)
// CreateTransactionInput.amount is string (converted for storage)

export const GetTransactionInput = z.object({
  id: z
    .number()
    .int('Transaction ID must be an integer')
    .positive('Transaction ID must be positive')
    .transform(toTransactionId),
});

export type GetTransactionInput = z.infer<typeof GetTransactionInput>;

export const ListTransactionsInput = z.object({
  limit: z.number().int().min(1).max(100).default(20),
  cursor: z.number().int().positive().optional(),
  status: z
    .enum(['pending', 'completed', 'failed', 'refunded'])
    .optional(),
});

export type ListTransactionsInput = z.infer<typeof ListTransactionsInput>;

// ---------------------------------------------------------------
// BOUNDARY 2: API output validation
// Validates data leaving the server before it reaches the client.
// This catches internal drift: schema changes, transformation bugs,
// nullable columns added without updating types.
//
// Critical: timestamp fields use coercedDateToISOString to handle
// the Date-to-string gap between Drizzle and JSON serialization.
// ---------------------------------------------------------------

export const TransactionResponse = z.object({
  id: z.number().int().positive(),
  userId: z.number().int().positive(),
  // amount is stored as numeric (string in Drizzle) — validate as decimal string
  amount: z
    .string()
    .regex(/^\d+\.\d{2}$/, 'Amount must be a decimal string with 2 places'),
  currency: z.string().length(3),
  status: z.enum(['pending', 'completed', 'failed', 'refunded']),
  // createdAt: accepts Date from Drizzle OR ISO string if already serialized
  createdAt: coercedDateToISOString,
});

export type TransactionResponse = z.infer<typeof TransactionResponse>;
// TransactionResponse.createdAt is string (ISO 8601)
// TransactionResponse.amount is string (decimal)
// These are the shapes the frontend will receive

export const UserResponse = z.object({
  id: z.number().int().positive(),
  email: z.string().email(),
  name: z.string().min(1),
  currencyPrecision: z
    .number()
    .int()
    .min(0)
    .max(8),
  isActive: z.boolean(),
  createdAt: coercedDateToISOString,
  updatedAt: coercedDateToISOString,
});

export type UserResponse = z.infer<typeof UserResponse>;

export const PaginatedTransactionsResponse = z.object({
  items: z.array(TransactionResponse),
  nextCursor: z.number().int().positive().nullable(),
});

export type PaginatedTransactionsResponse = z.infer<
  typeof PaginatedTransactionsResponse
>;

// ---------------------------------------------------------------
// Validation utility functions
// Use validateOutput on every response before returning from a procedure.
// Use validateDbRow when you need to validate individual query results.
// ---------------------------------------------------------------

export function validateOutput<T>(
  schema: z.ZodSchema<T>,
  data: unknown,
  context: string
): T {
  const result = schema.safeParse(data);
  if (!result.success) {
    // Log the full issue list for debugging — do not swallow the error
    console.error(
      `[TYPE DRIFT] Output validation failed in ${context}:`,
      result.error.issues
    );
    throw new Error(
      `Internal type drift detected in ${context} — check server logs`
    );
  }
  return result.data;
}

export function validateDbRow<T>(
  schema: z.ZodSchema<T>,
  row: unknown,
  context: string
): T {
  const result = schema.safeParse(row);
  if (!result.success) {
    console.error(
      `[DB DRIFT] Row does not match expected schema in ${context}:`,
      result.error.issues
    );
    throw new Error(
      `Database result does not match expected schema in ${context}`
    );
  }
  return result.data;
}

// ---------------------------------------------------------------
// BOUNDARY 3: External webhook validation
// Every third-party payload must be validated against an explicit schema.
// Never trust external data — validate before processing.
// ---------------------------------------------------------------

export const StripeWebhookPayload = z.object({
  id: z.string().startsWith('evt_', 'Stripe event IDs start with evt_'),
  type: z.string().min(1),
  data: z.object({
    object: z.object({
      id: z.string().startsWith('pi_', 'Payment intent IDs start with pi_'),
      amount: z
        .number()
        .int('Stripe amounts are integers in the smallest currency unit'),
      currency: z.string().length(3),
      status: z.enum(['succeeded', 'processing', 'requires_payment_method', 'canceled']),
    }),
  }),
  created: z.number().int(),
});

export type StripeWebhookPayload = z.infer<typeof StripeWebhookPayload>;

// ---------------------------------------------------------------
// BOUNDARY 4: Environment variable validation
// Validate process.env at application startup, not at call time.
// This catches missing configuration before the server accepts requests.
// ---------------------------------------------------------------

export const ServerEnvSchema = z.object({
  DATABASE_URL: z.string().url('DATABASE_URL must be a valid connection URL'),
  NODE_ENV: z.enum(['development', 'staging', 'production']),
  PORT: z
    .string()
    .transform(Number)
    .pipe(z.number().int().min(1024).max(65535))
    .default('3000'),
});

export type ServerEnv = z.infer<typeof ServerEnvSchema>;

// Call this at server startup — throws if any env var is missing or invalid
export function validateServerEnv(): ServerEnv {
  const result = ServerEnvSchema.safeParse(process.env);
  if (!result.success) {
    console.error('[ENV] Invalid server configuration:', result.error.issues);
    throw new Error('Server environment validation failed — see above for details');
  }
  return result.data;
}

// packages/api/routers/transaction.ts
// Type-safe tRPC router with input validation, output validation,
// and typed error handling.
//
// Every procedure defines:
//   .input()  — validates and types incoming data
//   .output() — validates return value before sending to client
//
// .output() does two things:
//   1. Infers the return type for the client (compile-time)
//   2. Validates the actual return value at runtime (catches internal drift)

import { z } from 'zod';
import { TRPCError } from '@trpc/server';
import { eq, desc, lt, and } from 'drizzle-orm';
import { router, protectedProcedure } from '../trpc';
import { transactions } from '@company/db';
import {
  CreateTransactionInput,
  GetTransactionInput,
  ListTransactionsInput,
  TransactionResponse,
  PaginatedTransactionsResponse,
  validateOutput,
} from '../validation';

export const transactionRouter = router({
  // -----------------------------------------------------------------
  // getById: fetch a single transaction by ID
  // -----------------------------------------------------------------
  getById: protectedProcedure
    .input(GetTransactionInput)
    .output(TransactionResponse)
    .query(async ({ input, ctx }) => {
      const rows = await ctx.db
        .select()
        .from(transactions)
        .where(eq(transactions.id, input.id))
        .limit(1);

      if (!rows[0]) {
        throw new TRPCError({
          code: 'NOT_FOUND',
          message: `Transaction ${input.id} not found`,
        });
      }

      // validateOutput catches drift between the DB row shape and
      // what the client expects. coercedDateToISOString in
      // TransactionResponse handles the Date → string conversion.
      return validateOutput(
        TransactionResponse,
        rows[0],
        'transactionRouter.getById'
      );
    }),

  // -----------------------------------------------------------------
  // create: insert a new transaction
  // -----------------------------------------------------------------
  create: protectedProcedure
    .input(CreateTransactionInput)
    .output(TransactionResponse)
    .mutation(async ({ input, ctx }) => {
      // Verify the user exists before creating the transaction
      const userExists = await ctx.db.query.users.findFirst({
        where: (users, { eq }) => eq(users.id, input.userId),
        columns: { id: true },
      });

      if (!userExists) {
        throw new TRPCError({
          code: 'BAD_REQUEST',
          message: `User ${input.userId} does not exist`,
        });
      }

      const [created] = await ctx.db
        .insert(transactions)
        .values({
          userId: input.userId,
          // amount was transformed to string by the input schema
          amount: input.amount,
          // currency was validated and branded by the input schema
          currency: input.currency,
          status: 'pending',
          metadata: input.metadata
            ? JSON.stringify(input.metadata)
            : null,
        })
        .returning();

      if (!created) {
        throw new TRPCError({
          code: 'INTERNAL_SERVER_ERROR',
          message: 'Transaction insert did not return a row',
        });
      }

      return validateOutput(
        TransactionResponse,
        created,
        'transactionRouter.create'
      );
    }),

  // -----------------------------------------------------------------
  // list: paginated transaction list with optional status filter
  // -----------------------------------------------------------------
  list: protectedProcedure
    .input(ListTransactionsInput)
    .output(PaginatedTransactionsResponse)
    .query(async ({ input, ctx }) => {
      const conditions = [];

      if (input.status) {
        conditions.push(eq(transactions.status, input.status));
      }

      if (input.cursor) {
        conditions.push(lt(transactions.id, input.cursor));
      }

      // Fetch one extra row to determine if there is a next page
      const rows = await ctx.db
        .select()
        .from(transactions)
        .where(conditions.length > 0 ? and(...conditions) : undefined)
        .orderBy(desc(transactions.id))
        .limit(input.limit + 1);

      const hasNextPage = rows.length > input.limit;
      const pageRows = rows.slice(0, input.limit);

      return validateOutput(
        PaginatedTransactionsResponse,
        {
          items: pageRows.map((row) =>
            validateOutput(
              TransactionResponse,
              row,
              'transactionRouter.list.item'
            )
          ),
          nextCursor: hasNextPage
            ? pageRows[pageRows.length - 1]?.id ?? null
            : null,
        },
        'transactionRouter.list'
      );
    }),
});

// -----------------------------------------------------------------
// Typed error handling
//
// tRPC error codes map to HTTP status codes:
//   NOT_FOUND          → 404
//   BAD_REQUEST        → 400
//   UNAUTHORIZED       → 401
//   FORBIDDEN          → 403
//   INTERNAL_SERVER_ERROR → 500
//
// The frontend receives typed error codes and can narrow on them:
//
//   const mutation = trpc.transaction.create.useMutation({
//     onError(error) {
//       if (error.data?.code === 'BAD_REQUEST') {
//         // Handle validation error
//       }
//     },
//   });
// -----------------------------------------------------------------

// apps/web/features/transactions/transaction-list.tsx
// Frontend type consumption — all types inferred or imported.
// No manual API response interfaces.

'use client';

import { useState } from 'react';
import { trpc } from '@/lib/trpc';
// Types imported from the shared API package — never redefined here
import type { TransactionResponse } from '@company/api';
import { CreateTransactionInput } from '@company/api';

// ---------------------------------------------------------------
// WRONG: Manually defining API response types
// ---------------------------------------------------------------
// interface Transaction {        // ❌ Second source of truth
//   id: number;
//   amount: string;
//   currency: string;
//   status: string;
//   createdAt: string;
// }
//
// This drifts the moment the API changes. TypeScript will not warn you.
// ---------------------------------------------------------------

// ---------------------------------------------------------------
// CORRECT: Type inferred from tRPC client
// ---------------------------------------------------------------
// trpc.transaction.list.useQuery() returns data typed as:
//   { items: TransactionResponse[]; nextCursor: number | null } | undefined
// This type comes directly from the server's .output() schema.
// A schema change produces a compile error here automatically.

export function TransactionList() {
  const { data, isLoading, error } = trpc.transaction.list.useQuery({
    limit: 20,
  });

  if (isLoading) {
    return <div aria-busy="true">Loading transactions...</div>;
  }

  // error.data.code is typed — you can narrow on specific tRPC error codes
  if (error) {
    if (error.data?.code === 'UNAUTHORIZED') {
      return <div>Please sign in to view transactions.</div>;
    }
    return <div>Failed to load transactions: {error.message}</div>;
  }

  if (!data) return null;

  return (
    <ul>
      {data.items.map((transaction) => (
        <TransactionItem key={transaction.id} transaction={transaction} />
      ))}
    </ul>
  );
}

// ---------------------------------------------------------------
// Component props derived from canonical type using utility types.
// Never redeclare fields that exist on TransactionResponse.
// ---------------------------------------------------------------

interface TransactionItemProps {
  // Pick only the fields this component uses — not the full type
  transaction: Pick<
    TransactionResponse,
    'id' | 'amount' | 'currency' | 'status' | 'createdAt'
  >;
  onSelect?: (id: number) => void;
}

function TransactionItem({ transaction, onSelect }: TransactionItemProps) {
  // transaction.createdAt is string (ISO 8601) — defined by TransactionResponse
  // Parse to Date for display — do not assume the format, always parse explicitly
  const formattedDate = new Intl.DateTimeFormat('en-US', {
    dateStyle: 'medium',
  }).format(new Date(transaction.createdAt));

  const formattedAmount = new Intl.NumberFormat('en-US', {
    style: 'currency',
    currency: transaction.currency,
  }).format(parseFloat(transaction.amount));

  return (
    <li
      onClick={() => onSelect?.(transaction.id)}
      className="flex justify-between py-2 cursor-pointer"
    >
      <span>{formattedAmount}</span>
      <span>{transaction.status}</span>
      <time dateTime={transaction.createdAt}>{formattedDate}</time>
    </li>
  );
}

// ---------------------------------------------------------------
// Form: same Zod schema as the server — one definition, both sides.
// Client validation catches the same errors the server would reject.
// Field error types are inferred from the Zod schema.
// ---------------------------------------------------------------

type CreateTransactionFormState = {
  values: Partial<{
    userId: number;
    amount: number;
    currency: string;
    metadata?: Record<string, unknown>;
  }>;
  // z.ZodError.flatten() produces typed field errors
  // The type is inferred from the schema — no manual error interfaces
  errors: ReturnType<
    ReturnType<(typeof CreateTransactionInput)['safeParse']>['error'] extends infer E
      ? E extends z.ZodError
        ? typeof E.prototype.flatten
        : never
      : never
  > | null;
};

function CreateTransactionForm() {
  const [state, setState] = useState<CreateTransactionFormState>({
    values: {},
    errors: null,
  });

  const mutation = trpc.transaction.create.useMutation({
    onError(error) {
      // error.data.code is typed as a TRPCError code
      if (error.data?.code === 'BAD_REQUEST') {
        console.error('Validation error from server:', error.message);
      }
    },
  });

  function handleSubmit(e: React.FormEvent<HTMLFormElement>) {
    e.preventDefault();

    // Client-side validation using the same schema as the server.
    // .safeParse() on the raw form values — these are pre-transform types.
    // Note: the schema will run .transform() — userId becomes UserId, etc.
    const result = CreateTransactionInput.safeParse(state.values);

    if (!result.success) {
      setState((prev) => ({
        ...prev,
        errors: result.error.flatten() as any,
      }));
      return;
    }

    // result.data is fully typed: CreateTransactionInput (post-transform)
    // userId is UserId (branded), currency is CurrencyCode (branded)
    mutation.mutate(result.data);
  }

  return (
    <form onSubmit={handleSubmit}>
      {state.errors?.fieldErrors.amount && (
        <p role="alert" className="text-red-600">
          {state.errors.fieldErrors.amount[0]}
        </p>
      )}
      {/* form fields */}
      <button type="submit" disabled={mutation.isPending}>
        {mutation.isPending ? 'Creating...' : 'Create Transaction'}
      </button>
    </form>
  );
}

// Re-export types consumers of this feature might need
export type { TransactionItemProps };

// packages/shared/index.ts
// The shared type package — the structural foundation of full-stack type safety.
//
// Rules for this package:
//   1. Zero framework dependencies (no React, no Express, no Drizzle, no Prisma)
//   2. No layer-specific types (no component props, no middleware types, no ORM queries)
//   3. Only types used by two or more layers belong here
//   4. This package is the INTERSECTION of cross-layer types — not the union of all types

// ---------------------------------------------------------------
// CATEGORY 1: Domain types (branded)
// These are used by every layer — DB, API, and frontend
// The unique symbol brand cannot be forged via type assertion
// ---------------------------------------------------------------

declare const UserIdBrand: unique symbol;
declare const TransactionIdBrand: unique symbol;
declare const CurrencyCodeBrand: unique symbol;
declare const CurrencyPrecisionBrand: unique symbol;

export type UserId = number & { readonly [UserIdBrand]: typeof UserIdBrand };
export type TransactionId = number & {
  readonly [TransactionIdBrand]: typeof TransactionIdBrand;
};
export type CurrencyCode = string & {
  readonly [CurrencyCodeBrand]: typeof CurrencyCodeBrand;
};
export type CurrencyPrecision = number & {
  readonly [CurrencyPrecisionBrand]: typeof CurrencyPrecisionBrand;
};

export type TransactionStatus =
  | 'pending'
  | 'completed'
  | 'failed'
  | 'refunded';

// ---------------------------------------------------------------
// CATEGORY 2: API contract types
// Used by both the API package (to produce) and the frontend (to consume)
// ---------------------------------------------------------------

export interface PaginatedResponse<T> {
  items: T[];
  nextCursor: number | null;
}

export interface ApiError {
  code: string;
  message: string;
  details?: Record<string, string[]>;
}

export type ApiResponse<T> =
  | { data: T; error: null }
  | { data: null; error: ApiError };

// ---------------------------------------------------------------
// CATEGORY 3: Utility types
// Generic helpers used across layers
// ---------------------------------------------------------------

// Make specific fields required on an otherwise-optional type
export type RequireFields<T, K extends keyof T> = T & Required<Pick<T, K>>;

// Strip branded type tags — useful for serialization and testing
export type Unbranded<T> = {
  [K in keyof T]: T[K] extends number & { [key: symbol]: unknown }
    ? number
    : T[K] extends string & { [key: symbol]: unknown }
    ? string
    : T[K];
};

// Recursive deep partial — useful for update operations
export type DeepPartial<T> = {
  [K in keyof T]?: T[K] extends object ? DeepPartial<T[K]> : T[K];
};

// Result type for operations that can fail with typed errors
export type Result<T, E = ApiError> =
  | { ok: true; value: T }
  | { ok: false; error: E };

export function ok<T>(value: T): Result<T> {
  return { ok: true, value };
}

export function err<E = ApiError>(error: E): Result<never, E> {
  return { ok: false, error };
}

// packages/api/error-handling.ts
// Typed error patterns for the full-stack type chain.
// Error codes, structured error responses, and client-side error handling.

import { TRPCError } from '@trpc/server';
import { z } from 'zod';
import type { ApiError } from '@company/shared';

// ---------------------------------------------------------------
// Typed application error codes
// These extend TRPCError codes with domain-specific error types.
// ---------------------------------------------------------------

export const AppErrorCode = {
  // Resource errors
  NOT_FOUND: 'NOT_FOUND',
  ALREADY_EXISTS: 'ALREADY_EXISTS',
  // Authorization errors
  UNAUTHORIZED: 'UNAUTHORIZED',
  FORBIDDEN: 'FORBIDDEN',
  INSUFFICIENT_FUNDS: 'INSUFFICIENT_FUNDS',
  // Validation errors
  VALIDATION_ERROR: 'VALIDATION_ERROR',
  INVALID_CURRENCY: 'INVALID_CURRENCY',
  INVALID_AMOUNT: 'INVALID_AMOUNT',
  // System errors
  INTERNAL_ERROR: 'INTERNAL_ERROR',
  DATABASE_ERROR: 'DATABASE_ERROR',
  EXTERNAL_SERVICE_ERROR: 'EXTERNAL_SERVICE_ERROR',
} as const;

export type AppErrorCode = (typeof AppErrorCode)[keyof typeof AppErrorCode];

// ---------------------------------------------------------------
// Structured error factory
// Wraps TRPCError with a consistent shape the frontend can rely on.
// ---------------------------------------------------------------

export function createAppError(
  code: AppErrorCode,
  message: string,
  details?: Record<string, string[]>
): TRPCError {
  // Map domain codes to tRPC HTTP codes
  const trpcCode = (() => {
    switch (code) {
      case AppErrorCode.NOT_FOUND:
        return 'NOT_FOUND';
      case AppErrorCode.UNAUTHORIZED:
        return 'UNAUTHORIZED';
      case AppErrorCode.FORBIDDEN:
      case AppErrorCode.INSUFFICIENT_FUNDS:
        return 'FORBIDDEN';
      case AppErrorCode.VALIDATION_ERROR:
      case AppErrorCode.INVALID_CURRENCY:
      case AppErrorCode.INVALID_AMOUNT:
      case AppErrorCode.ALREADY_EXISTS:
        return 'BAD_REQUEST';
      default:
        return 'INTERNAL_SERVER_ERROR';
    }
  })();

  return new TRPCError({
    code: trpcCode,
    message,
    cause: details ? new Error(JSON.stringify(details)) : undefined,
  });
}

// ---------------------------------------------------------------
// Zod error → field error map
// Use this to convert Zod validation failures to form field errors
// on the client side. The output type is explicitly mapped so the
// frontend can render field-level error messages without string parsing.
// ---------------------------------------------------------------

export function zodErrorToFieldErrors(
  error: z.ZodError
): Record<string, string[]> {
  const fieldErrors: Record<string, string[]> = {};
  for (const issue of error.issues) {
    const path = issue.path.join('.');
    const key = path || '_root';
    if (!fieldErrors[key]) {
      fieldErrors[key] = [];
    }
    fieldErrors[key].push(issue.message);
  }
  return fieldErrors;
}

// ---------------------------------------------------------------
// Client-side error utilities
// These run in the frontend — imported from @company/api
// ---------------------------------------------------------------

// Type guard for TRPCClientError
import type { TRPCClientError } from '@trpc/client';
import type { AppRouter } from '../root';

export function isTRPCError(
  error: unknown
): error is TRPCClientError<AppRouter> {
  return (
    error !== null &&
    typeof error === 'object' &&
    'data' in error &&
    'message' in error
  );
}

// Extract typed field errors from a tRPC validation error response
export function extractFieldErrors(
  error: TRPCClientError<AppRouter>
): Record<string, string[]> | null {
  if (error.data?.code !== 'BAD_REQUEST') return null;
  try {
    // tRPC serializes Zod issues in error.data.zodError
    const zodError = error.data?.zodError;
    if (!zodError) return null;
    return (zodError.fieldErrors as Record<string, string[]>) ?? null;
  } catch {
    return null;
  }
}

// ---------------------------------------------------------------
// Frontend usage example:
//
// const mutation = trpc.transaction.create.useMutation({
//   onError(error) {
//     if (isTRPCError(error)) {
//       const fieldErrors = extractFieldErrors(error);
//       if (fieldErrors) {
//         setFormErrors(fieldErrors); // Record<string, string[]>
//         return;
//       }
//       if (error.data?.code === 'INSUFFICIENT_FUNDS') {
//         showToast('Insufficient funds for this transaction');
//         return;
//       }
//     }
//   },
// });
// ---------------------------------------------------------------

#!/usr/bin/env bash
# audit-type-safety.sh
# Run before starting migration to understand the current state of type safety.
# Produces a prioritized list of the riskiest untyped boundaries.

set -euo pipefail

echo "=================================================================="
echo " Full-Stack Type Safety Audit"
echo "=================================================================="
echo ""

# -----------------------------------------------------------------
# 1. Find manually defined API response interfaces (migration targets)
# These interfaces may have drifted from the actual API responses.
# -----------------------------------------------------------------
echo "--- Manually defined API interfaces (potential drift sources) ---"
grep -rn --include='*.ts' --include='*.tsx' \
  -E 'interface [A-Z][a-zA-Z]*(Response|Request|Payload|ApiResult)' \
  apps/ src/ \
  | sort \
  | head -30
echo ""

# -----------------------------------------------------------------
# 2. Find unvalidated JSON.parse calls (runtime type risk)
# Every JSON.parse without a Zod schema is a potential runtime error.
# -----------------------------------------------------------------
echo "--- Unvalidated JSON.parse calls (add Zod validation here) ---"
grep -rn --include='*.ts' --include='*.tsx' \
  'JSON\.parse' \
  apps/ src/ packages/ \
  | grep -v 'safeParse\|schema\.parse\|\.parse(' \
  | grep -v node_modules \
  | grep -v '\.test\.' \
  | head -20
echo ""

# -----------------------------------------------------------------
# 3. Find 'as unknown as' or forced type assertions (type safety bypasses)
# Forced assertions hide real type mismatches.
# -----------------------------------------------------------------
echo "--- Forced type assertions (potential type safety bypasses) ---"
grep -rn --include='*.ts' --include='*.tsx' \
  -E 'as unknown as|as any' \
  apps/ src/ packages/ \
  | grep -v node_modules \
  | grep -v '\.test\.' \
  | grep -v '// safe:' \
  | sort \
  | head -20
echo ""

# -----------------------------------------------------------------
# 4. Find fetch() calls without response type validation
# Every raw fetch() is a potential untyped API boundary.
# -----------------------------------------------------------------
echo "--- Raw fetch() calls without Zod parsing (migration priority) ---"
grep -rn --include='*.ts' --include='*.tsx' \
  'await fetch(' \
  apps/ src/ \
  | grep -v 'safeParse\|schema\.parse\|z\.object' \
  | grep -v node_modules \
  | head -20
echo ""

# -----------------------------------------------------------------
# 5. TypeScript strict mode status per package
# Packages without strict: true have hidden type errors.
# -----------------------------------------------------------------
echo "--- TypeScript strict mode status per tsconfig ---"
find . -name 'tsconfig.json' \
  -not -path '*/node_modules/*' \
  -not -path '*/.git/*' \
  | while read -r f; do
    strict=$(python3 -c "
import json, sys
try:
  d = json.load(open('$f'))
  print(d.get('compilerOptions', {}).get('strict', 'NOT SET'))
except: print('PARSE ERROR')
" 2>/dev/null)
    echo "  $f → strict: $strict"
  done
echo ""

echo "=================================================================="
echo " Recommended migration order:"
echo "  1. Enable strict: true in all tsconfig.json files"
echo "  2. Add Zod validation to all fetch() calls above"
echo "  3. Replace manual API interfaces with Zod-inferred types"
echo "  4. Migrate high-traffic endpoints to tRPC"
echo "  5. Add branded types for IDs and domain values"
echo "=================================================================="

// full-pipeline-example.ts
// Annotated walkthrough of the complete type safety pipeline.
// Shows how a single schema change propagates to a frontend compile error.

// =================================================================
// SCENARIO: Add a required `merchantId` field to transactions
// =================================================================

// -----------------------------------------------------------------
// STEP 1: Database schema change (packages/db/schema.ts)
// -----------------------------------------------------------------
//
// export const transactions = pgTable('transactions', {
//   id: serial('id').primaryKey(),
//   userId: integer('user_id').notNull().references(() => users.id),
//   amount: numeric('amount', { precision: 12, scale: 2 }).notNull(),
//   currency: text('currency').notNull().default('USD'),
//   status: text('status', { enum: ['pending', 'completed', 'failed', 'refunded'] }).notNull(),
//
//   // NEW FIELD — required, no default
//   merchantId: integer('merchant_id').notNull().references(() => merchants.id),
//
//   metadata: text('metadata'),
//   createdAt: timestamp('created_at').notNull().defaultNow(),
// });

// -----------------------------------------------------------------
// STEP 2: Inferred types update automatically
// No command to run — the type updates the moment the schema file changes.
// -----------------------------------------------------------------
//
// export type Transaction = typeof transactions.$inferSelect;
// Transaction now has: merchantId: number
// Transaction now requires merchantId in inserts: NewTransaction

// -----------------------------------------------------------------
// STEP 3: drizzle-zod schemas update automatically
// createInsertSchema reads the schema at build time.
// -----------------------------------------------------------------
//
// export const transactionInsertSchema = createInsertSchema(transactions, {
//   amount: () => z.string().regex(/^\d+(\.\d{1,2})?$/),
//   currency: (schema) => schema.length(3).toUpperCase(),
// });
// transactionInsertSchema now REQUIRES merchantId

// -----------------------------------------------------------------
// STEP 4: API input validation schema updates automatically
// CreateTransactionInput is built from transactionInsertSchema.
// -----------------------------------------------------------------
//
// export const CreateTransactionInput = z.object({
//   userId: z.number().int().positive().transform(toUserId),
//   amount: z.number().positive().transform((n) => n.toFixed(2)),
//   currency: z.string().length(3).transform(toCurrencyCode),
//   merchantId: z.number().int().positive(), // NEW — required
//   metadata: z.record(z.string(), z.unknown()).optional(),
// });

// -----------------------------------------------------------------
// STEP 5: tRPC procedure input type updates
// The procedure uses CreateTransactionInput — its type updates automatically.
// -----------------------------------------------------------------
//
// create: protectedProcedure
//   .input(CreateTransactionInput)  // merchantId is now required in input
//   .output(TransactionResponse)
//   .mutation(async ({ input, ctx }) => { ... })

// -----------------------------------------------------------------
// STEP 6: Frontend compile error
// The tRPC client reflects the updated procedure input type.
// Any call to create that omits merchantId produces a compile error.
// -----------------------------------------------------------------
//
// const mutation = trpc.transaction.create.useMutation();
//
// mutation.mutate({
//   userId: 1,
//   amount: 99.99,
//   currency: 'USD',
//   // ❌ COMPILE ERROR:
//   // Argument of type '{ userId: number; amount: number; currency: string; }'
//   // is not assignable to parameter of type 'CreateTransactionInput'.
//   // Property 'merchantId' is missing.
// });

// =================================================================
// RESULT
// One schema change → automatic compile error in the frontend.
// No manual sync. No documentation to update. No runtime error in production.
// The TypeScript compiler IS your integration test for data contracts.
// =================================================================

// -----------------------------------------------------------------
// SAFE MIGRATION PATTERN for adding required fields
// Never add a required column without a default value in a single deploy.
// The type chain enforces correctness — the deployment sequence
// must match the migration pattern below.
// -----------------------------------------------------------------
//
// Step A: Deploy migration with column as nullable (or with DEFAULT)
//   ALTER TABLE transactions ADD COLUMN merchant_id INTEGER REFERENCES merchants(id);
//
// Step B: Deploy the application code that populates merchant_id
//   (the schema still allows NULL, so existing inserts don't break)
//
// Step C: Backfill existing rows
//   UPDATE transactions SET merchant_id = ... WHERE merchant_id IS NULL;
//
// Step D: Deploy migration that makes the column NOT NULL
//   ALTER TABLE transactions ALTER COLUMN merchant_id SET NOT NULL;
//
// Step E: Update the Drizzle schema to .notNull() — types now enforce the contract
//   merchantId: integer('merchant_id').notNull().references(() => merchants.id),
//
// This sequence ensures the type chain is never broken at runtime.