導入
JavaScriptで日時を扱う際、Dateオブジェクトの操作は避けて通れません。特に「特定の時刻から数秒進めたい」「秒数を00にリセットしたい」といった要件は、タイマー処理やログの生成などで頻繁に発生します。Date.prototype.setSecondsは、日付オブジェクトの「秒」を直接操作するためのメソッドですが、使い方を誤ると予期せぬ日付の繰り上がりが発生し、バグの温床になります。本記事では、このAPIを安全に使いこなすための勘所を解説します。
基礎知識
Date.prototype.setSeconds()は、Dateインスタンスの秒数を設定するメソッドです。引数には「0から59」までの整数を指定するのが基本ですが、実は「60以上」を指定することも可能です。その場合、自動的に「分」や「時」が繰り上がります。例えば、秒に「70」を指定すると、自動的に「1分10秒」として計算されます。この仕様は便利ですが、意図せず日付が変わってしまう可能性があるため、理解しておく必要があります。
実装/解決策
実務では、単に秒を設定するだけでなく、同時に「ミリ秒」をゼロにリセットするケースが非常に多いです。正確な時刻の比較や、特定のキリが良いタイミングでイベントを発火させたい場合、ミリ秒が残っていると微妙な誤差が生じるためです。setSecondsは第2引数でミリ秒を指定できるため、明示的に「0」を指定する癖をつけるのが推奨されます。
サンプルプログラム
以下のコードは、現在時刻の「秒」を0にし、ミリ秒も切り捨てて「整った時刻」を取得する実用例です。
// 現在の日時を取得
const now = new Date();
// 秒を0に設定し、同時にミリ秒も0にリセットする
// 第1引数: 秒 (0)
// 第2引数: ミリ秒 (0)
now.setSeconds(0, 0);
console.log("調整後の時刻:", now.toISOString());
// 応用: 65秒を指定するとどうなるか？
const future = new Date();
future.setSeconds(65);
// 1分5秒後として計算されるため、分が繰り上がります
console.log("65秒加算後の時刻:", future.toISOString());
応用・注意点
現場で最も注意すべき点は「Dateオブジェクトのミュータブル（書き換え可能）な性質」です。setSecondsを実行すると、元のDateオブジェクト自体が変更されます。もし元の時刻を保持しておきたい場合は、必ず `const newDate = new Date(originalDate.getTime());` のように複製してから操作してください。
また、タイムゾーンの問題も無視できません。setSecondsはローカル環境のタイムゾーンに基づいて計算されます。サーバー側の時刻（UTC）を操作したい場合は、必ず `setUTCSeconds()` を使用してください。これを混同すると、サマータイムやサーバーの環境依存による不可解な時刻のズレが発生します。仕様書やログ生成などで時刻を扱う際は、常に「UTC基準か、ローカル基準か」を意識することが、トラブルを未然に防ぐ鍵となります。