/** * Represents immutable spans of time. * * A `Duration` can be finite, positive infinity, or negative infinity. It is * the standard representation for delays, timeouts, intervals, and * time-to-live values across Effect APIs. This module includes constructors * from common input shapes, unit conversions, comparisons, arithmetic, * formatting, and reusable reducer or combiner helpers. * * @stability stable * @since 2.0.0 */ import * as Combiner from "./Combiner.ts"; import * as Equal from "./Equal.ts"; import type * as Equ from "./Equivalence.ts"; import type * as Inspectable from "./Inspectable.ts"; import * as Option from "./Option.ts"; import * as order from "./Order.ts"; import type { Pipeable } from "./Pipeable.ts"; import * as Reducer from "./Reducer.ts"; declare const TypeId = "~effect/Duration"; /** * Represents a span of time with high precision, supporting operations from * nanoseconds to weeks. * * **When to use** * * Use to model elapsed time, delays, timeouts, schedule intervals, and cache * TTLs as immutable duration values. * * @see {@link Input} for values accepted by APIs that decode duration-like * inputs * @see {@link DurationValue} for the tagged representation exposed by the * `value` field * * @stability stable * @category models * @since 2.0.0 */ export interface Duration extends Equal.Equal, Pipeable, Inspectable.Inspectable { readonly [TypeId]: typeof TypeId; readonly value: DurationValue; } /** * Tagged representation of a `Duration` value. * * **When to use** * * Use when modeling or inspecting the exact tagged representation stored in a * `Duration`, including finite millisecond or nanosecond values and infinite * sentinels. * * **Details** * * A duration is represented as milliseconds, nanoseconds, positive infinity, * or negative infinity. * * @see {@link Duration} for the public type whose `value` field contains this * representation * @see {@link match} for pattern matching without reading `value` directly * * @stability stable * @category models * @since 2.0.0 */ export type DurationValue = { _tag: "Millis"; millis: number; } | { _tag: "Nanos"; nanos: bigint; } | { _tag: "Infinity"; } | { _tag: "NegativeInfinity"; }; /** * Valid time units that can be used in duration string representations. * * **When to use** * * Use when typing the unit portion of duration string inputs accepted by * `Duration.Input`. * * @see {@link Input} for the full duration input union * * @stability stable * @category models * @since 2.0.0 */ export type Unit = "nano" | "nanos" | "micro" | "micros" | "milli" | "millis" | "second" | "seconds" | "minute" | "minutes" | "hour" | "hours" | "day" | "days" | "week" | "weeks"; /** * Valid input types that can be converted to a Duration. * * **When to use** * * Use when an API should accept any value that Effect can convert into a * `Duration`, including existing durations, millisecond numbers, nanosecond * bigints, high-resolution tuples, duration strings, infinity strings, or * duration objects. * * **Details** * * String inputs accept values like `"10 seconds"`, `"500 millis"`, * `"Infinity"`, and `"-Infinity"`. Finite fractional values that are * normalized to nanoseconds are rounded to the nearest nanosecond, with ties * away from zero. * * @see {@link fromInput} for safe conversion to `Option` * @see {@link fromInputUnsafe} for throwing conversion * @see {@link DurationObject} for object-shaped duration input * @see {@link Unit} for supported string units * * @stability stable * @category models * @since 4.0.0 */ export type Input = Duration | number | bigint | readonly [seconds: number, nanos: number] | `${number} ${Unit}` | "Infinity" | "-Infinity" | DurationObject; /** * An object with optional duration components that can be combined to create * a Duration. All fields are optional and additive. * * **Details** * * Compatible with Temporal.Duration-like objects. * * **Example** (Combining duration object fields) * * ```ts import.meta.vitest * import { Duration } from "effect" * * Duration.fromInputUnsafe({ seconds: 30 }) // => Duration.seconds(30) * Duration.fromInputUnsafe({ days: 1 }) // => Duration.days(1) * Duration.fromInputUnsafe({ seconds: 1, nanoseconds: 500 }) // => Duration.nanos(1_000_000_500n) * ``` * * @stability stable * @category models * @since 4.0.0 */ export interface DurationObject { readonly weeks?: number | undefined; readonly days?: number | undefined; readonly hours?: number | undefined; readonly minutes?: number | undefined; readonly seconds?: number | undefined; readonly milliseconds?: number | undefined; readonly microseconds?: number | undefined; readonly nanoseconds?: number | undefined; } /** * Decodes a `Duration.Input` into a `Duration`. * * **When to use** * * Use when the input has already been validated or comes from a trusted source * and throwing is acceptable for invalid duration syntax. * * **Gotchas** * * If the input is not a valid `Duration.Input`, it throws an error. * * **Example** (Decoding duration inputs) * * ```ts import.meta.vitest * import { Duration } from "effect" * * Duration.fromInputUnsafe(1000) // => Duration.millis(1000) * Duration.fromInputUnsafe("5 seconds") // => Duration.seconds(5) * Duration.fromInputUnsafe("Infinity") // => Duration.infinity * Duration.fromInputUnsafe([2, 500_000_000]) // => Duration.nanos(2_500_000_000n) * ``` * * @stability stable * @category constructors * @since 4.0.0 */ export declare const fromInputUnsafe: (input: Input) => Duration; /** * Decodes a `Input` value into a `Duration` safely, returning * `Option.none()` if decoding fails. * * **Example** (Safely decoding duration inputs) * * ```ts import.meta.vitest * import { Duration, Option } from "effect" * * Duration.fromInput(1000) // => Option.some(Duration.seconds(1)) * Duration.fromInput("invalid" as any) // => Option.none() * ``` * * @stability stable * @category constructors * @since 4.0.0 */ export declare const fromInput: (u: Input) => Option.Option; /** * Checks whether a value is a Duration. * * **Example** (Checking for durations) * * ```ts import.meta.vitest * import { Duration } from "effect" * * Duration.isDuration(Duration.seconds(1)) // => true * Duration.isDuration(1000) // => false * ``` * * @stability stable * @category guards * @since 2.0.0 */ export declare const isDuration: (u: unknown) => u is Duration; /** * Checks whether a Duration is finite (not infinite). * * **Example** (Checking finite durations) * * ```ts import.meta.vitest * import { Duration } from "effect" * * Duration.isFinite(Duration.seconds(5)) // => true * Duration.isFinite(Duration.infinity) // => false * ``` * * @stability stable * @category predicates * @since 2.0.0 */ export declare const isFinite: (self: Duration) => boolean; /** * Checks whether a Duration is zero. * * **Example** (Checking for zero durations) * * ```ts import.meta.vitest * import { Duration } from "effect" * * Duration.isZero(Duration.zero) // => true * Duration.isZero(Duration.seconds(1)) // => false * ``` * * @stability stable * @category predicates * @since 3.5.0 */ export declare const isZero: (self: Duration) => boolean; /** * Returns `true` if the duration is negative (strictly less than zero). * * **Example** (Checking for negative durations) * * ```ts import.meta.vitest * import { Duration } from "effect" * * Duration.isNegative(Duration.seconds(-5)) // => true * Duration.isNegative(Duration.zero) // => false * Duration.isNegative(Duration.negativeInfinity) // => true * ``` * * @stability stable * @category predicates * @since 4.0.0 */ export declare const isNegative: (self: Duration) => boolean; /** * Returns `true` if the duration is positive (strictly greater than zero). * * **Example** (Checking for positive durations) * * ```ts import.meta.vitest * import { Duration } from "effect" * * Duration.isPositive(Duration.seconds(5)) // => true * Duration.isPositive(Duration.zero) // => false * Duration.isPositive(Duration.infinity) // => true * ``` * * @stability stable * @category predicates * @since 4.0.0 */ export declare const isPositive: (self: Duration) => boolean; /** * Returns the absolute value of the duration. * * **Example** (Taking absolute duration values) * * ```ts import.meta.vitest * import { Duration } from "effect" * * Duration.abs(Duration.seconds(-5)) // => Duration.seconds(5) * Duration.abs(Duration.negativeInfinity) // => Duration.infinity * ``` * * @stability stable * @category math * @since 4.0.0 */ export declare const abs: (self: Duration) => Duration; /** * Returns the negated duration. * * **Example** (Negating durations) * * ```ts import.meta.vitest * import { Duration } from "effect" * * Duration.negate(Duration.seconds(5)) // => Duration.seconds(-5) * Duration.negate(Duration.infinity) // => Duration.negativeInfinity * ``` * * @stability stable * @category math * @since 4.0.0 */ export declare const negate: (self: Duration) => Duration; /** * A Duration representing zero time. * * **Example** (Referencing the zero duration) * * ```ts import.meta.vitest * import { Duration } from "effect" * * Duration.toMillis(Duration.zero) // => 0 * ``` * * @stability stable * @category constructors * @since 2.0.0 */ export declare const zero: Duration; /** * A Duration representing infinite time. * * **Example** (Referencing infinite duration) * * ```ts import.meta.vitest * import { Duration } from "effect" * * Duration.toMillis(Duration.infinity) // => Infinity * ``` * * @stability stable * @category constructors * @since 2.0.0 */ export declare const infinity: Duration; /** * A Duration representing negative infinite time. * * **Example** (Referencing negative infinite duration) * * ```ts import.meta.vitest * import { Duration } from "effect" * * Duration.toMillis(Duration.negativeInfinity) // => -Infinity * ``` * * @stability stable * @category constructors * @since 4.0.0 */ export declare const negativeInfinity: Duration; /** * Creates a Duration from nanoseconds. * * **Example** (Creating durations from nanoseconds) * * ```ts import.meta.vitest * import { Duration } from "effect" * * Duration.nanos(500_000_000n) // => Duration.nanos(500_000_000n) * ``` * * @stability stable * @category constructors * @since 2.0.0 */ export declare const nanos: (nanos: bigint) => Duration; /** * Creates a Duration from microseconds. * * **Example** (Creating durations from microseconds) * * ```ts import.meta.vitest * import { Duration } from "effect" * * Duration.micros(500_000n) // => Duration.nanos(500_000_000n) * ``` * * @stability stable * @category constructors * @since 2.0.0 */ export declare const micros: (micros: bigint) => Duration; /** * Creates a Duration from milliseconds. * * **Example** (Creating durations from milliseconds) * * ```ts import.meta.vitest * import { Duration } from "effect" * * Duration.toMillis(Duration.millis(1000)) // => 1000 * ``` * * @stability stable * @category constructors * @since 2.0.0 */ export declare const millis: (millis: number) => Duration; /** * Creates a Duration from seconds. * * **Example** (Creating durations from seconds) * * ```ts import.meta.vitest * import { Duration } from "effect" * * Duration.toMillis(Duration.seconds(30)) // => 30_000 * ``` * * @stability stable * @category constructors * @since 2.0.0 */ export declare const seconds: (seconds: number) => Duration; /** * Creates a Duration from minutes. * * **Example** (Creating durations from minutes) * * ```ts import.meta.vitest * import { Duration } from "effect" * * Duration.toMillis(Duration.minutes(5)) // => 300_000 * ``` * * @stability stable * @category constructors * @since 2.0.0 */ export declare const minutes: (minutes: number) => Duration; /** * Creates a Duration from hours. * * **Example** (Creating durations from hours) * * ```ts import.meta.vitest * import { Duration } from "effect" * * Duration.toMillis(Duration.hours(2)) // => 7_200_000 * ``` * * @stability stable * @category constructors * @since 2.0.0 */ export declare const hours: (hours: number) => Duration; /** * Creates a Duration from days. * * **Example** (Creating durations from days) * * ```ts import.meta.vitest * import { Duration } from "effect" * * Duration.toMillis(Duration.days(1)) // => 86_400_000 * ``` * * @stability stable * @category constructors * @since 2.0.0 */ export declare const days: (days: number) => Duration; /** * Creates a Duration from weeks. * * **Example** (Creating durations from weeks) * * ```ts import.meta.vitest * import { Duration } from "effect" * * Duration.toMillis(Duration.weeks(1)) // => 604_800_000 * ``` * * @stability stable * @category constructors * @since 2.0.0 */ export declare const weeks: (weeks: number) => Duration; /** * Converts a Duration to milliseconds. * * **Example** (Converting durations to milliseconds) * * ```ts import.meta.vitest * import { Duration } from "effect" * * Duration.toMillis(Duration.seconds(5)) // => 5000 * Duration.toMillis(Duration.minutes(2)) // => 120_000 * ``` * * @stability stable * @category getters * @since 2.0.0 */ export declare const toMillis: (self: Input) => number; /** * Converts a Duration to seconds. * * **Example** (Converting durations to seconds) * * ```ts import.meta.vitest * import { Duration } from "effect" * * Duration.toSeconds(Duration.millis(5000)) // => 5 * Duration.toSeconds(Duration.minutes(2)) // => 120 * ``` * * @stability stable * @category getters * @since 2.0.0 */ export declare const toSeconds: (self: Input) => number; /** * Converts a Duration to minutes. * * **Example** (Converting durations to minutes) * * ```ts import.meta.vitest * import { Duration } from "effect" * * Duration.toMinutes(Duration.seconds(120)) // => 2 * Duration.toMinutes(Duration.hours(1)) // => 60 * ``` * * @stability stable * @category getters * @since 3.8.0 */ export declare const toMinutes: (self: Input) => number; /** * Converts a Duration to hours. * * **Example** (Converting durations to hours) * * ```ts import.meta.vitest * import { Duration } from "effect" * * Duration.toHours(Duration.minutes(120)) // => 2 * Duration.toHours(Duration.days(1)) // => 24 * ``` * * @stability stable * @category getters * @since 3.8.0 */ export declare const toHours: (self: Input) => number; /** * Converts a Duration to days. * * **Example** (Converting durations to days) * * ```ts import.meta.vitest * import { Duration } from "effect" * * Duration.toDays(Duration.hours(48)) // => 2 * Duration.toDays(Duration.weeks(1)) // => 7 * ``` * * @stability stable * @category getters * @since 3.8.0 */ export declare const toDays: (self: Input) => number; /** * Converts a Duration to weeks. * * **Example** (Converting durations to weeks) * * ```ts import.meta.vitest * import { Duration } from "effect" * * Duration.toWeeks(Duration.days(14)) // => 2 * Duration.toWeeks(Duration.days(7)) // => 1 * ``` * * @stability stable * @category getters * @since 3.8.0 */ export declare const toWeeks: (self: Input) => number; /** * Gets the duration in nanoseconds as a bigint. * * **When to use** * * Use when the duration is known to be finite and you need the nanosecond value * as a `bigint`. * * **Details** * * Millisecond-backed fractional durations are rounded to the nearest * nanosecond, with ties away from zero. * * **Gotchas** * * If the duration is infinite, it throws an error. * * **Example** (Reading nanoseconds unsafely) * * ```ts import.meta.vitest * import { Duration } from "effect" * * Duration.toNanosUnsafe(Duration.seconds(2)) // => 2_000_000_000n * * // Duration.toNanosUnsafe(Duration.infinity) * // throws Error: "Cannot convert infinite duration to nanos" * ``` * * @stability stable * @category getters * @since 4.0.0 */ export declare const toNanosUnsafe: (input: Input) => bigint; /** * Gets the duration in nanoseconds safely as an `Option`. * * **Details** * * If the duration is infinite, returns `Option.none()`. * * **Example** (Safely reading nanoseconds) * * ```ts import.meta.vitest * import { Duration, Option } from "effect" * * Duration.toNanos(Duration.seconds(1)) // => Option.some(1_000_000_000n) * Duration.toNanos(Duration.infinity) // => Option.none() * ``` * * @stability stable * @category getters * @since 2.0.0 */ export declare const toNanos: (self: Input) => Option.Option; /** * Converts a Duration to high-resolution time format [seconds, nanoseconds]. * * **Example** (Converting durations to high-resolution time) * * ```ts import.meta.vitest * import { Duration } from "effect" * * Duration.toHrTime(Duration.millis(1500)) // => [1, 500_000_000] * ``` * * @stability stable * @category getters * @since 2.0.0 */ export declare const toHrTime: (input: Input) => [seconds: number, nanos: number]; /** * Pattern matches on the representation of a `Duration`. * * **Details** * * Provide handlers for millisecond-backed values, nanosecond-backed values, * and positive infinity. Use `onNegativeInfinity` to handle negative infinity * separately; otherwise negative infinity is handled by `onInfinity`. * * **Example** (Pattern matching on duration representations) * * ```ts import.meta.vitest * import { Duration } from "effect" * * Duration.match(Duration.seconds(5), { * onMillis: (millis) => `${millis} milliseconds`, * onNanos: (nanos) => `${nanos} nanoseconds`, * onInfinity: () => "infinite" * }) // => "5000 milliseconds" * ``` * * @stability stable * @category pattern matching * @since 2.0.0 */ export declare const match: { /** * Pattern matches on the representation of a `Duration`. * * **Details** * * Provide handlers for millisecond-backed values, nanosecond-backed values, * and positive infinity. Use `onNegativeInfinity` to handle negative infinity * separately; otherwise negative infinity is handled by `onInfinity`. * * **Example** (Pattern matching on duration representations) * * ```ts import.meta.vitest * import { Duration } from "effect" * * Duration.match(Duration.seconds(5), { * onMillis: (millis) => `${millis} milliseconds`, * onNanos: (nanos) => `${nanos} nanoseconds`, * onInfinity: () => "infinite" * }) // => "5000 milliseconds" * ``` * * @stability stable * @category pattern matching * @since 2.0.0 */ (options: { readonly onMillis: (millis: number) => A; readonly onNanos: (nanos: bigint) => B; readonly onInfinity: () => C; readonly onNegativeInfinity?: () => D; }): (self: Duration) => A | B | C | D; /** * Pattern matches on the representation of a `Duration`. * * **Details** * * Provide handlers for millisecond-backed values, nanosecond-backed values, * and positive infinity. Use `onNegativeInfinity` to handle negative infinity * separately; otherwise negative infinity is handled by `onInfinity`. * * **Example** (Pattern matching on duration representations) * * ```ts import.meta.vitest * import { Duration } from "effect" * * Duration.match(Duration.seconds(5), { * onMillis: (millis) => `${millis} milliseconds`, * onNanos: (nanos) => `${nanos} nanoseconds`, * onInfinity: () => "infinite" * }) // => "5000 milliseconds" * ``` * * @stability stable * @category pattern matching * @since 2.0.0 */ (self: Duration, options: { readonly onMillis: (millis: number) => A; readonly onNanos: (nanos: bigint) => B; readonly onInfinity: () => C; readonly onNegativeInfinity?: () => D; }): A | B | C | D; }; /** * Pattern matches on two `Duration`s, providing handlers that receive both values. * * **Example** (Pattern matching on duration pairs) * * ```ts import.meta.vitest * import { Duration } from "effect" * * Duration.matchPair(Duration.seconds(3), Duration.seconds(2), { * onMillis: (a, b) => a + b, * onNanos: (a, b) => Number(a + b), * onInfinity: () => Infinity * }) // => 5000 * ``` * * @stability stable * @category pattern matching * @since 4.0.0 */ export declare const matchPair: { /** * Pattern matches on two `Duration`s, providing handlers that receive both values. * * **Example** (Pattern matching on duration pairs) * * ```ts import.meta.vitest * import { Duration } from "effect" * * Duration.matchPair(Duration.seconds(3), Duration.seconds(2), { * onMillis: (a, b) => a + b, * onNanos: (a, b) => Number(a + b), * onInfinity: () => Infinity * }) // => 5000 * ``` * * @stability stable * @category pattern matching * @since 4.0.0 */ (that: Duration, options: { readonly onMillis: (self: number, that: number) => A; readonly onNanos: (self: bigint, that: bigint) => B; readonly onInfinity: (self: Duration, that: Duration) => C; }): (self: Duration) => A | B | C; /** * Pattern matches on two `Duration`s, providing handlers that receive both values. * * **Example** (Pattern matching on duration pairs) * * ```ts import.meta.vitest * import { Duration } from "effect" * * Duration.matchPair(Duration.seconds(3), Duration.seconds(2), { * onMillis: (a, b) => a + b, * onNanos: (a, b) => Number(a + b), * onInfinity: () => Infinity * }) // => 5000 * ``` * * @stability stable * @category pattern matching * @since 4.0.0 */ (self: Duration, that: Duration, options: { readonly onMillis: (self: number, that: number) => A; readonly onNanos: (self: bigint, that: bigint) => B; readonly onInfinity: (self: Duration, that: Duration) => C; }): A | B | C; }; /** * Provides an `Order` instance for comparing `Duration` values. * * **Details** * * `NegativeInfinity` < any finite value < `Infinity`. * * **Example** (Sorting durations) * * ```ts import.meta.vitest * import { Duration } from "effect" * * const durations = [ * Duration.seconds(3), * Duration.seconds(1), * Duration.seconds(2) * ] * durations.sort((a, b) => Duration.Order(a, b)).map(Duration.toSeconds) // => [1, 2, 3] * ``` * * @stability stable * @category instances * @since 2.0.0 */ export declare const Order: order.Order; /** * Returns `true` if a `Duration` is greater than or equal to `minimum` and * less than or equal to `maximum`, according to `Duration.Order`. * * **When to use** * * Use to test whether a duration is inside an inclusive range. * * **Details** * * Both bounds are inclusive and compared with `Duration.Order`. * * **Gotchas** * * The bounds are not normalized. If `minimum` is greater than `maximum`, the * predicate returns `false` for every duration. * * **Example** (Checking duration ranges) * * ```ts import.meta.vitest * import { Duration } from "effect" * * Duration.between(Duration.seconds(3), { * minimum: Duration.seconds(2), * maximum: Duration.seconds(5) * }) // => true * ``` * * @see {@link clamp} for constraining a duration to a range * @see {@link isGreaterThanOrEqualTo} for checking only the lower bound * @see {@link isLessThanOrEqualTo} for checking only the upper bound * * @stability stable * @category predicates * @since 2.0.0 */ export declare const between: { /** * Returns `true` if a `Duration` is greater than or equal to `minimum` and * less than or equal to `maximum`, according to `Duration.Order`. * * **When to use** * * Use to test whether a duration is inside an inclusive range. * * **Details** * * Both bounds are inclusive and compared with `Duration.Order`. * * **Gotchas** * * The bounds are not normalized. If `minimum` is greater than `maximum`, the * predicate returns `false` for every duration. * * **Example** (Checking duration ranges) * * ```ts import.meta.vitest * import { Duration } from "effect" * * Duration.between(Duration.seconds(3), { * minimum: Duration.seconds(2), * maximum: Duration.seconds(5) * }) // => true * ``` * * @see {@link clamp} for constraining a duration to a range * @see {@link isGreaterThanOrEqualTo} for checking only the lower bound * @see {@link isLessThanOrEqualTo} for checking only the upper bound * * @stability stable * @category predicates * @since 2.0.0 */ (options: { minimum: Duration; maximum: Duration; }): (self: Duration) => boolean; /** * Returns `true` if a `Duration` is greater than or equal to `minimum` and * less than or equal to `maximum`, according to `Duration.Order`. * * **When to use** * * Use to test whether a duration is inside an inclusive range. * * **Details** * * Both bounds are inclusive and compared with `Duration.Order`. * * **Gotchas** * * The bounds are not normalized. If `minimum` is greater than `maximum`, the * predicate returns `false` for every duration. * * **Example** (Checking duration ranges) * * ```ts import.meta.vitest * import { Duration } from "effect" * * Duration.between(Duration.seconds(3), { * minimum: Duration.seconds(2), * maximum: Duration.seconds(5) * }) // => true * ``` * * @see {@link clamp} for constraining a duration to a range * @see {@link isGreaterThanOrEqualTo} for checking only the lower bound * @see {@link isLessThanOrEqualTo} for checking only the upper bound * * @stability stable * @category predicates * @since 2.0.0 */ (self: Duration, options: { minimum: Duration; maximum: Duration; }): boolean; }; /** * Provides an `Equivalence` instance for comparing `Duration` values. * * **Example** (Comparing durations for equivalence) * * ```ts import.meta.vitest * import { Duration } from "effect" * * Duration.Equivalence(Duration.seconds(5), Duration.millis(5000)) // => true * ``` * * @stability stable * @category instances * @since 2.0.0 */ export declare const Equivalence: Equ.Equivalence; /** * Returns the smaller of two Durations. * * **Example** (Selecting the shorter duration) * * ```ts import.meta.vitest * import { Duration } from "effect" * * Duration.min(Duration.seconds(5), Duration.seconds(3)) // => Duration.seconds(3) * ``` * * @stability stable * @category ordering * @since 2.0.0 */ export declare const min: { /** * Returns the smaller of two Durations. * * **Example** (Selecting the shorter duration) * * ```ts import.meta.vitest * import { Duration } from "effect" * * Duration.min(Duration.seconds(5), Duration.seconds(3)) // => Duration.seconds(3) * ``` * * @stability stable * @category ordering * @since 2.0.0 */ (that: Duration): (self: Duration) => Duration; /** * Returns the smaller of two Durations. * * **Example** (Selecting the shorter duration) * * ```ts import.meta.vitest * import { Duration } from "effect" * * Duration.min(Duration.seconds(5), Duration.seconds(3)) // => Duration.seconds(3) * ``` * * @stability stable * @category ordering * @since 2.0.0 */ (self: Duration, that: Duration): Duration; }; /** * Returns the larger of two Durations. * * **Example** (Selecting the longer duration) * * ```ts import.meta.vitest * import { Duration } from "effect" * * Duration.max(Duration.seconds(5), Duration.seconds(3)) // => Duration.seconds(5) * ``` * * @stability stable * @category ordering * @since 2.0.0 */ export declare const max: { /** * Returns the larger of two Durations. * * **Example** (Selecting the longer duration) * * ```ts import.meta.vitest * import { Duration } from "effect" * * Duration.max(Duration.seconds(5), Duration.seconds(3)) // => Duration.seconds(5) * ``` * * @stability stable * @category ordering * @since 2.0.0 */ (that: Duration): (self: Duration) => Duration; /** * Returns the larger of two Durations. * * **Example** (Selecting the longer duration) * * ```ts import.meta.vitest * import { Duration } from "effect" * * Duration.max(Duration.seconds(5), Duration.seconds(3)) // => Duration.seconds(5) * ``` * * @stability stable * @category ordering * @since 2.0.0 */ (self: Duration, that: Duration): Duration; }; /** * Returns a `Duration` constrained between a minimum and maximum value. * * **Example** (Clamping durations to a range) * * ```ts import.meta.vitest * import { Duration } from "effect" * * Duration.clamp(Duration.seconds(10), { * minimum: Duration.seconds(2), * maximum: Duration.seconds(5) * }) // => Duration.seconds(5) * ``` * * @stability stable * @category ordering * @since 2.0.0 */ export declare const clamp: { /** * Returns a `Duration` constrained between a minimum and maximum value. * * **Example** (Clamping durations to a range) * * ```ts import.meta.vitest * import { Duration } from "effect" * * Duration.clamp(Duration.seconds(10), { * minimum: Duration.seconds(2), * maximum: Duration.seconds(5) * }) // => Duration.seconds(5) * ``` * * @stability stable * @category ordering * @since 2.0.0 */ (options: { minimum: Duration; maximum: Duration; }): (self: Duration) => Duration; /** * Returns a `Duration` constrained between a minimum and maximum value. * * **Example** (Clamping durations to a range) * * ```ts import.meta.vitest * import { Duration } from "effect" * * Duration.clamp(Duration.seconds(10), { * minimum: Duration.seconds(2), * maximum: Duration.seconds(5) * }) // => Duration.seconds(5) * ``` * * @stability stable * @category ordering * @since 2.0.0 */ (self: Duration, options: { minimum: Duration; maximum: Duration; }): Duration; }; /** * Divides a `Duration` by a finite, non-zero number safely. * * **Details** * * Returns `Option.none()` for zero, negative zero, or non-finite divisors. For * nanosecond-backed durations, also returns `Option.none()` when the divisor * cannot be converted to a `bigint`, such as a fractional divisor. * * **Example** (Safely dividing durations) * * ```ts import.meta.vitest * import { Duration, Option } from "effect" * * Duration.divide(Duration.seconds(10), 2) // => Option.some(Duration.seconds(5)) * Duration.divide(Duration.seconds(10), 0) // => Option.none() * ``` * * @stability stable * @category math * @since 2.4.19 */ export declare const divide: { /** * Divides a `Duration` by a finite, non-zero number safely. * * **Details** * * Returns `Option.none()` for zero, negative zero, or non-finite divisors. For * nanosecond-backed durations, also returns `Option.none()` when the divisor * cannot be converted to a `bigint`, such as a fractional divisor. * * **Example** (Safely dividing durations) * * ```ts import.meta.vitest * import { Duration, Option } from "effect" * * Duration.divide(Duration.seconds(10), 2) // => Option.some(Duration.seconds(5)) * Duration.divide(Duration.seconds(10), 0) // => Option.none() * ``` * * @stability stable * @category math * @since 2.4.19 */ (by: number): (self: Duration) => Option.Option; /** * Divides a `Duration` by a finite, non-zero number safely. * * **Details** * * Returns `Option.none()` for zero, negative zero, or non-finite divisors. For * nanosecond-backed durations, also returns `Option.none()` when the divisor * cannot be converted to a `bigint`, such as a fractional divisor. * * **Example** (Safely dividing durations) * * ```ts import.meta.vitest * import { Duration, Option } from "effect" * * Duration.divide(Duration.seconds(10), 2) // => Option.some(Duration.seconds(5)) * Duration.divide(Duration.seconds(10), 0) // => Option.none() * ``` * * @stability stable * @category math * @since 2.4.19 */ (self: Duration, by: number): Option.Option; }; /** * Divides a `Duration` by a number using fallback rules instead of returning * an `Option`. * * **When to use** * * Use when dividing a `Duration` should return `Duration.zero` or signed * infinity for invalid cases instead of forcing callers to handle `Option.none`. * * **Details** * * Non-finite divisors return `Duration.zero`. Division by positive or negative * zero can produce signed infinity for non-zero finite durations, while zero * or infinite durations divided by zero produce `Duration.zero`. * Nanosecond-backed durations return `Duration.zero` when the divisor cannot * be converted to a `bigint`. * * **Example** (Dividing durations unsafely) * * ```ts import.meta.vitest * import { Duration } from "effect" * * Duration.divideUnsafe(Duration.seconds(10), 2) // => Duration.seconds(5) * Duration.divideUnsafe(Duration.seconds(10), 0) // => Duration.infinity * ``` * * @stability stable * @category math * @since 4.0.0 */ export declare const divideUnsafe: { /** * Divides a `Duration` by a number using fallback rules instead of returning * an `Option`. * * **When to use** * * Use when dividing a `Duration` should return `Duration.zero` or signed * infinity for invalid cases instead of forcing callers to handle `Option.none`. * * **Details** * * Non-finite divisors return `Duration.zero`. Division by positive or negative * zero can produce signed infinity for non-zero finite durations, while zero * or infinite durations divided by zero produce `Duration.zero`. * Nanosecond-backed durations return `Duration.zero` when the divisor cannot * be converted to a `bigint`. * * **Example** (Dividing durations unsafely) * * ```ts import.meta.vitest * import { Duration } from "effect" * * Duration.divideUnsafe(Duration.seconds(10), 2) // => Duration.seconds(5) * Duration.divideUnsafe(Duration.seconds(10), 0) // => Duration.infinity * ``` * * @stability stable * @category math * @since 4.0.0 */ (by: number): (self: Duration) => Duration; /** * Divides a `Duration` by a number using fallback rules instead of returning * an `Option`. * * **When to use** * * Use when dividing a `Duration` should return `Duration.zero` or signed * infinity for invalid cases instead of forcing callers to handle `Option.none`. * * **Details** * * Non-finite divisors return `Duration.zero`. Division by positive or negative * zero can produce signed infinity for non-zero finite durations, while zero * or infinite durations divided by zero produce `Duration.zero`. * Nanosecond-backed durations return `Duration.zero` when the divisor cannot * be converted to a `bigint`. * * **Example** (Dividing durations unsafely) * * ```ts import.meta.vitest * import { Duration } from "effect" * * Duration.divideUnsafe(Duration.seconds(10), 2) // => Duration.seconds(5) * Duration.divideUnsafe(Duration.seconds(10), 0) // => Duration.infinity * ``` * * @stability stable * @category math * @since 4.0.0 */ (self: Duration, by: number): Duration; }; /** * Returns a `Duration` multiplied by a number. * * **Details** * * Fractional multipliers on nanosecond-backed durations round the result to * the nearest nanosecond, with ties rounding away from zero. Infinite * durations return positive infinity, negative infinity, or zero depending on * the multiplier sign. * * **Example** (Multiplying durations) * * ```ts import.meta.vitest * import { Duration } from "effect" * * Duration.times(Duration.seconds(5), 2) // => Duration.seconds(10) * ``` * * @stability stable * @category math * @since 2.0.0 */ export declare const times: { /** * Returns a `Duration` multiplied by a number. * * **Details** * * Fractional multipliers on nanosecond-backed durations round the result to * the nearest nanosecond, with ties rounding away from zero. Infinite * durations return positive infinity, negative infinity, or zero depending on * the multiplier sign. * * **Example** (Multiplying durations) * * ```ts import.meta.vitest * import { Duration } from "effect" * * Duration.times(Duration.seconds(5), 2) // => Duration.seconds(10) * ``` * * @stability stable * @category math * @since 2.0.0 */ (times: number): (self: Duration) => Duration; /** * Returns a `Duration` multiplied by a number. * * **Details** * * Fractional multipliers on nanosecond-backed durations round the result to * the nearest nanosecond, with ties rounding away from zero. Infinite * durations return positive infinity, negative infinity, or zero depending on * the multiplier sign. * * **Example** (Multiplying durations) * * ```ts import.meta.vitest * import { Duration } from "effect" * * Duration.times(Duration.seconds(5), 2) // => Duration.seconds(10) * ``` * * @stability stable * @category math * @since 2.0.0 */ (self: Duration, times: number): Duration; }; /** * Subtracts one Duration from another. The result can be negative. * * **Details** * * Infinity subtraction follows signed-infinity arithmetic. Subtracting the * same infinity from itself returns zero. Positive infinity minus negative * infinity or any finite duration remains positive infinity. Negative infinity * minus positive infinity or any finite duration remains negative infinity. * Finite durations minus positive infinity produce negative infinity, and * finite durations minus negative infinity produce positive infinity. * * **Example** (Subtracting durations) * * ```ts import.meta.vitest * import { Duration } from "effect" * * Duration.subtract(Duration.seconds(10), Duration.seconds(3)) // => Duration.seconds(7) * ``` * * @stability stable * @category math * @since 2.0.0 */ export declare const subtract: { /** * Subtracts one Duration from another. The result can be negative. * * **Details** * * Infinity subtraction follows signed-infinity arithmetic. Subtracting the * same infinity from itself returns zero. Positive infinity minus negative * infinity or any finite duration remains positive infinity. Negative infinity * minus positive infinity or any finite duration remains negative infinity. * Finite durations minus positive infinity produce negative infinity, and * finite durations minus negative infinity produce positive infinity. * * **Example** (Subtracting durations) * * ```ts import.meta.vitest * import { Duration } from "effect" * * Duration.subtract(Duration.seconds(10), Duration.seconds(3)) // => Duration.seconds(7) * ``` * * @stability stable * @category math * @since 2.0.0 */ (that: Duration): (self: Duration) => Duration; /** * Subtracts one Duration from another. The result can be negative. * * **Details** * * Infinity subtraction follows signed-infinity arithmetic. Subtracting the * same infinity from itself returns zero. Positive infinity minus negative * infinity or any finite duration remains positive infinity. Negative infinity * minus positive infinity or any finite duration remains negative infinity. * Finite durations minus positive infinity produce negative infinity, and * finite durations minus negative infinity produce positive infinity. * * **Example** (Subtracting durations) * * ```ts import.meta.vitest * import { Duration } from "effect" * * Duration.subtract(Duration.seconds(10), Duration.seconds(3)) // => Duration.seconds(7) * ``` * * @stability stable * @category math * @since 2.0.0 */ (self: Duration, that: Duration): Duration; }; /** * Adds two Durations together. * * **Details** * * Infinity addition follows these rules: * * - infinity + infinity = infinity * - infinity + negativeInfinity = zero * - infinity + finite = infinity * - negativeInfinity + negativeInfinity = negativeInfinity * - negativeInfinity + finite = negativeInfinity * * **Example** (Adding durations) * * ```ts import.meta.vitest * import { Duration } from "effect" * * Duration.sum(Duration.seconds(5), Duration.seconds(3)) // => Duration.seconds(8) * ``` * * @stability stable * @category math * @since 2.0.0 */ export declare const sum: { /** * Adds two Durations together. * * **Details** * * Infinity addition follows these rules: * * - infinity + infinity = infinity * - infinity + negativeInfinity = zero * - infinity + finite = infinity * - negativeInfinity + negativeInfinity = negativeInfinity * - negativeInfinity + finite = negativeInfinity * * **Example** (Adding durations) * * ```ts import.meta.vitest * import { Duration } from "effect" * * Duration.sum(Duration.seconds(5), Duration.seconds(3)) // => Duration.seconds(8) * ``` * * @stability stable * @category math * @since 2.0.0 */ (that: Duration): (self: Duration) => Duration; /** * Adds two Durations together. * * **Details** * * Infinity addition follows these rules: * * - infinity + infinity = infinity * - infinity + negativeInfinity = zero * - infinity + finite = infinity * - negativeInfinity + negativeInfinity = negativeInfinity * - negativeInfinity + finite = negativeInfinity * * **Example** (Adding durations) * * ```ts import.meta.vitest * import { Duration } from "effect" * * Duration.sum(Duration.seconds(5), Duration.seconds(3)) // => Duration.seconds(8) * ``` * * @stability stable * @category math * @since 2.0.0 */ (self: Duration, that: Duration): Duration; }; /** * Checks whether the first Duration is less than the second. * * **Example** (Comparing durations with less than) * * ```ts import.meta.vitest * import { Duration } from "effect" * * Duration.isLessThan(Duration.seconds(3), Duration.seconds(5)) // => true * ``` * * @stability stable * @category predicates * @since 4.0.0 */ export declare const isLessThan: { /** * Checks whether the first Duration is less than the second. * * **Example** (Comparing durations with less than) * * ```ts import.meta.vitest * import { Duration } from "effect" * * Duration.isLessThan(Duration.seconds(3), Duration.seconds(5)) // => true * ``` * * @stability stable * @category predicates * @since 4.0.0 */ (that: Duration): (self: Duration) => boolean; /** * Checks whether the first Duration is less than the second. * * **Example** (Comparing durations with less than) * * ```ts import.meta.vitest * import { Duration } from "effect" * * Duration.isLessThan(Duration.seconds(3), Duration.seconds(5)) // => true * ``` * * @stability stable * @category predicates * @since 4.0.0 */ (self: Duration, that: Duration): boolean; }; /** * Checks whether the first Duration is less than or equal to the second. * * **Example** (Comparing durations with less than or equal) * * ```ts import.meta.vitest * import { Duration } from "effect" * * Duration.isLessThanOrEqualTo( * Duration.seconds(5), * Duration.seconds(5) * ) // => true * ``` * * @stability stable * @category predicates * @since 4.0.0 */ export declare const isLessThanOrEqualTo: { /** * Checks whether the first Duration is less than or equal to the second. * * **Example** (Comparing durations with less than or equal) * * ```ts import.meta.vitest * import { Duration } from "effect" * * Duration.isLessThanOrEqualTo( * Duration.seconds(5), * Duration.seconds(5) * ) // => true * ``` * * @stability stable * @category predicates * @since 4.0.0 */ (that: Duration): (self: Duration) => boolean; /** * Checks whether the first Duration is less than or equal to the second. * * **Example** (Comparing durations with less than or equal) * * ```ts import.meta.vitest * import { Duration } from "effect" * * Duration.isLessThanOrEqualTo( * Duration.seconds(5), * Duration.seconds(5) * ) // => true * ``` * * @stability stable * @category predicates * @since 4.0.0 */ (self: Duration, that: Duration): boolean; }; /** * Checks whether the first Duration is greater than the second. * * **Example** (Comparing durations with greater than) * * ```ts import.meta.vitest * import { Duration } from "effect" * * Duration.isGreaterThan(Duration.seconds(5), Duration.seconds(3)) // => true * ``` * * @stability stable * @category predicates * @since 4.0.0 */ export declare const isGreaterThan: { /** * Checks whether the first Duration is greater than the second. * * **Example** (Comparing durations with greater than) * * ```ts import.meta.vitest * import { Duration } from "effect" * * Duration.isGreaterThan(Duration.seconds(5), Duration.seconds(3)) // => true * ``` * * @stability stable * @category predicates * @since 4.0.0 */ (that: Duration): (self: Duration) => boolean; /** * Checks whether the first Duration is greater than the second. * * **Example** (Comparing durations with greater than) * * ```ts import.meta.vitest * import { Duration } from "effect" * * Duration.isGreaterThan(Duration.seconds(5), Duration.seconds(3)) // => true * ``` * * @stability stable * @category predicates * @since 4.0.0 */ (self: Duration, that: Duration): boolean; }; /** * Checks whether the first Duration is greater than or equal to the second. * * **Example** (Comparing durations with greater than or equal) * * ```ts import.meta.vitest * import { Duration } from "effect" * * Duration.isGreaterThanOrEqualTo( * Duration.seconds(5), * Duration.seconds(5) * ) // => true * ``` * * @stability stable * @category predicates * @since 4.0.0 */ export declare const isGreaterThanOrEqualTo: { /** * Checks whether the first Duration is greater than or equal to the second. * * **Example** (Comparing durations with greater than or equal) * * ```ts import.meta.vitest * import { Duration } from "effect" * * Duration.isGreaterThanOrEqualTo( * Duration.seconds(5), * Duration.seconds(5) * ) // => true * ``` * * @stability stable * @category predicates * @since 4.0.0 */ (that: Duration): (self: Duration) => boolean; /** * Checks whether the first Duration is greater than or equal to the second. * * **Example** (Comparing durations with greater than or equal) * * ```ts import.meta.vitest * import { Duration } from "effect" * * Duration.isGreaterThanOrEqualTo( * Duration.seconds(5), * Duration.seconds(5) * ) // => true * ``` * * @stability stable * @category predicates * @since 4.0.0 */ (self: Duration, that: Duration): boolean; }; /** * Checks whether two Durations are equal. * * **Example** (Checking duration equality) * * ```ts import.meta.vitest * import { Duration } from "effect" * * Duration.equals(Duration.seconds(5), Duration.millis(5000)) // => true * ``` * * @stability stable * @category predicates * @since 2.0.0 */ export declare const equals: { /** * Checks whether two Durations are equal. * * **Example** (Checking duration equality) * * ```ts import.meta.vitest * import { Duration } from "effect" * * Duration.equals(Duration.seconds(5), Duration.millis(5000)) // => true * ``` * * @stability stable * @category predicates * @since 2.0.0 */ (that: Duration): (self: Duration) => boolean; /** * Checks whether two Durations are equal. * * **Example** (Checking duration equality) * * ```ts import.meta.vitest * import { Duration } from "effect" * * Duration.equals(Duration.seconds(5), Duration.millis(5000)) // => true * ``` * * @stability stable * @category predicates * @since 2.0.0 */ (self: Duration, that: Duration): boolean; }; /** * Decomposes a `Duration` into normalized signed components. * * **Details** * * Finite durations are returned as `{ days, hours, minutes, seconds, millis, * nanos }`. Infinite durations return every component as `Infinity` or * `-Infinity`. * * **Example** (Decomposing durations into parts) * * ```ts import.meta.vitest * import { Duration } from "effect" * * // Create a complex duration by adding multiple parts * const duration = Duration.sum( * Duration.sum( * Duration.sum(Duration.days(1), Duration.hours(2)), * Duration.sum(Duration.minutes(30), Duration.seconds(45)) * ), * Duration.millis(123) * ) * Duration.parts(duration) // => ({ days: 1, hours: 2, minutes: 30, seconds: 45, millis: 123, nanos: 0 }) * * const complex = Duration.sum(Duration.hours(25), Duration.minutes(90)) * Duration.parts(complex) // => ({ days: 1, hours: 2, minutes: 30, seconds: 0, millis: 0, nanos: 0 }) * ``` * * @stability stable * @category converting * @since 3.8.0 */ export declare const parts: (self: Duration) => { days: number; hours: number; minutes: number; seconds: number; millis: number; nanos: number; }; /** * Converts a `Duration` to a human readable string. * * **Example** (Formatting durations) * * ```ts import.meta.vitest * import { Duration } from "effect" * * Duration.format(Duration.millis(1000)) // => "1s" * Duration.format(Duration.millis(1001)) // => "1s 1ms" * ``` * * @stability stable * @category converting * @since 2.0.0 */ export declare const format: (self: Duration) => string; /** * Reducer for summing `Duration`s. * * **When to use** * * Use to sum many `Duration` values through APIs that consume a `Reducer`. * * **Details** * * `ReducerSum` uses `sum` and starts from `zero`, so `combineAll([])` returns * `zero`. * * @see {@link sum} for adding two duration values directly * @see {@link CombinerMax} for keeping the longest duration instead of summing * @see {@link CombinerMin} for keeping the shortest duration instead of summing * * @stability stable * @category math * @since 4.0.0 */ export declare const ReducerSum: Reducer.Reducer; /** * Combiner that returns the maximum `Duration`. * * **When to use** * * Use to keep the longest `Duration` when an API consumes a `Combiner`. * * @see {@link CombinerMin} for keeping the shortest `Duration` * @see {@link max} for comparing two `Duration` values directly * * @stability stable * @category math * @since 4.0.0 */ export declare const CombinerMax: Combiner.Combiner; /** * Combiner that returns the minimum `Duration`. * * **When to use** * * Use to keep the shortest `Duration` through APIs that consume a `Combiner`. * * @see {@link CombinerMax} for keeping the longest `Duration` * @see {@link min} for comparing two `Duration` values directly * * @stability stable * @category math * @since 4.0.0 */ export declare const CombinerMin: Combiner.Combiner; export {}; //# sourceMappingURL=Duration.d.ts.map