Skip to main content Link Search Menu Expand Document (external link)

Duration overview

Added in v2.0.0


Table of contents


constructors

days

Signature

export declare const days: (days: number) => Duration

Added in v2.0.0

hours

Signature

export declare const hours: (hours: number) => Duration

Added in v2.0.0

infinity

Signature

export declare const infinity: Duration

Added in v2.0.0

micros

Signature

export declare const micros: (micros: bigint) => Duration

Added in v2.0.0

millis

Signature

export declare const millis: (millis: number) => Duration

Added in v2.0.0

minutes

Signature

export declare const minutes: (minutes: number) => Duration

Added in v2.0.0

nanos

Signature

export declare const nanos: (nanos: bigint) => Duration

Added in v2.0.0

seconds

Signature

export declare const seconds: (seconds: number) => Duration

Added in v2.0.0

weeks

Signature

export declare const weeks: (weeks: number) => Duration

Added in v2.0.0

zero

Signature

export declare const zero: Duration

Added in v2.0.0

conversions

format

Converts a Duration to a human readable string.

Signature

export declare const format: (self: DurationInput) => string

Example

import { Duration } from "effect"

Duration.format(Duration.millis(1000)) // "1s"
Duration.format(Duration.millis(1001)) // "1s 1ms"

Added in v2.0.0

formatIso

Formats a Duration into an ISO8601 duration string.

Months are assumed to be 30 days and years are assumed to be 365 days.

Returns Option.none() if the duration is infinite.

Signature

export declare const formatIso: (self: DurationInput) => Option.Option<string>

Example

import { Duration, Option } from "effect"

Duration.formatIso(Duration.days(1)) // => Option.some("P1D")
Duration.formatIso(Duration.minutes(90)) // => Option.some("PT1H30M")
Duration.formatIso(Duration.millis(1500)) // => Option.some("PT1.5S")
Duration.formatIso(Duration.infinity) // => Option.none()

Added in v3.13.0

fromIso

Parses an ISO8601 duration string into a Duration.

Months are assumed to be 30 days and years are assumed to be 365 days.

Signature

export declare const fromIso: (iso: string) => Option.Option<Duration>

Example

import { Duration, Option } from "effect"

Duration.fromIso("P1D") // => Option.some(Duration.days(1))
Duration.fromIso("PT1H") // => Option.some(Duration.hours(1))
Duration.fromIso("PT1M") // => Option.some(Duration.minutes(1))
Duration.fromIso("PT1.5S") // => Option.some(Duration.seconds(1.5))

Added in v3.13.0

parts

Converts a Duration to its parts.

Signature

export declare const parts: (self: DurationInput) => {
  days: number
  hours: number
  minutes: number
  seconds: number
  millis: number
  nanos: number
}

Added in v3.8.0

unsafeFormatIso

Formats a Duration into an ISO8601 duration string.

The ISO8601 duration format is generally specified as P[n]Y[n]M[n]DT[n]H[n]M[n]S. However, since the Duration type does not support years or months, this function will only output the days, hours, minutes and seconds. Thus, the effective format is P[n]DT[n]H[n]M[n]S.

Milliseconds and nanoseconds are expressed as fractional seconds.

Signature

export declare const unsafeFormatIso: (self: DurationInput) => string

Example

import { Duration } from "effect"

Duration.unsafeFormatIso(Duration.days(1)) // => "P1D"
Duration.unsafeFormatIso(Duration.minutes(90)) // => "PT1H30M"
Duration.unsafeFormatIso(Duration.millis(1500)) // => "PT1.5S"

Added in v3.13.0

getters

toDays

Signature

export declare const toDays: (self: DurationInput) => number

Added in v3.8.0

toHours

Signature

export declare const toHours: (self: DurationInput) => number

Added in v3.8.0

toHrTime

Signature

export declare const toHrTime: (self: DurationInput) => [seconds: number, nanos: number]

Added in v2.0.0

toMillis

Signature

export declare const toMillis: (self: DurationInput) => number

Added in v2.0.0

toMinutes

Signature

export declare const toMinutes: (self: DurationInput) => number

Added in v3.8.0

toNanos

Get the duration in nanoseconds as a bigint.

If the duration is infinite, returns Option.none()

Signature

export declare const toNanos: (self: DurationInput) => Option.Option<bigint>

Added in v2.0.0

toSeconds

Signature

export declare const toSeconds: (self: DurationInput) => number

Added in v2.0.0

toWeeks

Signature

export declare const toWeeks: (self: DurationInput) => number

Added in v3.8.0

unsafeToNanos

Get the duration in nanoseconds as a bigint.

If the duration is infinite, it throws an error.

Signature

export declare const unsafeToNanos: (self: DurationInput) => bigint

Added in v2.0.0

guards

isDuration

Signature

export declare const isDuration: (u: unknown) => u is Duration

Added in v2.0.0

isFinite

Signature

export declare const isFinite: (self: Duration) => boolean

Added in v2.0.0

isZero

Signature

export declare const isZero: (self: Duration) => boolean

Added in v3.5.0

instances

Equivalence

Signature

export declare const Equivalence: equivalence.Equivalence<Duration>

Added in v2.0.0

Order

Signature

export declare const Order: order.Order<Duration>

Added in v2.0.0

math

divide

Signature

