はじめに (対象読者・この記事でわかること)

この記事は、TypeScriptの基本的な文法を理解している開発者を対象にしています。JavaScriptでのプログラミング経験がある方で、日付や時間を扱うアプリケーション開発に興味がある方にもおすすめです。

この記事を読むことで、TypeScriptでUNIX時間を取得する方法、UNIX時間とDateオブジェクトの相互変換方法、時間の計算やフォーマット変換の実装方法を学べます。また、実用的な時間処理のベストプラクティスや、より高度な時間操作ライブラリの活用方法についても理解できます。

前提知識

この記事を読み進める上で、以下の知識があるとスムーズです。 - TypeScriptの基本的な文法と型システムの理解 - JavaScriptの基本的な知識 - Node.jsの基本的な環境構築経験 - コマンドライン操作の基礎知識

UNIX時間とは：概要と背景

UNIX時間とは、1970年1月1日00:00:00 UTC（協定世界時）からの経過秒数を指すタイムスタンプです。コンピュータシステムでは、時間を表現するための標準的なフォーマットとして広く利用されています。特にサーバーサイドのアプリケーション開発では、データベースに時間情報を保存したり、APIの応答にタイムスタンプを含めたりする場面で頻繁に使用されます。

TypeScriptはJavaScriptのスーパーセットとして、型安全なコードを記述できるため、時間処理においても型チェックによる恩恵を受けられます。本記事では、TypeScriptでUNIX時間を効果的に扱うための基本的な方法から実践的なテクニックまでを網羅的に解説します。

TypeScriptでのUNIX時間操作：具体的な実装方法

ステップ1：UNIX時間の取得

TypeScript/JavaScriptで現在のUNIX時間を取得するには、DateオブジェクトのgetTime()メソッドやDate.now()関数を使用します。これらはミリ秒単位の値を返すため、1000で割って秒単位に変換する必要があります。

Typescript

// 現在のUNIX時間（秒単位）を取得
const currentUnixTime = Math.floor(Date.now() / 1000);

// またはDateオブジェクトを使用
const now = new Date();
const currentUnixTime2 = Math.floor(now.getTime() / 1000);

console.log(`現在のUNIX時間: ${currentUnixTime}`);

また、Node.js環境ではprocessオブジェクトからも取得できます：

Typescript

// Node.js環境でのUNIX時間取得
const nodeUnixTime = Math.floor(process.uptime());

ステップ2：UNIX時間とDateオブジェクトの相互変換

UNIX時間をDateオブジェクトに変換するには、コンストラクタに秒単位の値を1000倍して渡します：

Typescript

// UNIX時間をDateオブジェクトに変換
const unixTime = 1672531200; // 2023年1月1日00:00:00 UTC
const date = new Date(unixTime * 1000);

console.log(date.toString()); // "Mon Jan 01 2023 00:00:00 GMT+0000 (Coordinated Universal Time)"

逆に、DateオブジェクトをUNIX時間に変換するには、getTime()メソッドを使用します：

Typescript

// DateオブジェクトをUNIX時間に変換
const date = new Date();
const unixTime = Math.floor(date.getTime() / 1000);

console.log(unixTime);

ステップ3：時間のフォーマット変換

UNIX時間から特定のフォーマットの日付文字列に変換するには、Dateオブジェクトのメソッドを使用します：

Typescript

function formatDate(unixTime: number, format: string): string {
  const date = new Date(unixTime * 1000);

  // YYYY-MM-DD形式
  const year = date.getFullYear();
  const month = String(date.getMonth() + 1).padStart(2, '0');
  const day = String(date.getDate()).padStart(2, '0');

  // HH:MM:SS形式
  const hours = String(date.getHours()).padStart(2, '0');
  const minutes = String(date.getMinutes()).padStart(2, '0');
  const seconds = String(date.getSeconds()).padStart(2, '0');

  return format
    .replace('YYYY', year)
    .replace('MM', month)
    .replace('DD', day)
    .replace('HH', hours)
    .replace('mm', minutes)
    .replace('SS', seconds);
}

const unixTime = 1672531200;
console.log(formatDate(unixTime, 'YYYY-MM-DD HH:mm:ss')); // "2023-01-01 00:00:00"

ステップ4：時間の計算

UNIX時間を使った時間の計算も簡単に行えます：

Typescript

// 現在の時間から1日後のUNIX時間を計算
const now = Math.floor(Date.now() / 1000);
const oneDayLater = now + (24 * 60 * 60);

// 1時間前のUNIX時間を計算
const oneHourAgo = now - (60 * 60);

// 2週間後のUNIX時間を計算
const twoWeeksLater = now + (14 * 24 * 60 * 60);

ステップ5：タイムゾーンの考慮

タイムゾーンを考慮した処理が必要な場合は、以下のように実装します：

Typescript

// UTC時間とローカル時間の変換
function convertTimezone(unixTime: number, fromTimezone: string, toTimezone: string): number {
  const date = new Date(unixTime * 1000);

  // タイムゾーンオフセットの計算（簡易的な実装）
  const fromOffset = getTimezoneOffset(fromTimezone);
  const toOffset = getTimezoneOffset(toTimezone);

  // タイムゾーンを考慮した時間の計算
  const convertedTime = unixTime + (fromOffset - toOffset);

  return convertedTime;
}

