feat: add method to format relative time

lib/index.ts

@@ -22,3 +22,9 @@ export type { Translations } from './registry'
 export * from './date'
 export * from './locale'
 export * from './translation'
+
+export {
+	type FormatDateOptions,
+
+	formatRelativeTime,
+} from './time.ts'

lib/time.ts

@@ -0,0 +1,83 @@
+/*!
+ * SPDX-FileCopyrightText: 2025 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+import { getLanguage } from './locale.ts'
+
+export interface FormatDateOptions {
+	/**
+	 * If set then instead of showing seconds since the timestamp show the passed message.
+	 * @default false
+	 */
+	ignoreSeconds?: string | false
+
+	/**
+	 * The relative time formatting option to use
+	 * @default 'long
+	 */
+	relativeTime?: 'long' | 'short' | 'narrow'
+
+	/**
+	 * Language to use
+	 * @default 'current language'
+	 */
+	language?: string
+}
+
+/**
+ * Format a given time as "relative time" also called "humanizing".
+ *
+ * @param timestamp Timestamp or Date object
+ * @param opts Options for the formatting
+ */
+export function formatRelativeTime(
+	timestamp: Date|number = Date.now(),
+	opts: FormatDateOptions = {},
+): string {
+	const options: Required<FormatDateOptions> = {
+		ignoreSeconds: false,
+		language: getLanguage(),
+		relativeTime: 'long' as const,
+		...opts,
+	}
+
+	/** ECMA Date object of the timestamp */
+	const date = new Date(timestamp)
+
+	const formatter = new Intl.RelativeTimeFormat([options.language, getLanguage()], { numeric: 'auto', style: options.relativeTime })
+	const diff = date.getTime() - Date.now()
+	const seconds = diff / 1000
+
+	if (Math.abs(seconds) < 59.5) {
+		return options.ignoreSeconds
+			|| formatter.format(Math.round(seconds), 'second')
+	}
+
+	const minutes = seconds / 60
+	if (Math.abs(minutes) <= 59) {
+		return formatter.format(Math.round(minutes), 'minute')
+	}
+	const hours = minutes / 60
+	if (Math.abs(hours) < 23.5) {
+		return formatter.format(Math.round(hours), 'hour')
+	}
+	const days = hours / 24
+	if (Math.abs(days) < 6.5) {
+		return formatter.format(Math.round(days), 'day')
+	}
+	if (Math.abs(days) < 27.5) {
+		const weeks = days / 7
+		return formatter.format(Math.round(weeks), 'week')
+	}
+
+	// For everything above we show year + month like "August 2025" or month + day if same year like "May 12"
+	// This is based on a Nextcloud design decision: https://github.com/nextcloud/server/issues/29807#issuecomment-2431895872
+	const months = days / 30
+	const format: Intl.DateTimeFormatOptions = Math.abs(months) < 11
+		? { month: options.relativeTime, day: 'numeric' }
+		: { year: options.relativeTime === 'narrow' ? '2-digit' : 'numeric', month: options.relativeTime }
+
+	const dateTimeFormatter = new Intl.DateTimeFormat([options.language, getLanguage()], format)
+	return dateTimeFormatter.format(date)
+}

tests/time.test.ts

@@ -0,0 +1,64 @@
+/*!
+ * SPDX-FileCopyrightText: 2025 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+import { beforeAll, beforeEach, describe, expect, it, test, vi } from 'vitest'
+import { formatRelativeTime } from '../lib'
+
+const setLanguage = (lang: string) => document.documentElement.setAttribute('lang', lang)
+
+describe('time - formatRelativeTime', () => {
+
+	beforeAll(() => {
+		vi.useFakeTimers({ now: new Date('2025-01-01T00:00:00Z') })
+	})
+
+	beforeEach(() => {
+		setLanguage('en')
+	})
+
+	test.each`
+	input                     | relativeTime | expected
+	${'2024-12-31T23:59:30Z'} |    ${'long'} | ${'30 seconds ago'}
+	${'2024-12-31T23:59:30Z'} |   ${'short'} | ${'30 sec. ago'}
+	${'2024-12-31T23:59:30Z'} |  ${'narrow'} | ${'30s ago'}
+	${'2024-12-31T23:55:00Z'} |    ${'long'} | ${'5 minutes ago'}
+	${'2024-12-31T23:55:00Z'} |   ${'short'} | ${'5 min. ago'}
+	${'2024-12-31T23:55:00Z'} |  ${'narrow'} | ${'5m ago'}
+	${'2025-01-01T10:00:00Z'} |    ${'long'} | ${'in 10 hours'}
+	${'2025-01-01T10:00:00Z'} |   ${'short'} | ${'in 10 hr.'}
+	${'2025-01-01T10:00:00Z'} |  ${'narrow'} | ${'in 10h'}
+	${'2025-01-02T11:00:00Z'} |    ${'long'} | ${'tomorrow'}
+	${'2025-01-03T11:00:00Z'} |    ${'long'} | ${'in 2 days'}
+	${'2025-01-07T12:00:00Z'} |    ${'long'} | ${'next week'}
+	${'2025-01-14T10:00:00Z'} |    ${'long'} | ${'in 2 weeks'}
+	${'2025-03-01T10:00:00Z'} |    ${'long'} | ${'March 1'}
+	${'2025-03-14T10:00:00Z'} |    ${'long'} | ${'March 14'}
+	${'2025-03-14T10:00:00Z'} |   ${'short'} | ${'Mar 14'}
+	${'2025-03-14T10:00:00Z'} |  ${'narrow'} | ${'M 14'}
+	${'2026-01-01T10:00:00Z'} |    ${'long'} | ${'January 2026'}
+	${'2024-01-01T10:00:00Z'} |    ${'long'} | ${'January 2024'}
+	${'2024-01-01T10:00:00Z'} |   ${'short'} | ${'Jan 2024'}
+	${'2024-01-01T10:00:00Z'} |  ${'narrow'} | ${'J 24'}
+	`('format date time $input as $expected', ({ input, relativeTime, expected }) => {
+		const date = new Date(input)
+		expect(formatRelativeTime(date, { relativeTime })).toBe(expected)
+	})
+
+	it('can ignore seconds', () => {
+		expect(formatRelativeTime(new Date('2024-12-31T23:59:30Z'), { ignoreSeconds: 'few seconds ago' })).toBe('few seconds ago')
+		expect(formatRelativeTime(new Date('2024-12-31T23:58:00Z'), { ignoreSeconds: 'few seconds ago' })).toBe('2 minutes ago')
+	})
+
+	it('uses user language by default', () => {
+		setLanguage('de')
+		expect(formatRelativeTime(new Date('2024-12-31T23:58:00Z'))).toBe('vor 2 Minuten')
+	})
+
+	it('can override the lange as parameter', () => {
+		setLanguage('de')
+		expect(formatRelativeTime(new Date('2024-12-31T23:58:00Z'), { language: 'en' })).toBe('2 minutes ago')
+	})
+
+})