{"id":15120,"library":"hh-mm-ss","title":"hh-mm-ss Time Formatting Utility","description":"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.","status":"maintenance","version":"1.2.0","language":"javascript","source_language":"en","source_url":"https://github.com/Goldob/hh-mm-ss","tags":["javascript","time format","hours","minutes","seconds","miliseconds","hh:mm:ss"],"install":[{"cmd":"npm install hh-mm-ss","lang":"bash","label":"npm"},{"cmd":"yarn add hh-mm-ss","lang":"bash","label":"yarn"},{"cmd":"pnpm add hh-mm-ss","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"This package is primarily CommonJS; use a default import for ESM consumption of the main utility object.","wrong":"import { TimeFormat } from 'hh-mm-ss'","symbol":"TimeFormat","correct":"import TimeFormat from 'hh-mm-ss'"},{"note":"Standard CommonJS import pattern.","symbol":"TimeFormat","correct":"const TimeFormat = require('hh-mm-ss')"},{"note":"Individual functions like `toS` are methods on the `TimeFormat` object, not direct named exports, as the package is a CommonJS default export.","wrong":"import { toS } from 'hh-mm-ss'","symbol":"toS","correct":"import TimeFormat from 'hh-mm-ss'; TimeFormat.toS(...)"}],"quickstart":{"code":"import TimeFormat from 'hh-mm-ss';\n\n// Convert formatted strings to seconds\nconsole.log('137:00:00 to seconds:', TimeFormat.toS('137:00:00'));            // Expected: 493200\nconsole.log('02:00 (mm:ss default) to seconds:', TimeFormat.toS('02:00'));    // Expected: 120 (2 minutes)\nconsole.log('02:00 (hh:mm specified) to seconds:', TimeFormat.toS('02:00', 'hh:mm')); // Expected: 7200 (2 hours)\n\n// Convert seconds to formatted strings\nconsole.log('194 seconds to mm:ss:', TimeFormat.fromS(194));                 // Expected: '03:14'\nconsole.log('150 seconds to hh:mm:ss:', TimeFormat.fromS(150, 'hh:mm:ss'));  // Expected: '00:02:30'\nconsole.log('8100 seconds to hh:mm:', TimeFormat.fromS(8100, 'hh:mm'));      // Expected: '02:15'\n\n// Convert milliseconds to formatted strings\nconsole.log('12345 ms to mm:ss.sss:', TimeFormat.fromMs(12345));             // Expected: '00:12.345'","lang":"javascript","description":"Demonstrates converting various time string formats to seconds and milliseconds, and vice-versa, using explicit format parameters to avoid ambiguity."},"warnings":[{"fix":"Always explicitly provide the `format` parameter (e.g., `TimeFormat.toS('02:00', 'hh:mm')`) to prevent ambiguous interpretations and ensure correct conversion.","message":"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`.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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).","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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`).","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).","error":"ReferenceError: require is not defined"},{"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(...)`.","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'`).","error":"TypeError: TimeFormat.toS is not a function"},{"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.","cause":"The input format was ambiguous, and the library defaulted to `mm:ss` when `hh:mm` was the intended format.","error":"Incorrect time conversion, e.g., `TimeFormat.toS('02:00')` returns 120 (2 minutes) but 7200 (2 hours) was expected."}],"ecosystem":"npm"}