Timestamp Converter
Relevant source files
The following files were used as context for generating this wiki page:
The Timestamp Converter, referred to in the codebase as the "Unix Timestamp Compass," is a core utility within the DevUtils suite designed to facilitate seamless conversion between various temporal representations. It allows developers to transform Unix timestamps, ISO 8601 strings, and other date formats into over 30 distinct display formats, including specialized outputs for SQL, Excel, and web protocols.
Sources: README.md:9, messages/en.json:302-304, components/tools/timestamp-converter.tsx:102-132
Architecture and Core Logic
The system is implemented as a React functional component utilizing the @tanstack/react-query or standard React hooks for state management. It relies on a centralized parsing engine that detects input types and synchronizes multiple output formats in real-time.
Parsing Engine
The component employs a parseTimestamp callback that handles three primary input patterns:
- Unix Seconds: 10-digit numeric strings (multiplied by 1000 for JavaScript Date objects).
- Unix Milliseconds: 13-digit numeric strings.
- Date Strings: Standard strings parsed via
Date.parse(), supporting ISO 8601 and RFC 2822.
Sources: components/tools/timestamp-converter.tsx:82-108
State Management Flow
The following diagram illustrates how user input triggers the transformation process and updates the multi-format display.
The application uses useEffect to synchronize the parsed date state whenever the raw string input changes, ensuring the UI remains reactive to user edits.
Sources: components/tools/timestamp-converter.tsx:112-114, components/tools/timestamp-converter.tsx:285-289
Supported Formats and Features
The tool categorizes output into standard, database-specific, and specialized formats.
Format Categories
| Category | Formats Included | Description |
|---|---|---|
| Standard | Unix, Unix MS, ISO 8601, UTC, Local | Core temporal representations. |
| SQL | sqlDateTime, sqlDate, sqlTime | Standardized strings for database queries. |
| Web/Feeds | HTTP Header, Atom, RSS, W3C, Cookie | Protocol-compliant date strings. |
| Specialized | Excel Serial, Julian Day, Quarter | Formats for data analysis and legacy systems. |
Sources: components/tools/timestamp-converter.tsx:23-53, components/tools/timestamp-converter.tsx:238-266
Relative Time Calculation
The converter includes a custom getTimeAgo function that calculates human-readable relative differences (e.g., "5 minutes ago" or "in 2 days"). It dynamically switches between past and future tense based on the sign of the millisecond difference between the parsed date and new Date().
Sources: components/tools/timestamp-converter.tsx:143-207
Integration with Cron Generator
While housed in separate components, the project integrates temporal logic through the "Cron Schedule Builder." This submodule allows users to build cron expressions that determine future execution times, complementing the static conversion of timestamps.
Implementation Details
Mathematical Conversions
For specialized formats, the component implements specific algorithms:
- Julian Day: Calculated using an astronomical formula involving year, month, and day adjustments.
- Excel Serial: Calculated based on the epoch of December 30, 1899.
- ISO Week: Implements ISO 8601 logic where Week 1 is the week containing January 4th.
Sources: components/tools/timestamp-converter.tsx:209-236
Localization
Internationalization is handled via react-i18next. The UI labels, relative time strings, and weekday names are dynamically retrieved from locale files (e.g., en.json, zh.json) to support multi-language environments.
Sources: messages/en.json:302-340, messages/zh.json:302-340, components/tools/timestamp-converter.tsx:135-141
Summary
The Timestamp Converter serves as a versatile utility within DevUtils for handling time-based data. By combining robust parsing logic with a wide array of standardized output formats and an integrated Cron generator, it addresses common developer needs for temporal data manipulation and schedule visualization.