Docs: review Event Handler docs

[dreamorosi]

What were you searching in the docs?

Over the past few weeks we've made updates to the Event Handler ahead of the GA release, but in some cases we've let the docs lag behind as reported by internal customers.

Is this related to an existing documentation section?

No response

How can we improve?

Before the next release we should review the docs and make sure they're up to date.

Got a suggestion in mind?

No response

Acknowledgment

• I understand the final update might be different from my proposed suggestion, or refused.

[dreamorosi]

I've used Q CLI to do a couple passes at assessing the docs against the implementation in the codebase and these are the issues that were flagged. I think most of them look sensible and kind of match changes we've made since the last update but feel free to disregard any that are off - hope this helps!

1. Split Routers - Incorrectly Marked as "Coming Soon" ✅

• Documentation (lines 566-576): Says "Coming soon" and claims "Router class doesn't provide a way to compose multiple router instances"
• Reality: includeRouter() method is fully implemented in Router.ts (lines 755-763)
• Evidence: Method exists with full implementation including context merging, route registry merging, error handler merging, and middleware merging
• Impact: Users don't know this feature exists and is ready to use

2. Response Streaming - Incorrectly Marked as "Coming Soon"

• Documentation (lines 520-524): Says "Coming soon" with issue Feature request: Handle Response Streaming in Event Handler #4476
• Reality: resolveStream() method exists and is fully implemented in Router.ts, and streamify() utility is exported
• Evidence: Full implementation with HttpResponseStream support
• Impact: Users don't know streaming is available

3. Missing Exported Utilities Documentation

• Documentation: Doesn't list utility exports
• Reality: Package exports these utilities from index.ts:
  • composeMiddleware - mentioned in docs but import not shown
  • isAPIGatewayProxyEventV1 - type guard
  • isAPIGatewayProxyEventV2 - type guard
  • isExtendedAPIGatewayProxyResult - type guard
  • isHttpMethod - type guard
  • streamify - streaming helper
• Impact: Users don't know about helpful utilities

4. CORS maxAge Default Value is Wrong ✅

• Documentation (line 446): Says default is 0
• Reality: DEFAULT_CORS_OPTIONS in constants.ts does NOT include maxAge property (it's undefined)
• Evidence: The middleware checks if (config.maxAge !== undefined) before setting the header

5. Missing methodNotAllowed() Documentation ✅

• Documentation: No mention of this method
• Reality: methodNotAllowed() exists in Router.ts (lines 155-171), works like notFound()
• Impact: Users can't customize 405 responses

6. Missing Error Classes in Documentation

• Documentation: Only shows the HTTP error classes table
• Reality: Additional error classes exist and are exported:
  • InvalidEventError - for incompatible events
  • InvalidHttpMethodError - for unsupported HTTP methods
  • ParameterValidationError - for parameter validation failures
  • RouteMatchingError - base class for route matching issues

7. CORS methods Format Inconsistency ✅

• Documentation (line 442): Shows as comma-separated string GET,HEAD,PUT,PATCH,POST,DELETE
• Reality: It's an array ['DELETE', 'GET', 'HEAD', 'PATCH', 'POST', 'PUT'] (alphabetically sorted)

8. Missing RestRouterOptions.logger Documentation

• Documentation: No mention of logger option
• Reality: RestRouterOptions includes optional logger parameter

9. Missing context Property Documentation

• Documentation: No mention of Router's context property
• Reality: Router has a context property that gets merged when using includeRouter()

[dreamorosi]

Another area we should address is improving the "Testing your code" section (this) to include details on how to test functions using response streaming.

[svozza]

Ah yes, good shout, could get lost otherwise.