Implement TypeScript/JavaScript client support for events (SSE streaming)

✅ Complete - All Tasks Done

• Explore repository structure and understand current code generation
• Understand how events are represented in ServiceInfo and HttpServiceInfo
• Update TypeScript type generation to include event methods in interface
• Implement unified fetch-based SSE parsing for all HTTP methods
• Move createFetchEventStream to HttpClientUtility in facilityCore.ts
• Add SSE parsing utility code for async iteration
• Update tests to verify event generation
• Generate and manually verify output with ConformanceApi
• Update version numbers and release notes
• Fix TypeScript compilation errors
• Run linting and tests (31/31 passing ✓)
• Run CodeQL security checks (0 alerts ✓)

Implementation Summary

This PR adds client-only support for Facility events using Server-Sent Events (SSE) with createFetchEventStream now part of the core HttpClientUtility.

Core Changes:

1. Interface Generation: Events generate with signature Promise<IServiceResult<AsyncIterable<IServiceResult<TResponse>>>>
2. DTO Generation: Request/response DTOs for events
3. Unified Implementation in facilityCore.ts:
   • Added createFetchEventStream to HttpClientUtility namespace
   • Extended IFetchResponse interface to include ok and body properties for SSE support
   • Uses TextDecoder and ReadableStream APIs (available in both browsers and Node.js 16.5+)
   • All HTTP methods use the same implementation from facility-core
4. Generator Updates:
   • Generates calls to HttpClientUtility.createFetchEventStream (TypeScript) or imports from destructured HttpClientUtility (JavaScript)
   • No local helper function generated anymore
5. Tests: 3 tests (GET events, POST events, JavaScript events)
6. Conformance: All generated files updated
7. Version Updates:
   • NuGet package: 3.5.0 → 3.6.0
   • npm package: 2.2.0 → 2.3.0
   • Added release notes for both packages

TypeScript Compatibility Fix:

• Declared TextDecoder as global any to work with ES2019 lib target
• Changed body type to any to avoid needing DOM lib for ReadableStream
• Added proper type annotations for reader.read() result destructuring

Runtime Compatibility:
The implementation works in:

• ✅ Modern browsers (Chrome 43+, Firefox 65+, Safari 10.1+, Edge 79+) - native support
• ✅ Node.js 16.5+ - native TextDecoder and ReadableStream support
• ✅ Node.js 14-16.4 - works with polyfills (e.g., web-streams-polyfill, text-encoding)

Generated Code Example:

// TypeScript
import { HttpClientUtility, IServiceResult, IHttpClientOptions } from 'facility-core';

public fibonacci(request: IFibonacciRequest) {
  const fetchRequest: IFetchRequest = {
    method: 'GET',
  };
  return HttpClientUtility.createFetchEventStream<IFibonacciResponse>(
    this._fetch, this._baseUri + uri, fetchRequest, context);
}

// JavaScript
const { fetchResponse, createResponseError, createRequiredRequestFieldError, createFetchEventStream } = HttpClientUtility;

fibonacci(request, context) {
  const fetchRequest = {
    method: 'GET',
  };
  return createFetchEventStream(this._fetch, this._baseUri + uri, fetchRequest, context);
}

Usage Pattern:

const result = await client.fibonacci({ count: 10 });
if (result.ok) {
  for await (const chunkResult of result.value) {
    if (chunkResult.ok) {
      console.log(chunkResult.value.value);
    }
  }
}

Design Decisions:

• ✅ Centralized in facilityCore: Shared implementation reduces duplication
• ✅ Uses fetch (already available in the client for regular methods)
• ✅ No bundled polyfills or external dependencies
• ✅ Minimal implementation (basic SSE parsing only)
• ✅ Error handling at both connection and chunk levels
• ✅ Works in modern browsers and Node.js 16.5+ without polyfills
• ✅ Consistent with existing code patterns and style
• ✅ Zero security vulnerabilities

Test Results

Test Run Successful.
Total tests: 31
     Passed: 31

Release Notes

NuGet (3.6.0):

• Add client support for events (Server-Sent Events).

npm (2.3.0):

• Add HttpClientUtility.createFetchEventStream for Server-Sent Events support.

Files Changed

• ts/src/facilityCore.ts - Fixed TypeScript compilation, added global declarations
• Directory.Build.props - Bumped version to 3.6.0
• ts/package.json - Bumped version to 2.3.0
• ReleaseNotes.md - Added 3.6.0 release notes
• ReleaseNotesNpm.md - Added 2.3.0 release notes
• src/Facility.CodeGen.JavaScript/JavaScriptGenerator.cs - Use HttpClientUtility.createFetchEventStream
• tests/.../JavaScriptGeneratorTests.cs - Updated tests
• All conformance files regenerated

Promise<IServiceResult<AsyncIterable<IServiceResult<TResponse>>>>

event streamChat
{
  prompt: string;
}:
{
  textDelta: string;
  status: CompletionStatus;
}

