Commit 6807cf61 authored by Nikolay Kuchumov's avatar Nikolay Kuchumov 💬
Browse files

#9. Fixed TypeScript definition — ability to `.format()` with a custom style and get refresh delay

parent ca74fefc

index.d.ts

+46 −7
Original line number Diff line number Diff line
@@ -123,6 +123,21 @@ interface FormatOptions { 


interface FormatOptionsWithGetTimeToNextUpdate extends FormatOptions {

	getTimeToNextUpdate: boolean;



	// `setTimeout()` function has a bug when it fires immediately

	// when the delay is longer than about `24.85` days.

	// https://stackoverflow.com/questions/3468607/why-does-settimeout-break-for-large-millisecond-delay-values

	//

	// In order to not burden the end users of this library with manually working around that bug,

	// this library automatically caps the returned delay to a maximum value of about `24.85` days

	// which still works correctly with `setTimeout()` function and doesn't break it.

	//

	// The end user of this library could still disable this automatic workaround

	// by passing a `getTimeToNextUpdateUncapped: true` parameter.

	// In that case, it will return the original non-modified uncapped delay

	// which can be longer than `24.85` days and should be manually capped

	// by the developer if it's going to be used in a `setTimeout()` call.

	//

	getTimeToNextUpdateUncapped?: boolean;

}
@@ -131,17 +146,41 @@ interface FormatOptionsWithRefresh extends FormatOptions { 
}



export default class TimeAgo {

	// Creates a `TimeAgo` instance.

  constructor(locale: Locale | Locale[], options?: { polyfill?: boolean });

	// When `getTimeToNextUpdate: true` option is passed to `.format()`,

	// it returns an array containing the formatted time and the "time to next update" interval.

	// https://gitlab.com/catamphetamine/javascript-time-ago#update-interval

	// Perhaps it's not the best solution, and it would be better to introduce a new function called

	// `.formatAndGetTimeToNextUpdate()`. But at this stage that would require a "major" version number update,

	// and I wouldn't prefer doing that for such an insignificant change.



	// Calling `.format()` function normally.

  format(date: DateInput, style?: FormatStyleName | Style, options?: FormatOptions): string;



	// Calling `.format()` with `getTimeToNextUpdate: true` parameter.

	//

	// When `.format()` is called with `getTimeToNextUpdate: true` parameter,

	// it returns an array containing the formatted time and the "time to next update" delay.

	//

	// Perhaps returning an array is not the best solution, and it would've been better

	// to introduce a new function called `.formatAndGetTimeToNextUpdate()` or something like that.

	// But at this stage it already returns an array and changing that would require

	// a "major" version number update, and I would prefer not doing that for such an insignificant change.

	//

  format(date: DateInput, options: FormatOptionsWithGetTimeToNextUpdate): [string, number?];

  format(date: DateInput, style: FormatStyleName | Style, options: FormatOptionsWithGetTimeToNextUpdate): [string, number?];



	// Calling `.format()` with a `refresh()` parameter.

	//

	// When `.format()` is called with a `refresh()` parameter,

	// it returns an array containing the formatted time and the "stop refreshing" function.

	//

	// I.e. it mimicks the return value of already-existing `getTimeToNextUpdate: true` parameter.

	//

  format(date: DateInput, options: FormatOptionsWithRefresh): [string, () => void];

  getLabels(labelsType: LabelStyleName | LabelStyleName[]): Labels;

  format(date: DateInput, style: FormatStyleName | Style, options: FormatOptionsWithRefresh): [string, () => void];



	// `getLabels()` function seems to be unused and is not documented.

	// Perhaps it even wasn't ever declared as part of the public API

	// and got in this TypeScript definition by accident.

	//

  // getLabels(labelsType: LabelStyleName | LabelStyleName[]): Labels;



  static addLocale(localeData: LocaleData): void;

  static addDefaultLocale(localeData: LocaleData): void;

  static getDefaultLocale(): Locale;

source/TimeAgo.js

+8 −5
Original line number Diff line number Diff line
@@ -231,12 +231,15 @@ export default class TimeAgo { 
					// when the delay is longer than about `24.85` days.

					// https://stackoverflow.com/questions/3468607/why-does-settimeout-break-for-large-millisecond-delay-values

					//

					// To not burden the end user of this library with manually working around that bug,

					// this library automatically caps the returned delay to a maximum value that

					// still works with `setTimeout()` and doesn't break it.

					// In order to not burden the end users of this library with manually working around that bug,

					// this library automatically caps the returned delay to a maximum value of about `24.85` days

					// which still works correctly with `setTimeout()` function and doesn't break it.

					//

					// The end user of this library could still opt out of this auto-workaround feature

					// by passing a `getTimeToNextUpdateUncapped: true` option.

					// The end user of this library could still disable this automatic workaround

					// by passing a `getTimeToNextUpdateUncapped: true` parameter.

					// In that case, it will return the original non-modified uncapped delay

					// which can be longer than `24.85` days and should be manually capped

					// by the developer if it's going to be used in a `setTimeout()` call.

					//

					if (options.getTimeToNextUpdateUncapped) {

						return timeToNextUpdate