vercel_rpc_cli/codegen/

client.rs

use std::fmt::Write;

use super::typescript::{emit_jsdoc, rust_type_to_ts};
use crate::model::{Manifest, Procedure, ProcedureKind};

// Header comment included at the top of every generated client file.
const GENERATED_HEADER: &str = "\
// This file is auto-generated by vercel-rpc-cli. Do not edit manually.
// Re-run `rpc generate` or use `rpc watch` to regenerate.
";

/// Standard RPC error class with status code and structured error data.
const ERROR_CLASS: &str = r#"export class RpcError extends Error {
  readonly status: number;
  readonly data: unknown;

  constructor(status: number, message: string, data?: unknown) {
    super(message);
    this.name = "RpcError";
    this.status = status;
    this.data = data;
  }
}"#;

/// Context passed to the `onRequest` lifecycle hook.
const REQUEST_CONTEXT_INTERFACE: &str = r#"export interface RequestContext {
  procedure: string;
  method: "GET" | "POST";
  url: string;
  headers: Record<string, string>;
  input?: unknown;
}"#;

/// Context passed to the `onResponse` lifecycle hook.
const RESPONSE_CONTEXT_INTERFACE: &str = r#"export interface ResponseContext {
  procedure: string;
  method: "GET" | "POST";
  url: string;
  response: Response;
  data: unknown;
  duration: number;
}"#;

/// Context passed to the `onError` lifecycle hook.
const ERROR_CONTEXT_INTERFACE: &str = r#"export interface ErrorContext {
  procedure: string;
  method: "GET" | "POST";
  url: string;
  error: unknown;
  attempt: number;
  willRetry: boolean;
}"#;

/// Retry policy configuration.
const RETRY_POLICY_INTERFACE: &str = r#"export interface RetryPolicy {
  attempts: number;
  delay: number | ((attempt: number) => number);
  retryOn?: number[];
}"#;

/// Configuration interface for the RPC client.
const CONFIG_INTERFACE: &str = r#"export interface RpcClientConfig {
  baseUrl: string;
  fetch?: typeof globalThis.fetch;
  headers?:
    | Record<string, string>
    | (() => Record<string, string> | Promise<Record<string, string>>);
  onRequest?: (ctx: RequestContext) => void | Promise<void>;
  onResponse?: (ctx: ResponseContext) => void | Promise<void>;
  onError?: (ctx: ErrorContext) => void | Promise<void>;
  retry?: RetryPolicy;
  timeout?: number;
  serialize?: (input: unknown) => string;
  deserialize?: (text: string) => unknown;
  // AbortSignal for cancelling all requests made by this client.
  signal?: AbortSignal;
}"#;

/// Internal fetch helper shared by query and mutate methods.
const FETCH_HELPER: &str = r#"const DEFAULT_RETRY_ON = [408, 429, 500, 502, 503, 504];

async function rpcFetch(
  config: RpcClientConfig,
  method: "GET" | "POST",
  procedure: string,
  input?: unknown,
): Promise<unknown> {
  let url = `${config.baseUrl}/${procedure}`;
  const customHeaders = typeof config.headers === "function"
    ? await config.headers()
    : config.headers;
  const baseHeaders: Record<string, string> = { ...customHeaders };

  if (method === "GET" && input !== undefined) {
    const serialized = config.serialize ? config.serialize(input) : JSON.stringify(input);
    url += `?input=${encodeURIComponent(serialized)}`;
  } else if (method === "POST" && input !== undefined) {
    baseHeaders["Content-Type"] = "application/json";
  }

  const fetchFn = config.fetch ?? globalThis.fetch;
  const maxAttempts = 1 + (config.retry?.attempts ?? 0);
  const retryOn = config.retry?.retryOn ?? DEFAULT_RETRY_ON;
  const start = Date.now();

  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    const reqCtx: RequestContext = { procedure, method, url, headers: { ...baseHeaders }, input };
    await config.onRequest?.(reqCtx);

    const init: RequestInit = { method, headers: reqCtx.headers };
    if (method === "POST" && input !== undefined) {
      init.body = config.serialize ? config.serialize(input) : JSON.stringify(input);
    }

    let timeoutId: ReturnType<typeof setTimeout> | undefined;
    if (config.timeout) {
      const controller = new AbortController();
      timeoutId = setTimeout(() => controller.abort(), config.timeout);
      init.signal = config.signal
        ? AbortSignal.any([config.signal, controller.signal])
        : controller.signal;
    } else if (config.signal) {
      init.signal = config.signal;
    }

    try {
      const res = await fetchFn(url, init);

      if (!res.ok) {
        let data: unknown;
        try {
          data = await res.json();
        } catch {
          data = await res.text().catch(() => null);
        }
        const rpcError = new RpcError(
          res.status,
          `RPC error on "${procedure}": ${res.status} ${res.statusText}`,
          data,
        );
        const canRetry = retryOn.includes(res.status) && attempt < maxAttempts;
        await config.onError?.({ procedure, method, url, error: rpcError, attempt, willRetry: canRetry });
        if (!canRetry) throw rpcError;
      } else {
        const json = config.deserialize ? config.deserialize(await res.text()) : await res.json();
        const result = json?.result?.data ?? json;
        const duration = Date.now() - start;
        await config.onResponse?.({ procedure, method, url, response: res, data: result, duration });
        return result;
      }
    } catch (err) {
      if (err instanceof RpcError) throw err;
      const willRetry = attempt < maxAttempts;
      await config.onError?.({ procedure, method, url, error: err, attempt, willRetry });
      if (!willRetry) throw err;
    } finally {
      if (timeoutId !== undefined) clearTimeout(timeoutId);
    }

    if (config.retry) {
      const d = typeof config.retry.delay === "function"
        ? config.retry.delay(attempt) : config.retry.delay;
      await new Promise(r => setTimeout(r, d));
    }
  }
}"#;

