TypeScript — 164 Operations for AI Agents

This page is the canonical reference an AI coding agent uses to refactor, query, and analyze TypeScript code through the act MCP server. 164 operations available: 90 refactor, 18 query, 42 analysis, 14 verification. Each operation is callable from Claude Code, Cursor, Codex, OpenCode, or any MCP-compatible agent host. Click any operation for a stable anchor link suitable for citation.

Worked TypeScript examples

act101 treats the TypeScript type layer as a refactoring surface, not just a checker: the engine can derive a runtime type guard from a static interface, turn a string-literal union into an enum, or rewrite an interface as a type alias. It can also generate a mapped type from an interface or type alias, applying a readonly [K in keyof T]: T[K] transformation to every field under a new type name. It can append a satisfies clause to an object literal, checking it against a named type without widening the literal's own inferred type, and it can convert string concatenation built with + into a template literal with ${} interpolation. Every edit here is resolved against the syntax tree, never by text search. Each example below is the verbatim output of the command shown, run against the file shown.

Derive a runtime type guard from an interface

A webhook handler receives unknown JSON and needs a runtime check that mirrors the static WebhookEvent shape.

$ act refactor generate-type-guard --file webhooks.ts --name WebhookEvent

Before

export interface WebhookEvent {
  id: string;
  kind: string;
  payload: Record<string, unknown>;
  receivedAt: string;
}

After

export interface WebhookEvent {
  id: string;
  kind: string;
  payload: Record<string, unknown>;
  receivedAt: string;
}

function isWebhookEvent(value: unknown): value is WebhookEvent {
    return (
        typeof value === 'object' &&
        value !== null &&
        typeof (value as WebhookEvent).id === 'string' &&
        typeof (value as WebhookEvent).kind === 'string' &&
        typeof (value as WebhookEvent).payload === 'object' && (value as WebhookEvent).payload !== null &&
        typeof (value as WebhookEvent).receivedAt === 'string'
    );
}

The generated isWebhookEvent narrows unknown to WebhookEvent, property by property, including the null guard on the Record field.

Turn a string-literal union into an enum

color-union.ts declares type Color = "red" | "green" | "blue"; — a union of literal strings with no runtime representation.

$ act refactor-lang convert_union_to_enum --file color-union.ts --params '{"line":1,"column":1,"symbol":"Color"}'

Before

type Color = "red" | "green" | "blue";

After

enum Color { red = 'red', green = 'green', blue = 'blue' }

The type alias becomes enum Color { red = 'red', green = 'green', blue = 'blue' }; each member keeps its literal as its value, so string comparisons against the old literals still hold.

Rewrite an interface as a type alias

House style prefers type aliases for object shapes that are never merged or extended.

$ act refactor convert-interface-to-type FeatureFlag

Before

export interface FeatureFlag {
  key: string;
  enabled: boolean;
  rolloutPercent: number;
}

After

export type FeatureFlag = {
  key: string;
  enabled: boolean;
  rolloutPercent: number;
};

Only the declaration form changes — the three members, their types, and the export survive untouched.

Generate a mapped type from an interface

UserProfile has four fields and no mapped-type companion for read-only access.

$ act refactor generate-mapped-type --file user-profile.ts --target UserProfile --name PartialUserProfile

Before

interface UserProfile {
  id: string;
  username: string;
  email: string;
  createdAt: Date;
}

After

interface UserProfile {
  id: string;
  username: string;
  email: string;
  createdAt: Date;
}

type PartialUserProfile = {
    readonly [K in keyof UserProfile]: UserProfile[K];
};

A PartialUserProfile type alias is appended, applying readonly to every property named by keyof UserProfile.

Check an object literal against a type

palette.ts defines the Color union and an object literal whose property values are color strings, but nothing ties the literal to the union.

$ act refactor-lang add_satisfies --file palette.ts --params '{"type_name":"Record<string, Color>","line":3,"column":16}'

Before

type Color = "red" | "green" | "blue";

const palette = {
  primary: "red",
  secondary: "blue",
};

After

type Color = "red" | "green" | "blue";

const palette = {
  primary: "red",
  secondary: "blue",
} satisfies Record<string, Color>;

satisfies Record<string, Color> is appended after the literal's closing brace: the property values are now checked against Color, while the literal's own inferred type stays intact.

Convert concatenation to a template literal

formatMessage in format-message.ts returns "Hello " + name + ", you have " + count + " messages" — four pieces glued with +.

$ act refactor-lang use_template_literals --file format-message.ts --params '{"line":2,"column":10}'

Before

function formatMessage(name: string, count: number): string {
  return "Hello " + name + ", you have " + count + " messages";
}

After

function formatMessage(name: string, count: number): string {
  return `Hello ${name}, you have ${count} messages`;
}

The return becomes the single template literal `Hello ${name}, you have ${count} messages`, interpolating name and count in place.

Replace an OR-default with nullish coalescing

applySettings evaluates settings.theme || "light" and settings.fontSize || 14, defaulting on any falsy value rather than only null/undefined.

$ act refactor-lang add_nullish_coalescing --file settings.ts --params '{"line":7,"column":15}'

Before

interface Settings {
  theme?: string;
  fontSize?: number;
}

function applySettings(settings: Settings): void {
  const theme = settings.theme || "light";
  const fontSize = settings.fontSize || 14;
  console.log(theme, fontSize);
}

After

interface Settings {
  theme?: string;
  fontSize?: number;
}

function applySettings(settings: Settings): void {
  const theme = settings.theme ?? "light";
  const fontSize = settings.fontSize || 14;
  console.log(theme, fontSize);
}

Only the targeted settings.theme || "light" becomes settings.theme ?? "light"; the second line's settings.fontSize || 14 is untouched, so a fontSize of 0 would still resolve to 14 there.

Query

18 query tools, the same on every supported language. Descriptions live in the shared reference: /docs/query-tools.

callers control_flow data_flow definition diagnostics effect_closure effect_summary fix_auto get_type graph import_organize interface mutations references repo_outline skeleton symbols symbols_batch

Refactor

Analysis

42 analysis tools, the same on every supported language. Descriptions live in the shared reference: /docs/analysis-tools.

analyze_api_diff analyze_chokepoints analyze_clones analyze_clusters analyze_cohesion analyze_conformance analyze_coupling analyze_cycle_risk analyze_cycles analyze_dead_code analyze_depth analyze_entry_points analyze_export analyze_extraction analyze_fan_balance analyze_features analyze_hotspots analyze_impact analyze_inconsistencies analyze_inheritance analyze_interface_bloat analyze_interfaces analyze_layers analyze_orphan_types analyze_patterns analyze_platform_deps analyze_readiness analyze_roles analyze_seams analyze_stability analyze_surface analyze_test_gaps analyze_thickness analyze_type_completeness churn_hotspots co_change_clusters coverage_overlay ownership_map profile_overlay simulate split_module trace_overlay

Verify

14 verify tools, the same on every supported language. Descriptions live in the shared reference: /docs/verification.

bisect_regression gate generate_test_harness scan secret_surface summarize_pr taint_flow unsafe_surface verify_behavioral_equivalence verify_contract_preserved verify_diff_semantics verify_port_parity verify_side_effects verify_test_impact