Textual Time Period Converter

3.0.2 · active · verified Tue Apr 21

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.

Common errors

```
ERR_PACKAGE_PATH_NOT_EXPORTED
```
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.

fix Update Node.js to 20.19.0 or newer. If using TypeScript, set `moduleResolution` to `node16`, `nodenext`, or `bundler` in your `tsconfig.json`.
```
TypeError: toTime is not a function
```
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.

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.

Warnings

breaking 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.
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.
gotcha 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.
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.
gotcha `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.
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)`.

Install

npm install to-time npm
yarn add to-time yarn
pnpm add to-time pnpm

Imports

toTime
wrong:
```
const toTime = require('to-time');
```
correct:
```
import toTime from 'to-time';
```
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.
toTime
wrong:
```
import toTime from 'to-time';
```
correct:
```
const toTime = require('to-time');
```
Use this for CommonJS modules (e.g., typical Node.js projects without `type: "module"` in `package.json`).
toTime
```
<script src="node_modules/to-time/lib/to-time.min.js"></script>

```
For browser environments without a bundler, the UMD build exposes `toTime` globally. `bignumber.js` is bundled into this file.

Quickstart

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`.

import toTime from 'to-time';

// Example 1: Parsing a textual time period and getting total days
// Converts "1 year and 6 months" to total days, demonstrating precision.
const daysInYearAndHalf = toTime('1 Year 6 Months').days();
console.log(`Days in 1 year and 6 months: ${daysInYearAndHalf}`);
// Expected output: Days in 1 year and 6 months: 547.5

// Example 2: Using factory methods for clearer time intervals in milliseconds
const twelveHoursInMs = toTime.fromHours(12).ms();
console.log(`12 hours in milliseconds: ${twelveHoursInMs}`);
// Expected output: 12 hours in milliseconds: 43200000

// Using it with setInterval/setTimeout for clear, human-readable delays.
// Simulate an action after 1.5 hours without blocking.
console.log('Simulating an action scheduled after 1.5 hours...');
setTimeout(() => {
  console.log('Action performed after 1.5 hours.');
}, toTime.fromHours(1.5).ms());

// Example 3: Combining parsing, appending units, and humanizing the output
const combinedTime = toTime('2 days 3 hours').addMinutes(90).humanize();
console.log(`Combined time (2 days, 3 hours + 90 minutes) humanized: ${combinedTime}`);
// Expected output: Combined time (2 days, 3 hours + 90 minutes) humanized: 2 days, 4 hours, 30 minutes

view raw JSON →