@dereekb/date 13.0.7 → 13.1.0

package/src/lib/timezone/timezone.d.ts

@@ -1,22 +1,122 @@
 import { type Maybe, type TimezoneAbbreviation, type TimezoneString, type TimezoneStringRef, type UTCTimezoneAbbreviation } from '@dereekb/util';
+/**
+ * Returns all recognized IANA timezone strings, including the explicit UTC entry.
+ *
+ * @example
+ * ```ts
+ * const zones = allTimezoneStrings();
+ * // ['Africa/Abidjan', ..., 'UTC']
+ * ```
+ */
 export declare function allTimezoneStrings(): TimezoneString[];
+/**
+ * Lazily-computed set of all known timezone strings for O(1) membership checks.
+ *
+ * @example
+ * ```ts
+ * allKnownTimezoneStrings().has('America/New_York'); // true
+ * ```
+ */
 export declare const allKnownTimezoneStrings: import("@dereekb/util").CachedFactoryWithInput<Set<string>, unknown>;
+/**
+ * Lazily-computed array of {@link TimezoneInfo} for every known timezone.
+ *
+ * Abbreviations are resolved at the time of first access, so results reflect
+ * the DST state at that moment.
+ */
 export declare const allTimezoneInfos: import("@dereekb/util").CachedFactoryWithInput<TimezoneInfo[], unknown>;
+/**
+ * Pre-computed timezone metadata used for display and search operations.
+ *
+ * Contains lowercase and search-friendly string variants so that
+ * {@link searchTimezoneInfos} can perform fast case-insensitive matching.
+ */
 export interface TimezoneInfo extends TimezoneStringRef {
+    /** Searchable form with slashes/underscores replaced by spaces and lowercased. */
     readonly search: string;
+    /** Lowercased IANA timezone identifier. */
     readonly lowercase: string;
+    /** Short abbreviation (e.g., `"EST"`, `"PDT"`). */
     readonly abbreviation: string;
+    /** Lowercased abbreviation for case-insensitive matching. */
     readonly lowercaseAbbreviation: string;
 }
+/**
+ * Returns the {@link TimezoneInfo} for the current system timezone, falling back to UTC.
+ *
+ * @example
+ * ```ts
+ * const info = timezoneInfoForSystem();
+ * console.log(info.abbreviation); // e.g., 'CST'
+ * ```
+ */
 export declare function timezoneInfoForSystem(): TimezoneInfo;
+/**
+ * Returns the short abbreviation (e.g., `"EST"`, `"PDT"`) for the given timezone at the specified date.
+ *
+ * The date matters because abbreviations change with DST transitions.
+ * Returns `"UKNOWN"` if no timezone is provided.
+ *
+ * @example
+ * ```ts
+ * getTimezoneAbbreviation('America/New_York'); // 'EST' or 'EDT'
+ * ```
+ */
 export declare function getTimezoneAbbreviation(timezone: Maybe<TimezoneString | UTCTimezoneAbbreviation>, date?: Date): TimezoneAbbreviation;
+/**
+ * Returns the full display name (e.g., `"Eastern Standard Time"`) for the given timezone.
+ *
+ * Returns `"Unknown Timezone"` if no timezone is provided.
+ *
+ * @example
+ * ```ts
+ * getTimezoneLongName('America/New_York'); // 'Eastern Standard Time'
+ * ```
+ */
 export declare function getTimezoneLongName(timezone: Maybe<TimezoneString>, date?: Date): string;
+/**
+ * Builds a {@link TimezoneInfo} for the given timezone, computing abbreviation and search variants.
+ *
+ * @example
+ * ```ts
+ * const info = timezoneStringToTimezoneInfo('America/Chicago');
+ * // info.abbreviation => 'CST' or 'CDT'
+ * // info.search => 'america chicago'
+ * ```
+ */
 export declare function timezoneStringToTimezoneInfo(timezone: TimezoneString, date?: Date): TimezoneInfo;
+/**
+ * Filters timezone infos by a search string, matching against the searchable name,
+ * lowercase identifier, and abbreviation.
+ *
+ * For queries longer than 2 characters, substring matching on the searchable name is also used.
+ *
+ * @example
+ * ```ts
+ * const results = searchTimezoneInfos('eastern', allTimezoneInfos());
+ * ```
+ */
 export declare function searchTimezoneInfos(search: string, infos: TimezoneInfo[]): TimezoneInfo[];
+/**
+ * Converts a timezone identifier into a lowercase, space-separated string for search indexing.
+ *
+ * Replaces `/` and `_` with spaces (e.g., `"America/New_York"` becomes `"america new york"`).
+ *
+ * @example
+ * ```ts
+ * timezoneStringToSearchableString('America/New_York'); // 'america new york'
+ * ```
+ */
 export declare function timezoneStringToSearchableString(timezone: TimezoneString): string;
 /**
- * Returns true if the input string is a known timezone.
+ * Checks whether the input string is a recognized IANA timezone identifier.
+ *
+ * Uses the cached set from {@link allKnownTimezoneStrings} for O(1) lookup.
  *
- * @param input
+ * @example
+ * ```ts
+ * isKnownTimezone('America/New_York'); // true
+ * isKnownTimezone('Mars/Olympus');     // false
+ * ```
  */
 export declare function isKnownTimezone(input: string | TimezoneString): boolean;

package/src/lib/timezone/timezone.validator.d.ts

@@ -1,6 +1,11 @@
-import { type ObjectWithConstructor } from '@dereekb/util';
-import { type ValidationOptions } from 'class-validator';
 /**
- * isKnownTimezone validator
+ * ArkType schema that validates a string is a recognized IANA timezone.
+ *
+ * Delegates to {@link isKnownTimezone} for the actual check.
+ *
+ * @example
+ * ```ts
+ * const result = knownTimezoneType('America/Denver');
+ * ```
  */
-export declare function IsKnownTimezone(validationOptions?: ValidationOptions): (object: ObjectWithConstructor, propertyName: string) => void;
+export declare const knownTimezoneType: import("arktype/internal/variants/string.ts").StringType<string, {}>;