@internationalized/date - npm Package Compare versions

Comparing version 3.0.0-nightly.3204 to 3.0.0-nightly.3207

dist/types.d.ts

@@ -147,2 +147,3 @@ /** An interface that is compatible with any object with date fields. */
 export function getLocalTimeZone(): string;
+/** Returns the first date of the month for the given date. */
 export function startOfMonth(date: ZonedDateTime): ZonedDateTime;
@@ -152,2 +153,3 @@ export function startOfMonth(date: CalendarDateTime): CalendarDateTime;
 export function startOfMonth(date: DateValue): DateValue;
+/** Returns the last date of the month for the given date. */
 export function endOfMonth(date: ZonedDateTime): ZonedDateTime;
@@ -157,2 +159,3 @@ export function endOfMonth(date: CalendarDateTime): CalendarDateTime;
 export function endOfMonth(date: DateValue): DateValue;
+/** Returns the first day of the year for the given date. */
 export function startOfYear(date: ZonedDateTime): ZonedDateTime;
@@ -162,2 +165,3 @@ export function startOfYear(date: CalendarDateTime): CalendarDateTime;
 export function startOfYear(date: DateValue): DateValue;
+/** Returns the last day of the year for the given date. */
 export function endOfYear(date: ZonedDateTime): ZonedDateTime;
@@ -169,2 +173,3 @@ export function endOfYear(date: CalendarDateTime): CalendarDateTime;
 export function getMinimumDayInMonth(date: AnyCalendarDate): number;
+/** Returns the first date of the week for the given date and locale. */
 export function startOfWeek(date: ZonedDateTime, locale: string): ZonedDateTime;
@@ -174,2 +179,3 @@ export function startOfWeek(date: CalendarDateTime, locale: string): CalendarDateTime;
 export function startOfWeek(date: DateValue, locale: string): DateValue;
+/** Returns the last date of the week for the given date and locale. */
 export function endOfWeek(date: ZonedDateTime, locale: string): ZonedDateTime;
@@ -227,7 +233,24 @@ export function endOfWeek(date: CalendarDateTime, locale: string): CalendarDateTime;
 export function toLocalTimeZone(date: ZonedDateTime): ZonedDateTime;
+/** Parses an ISO 8601 time string. */
 export function parseTime(value: string): Time;
+/** Parses an ISO 8601 date string, with no time components. */
 export function parseDate(value: string): CalendarDate;
+/** Parses an ISO 8601 date and time string, with no time zone. */
 export function parseDateTime(value: string): CalendarDateTime;
+/**
+ * Parses an ISO 8601 date and time string with a time zone extension and optional UTC offset
+ * (e.g. "2021-11-07T00:45[America/Los_Angeles]" or "2021-11-07T00:45-07:00[America/Los_Angeles]").
+ * Ambiguous times due to daylight saving time transitions are resolved according to the `disambiguation`
+ * parameter.
+ */
 export function parseZonedDateTime(value: string, disambiguation?: Disambiguation): ZonedDateTime;
+/**
+ * Parses an ISO 8601 date and time string with a UTC offset (e.g. "2021-11-07T07:45:00Z"
+ * or "2021-11-07T07:45:00-07:00"). The result is converted to the provided time zone.
+ */
 export function parseAbsolute(value: string, timeZone: string): ZonedDateTime;
+/**
+ * Parses an ISO 8601 date and time string with a UTC offset (e.g. "2021-11-07T07:45:00Z"
+ * or "2021-11-07T07:45:00-07:00"). The result is converted to the user's local time zone.
+ */
 export function parseAbsoluteToLocal(value: string): ZonedDateTime;
@@ -574,2 +597,3 @@ /** A CalendarDate represents a date without any time components in a specific calendar system. */
 }
+/** Creates a `Calendar` instance from a Unicode calendar identifier string. */
 export function createCalendar(name: string): Calendar;
