Server Utilities

/**
 * Creates a start handler for server-side request processing
 * @param options - Configuration options for the handler
 * @returns Request handler function
 */
function createStartHandler(
  options?: { streamHandler?: StreamHandler }
): RequestHandler<Register>;

/**
 * Handle server actions and provide proper error handling
 * @param action - The server action to handle
 * @returns Promise resolving to action result
 */
function handleServerAction<T>(action: T): Promise<T>;

/**
 * Create a request handler with custom logic
 * @param handler - Function to handle the request
 * @returns Request handler with proper typing
 */
function requestHandler<TRegister>(
  handler: (request: Request) => Response | Promise<Response>
): RequestHandler<TRegister>;

import { createStartHandler, requestHandler } from "@tanstack/react-start/server";

// Basic start handler
const handler = createStartHandler();

// Custom request handler
const apiHandler = requestHandler(async (request) => {
  if (request.url.includes("/api/")) {
    return new Response(JSON.stringify({ message: "API endpoint" }), {
      headers: { "Content-Type": "application/json" }
    });
  }
  return new Response("Not found", { status: 404 });
});

// Handler with custom stream handler
const streamHandler = createStartHandler({
  streamHandler: (readable) => {
    // Custom streaming logic
    return readable;
  }
});

/**
 * Get the current request object
 * @returns Current HTTP request
 */
function getRequest(): Request;

/**
 * Get all request headers as an object
 * @returns Object containing all request headers
 */
function getRequestHeaders(): Record<string, string>;

/**
 * Get a specific request header by name
 * @param name - Header name to retrieve
 * @returns Header value or undefined
 */
function getRequestHeader(name: string): string | undefined;

/**
 * Get the client IP address from the request
 * @param options - Options for IP detection
 * @returns Client IP address or undefined
 */
function getRequestIP(options?: { ipHeader?: string }): string | undefined;

import {
  getRequest,
  getRequestHeaders,
  getRequestHeader,
  getRequestIP
} from "@tanstack/react-start";

// Access request information in a server function
const getUserInfo = createServerFn()
  .handler(async () => {
    const request = getRequest();
    const headers = getRequestHeaders();
    const userAgent = getRequestHeader("user-agent");
    const clientIP = getRequestIP();

    return {
      method: request.method,
      url: request.url,
      userAgent,
      clientIP,
      headers
    };
  });

/**
 * Create a JSON response with proper headers
 * @param data - Data to serialize as JSON
 * @param options - Response options
 * @returns JSON response object
 */
function json<T>(
  data: T,
  options?: { status?: number; headers?: HeadersInit }
): JsonResponse;

/**
 * Merge multiple header objects into one
 * @param headers - Header objects to merge
 * @returns Merged headers object
 */
function mergeHeaders(...headers: HeadersInit[]): Headers;

import { json, mergeHeaders } from "@tanstack/react-start";

// Create JSON responses
const getUsers = createServerFn()
  .handler(async () => {
    const users = await db.user.findMany();

    return json(users, {
      status: 200,
      headers: { "Cache-Control": "max-age=300" }
    });
  });

// Merge headers from multiple sources
const createUser = createServerFn()
  .handler(async (userData) => {
    const user = await db.user.create({ data: userData });

    const responseHeaders = mergeHeaders(
      { "Content-Type": "application/json" },
      { "X-User-ID": user.id },
      { "Cache-Control": "no-cache" }
    );

    return json(user, { headers: responseHeaders });
  });

/**
 * Attach router server-side SSR utilities
 * @param router - Router instance to enhance
 * @returns Enhanced router with SSR utilities
 */
function attachRouterServerSsrUtils<T>(router: T): T;

/**
 * Transform readable stream with router context
 * @param stream - Readable stream to transform
 * @param router - Router instance
 * @returns Transformed stream
 */
function transformReadableStreamWithRouter<T>(
  stream: ReadableStream<T>,
  router: any
): ReadableStream<T>;

/**
 * Transform pipeable stream with router context
 * @param stream - Pipeable stream to transform
 * @param router - Router instance
 * @returns Transformed stream
 */
function transformPipeableStreamWithRouter<T>(
  stream: T,
  router: any
): T;

/**
 * Get the global Start context
 * @returns Global Start context object
 */
function getGlobalStartContext(): StartContext;

/**
 * Get the current router instance
 * @returns Router instance
 */
function getRouterInstance(): AnyRouter;

// Request handler types
interface RequestHandler<TRegister> {
  (request: Request): Promise<Response> | Response;
}

interface RequestOptions {
  onError?: (error: Error) => Response | Promise<Response>;
  onRequest?: (request: Request) => Request | Promise<Request>;
  onResponse?: (response: Response) => Response | Promise<Response>;
}

// Stream handler types
interface StreamHandler {
  (readable: ReadableStream): ReadableStream;
}

// JSON response type
interface JsonResponse {
  json(): any;
  status: number;
  headers: Headers;
  ok: boolean;
  statusText: string;
}

// Start context type
interface StartContext {
  request: Request;
  response?: Response;
  [key: string]: any;
}

// Router types
interface AnyRouter {
  // Router implementation from TanStack Router
}

// Registration interface
interface Register {
  // Extend this for custom type registration
}

// HTTP headers constants
const HEADERS: {
  readonly CONTENT_TYPE: string;
  readonly CACHE_CONTROL: string;
  readonly X_TSS_SERIALIZED: string;
};