@dereekb/date 13.3.1 → 13.4.1

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

@@ -2,6 +2,8 @@ import { type Maybe, type TimezoneAbbreviation, type TimezoneString, type Timezo
 /**
  * Returns all recognized IANA timezone strings, including the explicit UTC entry.
  *
+ * @returns all known IANA timezone strings plus UTC
+ *
  * @example
  * ```ts
  * const zones = allTimezoneStrings();
@@ -32,18 +34,28 @@ export declare const allTimezoneInfos: import("@dereekb/util").CachedFactoryWith
  * {@link searchTimezoneInfos} can perform fast case-insensitive matching.
  */
 export interface TimezoneInfo extends TimezoneStringRef {
-    /** Searchable form with slashes/underscores replaced by spaces and lowercased. */
+    /**
+     * Searchable form with slashes/underscores replaced by spaces and lowercased.
+     */
     readonly search: string;
-    /** Lowercased IANA timezone identifier. */
+    /**
+     * Lowercased IANA timezone identifier.
+     */
     readonly lowercase: string;
-    /** Short abbreviation (e.g., `"EST"`, `"PDT"`). */
+    /**
+     * Short abbreviation (e.g., `"EST"`, `"PDT"`).
+     */
     readonly abbreviation: string;
-    /** Lowercased abbreviation for case-insensitive matching. */
+    /**
+     * Lowercased abbreviation for case-insensitive matching.
+     */
     readonly lowercaseAbbreviation: string;
 }
 /**
  * Returns the {@link TimezoneInfo} for the current system timezone, falling back to UTC.
  *
+ * @returns timezone info for the current system timezone
+ *
  * @example
  * ```ts
  * const info = timezoneInfoForSystem();
@@ -57,6 +69,10 @@ export declare function timezoneInfoForSystem(): TimezoneInfo;
  * The date matters because abbreviations change with DST transitions.
  * Returns `"UKNOWN"` if no timezone is provided.
  *
+ * @param timezone - the IANA timezone string (or UTC abbreviation) to get the abbreviation for
+ * @param date - the date at which to evaluate the abbreviation (defaults to now)
+ * @returns the short timezone abbreviation
+ *
  * @example
  * ```ts
  * getTimezoneAbbreviation('America/New_York'); // 'EST' or 'EDT'
@@ -68,6 +84,10 @@ export declare function getTimezoneAbbreviation(timezone: Maybe<TimezoneString |
  *
  * Returns `"Unknown Timezone"` if no timezone is provided.
  *
+ * @param timezone - the IANA timezone string to get the long name for
+ * @param date - the date at which to evaluate the name (defaults to now)
+ * @returns the full timezone display name
+ *
  * @example
  * ```ts
  * getTimezoneLongName('America/New_York'); // 'Eastern Standard Time'
@@ -77,6 +97,10 @@ export declare function getTimezoneLongName(timezone: Maybe<TimezoneString>, dat
 /**
  * Builds a {@link TimezoneInfo} for the given timezone, computing abbreviation and search variants.
  *
+ * @param timezone - the IANA timezone string to build info for
+ * @param date - the date at which to evaluate the abbreviation (defaults to now)
+ * @returns the computed TimezoneInfo
+ *
  * @example
  * ```ts
  * const info = timezoneStringToTimezoneInfo('America/Chicago');
@@ -91,6 +115,10 @@ export declare function timezoneStringToTimezoneInfo(timezone: TimezoneString, d
  *
  * For queries longer than 2 characters, substring matching on the searchable name is also used.
  *
+ * @param search - the search query string
+ * @param infos - the array of TimezoneInfo objects to filter
+ * @returns the matching TimezoneInfo entries
+ *
  * @example
  * ```ts
  * const results = searchTimezoneInfos('eastern', allTimezoneInfos());
@@ -102,6 +130,9 @@ export declare function searchTimezoneInfos(search: string, infos: TimezoneInfo[
  *
  * Replaces `/` and `_` with spaces (e.g., `"America/New_York"` becomes `"america new york"`).
  *
+ * @param timezone - the IANA timezone string to convert
+ * @returns the searchable lowercase string
+ *
  * @example
  * ```ts
  * timezoneStringToSearchableString('America/New_York'); // 'america new york'
@@ -113,6 +144,9 @@ export declare function timezoneStringToSearchableString(timezone: TimezoneStrin
  *
  * Uses the cached set from {@link allKnownTimezoneStrings} for O(1) lookup.
  *
+ * @param input - the string to check
+ * @returns whether the input is a known timezone
+ *
  * @example
  * ```ts
  * isKnownTimezone('America/New_York'); // true