@samual/duration/normalizeDuration.d.ts

Normalize and format durations of time.

/**
 * Normalize a {@linkcode Duration}.
 *
 * @example Basic Usage
 * ```ts
 * import { type Duration, normalizeDuration } from "@samual/duration/normalizeDuration"
 *
 * let duration: Duration = { years: 0, days: 0, hours: 0, minutes: 0, seconds: 0, milliseconds: Date.now() }
 *
 * normalizeDuration(duration)
 * console.log(duration) // { years: 54, days: 349, hours: 11, minutes: 47, seconds: 14, milliseconds: 227 }
 * ```
 *
 * @module
 */
import { DurationError } from "./DurationError";
import type { Duration } from "./default";
/**
 * Error that can be thrown by {@linkcode normalizeDuration()}.
 *
 * @example Basic Usage
 * ```ts
 * import { normalizeDuration, NormalizeDurationError } from "@samual/duration"
 *
 * try {
 * 	normalizeDuration(duration)
 * } catch (error) {
 * 	if (error instanceof NormalizeDurationError) {
 * 		// ...
 * 	} else
 * 		throw error
 * }
 * ```
 */
export declare class NormalizeDurationError extends DurationError {
}
/**
 * Error that can be thrown by {@linkcode normalizeDuration()} for trying to normalize non-integers.
 *
 * @example Basic Usage
 * ```ts
 * import { normalizeDuration, NormalizeNonIntegerDurationError } from "@samual/duration"
 *
 * try {
 * 	normalizeDuration(duration)
 * } catch (error) {
 * 	if (error instanceof NormalizeNonIntegerDurationError) {
 * 		// ...
 * 	} else
 * 		throw error
 * }
 * ```
 */
export declare class NormalizeNonIntegerDurationError extends NormalizeDurationError {
}
/**
 * Normalize a {@linkcode Duration}.
 *
 * e.g. 120,000 milliseconds becomes 2 minutes.
 *
 * This function mutates the given `Duration`, hence why it doesn't return anything.
 *
 * @param duration The {@linkcode Duration} to be normalized.
 * @throws Any {@linkcode NormalizeDurationError}.
 * @throws A {@linkcode NormalizeNonIntegerDurationError} for trying to normalize a duration with numbers that aren't integers.
 *
 * @example Basic Usage
 * ```ts
 * import { type Duration, normalizeDuration } from "@samual/duration"
 *
 * let duration: Duration = { years: 0, days: 0, hours: 0, minutes: 0, seconds: 0, milliseconds: Date.now() }
 *
 * normalizeDuration(duration)
 * console.log(duration) // { years: 54, days: 349, hours: 11, minutes: 47, seconds: 14, milliseconds: 227 }
 * ```
 */
export declare function normalizeDuration(duration: Duration): void;