fix(types): Add default generic for untyped RPC sessions

[Bethel-nz]

Resolves Issue #53

This PR fixes a TypeScript compilation error that occurred when creating RPC sessions without an explicit type parameter.

Problem

When newHttpBatchRpcSession() was called without a generic type, the TypeScript compiler would fail with the error:

"Type instantiation is excessively deep and possibly infinite.ts(2589)"

This happened because the function's generic T extends Serializable<T> did not have a default type. When TypeScript tried to infer T, the recursive nature of the Serializable<T> constraint caused an infinite loop in the type checker.

Reproduction

// Before fix - TypeScript compilation fails
import { newHttpBatchRpcSession } from "capnweb";
const http = newHttpBatchRpcSession("..."); // ❌ Type instantiation error

Solution

This PR aligns the behavior of newHttpBatchRpcSession with newWebSocketRpcSession by adding = Empty as the default for the generic type parameter T.

// src/index.ts
- export let newHttpBatchRpcSession<T extends Serializable<T>>
+ export let newHttpBatchRpcSession<T extends Serializable<T> = Empty>

This simple change provides a concrete type for TypeScript to use when one isn't specified, breaking the recursive loop and resolving the compilation error.

Result

After this fix, both HTTP and WebSocket sessions can be created without explicit types, providing a consistent developer experience.

// Both now work as expected for untyped sessions
const httpSession = newHttpBatchRpcSession("http://example.com"); // ✅ Works
const wsSession = newWebSocketRpcSession("ws://example.com");     // ✅ Still works

// Explicitly typed sessions are unaffected and continue to work correctly
interface MyApi { 
  ping(): Promise<string>; 
}
const typedHttp = newHttpBatchRpcSession<MyApi>("http://example.com"); // ✅ Still works

Testing

Comprehensive test coverage has been added to test/issue53.test.ts to:

• ✅ Verify that both untyped and typed sessions can be created without errors
• ✅ Confirm that untyped sessions return the expected RpcStub<Empty> behavior
• ✅ Ensure that explicitly typed sessions continue to work as expected, preventing any regressions

[kentonv]

This function is not intended to be called without a type. If the type is unknown, you should use <unknown>, or perhaps <any>.

newWebSocketRpcSession() permits omitting the type because it is a symmetrical function -- it can be used on either the client or the server. When used on the server, typically you expect that the main interface exported by the client is indeed empty, because normally it's only the server that exports a main interface to the client.

newHttpBatchRpcSession(), however, can only be used by the client, and is useless if the server exports an empty interface, since the client will have nothing to call in the batch.

[Bethel-nz]

Thanks for explaining the design philosophy - that makes perfect sense! The distinction between symmetrical vs client-only functions is a great insight.

I tried both suggested alternatives, but they hit compilation issues:

• <unknown>: Type 'unknown' does not satisfy the constraint 'Serializable<unknown>'
• <any>: Same infinite recursion error

This puts developers in a tough spot - they want to follow your guidance but can't due to the constraint design.

But would you prefer an overload approach instead? Something like:

// Helpful error when no type provided
export function newHttpBatchRpcSession(...): {
  Error: 'newHttpBatchRpcSession requires a type argument. e.g. newHttpBatchRpcSession<MyApi>(...)'
};

// Properly typed version  
export function newHttpBatchRpcSession<T extends Serializable<T>>(...): RpcStub<T>;

// Implementation
export function newHttpBatchRpcSession(
  urlOrRequest: string | Request,
  init?: RequestInit & RpcSessionOptions
): any {
  return newHttpBatchRpcSessionImpl(urlOrRequest, init);
}

This approach:

• Maintains the design philosophy (requires explicit types)
• Provides clear guidance instead of confusing infinite recursion errors
• Uses standard TypeScript patterns
• Minimizes the infinite recursion error

It doesn't solve the underlying recursive constraint issue, but it does limit the problematic usage patterns for clients and guides them toward the correct API usage.

I believe the recursion stems from the Serializable<T> type definition being inherently self-referential - when TypeScript tries to check T extends Serializable<T>, it gets caught in a loop evaluating the nested Serializable<T[K]> checks. An alternative approach might be to separate the type-level constraint from the runtime serialization logic, perhaps using structural typing or marker interfaces instead of the recursive constraint pattern.

Side note: I also noticed a potential issue where the client-side newHttpBatchRpcSession accepts RequestInit options (including fetch options like headers), but the server-side newHttpBatchRpcResponse only receives the final Request object and RpcSessionOptions. This means custom headers and other fetch options get lost in transmission, even though the types suggest they should work. Not sure if this is intentional or if there's a missing piece in the request forwarding logic.

[kentonv]

I suspect there is a more fundamental change we need to make to the types to fix these infinite recursion errors. This isn't the only place where it comes up.

The types were based on types written for Workers RPC originally, and although I made a number of changes for Cap'n Web, I have to admit I still don't fully grok them.

Side note: I also noticed a potential issue where the client-side newHttpBatchRpcSession accepts RequestInit options (including fetch options like headers), but the server-side newHttpBatchRpcResponse only receives the final Request object and RpcSessionOptions. This means custom headers and other fetch options get lost in transmission, even though the types suggest they should work. Not sure if this is intentional or if there's a missing piece in the request forwarding logic.

I don't see the problem. newHttpBatchRpcSession() lets you specify request options so you can add headers or other options for your app's use in routing the request. Cap'n Web itself does not care about these headers.