to-time

library3.0.2jsnpmunverified

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.

serialization data

npm install to-time

github ↗package ↗

INSTALL

IMPORT

SIG · TO-TIME

to-time

serializationjavascriptv3.0.2

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

toTime

✓ import toTime from 'to-time';

✗ const toTime = require('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

✓ const toTime = require('to-time');

✗ import toTime from '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.

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

Debug

Known issues

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

affects: >=3.0.0

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

affects: >=3.0.0

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

affects: >=1.0.0

Errors

Common errors & fixes

ERR_PACKAGE_PATH_NOT_EXPORTED

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

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.

Upgrade

Version history

3.0.2latest on npm

Audit

Dependencies

bignumber.jsrequiredUsed internally for high-precision arithmetic to avoid floating-point errors in time calculations. Bundled in UMD builds, but a runtime dependency for other environments.

Agent activity

21 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/hafuta/to-time ↗

packagehttps://www.npmjs.com/package/to-time ↗