KY is forcing empty string on 204

[KutnerUri]

Currently, when an API responds with a 204 No Content status, ky's .json() method returns an empty string (""). This is a helpful convenience that prevents an error from being thrown when trying to parse an empty response body.

However, the choice of an empty string as the default value can lead to unexpected behavior. For example, it prevents the use of standard optional chaining (?.) to safely access properties on a potentially non-existent object.

Consider the following common pattern:

const data = await ky.get('...').json();

// EDIT: the error happened when trying to access slightly nested data:
const numberOfPosts = data?.content.posts.length;
// This throws a TypeError: Cannot read properties of undefined (reading 'posts')

Because "" is not null or undefined, the optional chaining operator does not short-circuit, and the code attempts to access a property on a string, causing a runtime error. The ideal value in this scenario would be null, which works naturally with this syntax.

I attempted to use an afterResponse hook to modify this, but it appears this behavior is handled internally by ky after the hooks have run.

Proposed Solution

I propose adding a new option to ky that allows developers to specify the value that should be returned for a 204 No Content response. This would provide flexibility while maintaining the helpful default for backward compatibility.

Here are a couple of ideas for the API design:

const client = ky.create({
  // Defaults to "" for backward compatibility
  noContentValue: null
});

const data = await client.get(...).json(); // `data` will be `null` on a 204 response
const userContent = data?.content; // Works as expected, `userContent` is `undefined`

or - an extendible object

const client = ky.create({
  defaultResponseValues: {
    // Defaults to { 204: "" }
    204: null
  }
});

This would solve the issue by allowing developers to choose a value (like null) that aligns better with modern JavaScript patterns like optional chaining and nullish coalescing.

[sholladay]

I'm afraid there is some kind of misunderstanding of optional chaining here. The real problem might be that your code is trying to access properties of userContent without optional chaining when it should be using optional chaining.

Below, you can see the results of running multiple variations on accessing foo.content, with foo as an empty string vs null, and with optional chaining vs without. Notice that they all log undefined, until the last variant where foo is null and we do not use optional chaining, which causes the code to throw. In other words, your choice of null would make the code more susceptible to errors, not less. And in fact, that is precisely why we chose an empty string in the first place.

~/Code/sandbox
❯ node -e 'const foo = \'\'; console.log(foo?.content)'
undefined

~/Code/sandbox
❯ node -e 'const foo = null; console.log(foo?.content)'
undefined

~/Code/sandbox
❯ node -e 'const foo = \'\'; console.log(foo.content)'
undefined

~/Code/sandbox
❯ node -e 'const foo = null; console.log(foo.content)'
[eval]:1
const foo = null; console.log(foo.content)
                                  ^

TypeError: Cannot read properties of null (reading 'content')
    at [eval]:1:35
    at runScriptInThisContext (node:internal/vm:219:10)
    at node:internal/process/execution:451:12
    at [eval]-wrapper:6:24
    at runScriptInContext (node:internal/process/execution:449:60)
    at evalFunction (node:internal/process/execution:283:30)
    at evalTypeScript (node:internal/process/execution:295:3)
    at node:internal/main/eval_string:71:3

Node.js v24.6.0

[KutnerUri]

Hi @sholladay, thanks for the discussion.

I believe the core issue stems from how this behavior interacts with chained property access, which is a very common pattern.
The current "" default creates a trap that ?. is specifically designed to prevent.

These examples illustrate the problem:

let data;

// CASE 1: The Ideal (with null)
// The ?. operator correctly protects the entire chain.

data = null;
console.log(data?.content.title);
// --> undefined (✅ Safe and predictable)

// ----------------------------------------------------

// The ky Behavior (with "")
// CASE 2: The chain breaks on a non-string property.
// The ?. fails because `data.content` is undefined.

data = "";
console.log(data?.content.title);
// --> Uncaught TypeError: Cannot read properties of undefined (reading 'title')

// CASE 3: accessing string properties
// The ?. seems to work because replace is a function and has no property "from"

data = "";
console.log(""?.replace.from);
// --> undefined (? expected - but gives a wrong sense of security)

// CASE 4: accessing non-string properties

console.log(""?.replace.from.line);
// Uncaught TypeError: Cannot read properties of undefined (reading 'line')

Empty string is a weird choice in this case - it looks like you can safely access its properties (because most are undefined), but actually, it throws if you access the wrong thing.

Returning null for a 204 response aligns with the expected behavior of optional chaining and makes the result safe and predictable.

[KutnerUri]

❯ node -e 'const foo = ""; console.log(foo?.content)'

undefined

❯  node -e 'const foo = ""; console.log(foo?.includes)'

[Function: includes]

❯ node -e 'const foo = ""; console.log(foo?.content.bob)'

[eval]:1
const foo = ""; console.log(foo?.content.bob)
                                        ^

TypeError: Cannot read properties of undefined (reading 'bob')
    at [eval]:1:41
    at runScriptInThisContext (node:internal/vm:144:10)
    at node:internal/process/execution:109:14
    at [eval]-wrapper:6:24
    at runScript (node:internal/process/execution:92:62)
    at evalScript (node:internal/process/execution:123:10)
    at node:internal/main/eval_string:51:3

Node.js v20.10.0

❯ node -e 'const foo = null; console.log(foo?.content.bob)'

undefined

[sholladay]

Can't you just move it over one position to solve this? For example, data.content?.title

But I do see your point. Maybe it is worth changing. I'll give it some thought.

[LinusU]

Personally, I think that undefined (or possibly null) would be the expected return value from .json() on a 204 response

[sholladay]

See #193 for the history of how we decided on returning an empty string in this case.

We certainly can change it, though. I think there are valid arguments either way and there seems to be a good amount of support in the community for changing to undefined.

[LinusU]

I don't feel too strongly about this, but when thinking about it more now, I actually think that I prefer it throwing an error.

My reasoning is that I don't see a situation where I would want to handle 204s without body, and 200s with json body in the same code path.

e.g. if I'm posting to create something, and I expect the server to return the created resource as json, then it would be less confusion if I got an error vs. receiving an empty string (which will probably yield a "failed to read x of undefined" error) if the server for some reason returned a 204 instead.

and if I'm expecting the server to return a 204, then I wouldn't call .json at all.

and in the third case, when I'm expecting the server to sometimes return 204, and sometimes 200 with json (e.g. 204 might mean "queued for insertion"). Then again I probably wouldn't want to rely on a special value from .json(), and instead just check the status code to decide what to do.

---

For some background, throwing an error is what the native fetch does. They refer to 204 (and some others) as "null body status".

This is what Ky used to do as well, until it was changed after discussion in #193.

---

This also raises the question on how this should interact with #730 (if we decide to implement it). If we don't throw an error on 204 when calling .json(), then what is the return value of .json(mySchema) on a 204? It could be the result of calling mySchema.parse with an empty string I suppose, but that also feels a bit unexpected...