@@ -576,0 +600,0 @@ interface ResolvedDateTimeFormatOptions extends Intl.ResolvedDateTimeFormatOptions {

package.json

 {
   "name": "@internationalized/date",
-  "version": "3.0.0-nightly.3204+378582d60",
-  "description": "Internationalized calendar and date manipulation utilities",
+  "version": "3.0.0-nightly.3207+cc158b410",
+  "description": "Internationalized calendar, date, and time manipulation utilities",
   "license": "Apache-2.0",
@@ -17,3 +17,3 @@ "main": "dist/main.js",
     "type": "git",
-    "url": "https://github.com/adobe/react-spectrum"
+    "url": "https://github.com/adobe/react-spectrum/tree/main/packages/@internationalized/date"
   },
@@ -26,3 +26,3 @@ "dependencies": {
   },
-  "gitHead": "378582d606bf55c9937d74c82eb5a9f4fcb82018"
+  "gitHead": "cc158b410d11894fb2f14cc2732165dd91786036"
 }

README.md

 # @internationalized/date
 
-This package is part of [react-spectrum](https://github.com/adobe/react-spectrum). See the repo for more details.
+The `@internationalized/date` package provides objects and functions for representing and manipulating dates and times in a locale-aware manner.
+
+## Features
+
+* **Typed objects** – Includes immutable objects to represent dates, times, calendars, and more.
+* **International calendars** – Support for 13 calendar systems used around the world, including Gregorian, Buddhist, Islamic, Persian, and more.
+* **Manipulation** – Add and subtract durations, set and cycle fields, and more.
+* **Conversion** – Convert between calendar systems, time zones, string representations, and object types.
+* **Queries** – Compare dates and times for ordering or full/partial equality. Determine locale-specific metadata such as day of week, weekend/weekday, etc.
+* **Time zone aware** – The [ZonedDateTime](https://react-specrum.adobe.com/internationalized/date/ZonedDateTime.html) object supports time zone aware date and time manipulation.
+* **Predictable** – The API is designed to resolve ambiguity in all operations explicitly, including time zone conversions, arithmetic involving daylight saving time, locale-specific queries, and more.
+* **Small bundle size** – The entire library including all calendars and functions is 8 kB minified and compressed with Brotli.
+* **Tree shakeable** – Only include the functions and calendar systems you need. For example, if you only use the Gregorian calendar and builtin `CalendarDate` methods, it's just 2.8 kB.
+
+## Introduction
+
+Dates and times are represented in many different ways by cultures around the world. This includes differences in calendar systems, time zones, daylight saving time rules, date and time formatting, weekday and weekend rules, and much more. When building applications that support users around the world, it is important to handle these aspects correctly for each locale. The `@internationalized/date` package provides a library of objects and functions to perform date and time related manipulation, queries, and conversions that work across locales and calendars.
+
+By default, JavaScript represents dates and times using the [Date](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) object. However, `Date` has _many_ problems, including a very difficult to use API, lack of all internationalization support, and more. The [Temporal](https://tc39.es/proposal-temporal/docs/index.html) proposal will eventually address this in the language, and `@internationalized/date` is heavily inspired by it. We hope to back the objects in this package with it once it is implemented in browsers.
+
+## Package structure
+
+The `@internationalized/date` package includes the following object types:
+
+* [Calendar](https://react-specrum.adobe.com/internationalized/date/Calendar.html) – An interface which provides calendar conversion and metadata like number of days in month, and number of months in year. Many implementations are provided to support the most commonly used calendar systems.
+* [CalendarDate](https://react-specrum.adobe.com/internationalized/date/CalendarDate.html) – An immutable object that stores a date associated with a specific calendar system, without any time components.
+* [CalendarDateTime](https://react-specrum.adobe.com/internationalized/date/CalendarDateTime.html) – An immutable object that represents a date and time without a time zone, in a specific calendar system.
+* [ZonedDateTime](https://react-specrum.adobe.com/internationalized/date/ZonedDateTime.html) – An immutable object that represents a date and time in a specific time zone and calendar system.
+* [Time](https://react-specrum.adobe.com/internationalized/date/Time.html) – An immutable object that stores a clock time without any date components.
+
+Each object includes methods to allow basic manipulation and conversion functionality, such as adding and subtracting durations, and formatting as an ISO 8601 string. Additional less commonly used functions can be imported from the `@internationalized/date` package, and passed a date object as a parameter. This includes functions to parse ISO 8601 strings, query properties such as day of week, convert between time zones and much more. See the documentation for each of the objects to learn more about the supported methods and functions.
+
+This example constructs a `CalendarDate` object, manipulates it to get the start of the next week, and converts it to a string representation.
+
+```tsx
+import {CalendarDate, startOfWeek} from '@internationalized/date';
+
+let date = new CalendarDate(2022, 2, 3);
+date = date.add({weeks: 1});
+date = startOfWeek(date, 'en-US');
+date.toString(); // 2022-02-06
+```

src/calendars/JapaneseCalendar.ts

@@ -81,2 +81,3 @@ /*
     date.year -= ERA_ADDENDS[era];
+    this.constrainDate(date);
     return date as CalendarDate;
@@ -97,2 +98,5 @@ }
     }
+
+    // Constrain in case we went before the first supported era.
+    this.constrainDate(date);
   }
@@ -109,3 +113,3 @@
       let maxYear = endYear - ERA_ADDENDS[idx];
-      date.year = Math.min(maxYear, date.year);
+      date.year = Math.max(1, Math.min(maxYear, date.year));
       if (date.year === maxYear) {
@@ -112,0 +116,0 @@ date.month = Math.min(endMonth, date.month);

src/createCalendar.ts

@@ -24,2 +24,3 @@ /*
 
+/** Creates a `Calendar` instance from a Unicode calendar identifier string. */
 export function createCalendar(name: string): Calendar {
@@ -26,0 +27,0 @@ switch (name) {

src/queries.ts

@@ -130,2 +130,3 @@ /*
 
+/** Returns the first date of the month for the given date. */
 export function startOfMonth(date: ZonedDateTime): ZonedDateTime;
@@ -135,3 +136,2 @@ export function startOfMonth(date: CalendarDateTime): CalendarDateTime;
 export function startOfMonth(date: DateValue): DateValue;
-/** Returns the first date of the month for the given date. */
 export function startOfMonth(date: DateValue): DateValue {
@@ -142,2 +142,3 @@ // Use `subtract` instead of `set` so we don't get constrained in an era.
 
+/** Returns the last date of the month for the given date. */
 export function endOfMonth(date: ZonedDateTime): ZonedDateTime;
@@ -147,3 +148,2 @@ export function endOfMonth(date: CalendarDateTime): CalendarDateTime;
 export function endOfMonth(date: DateValue): DateValue;
-/** Returns the last date of the month for the given date. */
 export function endOfMonth(date: DateValue): DateValue {
@@ -153,2 +153,3 @@ return date.add({days: date.calendar.getDaysInMonth(date) - date.day});
 
+/** Returns the first day of the year for the given date. */
 export function startOfYear(date: ZonedDateTime): ZonedDateTime;
@@ -158,3 +159,2 @@ export function startOfYear(date: CalendarDateTime): CalendarDateTime;
 export function startOfYear(date: DateValue): DateValue;
-/** Returns the first day of the year for the given date. */
 export function startOfYear(date: DateValue): DateValue {
@@ -164,2 +164,3 @@ return startOfMonth(date.subtract({months: date.month - 1}));
 
+/** Returns the last day of the year for the given date. */
 export function endOfYear(date: ZonedDateTime): ZonedDateTime;
@@ -169,3 +170,2 @@ export function endOfYear(date: CalendarDateTime): CalendarDateTime;
 export function endOfYear(date: DateValue): DateValue;
-/** Returns the last day of the year for the given date. */
 export function endOfYear(date: DateValue): DateValue {
@@ -191,2 +191,3 @@ return endOfMonth(date.add({months: date.calendar.getMonthsInYear(date) - date.month}));
 
+/** Returns the first date of the week for the given date and locale. */
 export function startOfWeek(date: ZonedDateTime, locale: string): ZonedDateTime;
@@ -196,3 +197,2 @@ export function startOfWeek(date: CalendarDateTime, locale: string): CalendarDateTime;
 export function startOfWeek(date: DateValue, locale: string): DateValue;
-/** Returns the first date of the week for the given date and locale. */
 export function startOfWeek(date: DateValue, locale: string): DateValue {
@@ -203,6 +203,6 @@ let dayOfWeek = getDayOfWeek(date, locale);
 
+/** Returns the last date of the week for the given date and locale. */
 export function endOfWeek(date: ZonedDateTime, locale: string): ZonedDateTime;
 export function endOfWeek(date: CalendarDateTime, locale: string): CalendarDateTime;
 export function endOfWeek(date: CalendarDate, locale: string): CalendarDate;
-/** Returns the last date of the week for the given date and locale. */
 export function endOfWeek(date: DateValue, locale: string): DateValue {
@@ -209,0 +209,0 @@ return startOfWeek(date, locale).add({days: 6});

src/string.ts

@@ -26,2 +26,3 @@ /*
 
+/** Parses an ISO 8601 time string. */
 export function parseTime(value: string): Time {
@@ -41,2 +42,3 @@ let m = value.match(TIME_RE);
 
+/** Parses an ISO 8601 date string, with no time components. */
 export function parseDate(value: string): CalendarDate {
@@ -58,2 +60,3 @@ let m = value.match(DATE_RE);
 
+/** Parses an ISO 8601 date and time string, with no time zone. */
 export function parseDateTime(value: string): CalendarDateTime {
@@ -79,2 +82,8 @@ let m = value.match(DATE_TIME_RE);
 
+/**
+ * Parses an ISO 8601 date and time string with a time zone extension and optional UTC offset
+ * (e.g. "2021-11-07T00:45[America/Los_Angeles]" or "2021-11-07T00:45-07:00[America/Los_Angeles]").
+ * Ambiguous times due to daylight saving time transitions are resolved according to the `disambiguation`
+ * parameter.
+ */
 export function parseZonedDateTime(value: string, disambiguation?: Disambiguation): ZonedDateTime {
@@ -120,2 +129,6 @@ let m = value.match(ZONED_DATE_TIME_RE);
 
+/**
+ * Parses an ISO 8601 date and time string with a UTC offset (e.g. "2021-11-07T07:45:00Z"
+ * or "2021-11-07T07:45:00-07:00"). The result is converted to the provided time zone.
+ */
 export function parseAbsolute(value: string, timeZone: string): ZonedDateTime {
@@ -148,2 +161,6 @@ let m = value.match(ABSOLUTE_RE);
 
+/**
+ * Parses an ISO 8601 date and time string with a UTC offset (e.g. "2021-11-07T07:45:00Z"
+ * or "2021-11-07T07:45:00-07:00"). The result is converted to the user's local time zone.
+ */
 export function parseAbsoluteToLocal(value: string): ZonedDateTime {
@@ -150,0 +167,0 @@ return parseAbsolute(value, getLocalTimeZone());

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Manifest confusion

Supply chain risk

This package has inconsistent metadata. This could be malicious or caused by an error when publishing the package.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Manifest confusion

Supply chain risk

This package has inconsistent metadata. This could be malicious or caused by an error when publishing the package.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

801941

increased by1.26%

Lines of code

7952

increased by0.65%

Number of lines in readme file

45

increased by1025%

No dependency changes