nextcloud-libraries · susnux · Jul 7, 2025 · Jul 7, 2025 · Jul 7, 2025
diff --git a/.eslintrc.json b/.eslintrc.json
diff --git a/build/format-changelog.mjs b/build/format-changelog.mjs
@@ -1,7 +1,10 @@
-/**
+/*!
  * SPDX-FileCopyrightText: Nextcloud GmbH and Nextcloud contributors
  * SPDX-License-Identifier: GPL-3.0-or-later
  */
+
+/* eslint-disable no-console */
+
 import { readFile, writeFile } from 'node:fs/promises'
 import { join } from 'node:path'
 

diff --git a/eslint.config.js b/eslint.config.js
@@ -0,0 +1,21 @@
+/*!
+ * SPDX-FileCopyrightText: 2025 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: CC0-1.0
+ */
+
+import { recommendedLibrary } from '@nextcloud/eslint-config'
+
+export default [
+	...recommendedLibrary,
+
+	// Fix tsdoc generation
+	{
+		files: ['lib/**.ts'],
+		rules: {
+			'jsdoc/check-tag-names': [
+				'error',
+				{ definedTags: ['packageDocumentation'] },
+			],
+		},
+	},
+]
diff --git a/lib/date.ts b/lib/date.ts
@@ -1,12 +1,12 @@
+/// <reference types="@nextcloud/typings" />
 /*!
  * SPDX-FileCopyrightText: 2022 Nextcloud GmbH and Nextcloud contributors
  * SPDX-License-Identifier: GPL-3.0-or-later
  */
-/// <reference types="@nextcloud/typings" />
 
-import { getCanonicalLocale } from './locale'
+import { getCanonicalLocale } from './locale.ts'
 
-declare let window: Nextcloud.v27.WindowWithGlobals
+declare let window: Nextcloud.v29.WindowWithGlobals
 
 export type WeekDay = 0 | 1 | 2 | 3 | 4 | 5 | 6
 
@@ -26,10 +26,10 @@ export function getFirstDay(): WeekDay {
 	// Node.js and Samsung Internet only has accessor property weekInfo instead
 	type WeekInfoDay = 1 | 2 | 3 | 4 | 5 | 6 | 7
 	type WeekInfo = {
-		firstDay: WeekInfoDay,
-		weekend: WeekInfoDay,
-		minimalDays: WeekInfoDay,
-	 }
+		firstDay: WeekInfoDay
+		weekend: WeekInfoDay
+		minimalDays: WeekInfoDay
+	}
 	const intl = new Intl.Locale(getCanonicalLocale())
 	// @ts-expect-error These properties are not part of the standard
 	const weekInfo: WeekInfo = intl.getWeekInfo?.() ?? intl.weekInfo
