【Node.js】qs.stringfy でvalueがundefinedのkeyはクエリ変換の際に省略されるので注意しておく

Node.jsのライブラリqsを使ってクエリ構築する時にちょっと戸惑ったのでメモ。

ライブラリのインストールはこれ

$ npm install --save @types/qs

クエリに変換する
undefined を意図してないと挙動に戸惑う
1. なんで qs.stringfy が紛らわしいか
環境
参考

クエリに変換する

JSONのオブジェクトstringfyで変換すると下記のようになる。

import qs from 'qs'; 
const query = qs.stringify({
  hogeId: 1,
  mogeId: 2,
});

const uri = `$api/v1/search?${query}`;

// api/v1/search?hogeId=1&mogeId=2

そしてJSONオブジェクトのvalueがundefinedの値を変換するとこうなる。

import qs from 'qs'; 
const query = qs.stringify({
  hogeId: 1,
  mogeId: undefined,
});

const uri = `$api/v1/search?${query}`;

// api/v1/search?hogeId=1

mogeIdのvalueはundefinedだったのでパラメータがまるごと削除されている。

undefined を意図してないと挙動に戸惑う

実際に戸惑ったコードはこんな感じ。

import qs from 'qs'; 

const query = qs.stringify({
  hogeId: 1,
  mogeIds: mogeIds?.join(','), // mogeIds: null | number[],
});

const uri = `$api/v1/search?${query}`;

// api/v1/search?hogeId=1

nullの値にオプショナルチェーン(?.)でjoin()させる。

もし、mogeIdsがnullだった場合はnullではなくてundefinedが返ることに注意。

そしてmogeIds: undefined になった場合は変換の際に省略されることを思い出す。
つまりmogeIdsがnullだった場合はmogeIdsのクエリパラメータは付与されないことになる。

なんで qs.stringfy が紛らわしいか

と、いうのもvalueがnullだった場合は変換されるから。

import qs from 'qs'; 

const query = qs.stringify({
  hogeId: 1,
  mogeIds: null
});

const uri = `$api/v1/search?${query}`;

// api/v1/search?hogeId=1&mogeIds=

単純にオプショナルチェーンとstringifyの仕様を理解しておらず、クエリパラメータが送られてこない現象にぶちあたって少し慌てふためいたりしました。