/// Generates the complete `rpc-client.ts` file content from a manifest.
///
/// The output includes:
/// 1. Auto-generation header
/// 2. Re-export of `Procedures` type from the types file
/// 3. `RpcError` class for structured error handling
/// 4. Internal `rpcFetch` helper
/// 5. `createRpcClient` factory function with fully typed `query` / `mutate` methods
pub fn generate_client_file(
    manifest: &Manifest,
    types_import_path: &str,
    preserve_docs: bool,
) -> String {
    let mut out = String::with_capacity(2048);

    // Header
    out.push_str(GENERATED_HEADER);
    out.push('\n');

    // Collect all user-defined type names (structs + enums) for import
    let type_names: Vec<&str> = manifest
        .structs
        .iter()
        .map(|s| s.name.as_str())
        .chain(manifest.enums.iter().map(|e| e.name.as_str()))
        .collect();

    // Import Procedures type (and any referenced types) from the types file
    if type_names.is_empty() {
        let _ = writeln!(
            out,
            "import type {{ Procedures }} from \"{types_import_path}\";\n"
        );
        let _ = writeln!(out, "export type {{ Procedures }};\n");
    } else {
        let types_csv = type_names.join(", ");
        let _ = writeln!(
            out,
            "import type {{ Procedures, {types_csv} }} from \"{types_import_path}\";\n"
        );
        let _ = writeln!(out, "export type {{ Procedures, {types_csv} }};\n");
    }

    // Error class
    let _ = writeln!(out, "{ERROR_CLASS}\n");

    // Lifecycle hook context interfaces
    let _ = writeln!(out, "{REQUEST_CONTEXT_INTERFACE}\n");
    let _ = writeln!(out, "{RESPONSE_CONTEXT_INTERFACE}\n");
    let _ = writeln!(out, "{ERROR_CONTEXT_INTERFACE}\n");

    // Retry policy interface
    let _ = writeln!(out, "{RETRY_POLICY_INTERFACE}\n");

    // Client config interface
    let _ = writeln!(out, "{CONFIG_INTERFACE}\n");

    // Internal fetch helper
    let _ = writeln!(out, "{FETCH_HELPER}\n");

    // Type helpers for ergonomic API
    generate_type_helpers(&mut out);
    out.push('\n');

    // Client factory
    generate_client_factory(manifest, preserve_docs, &mut out);

    out
}

/// Emits utility types that power the typed client API.
fn generate_type_helpers(out: &mut String) {
    let _ = writeln!(out, "type QueryKey = keyof Procedures[\"queries\"];");
    let _ = writeln!(out, "type MutationKey = keyof Procedures[\"mutations\"];");
    let _ = writeln!(
        out,
        "type QueryInput<K extends QueryKey> = Procedures[\"queries\"][K][\"input\"];"
    );
    let _ = writeln!(
        out,
        "type QueryOutput<K extends QueryKey> = Procedures[\"queries\"][K][\"output\"];"
    );
    let _ = writeln!(
        out,
        "type MutationInput<K extends MutationKey> = Procedures[\"mutations\"][K][\"input\"];"
    );
    let _ = writeln!(
        out,
        "type MutationOutput<K extends MutationKey> = Procedures[\"mutations\"][K][\"output\"];"
    );
}