@@ -44,8 +44,6 @@ export function getFirstDay(): WeekDay {
 
 /**
  * Get a list of day names (full names)
- *
- * @return {string[]}
  */
 export function getDayNames(): string[] {
 	// Server rendered
@@ -68,8 +66,6 @@ export function getDayNames(): string[] {
 
 /**
  * Get a list of day names (short names)
- *
- * @return {string[]}
  */
 export function getDayNamesShort(): string[] {
 	if (typeof window.dayNamesShort !== 'undefined') {
@@ -92,8 +88,6 @@ export function getDayNamesShort(): string[] {
 
 /**
  * Get a list of day names (minified names)
- *
- * @return {string[]}
  */
 export function getDayNamesMin(): string[] {
 	// Server rendered
@@ -116,8 +110,6 @@ export function getDayNamesMin(): string[] {
 
 /**
  * Get a list of month names (full names)
- *
- * @return {string[]}
  */
 export function getMonthNames(): string[] {
 	// Server rendered
@@ -145,8 +137,6 @@ export function getMonthNames(): string[] {
 
 /**
  * Get a list of month names (short names)
- *
- * @return {string[]}
  */
 export function getMonthNamesShort(): string[] {
 	// Server rendered

diff --git a/lib/gettext.ts b/lib/gettext.ts
@@ -18,7 +18,9 @@ const gt = getGettextBuilder()
 gt.gettext('some string to translate')
 ```
  */
+
 import type { AppTranslations } from './registry.ts'
+
 import { getLanguage, getPlural, translate, translatePlural } from './index.ts'
 
 export interface GettextTranslation {
@@ -34,14 +36,40 @@ export interface GettextTranslationContext {
 export interface GettextTranslationBundle {
 	headers: {
 		[headerName: string]: string
-	},
+	}
 	translations: {
 		[context: string]: GettextTranslationContext
 	}
 }
 
-class GettextBuilder {
+class GettextWrapper {
+	constructor(private bundle: AppTranslations) {
+	}
+
+	/**
+	 * Get translated string (singular form), optionally with placeholders
+	 *
+	 * @param original original string to translate
+	 * @param placeholders map of placeholder key to value
+	 */
+	gettext(original: string, placeholders: Record<string, string | number> = {}): string {
+		return translate('', original, placeholders, undefined, { bundle: this.bundle })
+	}
 
+	/**
+	 * Get translated string with plural forms
+	 *
+	 * @param singular Singular text form
+	 * @param plural Plural text form to be used if `count` requires it
+	 * @param count The number to insert into the text
+	 * @param placeholders optional map of placeholder key to value
+	 */
+	ngettext(singular: string, plural: string, count: number, placeholders: Record<string, string | number> = {}): string {
+		return translatePlural('', singular, plural, count, placeholders, { bundle: this.bundle })
+	}
+}
+
+class GettextBuilder {
 	private debug = false
 	private language = 'en'
 	private translations = {} as Record<string, GettextTranslationBundle>
@@ -81,6 +109,7 @@ class GettextBuilder {
 
 	build(): GettextWrapper {
 		if (this.debug) {
+			// eslint-disable-next-line no-console
 			console.debug(`Creating gettext instance for language ${this.language}`)
 		}
 
@@ -99,38 +128,6 @@ class GettextBuilder {
 
 		return new GettextWrapper(bundle)
 	}
-
-}
-
-class GettextWrapper {
-
-	constructor(
-		private bundle: AppTranslations,
-	) {
-	}
-
-	/**
-	 * Get translated string (singular form), optionally with placeholders
-	 *
-	 * @param original original string to translate
-	 * @param placeholders map of placeholder key to value
-	 */
-	gettext(original: string, placeholders: Record<string, string | number> = {}): string {
-		return translate('', original, placeholders, undefined, { bundle: this.bundle })
-	}
-
-	/**
-	 * Get translated string with plural forms
-	 *
-	 * @param singular Singular text form
-	 * @param plural Plural text form to be used if `count` requires it
-	 * @param count The number to insert into the text
-	 * @param placeholders optional map of placeholder key to value
-	 */
-	ngettext(singular: string, plural: string, count: number, placeholders: Record<string, string | number> = {}): string {
-		return translatePlural('', singular, plural, count, placeholders, { bundle: this.bundle })
-	}
-
 }
 
 /**

diff --git a/lib/index.ts b/lib/index.ts
@@ -17,11 +17,11 @@ console.warn(n('my-app', 'Got an error', 'Got multiple errors', 2));
 ```
  */
 
-export type { Translations } from './registry'
+export type { Translations } from './registry.ts'
 
-export * from './date'
-export * from './locale'
-export * from './translation'
+export * from './date.ts'
+export * from './locale.ts'
+export * from './translation.ts'
 
 export {
 	type FormatDateOptions,

diff --git a/lib/locale.ts b/lib/locale.ts
@@ -37,33 +37,33 @@ export function isRTL(language?: string): boolean {
 
 	// Source: https://meta.wikimedia.org/wiki/Template:List_of_language_names_ordered_by_code
 	const rtlLanguages = [
-		/* eslint-disable no-multi-spaces */
-		'ae',  // Avestan
-		'ar',  // 'العربية', Arabic
+
+		'ae', // Avestan
+		'ar', // 'العربية', Arabic
 		'arc', // Aramaic
 		'arz', // 'مصرى', Egyptian
 		'bcc', // 'بلوچی مکرانی', Southern Balochi
 		'bqi', // 'بختياري', Bakthiari
 		'ckb', // 'Soranî / کوردی', Sorani
-		'dv',  // Dhivehi
-		'fa',  // 'فارسی', Persian
+		'dv', // Dhivehi
+		'fa', // 'فارسی', Persian
 		'glk', // 'گیلکی', Gilaki
-		'ha',  // 'هَوُسَ', Hausa
-		'he',  // 'עברית', Hebrew
+		'ha', // 'هَوُسَ', Hausa
+		'he', // 'עברית', Hebrew
 		'khw', // 'کھوار', Khowar
-		'ks',  // 'कॉशुर / کٲشُر', Kashmiri
-		'ku',  // 'Kurdî / كوردی', Kurdish
+		'ks', // 'कॉशुर / کٲشُر', Kashmiri
+		'ku', // 'Kurdî / كوردی', Kurdish
 		'mzn', // 'مازِرونی', Mazanderani
 		'nqo', // 'ߒߞߏ', N’Ko
 		'pnb', // 'پنجابی', Western Punjabi
-		'ps',  // 'پښتو', Pashto,
-		'sd',  // 'سنڌي', Sindhi
-		'ug',  // 'Uyghurche / ئۇيغۇرچە', Uyghur
-		'ur',    // 'اردو', Urdu
+		'ps', // 'پښتو', Pashto,
+		'sd', // 'سنڌي', Sindhi
+		'ug', // 'Uyghurche / ئۇيغۇرچە', Uyghur
+		'ur', // 'اردو', Urdu
 		'ur-PK', // 'اردو', Urdu (nextcloud BCP47 variant)
 		'uz-AF', // 'اوزبیکی', Uzbek Afghan
-		'yi',    // 'ייִדיש', Yiddish
-		/* eslint-enable no-multi-spaces */
+		'yi', // 'ייִדיש', Yiddish
+
 	]
 
 	return rtlLanguages.includes(languageCode)

diff --git a/lib/registry.ts b/lib/registry.ts
@@ -1,5 +1,4 @@
 /// <reference types="@nextcloud/typings" />
-
 /*!
  * SPDX-FileCopyrightText: 2022 Nextcloud GmbH and Nextcloud contributors
  * SPDX-License-Identifier: GPL-3.0-or-later
@@ -54,8 +53,8 @@ export interface AppTranslations {
 /**
  * Check if translations and plural function are set for given app
  *
- * @param {string} appId the app id
- * @return {boolean}
+ * @param appId - The app id
+ * @return
  */
 export function hasAppTranslations(appId: string) {
 	return (
@@ -67,9 +66,9 @@ export function hasAppTranslations(appId: string) {
 /**
  * Register new, or extend available, translations for an app
  *
- * @param {string} appId the app id
- * @param {object} translations the translations list
- * @param {Function} pluralFunction the plural function
+ * @param appId - The app id
+ * @param translations - The translations list
+ * @param pluralFunction - The plural function
  */
 export function registerAppTranslations(
 	appId: string,
@@ -98,7 +97,7 @@ export function registerAppTranslations(
 /**
  * Unregister all translations and plural function for given app
  *
- * @param {string} appId the app id
+ * @param appId - The app id
  */
 export function unregisterAppTranslations(appId: string) {
 	delete window._oc_l10n_registry_translations?.[appId]
@@ -108,8 +107,7 @@ export function unregisterAppTranslations(appId: string) {
 /**
  * Get translations bundle for given app and current locale
  *
- * @param {string} appId the app id
- * @return {object}
+ * @param appId - The app id
  */
 export function getAppTranslations(appId: string): AppTranslations {
 	return {

diff --git a/lib/time.ts b/lib/time.ts
@@ -8,18 +8,21 @@ 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
@@ -32,7 +35,7 @@ export interface FormatDateOptions {
  * @param opts Options for the formatting
  */
 export function formatRelativeTime(
-	timestamp: Date|number = Date.now(),
+	timestamp: Date | number = Date.now(),
 	opts: FormatDateOptions = {},
 ): string {
 	const options: Required<FormatDateOptions> = {