fix: add WebSocketConfig type for constructor options

[eL1fe]

Summary

• Adds new WebSocketConfig type that includes only WebSocket configuration options (idleTimeout, maxPayloadLength, etc.)
• Updates ElysiaConfig.websocket to use WebSocketConfig instead of Omit<WebSocketHandler, ...>
• Exports WebSocketConfig from ws/index.ts

Problem

Users couldn't pass WebSocket config to the Elysia constructor without TypeScript errors:

const app = new Elysia({
  websocket: {
    idleTimeout: 30  // TS error: missing 'message' handler
  }
})

This happened because WebSocketHandler requires the message handler method.

Solution

Created a separate WebSocketConfig type that only includes configuration options without handler methods. This allows users to configure WebSocket behavior at the app level without needing @ts-expect-error.

Test plan

• Build passes (bun run build)
• No new type errors introduced in modified files

Fixes #1517

Summary by CodeRabbit

• New Features
  • Introduced a public WebSocketConfig type to customize server WebSocket behavior (payload limits, backpressure, idle timeout, ping, compression).
  • Exposed the WebSocketConfig type for consumers to import and reuse.
  • Added an optional server configuration option to pass WebSocketConfig when starting the server.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

Walkthrough

Adds a new exported WebSocketConfig type and updates public config/serve types to accept that config (replaces previous handler-based websocket typing), exposing websocket options through ElysiaConfig and ServeOptions.

Changes

Cohort / File(s)	Summary
WebSocket types & handler src/ws/bun.ts	Introduces WebSocketConfig type (maxPayloadLength, backpressureLimit, closeOnBackpressureLimit, idleTimeout, publishToSelf, sendPings, perMessageDeflate) and makes WebSocketHandler<T> extend WebSocketConfig, consolidating config fields.
Public exports src/ws/index.ts	Re-exports WebSocketConfig so it’s available from the public ws module.
Public config types src/types.ts	Replaces ElysiaConfig.websocket type from an Omit<WebSocketHandler<any>, ...> to WebSocketConfig; updates imports to include WebSocketConfig.
Server/serve options src/universal/server.ts	Adds optional websocket?: WebSocketConfig to ServeOptions and imports the type from ../ws/bun.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• fix: allow overriding websocket handler with listen options #1358: Merges/uses options.websocket in the Bun adapter — closely related to exposing/typing the websocket serve option.

Poem

🐰
I nibble configs, tidy and neat,
Websockets now fit my little seat.
Idle timeouts travel through the hole,
Types aligned, my whiskers stole a scroll.

Pre-merge checks and finishing touches

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main change: adding a WebSocketConfig type for constructor options, which is the primary objective of the PR.
Linked Issues check	✅ Passed	The PR successfully addresses issue #1517 by introducing WebSocketConfig type that accepts configuration options without requiring handler methods, allowing WebSocket config to be passed to the Elysia constructor without TypeScript errors.
Out of Scope Changes check	✅ Passed	All changes are directly related to adding the WebSocketConfig type and updating related interfaces; no out-of-scope modifications detected.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

📜 Recent review details

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 96ac9ac and 52e2522.

📒 Files selected for processing (4)

• src/types.ts
• src/universal/server.ts
• src/ws/bun.ts
• src/ws/index.ts

🚧 Files skipped from review as they are similar to previous changes (1)

• src/ws/index.ts

🧰 Additional context used

🧬 Code graph analysis (3)

src/ws/bun.ts (1)

src/ws/index.ts (1)

• WebSocketConfig (11-11)

src/universal/server.ts (2)

src/ws/bun.ts (1)

• WebSocketConfig (324-372)

src/ws/index.ts (1)

• WebSocketConfig (11-11)

src/types.ts (2)

src/ws/bun.ts (1)

• WebSocketConfig (324-372)

src/ws/index.ts (1)

• WebSocketConfig (11-11)

🔇 Additional comments (6)

src/universal/server.ts (2)

3-3: LGTM!

The import correctly brings in the new WebSocketConfig type for use in the ServeOptions interface.

---

125-130: LGTM!

The new websocket property allows passing WebSocket configuration options to the server. The documentation is clear and includes a helpful reference link to Bun's WebSocket documentation.

src/types.ts (2)

35-35: LGTM!

The import correctly adds WebSocketConfig to support the updated ElysiaConfig.websocket type.

---

174-174: Excellent refactor that fixes issue #1517.

Replacing Omit<WebSocketHandler<any>, 'open' | 'close' | 'message' | 'drain'> with WebSocketConfig is cleaner and more maintainable. This definitively solves the TypeScript error where users couldn't pass WebSocket configuration to the Elysia constructor without providing handler methods. The new approach separates concerns: WebSocketConfig contains only configuration options, while WebSocketHandler extends it to add handler methods.

src/ws/bun.ts (2)

429-429: LGTM! Follows DRY principle.

Having WebSocketHandler extend WebSocketConfig eliminates duplication and establishes a single source of truth for configuration properties. This is more maintainable than the previous approach where config properties were defined inline within the handler interface.

---

319-372: LGTM! Well-designed type separation.

