@torcue/timekit

Internal Time Utility that can be used across the apps developed by Torcue. A lightweight timezone management library built on Luxon.

Installation

npm install @torcue/timekit

Features

• Convert timezone-naive date strings to UTC Date objects
• Validate and ensure UTC consistency
• Format UTC timestamps to any timezone
• Built-in error handling for invalid inputs
• TypeScript support included

Usage

import timekit from '@torcue/timekit';

// Convert a timezone-naive date string to UTC
const dateString = "2026-01-23T10:00:00";
const utcDate = timekit.stringToUTC(dateString, "Asia/Tokyo");
console.log(utcDate); // UTC Date object

// Check if a date or string is properly UTC
const isUtc = timekit.ensureUTC(utcDate);
console.log(isUtc); // true

const isUtcString = timekit.ensureUTC("2026-01-23T01:00:00Z");
console.log(isUtcString); // true

// Format UTC timestamp to specific timezone
const formatted = timekit.formatToZone(utcDate, "America/New_York");
console.log(formatted); // "01-23-2026 08:00 PM EST"

API Reference

stringToUTC(dateString: string, timeZone: string): Date

Converts a date string without timezone information to a UTC Date object by interpreting it in the specified timezone.

Parameters:

• dateString - ISO date string without timezone offset
• timeZone - IANA timezone identifier (e.g., "America/New_York", "Asia/Tokyo")

Returns: UTC Date object

Throws: Error if dateString or timeZone is invalid

ensureUTC(input: string | Date): boolean

Validates whether a Date object or ISO string represents a proper UTC timestamp.

Parameters:

• input - Date object or ISO string to validate

Returns: boolean indicating if input is valid UTC

formatToZone(utcDate: string | Date, timeZone: string): string

Converts a UTC timestamp to a formatted string in the target timezone.

Parameters:

• utcDate - UTC Date object or ISO string
• timeZone - Target timezone identifier

Returns: Formatted date string in target timezone (default: "MM-dd-yyyy hh:mm a ZZZZ")

Throws: Error if date or timezone is invalid

Dependencies

• Luxon v3.7.2

License

ISC