Enable typescript undefined response by atmoos · Pull Request #5398 · RicoSuter/NSwag

atmoos · 2026-08-13T15:11:00Z

Rationale

Returning no value as a valid response to an endpoint (Controller action) is a viable pattern that is apparently currently only supported via null by the NSwag typescript code generator.

The apparent configuration value nullValue = Undefined is unfortunately not propagated to return types, meaning they are only ever TReturn | null instead of TReturn | undefined.

Proposal Outline

This PR bridges that gap in the TypeScriptOperationModel, by propagating the already existing setting to return types, enabling the following:

C# return type 1)	settings `nullValue`	TS return type
`TReturn`	"doesn't apply"	`TReturn`
`TReturn?`	"default"	`TReturn \| undefined` 2)
`TReturn?`	`Undefined`	`TReturn \| undefined`
`TReturn?`	`Null`	`TReturn \| null`

This is also mirrored in the tests I added.

Also the above table applies not just to C#'s nullability feature but also when using the nullability attributes. Naturally, this actually relies on the OpenApi definition "x-nullable": "true/false".

Notes

The return type irrespective of how it's defined in C# (TReturn, Task<TReturn>, {I}ActionResult<TReturn>). The OpenApi definition is relevant.
The fact that the default value for nullValue is Undefined is arguably the right choice from a TS point of view. In the context of this change it is possibly somewhat unfortunate for backward compatibility. But see the discussion about alternatives further below.

Alternatives

This PR represents the (arguably) simplest possible way to enable undefined returns. It may not be the optimal solution in terms of backward compatibility (point 2)). Hence, here some Ideas to change the implementation, if so desired by the maintainer.

A) Additional Setting

Add another independent setting: say a nullReturnValue which would take exactly the same values as nullValue, where the default would be set to Null for backward compatibility.

B) Changing the default value of `nullValue` to `Null`

This would keep return types the same, but might wreak havoc on input types and Dto parameters. If this PR were merged with a changed default value, any project that does not set that value would suddendly be seeing TInputParameter | null instead of TInputParameter | undefined. (Although by setting the nullValue setting this would be easily fixable).

Tests

It may seem that there are too many changed tests. Here's why they changed

As far as I can tell the projects don't yet make use of C# built in nullability feature meaning a return type of TReturn (some class) would be interpreted as nullable (consistent with C#'s default behaviour prior to the nullability feature)
The settings in the OpenAPI base generator used in the tests interprets a return type without attribute annotation as "CanBeNull"
- If _settings.DefaultResponseReferenceTypeNullHandling is added to the configuration of the typeDescriptor on line 283 in OperationResponseProcessorBase.cs, the interpretation would change to "NotNull". This would lead to changes in the test verifications form TReturn | null to TReturn only

RicoSuter · 2026-09-03T19:00:47Z


-                var resultType = isNullable && UnwrappedResultType != "void" && UnwrappedResultType != "null" ?
-                    UnwrappedResultType + " | null" :
+                var resultType = isNullable && UnwrappedResultType != "void" ?


shouldnt it be

Suggested change

var resultType = isNullable && UnwrappedResultType != "void" ?

var resultType = isNullable && UnwrappedResultType != "void" && UnwrappedResultType != optionalReturn

?

Quite right. I'll add a test for that on Monday and fix it.

Ok,so I added two test that assert the returned Promise as being Promise<any> when the return type is a nullable any. So we don't get a redundant Promise<any | null>, as any already "includes" null (as well as undefined).

Was that the intent of your original comment? If so, I had to change your suggestion to not check against UnwrappedResultType != optionalReturn but to verify that UnwrappedResultType is not any.

Does that capture your intention?

Update: The original UnwrappedResultType != "null" guarded a generated result type of null, which likely can't happen. The same holds for undefined as a bare result type. But the any case is precisely what is generated by a controller action that returns object. So I'd argue this is what we should be guarding against. Do you agree?

RicoSuter · 2026-09-07T21:39:59Z

The generated return type and runtime value currently disagree. For example, the new nullable-string snapshot declares Promise<string | undefined>, but a JSON null response still produces JavaScript null. A caller checking only for undefined can therefore compile successfully and crash at runtime.

Could we use your alternative A, with a separate ResponseNullValue setting defaulting to Null? That would preserve existing behavior while allowing users to explicitly opt into Undefined. When enabled, it should change both the return type and the actual response conversion consistently across supported templates.

