FazBrowse GitHub Viewer | Trending |
URL:
| Home
Tools: [Download Repo ZIP]   [Original HTTPS Page]

gravity-ui/date-utils: Helpers to manage work with dates. · GitHub

/ date-utils Public
BranchesTags

Repository files navigation

@gravity-ui/date-utils

Helpers for managing Date and Time.

Install

npm i @gravity-ui/date-utils

Usage

import {dateTimeParse, dateTime} from '@gravity-ui/date-utils';

// Current date: 2021-08-07T12:10:00
// User's time zone: Europe/Istanbul

const FORMAT = 'YYYY-MM-DDTHH:mm:ssZ';

// parse absolute date
dateTimeParse({year: 2021, month: 7, day: 7})?.format(FORMAT); // "2021-08-07T00:00:00+03:00"
dateTimeParse([2021, 7, 7])?.format(FORMAT); // "2021-08-07T00:00:00+03:00"
dateTimeParse('2021-08-07')?.format(FORMAT); // "2021-08-07T00:00:00+03:00"
dateTimeParse(1621708204063)?.format(FORMAT); // "2021-05-22T21:30:04+03:00"
dateTimeParse('')?.format(FORMAT); // undefined
dateTimeParse('incorrect-date')?.format(FORMAT); // undefined

// parse relative date
dateTimeParse('now')?.format(FORMAT); // "2021-08-07T12:10:00+03:00"
dateTimeParse('now-1d')?.format(FORMAT); // "2021-08-06T12:10:00+03:00"
dateTimeParse('now-1d+1M')?.format(FORMAT); // "2021-09-06T12:10:00+03:00"
dateTimeParse('now/d')?.format(FORMAT); // "2021-08-07T00:00:00+03:00"
dateTimeParse('now+1d/d')?.format(FORMAT); // "2021-08-08T00:00:00+03:00"
dateTimeParse('now-1f')?.format(FORMAT); // undefined

// create dateTime
dateTime().format(FORMAT); // "2021-08-07T12:10:00+03:00"
dateTime({input: '2021-08-07'}).format(FORMAT); // "2021-08-07T00:00:00+03:00"
dateTime({input: '2021-08-07', format: 'YYYY-MM-DD'}).format(FORMAT); // "2021-08-07T00:00:00+03:00"
dateTime({timeZone: 'Asia/Tokyo'}).format(FORMAT); // "2021-08-07T18:10:00+09:00
dateTime({input: ''}).format(FORMAT); // "Invalid Date"
dateTime({input: '2021-08', format: 'YYYY-MM-DD'}).format(FORMAT); // "Invalid Date"

Settings

import {settings} from '@gravity-ui/date-utils';

// Locales management
settings.getLocale(); // default locale "en"
settings.loadLocale('de').then(() => {
  settings.setLocale('de');
  settings.getLocale(); // "de"
});

// Customization
settings.updateLocale({weekStart: 0}); // change first day of week

License

Distributed under the MIT License. See LICENSE for details.

For AI agents

Timezone-aware date/time helpers — parsing (including relative expressions like now-1d/d), formatting, and locale management — without any UI, reach for it when you need to compute and format dates reliably across time zones instead of pulling in a full UI calendar.

When to use

  • Parsing absolute or relative date expressions ('now-1d', 'now/d') into a timezone-aware dateTime object.
  • Formatting dates for display in the user's timezone with locale support.
  • Sharing date logic between server (Node) and client (React) code — the package has no React dependency.

When not to use

  • To render a calendar, date picker, or any date UI, use @gravity-ui/date-components — it builds its visuals on top of this package.
  • For lightweight immutable date math and no timezone/relative-expression needs, date-fns or the native Intl/Date APIs may suffice.

Common pitfalls

  • Calling dateTimeParse('') expecting a date — returns undefined, not a dateTime; guard with optional chaining or a null check.
  • Forgetting to load a locale — settings.setLocale('de') only formats localized names (weekdays, months) after settings.loadLocale('de') has resolved.
  • Hallucinated function formatDate / parseDate — the entry points are dateTimeParse (parse) and dateTime(...).format(...) (format).
  • Assuming the user's timezone is applied automatically — pass timeZone explicitly or the system timezone is used.

Documentation for AI agents

Agent-readable documentation for the installed version is located in node_modules/@gravity-ui/date-utils/build/docs/INDEX.md.

About

Helpers to manage work with dates.

gravity-ui.github.io/date-utils/

Topics

date-formattingdate-parserdate-utilsgravity-ui

Resources

Readme
MIT license

Contributing

Contributing
Activity
Custom properties

Stars

16 stars

Watchers

1 watching

Forks

4 forks
Report repository

Releases

Packages

Used by

Contributors

Languages

Back | FazBrowse Home | New Git URL