Add TypeScript testing and error handling documentation

[amavashev]

Summary

This PR adds comprehensive TypeScript documentation for testing Cycles-governed code and error handling patterns, bringing TypeScript documentation to feature parity with Python and Java guides.

Key Changes

• New TypeScript Testing Guide: Added extensive section to testing-with-cycles.md covering:

  • Unit testing withCycles-wrapped functions
  • Mocking CyclesClient with Vitest (vi.fn())
  • Mocking global fetch for integration tests
  • Testing error handling and exception types
  • Testing withCycles full lifecycle with mocked HTTP
  • Testing reserveForStream streaming handle behavior

• New TypeScript Error Handling Guide: Created error-handling-patterns-in-typescript.md with:

  • Complete exception hierarchy (CyclesProtocolError, CyclesTransportError, and specific subclasses)
  • Detailed property and method reference for error objects
  • Error handling patterns for withCycles and reserveForStream
  • Express middleware error handler example
  • Next.js API route error handling
  • Graceful degradation with caps support
  • Retry-after and exponential backoff patterns
  • Distinguishing retryable vs non-retryable errors

• Updated Cross-Language Guides:

  • error-handling-patterns-in-cycles-client-code.md: Added TypeScript examples alongside Python and Java for all error handling patterns (DENY decisions, degradation, debt/overdraft, expired reservations, catching all errors, web framework handlers, programmatic client errors)
  • using-the-cycles-client-programmatically.md: Added TypeScript examples for all programmatic client operations (initialization, creating/committing/releasing reservations, preflight decisions, querying balances, listing reservations, recording events)
  • testing-with-cycles.md: Updated tips section to reference TypeScript-specific mocking approaches

Notable Implementation Details

• TypeScript examples use Vitest as the test framework with vi.fn() for mocking and vi.stubGlobal() for fetch mocking
• Error handling examples cover both decorator-style (withCycles HOF) and programmatic (CyclesClient) approaches
• Documentation includes practical patterns for Express and Next.js frameworks
• All TypeScript examples follow the same structure and patterns as existing Python and Java documentation for consistency

https://claude.ai/code/session_01AioSM8RvRKCXgRsV6m75Mm