Duration
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.
Constructors
Signature
declare function days(days: number): Duration;Decodes a Input value into a Duration safely, returning Option.none() if decoding fails.
Signature
declare const fromInput: (u: Input) => Option.Option<Duration>;fromInputUnsafe
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.
Signature
declare function fromInputUnsafe(input: Input): Duration;Creates a Duration from hours.
Signature
declare function hours(hours: number): Duration;A Duration representing infinite time.
Signature
declare const infinity: Duration;Creates a Duration from microseconds.
Signature
declare function micros(micros: bigint): Duration;Creates a Duration from milliseconds.
Signature
declare function millis(millis: number): Duration;Creates a Duration from minutes.
Signature
declare function minutes(minutes: number): Duration;Creates a Duration from nanoseconds.
Signature
declare function nanos(nanos: bigint): Duration;negativeInfinity
A Duration representing negative infinite time.
Signature
declare const negativeInfinity: Duration;Creates a Duration from seconds.
Signature
declare function seconds(seconds: number): Duration;Creates a Duration from weeks.
Signature
declare function weeks(weeks: number): Duration;A Duration representing zero time.
Signature
declare const zero: Duration;Converting
Converts a Duration to a human readable string.
Signature
declare function format(self: Duration): string;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.
Signature
declare function parts(self: Duration): {
days: number;
hours: number;
millis: number;
minutes: number;
nanos: number;
seconds: number;
};Getters
Converts a Duration to days.
Signature
declare function toDays(self: Input): number;Converts a Duration to hours.
Signature
declare function toHours(self: Input): number;Converts a Duration to high-resolution time format [seconds, nanoseconds].
Signature
declare function toHrTime(input: Input): [seconds: number, nanos: number];Converts a Duration to milliseconds.
Signature
declare function toMillis(self: Input): number;Converts a Duration to minutes.
Signature
declare function toMinutes(self: Input): number;Gets the duration in nanoseconds safely as an Option<bigint>.
Details
If the duration is infinite, returns Option.none().
Signature
declare const toNanos: (self: Input) => Option.Option<bigint>;toNanosUnsafe
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.
Signature
declare function toNanosUnsafe(input: Input): bigint;Converts a Duration to seconds.
Signature
declare function toSeconds(self: Input): number;Converts a Duration to weeks.
Signature
declare function toWeeks(self: Input): number;Guards
isDuration
Checks whether a value is a Duration.
Signature
declare function isDuration(u: unknown): u is Duration;Instances
Equivalence
Provides an Equivalence instance for comparing Duration values.
Signature
declare const Equivalence: Equ.Equivalence<Duration>;Provides an Order instance for comparing Duration values.
Details
NegativeInfinity < any finite value < Infinity.
Signature
declare const Order: order.Order<Duration>;Math
Returns the absolute value of the duration.
Signature
declare function abs(self: Duration): Duration;CombinerMax
Combiner that returns the maximum Duration.
When to use
Use to keep the longest Duration when an API consumes a Combiner.
See
CombinerMinfor keeping the shortestDurationmaxfor comparing twoDurationvalues directly
Signature
declare const CombinerMax: Combiner.Combiner<Duration>;CombinerMin
Combiner that returns the minimum Duration.
When to use
Use to keep the shortest Duration through APIs that consume a Combiner.
See
CombinerMaxfor keeping the longestDurationminfor comparing twoDurationvalues directly
Signature
declare const CombinerMin: Combiner.Combiner<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.
Signature
declare const divide: {
(by: number): (self: Duration) => Option<Duration>;
(self: Duration, by: number): Option<Duration>;
};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.
Signature
declare const divideUnsafe: {
(by: number): (self: Duration) => Duration;
(self: Duration, by: number): Duration;
};Returns the negated duration.
Signature
declare function negate(self: Duration): Duration;ReducerSum
Reducer for summing Durations.
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
sumfor adding two duration values directlyCombinerMaxfor keeping the longest duration instead of summingCombinerMinfor keeping the shortest duration instead of summing
Signature
declare const ReducerSum: Reducer.Reducer<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.
Signature
declare const subtract: {
(that: Duration): (self: Duration) => Duration;
(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
Signature
declare const sum: {
(that: Duration): (self: Duration) => Duration;
(self: Duration, that: Duration): Duration;
};Returns a Duration multiplied by a number.
Details
For nanosecond-backed durations, the multiplier must be convertible to a bigint; fractional or non-finite multipliers can throw. Infinite durations return positive infinity, negative infinity, or zero depending on the multiplier sign.
Signature
declare const times: {
(times: number): (self: Duration) => Duration;
(self: Duration, times: number): Duration;
};Models
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
Inputfor values accepted by APIs that decode duration-like inputsDurationValuefor the tagged representation exposed by thevaluefield
Signature
interface Duration extends Equal, Pipeable, Inspectable {
readonly "~effect/time/Duration": "~effect/time/Duration";
readonly value: DurationValue;
}DurationObject interface
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.
Signature
interface DurationObject {
readonly days?: number;
readonly hours?: number;
readonly microseconds?: number;
readonly milliseconds?: number;
readonly minutes?: number;
readonly nanoseconds?: number;
readonly seconds?: number;
readonly weeks?: number;
}DurationValue type
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
Signature
type DurationValue =
| {
_tag: "Millis";
millis: number;
}
| {
_tag: "Nanos";
nanos: bigint;
}
| {
_tag: "Infinity";
}
| {
_tag: "NegativeInfinity";
};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
fromInputfor safe conversion toOptionfromInputUnsafefor throwing conversionDurationObjectfor object-shaped duration inputUnitfor supported string units
Signature
type Input =
| Duration
| number
| bigint
| readonly [seconds: number, nanos: number]
| `${number} ${Unit}`
| "Infinity"
| "-Infinity"
| DurationObject;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
Inputfor the full duration input union
Signature
type Unit =
| "nano"
| "nanos"
| "micro"
| "micros"
| "milli"
| "millis"
| "second"
| "seconds"
| "minute"
| "minutes"
| "hour"
| "hours"
| "day"
| "days"
| "week"
| "weeks";Ordering
Returns a Duration constrained between a minimum and maximum value.
Signature
declare const clamp: {
(options: { maximum: Duration; minimum: Duration }): (self: Duration) => Duration;
(
self: Duration,
options: {
maximum: Duration;
minimum: Duration;
},
): Duration;
};Returns the larger of two Durations.
Signature
declare const max: {
(that: Duration): (self: Duration) => Duration;
(self: Duration, that: Duration): Duration;
};Returns the smaller of two Durations.
Signature
declare const min: {
(that: Duration): (self: Duration) => Duration;
(self: Duration, that: Duration): Duration;
};Pattern Matching
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.
Signature
declare const match: {
<A, B, C, D = C>(options: {
readonly onInfinity: () => C;
readonly onMillis: (millis: number) => A;
readonly onNanos: (nanos: bigint) => B;
readonly onNegativeInfinity?: () => D;
}): (self: Duration) => A | B | C | D;
<A, B, C, D = C>(
self: Duration,
options: {
readonly onInfinity: () => C;
readonly onMillis: (millis: number) => A;
readonly onNanos: (nanos: bigint) => B;
readonly onNegativeInfinity?: () => D;
},
): A | B | C | D;
};Pattern matches on two Durations, providing handlers that receive both values.
Signature
declare const matchPair: {
<A, B, C>(
that: Duration,
options: {
readonly onInfinity: (self: Duration, that: Duration) => C;
readonly onMillis: (self: number, that: number) => A;
readonly onNanos: (self: bigint, that: bigint) => B;
},
): (self: Duration) => A | B | C;
<A, B, C>(
self: Duration,
that: Duration,
options: {
readonly onInfinity: (self: Duration, that: Duration) => C;
readonly onMillis: (self: number, that: number) => A;
readonly onNanos: (self: bigint, that: bigint) => B;
},
): A | B | C;
};Predicates
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.
See
clampfor constraining a duration to a rangeisGreaterThanOrEqualTofor checking only the lower boundisLessThanOrEqualTofor checking only the upper bound
Signature
declare const between: {
(options: { maximum: Duration; minimum: Duration }): (self: Duration) => boolean;
(
self: Duration,
options: {
maximum: Duration;
minimum: Duration;
},
): boolean;
};Checks whether two Durations are equal.
Signature
declare const equals: {
(that: Duration): (self: Duration) => boolean;
(self: Duration, that: Duration): boolean;
};Checks whether a Duration is finite (not infinite).
Signature
declare function isFinite(self: Duration): boolean;isGreaterThan
Checks whether the first Duration is greater than the second.
Signature
declare const isGreaterThan: {
(that: Duration): (self: Duration) => boolean;
(self: Duration, that: Duration): boolean;
};isGreaterThanOrEqualTo
Checks whether the first Duration is greater than or equal to the second.
Signature
declare const isGreaterThanOrEqualTo: {
(that: Duration): (self: Duration) => boolean;
(self: Duration, that: Duration): boolean;
};isLessThan
Checks whether the first Duration is less than the second.
Signature
declare const isLessThan: {
(that: Duration): (self: Duration) => boolean;
(self: Duration, that: Duration): boolean;
};isLessThanOrEqualTo
Checks whether the first Duration is less than or equal to the second.
Signature
declare const isLessThanOrEqualTo: {
(that: Duration): (self: Duration) => boolean;
(self: Duration, that: Duration): boolean;
};isNegative
Returns true if the duration is negative (strictly less than zero).
Signature
declare function isNegative(self: Duration): boolean;isPositive
Returns true if the duration is positive (strictly greater than zero).
Signature
declare function isPositive(self: Duration): boolean;Checks whether a Duration is zero.
Signature
declare function isZero(self: Duration): boolean;
Creates a Duration from days.