Socket
Socket
Sign inDemoInstall

intl-datetimeformat-options

Package Overview
Dependencies
0
Maintainers
1
Versions
2
Alerts
File Explorer

Advanced tools

Install Socket

Detect and block malicious and high-risk dependencies

Install

intl-datetimeformat-options

Provides localized date/time format patterns for styles full, long, medium and short, using Intl.DateTimeFormat.


Version published
Maintainers
1
Created

Changelog

Source

1.0.1 (2023-12-10)

Bug Fixes

  • Upgrade dependencies (0eb1318)

Initial release

Readme

Source

Intl DateTime Format Patterns

Latest version Dependency status Coverage Codacy Badge

Provides localized date/time format patterns for styles full, long, medium and short, using Intl.DateTimeFormat. For example:

LocaleStylePatternExample
enshortM/d/yy, h:mm a2/3/01, 4:05 AM
cslongd. MMMM y H:mm:ss z3. února 1901 4:05:06 GMT+1
const formatter = new Intl.DateTimeFormat('cs', { dateStyle: 'short'})
const pattern = getDateTimeFormatPattern(formatter) // d.M.yy
  • ES, CJS and UMD module exports.
  • TypeScript type declarations (typings).
  • No other dependencies.
  • Tiny code base - 2.73 kB minified, 1.31 B gzipped, 1.16 B brotlied.
  • Resolves four date/time-formatting pattern styles (lengths) - full, long, medium, short.

This library needs a working implementation of Intl.DateTimeFormat.If you are interested in a library, which does not need Intl.DateTimeFormat and uses CLDR data to be compliant with Unicode LDML too, have look at datetime-locale-patterns.

Related projects:

Motivation

When do you need to know the date/time format pattern? When is just formatting a date or time values to a string not enough?

  1. Date/time pickers. You format with Intl.DateTimeFormat. Intl.DateTimeFormat or luxon format using a localized pattern decided by a specified locale. No need to provide the format explicitly. But what if you need to display the format pattern, which is used for the formatting? For example, in a date picker field as a value placeholder.
  2. Raw date/time formatting. You do not format with Intl.DateTimeFormat. Libraries like date-and-time, date-fns and others format using patterns provided by the developer. But how to get a localized pattern for a particular language and country?

There is no built-in API in browsers or Node.js for getting localized date/time-formatting patterns.

Synopsis

  1. Date/time pickers. Get a pattern to see in an abstract way how a concrete date will be formatted:
import { getDateTimeFormatPattern } from 'intl-datetimeformat-options'

const date = new Date(1, 1, 3, 4, 5, 6)
const options = { dateStyle: 'short', timeStyle: 'short' }

const formatter = new Intl.DateTimeFormat('en', options)
const text = formatter.format(date)
console.log(text) // prints '2/3/01, 4:05 AM'

const pattern = getDateTimeFormatPattern('en', options)
console.log(pattern) // prints 'M/d/yy, h:mm a'
  1. Raw date/time formatting. Get a pattern to format a concrete date with:
import { getDateTimeFormatPattern } from 'intl-datetimeformat-options'
import formatter from 'date-and-time'

const date = new Date(1, 1, 3, 4, 5, 6)

const pattern = getDateTimeFormatPattern('en', 'short', 'short')
console.log(pattern) // prints 'M/d/yy, h:mm a'

const text = formatter.format(date, pattern)
console.log(text) // prints '2/3/01, 4:05 AM'

Installation

This module can be installed in your project using NPM, PNPM or Yarn. Make sure, that you use Node.js version 16.14 or newer.

$ npm i intl-datetimeformat-options
$ pnpm i intl-datetimeformat-options
$ yarn add intl-datetimeformat-options

Functions are exposed as named exports from ES and CJS modules, for example:

import { getDateTimeFormatPattern } from 'intl-datetimeformat-options'
const { getDateTimeFormatPattern } = require('intl-datetimeformat-options')

A UMD module can be loaded to the browser either directly:

<script src="https://unpkg.com/intl-datetimeformat-options@1.0.0/lib/index.min.js"></script>
<script>
  const { getDateTimeFormatPattern } = window.intlDateTimeFormatOptions
</script>

Or using an AMD module loader:

<script>
  require([
    'https://unpkg.com/intl-datetimeformat-options@1.0.0/lib/index.min.js'
  ], ({ getDateTimeFormatPattern }) => {
    ...
  })
</script>

API

This library works well with Intl.DateTimeFormat by using concepts from Unicode CLDR (Common Locale Data Repository):

getDateTimeFormatPattern(locale, dateStyle?, timeStyle?)

Returns a pattern to format a date+time value for the specified locale with the specified style.

The locale argument can be either a locale or an instance of Intl.DateTimeFomat. The second argument won't be needed in the latter case.

The dateStyle argument can be either a string (full, long, medium, short) or an object with dateStyle and timeStyle properties from Intl.DateTimeFomat options. If it is a string, the timeStyle argument will be required (as a string).

import { getDateTimeFormatPattern } from 'intl-datetimeformat-options'

const pattern = getDateTimeFormatPattern('en', 'short', 'short')
console.log(pattern) // prints 'M/d/yy, h:mm a'

Problems

The patterns are guessed by formatting a specific date (1901-02-03 04:05:06), parsing the formatted output and detecting numeric formats, names of days and months and other tokens from Unicode LDML. This needs a reliable implementation of Intl.DateTimeFormat.

  • If the date/time formatting provided by the underlying OS API is used in the implementation of Intl.DateTimeFormat, the actual pattern may differ from the multi-platform Unicode CLDR.
  • If ICU (International Components for Unicode) library, which is supposed to be in sync with Unicode CLDR, is used by a browser or Node.js, the version of that ICU may differ from the latest version of Unicode CLDR and from the implementation of Intl.DateTimeFormat. This can be seen in long and full styles of the en locale, which include a different "glue pattern" for joining data and time patterns. ICU includes " at ", while Unicode CLDR includes ",".

Patterns returned by this library should match the behaviour of Intl.DateTimeFormat well. Patterns from Unicode CLDR may differ.

Contributing

In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code using Grunt.

License

Copyright (c) 2023 Ferdinand Prantl

Licensed under the MIT license.

Keywords

FAQs

Package last updated on 10 Dec 2023

Did you know?

Socket

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

Related posts

SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap

Packages

Stay in touch

Get open source security insights delivered straight into your inbox.


  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc