@kikiutils/shared 18.0.1 → 18.1.0

package/src/datetime.ts

@@ -1,77 +1,66 @@
-import {
-    format as dateFnsFormat,
-    endOfDay,
-    endOfMonth,
-    endOfWeek,
-    startOfDay,
-    startOfMonth,
-    startOfWeek,
-    subDays,
-    subMonths,
-    subWeeks,
-} from 'date-fns';
-import type {
-    DateArg,
-    Day,
-    FormatOptions,
-} from 'date-fns';
+import * as dateFns from 'date-fns';
+
+import { EnhancedDate } from './classes/enhanced-date';
 
 export type DateRangeType = 'lastMonth' | 'lastWeek' | 'thisMonth' | 'thisWeek' | 'today' | 'yesterday';
 
 /**
- * Formats a given date, timestamp, or date string into a specified format.
+ * Formats a date using a date-fns pattern without changing the input.
  *
- * This function is a wrapper around `date-fns/format`.
+ * @remarks
+ * Formatting uses the system time zone unless configured through date-fns options.
+ * Invalid dates and unsupported patterns propagate date-fns exceptions.
  *
- * @param {DateArg<Date>} date - The input date to format. Can be a Date object, a timestamp, or a string
- * @param {string} [format] - The target format string
- * @param {FormatOptions} [options] - Optional formatting options passed to `date-fns/format`
+ * @param date - The date, timestamp in milliseconds, or date string to format.
+ * @param format - The date-fns pattern. Defaults to `yyyy-MM-dd HH:mm:ss`.
+ * @param options - Formatting options passed to date-fns.
  *
- * @returns {string} The formatted date string
+ * @returns The formatted date string.
  *
  * @example
- * ```typescript
- * import { formatDate } from '@kikiutils/shared/datetime';
  *
- * // Format a Date object
- * console.log(formatDate(new Date(), 'yyyy-MM-dd')); // 2024-07-10
- *
- * // Format a timestamp
- * console.log(formatDate(1657814400000, 'yyyy-MM-dd')); // 2022-07-15
+ * ```ts
+ * import { formatDate } from '@kikiutils/shared/datetime';
  *
- * // Format a date string
- * console.log(formatDate('2024-07-10T00:00:00Z', 'yyyy-MM-dd')); // 2024-07-10
+ * const date = new Date(2026, 0, 15, 12);
+ * console.log(formatDate(date, 'yyyy-MM-dd')); // => '2026-01-15'
  * ```
  */
