date-vir 8.6.4 → 9.1.0

package/dist/timezone/timezone-checks.d.ts

@@ -1,3 +1,4 @@
+import { type Timezone } from './timezones.js';
 /**
  * Checks that the given timezone is valid.
  *
@@ -7,7 +8,7 @@
  *
  * @category Assertion
  */
-export declare function isValidTimezone(potentialTimezone: string): boolean;
+export declare function isValidTimezone(raw: string): raw is Timezone;
 /**
  * Asserts that the given input is a valid timezone name.
  *
@@ -17,4 +18,16 @@ export declare function isValidTimezone(potentialTimezone: string): boolean;
  *
  * @category Assertion
  */
-export declare function assertValidTimezone(potentialTimezone: string, userMessage?: string | undefined): void;
+export declare function assertValidTimezone(raw: string, userMessage?: string | undefined): asserts raw is Timezone;
+/**
+ * Asserts that the given input is a valid timezone name and returns it.
+ *
+ * @category Assertion
+ */
+export declare function assertWrapValidTimezone(raw: string, userMessage?: string | undefined): Timezone;
+/**
+ * Checks that the given input is a valid timezone name and returns it when valid.
+ *
+ * @category Assertion
+ */
+export declare function checkWrapValidTimezone(raw: string): Timezone | undefined;

package/dist/timezone/timezone-checks.js

@@ -19,16 +19,16 @@ const ianaValidityCache = new Map();
  *
  * @category Assertion
  */