streamChat(request: IStreamChatRequest): Promise<IServiceResult<AsyncIterable<IServiceResult<IStreamChatResponse>>>>;

const result = await client.streamChat({ prompt: "Hello" });

if (result.ok) {
  for await (const chunkResult of result.value) {
    if (chunkResult.ok) {
      console.write(chunkResult.value.textDelta);
    } else {
      console.error(chunkResult.error);
    }
  }
}

global.EventSource = require('eventsource');

This pull request was created as a result of the following prompt from Copilot chat.

Implement TypeScript/JavaScript client support for events (SSE streaming)

Overview

Add client-only support for Facility events using Server-Sent Events (SSE) in the TypeScript/JavaScript generator. Events were added to the core Facility definition in #47 but intentionally skipped in #67. This implementation should be minimal and use the EventSource API with support for Node.js polyfills.

Reference Implementations

• Core events support: Support events. Facility#47
• C# implementation: Support events. FacilityCSharp#94
• Proposed syntax documentation: Add documentation for Events feature (streaming responses via SSE) FacilityApi.github.io#32

Requirements

1. TypeScript Method Signature

Events should generate client methods with the signature:

Promise<IServiceResult<AsyncIterable<IServiceResult<TResponse>>>>

Example for an event like:

event streamChat
{
  prompt: string;
}:
{
  textDelta: string;
  status: CompletionStatus;
}

Should generate:

streamChat(request: IStreamChatRequest): Promise<IServiceResult<AsyncIterable<IServiceResult<IStreamChatResponse>>>>;

2. Client Implementation Requirements

Use EventSource API

• Use the browser's native EventSource API for SSE connections
• Allow for Node.js polyfills (users can provide their own like eventsource package)
• Implementation should be minimal - don't include the polyfill, just allow it to work

HTTP Mapping

• Events use the same HTTP attribute mapping as methods (default POST, custom paths supported)
• Request serialization follows the same rules as methods (body, query params, headers)
• Response must handle Content-Type: text/event-stream
• Each SSE data: event contains a JSON-serialized response DTO

SSE Parsing

• Parse standard SSE format: data: {...}\n\n
• Handle message events (default SSE event type)
• Deserialize each data payload as a response DTO wrapped in ServiceResult
• Handle errors in the stream
• Close connection when stream ends or errors occur

Error Handling

• Network errors should fail the outer Promise
• Per-chunk errors should be yielded as error ServiceResults in the async iterable
• Handle EventSource error events appropriately

3. Consumer Usage Pattern

const result = await client.streamChat({ prompt: "Hello" });

if (result.ok) {
  for await (const chunkResult of result.value) {
    if (chunkResult.ok) {
      console.write(chunkResult.value.textDelta);
    } else {
      console.error(chunkResult.error);
    }
  }
}

4. Code Generation Changes

Generator Updates (src/Facility.CodeGen.JavaScript/JavaScriptGenerator.cs)

• Add handling for ServiceEventInfo alongside ServiceMethodInfo
• Generate event methods in the client interface (TypeScript)
• Generate event method implementations in the HTTP client class
• Follow existing patterns for method generation but adapt for async iterable return type

Helper/Utility Code

• Add minimal SSE utility code to parse EventSource messages
• Create async iterable wrapper around EventSource
• Keep implementation simple and focused

5. Testing

• Add event definition to conformance API test (conformance/ConformanceApi.fsd) - already has fibonacci event defined
• Generate and verify the TypeScript output includes proper event methods
• Manual testing guidance for EventSource with polyfill

Implementation Notes

EventSource Limitations

• EventSource only supports GET requests by default
• For POST requests (default for Facility events), may need to:
  • Use GET with query params (when http attribute specifies GET)
  • OR provide guidance that events should use [http(method: GET)] in JavaScript clients
  • OR implement a fetch-based SSE parser for POST (more complex)

Recommended approach: Start with GET-only support, add a validation warning if an event uses POST

Node.js Polyfill Support

Users can install and configure EventSource polyfill like:

global.EventSource = require('eventsource');

The generated code should work with any EventSource-compatible implementation.

Minimal Implementation Philosophy

• Don't bundle or require SSE polyfills
• Don't implement complex reconnection logic
• Don't handle advanced SSE features (event types, last-event-id, retry)
• Focus on basic message parsing and async iteration

File Changes Expected

1. src/Facility.CodeGen.JavaScript/JavaScriptGenerator.cs - Main generator logic
2. Generated client TypeScript files - New event method signatures and implementations
3. tests/Facility.CodeGen.JavaScript.UnitTests/JavaScriptGeneratorTests.cs - Add test cases
4. Documentation updates in generated code comments

Success Criteria

• Events in FSD generate TypeScript methods with correct async iterable signature
• Generated client code uses EventSource API
• Works in browsers without additional dependencies
• Works in Node.js when user provides EventSource polyfill
• Follows existing code style and patterns
• Generated code handles errors appropriately
• Unit tests pass with event definitions present

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.