date-vir 1.0.0 → 2.0.0

package/README.md

@@ -4,6 +4,8 @@ Easy dates and times with explicit timezones (and typed timezones).
 
 `date-vir` revolves around the new `FullDate` type, which includes all the information you need to correctly pinpoint _and_ format a given point in time. Most notably, `FullDate` always includes a `timezone` property, so you _always_ know what timezone the date was originally defined in, or what timezone the date is intended to be used in:
 
+Full docs: http://electrovir.github.io/date-vir
+
 <!-- example-link: src/readme-examples/full-date.example.ts -->
 
 ```TypeScript

package/dist/cjs/date-operations/calculate-relative-date.js

@@ -2,7 +2,11 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.calculateRelativeDate = void 0;
 const luxon_date_time_conversion_1 = require("../full-date/luxon-date-time-conversion");
-function calculateRelativeDate(fullDate, relativeCalculation) {
-    return (0, luxon_date_time_conversion_1.parseLuxonDateTime)((0, luxon_date_time_conversion_1.toLuxonDateTime)(fullDate).plus(relativeCalculation));
+/**
+ * Calculates a new date starting at the given fullDate and adding the given offsets. Offsets can be
+ * negative to go backwards in time.
+ */
+function calculateRelativeDate(fullDate, offset) {
+    return (0, luxon_date_time_conversion_1.parseLuxonDateTime)((0, luxon_date_time_conversion_1.toLuxonDateTime)(fullDate).plus(offset));
 }
 exports.calculateRelativeDate = calculateRelativeDate;

package/dist/cjs/date-operations/combine-dates.js

@@ -3,6 +3,11 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.combineDateParts = void 0;
 const object_shape_tester_1 = require("object-shape-tester");
 const full_date_shape_1 = require("../full-date/full-date-shape");
+/**
+ * Combine two parts of a FullDate objects into a filled-in FullDate. Note that the timezones must
+ * match for both inputs. If two complete FullDate objects are passed in, only the respective parts
+ * of each is used.
+ */
 function combineDateParts(maybeDateParts) {
     const timePart = (0, object_shape_tester_1.isValidShape)(maybeDateParts.time, full_date_shape_1.timePartShape, {
         allowExtraKeys: true,

package/dist/cjs/{full-date → extra-utils}/js-date-conversion.js

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.toJsDate = void 0;
-const primitive_conversions_1 = require("./primitive-conversions");
+const primitive_conversions_1 = require("../full-date/primitive-conversions");
 function toJsDate(fullDate) {
     return new Date((0, primitive_conversions_1.toTimestamp)(fullDate));
 }

package/dist/cjs/extra-utils/{now-in-iso-string.js → now.js}

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getNowInIsoString = void 0;
+exports.getNowInUserTimezone = exports.getNowInIsoString = void 0;
 const create_full_date_1 = require("../full-date/create-full-date");
 const primitive_conversions_1 = require("../full-date/primitive-conversions");
 const timezones_1 = require("../timezone/timezones");
@@ -12,3 +12,7 @@ function getNowInIsoString() {
     return (0, primitive_conversions_1.toIsoString)((0, create_full_date_1.getNowFullDate)(timezones_1.utcTimezone));
 }
 exports.getNowInIsoString = getNowInIsoString;
+function getNowInUserTimezone() {
+    return (0, create_full_date_1.getNowFullDate)(timezones_1.userTimezone);
+}
+exports.getNowInUserTimezone = getNowInUserTimezone;

package/dist/cjs/extra-utils/zero.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.clearParts = exports.clearTime = exports.zeroTime = exports.zeroDate = void 0;
+const common_1 = require("@augment-vir/common");
+const full_date_shape_1 = require("../full-date/full-date-shape");
+const date_transforms_1 = require("./date-transforms");
+exports.zeroDate = {
+    year: 0,
+    month: 1,
+    day: 1,
+    hour: 0,
+    minute: 0,
+    second: 0,
+    millisecond: 0,
+};
+exports.zeroTime = (0, common_1.pickObjectKeys)(exports.zeroDate, full_date_shape_1.timeFullDateKeys);
+function clearTime(inputFullDate) {
+    return clearParts(inputFullDate, full_date_shape_1.timeFullDateKeys);
+}
+exports.clearTime = clearTime;
+function clearParts(inputFullDate, parts) {
+    const clearParts = (0, common_1.typedObjectFromEntries)(parts.map((keyName) => {
+        return [
+            keyName,
+            exports.zeroDate[keyName],
+        ];
+    }));
+    return (0, date_transforms_1.overrideDateParts)(inputFullDate, clearParts);
+}
+exports.clearParts = clearParts;

package/dist/cjs/full-date/full-date-shape.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.fullDateShape = exports.datePartShape = exports.timePartShape = exports.FullDatePartEnum = void 0;
+exports.fullDateShape = exports.datePartShape = exports.timePartShape = exports.dateFullDateKeys = exports.timeFullDateKeys = exports.FullDatePartEnum = void 0;
 const object_shape_tester_1 = require("object-shape-tester");
 const timezones_1 = require("../timezone/timezones");
 /**
@@ -13,15 +13,26 @@ var FullDatePartEnum;
     FullDatePartEnum["Time"] = "time";
     FullDatePartEnum["DateTime"] = "datetime-local";
 })(FullDatePartEnum || (exports.FullDatePartEnum = FullDatePartEnum = {}));
+exports.timeFullDateKeys = [
+    'hour',
+    'minute',
+    'second',
+    'millisecond',
+];
+exports.dateFullDateKeys = [
+    'year',
+    'month',
+    'day',
+];
 exports.timePartShape = (0, object_shape_tester_1.defineShape)({
     /** Hour of the day in 24 time: 0-23 */
     hour: 14,
     /** Minute of the hour: 0-59 */
     minute: 19,
     /** Second of the minute: 0-59 */
-    second: 0,
+    second: 7,
     /** Millisecond of the second: 0-999 */
-    millisecond: 870,
+    millisecond: 877,
     /** The timezone that this date/time is meant for / originated from. */
     timezone: timezones_1.utcTimezone,
 });

package/dist/cjs/index.js

@@ -17,14 +17,16 @@ Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./date-operations/calculate-relative-date"), exports);
 __exportStar(require("./date-operations/combine-dates"), exports);
 __exportStar(require("./date-operations/diff-dates"), exports);
-__exportStar(require("./extra-utils/now-in-iso-string"), exports);
+__exportStar(require("./duration"), exports);
+__exportStar(require("./extra-utils/date-transforms"), exports);
+__exportStar(require("./extra-utils/js-date-conversion"), exports);
+__exportStar(require("./extra-utils/now"), exports);
+__exportStar(require("./extra-utils/zero"), exports);
 __exportStar(require("./full-date/create-full-date"), exports);
 __exportStar(require("./full-date/date-like"), exports);
-__exportStar(require("./full-date/date-transforms"), exports);
 __exportStar(require("./full-date/format-presets"), exports);
 __exportStar(require("./full-date/full-date-shape"), exports);
 __exportStar(require("./full-date/is-valid-full-date"), exports);
-__exportStar(require("./full-date/js-date-conversion"), exports);
 __exportStar(require("./full-date/luxon-date-time-conversion"), exports);
 __exportStar(require("./full-date/parsing"), exports);
 __exportStar(require("./full-date/primitive-conversions"), exports);

package/dist/esm/date-operations/calculate-relative-date.d.ts

@@ -1,3 +1,7 @@
+import { AnyDuration } from '../duration';
 import { FullDate } from '../full-date/full-date-shape';
-import { RelativeTimeDuration } from '../relative-time-duration';
-export declare function calculateRelativeDate(fullDate: FullDate, relativeCalculation: RelativeTimeDuration): FullDate;
+/**
+ * Calculates a new date starting at the given fullDate and adding the given offsets. Offsets can be
+ * negative to go backwards in time.
+ */
+export declare function calculateRelativeDate(fullDate: Readonly<FullDate>, offset: Readonly<AnyDuration>): FullDate;

package/dist/esm/date-operations/calculate-relative-date.js

@@ -1,4 +1,8 @@
 import { parseLuxonDateTime, toLuxonDateTime } from '../full-date/luxon-date-time-conversion';
-export function calculateRelativeDate(fullDate, relativeCalculation) {
-    return parseLuxonDateTime(toLuxonDateTime(fullDate).plus(relativeCalculation));
+/**
+ * Calculates a new date starting at the given fullDate and adding the given offsets. Offsets can be
+ * negative to go backwards in time.
+ */
+export function calculateRelativeDate(fullDate, offset) {
+    return parseLuxonDateTime(toLuxonDateTime(fullDate).plus(offset));
 }

package/dist/esm/date-operations/combine-dates.d.ts

@@ -1,14 +1,11 @@
 import { DatePart, FullDate, FullDatePartEnum, TimePart } from '../full-date/full-date-shape';
+/** An object containing date and/or time parts or neither. */
 type MaybeDateParts = Partial<{
     [FullDatePartEnum.Date]: DatePart | undefined | Partial<FullDate>;
     [FullDatePartEnum.Time]: TimePart | undefined | Partial<FullDate>;
 }>;
+/** A full date, time or date parts of a date, or undefined. */
 export type MaybeDatePart = FullDate | Partial<FullDate> | DatePart | TimePart | undefined;
-/**
- * Combine two parts of a FullDate objects into a filled-in FullDate. Note that the timezones must
- * match for both inputs. If two complete FullDate objects are passed in, only the respective parts
- * of each is used.
- */
 export declare function combineDateParts(maybeDateParts: {
     [FullDatePartEnum.Date]: DatePart;
     [FullDatePartEnum.Time]: TimePart;

package/dist/esm/date-operations/combine-dates.js

@@ -1,5 +1,10 @@
 import { isValidShape } from 'object-shape-tester';
 import { FullDatePartEnum, datePartShape, timePartShape, } from '../full-date/full-date-shape';
+/**
+ * Combine two parts of a FullDate objects into a filled-in FullDate. Note that the timezones must
+ * match for both inputs. If two complete FullDate objects are passed in, only the respective parts
+ * of each is used.
+ */
 export function combineDateParts(maybeDateParts) {
     const timePart = isValidShape(maybeDateParts.time, timePartShape, {
         allowExtraKeys: true,

package/dist/esm/date-operations/diff-dates.d.ts

@@ -1,6 +1,6 @@
-import { AtLeastTuple, RequiredAndNotNull } from '@augment-vir/common';
+import { AtLeastTuple } from '@augment-vir/common';
+import { Duration } from '../duration';
 import { FullDate } from '../full-date/full-date-shape';
-import { RelativeTimeDuration } from '../relative-time-duration';
 export type MaybeTuple<T> = T | AtLeastTuple<T, 1>;
 /**
  * Exclude the higher order units of time measure for diffing because they vary significantly,
@@ -18,13 +18,11 @@ export declare enum DiffUnit {
     Seconds = "seconds",
     Milliseconds = "milliseconds"
 }
-export type DiffDuration<DurationKeys extends MaybeTuple<DiffUnit>> = MaybeTuple<DiffUnit> extends DurationKeys ? Pick<RelativeTimeDuration, DiffUnit> : Pick<RequiredAndNotNull<RelativeTimeDuration>, DurationKeys extends AtLeastTuple<infer InnerValue, 1> ? InnerValue : DurationKeys>;
-export type Duration<DurationKeys extends MaybeTuple<DiffUnit>> = DiffDuration<DurationKeys>;
 export declare function diffDates<const DurationKeys extends MaybeTuple<DiffUnit> = MaybeTuple<DiffUnit>>({ start, end, unit, }: {
     start: FullDate;
     end: FullDate;
     unit: DurationKeys;
-}): DiffDuration<DurationKeys>;
+}): Duration<DurationKeys>;
 export declare function isDateAfter({ start, end }: {
     start: FullDate;
     end: FullDate;

package/dist/esm/duration.d.ts

@@ -0,0 +1,11 @@
+import { AtLeastTuple, RequiredAndNotNull } from '@augment-vir/common';
+import { DurationObjectUnits } from 'luxon';
+import { DiffUnit, MaybeTuple } from './date-operations/diff-dates';
+/** All possible options for the more strict Duration type. */
+export type AnyDuration = DurationObjectUnits;
+/**
+ * Not a single date instance, but a description of a date duration. Used to calculate diffs between
+ * dates, or add offsets to an existing date, or describe a single time duration. Usually only one
+ * property is set on this at any given time.
+ */
+export type Duration<DurationKeys extends MaybeTuple<DiffUnit>> = MaybeTuple<DiffUnit> extends DurationKeys ? Pick<AnyDuration, DiffUnit> : Pick<RequiredAndNotNull<AnyDuration>, DurationKeys extends AtLeastTuple<infer InnerValue, 1> ? InnerValue : DurationKeys>;

package/dist/esm/{full-date → extra-utils}/date-transforms.d.ts

@@ -1,3 +1,3 @@
-import { FullDate } from './full-date-shape';
+import { FullDate } from '../full-date/full-date-shape';
 /** Override the initial provided FullDate with all subsequent FullDate parts. */
 export declare function overrideDateParts(date: FullDate, ...overrides: Partial<FullDate>[]): FullDate;

package/dist/esm/{full-date → extra-utils}/js-date-conversion.d.ts

@@ -1,2 +1,2 @@
-import { FullDate } from './full-date-shape';
+import { FullDate } from '../full-date/full-date-shape';
 export declare function toJsDate(fullDate: FullDate): Date;

package/dist/esm/{full-date → extra-utils}/js-date-conversion.js

@@ -1,4 +1,4 @@
-import { toTimestamp } from './primitive-conversions';
+import { toTimestamp } from '../full-date/primitive-conversions';
 export function toJsDate(fullDate) {
     return new Date(toTimestamp(fullDate));
 }

package/dist/esm/extra-utils/{now-in-iso-string.d.ts → now.d.ts}

@@ -1,2 +1,4 @@
+import { FullDate } from '../full-date/full-date-shape';
 import { UtcIsoString } from '../full-date/string-format-types';
 export declare function getNowInIsoString(): UtcIsoString;
+export declare function getNowInUserTimezone(): FullDate;

package/dist/esm/extra-utils/{now-in-iso-string.js → now.js}

@@ -1,6 +1,6 @@
 import { getNowFullDate } from '../full-date/create-full-date';
 import { toIsoString } from '../full-date/primitive-conversions';
-import { utcTimezone } from '../timezone/timezones';
+import { userTimezone, utcTimezone } from '../timezone/timezones';
 export function getNowInIsoString() {
     /**
      * The time zone doesn't matter here because the ISO string will be identical for a given date
@@ -8,3 +8,6 @@ export function getNowInIsoString() {
      */
     return toIsoString(getNowFullDate(utcTimezone));
 }
+export function getNowInUserTimezone() {
+    return getNowFullDate(userTimezone);
+}

package/dist/esm/extra-utils/zero.d.ts

@@ -0,0 +1,21 @@
+import { FullDate } from '../full-date/full-date-shape';
+export declare const zeroDate: {
+    readonly year: 0;
+    readonly month: 1;
+    readonly day: 1;
+    readonly hour: 0;
+    readonly minute: 0;
+    readonly second: 0;
+    readonly millisecond: 0;
+};
+export declare const zeroTime: Pick<{
+    year: 0;
+    month: 1;
+    day: 1;
+    hour: 0;
+    minute: 0;
+    second: 0;
+    millisecond: 0;
+}, "hour" | "minute" | "second" | "millisecond">;
+export declare function clearTime(inputFullDate: Readonly<FullDate>): FullDate;
+export declare function clearParts(inputFullDate: Readonly<FullDate>, parts: ReadonlyArray<Exclude<keyof FullDate, 'timezone'>>): FullDate;

package/dist/esm/extra-utils/zero.js

@@ -0,0 +1,25 @@
+import { pickObjectKeys, typedObjectFromEntries } from '@augment-vir/common';
+import { timeFullDateKeys } from '../full-date/full-date-shape';
+import { overrideDateParts } from './date-transforms';
+export const zeroDate = {
+    year: 0,
+    month: 1,
+    day: 1,
+    hour: 0,
+    minute: 0,
+    second: 0,
+    millisecond: 0,
+};
+export const zeroTime = pickObjectKeys(zeroDate, timeFullDateKeys);
+export function clearTime(inputFullDate) {
+    return clearParts(inputFullDate, timeFullDateKeys);
+}
+export function clearParts(inputFullDate, parts) {
+    const clearParts = typedObjectFromEntries(parts.map((keyName) => {
+        return [
+            keyName,
+            zeroDate[keyName],
+        ];
+    }));
+    return overrideDateParts(inputFullDate, clearParts);
+}

package/dist/esm/full-date/full-date-shape.d.ts

@@ -1,4 +1,4 @@
-import { Overwrite, RequiredBy } from '@augment-vir/common';
+import { ArrayElement, Overwrite, RequiredBy } from '@augment-vir/common';
 import { Timezone } from '../timezone/timezone-names';
 /**
  * Represents various parts of a FullDate. Each value is also a valid "type" attribute for an
@@ -9,6 +9,10 @@ export declare enum FullDatePartEnum {
     Time = "time",
     DateTime = "datetime-local"
 }
+export declare const timeFullDateKeys: readonly ["hour", "minute", "second", "millisecond"];
+export type TimeFullDateKeys = ArrayElement<typeof timeFullDateKeys>;
+export declare const dateFullDateKeys: readonly ["year", "month", "day"];
+export type DateFullDateKeys = ArrayElement<typeof dateFullDateKeys>;
 export declare const timePartShape: import("object-shape-tester").ShapeDefinition<{
     /** Hour of the day in 24 time: 0-23 */
     hour: number;

package/dist/esm/full-date/full-date-shape.js

@@ -10,15 +10,26 @@ export var FullDatePartEnum;
     FullDatePartEnum["Time"] = "time";
     FullDatePartEnum["DateTime"] = "datetime-local";
 })(FullDatePartEnum || (FullDatePartEnum = {}));
+export const timeFullDateKeys = [
+    'hour',
+    'minute',
+    'second',
+    'millisecond',
+];
+export const dateFullDateKeys = [
+    'year',
+    'month',
+    'day',
+];
 export const timePartShape = defineShape({
     /** Hour of the day in 24 time: 0-23 */
     hour: 14,
     /** Minute of the hour: 0-59 */
     minute: 19,
     /** Second of the minute: 0-59 */
-    second: 0,
+    second: 7,
     /** Millisecond of the second: 0-999 */
-    millisecond: 870,
+    millisecond: 877,
     /** The timezone that this date/time is meant for / originated from. */
     timezone: utcTimezone,
 });

package/dist/esm/index.d.ts

@@ -1,14 +1,16 @@
 export * from './date-operations/calculate-relative-date';
 export * from './date-operations/combine-dates';
 export * from './date-operations/diff-dates';
-export * from './extra-utils/now-in-iso-string';
+export * from './duration';
+export * from './extra-utils/date-transforms';
+export * from './extra-utils/js-date-conversion';
+export * from './extra-utils/now';
+export * from './extra-utils/zero';
 export * from './full-date/create-full-date';
 export * from './full-date/date-like';
-export * from './full-date/date-transforms';
 export * from './full-date/format-presets';
 export * from './full-date/full-date-shape';
 export * from './full-date/is-valid-full-date';
-export * from './full-date/js-date-conversion';
 export * from './full-date/luxon-date-time-conversion';
 export * from './full-date/parsing';
 export * from './full-date/primitive-conversions';

package/dist/esm/index.js

@@ -1,14 +1,16 @@
 export * from './date-operations/calculate-relative-date';
 export * from './date-operations/combine-dates';
 export * from './date-operations/diff-dates';
-export * from './extra-utils/now-in-iso-string';
+export * from './duration';
+export * from './extra-utils/date-transforms';
+export * from './extra-utils/js-date-conversion';
+export * from './extra-utils/now';
+export * from './extra-utils/zero';
 export * from './full-date/create-full-date';
 export * from './full-date/date-like';
-export * from './full-date/date-transforms';
 export * from './full-date/format-presets';
 export * from './full-date/full-date-shape';
 export * from './full-date/is-valid-full-date';
-export * from './full-date/js-date-conversion';
 export * from './full-date/luxon-date-time-conversion';
 export * from './full-date/parsing';
 export * from './full-date/primitive-conversions';

package/docs-dist/assets/highlight.css

@@ -0,0 +1,92 @@
+:root {
+    --light-hl-0: #AF00DB;
+    --dark-hl-0: #C586C0;
+    --light-hl-1: #000000;
+    --dark-hl-1: #D4D4D4;
+    --light-hl-2: #001080;
+    --dark-hl-2: #9CDCFE;
+    --light-hl-3: #A31515;
+    --dark-hl-3: #CE9178;
+    --light-hl-4: #0000FF;
+    --dark-hl-4: #569CD6;
+    --light-hl-5: #0070C1;
+    --dark-hl-5: #4FC1FF;
+    --light-hl-6: #267F99;
+    --dark-hl-6: #4EC9B0;
+    --light-hl-7: #098658;
+    --dark-hl-7: #B5CEA8;
+    --light-hl-8: #008000;
+    --dark-hl-8: #6A9955;
+    --light-hl-9: #795E26;
+    --dark-hl-9: #DCDCAA;
+    --light-code-background: #FFFFFF;
+    --dark-code-background: #1E1E1E;
+}
+
+@media (prefers-color-scheme: light) { :root {
+    --hl-0: var(--light-hl-0);
+    --hl-1: var(--light-hl-1);
+    --hl-2: var(--light-hl-2);
+    --hl-3: var(--light-hl-3);
+    --hl-4: var(--light-hl-4);
+    --hl-5: var(--light-hl-5);
+    --hl-6: var(--light-hl-6);
+    --hl-7: var(--light-hl-7);
+    --hl-8: var(--light-hl-8);
+    --hl-9: var(--light-hl-9);
+    --code-background: var(--light-code-background);
+} }
+
+@media (prefers-color-scheme: dark) { :root {
+    --hl-0: var(--dark-hl-0);
+    --hl-1: var(--dark-hl-1);
+    --hl-2: var(--dark-hl-2);
+    --hl-3: var(--dark-hl-3);
+    --hl-4: var(--dark-hl-4);
+    --hl-5: var(--dark-hl-5);
+    --hl-6: var(--dark-hl-6);
+    --hl-7: var(--dark-hl-7);
+    --hl-8: var(--dark-hl-8);
+    --hl-9: var(--dark-hl-9);
+    --code-background: var(--dark-code-background);
+} }
+
+:root[data-theme='light'] {
+    --hl-0: var(--light-hl-0);
+    --hl-1: var(--light-hl-1);
+    --hl-2: var(--light-hl-2);
+    --hl-3: var(--light-hl-3);
+    --hl-4: var(--light-hl-4);
+    --hl-5: var(--light-hl-5);
+    --hl-6: var(--light-hl-6);
+    --hl-7: var(--light-hl-7);
+    --hl-8: var(--light-hl-8);
+    --hl-9: var(--light-hl-9);
+    --code-background: var(--light-code-background);
+}
+
+:root[data-theme='dark'] {
+    --hl-0: var(--dark-hl-0);
+    --hl-1: var(--dark-hl-1);
+    --hl-2: var(--dark-hl-2);
+    --hl-3: var(--dark-hl-3);
+    --hl-4: var(--dark-hl-4);
+    --hl-5: var(--dark-hl-5);
+    --hl-6: var(--dark-hl-6);
+    --hl-7: var(--dark-hl-7);
+    --hl-8: var(--dark-hl-8);
+    --hl-9: var(--dark-hl-9);
+    --code-background: var(--dark-code-background);
+}
+
+.hl-0 { color: var(--hl-0); }
+.hl-1 { color: var(--hl-1); }
+.hl-2 { color: var(--hl-2); }
+.hl-3 { color: var(--hl-3); }
+.hl-4 { color: var(--hl-4); }
+.hl-5 { color: var(--hl-5); }
+.hl-6 { color: var(--hl-6); }
+.hl-7 { color: var(--hl-7); }
+.hl-8 { color: var(--hl-8); }
+.hl-9 { color: var(--hl-9); }
+pre, code { background: var(--code-background); }