TypeScript type mismatch for clientId in Realtime options (null vs undefined) (ClientId must be either a string or null)

[ITBoomBKStudio]

When initializing a new Realtime client with an optional clientId, there’s an inconsistency between the TypeScript type definition and the runtime validation.

In TypeScript, passing clientId: null results in a compile-time error:

No overload matches this call.
  Overload 1 of 2, '(options: ClientOptions<CorePlugins>): Realtime', gave the following error.
    Type 'string | null' is not assignable to type 'string | undefined'.
      Type 'null' is not assignable to type 'string | undefined'.
  Overload 2 of 2, '(keyOrToken: string): Realtime', gave the following error.
    Argument of type '{ key: string; clientId: string | null; }' is not assignable to parameter of type 'string'.

So according to the typings, only string | undefined is allowed.

However, when passing undefined instead of null, a runtime error occurs:

Error: clientId must be either a string or null

---

Steps to reproduce:

import { Realtime } from "ably";

const user = { id: undefined };

const realtimeClient = new Realtime({
  key: 'your-ably-key',
  clientId: user.id ?? undefined // ✅ Compiles, ❌ Throws runtime error
});

const realtimeClient2 = new Realtime({
  key: 'your-ably-key',
  clientId: user.id ?? null // ❌ TypeScript error, ✅ Works at runtime
});

---

Expected behavior:

• The SDK should either allow null in TypeScript definitions (clientId?: string | null) or accept undefined at runtime without throwing an error.

Actual behavior:

• TypeScript forbids null, but runtime requires it.

Environment:

• SDK: [email protected]
• TypeScript: 5.1.x
• Framework: Next.js 15.5.5 (Turbopack)
• Runtime: Node.js 23.x

Suggested fix: Update the ClientOptions type definition to allow clientId?: string | null to match runtime behavior.

┆Issue is synchronized with this Jira Task by Unito

[VeskeR]

Hey @ITBoomBKStudio , thank you for reporting this.

We can confirm that there is an inconsistency between the TypeScript type definitions and the runtime validation. Both undefined and null should be valid values to represent an unidentified client. This will be addressed and corrected in the next release, expected later this week.