We should add runtime tests alongside the snapshots to verify this. Empty bodies and HTTP 204 also need explicit consideration, since no response content is distinct from JSON null and isn't implied by a nullable schema.

I've merged latest master into this branch, including the development-tooling fixes; all 67 TypeScript tests now pass locally.

atmoos · 2026-09-08T06:00:44Z

The generated return type and runtime value currently disagree. For example, the new nullable-string snapshot declares Promise<string | undefined>, but a JSON null response still produces JavaScript null. A caller checking only for undefined can therefore compile successfully and crash at runtime.

Could we use your alternative A, with a separate ResponseNullValue setting defaulting to Null? That would preserve existing behavior while allowing users to explicitly opt into Undefined. When enabled, it should change both the return type and the actual response conversion consistently across supported templates.

We should add runtime tests alongside the snapshots to verify this. Empty bodies and HTTP 204 also need explicit consideration, since no response content is distinct from JSON null and isn't implied by a nullable schema.

I've merged latest master into this branch, including the development-tooling fixes; all 67 TypeScript tests now pass locally.

Thanks for your feedback! I'll gladly,

realise option A), the ResponseNullValue
align runtime with compile time types & values
align the response conversion
add runtime tests (& others if needed)

This might take some time to get done properly. Let's say on the order of a week.

This is sensible since: a) The `TypeScriptGeneratorSettings` set "Undefined" as the default b) The class `OperationResponseProcessorBase` does not use the setting `_settings.DefaultResponseReferenceTypeNullHandling` on line 283, which would then default to non null returns.

…Model.cs Co-authored-by: Rico Suter <mail@rsuter.com>

atmoos

Hello @RicoSuter

I finally got round to commenting on the new changes. Please see inline.

There is still a pending decision when the API does not allow null as a return value. Now that NSwag can honour the contract, should we treat a 204 as error (a breaking change, but honouring the API) or should we ignore the 204 (ensuring backward compatibility, but not honouring the API)

I marked those cases with "Needs architectural decision".

The other comments where added to point you to the (IMHO) relevant changes or add a reminder for myself, for minor things I noticed while going through the PR. (I plan to update this shortly)

atmoos · 2026-10-13T08:46:07Z

+        public string ResultNullValueReturn =>
+            _settings.ResponseNullValue == TypeScriptNullValue.Undefined && IsNullableResult
+                ? ResultNullValue
+                : ResultNullValue + " as any";


FYI: This "as any" path is what keeps the behaviour the same when null value has been configured as Null (i.e. not Undefined)

This pattern occurs repeatedly elsewhere, too.

atmoos · 2026-10-13T08:50:37Z


+        /// <summary>Gets or sets the value used to represent "no value" in response types and their runtime
+        /// conversion, i.e. whether a nullable response is typed and returned as 'null' or 'undefined' (default: Null).</summary>
+        public TypeScriptNullValue ResponseNullValue { get; set; }


As discussed, a "null" value setting was added that targets return values only. Hence, the original null value settings scope is unaffected by this change.

atmoos · 2026-10-13T08:52:12Z

                Resolver = _resolver,
                Settings = Settings.TypeScriptGeneratorSettings,
-                NullValue = TypeScriptNullValue.Null,
+                NullValue = Settings.ResponseNullValue,


@atmoos To check whether this is correct, or whether we should have added a second ResponseNullValue property.

atmoos · 2026-10-13T08:55:01Z

 {% elsif Framework.IsAngular -%}
 {%     if operation.WrapResponse -%}
-return {{ Framework.RxJs.ObservableOfMethod }}<{{ operation.ResultType }}>(new {{ operation.ResponseClass }}(status, _headers, null as any));
+return {{ Framework.RxJs.ObservableOfMethod }}<{{ operation.ResultType }}>(new {{ operation.ResponseClass }}(status, _headers, {{ operation.ResultNullValue }} as any));


@atmoos To check whether this "as any" remnant is correct.

atmoos · 2026-10-13T08:56:29Z

The most relevant changes to the liquid files live here.

As before, the hardcoded "as any" part has been replaced to a programmatically created value based on the new null value configuration.

atmoos · 2026-10-13T09:03:22Z

