@checkdigit/time 1.0.0

package/.github/workflows/ci.yml

@@ -0,0 +1,72 @@
+name: CI
+
+on:
+  pull_request:
+    branches:
+      - 'main'
+
+env:
+  CI: true
+
+jobs:
+  pullRequestBuild:
+    name: Pull Request Build
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: [16.x, 18.x]
+    steps:
+      - uses: actions/checkout@v3
+      - name: Use Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v3
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: 'npm'
+      - name: Install dependencies
+        run: npm ci --ignore-scripts
+        env:
+          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+      - name: Audit Signatures
+        run: npm audit signatures
+        env:
+          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+      - name: Compile
+        run: npm run ci:compile
+      - name: Check Code Style
+        run: npm run ci:style
+      - name: Perform Linting
+        run: npm run ci:lint
+      - name: Run Tests
+        run: npm run ci:test
+
+  branchBuild:
+    runs-on: ubuntu-latest
+    name: Branch Build
+    strategy:
+      matrix:
+        node-version: [16.x, 18.x]
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          ref: ${{ github.event.pull_request.head.sha }}
+      - name: Use Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v3
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: 'npm'
+      - name: Install dependencies
+        run: npm ci --ignore-scripts
+        env:
+          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+      - name: Audit Signatures
+        run: npm audit signatures
+        env:
+          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+      - name: Compile
+        run: npm run ci:compile
+      - name: Check Code Style
+        run: npm run ci:style
+      - name: Perform Linting
+        run: npm run ci:lint
+      - name: Run Tests
+        run: npm run ci:test

package/.github/workflows/codeql-analysis.yml

@@ -0,0 +1,31 @@
+name: 'CodeQL'
+
+on:
+  push:
+    branches: ['main']
+  pull_request:
+    branches: ['main']
+  schedule:
+    - cron: '22 7 * * 1'
+
+jobs:
+  analyze:
+    name: Analyze
+    runs-on: ubuntu-latest
+    permissions:
+      actions: read
+      contents: read
+      security-events: write
+    strategy:
+      fail-fast: false
+      matrix:
+        language: ['javascript']
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v3
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@v2
+        with:
+          languages: ${{ matrix.language }}
+      - name: Perform CodeQL Analysis
+        uses: github/codeql-action/analyze@v2

package/.github/workflows/coverage.yml

@@ -0,0 +1,46 @@
+name: Coverage
+
+on:
+  pull_request:
+    branches:
+      - 'main'
+
+env:
+  CI: true
+
+jobs:
+  branchBuild:
+    runs-on: ubuntu-latest
+    name: Branch Build
+    strategy:
+      matrix:
+        node-version: [16.x]
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          ref: ${{ github.event.pull_request.head.sha }}
+      - name: Use Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v3
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: 'npm'
+      - name: Install dependencies
+        run: npm ci --ignore-scripts
+        env:
+          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+      - name: Calculate Code Coverage
+        run: npm run ci:coverage
+      - name: Create Coverage Report for base branch
+        run: |
+          mv coverage/lcov.info coverage/lcov_head.info
+          git fetch
+          git checkout origin/${{ github.event.pull_request.base.ref }}
+          npm ci --ignore-scripts && npm run ci:coverage
+        env:
+          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+      - name: Post Coverage Report
+        uses: checkdigit/github-actions/coverage-reporter@main
+        with:
+          lcov-file: 'coverage/lcov_head.info'
+          lcov-base: 'coverage/lcov.info'
+          delete-old-comments: true

