Question about handling nullable Integer with @JSProperty for REST API DTOs

[ivan-velikanov]

Hi @konsoletyper

First of all, thank you for all the amazing work done on teavm. I am slowly making my general code base more and more teavm compliant.

I am building annotation processors which work with lombok which generate teavm compliant jsobject interfaces, and other utility methods for serialization/deserialization without reflection in a type safe manner. I hope to be able to use shared DTOs between Java backend. Java desktop client (JavaFx) and JavaScript (both client-side and backend Cloudflare Workers).

I was tackling a use of sending/receiving REST API messages with optional numeric fields. For example:

public class PersonDTO {
private String name; // Required
private Integer age; // Optional - can be null, 0, or any number
}

The challenge: I need to distinguish between:

• {age: 0} - Person is 0 years old (valid data)
• {age: null} - Age explicitly set to null
• {} - Age not provided (undefined)

What I Discovered

When using @JSProperty with Integer:

interface PersonDTO extends JSObject {
  @JSProperty
  Integer getAge();  // Returns raw JavaScript number, not Java Integer
}

The issue: The returned Integer object cannot use Java methods directly:

Integer age = person.getAge();
if (age != null) {
System.out.println("Age: " + age); // ❌ Crashes with TypeError
int value = age.intValue(); // ❌ Crashes with TypeError
}

Error: TypeError: Cannot read properties of null (reading '$lastIndexOf0')

It appears @JSProperty returns a raw JavaScript number (not a proper Java Integer object), which lacks Java class metadata.

My Current Solution

I created a helper that converts the raw value to a proper Java Integer:

public static Integer toProperInteger(Integer rawValue) {
  // Check for null/undefined
  if (isNullOrUndefined(rawValue)) {
	  return null;
  }

  // Check for NaN
  if (isNaN(rawValue)) {
	  return null;
  }

  // Convert to primitive int, then to proper Java Integer
  int primitiveValue = toInt(rawValue);
  return Integer.valueOf(primitiveValue);
}

@JSBody(params = {"val"}, script = "return val === null || val === undefined;")
private static native boolean isNullOrUndefined(Integer val);

@JSBody(params = {"val"}, script = "return typeof val === 'number' && isNaN(val);")
private static native boolean isNaN(Integer val);

@JSBody(params = {"val"}, script = "return val | 0;")
private static native int toInt(Integer val);

Usage:
Integer age = toProperInteger(person.getAge());
if (age != null) {
  System.out.println("Age: " + age);        // ✅ Works!
  System.out.println("Next year: " + (age + 1));  // ✅ Works!
}

This successfully:

• ✅ Distinguishes 0 from null
• ✅ Handles undefined (missing property) as null
• ✅ Converts NaN to null
• ✅ Creates fully functional Java Integer objects

My Questions

1. Is this the intended behavior? Should @JSProperty with wrapper types (Integer, Double, etc.) return raw JavaScript values rather than proper Java objects?
2. Is there a better/official way to handle nullable numbers with @JSProperty? I noticed TeaVM's own tests only use primitives (int, double) with @JSProperty, never wrappers.
3. Is my solution acceptable, or is there a more idiomatic TeaVM pattern I should follow?
4. Should this be documented somewhere? I couldn't find guidance on this in the docs, and it's a common use case for REST APIs.

Thank you for any guidance you can provide! 🙏
(PS: I used bit of AI to type this, because I am having some trouble/medical issue in typing)

[konsoletyper]

Is this the intended behavior? Should @JSProperty with wrapper types (Integer, Double, etc.) return raw JavaScript values rather than proper Java objects?

Yes, this is an intended behaviour. Whenever you pass/retrieve anything except for String or JSObject to/from JS, you pass/retrieve a Java object. In case you use JSO to declare JS APIs, JSO trusts you, and it's you who's responsible for type consistency. In case you define anything as java.lang.Integer, but from JS side you return JS number, it's an error.

Passing Java objects to/from JS makes sense if you want, for example, declare a Promise that resolves with Java value or to store Java objects in JS collections.

Is there a better/official way to handle nullable numbers with @JSProperty? I noticed TeaVM's own tests only use primitives (int, double) with @JSProperty, never wrappers.

You can use JSNumber. Be careful! In JavaScript null and undefined are different, so if you expect undefined, you MUST check against it explicitly. undefined != null!

Is my solution acceptable, or is there a more idiomatic TeaVM pattern I should follow

No, it's definitely a dirty hack and nobody should ever use JSO this way.

Should this be documented somewhere? I couldn't find guidance on this in the docs, and it's a common use case for REST APIs.

Quote from docs:

TeaVM automatically converts from and to JS following types:

• boolean, byte, short, int, float, double which correspond to JavaScript numeric values.
• java.lang.String which corresponds to JavaScript String object.
• arrays of objects and primitives listed above.

So formally this is the answer to your question. I try to keep documentation as brief a possible, i.e. answer the question "what TeaVM does", but not "how would I do a thing X". Otherwise another problem arises: it's hard to navigate in the documentation and find out what you want. I just can't cover all specific developer's cases and find a way to come up with the generalized solution. Also, note that I like the idea of "tests is the code", so I'd encourage you to learn JSO from tests.

BTW, JSNumber is not something fundamental. You can write something like that yourself. Just learn its code, no magic there.

TeaVM does not convert Java collections and primitive wrappers. Additionally, TeaVM only performs conversion when type is directly known from method's signature. This means that with generics you won't get expected results, because type arguments from generics only known at compile time.

If you want a REST API, you should find a library that does not rely on reflection (e.g. uses annotation processors) or write such. I used to maintain such a library, but then abandoned it: https://github.com/konsoletyper/teavm-flavour. Feel free to fork or use it as an idea.

Also, regarding documentation. Feel free to open a PR. But it's recommended to reach me out personally to discuss your PR in advance.

[konsoletyper]

My tip it read carefully whatever I written in this topic.

[ivan-velikanov]

sorry for the confusion, it was an example to show which part will not work therefore the second part is the solution, i explained this later

Integer age = person.getAge();   // ⚠️ Raw JS number - boxing/unboxing issues

and i tested it, and it works

[konsoletyper]

            if (fieldType == String.class) return JSValueConverter.toString(jsValue);
            if (fieldType == Integer.class) return JSValueConverter.toInteger(jsValue);

This also not necessary. Everything can be resolved at the compile time by annotation processor.

[ivan-velikanov]

I have split the annotation processor in two parts - generic + teavm specific utils. I did not want to make a teavm specific annotation processor. So the annotation processor just provides the field names and types, and makes it available to the utility using a bifunction. But the converter/mapper is one time. The annotation processor's generated utility functions i use for other projects, example related to arcadedb to covert back and forth from db, did not want to have hard teavm dependency at annotation processor level (kept it optional)

[konsoletyper]

I think what you need is following: declare common JSON abstraction (base JsonNode class as well as JsonString/JsonObject/JsonArray/etc subclasses), then write annotation processor/mapper in terms of this JsonNode. Then the only thing you need for TeaVM is a converter from native JSObject to this JsonNode. Alternative approach: define this JsonNode as abstract or interface and provide JVM-specific implementation as well as TeaVM-specific implementation which would just wrap JSObject. You don't need any TeaVM-specific annotation processor. And you don't need to resolve types at runtime, everything you need is available to annotation processor, just apply corresponding converter for each property.