+
+            return result200;
+            });
+        } else if (status !== 200 && status !== 204) {


Return Case: "empty means a configured {undefined}"

=> A 204 is a valid response => Not throwing, but return undefined.

atmoos · 2026-10-13T09:04:43Z

+
+            return result200;
+            });
+        } else if (status !== 200 && status !== 204) {


Return Case: "empty means a configured {null}"

=> A 204 is a valid response => Not throwing, but return null.

atmoos · 2026-10-13T09:07:46Z

+            result200 = ReturnDto.fromJS(resultData200);
+            return result200;
+            });
+        } else if (status !== 200 && status !== 204) {


Return Case: "empty is not part of the API, the configured {undefined} setting case"

=> A 204 is not a valid response as per API => But, don't throw for backward compatibility and return undefined regardless.

@RicoSuter: Needs an architectural decision

atmoos · 2026-10-13T09:13:44Z

+            result200 = ReturnDto.fromJS(resultData200);
+            return result200;
+            });
+        } else if (status !== 200 && status !== 204) {


Return Case: "empty is not part of the API, the configured {null} setting case"

=> A 204 is not a valid response as per API => But, don't throw for backward compatibility and return null regardless.

@RicoSuter: Needs an architectural decision

atmoos · 2026-10-13T09:16:52Z

+
+            return result200;
+            });
+        } else if (status !== 200 && status !== 204) {


Return Case: "empty is implicitly part of the API, the configured {null} setting case"

=> A 204 is arguably a valid response as per API => return null.

atmoos commented Aug 13, 2026

View reviewed changes

Comment thread src/update-ts-snapshots.sh Outdated

RicoSuter reviewed Sep 3, 2026

View reviewed changes

atmoos force-pushed the enableTypescriptUndefinedResponse branch 2 times, most recently from 3cfd660 to 0eee331 Compare September 7, 2026 09:32

RicoSuter mentioned this pull request Sep 7, 2026

Fix development build dependencies and TypeScript test compiler #5400

Merged

atmoos and others added 17 commits September 8, 2026 08:03

Add script to run and easily diff typescript tests.

3d05a21

Print test outcome summary

fb8e3b5

Add an optional filter

3cf98e9

Add a todo!

4377b85

Enable nullable for the relevant test controllers.

abe71cf

add proper null handling

e166a5d

Revert to default nullable annotation.

f242fd0

Set up first test

f25129c

Complete the return type tests

524e49d

Revert the settings change

40a037f

Fix Verify verify prefix error.

89e21d7

Remove erroneously added script

f861ed1

Use undefined as return when it's configured.

7692499

Update src/NSwag.CodeGeneration.TypeScript/Models/TypeScriptOperation…

ad9997e

…Model.cs Co-authored-by: Rico Suter <mail@rsuter.com>

Add test case for when we return any.

e02eabc

Fix redundant union type with any

0cc4849

atmoos force-pushed the enableTypescriptUndefinedResponse branch from 546d042 to 0cc4849 Compare September 8, 2026 06:04

atmoos added 5 commits September 9, 2026 14:37

Add implementation plan

534c36b

[AI] Phase 0

ca38233

[AI] Phase 1

fa624a1

[AI] Phase 2

c5fabfc

[AI] Phase 3

5a2c4d3

atmoos added 7 commits September 9, 2026 14:38

[AI] Phase 4

f0d2bd9

[AI] Add compile coverage across all ts template types.

c393b83

Remove AI artefacts

ba5f9e7

Add missing last newline

b1d730f

[AI] use cleaner generated types when Undefined

f133ad5

Use both kinds of dto types: interface & class

a0037d2

[AI] Cover both TypeScriptTypeStyle values in response runtime tests

71f727f

atmoos commented Oct 13, 2026

View reviewed changes

	var resultType = isNullable && UnwrappedResultType != "void" ?
	var resultType = isNullable && UnwrappedResultType != "void" && UnwrappedResultType != optionalReturn

Conversation

atmoos commented Aug 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Rationale

Proposal Outline

Notes

Alternatives

A) Additional Setting

B) Changing the default value of nullValue to Null

Tests

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

atmoos Sep 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

RicoSuter commented Sep 7, 2026

Uh oh!

atmoos commented Sep 8, 2026

Uh oh!

atmoos left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

atmoos commented Aug 13, 2026 •

edited

Loading

B) Changing the default value of `nullValue` to `Null`

atmoos Sep 7, 2026 •

edited

Loading