/** a lazily computed value. */
export interface Lazy<T> {
	readonly value: T;
}

/**
 * compute and cache a value on first access.
 *
 * @param fn the computation to run on first access
 * @returns a holder whose `value` runs `fn` once on first read
 */
export const lazy = <T>(fn: () => T): Lazy<T> => ({
	get value(): T {
		// make cached reads plain property accesses.
		const value = fn();
		Object.defineProperty(this, 'value', { value });
		return value;
	},
});

/**
 * create an `Intl.DateTimeFormat`.
 * @param locale the BCP 47 locale
 * @param options the formatter options
 * @returns the date-time formatter
 */
export const dateTimeFormat = (locale: string, options?: Intl.DateTimeFormatOptions): Intl.DateTimeFormat =>
	new Intl.DateTimeFormat(locale, options);

/**
 * create an `Intl.NumberFormat`.
 * @param locale the BCP 47 locale
 * @param options the formatter options
 * @returns the formatter
 */
export const numberFormat = (locale: string, options?: Intl.NumberFormatOptions): Intl.NumberFormat =>
	new Intl.NumberFormat(locale, options);

/** plural-rules options, including the ES2023 rounding options TypeScript's lib omits. */
export type PluralRulesOptions = Intl.PluralRulesOptions &
	Pick<Intl.NumberFormatOptions, 'roundingIncrement' | 'roundingMode' | 'roundingPriority'>;

/**
 * create an `Intl.PluralRules`.
 * @param locale the BCP 47 locale
 * @param options the plural-rules options
 * @returns the plural rules
 */
export const pluralRules = (locale: string, options?: PluralRulesOptions): Intl.PluralRules =>
	new Intl.PluralRules(locale, options);