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;
  }
}"#;

/// Internal fetch helper shared by query and mutate methods.
const FETCH_HELPER: &str = r#"async function rpcFetch(
  baseUrl: string,
  method: "GET" | "POST",
  procedure: string,
  input?: unknown,
): Promise<unknown> {
  let url = `${baseUrl}/${procedure}`;
  const init: RequestInit = { method, headers: {} };

  if (method === "GET" && input !== undefined) {
    url += `?input=${encodeURIComponent(JSON.stringify(input))}`;
  } else if (method === "POST" && input !== undefined) {
    init.body = JSON.stringify(input);
    (init.headers as Record<string, string>)["Content-Type"] = "application/json";
  }

  const res = await fetch(url, init);

  if (!res.ok) {
    let data: unknown;
    try {
      data = await res.json();
    } catch {
      data = await res.text().catch(() => null);
    }
    throw new RpcError(
      res.status,
      `RPC error on "${procedure}": ${res.status} ${res.statusText}`,
      data,
    );
  }

  const json = await res.json();
  return json?.result?.data ?? json;
}"#;

/// 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");

    // 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(baseUrl: string): RpcClient {{"
    );
    let _ = writeln!(out, "  return {{");

    if has_queries {
        let _ = writeln!(
            out,
            "    query(key: QueryKey, ...args: unknown[]): Promise<unknown> {{"
        );
        let _ = writeln!(
            out,
            "      return rpcFetch(baseUrl, \"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(baseUrl, \"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 == "()")
}