/// Generates the `createRpcClient` factory using an interface for typed overloads.
fn generate_client_factory(manifest: &Manifest, preserve_docs: bool, out: &mut String) {
    let has_queries = manifest
        .procedures
        .iter()
        .any(|p| p.kind == ProcedureKind::Query);
    let has_mutations = manifest
        .procedures
        .iter()
        .any(|p| p.kind == ProcedureKind::Mutation);

    // Emit the RpcClient interface with overloaded method signatures
    let _ = writeln!(out, "export interface RpcClient {{");

    if has_queries {
        generate_query_overloads(manifest, preserve_docs, out);
    }

    if has_mutations {
        if has_queries {
            out.push('\n');
        }
        generate_mutation_overloads(manifest, preserve_docs, out);
    }

    let _ = writeln!(out, "}}");
    out.push('\n');

    // Emit the factory function
    let _ = writeln!(
        out,
        "export function createRpcClient(config: RpcClientConfig): RpcClient {{"
    );
    let _ = writeln!(out, "  return {{");

    if has_queries {
        let _ = writeln!(
            out,
            "    query(key: QueryKey, ...args: unknown[]): Promise<unknown> {{"
        );
        let _ = writeln!(out, "      return rpcFetch(config, \"GET\", key, args[0]);");
        let _ = writeln!(out, "    }},");
    }

    if has_mutations {
        let _ = writeln!(
            out,
            "    mutate(key: MutationKey, ...args: unknown[]): Promise<unknown> {{"
        );
        let _ = writeln!(
            out,
            "      return rpcFetch(config, \"POST\", key, args[0]);"
        );
        let _ = writeln!(out, "    }},");
    }

    let _ = writeln!(out, "  }} as RpcClient;");
    let _ = writeln!(out, "}}");
}

/// Generates query overload signatures for the RpcClient interface.
fn generate_query_overloads(manifest: &Manifest, preserve_docs: bool, out: &mut String) {
    let (void_queries, non_void_queries): (Vec<_>, Vec<_>) = manifest
        .procedures
        .iter()
        .filter(|p| p.kind == ProcedureKind::Query)
        .partition(|p| is_void_input(p));

    // Overload signatures for void-input queries (no input argument required)
    for proc in &void_queries {
        if preserve_docs && let Some(doc) = &proc.docs {
            emit_jsdoc(doc, "  ", out);
        }
        let output_ts = proc
            .output
            .as_ref()
            .map(rust_type_to_ts)
            .unwrap_or_else(|| "void".to_string());
        let _ = writeln!(
            out,
            "  query(key: \"{}\"): Promise<{}>;",
            proc.name, output_ts,
        );
    }

    // Overload signatures for non-void-input queries
    for proc in &non_void_queries {
        if preserve_docs && let Some(doc) = &proc.docs {
            emit_jsdoc(doc, "  ", out);
        }
        let input_ts = proc
            .input
            .as_ref()
            .map(rust_type_to_ts)
            .unwrap_or_else(|| "void".to_string());
        let output_ts = proc
            .output
            .as_ref()
            .map(rust_type_to_ts)
            .unwrap_or_else(|| "void".to_string());
        let _ = writeln!(
            out,
            "  query(key: \"{}\", input: {}): Promise<{}>;",
            proc.name, input_ts, output_ts,
        );
    }
}

/// Generates mutation overload signatures for the RpcClient interface.
fn generate_mutation_overloads(manifest: &Manifest, preserve_docs: bool, out: &mut String) {
    let (void_mutations, non_void_mutations): (Vec<_>, Vec<_>) = manifest
        .procedures
        .iter()
        .filter(|p| p.kind == ProcedureKind::Mutation)
        .partition(|p| is_void_input(p));

    // Overload signatures for void-input mutations
    for proc in &void_mutations {
        if preserve_docs && let Some(doc) = &proc.docs {
            emit_jsdoc(doc, "  ", out);
        }
        let output_ts = proc
            .output
            .as_ref()
            .map(rust_type_to_ts)
            .unwrap_or_else(|| "void".to_string());
        let _ = writeln!(
            out,
            "  mutate(key: \"{}\"): Promise<{}>;",
            proc.name, output_ts,
        );
    }

    // Overload signatures for non-void-input mutations
    for proc in &non_void_mutations {
        if preserve_docs && let Some(doc) = &proc.docs {
            emit_jsdoc(doc, "  ", out);
        }
        let input_ts = proc
            .input
            .as_ref()
            .map(rust_type_to_ts)
            .unwrap_or_else(|| "void".to_string());
        let output_ts = proc
            .output
            .as_ref()
            .map(rust_type_to_ts)
            .unwrap_or_else(|| "void".to_string());
        let _ = writeln!(
            out,
            "  mutate(key: \"{}\", input: {}): Promise<{}>;",
            proc.name, input_ts, output_ts,
        );
    }
}

/// Returns `true` if the procedure takes no input (void).
fn is_void_input(proc: &Procedure) -> bool {
    proc.input.as_ref().is_none_or(|ty| ty.name == "()")
}