export declare const divide: {
  (by: number): (self: DurationInput) => Option.Option<Duration>
  (self: DurationInput, by: number): Option.Option<Duration>
}

Added in v2.4.19

subtract

Signature

export declare const subtract: {
  (that: DurationInput): (self: DurationInput) => Duration
  (self: DurationInput, that: DurationInput): Duration
}

Added in v2.0.0

sum

Signature

export declare const sum: {
  (that: DurationInput): (self: DurationInput) => Duration
  (self: DurationInput, that: DurationInput): Duration
}

Added in v2.0.0

times

Signature

export declare const times: {
  (times: number): (self: DurationInput) => Duration
  (self: DurationInput, times: number): Duration
}

Added in v2.0.0

unsafeDivide

Signature

export declare const unsafeDivide: {
  (by: number): (self: DurationInput) => Duration
  (self: DurationInput, by: number): Duration
}

Added in v2.4.19

models

Duration (interface)

Signature

export interface Duration extends Equal.Equal, Pipeable, Inspectable {
  readonly [TypeId]: TypeId
  readonly value: DurationValue
}

Added in v2.0.0

DurationInput (type alias)

Signature

export type DurationInput =
  | Duration
  | number // millis
  | bigint // nanos
  | readonly [seconds: number, nanos: number]
  | `${number} ${Unit}`

Added in v2.0.0

DurationValue (type alias)

Signature

export type DurationValue =
  | {
      readonly _tag: "Millis"
      readonly millis: number
    }
  | {
      readonly _tag: "Nanos"
      readonly nanos: bigint
    }
  | {
      readonly _tag: "Infinity"
    }

Added in v2.0.0

Unit (type alias)

Signature

export type Unit =
  | "nano"
  | "nanos"
  | "micro"
  | "micros"
  | "milli"
  | "millis"
  | "second"
  | "seconds"
  | "minute"
  | "minutes"
  | "hour"
  | "hours"
  | "day"
  | "days"
  | "week"
  | "weeks"

Added in v2.0.0

order

clamp

Signature

export declare const clamp: {
  (options: { minimum: DurationInput; maximum: DurationInput }): (self: DurationInput) => Duration
  (self: DurationInput, options: { minimum: DurationInput; maximum: DurationInput }): Duration
}

Added in v2.0.0

max

Signature

export declare const max: {
  (that: DurationInput): (self: DurationInput) => Duration
  (self: DurationInput, that: DurationInput): Duration
}

Added in v2.0.0

pattern matching

match

Signature

export declare const match: {
  <A, B>(options: {
    readonly onMillis: (millis: number) => A
    readonly onNanos: (nanos: bigint) => B
  }): (self: DurationInput) => A | B
  <A, B>(
    self: DurationInput,
    options: { readonly onMillis: (millis: number) => A; readonly onNanos: (nanos: bigint) => B }
  ): A | B
}

Added in v2.0.0

matchWith

Signature

export declare const matchWith: {
  <A, B>(
    that: DurationInput,
    options: {
      readonly onMillis: (self: number, that: number) => A
      readonly onNanos: (self: bigint, that: bigint) => B
    }
  ): (self: DurationInput) => A | B
  <A, B>(
    self: DurationInput,
    that: DurationInput,
    options: {
      readonly onMillis: (self: number, that: number) => A
      readonly onNanos: (self: bigint, that: bigint) => B
    }
  ): A | B
}

Added in v2.0.0

predicates

between

Checks if a Duration is between a minimum and maximum value.

Signature

export declare const between: {
  (options: { minimum: DurationInput; maximum: DurationInput }): (self: DurationInput) => boolean
  (self: DurationInput, options: { minimum: DurationInput; maximum: DurationInput }): boolean
}

Added in v2.0.0

equals

Signature

export declare const equals: {
  (that: DurationInput): (self: DurationInput) => boolean
  (self: DurationInput, that: DurationInput): boolean
}

Added in v2.0.0

greaterThan

Signature

export declare const greaterThan: {
  (that: DurationInput): (self: DurationInput) => boolean
  (self: DurationInput, that: DurationInput): boolean
}

Added in v2.0.0

greaterThanOrEqualTo

Signature

export declare const greaterThanOrEqualTo: {
  (that: DurationInput): (self: DurationInput) => boolean
  (self: DurationInput, that: DurationInput): boolean
}

Added in v2.0.0

lessThan

Signature

export declare const lessThan: {
  (that: DurationInput): (self: DurationInput) => boolean
  (self: DurationInput, that: DurationInput): boolean
}

Added in v2.0.0

lessThanOrEqualTo

Signature

export declare const lessThanOrEqualTo: {
  (that: DurationInput): (self: DurationInput) => boolean
  (self: DurationInput, that: DurationInput): boolean
}

Added in v2.0.0

symbol

TypeId (type alias)

Signature

export type TypeId = typeof TypeId

Added in v2.0.0

utils

decode

Signature

export declare const decode: (input: DurationInput) => Duration

Added in v2.0.0

decodeUnknown

Signature

export declare const decodeUnknown: (u: unknown) => Option.Option<Duration>

Added in v2.5.0

min

Signature

export declare const min: {
  (that: DurationInput): (self: DurationInput) => Duration
  (self: DurationInput, that: DurationInput): Duration
}

Added in v2.0.0