Microsecond Time Utility

0.2.0 · abandoned · verified Tue Apr 21

The `microseconds` package provides a utility to generate and parse timestamps with microsecond precision. It currently stands at version 0.2.0, with its last update occurring approximately six years ago (December 2019). This indicates that the package is no longer actively maintained. It intelligently adapts to the execution environment, utilizing `process.hrtime` for high-resolution timing in Node.js and `performance.now()` in browsers. If neither is available, it falls back to `Date.now() * 1000` for a lower-resolution microsecond timestamp. Key functionalities include `μs.now()` for current microsecond timestamps, `μs.parse()` to convert a microsecond value into a structured object or human-readable string, and `μs.since()` to calculate elapsed time. Due to its abandoned status, developers should consider more modern and actively maintained alternatives for critical applications requiring robust time precision.

Common errors

```
TypeError: microseconds is not a function
```
cause Attempting to `import μs from 'microseconds'` in an ESM module, or incorrectly destructuring a CommonJS module that exports a single function/object.

fix Use the correct CommonJS `require` syntax: `const μs = require('microseconds')`.
```
SyntaxError: Cannot use import statement outside a module
```
cause Trying to use `import μs from 'microseconds'` in a Node.js script that is interpreted as CommonJS (e.g., a `.js` file without `"type": "module"` in `package.json`).

fix Either convert your project to an ES module (by adding `"type": "module"` to `package.json` and potentially refactoring other `require`s) or revert to the CommonJS `require()` statement for this package: `const μs = require('microseconds')`.

Warnings

breaking This package is no longer maintained. It was last published over six years ago, meaning it does not receive updates for new Node.js versions, browser API changes, or security fixes. Users should be aware of potential compatibility issues or unaddressed vulnerabilities.
Fix: Consider migrating to actively maintained alternatives like `precise-now` or `microtime` (by wadey) for high-resolution timing, which offer better compatibility and ongoing support.
gotcha The package is CommonJS-only. Attempting to use ESM `import` syntax (`import μs from 'microseconds'`) directly in a pure ES module environment will result in errors.
Fix: Ensure your project is configured for CommonJS, or use `require()` within an ESM module (e.g., `import { createRequire } from 'module'; const require = createRequire(import.meta.url); const μs = require('microseconds');`) or use a bundler that handles CJS-to-ESM conversion.
gotcha Precision and resolution can vary across environments. While it attempts to use high-resolution timers (`hrtime`, `performance.now`), it falls back to `Date.now() * 1000` if those are unavailable. This fallback significantly reduces actual microsecond precision.
Fix: Always test the actual resolution in your target environment. For critical applications, ensure the high-resolution timers are indeed available and not falling back to lower precision.

Install

npm install microseconds npm
yarn add microseconds yarn
pnpm add microseconds pnpm

Imports

μs
wrong:
```
import μs from 'microseconds'
```
correct:
```
const μs = require('microseconds')
```
This package is CommonJS-only. Attempting to use ESM `import` syntax will likely fail or require transpilation/configuration in modern JavaScript environments.
μs.now
```
const now = μs.now()
```
The `now()` method is directly available on the default CommonJS export to get a microsecond timestamp.
μs.parse
```
const parsed = μs.parse(timestamp)
```
The `parse()` method takes a microsecond timestamp and returns an object or a human-readable string representation via `toString()`.

Quickstart

Demonstrates generating current microsecond timestamps, calculating elapsed time, and parsing microsecond values into structured objects and human-readable strings.

const μs = require('microseconds');

// Get current timestamp in microseconds
const now = μs.now();
console.log(`Current microseconds: ${now}`);
// Example output: Current microseconds: 1713540843123456

// Simulate some work
for (let i = 0; i < 10000; i++) {
  Math.sin(i);
}

// Get time elapsed since 'now'
const elapsed = μs.since(now);
console.log(`Time elapsed (microseconds): ${elapsed}`);
// Example output: Time elapsed (microseconds): 12345

// Parse a microsecond value into an object
const parsed = μs.parse(123456789123456);
console.log('Parsed object:', parsed);
// Example output: Parsed object: { microseconds: 456, milliseconds: 123, seconds: 89, minutes: 23, hours: 14, days: 1428 }

// Convert parsed object to a human-readable string
console.log('Parsed string:', parsed.toString());
// Example output: Parsed string: 1428 days 14 hours 23 minutes 89 seconds 123 milliseconds 456 microseconds

// Parse a smaller value
console.log(μs.parse(5000).toString()); // 5 milliseconds
console.log(μs.parse(1).toString());   // 1 microsecond

view raw JSON →