// タイムゾーンオフセットの取得（簡易的な実装）
function getTimezoneOffset(timezone: string): number {
  // 実際の実装ではタイムゾーンデータベースやライブラリを使用
  // ここでは例として固定値を返す
  const offsets: Record<string, number> = {
    'UTC': 0,
    'JST': 9 * 60, // 日本標準時
    'EST': -5 * 60, // 東部標準時
    'PST': -8 * 60, // 太平洋標準時
  };

  return offsets[timezone] || 0;
}

// 使用例
const jstTime = 1672531200; // 2023/01/01 00:00:00 JST
const utcTime = convertTimezone(jstTime, 'JST', 'UTC');
console.log(`JST ${jstTime} → UTC ${utcTime}`);

ステップ6：ライブラリの活用

より高度な時間操作が必要な場合は、専用のライブラリを使用すると便利です。date-fnsやmoment-timezoneなどのライブラリが人気です：

date-fnsを使用した例

まず、ライブラリをインストールします：

Bash

npm install date-fns

次に、使用します：

Typescript

import { format, addDays, subHours, parseISO } from 'date-fns';

// 現在のUNIX時間を取得
const now = Math.floor(Date.now() / 1000);

// UNIX時間をフォーマット
const formatted = format(now * 1000, 'yyyy-MM-dd HH:mm:ss');
console.log(formatted);

// 時間の計算
const tomorrow = addDays(now * 1000, 1);
console.log(format(tomorrow, 'yyyy-MM-dd HH:mm:ss'));

// 時間の減算
const twoHoursAgo = subHours(now * 1000, 2);
console.log(format(twoHoursAgo, 'yyyy-MM-dd HH:mm:ss'));

moment-timezoneを使用した例

まず、ライブラリをインストールします：

Bash

npm install moment-timezone

次に、使用します：

Typescript

import moment from 'moment-timezone';

// 現在のUNIX時間を取得
const now = Math.floor(Date.now() / 1000);

// UNIX時間をフォーマット
const formatted = moment.unix(now).format('YYYY-MM-DD HH:mm:ss');
console.log(formatted);

// タイムゾーンの変換
const jstTime = moment.unix(now).tz('Asia/Tokyo').format('YYYY-MM-DD HH:mm:ss');
console.log(`JST時間: ${jstTime}`);

const estTime = moment.unix(now).tz('America/New_York').format('YYYY-MM-DD HH:mm:ss');
console.log(`EST時間: ${estTime}`);

ハマった点やエラー解決

問題1：ミリ秒と秒の混同

UNIX時間は秒単位で扱われることが多いですが、JavaScriptのDateオブジェクトは内部でミリ秒単位で時間を保持しています。この混同によって、時間が1000倍ずれたり、逆に1/1000になったりする問題が発生します。

Typescript

// 誤り：ミリ秒と秒を混同
const now = Date.now(); // ミリ秒単位
const incorrectUnixTime = now; // ミリ秒のまま

解決策

ミリ秒と秒を明確に区別し、必要に応じて変換を行います：

Typescript

// 正しい：ミリ秒と秒を明確に区別
const nowMs = Date.now(); // ミリ秒単位
const nowSec = Math.floor(nowMs / 1000); // 秒単位

// 秒単位のUNIX時間をDateオブジェクトに変換
const dateFromSec = new Date(unixTime * 1000);

// ミリ秒単位のUNIX時間をDateオブジェクトに変換
const dateFromMs = new Date(unixTimeMs);

問題2：タイムゾーンの誤解

サーバーとクライアントでタイムゾーンが異なる場合、時間表示がずれてしまう問題が発生します。特に、UTCとローカル時間の混同が原因です。

Typescript

// 誤り：タイムゾーンを考慮していない
const serverTime = new Date(); // サーバーのタイムゾーンで解釈される

解決策

時間データを保存する際はUTCで統一し、表示する際にのみタイムゾーンを変換します：

Typescript

// 正しい：UTCで統一
// サーバー側：UTCで保存
const nowUtc = new Date().toISOString(); // ISO 8601形式のUTC時間

// クライアント側：タイムゾーンを変換して表示
function displayTime(utcString: string, timezone: string): string {
  const date = new Date(utcString);
  return date.toLocaleString('ja-JP', { timeZone: timezone });
}

console.log(displayTime(nowUtc, 'Asia/Tokyo')); // 日本時間で表示

問題3：夏時間の考慮

夏時間（DST: Daylight Saving Time）を採用している地域では、時間が繰り返されたり、飛ばされたりします。これにより、計算が不正確になることがあります。

解決策

タイムゾーンを明示的に指定し、moment-timezoneのようなタイムゾーンに対応したライブラリを使用します：

Typescript

import moment from 'moment-timezone';

// 夏時間を考慮した時間計算
const date = moment.tz('2023-03-12 01:30:00', 'America/New_York');
const nextHour = date.add(1, 'hour');
console.log(nextHour.format()); // 夏時間の影響で03:30になる可能性がある

まとめ

本記事では、TypeScriptでUNIX時間を取得、変換、操作する方法を解説しました。主なポイントは以下の通りです：

  • TypeScriptでUNIX時間を取得するにはDate.now()やDateオブジェクトを使用
  • UNIX時間とDateオブジェクトの相互変換には1000倍/1000で除算
  • 時間のフォーマット変換にはDateオブジェクトのメソッドを活用
  • 時間の計算は単純な四則演算で可能
  • タイムゾーンの考慮にはmoment-timezoneなどのライブラリが便利
  • ミリ秒と秒の混同、タイムゾーンの誤解には注意

この記事を通して、読者はTypeScriptで時間を効果的に扱うための実用的な知識を得られたはずです。今後は、より高度な時間処理や、特定のフレームワークでの時間操作についても記事にする予定です。

参考資料