Dynamic GitHub Webhook Enum Generation (TypeScript)

Ubiquity OS Kernel · 2024 · Solved complex type-level abstraction that senior engineers couldn't crack. Eliminated manual webhook enums using advanced conditional, mapped, and template literal types with Octokit integration.

Problem

The Ubiquity OS Kernel team needed to eliminate manual webhook event enum maintenance while integrating with TypeBox validation. Senior kernel maintainer whilefoo was blocked on complex type-level abstractions required to transform Octokit’s dot-notation event names (workflow_run.requested) into valid TypeScript identifiers while preserving original values for compatibility.

Approach

• Advanced template literal type: Formatted<T> with recursive pattern matching for workflow_run.requested → WORKFLOW_RUN_REQUESTED transformation
• Mapped type preservation: Transform keys while mapping to original Octokit values for compatibility
• Runtime object construction: Build enum-like object from emitterEventNames using type-safe reduce operation
• TypeBox integration: Seamless compatibility with existing runtime validation without duplicate maintenance
• Complex type-level solution: Solved advanced TypeScript abstraction that blocked senior engineer

System diagram

flowchart LR
  Issue[Issue Recognition] --> Type[Type Analysis]
  Type --> Conditional[Conditional Type Design]
  Conditional --> Mapped[Mapped Type Implementation]
  Mapped --> Runtime[Runtime Object Generation]
  Runtime --> TypeBox[TypeBox Integration]
  TypeBox --> Review[Review Cycles]
  Review --> Merge[Merge Completion]

Outcome

• Solved complex blocker: Resolved type-level abstraction problem that prevented senior engineer progress
• Eliminated manual maintenance: Single source of truth for webhook events across entire kernel
• Preserved compatibility: Type-safe keys with unchanged Octokit values for existing integrations
• Team perception shift: Demonstrated advanced TypeScript competency beyond expected skill level
• Rapid adoption: “This looks promising!” feedback from project lead 0x4007

Constraints

• Type identifier compatibility: Keys must be valid TypeScript identifiers (no dots)
• Value preservation: Original Octokit strings required for runtime compatibility
• Type readability: Complex intersections needed prettification for IDE experience
• Senior engineer blocker: Solution required where experienced maintainer couldn’t proceed

Design choices

• Recursive template literals: Formatted<T> with pattern matching for compile-time transformation
• Type-safe runtime construction: reduce operation with proper type assertions and extraction
• Intersection prettification: Prettify utility for readable developer experience
• Value preservation enforcement: Review feedback ensured compatibility with existing Octokit expectations

Proof

Code excerpt — template/mapped types

type Formatted<T extends string> = T extends `${infer Prefix}.${infer Rest}`
  ? `${Prefix}_${Formatted<Rest>}` : T;

type GithubEventWebHookEvents = {
  [K in GitHubEventClassName as Formatted<Uppercase<K>>]: K;
};

Code excerpt — runtime construction from Octokit

export const githubWebhookEvents: Prettify<GithubEventWebHookEvents> = emitterEventNames.reduce((acc: GithubEventWebHookEvents, cur) => {
  const formatted = cur.replace(/\./g, "_");
  const upper = formatted.toUpperCase() as Formatted<Uppercase<typeof cur>>;
  acc[upper] = cur as Extract<GitHubEventClassName, Uppercase<typeof cur>>;
  return acc;
}, {} as GithubEventWebHookEvents);

Review evidence — senior engineer recognition and value preservation

"This is great! Just added some fixes because values shouldn't be changed - it got changed to workflow_run_requested but it should be workflow_run.requested" - whilefoo

"This looks promising! I was just reviewing their work related to this and began searching for a solution at the same time." - 0x4007 (project lead)

"whilefoo approved these changes on Feb 14, 2024"
"whilefoo merged commit ea1b1d7 into ubiquity-os:config on Feb 14, 2024"

Context evidence — solving where senior engineer was blocked

Original issue: "I haven't figured out how to use them with typebox"
Resolution: "resolved by #20" - demonstrating successful solution to complex type problem

Senior engineer domain: Kernel maintainer with advanced TypeScript experience
Problem complexity: Type-level abstractions with template literals and conditional types
Solution time: ~1 hour from problem analysis to working implementation

References

• Issue — #19 - dynamic webhook enums
• PR — #20 - feat: webhook type
• Files — webhook-events.ts, config.ts (see PR diff)