-export function isValidTimezone(potentialTimezone) {
-    if (knownTimezones.has(potentialTimezone)) {
+export function isValidTimezone(raw) {
+    if (knownTimezones.has(raw)) {
         return true;
     }
-    const cached = ianaValidityCache.get(potentialTimezone);
+    const cached = ianaValidityCache.get(raw);
     if (cached != undefined) {
         return cached;
     }
-    const isValid = Info.isValidIANAZone(potentialTimezone);
-    ianaValidityCache.set(potentialTimezone, isValid);
+    const isValid = Info.isValidIANAZone(raw);
+    ianaValidityCache.set(raw, isValid);
     return isValid;
 }
 /**
@@ -40,8 +40,25 @@ export function isValidTimezone(potentialTimezone) {
  *
  * @category Assertion
  */
-export function assertValidTimezone(potentialTimezone, userMessage) {
-    if (!isValidTimezone(potentialTimezone)) {
-        throw new AssertionError(`'${potentialTimezone}' is not a valid time zone`, userMessage);
+export function assertValidTimezone(raw, userMessage) {
+    if (!isValidTimezone(raw)) {
+        throw new AssertionError(`'${raw}' is not a valid time zone`, userMessage);
     }
 }
+/**
+ * Asserts that the given input is a valid timezone name and returns it.
+ *
+ * @category Assertion
+ */
+export function assertWrapValidTimezone(raw, userMessage) {
+    assertValidTimezone(raw, userMessage);
+    return raw;
+}
+/**
+ * Checks that the given input is a valid timezone name and returns it when valid.
+ *
+ * @category Assertion
+ */
+export function checkWrapValidTimezone(raw) {
+    return isValidTimezone(raw) ? raw : undefined;
+}

package/dist/timezone/timezone-shape.d.ts

@@ -1,12 +1,13 @@
+import { type Timezone } from './timezones.js';
 /**
  * A shape for a timezone value.
  *
  * Unlike a strict enum check against the typed {@link Timezone} list, this validates at runtime via
  * {@link isValidTimezone} (i.e. any valid IANA zone name). It therefore accepts valid IANA names
  * that aren't in the typed list, such as legacy aliases like `'America/Indianapolis'` that some
- * environments (notably Safari) still report from `Intl`. The static type is `string` so that
- * timezone inputs are not restricted to the {@link Timezone} enum.
+ * environments (notably Safari) still report from `Intl`. The branded {@link Timezone} type allows
+ * timezone inputs that are not restricted to the {@link Timezone} list.
  *
  * @category Shape
  */
-export declare const timezoneShape: (defaultValue?: string | undefined) => import("object-shape-tester").Shape<import("@sinclair/typebox").TUnsafe<string>>;
+export declare const timezoneShape: (defaultValue?: Timezone | undefined) => import("object-shape-tester").Shape<import("@sinclair/typebox").TUnsafe<Timezone>>;

package/dist/timezone/timezone-shape.js

@@ -8,8 +8,8 @@ import { utcTimezone } from './timezones.js';
  * Unlike a strict enum check against the typed {@link Timezone} list, this validates at runtime via
  * {@link isValidTimezone} (i.e. any valid IANA zone name). It therefore accepts valid IANA names
  * that aren't in the typed list, such as legacy aliases like `'America/Indianapolis'` that some
- * environments (notably Safari) still report from `Intl`. The static type is `string` so that
- * timezone inputs are not restricted to the {@link Timezone} enum.
+ * environments (notably Safari) still report from `Intl`. The branded {@link Timezone} type allows
+ * timezone inputs that are not restricted to the {@link Timezone} list.
  *
  * @category Shape
  */

package/dist/timezone/timezones.d.ts

@@ -1,12 +1,25 @@
-import { type ArrayElement } from '@augment-vir/common';
+import { type ArrayElement, type Branded } from '@augment-vir/common';
 import { allTimezoneNames } from './timezone-names.js';
 /**
- * All possible timezone names.
+ * All known timezone names.
  *
  * @category Timezone
  * @see {@link allTimezoneNames}
  */
-export type Timezone = ArrayElement<typeof allTimezoneNames>;
+export type TimezoneName = ArrayElement<typeof allTimezoneNames>;
+/**
+ * A branded string for any timezone
+ *
+ * @category Timezone
+ * @see {@link allTimezoneNames}
+ */
+export type TimezoneString = Branded<string, 'timezone-string'>;
+/**
+ * Any known or unknown timezone.
+ *
+ * @category Timezone
+ */
+export type Timezone = TimezoneString | TimezoneName;
 /**
  * An enum of all possible timezone names.
  *
@@ -14,20 +27,20 @@ export type Timezone = ArrayElement<typeof allTimezoneNames>;
  * @example
  *
  * ```ts
- * import {Timezone} from 'date-vir';
+ * import {TimezoneName} from 'date-vir';
  *
- * Timezone['Africa/Bamako'];
+ * TimezoneName['Africa/Bamako'];
  * ```
  */
-export declare const Timezone: Readonly<{
-    [SpecificTimezoneName in Timezone]: SpecificTimezoneName;
+export declare const TimezoneName: Readonly<{
+    [SpecificTimezoneName in TimezoneName]: SpecificTimezoneName;
 }>;
 /**
  * The timezone of the current user's environment.
  *
  * @category Timezone
  */
-export declare const userTimezone: string;
+export declare const userTimezone: NoInfer<TimezoneString>;
 /**
  * The UTC timezone.
  *

package/dist/timezone/timezones.js

@@ -1,3 +1,4 @@
+import { applyBrand } from '@augment-vir/common';
 import { Settings } from 'luxon';
 import { allTimezoneNames } from './timezone-names.js';
 /**
@@ -7,12 +8,12 @@ import { allTimezoneNames } from './timezone-names.js';
  * @example
  *
  * ```ts
- * import {Timezone} from 'date-vir';
+ * import {TimezoneName} from 'date-vir';
  *
- * Timezone['Africa/Bamako'];
+ * TimezoneName['Africa/Bamako'];
  * ```
  */
-export const Timezone = allTimezoneNames.reduce((accum, timezoneName) => {
+export const TimezoneName = allTimezoneNames.reduce((accum, timezoneName) => {
     accum[timezoneName] = timezoneName;
     return accum;
 }, {});
@@ -21,10 +22,10 @@ export const Timezone = allTimezoneNames.reduce((accum, timezoneName) => {
  *
  * @category Timezone
  */
-export const userTimezone = Settings.defaultZone.name;
+export const userTimezone = applyBrand(Settings.defaultZone.name);
 /**
  * The UTC timezone.
  *
  * @category Timezone
  */
-export const utcTimezone = Timezone.UTC;
+export const utcTimezone = TimezoneName.UTC;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "date-vir",
-    "version": "8.6.4",
+    "version": "9.1.0",
     "description": "Easy and explicit dates and times.",
     "keywords": [
         "date",
@@ -37,7 +37,7 @@
     "dependencies": {
         "@augment-vir/assert": "^32.2.1",
         "@augment-vir/common": "^32.2.1",
-        "@date-vir/duration": "^8.6.4",
+        "@date-vir/duration": "^9.1.0",
         "@types/luxon": "^3.7.3",
         "luxon": "^3.7.2",
         "object-shape-tester": "^6.14.1",