-export function formatDate(date: DateArg<Date> & {}, format: string = 'yyyy-MM-dd HH:mm:ss', options?: FormatOptions) {
-    return dateFnsFormat(date, format, options);
+export function formatDate(
+    date: dateFns.DateArg<Date>,
+    format: string = 'yyyy-MM-dd HH:mm:ss',
+    options?: dateFns.FormatOptions,
+) {
+    return dateFns.format(date, format, options);
 }
 
+/* eslint-disable jsdoc/check-param-names -- Inline TypeScript options are documented in remarks. */
+
 /**
- * Get the date range (start and end) based on a given date and range type.
+ * Returns new start and end dates for a calendar range in the system time zone.
+ *
+ * @remarks
+ * The reference date is unchanged. Boundaries are inclusive by default, ending at `23:59:59.999`.
+ * When `options.setEndDateToNextDayStart` is `true`, the end is the exclusive start of the next calendar day.
+ * `options.weekStartsOn` defaults to `1` (Monday); `0` means Sunday and `6` means Saturday.
+ * Calendar ranges follow local daylight saving transitions rather than fixed 24-hour durations.
  *
- * Supports common range types like 'lastMonth', 'lastWeek', 'thisMonth', 'thisWeek', 'today', and 'yesterday'.
+ * @param date - The reference date for the range.
+ * @param type - The current or previous day, week, or month to select.
+ * @param options - Settings for the end boundary and first day of the week.
  *
- * @param {Date} date - The reference date
- * @param {DateRangeType} type - The range type to compute
- * @param {object} [options] - Optional settings
- * @param {boolean} [options.setEndDateToNextDayStart] - If true, set `endDate` to 00:00:00.000 of the next day
- * @param {Day} [options.weekStartsOn] - The start day of the week (0 = Sunday, 1 = Monday, ..., 6 = Saturday)
+ * @returns An object containing new `EnhancedDate` boundaries; the reference date is unchanged.
  *
- * @returns {{ startDate: Date, endDate: Date }} An object with `startDate` and `endDate`
+ * @throws Error if the range type is unsupported at runtime.
  *
  * @example
- * ```typescript
- * import { getDateRangeFromDate } from '@kikiutils/shared/datetime';
  *
- * // Get the date range for last month
- * const date = new Date('2023-07-01');
- * console.log(getDateRangeFromDate(date, 'lastMonth'));
- * // { startDate: 2023-06-01T00:00:00.000Z, endDate: 2023-06-30T23:59:59.999Z }
+ * ```ts
+ * import { getDateRangeFromDate } from '@kikiutils/shared/datetime';
  *
- * // Get this week's range with Sunday as the first day
- * console.log(getDateRangeFromDate(date, 'thisWeek', { weekStartsOn: 0 }));
- * // { startDate: 2023-06-25T00:00:00.000Z, endDate: 2023-07-01T23:59:59.999Z }
+ * const range = getDateRangeFromDate(new Date(2026, 6, 15, 12), 'lastMonth');
+ * console.log(range.startDate.format('yyyy-MM-dd')); // => '2026-06-01'
+ * console.log(range.endDate.format('yyyy-MM-dd')); // => '2026-06-30'
  * ```
  */
 export function getDateRangeFromDate(
@@ -79,45 +68,46 @@ export function getDateRangeFromDate(
     type: DateRangeType,
     options?: {
         setEndDateToNextDayStart?: boolean;
-        weekStartsOn?: Day;
+        weekStartsOn?: dateFns.Day;
     },
 ) {
-    let endDate: Date;
-    let startDate: Date;
+    const referenceDate = new EnhancedDate(date);
+    let endDate: EnhancedDate;
+    let startDate: EnhancedDate;
     switch (type) {
         case 'lastMonth':
             {
-                const lastMonth = subMonths(date, 1);
-                endDate = endOfMonth(lastMonth);
-                startDate = startOfMonth(lastMonth);
+                const lastMonth = referenceDate.toSubMonths(1);
+                endDate = lastMonth.toEndOfMonth();
+                startDate = lastMonth.toStartOfMonth();
             }
 
             break;
         case 'lastWeek':
             {
-                const lastWeek = subWeeks(date, 1);
-                endDate = endOfWeek(lastWeek, { weekStartsOn: options?.weekStartsOn ?? 1 });
-                startDate = startOfWeek(lastWeek, { weekStartsOn: options?.weekStartsOn ?? 1 });
+                const lastWeek = referenceDate.toSubWeeks(1);
+                endDate = lastWeek.toEndOfWeek({ weekStartsOn: options?.weekStartsOn ?? 1 });
+                startDate = lastWeek.toStartOfWeek({ weekStartsOn: options?.weekStartsOn ?? 1 });
             }
 
             break;
         case 'thisMonth':
-            endDate = endOfMonth(date);
-            startDate = startOfMonth(date);
+            endDate = referenceDate.toEndOfMonth();
+            startDate = referenceDate.toStartOfMonth();
             break;
         case 'thisWeek':
-            endDate = endOfWeek(date, { weekStartsOn: options?.weekStartsOn ?? 1 });
-            startDate = startOfWeek(date, { weekStartsOn: options?.weekStartsOn ?? 1 });
+            endDate = referenceDate.toEndOfWeek({ weekStartsOn: options?.weekStartsOn ?? 1 });
+            startDate = referenceDate.toStartOfWeek({ weekStartsOn: options?.weekStartsOn ?? 1 });
             break;
         case 'today':
-            endDate = endOfDay(date);
-            startDate = startOfDay(date);
+            endDate = referenceDate.toEndOfDay();
+            startDate = referenceDate.toStartOfDay();
             break;
         case 'yesterday':
             {
-                const yesterday = subDays(date, 1);
-                endDate = endOfDay(yesterday);
-                startDate = startOfDay(yesterday);
+                const yesterday = referenceDate.toSubDays(1);
+                endDate = yesterday.toEndOfDay();
+                startDate = yesterday.toStartOfDay();
             }
 
             break;
@@ -131,25 +121,15 @@ export function getDateRangeFromDate(
     };
 }
 
+/* eslint-enable jsdoc/check-param-names */
+
 /**
- * Returns a `Date` object set to midnight (00:00:00) of today, with an optional day offset.
- *
- * @param {number} [offsetDays] - Number of days to offset from today. Can be negative
+ * Returns a new date at local midnight with an optional calendar-day offset from today.
  *
- * @returns {Date} A `Date` object at 00:00:00 of the offset day
+ * @param offsetDays - The calendar days to add; negative values select earlier days.
  *
- * @example
- * ```typescript
- * import { getMidnightDateFromToday } from '@kikiutils/shared/datetime';
- *
- * console.log(getMidnightDateFromToday()); // today at 00:00:00
- * console.log(getMidnightDateFromToday(3)); // 3 days from today at 00:00:00
- * console.log(getMidnightDateFromToday(-1)); // yesterday at 00:00:00
- * ```
+ * @returns A new `EnhancedDate` at local midnight on the selected day.
  */
 export function getMidnightDateFromToday(offsetDays: number = 0) {
-    const date = new Date();
-    date.setDate(date.getDate() + offsetDays);
-    date.setHours(0, 0, 0, 0);
-    return date;
+    return new EnhancedDate().addDays(offsetDays).startOfDay();
 }

package/src/element-plus.ts

@@ -4,22 +4,22 @@ import type { FormItemRule } from 'element-plus';
 export type DoNotRemoveOrUseThisType = RuleType;
 
 /**
- * Creates a reusable Element Plus `<el-form-item>` validation rule with sensible defaults.
+ * Creates a new Element Plus form validation rule with overridable defaults.
  *
- * This utility provides default values for `required`, `trigger`, and `type`,
- * while allowing overrides via the `options` parameter. It simplifies common
- * form validation rule creation and ensures consistency across forms.
+ * @remarks
+ * Defaults to `required: true`, `trigger: 'blur'`, and `type: 'string'`.
+ * Non-nullish options override those defaults; `null` and `undefined` use the defaults.
+ * The `message` argument takes precedence over `options.message`.
+ * The options object is unchanged.
  *
- * @param {FormItemRule['message']} message - The validation message to display when the rule fails
- * @param {FormItemRule} [options] - Optional overrides for the rule fields
- * @param {boolean} [options.required] - Whether the field is required (default: `true`)
- * @param {string | string[]} [options.trigger] - The event(s) that trigger validation (default: `'blur'`)
- * @param {RuleType} [options.type] - The expected type of the field (default: `'string'`)
+ * @param message - The validation message displayed on failure.
+ * @param options - Additional rule fields and non-nullish overrides for the defaults; `message` takes precedence.
  *
- * @returns A `FormItemRule` object that can be used in Element Plus form validation
+ * @returns A new `FormItemRule` object.
  *
  * @example
- * ```typescript
+ *
+ * ```ts
  * import { createElFormItemRuleWithDefaults } from '@kikiutils/shared/element-plus';
  *
  * const rule = createElFormItemRuleWithDefaults('This field is required');

package/src/enum.ts

@@ -1,24 +1,25 @@
 /**
  * Extracts only the numeric values from an enumeration-like object.
  *
- * @template T - The type of the enum object
+ * @typeParam T - The type of the enum object.
  *
- * @param {T} enumObject - The enumeration-like object to extract numeric values from,
+ * @param enumObject - The enumeration-like object to extract numeric values from,
  * the object can contain numeric values, string values, or both.
  *
- * @returns {Extract<T[keyof T], number>[]} An array of numeric values extracted from the enum object
+ * @returns An array of numeric values extracted from the enum object.
  *
  * @example
- * ```typescript
+ *
+ * ```ts
  * import { getEnumNumberValues } from '@kikiutils/shared/enum';
  *
  * enum RecordType {
- *   Receive = 0,
- *   Send = 1,
- *   Unknown = 'unknown'
+ *     Receive = 0,
+ *     Send = 1,
+ *     Unknown = 'unknown',
  * }
  *
- * console.log(getEnumNumberValues(RecordType)); // [0, 1]
+ * console.log(getEnumNumberValues(RecordType)); // => [0, 1]
  * ```
  */
 export function getEnumNumberValues<T extends Record<string, any>>(enumObject: T): Extract<T[keyof T], number>[] {
@@ -28,24 +29,25 @@ export function getEnumNumberValues<T extends Record<string, any>>(enumObject: T
 /**
  * Extracts only the string values from an enumeration-like object.
  *
- * @template T - The type of the enum object
+ * @typeParam T - The type of the enum object.
  *
- * @param {T} enumObject - The enumeration-like object to extract string values from,
+ * @param enumObject - The enumeration-like object to extract string values from,
  * the object can contain numeric values, string values, or both.
  *
- * @returns {Extract<T[keyof T], string>[]} An array of string values extracted from the enum object
+ * @returns An array of string values extracted from the enum object.
  *
  * @example
- * ```typescript
+ *
+ * ```ts
  * import { getEnumStringValues } from '@kikiutils/shared/enum';
  *
  * enum RecordType {
- *   Receive = 0,
- *   Send = 1,
- *   Unknown = 'unknown'
+ *     Receive = 0,
+ *     Send = 1,
+ *     Unknown = 'unknown',
  * }
  *
- * console.log(getEnumStringValues(RecordType)); // ['unknown']
+ * console.log(getEnumStringValues(RecordType)); // => ['unknown']
  * ```
  */
 export function getEnumStringValues<T extends Record<string, any>>(enumObject: T): Extract<T[keyof T], string>[] {
@@ -55,47 +57,49 @@ export function getEnumStringValues<T extends Record<string, any>>(enumObject: T
 /**
  * Extracts all values from an enumeration-like object.
  *
+ * @remarks
  * This function handles TypeScript enums correctly by accounting for the reverse mapping
  * that occurs with numeric enums. It works with pure numeric enums, pure string enums,
  * and mixed enums.
  *
- * @template T - The type of the enum object
+ * @typeParam T - The type of the enum object.
  *
- * @param {T} enumObject - The enumeration-like object to extract values from,
+ * @param enumObject - The enumeration-like object to extract values from,
  * the object can contain numeric values, string values, or both.
  *
- * @returns {(T[keyof T])[]} An array containing all the values from the enum object
+ * @returns An array containing all the values from the enum object.
  *
  * @example
- * ```typescript
+ *
+ * ```ts
  * import { getEnumValues } from '@kikiutils/shared/enum';
  *
  * // Numeric enum
  * enum Status {
- *   Active = 0,
- *   Inactive = 1,
- *   Pending = 2
+ *     Active = 0,
+ *     Inactive = 1,
+ *     Pending = 2,
  * }
  *
- * console.log(getEnumValues(Status)); // [0, 1, 2]
+ * console.log(getEnumValues(Status)); // => [0, 1, 2]
  *
  * // String enum
  * enum Color {
- *   Red = 'RED',
- *   Green = 'GREEN',
- *   Blue = 'BLUE'
+ *     Red = 'RED',
+ *     Green = 'GREEN',
+ *     Blue = 'BLUE',
  * }
  *
- * console.log(getEnumValues(Color)); // ['RED', 'GREEN', 'BLUE']
+ * console.log(getEnumValues(Color)); // => ['RED', 'GREEN', 'BLUE']
  *
  * // Mixed enum
  * enum RecordType {
- *   Receive = 0,
- *   Send = 1,
- *   Unknown = 'unknown'
+ *     Receive = 0,
+ *     Send = 1,
+ *     Unknown = 'unknown',
  * }
  *
- * console.log(getEnumValues(RecordType)); // [0, 1, 'unknown']
+ * console.log(getEnumValues(RecordType)); // => [0, 1, 'unknown']
  * ```
  */
 export function getEnumValues<T extends Record<string, any>>(enumObject: T): (T[keyof T])[] {

package/src/env.ts

@@ -1,17 +1,16 @@
 /**
  * Custom error class for handling missing environment variables.
  *
+ * @remarks
  * Extends the built-in `Error` class and includes the missing key.
- *
- * @extends {Error}
  */
 export class EnvironmentNotFoundError extends Error {
     readonly key: string;
 
     /**
-     * Creates a new EnvironmentNotFoundError.
+     * Creates an error identifying a missing environment variable.
      *
-     * @param {string} key - The missing environment variable key
+     * @param key - The missing environment variable key.
      */
     constructor(key: string) {
         super(`Missing environment variable: ${key}`);
@@ -24,24 +23,33 @@ export class EnvironmentNotFoundError extends Error {
 /**
  * Retrieves the value of an environment variable, or throws an error if it is not defined.
  *
- * Only checks for `process.env[key] === undefined`. An empty string (e.g. '') or any falsy string
+ * @remarks
+ * Only checks for `process.env[key] === undefined`. An empty string (for example `''`) or any falsy string
  * value like `'0'` or `'false'` is considered a valid (defined) value.
  *
- * @param {string} key - The environment variable key to retrieve
+ * @param key - The environment variable key to retrieve.
  *
- * @returns {string} The value of the environment variable
+ * @returns The value of the environment variable.
  *
- * @throws {EnvironmentNotFoundError} If the environment variable is not defined
+ * @throws EnvironmentNotFoundError if the environment variable is not defined.
  *
  * @example
- * ```typescript
- * import { checkAndGetEnvValue } from '@kikiutils/shared/env';
+ *
+ * ```ts
+ * import {
+ *     checkAndGetEnvValue,
+ *     EnvironmentNotFoundError,
+ * } from '@kikiutils/shared/env';
  *
  * process.env.API_KEY = '';
- * checkAndGetEnvValue('API_KEY'); // ✅ Returns '' (still considered "defined")
+ * checkAndGetEnvValue('API_KEY'); // => ''
  *
  * delete process.env.API_KEY;
- * checkAndGetEnvValue('API_KEY'); // ❌ Throws EnvironmentNotFoundError
+ * try {
+ *     checkAndGetEnvValue('API_KEY');
+ * } catch (error) {
+ *     console.log(error instanceof EnvironmentNotFoundError); // => true
+ * }
  * ```
  */
 export function checkAndGetEnvValue(key: string) {

package/src/event-awaiter.ts

@@ -1,25 +1,25 @@
 /**
- * EventAwaiter provides a mechanism to wait for events (by key) asynchronously.
+ * An asynchronous keyed event rendezvous for one or more waiting consumers.
  *
- * This class allows multiple consumers to `wait` for a specific key
- * and be resolved when `trigger` is called for that key, or automatically
- * resolved with `undefined` if a timeout occurs or an AbortSignal is triggered.
+ * @remarks
+ * Triggers resolve the currently registered waiters; values are not retained for future waits.
+ * Timeouts and subsequent abort events resolve affected waiters with `undefined`.
+ * Use `triggerAll` to resolve pending waits during cleanup. Timers and abort listeners are not proactively
+ * removed by triggers, so they may remain until their timeout or abort event occurs.
  *
- * Typical use cases include long-polling, request coordination,
- * or implementing event-driven primitives in applications or services.
- *
- * @template T - The type of value that will be resolved when the event is triggered
+ * @typeParam T - The value delivered to waiting consumers.
  */
 export class EventAwaiter<T> {
+    // Private instance properties
     #promiseResolvers = new Map<string, ((value: PromiseLike<T | undefined> | T | undefined) => void)[]>();
 
+    // Public instance methods
+
     /**
-     * Triggers all pending promises waiting for the given key.
-     * Each promise will be resolved with the provided value.
+     * Resolves all currently pending waits for a key with the supplied value.
      *
-     * @param {string} key - Identifier for the awaited event
-     * @param {T | undefined} value - The value to resolve the awaiting promises with.
-     * May be `undefined` to indicate no result or a timeout-like behavior.
+     * @param key - The event identifier; a key without pending waits has no effect.
+     * @param value - The delivered value; `undefined` indicates no result.
      */
     trigger(key: string, value: T | undefined) {
         const resolvers = this.#promiseResolvers.get(key);
@@ -30,13 +30,9 @@ export class EventAwaiter<T> {
     }
 
     /**
-     * Triggers and resolves all pending promises across all keys.
-     *
-     * This is typically used during shutdown or cleanup to ensure that
-     * no consumer is left waiting indefinitely.
+     * Resolves all currently pending waits and clears their registrations.
      *
-     * @param {T | undefined} [value] - Optional value to resolve all waiters with.
-     * Defaults to `undefined`, which usually indicates cancellation or shutdown.
+     * @param value - The delivered value; omission resolves all pending waits with `undefined`.
      */
     triggerAll(value: T | undefined = undefined) {
         for (const [_, resolvers] of this.#promiseResolvers.entries()) resolvers.forEach((resolve) => resolve(value));
@@ -44,27 +40,23 @@ export class EventAwaiter<T> {
     }
 
     /**
-     * Waits for an event associated with the given key.
+     * Waits for a trigger associated with a key.
      *
-     * The returned promise will resolve when:
-     *  - `trigger(key)` is called, in which case it resolves with the provided value.
-     *  - The optional timeout is reached, in which case it resolves with `undefined`.
-     *  - The optional `AbortSignal` is aborted, in which case it resolves with `undefined`.
+     * @remarks
+     * By default, multiple waiters share a key and all receive the next trigger value.
+     * `strict` mode rejects duplicate waits; `override` mode resolves existing waits with `undefined` before
+     * registering the new wait. Timeout and abort remove only the affected waiter's registration.
+     * An already aborted signal is not checked; only an abort event emitted after registration ends the wait.
+     * Without a timeout or subsequent abort, the wait remains pending until a trigger arrives.
      *
-     * Behavior when multiple waiters exist for the same key:
-     *  - Default (no mode): multiple waiters are allowed, all will be resolved when triggered.
-     *  - `strict` mode: throws an error if a waiter already exists for the given key.
-     *  - `override` mode: cancels all existing waiters (resolving them with `undefined`)
-     *    and only keeps the latest one.
+     * @param key - The event identifier to wait for.
+     * @param timeoutMs - The optional timeout in milliseconds, using native `setTimeout` timing rules.
+     * @param mode - The policy for existing waiters; omission allows multiple waiters.
+     * @param signal - A signal whose subsequent abort event ends this wait.
      *
-     * @param {string} key - Identifier for the awaited event
-     * @param {number} [timeoutMs] - Optional timeout (in milliseconds).
-     * If reached, the promise resolves with `undefined`.
-     * @param {'override' | 'strict'} [mode] - Optional behavior mode for handling multiple waiters
-     * @param {AbortSignal} [signal] - Optional AbortSignal. If aborted, the promise resolves with `undefined`
+     * @returns A promise resolving to the triggered value, or `undefined` after timeout, abort, or replacement.
      *
-     * @returns {Promise<T | undefined>} A promise that resolves with the triggered value,
-     * or `undefined` if timeout or abort occurs
+     * @throws Error through promise rejection if `strict` mode encounters an existing waiter.
      */
     wait(key: string, timeoutMs?: number, mode?: 'override' | 'strict', signal?: AbortSignal) {
         return new Promise<T | undefined>((resolve) => {
@@ -116,28 +108,35 @@ export class EventAwaiter<T> {
     }
 
     /**
-     * Waits for an event in strict mode.
-     * Only one waiter is allowed per key. If another waiter already exists,
-     * this method will throw an error.
+     * Waits for a key while rejecting duplicate registrations.
+     *
+     * @param key - The event identifier to wait for.
+     * @param timeoutMs - The optional timeout in milliseconds.
+     * @param signal - A signal whose subsequent abort event ends this wait; an already aborted signal is not checked.
+     *
+     * @returns A promise resolving to the triggered value, or `undefined` on timeout or subsequent abort.
      *
-     * @param {string} key - Identifier for the awaited event
-     * @param {number} [timeoutMs] - Optional timeout (in milliseconds).
-     * If reached, the promise resolves with `undefined`.
-     * @param {AbortSignal} [signal] - Optional AbortSignal. If aborted, the promise resolves with `undefined`
+     * @throws Error through promise rejection if the key already has a pending waiter.
+     *
+     * @see {@link EventAwaiter.wait}
      */
     waitExclusive(key: string, timeoutMs?: number, signal?: AbortSignal) {
         return this.wait(key, timeoutMs, 'strict', signal);
     }
 
     /**
-     * Waits for an event in override mode.
-     * If another waiter already exists for the given key, it will be canceled
-     * (resolved with `undefined`) and replaced by the new waiter.
+     * Replaces existing waiters for a key and waits for its next trigger.
+     *
+     * @remarks
+     * Existing waiters resolve with `undefined` before the new waiter is registered.
+     *
+     * @param key - The event identifier to wait for.
+     * @param timeoutMs - The optional timeout in milliseconds.
+     * @param signal - A signal whose subsequent abort event ends this wait; an already aborted signal is not checked.
+     *
+     * @returns A promise resolving to the triggered value, or `undefined` on timeout, subsequent abort, or replacement.
      *
-     * @param {string} key - Identifier for the awaited event
-     * @param {number} [timeoutMs] - Optional timeout (in milliseconds).
-     * If reached, the promise resolves with `undefined`.
-     * @param {AbortSignal} [signal] - Optional AbortSignal. If aborted, the promise resolves with `undefined`
+     * @see {@link EventAwaiter.wait}
      */
     waitLatest(key: string, timeoutMs?: number, signal?: AbortSignal) {
         return this.wait(key, timeoutMs, 'override', signal);

package/src/general.ts

@@ -1,28 +1,34 @@
 /* eslint-disable jsdoc/check-param-names */
 
 /**
- * Extracts the first value from an array or returns the value itself if it's not an array.
+ * Returns the first array element or the input value, with a nullish fallback.
  *
- * - If `value` is an array, returns the first element.
- * - If `value` is not an array, returns `value` directly.
- * - If the result is `null` or `undefined`, and `defaultValue` is provided, returns `defaultValue` instead.
+ * @remarks
+ * An empty array, `null`, or `undefined` selects the fallback; omission of a fallback yields `undefined`.
+ * The input and selected values are not copied or changed.
  *
- * @template T - The type of the input value(s)
- * @template D - The type of the default value (if provided)
+ * @typeParam T - The input value or array element type.
+ * @typeParam D - The fallback type when the fallback overload is used.
  *
- * @param {T | T[]} value - A single value or an array of values
- * @param {D} [defaultValue] - A fallback value if the result is `null` or `undefined`
+ * @param value - A single value or an array of values.
+ * @param defaultValue - The fallback returned when the selected value is nullish.
  *
- * @returns {T | D | undefined} The first value or the fallback
+ * @returns The selected non-nullish value, or the fallback without copying either value.
  *
  * @example
- * ```typescript
+ *
+ * ```ts
  * import { extractFirstValue } from '@kikiutils/shared/general';
  *
- * console.log(extractFirstValue([1, 2, 3])); // 1
- * console.log(extractFirstValue('hello'));  // hello
- * console.log(extractFirstValue([], 'default')); // default
- * console.log(extractFirstValue(undefined, 'fallback')); // fallback
+ * console.log(extractFirstValue([
+ *     1,
+ *     2,
+ *     3,
+ * ])); // => 1
+ *
+ * console.log(extractFirstValue('hello')); // => 'hello'
+ * console.log(extractFirstValue([], 'default')); // => 'default'
+ * console.log(extractFirstValue(undefined, 'fallback')); // => 'fallback'
  * ```
  */
 export function extractFirstValue<T>(value: T | T[]): T | undefined;