Sunorhc is a date-time library for JavaScript

Handling of year and month

Sunorhc instantiates the year as it is given, regardless of whether it is before or after C.E. There is no automatic mapping of two-digit years from 0 to 99 to 1900 or later, as there is with Date objects. It is easy to handle the year B.C. with negative years, but keep in mind that the year 1 BCE. will be 0.
Also, the months January through December in Sunorhc are directly interpreted as values 1 through 12. This is true for both input and output, although it is important to note that the index values for months in the Date object are 0-11, making it more intuitive to handle dates.

Dealing with Time Zones

In principle, the time zone of the date and time handled by Sunorhc instances is “UTC”. Sunorhc supports only “UTC” and other “local” time zones.
Sunorhc internally manages only the time zone offset, retrieving the time zone offset value on the system and generating the instance date and time according to that value. You can also specify a time zone name other than “local” that conforms to the Time Zone Database managed by IANA, but Sunorhc internally handles all time zone offset values other than 0 as “local”.

Observing of DST

When dealing with local time in Sunorhc instances, Daylight Saving Time (DST), which depends on some time zones, is supported. local time instantiated in Sunorhc includes the DST time difference, and the internally managed The time zone offset managed internally is also affected by the DST time difference. The details of whether the instance’s date and time are in DST and the time difference if they are in DST can be obtained via immediate properties, getters, and instance methods.
Note that DST will not be generated for dates and times instantiated with a time zone of “UTC”.

An Instance Construction

The specification of the instance created by the constructor of Sunorhc is as shown in the example below.
As an environment example, let’s assume that the system time zone is Asia/Tokyo (Japan Standard Time: UTC+09:00) and the current local time zone date and time (Japan Standard Time) is 2021-08-25 21:13:00.771.

1. The “example argument” is payloads of “args…” given to new Sunorhc(args...).
2. The “instance datetime” is the string that can be retrieved with the getter toISOString.
3. Information about the “Instance TimeZone” can be retrieved with the getters timezone and tzOffset.

As this example shows, Sunorhc does not handle dates and times in the local time zone in instances unless a time zone argument (such as local) is given to the constructor.
Note that you can use the getter toDate to convert a Sunorhc instance to a Date object, or use the instance methods getUTC() and getZoned() to convert the date and time between UTC and local time zone.

About Primitive Value

The primitive value of Sunorhc will be an instance of the native JavaScript Date object created by the constructor. As an entity, it is equivalent to the primitive value of the Date object, a number representing the number of milliseconds elapsed since the UNIX epoch.
If you want to reference a primitive value directly from an instance, you can use new Sunorhc(). _baseDate, but this reference is not recommended in many cases. Because the value stored in the _baseDate property is an instance of a pure Date object before it is finalized as a Sunorhc instance, and thus it is not consistent with the values of immediate properties, getters, and instance methods.
Normally, the _baseDate property should be made a private property, but Sunorhc does not require such robustness as a library.
As for the actual instance of using Sunorhc, the instant property described next plays a role.

Instant Property

The instance created by Sunorhc holds an instant object called instant property. This object contains various element snippets of the instantiated date and time data. The elements included in the instant property are as follows.

1. The acquisition unit can be specified in the constructor argument epochUnit. The initial value is seconds.

The instant property is an immutable value as well as the date and time data held internally. Basically, the various getters are like aliases for retrieving these instant properties with interactive descriptions.

Supported Browsers

The actual working environment and supported browsers of Sunorhc are as follows.

1. Note: “Intl.Locale” object is not supported by native JavaScript in Safari 13, so a separate Polyfill is required for formatter language resolution.

Please note that we have not checked the operation of the software on legacy browsers such as IE. We do not plan to provide support for these legacy browsers.

Installations

NPM

npm install sunorhc

If you are using Yarn, it will be yarn add sunorhc.

GitHub

git clone https://github.com/ka215/sunorhc.git

The built JS files are stored in the dist directory of the repository.

Usage

Sunorhc can be used by itself by loading the script file after it is built.

Node

const Sunorhc = require('sunorhc') 

const NOW_UTC = new Sunorhc()

ES6

import Sunorhc from 'sunorhc'

const NOW_ZONED = new Sunorhc('local')

HTML5

<script src="/path/to/sunorhc.min.js"></script>
<script>
const NOW_UTC = new Sunorhc()
</script>

It is also possible to load via CDN.

<script src="https://unpkg.com/sunorhc@latest/dist/sunorhc.min.js"></script>

Examples of Use

Constructor

const NOW_UTC = new Sunorhc()

const DateTime = new Sunorhc(2021, 8, 23, 22, 57, 'local')
console.log(DataTime.toISOString) //=> 2021-08-23T22:57:00.000+09:00

const DT1 = new Sunorhc(123456789000, { firstArgument: "timestamp" }),
      DT2 = new Sunorhc(123456789000, { firstArgument: "ceepoch" })
console.log(
  DT1.toISOString, //=> 1973-11-29T21:33:09.000Z
  DT2.toISOString, //=> 0004-11-29T21:33:09.000Z
)

Getter

const NOW_UTC = new Sunorhc()

console.log(
  NOW_UTC.toISOString, //=> 2021-08-23T14:11:34.249Z
  NOW_UTC.monthLong, //=> August
  NOW_UTC.weekdayLong, //=> Monday
  NOW_UTC.hour, //=> 14
  NOW_UTC.tzOffsetHM, //=> +00:00
  NOW_UTC.era, //=> 8 23, 2021 Anno Domini
)

Instance Methods

const DateTime = new Sunorhc()

console.log(
  DateTime.format('Y-m-d H:i:s'), //=> 2021-08-23 15:21:02
  DateTime.getLDE('weekday', 'long', 'en-US'), //=> Monday
  DateTime.modify(+1, 'month').toISOString, //=> 2021-09-23T15:24:20.070Z
  DateTime.modify(-1, 'day').toString, //=> Sun Aug 22 2021 15:24:20 GMT+0000 (UTC)
  DateTime.interval('2021-10-20', 'day'), //=> 58
  DateTime.getISO('ordinal'), //=> 2021-234
)

Documentations

Sorry, currently writing the manual document.

Repository

https://github.com/ka215/sunorhc

https://www.npmjs.com/package/sunorhc

Lisence

Code released under the MIT License.