lightFormat.d.ts 3.6 KB

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465
  1. import { lightFormatters } from "./_lib/format/lightFormatters.js";
  2. export { lightFormatters };
  3. /**
  4. * @name lightFormat
  5. * @category Common Helpers
  6. * @summary Format the date.
  7. *
  8. * @description
  9. * Return the formatted date string in the given format. Unlike `format`,
  10. * `lightFormat` doesn't use locales and outputs date using the most popular tokens.
  11. *
  12. * > ⚠️ Please note that the `lightFormat` tokens differ from Moment.js and other libraries.
  13. * > See: https://github.com/date-fns/date-fns/blob/master/docs/unicodeTokens.md
  14. *
  15. * The characters wrapped between two single quotes characters (') are escaped.
  16. * Two single quotes in a row, whether inside or outside a quoted sequence, represent a 'real' single quote.
  17. *
  18. * Format of the string is based on Unicode Technical Standard #35:
  19. * https://www.unicode.org/reports/tr35/tr35-dates.html#Date_Field_Symbol_Table
  20. *
  21. * Accepted patterns:
  22. * | Unit | Pattern | Result examples |
  23. * |---------------------------------|---------|-----------------------------------|
  24. * | AM, PM | a..aaa | AM, PM |
  25. * | | aaaa | a.m., p.m. |
  26. * | | aaaaa | a, p |
  27. * | Calendar year | y | 44, 1, 1900, 2017 |
  28. * | | yy | 44, 01, 00, 17 |
  29. * | | yyy | 044, 001, 000, 017 |
  30. * | | yyyy | 0044, 0001, 1900, 2017 |
  31. * | Month (formatting) | M | 1, 2, ..., 12 |
  32. * | | MM | 01, 02, ..., 12 |
  33. * | Day of month | d | 1, 2, ..., 31 |
  34. * | | dd | 01, 02, ..., 31 |
  35. * | Hour [1-12] | h | 1, 2, ..., 11, 12 |
  36. * | | hh | 01, 02, ..., 11, 12 |
  37. * | Hour [0-23] | H | 0, 1, 2, ..., 23 |
  38. * | | HH | 00, 01, 02, ..., 23 |
  39. * | Minute | m | 0, 1, ..., 59 |
  40. * | | mm | 00, 01, ..., 59 |
  41. * | Second | s | 0, 1, ..., 59 |
  42. * | | ss | 00, 01, ..., 59 |
  43. * | Fraction of second | S | 0, 1, ..., 9 |
  44. * | | SS | 00, 01, ..., 99 |
  45. * | | SSS | 000, 001, ..., 999 |
  46. * | | SSSS | ... |
  47. *
  48. * @typeParam DateType - The `Date` type, the function operates on. Gets inferred from passed arguments. Allows to use extensions like [`UTCDate`](https://github.com/date-fns/utc).
  49. *
  50. * @param date - The original date
  51. * @param format - The string of tokens
  52. *
  53. * @returns The formatted date string
  54. *
  55. * @throws `Invalid time value` if the date is invalid
  56. * @throws format string contains an unescaped latin alphabet character
  57. *
  58. * @example
  59. * const result = lightFormat(new Date(2014, 1, 11), 'yyyy-MM-dd')
  60. * //=> '2014-02-11'
  61. */
  62. export declare function lightFormat<DateType extends Date>(
  63. date: DateType | number | string,
  64. formatStr: string,
  65. ): string;