package/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License
+
+Copyright (c) 2022 Check Digit, LLC.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -0,0 +1,76 @@
+# Check Digit Time Library
+
+The Check Digit time library is the officially sanctioned method for Check Digit services to deal with time. It is a partial implementation of the new TC39 Temporal proposal
+and date manipulation functions provided by date-fns. Features:
+
+- Nanosecond precision date times, simulated with Node's built-in high-resolution timer
+- Tests that verify compliance with latest TC39 polyfill
+- Designed to be removed once Temporal is included, by default, within V8.
+- Implements most of Temporal.Instant, except timezone/calendar functionality
+- Implements Temporal.Now.instant()
+- Stripped down `date-fns` functions
+- `date-fns-tz` for timezone support
+- `formatUtc` for formatting UTC dates
+
+Temporal (vs the millisecond precision of standard Date built-in) is useful for webservices recording the time of events, where concurrent activity may occur and millisecond precision does not provide adequate uniqueness and ordering.
+
+The [`date-fns`](https://date-fns.org) library is included. The only locale currently supported is `en-US`, but otherwise contains all
+available functionality as of v2.29.1.
+
+Additionally, the [`date-fns-tz`](https://github.com/marnusw/date-fns-tz) library is included. Contains all
+available functionality as of v1.3.7.
+
+### `formatUtc`
+
+The `formatUtc` function is a wrapper around `date-fns-tz`'s `format` function, but with the following differences:
+
+- There is no `options` argument, `timeZone` is always UTC.
+
+Generally speaking, `formatUtc` should be used in place of `format` or `tzFormat`, unless non-UTC time zones are required.
+
+### Important note about `Instant.toString()`
+
+Unlike built-in `Date.toISOString()`, `Instant.toString()` will not add fractional second digits if those values are zero.
+
+E.g.
+
+```
+new Date(0).toISOString() -> 1970-01-01T00:00:00.100Z
+
+vs
+
+Temporal.Instant(0n).toString() -> 1970-01-01T00:00:00.1Z
+```
+
+### Why not just use the polyfill?
+
+The polyfill is not production ready. The implementation is designed to be used in the browser so cannot make use of Node's high-resolution timer to more accurately simulate nanosecond precision time. Crucially, the polyfill does not guarantee always increasing nanosecond precision times on subsequent calls, which makes it a non-starter for recording the time of events in production webservices.
+
+### Installing and usage
+
+`npm install @checkdigit/time` then:
+
+```
+import { Temporal } from '@checkdigit/time'; // delete this once Temporal becomes a built-in
+
+// print out nanosecond-precision ISO8601 datetime
+console.log('Current time', Temporal.Now.instant().toString());
+```
+
+For `date-fns` functionality:
+
+```
+import { formatUtc } from '@checkdigit/time';
+
+console.log(formatUtc(new Date(), 'yyyy-MM-dd'));
+```
+
+### Documentation
+
+The stage 3 proposal can be found here: https://github.com/tc39/proposal-temporal
+
+The reference documentation is here: https://tc39.es/proposal-temporal/docs/
+
+The documentation for `date-fns` is here: https://date-fns.org/
+
+The documentation for `date-fns-tz` is here: https://github.com/marnusw/date-fns-tz

package/SECURITY.md

@@ -0,0 +1,14 @@
+# Security Policy
+
+## Supported Versions
+
+These versions of `@checkdigit/time` are currently being supported with security updates.
+
+| Version | Supported          |
+| ------- | ------------------ |
+| \>= 1.x | :white_check_mark: |
+| < 1.0   | :x:                |
+
+## Reporting a Vulnerability
+
+Please create an issue at https://github.com/checkdigit/time/issues

package/dist/date-fns/_lib/addLeadingZeros/index.d.ts

@@ -0,0 +1 @@
+export default function addLeadingZeros(number: number, targetLength: number): string;

package/dist/date-fns/_lib/assign/index.d.ts

@@ -0,0 +1 @@
+export default function assign<T, U>(target: T, object: U): T & U;

package/dist/date-fns/_lib/cloneObject/index.d.ts

@@ -0,0 +1 @@
+export default function cloneObject<T>(object: T): T;

package/dist/date-fns/_lib/defaultLocale/index.d.ts

@@ -0,0 +1,2 @@
+import defaultLocale from '../../locale/en-US/index';
+export default defaultLocale;

package/dist/date-fns/_lib/defaultOptions/index.d.ts

@@ -0,0 +1,4 @@
+import type { FirstWeekContainsDateOptions, LocaleOptions, WeekStartOptions } from '../../types';
+export declare type DefaultOptions = LocaleOptions & WeekStartOptions & FirstWeekContainsDateOptions;
+export declare function getDefaultOptions(): DefaultOptions;
+export declare function setDefaultOptions(newOptions: DefaultOptions): void;

package/dist/date-fns/_lib/format/formatters/index.d.ts

@@ -0,0 +1,9 @@
+import type { Localize } from '../../../locale/types';
+import type { FirstWeekContainsDateOptions, LocaleOptions, WeekStartOptions } from '../../../types';
+declare type Formatter = (date: Date, token: string, localize: Localize, options: Required<LocaleOptions & WeekStartOptions & FirstWeekContainsDateOptions> & {
+    _originalDate: Date;
+}) => string;
+declare const formatters: {
+    [token: string]: Formatter;
+};
+export default formatters;

package/dist/date-fns/_lib/format/lightFormatters/index.d.ts

@@ -0,0 +1,12 @@
+declare const formatters: {
+    y(date: Date, token: string): string;
+    M(date: Date, token: string): string;
+    d(date: Date, token: string): string;
+    a(date: Date, token: string): string;
+    h(date: Date, token: string): string;
+    H(date: Date, token: string): string;
+    m(date: Date, token: string): string;
+    s(date: Date, token: string): string;
+    S(date: Date, token: string): string;
+};
+export default formatters;

package/dist/date-fns/_lib/format/longFormatters/index.d.ts

@@ -0,0 +1,4 @@
+import type { FormatLong } from '../../../locale/types';
+declare type LongFormatter = (pattern: string, formatLong: FormatLong) => string;
+declare const longFormatters: Record<string, LongFormatter>;
+export default longFormatters;

package/dist/date-fns/_lib/getTimezoneOffsetInMilliseconds/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Google Chrome as of 67.0.3396.87 introduced timezones with offset that includes seconds.
+ * They usually appear for dates that denote time before the timezones were introduced
+ * (e.g. for 'Europe/Prague' timezone the offset is GMT+00:57:44 before 1 October 1891
+ * and GMT+01:00:00 after that date)
+ *
+ * Date#getTimezoneOffset returns the offset in minutes and would return 57 for the example above,
+ * which would lead to incorrect calculations.
+ *
+ * This function returns the timezone offset in milliseconds that takes seconds in account.
+ */
+export default function getTimezoneOffsetInMilliseconds(date: Date): number;

package/dist/date-fns/_lib/protectedTokens/index.d.ts

@@ -0,0 +1,3 @@
+export declare function isProtectedDayOfYearToken(token: string): boolean;
+export declare function isProtectedWeekYearToken(token: string): boolean;
+export declare function throwProtectedError(token: string, format: string, input: string): void;

package/dist/date-fns/_lib/roundingMethods/index.d.ts

@@ -0,0 +1,2 @@
+import type { RoundingMethod } from '../../types';
+export declare function getRoundingMethod(method: RoundingMethod | undefined): (x: number) => number;

package/dist/date-fns/add/index.d.ts

@@ -0,0 +1,40 @@
+import type { Duration } from '../types';
+/**
+ * @name add
+ * @category Common Helpers
+ * @summary Add the specified years, months, weeks, days, hours, minutes and seconds to the given date.
+ *
+ * @description
+ * Add the specified years, months, weeks, days, hours, minutes and seconds to the given date.
+ *
+ * @param date - the date to be changed
+ * @param duration - the object with years, months, weeks, days, hours, minutes and seconds to be added. Positive decimals will be rounded using `Math.floor`, decimals less than zero will be rounded using `Math.ceil`.
+ *
+ * | Key            | Description                        |
+ * |----------------|------------------------------------|
+ * | years          | Amount of years to be added        |
+ * | months         | Amount of months to be added       |
+ * | weeks          | Amount of weeks to be added        |
+ * | days           | Amount of days to be added         |
+ * | hours          | Amount of hours to be added        |
+ * | minutes        | Amount of minutes to be added      |
+ * | seconds        | Amount of seconds to be added      |
+ *
+ * All values default to 0
+ *
+ * @returns the new date with the seconds added
+ *
+ * @example
+ * // Add the following duration to 1 September 2014, 10:19:50
+ * const result = add(new Date(2014, 8, 1, 10, 19, 50), {
+ *   years: 2,
+ *   months: 9,
+ *   weeks: 1,
+ *   days: 7,
+ *   hours: 5,
+ *   minutes: 9,
+ *   seconds: 30,
+ * })
+ * //=> Thu Jun 15 2017 15:29:20
+ */
+export default function add<DateType extends Date>(dirtyDate: DateType | number, duration: Duration): DateType;

package/dist/date-fns/addBusinessDays/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @name addBusinessDays
+ * @category Date Extension Helpers
+ * @summary Add the specified number of business days (mon - fri) to the given date.
+ *
+ * @description
+ * Add the specified number of business days (mon - fri) to the given date, ignoring weekends.
+ *
+ * @param date - the date to be changed
+ * @param amount - the amount of business days to be added. Positive decimals will be rounded using `Math.floor`, decimals less than zero will be rounded using `Math.ceil`.
+ * @returns the new date with the business days added
+ *
+ * @example
+ * // Add 10 business days to 1 September 2014:
+ * const result = addBusinessDays(new Date(2014, 8, 1), 10)
+ * //=> Mon Sep 15 2014 00:00:00 (skipped weekend days)
+ */
+export default function addBusinessDays<DateType extends Date>(dirtyDate: DateType | number, amount: number): DateType;

package/dist/date-fns/addDays/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @name addDays
+ * @category Day Helpers
+ * @summary Add the specified number of days to the given date.
+ *
+ * @description
+ * Add the specified number of days to the given date.
+ *
+ * @param date - the date to be changed
+ * @param amount - the amount of days to be added. Positive decimals will be rounded using `Math.floor`, decimals less than zero will be rounded using `Math.ceil`.
+ * @returns - the new date with the days added
+ *
+ * @example
+ * // Add 10 days to 1 September 2014:
+ * const result = addDays(new Date(2014, 8, 1), 10)
+ * //=> Thu Sep 11 2014 00:00:00
+ */
+export default function addDays<DateType extends Date>(dirtyDate: DateType | number, amount: number): DateType;

package/dist/date-fns/addHours/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @name addHours
+ * @category Hour Helpers
+ * @summary Add the specified number of hours to the given date.
+ *
+ * @description
+ * Add the specified number of hours to the given date.
+ *
+ * @param date - the date to be changed
+ * @param amount - the amount of hours to be added. Positive decimals will be rounded using `Math.floor`, decimals less than zero will be rounded using `Math.ceil`.
+ * @returns the new date with the hours added
+ *
+ * @example
+ * // Add 2 hours to 10 July 2014 23:00:00:
+ * const result = addHours(new Date(2014, 6, 10, 23, 0), 2)
+ * //=> Fri Jul 11 2014 01:00:00
+ */
+export default function addHours<DateType extends Date>(dirtyDate: DateType | number, amount: number): DateType;

package/dist/date-fns/addISOWeekYears/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @name addISOWeekYears
+ * @category ISO Week-Numbering Year Helpers
+ * @summary Add the specified number of ISO week-numbering years to the given date.
+ *
+ * @description
+ * Add the specified number of ISO week-numbering years to the given date.
+ *
+ * ISO week-numbering year: http://en.wikipedia.org/wiki/ISO_week_date
+ *
+ * @param date - the date to be changed
+ * @param amount - the amount of ISO week-numbering years to be added. Positive decimals will be rounded using `Math.floor`, decimals less than zero will be rounded using `Math.ceil`.
+ * @returns the new date with the ISO week-numbering years added
+ *
+ * @example
+ * // Add 5 ISO week-numbering years to 2 July 2010:
+ * const result = addISOWeekYears(new Date(2010, 6, 2), 5)
+ * //=> Fri Jn 26 2015 00:00:00
+ */
+export default function addISOWeekYears<DateType extends Date>(dirtyDate: DateType | number, amount: number): DateType;

package/dist/date-fns/addMilliseconds/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @name addMilliseconds
+ * @category Millisecond Helpers
+ * @summary Add the specified number of milliseconds to the given date.
+ *
+ * @description
+ * Add the specified number of milliseconds to the given date.
+ *
+ * @param date - the date to be changed
+ * @param amount - the amount of milliseconds to be added. Positive decimals will be rounded using `Math.floor`, decimals less than zero will be rounded using `Math.ceil`.
+ * @returns the new date with the milliseconds added
+ *
+ * @example
+ * // Add 750 milliseconds to 10 July 2014 12:45:30.000:
+ * const result = addMilliseconds(new Date(2014, 6, 10, 12, 45, 30, 0), 750)
+ * //=> Thu Jul 10 2014 12:45:30.750
+ */
+export default function addMilliseconds<DateType extends Date>(dirtyDate: DateType | number, amount: number): DateType;

package/dist/date-fns/addMinutes/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @name addMinutes
+ * @category Minute Helpers
+ * @summary Add the specified number of minutes to the given date.
+ *
+ * @description
+ * Add the specified number of minutes to the given date.
+ *
+ * @param date - the date to be changed
+ * @param amount - the amount of minutes to be added. Positive decimals will be rounded using `Math.floor`, decimals less than zero will be rounded using `Math.ceil`.
+ * @returns the new date with the minutes added
+ *
+ * @example
+ * // Add 30 minutes to 10 July 2014 12:00:00:
+ * const result = addMinutes(new Date(2014, 6, 10, 12, 0), 30)
+ * //=> Thu Jul 10 2014 12:30:00
+ */
+export default function addMinutes<DateType extends Date>(dirtyDate: DateType | number, amount: number): DateType;

package/dist/date-fns/addMonths/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @name addMonths
+ * @category Month Helpers
+ * @summary Add the specified number of months to the given date.
+ *
+ * @description
+ * Add the specified number of months to the given date.
+ *
+ * @param date - the date to be changed
+ * @param amount - the amount of months to be added. Positive decimals will be rounded using `Math.floor`, decimals less than zero will be rounded using `Math.ceil`.
+ * @returns the new date with the months added
+ *
+ * @example
+ * // Add 5 months to 1 September 2014:
+ * const result = addMonths(new Date(2014, 8, 1), 5)
+ * //=> Sun Feb 01 2015 00:00:00
+ */
+export default function addMonths<DateType extends Date>(dirtyDate: DateType | number, amount: number): DateType;

package/dist/date-fns/addQuarters/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @name addQuarters
+ * @category Quarter Helpers
+ * @summary Add the specified number of year quarters to the given date.
+ *
+ * @description
+ * Add the specified number of year quarters to the given date.
+ *
+ * @param date - the date to be changed
+ * @param amount - the amount of quarters to be added. Positive decimals will be rounded using `Math.floor`, decimals less than zero will be rounded using `Math.ceil`.
+ * @returns the new date with the quarters added
+ *
+ * @example
+ * // Add 1 quarter to 1 September 2014:
+ * const result = addQuarters(new Date(2014, 8, 1), 1)
+ * //=> Mon Dec 01 2014 00:00:00
+ */
+export default function addQuarters<DateType extends Date>(dirtyDate: DateType | number, amount: number): DateType;

package/dist/date-fns/addSeconds/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @name addSeconds
+ * @category Second Helpers
+ * @summary Add the specified number of seconds to the given date.
+ *
+ * @description
+ * Add the specified number of seconds to the given date.
+ *
+ * @param date - the date to be changed
+ * @param amount - the amount of seconds to be added. Positive decimals will be rounded using `Math.floor`, decimals less than zero will be rounded using `Math.ceil`.
+ * @returns the new date with the seconds added
+ *
+ * @example
+ * // Add 30 seconds to 10 July 2014 12:45:00:
+ * const result = addSeconds(new Date(2014, 6, 10, 12, 45, 0), 30)
+ * //=> Thu Jul 10 2014 12:45:30
+ */
+export default function addSeconds<DateType extends Date>(dirtyDate: DateType | number, amount: number): DateType;

package/dist/date-fns/addWeeks/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @name addWeeks
+ * @category Week Helpers
+ * @summary Add the specified number of weeks to the given date.
+ *
+ * @description
+ * Add the specified number of week to the given date.
+ *
+ * @param date - the date to be changed
+ * @param amount - the amount of weeks to be added. Positive decimals will be rounded using `Math.floor`, decimals less than zero will be rounded using `Math.ceil`.
+ * @returns the new date with the weeks added
+ *
+ * @example
+ * // Add 4 weeks to 1 September 2014:
+ * const result = addWeeks(new Date(2014, 8, 1), 4)
+ * //=> Mon Sep 29 2014 00:00:00
+ */
+export default function addWeeks<DateType extends Date>(dirtyDate: DateType | number, amount: number): DateType;

package/dist/date-fns/addYears/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @name addYears
+ * @category Year Helpers
+ * @summary Add the specified number of years to the given date.
+ *
+ * @description
+ * Add the specified number of years to the given date.
+ *
+ * @param date - the date to be changed
+ * @param amount - the amount of years to be added. Positive decimals will be rounded using `Math.floor`, decimals less than zero will be rounded using `Math.ceil`.
+ * @returns the new date with the years added
+ *
+ * @example
+ * // Add 5 years to 1 September 2014:
+ * const result = addYears(new Date(2014, 8, 1), 5)
+ * //=> Sun Sep 01 2019 00:00:00
+ */
+export default function addYears<DateType extends Date>(dirtyDate: DateType | number, amount: number): DateType;

package/dist/date-fns/areIntervalsOverlapping/index.d.ts

@@ -0,0 +1,61 @@
+import type { Interval } from '../types';
+/**
+ * The {@link areIntervalsOverlapping} function options.
+ */
+export interface AreIntervalsOverlappingOptions {
+    inclusive?: boolean;
+}
+/**
+ * @name areIntervalsOverlapping
+ * @category Interval Helpers
+ * @summary Is the given time interval overlapping with another time interval?
+ *
+ * @description
+ * Is the given time interval overlapping with another time interval? Adjacent intervals do not count as overlapping.
+ *
+ * @param intervalLeft - the first interval to compare. See [Interval]{@link https://date-fns.org/docs/Interval}
+ * @param intervalRight - the second interval to compare. See [Interval]{@link https://date-fns.org/docs/Interval}
+ * @param options - the object with options
+ * @returns whether the time intervals are overlapping
+ * @throws {RangeError} The start of an interval cannot be after its end
+ * @throws {RangeError} Date in interval cannot be `Invalid Date`
+ *
+ * @example
+ * // For overlapping time intervals:
+ * areIntervalsOverlapping(
+ *   { start: new Date(2014, 0, 10), end: new Date(2014, 0, 20) },
+ *   { start: new Date(2014, 0, 17), end: new Date(2014, 0, 21) }
+ * )
+ * //=> true
+ *
+ * @example
+ * // For non-overlapping time intervals:
+ * areIntervalsOverlapping(
+ *   { start: new Date(2014, 0, 10), end: new Date(2014, 0, 20) },
+ *   { start: new Date(2014, 0, 21), end: new Date(2014, 0, 22) }
+ * )
+ * //=> false
+ *
+ * @example
+ * // For adjacent time intervals:
+ * areIntervalsOverlapping(
+ *   { start: new Date(2014, 0, 10), end: new Date(2014, 0, 20) },
+ *   { start: new Date(2014, 0, 20), end: new Date(2014, 0, 30) }
+ * )
+ * //=> false
+ *
+ * @example
+ * // Using the inclusive option:
+ * areIntervalsOverlapping(
+ *   { start: new Date(2014, 0, 10), end: new Date(2014, 0, 20) },
+ *   { start: new Date(2014, 0, 20), end: new Date(2014, 0, 24) }
+ * )
+ * //=> false
+ * areIntervalsOverlapping(
+ *   { start: new Date(2014, 0, 10), end: new Date(2014, 0, 20) },
+ *   { start: new Date(2014, 0, 20), end: new Date(2014, 0, 24) },
+ *   { inclusive: true }
+ * )
+ * //=> true
+ */
+export default function areIntervalsOverlapping(intervalLeft: Interval, intervalRight: Interval, options?: AreIntervalsOverlappingOptions): boolean;