[Feature] Add nullable reference annotations.

[Jason5Lee]

The playwright library has no clear documentation about whether an argument or return type can be null. In the original TypeScript library it's not a problem since the type system of TypeScript supports nullable annotation. For example, the page.contentText has a string | null type, which indicates that it may be null. With strictNullCheck compiler option, you can't call its methods without proper null check.

However, in this project, the nullable annotation is absent, neither the documentation points out the fact that it can be null.

Java actually has a plenty of null annotations. These annotations can also be identify in Kotlin. I hope nullable can be properly annotated like the TypeScript library, or at least be documented.

[yury-s]

There is no @NotNull/@nullable annotations in standard Java which means we'd need to pick one of the third-party options which may work for some people but potentially cause conflicts for others. Are you talking about JetBrains annotations or something else?

[Jason5Lee]

I think JetBrains one is good. Even a documentation improvement can help if you want to keep third-party libraries minimum.

[jhyot]

Another widely accepted way (I think at least) is to document clearly that methods do not accept or return null values by default, and any exceptions to this rule are clearly documented in the Javadoc.

[seekM]

Since Java 8 it's possible to indicate that no value might be present using the Optional class. Could that maybe be used an alternative to annotations (for return types, at least)?

[yury-s]

I don't quite like the idea of optional as it would make the call sites even more verbose with extra .get() calls.

[3flex]

Couple of points:

1. From @yury-s: "we'd need to pick one of the third-party options which may work for some people but potentially cause conflicts for others" - is this really a blocker? There are countless projects adding nullability annotations of one flavour or another to their libraries, as far as I know the only major issue is that there's no standardisation (JSpecify will hopefully one day address this, but until then...)
2. At least some nullability annotation would majorly assist all IDE users, and Kotlin users when compiling
3. If adding annotation to source is truly not an option, could we instead get external annotations? They can be published in a separate artifact.

[lppedd]

JetBrains annotations are pretty much standard at this point between projects that use nullability annotations (outside of Eclipse).

However, I would much prefer to see Kotlin adopted, which would offer a safer alternative, and perfect interoperability with other JVM languages like Java.

[3flex]

There is no @NotNull/@nullable annotations in standard Java which means we'd need to pick one of the third-party options which may work for some people but potentially cause conflicts for others. Are you talking about JetBrains annotations or something else?

Picking JSpecify seems to be a safer choice than ever:

• In IntelliJ 2025.3 "JSpecify becomes the preferred nullability source".
• JSpecify reached version 1.0.0 last year.
• Kotlin 2.1.0 strictly checks JSpecify annotations.
• Eclipse JDT Language Server added support in November.

I can't find info about Eclipse itself, but slide 17 in this presentation says it's already supported: https://resources.jetbrains.com/storage/products/kotlinconf-2025/may-23/JSpecify_%20Java%20Nullness%20Annotations%20and%20Kotlin%20_%20David%20Baker.pdf

Slide 2 shows the projects and companies participating in the JSpecify Working Group.

Is more feedback required before this is considered?

[lppedd]

Yes, JSpecify is the gold standard at this point. The Kotlin/JB folks also contributed to JSpecify, so it's the correct choice.