Skip to content

⬅️ Back to Table of Contents

📄 useTimeAgoIntl

📊 Analysis Summary

Metric Count
🔧 Functions 4
📦 Imports 9
📊 Variables & Constants 1
🟢 Vue Composition API 3
📐 Interfaces 3
📑 Type Aliases 2

📚 Table of Contents

🛠️ File Location:

📂 packages/core/useTimeAgoIntl/index.ts

📦 Imports

Name Source
AnyFn @vueuse/shared
Pausable @vueuse/shared
ComputedRef vue
MaybeRefOrGetter vue
ConfigurableScheduler ../_configurable
useIntervalFn @vueuse/shared
computed vue
toValue vue
useNow ../useNow

Variables & Constants

Name Type Kind Value Exported
UNITS TimeAgoUnit[] const [ { name: 'year', ms: 31_536_000_000 }, { name: 'month', ms: 2_592_000_000 },... ✗

Vue Composition API

Name Type Reactive Variables Composables
computed computed none none
computed computed none none
computed computed none none

Functions

useTimeAgoIntl(time: MaybeRefOrGetter<Date | number | string>, options: UseTimeAgoIntlOptions<false>): UseTimeAgoReturn<false>

A reactive wrapper for Intl.RelativeTimeFormat.

Raw JSDoc 
/**
 * A reactive wrapper for `Intl.RelativeTimeFormat`.
 */
Code 
export function useTimeAgoIntl(time: MaybeRefOrGetter<Date | number | string>, options?: UseTimeAgoIntlOptions<false>): UseTimeAgoReturn<false>

formatTimeAgoIntl(from: Date, options: FormatTimeAgoIntlOptions, now: Date | number): string

Non-reactive version of useTimeAgoIntl

Raw JSDoc 
/**
 * Non-reactive version of useTimeAgoIntl
 */

Calls:

  • getTimeAgoIntlResult
  • formatTimeAgoIntlParts
Code 
export function formatTimeAgoIntl(
  from: Date,
  options: FormatTimeAgoIntlOptions = {},
  now: Date | number = Date.now(),
): string {
  const { parts, resolvedLocale } = getTimeAgoIntlResult(from, options, now)
  return formatTimeAgoIntlParts(parts, {
    ...options,
    locale: resolvedLocale,
  })
}

formatTimeAgoIntlParts(parts: Intl.RelativeTimeFormatPart[], options: FormatTimeAgoIntlOptions): string

Format parts into a string

Raw JSDoc 
/**
 * Format parts into a string
 */

Calls:

  • joinParts
  • parts.map(part => part.value).join
  • parts .map(part => part.value.trim()) .join
Code 
export function formatTimeAgoIntlParts(
  parts: Intl.RelativeTimeFormatPart[],
  options: FormatTimeAgoIntlOptions = {},
): string {
  const {
    insertSpace = true,
    joinParts,
    locale,
  } = options

  if (typeof joinParts === 'function')
    return joinParts(parts, locale)

  if (!insertSpace)
    return parts.map(part => part.value).join('')

  return parts
    .map(part => part.value.trim())
    .join(' ')
}

getTimeAgoIntlResult(from: Date, options: FormatTimeAgoIntlOptions, now: Date | number): { parts: Intl.RelativeTimeFormatPart[], resolvedLocale: Loc…

Get parts from Intl.RelativeTimeFormat.formatToParts.

Raw JSDoc 
/**
 * Get parts from `Intl.RelativeTimeFormat.formatToParts`.
 */

Calls:

  • rtf.resolvedOptions
  • Math.abs
  • rtf.formatToParts
  • Math.round
Code 
function getTimeAgoIntlResult(
  from: Date,
  options: FormatTimeAgoIntlOptions = {},
  now: Date | number = Date.now(),
): { parts: Intl.RelativeTimeFormatPart[], resolvedLocale: Locale } {
  const {
    locale,
    relativeTimeFormatOptions = { numeric: 'auto' },
  } = options

  const rtf = new Intl.RelativeTimeFormat(locale, relativeTimeFormatOptions)
  const { locale: resolvedLocale } = rtf.resolvedOptions()

  const diff = +from - +now
  const absDiff = Math.abs(diff)

  const units = options.units ?? UNITS
  for (const { name, ms } of units) {
    if (absDiff >= ms) {
      return {
        resolvedLocale,
        parts: rtf.formatToParts(Math.round(diff / ms), name),
      }
    }
  }

  return {
    resolvedLocale,
    parts: rtf.formatToParts(0, units[units.length - 1].name),
  }
}

Interfaces

FormatTimeAgoIntlOptions

Interface Code 
export interface FormatTimeAgoIntlOptions {
  /**
   * The locale to format with
   *
   * @default undefined
   * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat/RelativeTimeFormat#locales
   */
  locale?: Locale

  /**
   * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat/RelativeTimeFormat#options
   */
  relativeTimeFormatOptions?: Intl.RelativeTimeFormatOptions

  /**
   * Whether to insert spaces between parts.
   *
   * Ignored if `joinParts` is provided.
   *
   * @default true
   */
  insertSpace?: boolean

  /**
   * Custom function to join the parts returned by `Intl.RelativeTimeFormat.formatToParts`.
   *
   * If provided, it will be used instead of the default join logic.
   */
  joinParts?: (parts: Intl.RelativeTimeFormatPart[], locale?: Intl.UnicodeBCP47LocaleIdentifier | Intl.Locale) => string

  /**
   * Custom units
   */
  units?: TimeAgoUnit[]
}

Properties

Name Type Optional Description
locale Locale ✓ not shown
relativeTimeFormatOptions Intl.RelativeTimeFormatOptions ✓ not shown
insertSpace boolean ✓ not shown
joinParts (parts: Intl.RelativeTimeFormatPart[], locale?: Intl.UnicodeBCP47LocaleIdenti... ✓ not shown
units TimeAgoUnit[] ✓ not shown

UseTimeAgoIntlOptions<Controls extends boolean>

Interface Code 
export interface UseTimeAgoIntlOptions<Controls extends boolean> extends FormatTimeAgoIntlOptions, ConfigurableScheduler {
  /**
   * Expose more controls and the raw `parts` result.
   *
   * @default false
   */
  controls?: Controls
}

Properties

Name Type Optional Description
controls Controls ✓ not shown

TimeAgoUnit

Interface Code 
export interface TimeAgoUnit {
  name: Intl.RelativeTimeFormatUnit
  ms: number
}

Properties

Name Type Optional Description
name Intl.RelativeTimeFormatUnit ✗ not shown
ms number ✗ not shown

Type Aliases

Locale

type Locale = Intl.UnicodeBCP47LocaleIdentifier | Intl.Locale;

UseTimeAgoReturn<Controls extends boolean = false>

type UseTimeAgoReturn<Controls extends boolean = false> = Controls extends true
    ? { timeAgoIntl: ComputedRef<string>, parts: ComputedRef<Intl.RelativeTimeFormatPart[]> } & Pausable
    : ComputedRef<string>;

Generated by Syntax Scribe