Standard `WebSocket` type returned instead of type from `@cloudflare/workers-types`

[Peter Johnson]

Version

"@cloudflare/workers-types": "4.20240222.0"

Expected

deserializeAttachment() exists on WebSocket type returned by DurableState.getWebSockets()

Actual

DurableState.getWebSockets() returns type globalThis.WebSocket (standard type as defined by MDN Reference):

Suggestion

The types file does in fact include a type for the Cloudflare implementation of WebSocket which includes this signature, but this is not the Type which is returned.

Anecdote

Could this be due to the WebSocket type definition coming later in the types file than the DurableObjectState definition?

[Peter Johnson]

Workaround:

declare module '@cloudflare/workers-types/experimental' {
  export interface DurableObjectState extends OriginalDurableObjectState {
    acceptWebSocket: (ws: WebSocket, tags?: string[]) => void
    getWebSockets: (tag?: string) => WebSocket[]
    getWebSocketAutoResponseTimestamp: (ws: WebSocket) => Date | null
    getTags: (ws: WebSocket) => string[]
  }
  export declare const WebSocketPair: {
    new (): {
      0: WebSocket
      1: WebSocket
    }
  }
}

[Russell Davis]

I ran into this as well. I don't think it's actually a cloudflare issue though. The issue (at least for me) was that lib.dom.d.ts (which has the conflicting definition of WebSocket) was being inadvertently added to my project[1]. Even if it's not included in your tsconfig, if you have any dependencies that reference it, it gets pulled in globally (see microsoft/TypeScript#43990 and microsoft/TypeScript#37053)

[1] It was being added via fetch-retry package (which incidentally just fixed their types to stop doing that: jonbern/fetch-retry#88).

[Peter Johnson]

@russelldavis I still believe it's a CloudFlare issue as the second screenshot from within CloudFlare type definitions file shows a modal which lists the return type as globalThis.WebSocket.

I will investigate what you said and report back.

[Russell Davis]

CloudFlare type definitions file shows a modal which lists the return type as globalThis.WebSocket

That's correct and expected. The Cloudflare library defines WebSocket as a global definition (because it is available without importing, per standards). Everything works properly as long as you don't import a library with a conflicting global WebSocket definition.

[Tyler Swindell]

I ran into this issue a couple months ago when a package in my project was using the WebSocket type from lib.dom.d.ts, the solution for me was to add the following declaration extending the WebSocket type with the @cloudflare/workers-types WebSocket type.

import { type WebSocket as CloudflareWebSocket } from '@cloudflare/workers-types'

declare global {
	interface WebSocket extends CloudflareWebSocket {}
  }