The new WebSocketConfig type cleanly separates configuration options from handler methods. Each property is properly documented with JSDoc comments including default values. The complex perMessageDeflate union type is correctly preserved. The type is correctly exported from src/ws/index.ts, making it publicly accessible.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 0

🧹 Nitpick comments (1)

src/ws/bun.ts (1)

319-372: Consider refactoring to eliminate type duplication.

The new WebSocketConfig type duplicates the configuration properties already defined in WebSocketHandler (lines 491-549). This creates a maintenance risk where updating one type without the other could lead to inconsistencies.

🔎 Refactor suggestion to eliminate duplication

Consider having WebSocketHandler extend WebSocketConfig to avoid duplicating the configuration properties:

+/**
+ * WebSocket configuration options (without handler methods).
+ * Use this type when you only need to configure WebSocket behavior
+ * without defining message handlers.
+ */
+export type WebSocketConfig = {
+	/**
+	 * Sets the maximum size of messages in bytes.
+	 * @default 16 MB (1024 * 1024 * 16)
+	 */
+	maxPayloadLength?: number
+
+	/**
+	 * Sets the maximum number of bytes that can be buffered on a single connection.
+	 * @default 16 MB (1024 * 1024 * 16)
+	 */
+	backpressureLimit?: number
+
+	/**
+	 * Sets if the connection should be closed if `backpressureLimit` is reached.
+	 * @default false
+	 */
+	closeOnBackpressureLimit?: boolean
+
+	/**
+	 * Sets the number of seconds to wait before timing out a connection
+	 * due to no messages or pings.
+	 * @default 120 (2 minutes)
+	 */
+	idleTimeout?: number
+
+	/**
+	 * Should `ws.publish()` also send a message to `ws` (itself), if it is subscribed?
+	 * @default false
+	 */
+	publishToSelf?: boolean
+
+	/**
+	 * Should the server automatically send and respond to pings to clients?
+	 * @default true
+	 */
+	sendPings?: boolean
+
+	/**
+	 * Sets the compression level for messages, for clients that support it.
+	 * @default false (disabled)
+	 */
+	perMessageDeflate?:
+		| boolean
+		| {
+				compress?: WebSocketCompressor | boolean
+				decompress?: WebSocketCompressor | boolean
+		  }
+}

-export interface WebSocketHandler<in out T = undefined> {
+export interface WebSocketHandler<in out T = undefined> extends WebSocketConfig {
 	/**
 	 * Called when the server receives an incoming message.
 	 */
 	message(
 		ws: ServerWebSocket<T>,
 		message: string | Buffer
 	): void | Promise<void>

 	/**
 	 * Called when a connection is opened.
 	 */
 	open?(ws: ServerWebSocket<T>): void | Promise<void>

 	// ... other handler methods ...

-	/**
-	 * Sets the maximum size of messages in bytes.
-	 *
-	 * Default is 16 MB, or `1024 * 1024 * 16` in bytes.
-	 */
-	maxPayloadLength?: number
-
-	// ... remove other duplicated config properties ...
}

This ensures the configuration properties are defined in one place and automatically inherited by WebSocketHandler.

📜 Review details

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between f751caf and 96ac9ac.

📒 Files selected for processing (4)

• src/types.ts
• src/universal/server.ts
• src/ws/bun.ts
• src/ws/index.ts

🧰 Additional context used

🧬 Code graph analysis (3)

src/ws/bun.ts (1)

src/ws/index.ts (1)

• WebSocketConfig (11-11)

src/universal/server.ts (2)

src/ws/bun.ts (1)

• WebSocketConfig (324-372)

src/ws/index.ts (1)

• WebSocketConfig (11-11)

src/types.ts (2)

src/ws/bun.ts (1)

• WebSocketConfig (324-372)

src/ws/index.ts (1)

• WebSocketConfig (11-11)

🔇 Additional comments (5)

src/ws/index.ts (1)

7-11: LGTM! Clean public API exposure.

The import and re-export of WebSocketConfig correctly makes the type available for public consumption. This allows users to reference the type when configuring WebSocket options.

src/universal/server.ts (2)

3-3: LGTM! Correct import.

The import of WebSocketConfig from the internal module is appropriate for typing the new websocket property.

---

125-130: LGTM! Well-documented property addition.

The optional websocket property correctly uses the new WebSocketConfig type and includes helpful documentation. This enables users to pass WebSocket configuration through the constructor as intended.

src/types.ts (2)

35-35: LGTM! Import updated correctly.

The import now includes WebSocketConfig alongside the existing WebSocketHandler, enabling the type update in ElysiaConfig.

---

174-174: LGTM! Cleaner type definition.

The change from Omit<WebSocketHandler<any>, 'open' | 'close' | 'message' | 'drain'> to WebSocketConfig is a significant improvement. The new type is more explicit and semantically correct—configuration should contain only configuration properties, not handler methods.

Note: The previous type inadvertently included the ping? and pong? handler methods (they weren't in the omit list), which was likely unintended. The new WebSocketConfig correctly excludes all handler methods, focusing purely on configuration options.