hh-mm-ss Time Formatting Utility

1.2.0 · maintenance · verified Tue Apr 21

The `hh-mm-ss` package provides a lightweight and focused utility for converting time representations between numerical values (seconds or milliseconds) and formatted strings like `hh:mm:ss`. Currently stable at version `1.2.0`, the library appears to have a conservative release cadence, with updates primarily focused on adding new format support and convenience methods incrementally, rather than frequent major changes. Its core differentiator lies in its specialization, offering a simpler alternative to larger, more comprehensive date-time libraries by focusing solely on common `hh:mm:ss` patterns and handling ambiguities with optional format parameters. It supports various time string patterns, including `mm:ss`, `hh:mm`, `hh:mm:ss`, and their millisecond-inclusive variants like `mm:ss.sss`, with a mechanism to automatically extend output formats to preserve precision when milliseconds are present.

Common errors

```
ReferenceError: require is not defined
```
cause Attempting to use `require()` to import the `hh-mm-ss` package within a JavaScript file that is being interpreted as an ES Module (e.g., due to `"type": "module"` in `package.json` or an `.mjs` extension).

fix Change the import statement to use ESM syntax: `import TimeFormat from 'hh-mm-ss';`. If using TypeScript, ensure `tsconfig.json`'s `moduleResolution` is set appropriately (e.g., `node16` or `nodenext`).
```
TypeError: TimeFormat.toS is not a function
```
cause This error typically occurs if the `TimeFormat` object was not correctly imported, or if an incorrect import pattern was used (e.g., trying to destructure a default export as a named export like `import { toS } from 'hh-mm-ss'`).

fix Ensure `TimeFormat` is imported as a default export: `import TimeFormat from 'hh-mm-ss';` for ESM, or `const TimeFormat = require('hh-mm-ss');` for CommonJS. Then access methods via the imported object, e.g., `TimeFormat.toS(...)`.
```
Incorrect time conversion, e.g., `TimeFormat.toS('02:00')` returns 120 (2 minutes) but 7200 (2 hours) was expected.
```
cause The input format was ambiguous, and the library defaulted to `mm:ss` when `hh:mm` was the intended format.

fix Explicitly specify the input format when calling the conversion function: `TimeFormat.toS('02:00', 'hh:mm')`. Similarly, for `fromS` or `fromMs`, specify the desired output format.

Warnings

gotcha The `toS`, `toMs`, `fromS`, and `fromMs` functions implicitly default to the `mm:ss` format if no `format` parameter is provided. This can lead to incorrect conversions if the input string or desired output should be interpreted as `hh:mm` or `hh:mm:ss`.
Fix: Always explicitly provide the `format` parameter (e.g., `TimeFormat.toS('02:00', 'hh:mm')`) to prevent ambiguous interpretations and ensure correct conversion.
gotcha When using `fromMs` with output formats that do not explicitly include milliseconds (e.g., `mm:ss`), the library will automatically extend the format to `mm:ss.sss` if the millisecond component is non-zero. This ensures precision but might result in an unexpected output string length or format if strict `mm:ss` output is required.
Fix: If a strictly limited output format is necessary (e.g., exactly `mm:ss`), round or truncate the input milliseconds (`ms`) before passing them to `fromMs`. Alternatively, handle the extended output format in your downstream logic.
gotcha This package is primarily distributed as a CommonJS module. While modern Node.js environments and bundlers can often handle importing CommonJS modules into ESM projects, direct `require()` calls will fail in pure ES Module contexts (`"type": "module"` in `package.json` or `.mjs` files).
Fix: In ES Module projects, use the ESM import syntax: `import TimeFormat from 'hh-mm-ss';`. Ensure your build tools are configured to correctly transpile or resolve CommonJS modules for browser or other specialized environments.

Install

npm install hh-mm-ss npm
yarn add hh-mm-ss yarn
pnpm add hh-mm-ss pnpm

Imports

TimeFormat
wrong:
```
import { TimeFormat } from 'hh-mm-ss'
```
correct:
```
import TimeFormat from 'hh-mm-ss'
```
This package is primarily CommonJS; use a default import for ESM consumption of the main utility object.
TimeFormat
```
const TimeFormat = require('hh-mm-ss')
```
Standard CommonJS import pattern.
toS
wrong:
```
import { toS } from 'hh-mm-ss'
```
correct:
```
import TimeFormat from 'hh-mm-ss'; TimeFormat.toS(...)
```
Individual functions like `toS` are methods on the `TimeFormat` object, not direct named exports, as the package is a CommonJS default export.

Quickstart

Demonstrates converting various time string formats to seconds and milliseconds, and vice-versa, using explicit format parameters to avoid ambiguity.

import TimeFormat from 'hh-mm-ss';

// Convert formatted strings to seconds
console.log('137:00:00 to seconds:', TimeFormat.toS('137:00:00'));            // Expected: 493200
console.log('02:00 (mm:ss default) to seconds:', TimeFormat.toS('02:00'));    // Expected: 120 (2 minutes)
console.log('02:00 (hh:mm specified) to seconds:', TimeFormat.toS('02:00', 'hh:mm')); // Expected: 7200 (2 hours)

// Convert seconds to formatted strings
console.log('194 seconds to mm:ss:', TimeFormat.fromS(194));                 // Expected: '03:14'
console.log('150 seconds to hh:mm:ss:', TimeFormat.fromS(150, 'hh:mm:ss'));  // Expected: '00:02:30'
console.log('8100 seconds to hh:mm:', TimeFormat.fromS(8100, 'hh:mm'));      // Expected: '02:15'

// Convert milliseconds to formatted strings
console.log('12345 ms to mm:ss.sss:', TimeFormat.fromMs(12345));             // Expected: '00:12.345'

view raw JSON →