Add formatRelativeTime function

[aleclarson]

I think Radashi could use a few tiny time-specific formatting functions.

The first one would be formatRelativeTime, which formats a given number and time unit into a locale-specific relative time string, such as "6 days ago". This function leverages the Intl.RelativeTimeFormat API to ensure accurate and locale-aware formatting.

const formatRelativeTime = (
  n: number,
  unit: Intl.RelativeTimeFormatUnit,
  locale = "en"
): string =>
  new Intl.RelativeTimeFormat(locale, { numeric: "auto" }).format(-n, unit);

• Parameters:
  • n: The numeric value representing the amount of time.
  • unit: The time unit as specified by Intl.RelativeTimeFormatUnit (e.g., "day", "hour", "minute").
  • locale: Optional parameter for specifying the locale; defaults to "en" (English).

Example Usage

const result = formatRelativeTime(6, "day");
console.log(result); // Outputs: "6 days ago"

[aleclarson]

Other functions to include:

export function* timeUnits(): Generator<[number, Intl.RelativeTimeFormatUnit]> {
  yield [31536000000, 'year'];
  yield [2592000000, 'month'];
  yield [86400000, 'day'];
  yield [3600000, 'hour'];
  yield [60000, 'minute'];
  yield [1000, 'second'];
}

export function formatRelativeElapsedTime(ms: number, locale = 'en'): string {
  for (const [factor, unit] of timeUnits()) {
    if (Math.abs(ms) >= factor) {
      const value = +(ms / factor).toFixed(1);
      return new Intl.RelativeTimeFormat(locale, { numeric: 'auto' }).format(-value, unit);
    }
  }
  return new Intl.RelativeTimeFormat(locale, { numeric: 'auto' }).format(0, 'second');
}

[Minhir]

For me, it looks like too much sugar.

BTW, there is no Intl object in default build in Node.js https://nodejs.org/api/intl.html. I think we should specify radashi behavior in different environments. For utils library, the best one if it just works in all widely-used envs. So it could be a nice rule of thumb if we want to include some feature or not.

[aleclarson]

BTW, there is no Intl object in default build in Node.js nodejs.org/api/intl.html.

Interesting!

For utils library, the best one if it just works in all widely-used envs. So it could be a nice rule of thumb if we want to include some feature or not.

Node.js support is absolutely a must! If supporting both with a single implementation is suboptimal, we can always use package.json exports with a "node" condition.

{
  "exports": {
    "./time/formatIntlTimeAgo": {
      "node": "./time/formatIntlTimeAgo.node.mjs",
      "default": "./time/formatIntlTimeAgo.web.mjs"
    }
  }
}

For me, it looks like too much sugar.

You're right, but it wraps a clumsy API, so I'm on the fence. 🙃

Though formatRelativeElapsedTime is not sugar, I'd say.

[hugo082]

Having something similar to vercel/ms could be interesting, the project appears to be no longer maintained and the latest version was published 3 years ago. Some fixes on the main branch have not been released for several month now.

Here is some API examples:

ms('2 days')  // 172800000
ms('1d')      // 86400000
ms('10h')     // 36000000
ms('2.5 hrs') // 9000000

[aleclarson]

Can we assume this is only being used with a string literal input? (as opposed to dynamic user-provided input)

In cases where the value is user-provided (or loaded from a configuration file maybe), I would probably suggest using a datetime-focused library instead, for a more robust solution.

I've written up an initial exploration of the API and implementation, with compile-time type safety for string literals and options for customizing units/aliases. If you'd like to fork it and open a PR with added tests, benchmarks, and docs, you're welcome to it!

• Implementation: https://github.com/radashi-org/radashi/blob/d37af83732d45b67375b79e013d7bd87fcf72c80/src/number/parseHumanDuration.ts
  • By default, months and years are not supported, since these aren't likely to be useful in the majority of cases and they introduce ambiguity due to leap years and length differences between months.
• To fork it:

  # If you don't have Radashi forked yet:
  git clone https://github.com/radashi-org/radashi -b feat/parseHumanDuration --single-branch
  
  # If you already have a fork:
  git fetch origin feat/parseHumanDuration:feat/parseHumanDuration
  git checkout feat/parseHumanDuration

Example usage

import { parseHumanDuration as ms } from 'radashi'

ms('1.5 weeks') // 907_200_000
ms('3 days') // 259_200_000
ms('1 hour') // 3_600_000

import { defineHumanDurationParser } from 'radashi'

const parse = defineHumanDurationParser({
  units: {
    fortnight: 14 * 24 * 60 * 60 * 1000,
    day: 24 * 60 * 60 * 1000,
    hour: 60 * 60 * 1000,
  },
  short: {
    f: 'fortnight',
    d: 'day',
    h: 'hour',
  },
})

parse('2 fortnights') // 2_419_200_000
parse('3 days') // 259_200_000
parse('5h') // 18_000_000 (Alias for hours)

// TypeScript warns about invalid units:
parse('2 months')
parse('5 xyz')