{"id":16245,"library":"to-time","title":"Textual Time Period Converter","description":"to-time is a JavaScript/TypeScript utility for parsing and converting textual time periods (e.g., \"1 hour\", \"1y 365d 4h\") into various standard time units such as milliseconds, seconds, minutes, hours, days, weeks, and years. The current stable version is 3.0.2, with recent minor and patch releases indicating active development. A key differentiator of to-time is its internal reliance on the `bignumber.js` library to perform arithmetic operations, ensuring high precision and mitigating common floating-point inaccuracies often encountered in time calculations. The package supports dual CommonJS and ESM builds through an `exports` map, providing native compatibility for modern Node.js environments (requiring Node.js 20.19+). It also ships with comprehensive TypeScript types, facilitating robust development. The library offers both a primary parsing function and a suite of static factory methods (`fromMilliseconds`, `fromHours`) for initialization, alongside fluent appender methods (`addMinutes`, `addYears`) for manipulating time frames.","status":"active","version":"3.0.2","language":"javascript","source_language":"en","source_url":"https://github.com/hafuta/to-time","tags":["javascript","typescript"],"install":[{"cmd":"npm install to-time","lang":"bash","label":"npm"},{"cmd":"yarn add to-time","lang":"bash","label":"yarn"},{"cmd":"pnpm add to-time","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Used internally for high-precision arithmetic to avoid floating-point errors in time calculations. Bundled in UMD builds, but a runtime dependency for other environments.","package":"bignumber.js","optional":false}],"imports":[{"note":"Use this for ES Modules (e.g., `type: \"module\"` in `package.json` or `.mjs` files). This is the primary import for modern JavaScript and TypeScript projects.","wrong":"const toTime = require('to-time');","symbol":"toTime","correct":"import toTime from 'to-time';"},{"note":"Use this for CommonJS modules (e.g., typical Node.js projects without `type: \"module\"` in `package.json`).","wrong":"import toTime from 'to-time';","symbol":"toTime","correct":"const toTime = require('to-time');"},{"note":"For browser environments without a bundler, the UMD build exposes `toTime` globally. `bignumber.js` is bundled into this file.","symbol":"toTime","correct":"<script src=\"node_modules/to-time/lib/to-time.min.js\"></script>\n<!-- exposes global: window.toTime -->"}],"quickstart":{"code":"import toTime from 'to-time';\n\n// Example 1: Parsing a textual time period and getting total days\n// Converts \"1 year and 6 months\" to total days, demonstrating precision.\nconst daysInYearAndHalf = toTime('1 Year 6 Months').days();\nconsole.log(`Days in 1 year and 6 months: ${daysInYearAndHalf}`);\n// Expected output: Days in 1 year and 6 months: 547.5\n\n// Example 2: Using factory methods for clearer time intervals in milliseconds\nconst twelveHoursInMs = toTime.fromHours(12).ms();\nconsole.log(`12 hours in milliseconds: ${twelveHoursInMs}`);\n// Expected output: 12 hours in milliseconds: 43200000\n\n// Using it with setInterval/setTimeout for clear, human-readable delays.\n// Simulate an action after 1.5 hours without blocking.\nconsole.log('Simulating an action scheduled after 1.5 hours...');\nsetTimeout(() => {\n  console.log('Action performed after 1.5 hours.');\n}, toTime.fromHours(1.5).ms());\n\n// Example 3: Combining parsing, appending units, and humanizing the output\nconst combinedTime = toTime('2 days 3 hours').addMinutes(90).humanize();\nconsole.log(`Combined time (2 days, 3 hours + 90 minutes) humanized: ${combinedTime}`);\n// Expected output: Combined time (2 days, 3 hours + 90 minutes) humanized: 2 days, 4 hours, 30 minutes\n","lang":"typescript","description":"This quickstart demonstrates parsing time strings, using factory methods to create `TimeFrame` instances, chaining appender methods, and retrieving values in various units, including human-readable formats. It highlights practical usage for setting time-based operations like `setTimeout`."},"warnings":[{"fix":"Upgrade Node.js to 20.19.0 or higher. For TypeScript, ensure `moduleResolution` is set to `node16`, `nodenext`, or `bundler` in `tsconfig.json`. Verify your bundler (e.g., Webpack, Rollup) is configured to correctly resolve `package.json` `exports` fields.","message":"Version 3.0.0 introduced a dual CommonJS/ESM build strategy with an `exports` map in `package.json`. Projects on older Node.js versions (below 20.19.0) or with outdated bundler configurations may experience import resolution issues.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Ensure your Node.js development and deployment environments meet the minimum requirement of 20.19.0. Tools like `nvm` (Node Version Manager) can help manage multiple Node.js versions efficiently.","message":"This package explicitly requires Node.js version 20.19.0 or higher, as specified in its `engines` field. Running `to-time` on older Node.js versions may lead to runtime errors, incorrect module resolution, or unexpected behavior, especially due to the v3 `exports` map implementation.","severity":"gotcha","affected_versions":">=3.0.0"},{"fix":"Be aware that the output of getter methods is always a `Number`. If `BigInt` precision is required after `to-time` calculations, explicitly convert the `Number` result to `BigInt` using `BigInt(value)`.","message":"`to-time` leverages `bignumber.js` internally to guarantee high precision for all time calculations, mitigating floating-point inaccuracies. However, all getter methods (e.g., `ms()`, `seconds()`, `hours()`) return standard JavaScript `Number` types, not `BigInt` or `BigNumber` objects. Developers requiring `BigInt` precision for subsequent operations must manually convert the `Number` result.","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":"Update Node.js to 20.19.0 or newer. If using TypeScript, set `moduleResolution` to `node16`, `nodenext`, or `bundler` in your `tsconfig.json`.","cause":"Node.js (or a bundler) failed to resolve the `to-time` package due to its `exports` map, often indicating an older Node.js version or incorrect module resolution configuration.","error":"ERR_PACKAGE_PATH_NOT_EXPORTED"},{"fix":"If your `package.json` has `\"type\": \"module\"` or it's an `.mjs` file, use `import toTime from 'to-time';`. If it's a CommonJS module (no `\"type\": \"module\"` and a `.js` file), use `const toTime = require('to-time');`. For browsers without a bundler, ensure `to-time.min.js` is loaded via a script tag.","cause":"Attempting to use `toTime` after importing it incorrectly for the module context (e.g., `require` in an ESM file or `import` in a CJS file), or accessing the global `toTime` without the UMD build being loaded.","error":"TypeError: toTime is not a function"}],"ecosystem":"npm"}