velt/time

API reference

Time: For a walkthrough, read the guide.

import { DateTime, Duration, delay, Ticker } from "velt/time";

Exports

clearImmediateCancels t if its task has not started (same as t.clear()).clearIntervalStops the interval t (same as t.clear(); also cancels a timeout, like JS).clearTimeoutCancels t if its task has not started (same as t.clear()).delayResolves after ms milliseconds (same as the built-in sleep).setImmediateCalls task once the code that is running and the callbacks it queued are done, before the timers created after it (like Node's setImmediate).setIntervalCalls task every ms milliseconds (at least 1) until the returned timer is cleared, like Node: on a fixed schedule, also while an earlier run's promise is still pending.setTimeoutCalls task after at least ms milliseconds (at least 1, like Node: setTimeout(f, 0) is setTimeout(f, 1)) unless the returned timer is cleared first.DateTimeErrorThrown by DateTime.parse / parseHttpDate for malformed or out-of-range input.TickerA drift-free periodic schedule: tick k is due k * periodMs after construction (measured with performance.now()), independent of how long the loop body takes.TickerStopStops a Ticker from any task: const stop = t.stopper(); spawn(later(stop));.TimerHandle of a pending setTimeout / setImmediate task or of a setInterval schedule.DateTimeAn instant in time: milliseconds since 1970-01-01T00:00:00Z.DurationA signed span of time with millisecond precision.DatePartsCalendar fields of a DateTime: year month(1-12) day hour minute second millisecond dayOfWeek(0 = Sunday) dayOfYear(1-366) offsetMinutes.

function

clearImmediate

#std/prelude/timers.vlt:205

Re-exported from velt/prelude/timers

function clearImmediate(t: Timer)

Cancels t if its task has not started (same as t.clear()).

function

clearInterval

#std/prelude/timers.vlt:237

Re-exported from velt/prelude/timers

function clearInterval(t: Timer)

Stops the interval t (same as t.clear(); also cancels a timeout, like JS).

function

clearTimeout

#std/prelude/timers.vlt:219

Re-exported from velt/prelude/timers

function clearTimeout(t: Timer)

Cancels t if its task has not started (same as t.clear()).

functionasync

delay

#std/time/timers.vlt:18

Re-exported from velt/time/timers

async function delay(ms: i64): Promise<void>

Resolves after ms milliseconds (same as the built-in sleep).

function

setImmediate

#std/prelude/timers.vlt:200

Re-exported from velt/prelude/timers

function setImmediate<E>(task: () => Promise<void, E>): Timer

Calls task once the code that is running and the callbacks it queued are done, before the timers created after it (like Node's setImmediate).

function

setInterval

#std/prelude/timers.vlt:228

Re-exported from velt/prelude/timers

function setInterval<E>(task: () => Promise<void, E>, ms: i64): Timer

Calls task every ms milliseconds (at least 1) until the returned timer is cleared, like Node: on a fixed schedule, also while an earlier run's promise is still pending. Runs that overlap interleave at their awaits on the timer's task; they never run in parallel.

function

setTimeout

#std/prelude/timers.vlt:192

Re-exported from velt/prelude/timers

function setTimeout<E>(task: () => Promise<void, E>, ms: i64): Timer

Calls task after at least ms milliseconds (at least 1, like Node: setTimeout(f, 0) is setTimeout(f, 1)) unless the returned timer is cleared first. An error it throws is uncaught, as in Node.

class

DateTimeError

#std/time/errors.vlt:4

Re-exported from velt/time/errors

class DateTimeError extends Error

Thrown by DateTime.parse / parseHttpDate for malformed or out-of-range input.

class

Ticker

#std/time/ticker.vlt:16

Re-exported from velt/time/ticker

class Ticker implements AsyncIterable<i64>

A drift-free periodic schedule: tick k is due k * periodMs after construction (measured with performance.now()), independent of how long the loop body takes. Missed ticks are skipped, not burst: a tick() that is already late resolves at once, and the next one is the first schedule point after that. A stop wakes a pending tick at once: its sleep races the stop signal (velt/task), and the losing sleep is cancelled.

constructor(periodMs: i64)

A ticker whose first tick is due periodMs (>= 1) from now.

tick(): Promise<bool>

Resolves when the next tick is due: true, or false once the ticker is stopped.

async * [Symbol.asyncIterator](): AsyncIterator<i64>

for await (const n of ticker): each tick as tick() waits for it, numbered from 1, until the ticker is stopped. Leaving the loop early does not stop the ticker.

stop()

Stops the ticker (see TickerStop.stop).

stopper(): TickerStop

A handle that stops this ticker from another task.

class

TickerStop

#std/time/ticker_stop.vlt:6

Re-exported from velt/time/ticker_stop

Stops a Ticker from any task: const stop = t.stopper(); spawn(later(stop));.

Returned byTicker.stopper

constructor(control: AbortController)

Wraps a ticker's stop controller (use Ticker.stopper()).

stop()

Makes the ticker's pending and future tick()s resolve to false, the pending one at once.

class

Timer

#std/prelude/timers.vlt:104

Re-exported from velt/prelude/timers

Handle of a pending setTimeout / setImmediate task or of a setInterval schedule.

Parameter ofclearImmediateclearTimeoutclearIntervalReturned bysetTimeoutsetImmediatesetInterval

constructor(state: shared<Mutex<TimerState>>, repeats: bool)

Wraps the task's state (use setTimeout or setInterval to create timers).

clear()

Cancels the task if it has not started yet, and an interval's future runs at any time (a no-op on a timeout that started, like JS clearTimeout). A cleared timer no longer keeps the process alive. Dropping the handle does not cancel.

unref(): Timer

Lets the process exit while this timer is pending, like Node's timeout.unref(). Returns the timer.

ref(): Timer

Keeps the process alive while this timer is pending again (the default), like Node's timeout.ref(). Returns the timer.

hasRef(): bool

Whether the timer is ref'd (ref(), the default) rather than unref()'d, like Node's timeout.hasRef().

get cleared(): bool

Whether clear() cancelled the task before it started (an interval: whether it was cleared).

get started(): bool

Whether the task has started (an interval: whether it ran at least once).

struct

DateTime

#std/time/datetime.vlt:34

Re-exported from velt/time/datetime

struct DateTime implements Comparable<DateTime>

An instant in time: milliseconds since 1970-01-01T00:00:00Z.

static now(): DateTime

The current time (Date.now()).

static fromEpochMs(ms: i64): DateTime

The instant ms milliseconds after the Unix epoch (negative: before).

static utc(year: i64, month: i64, day: i64 = 1, hour: i64 = 0, minute: i64 = 0, second: i64 = 0, ms: i64 = 0): DateTime

A UTC date-time; month is 1-12. Out-of-range fields roll over like JS Date.UTC (month 13 is January of the next year, day 0 the last day of the previous month).

static parse(s: string): DateTime

ISO 8601 / RFC 3339: 2024-02-29, 2024-02, 2024, 2024-02-29T12:34, 2024-02-29T12:34:56.789Z, 2024-02-29 12:34:56+02:00 (t/space separators, z, ±HH:mm / ±HHmm / ±HH offsets, 1-9 fraction digits, ±YYYYYY years). No offset means UTC. Throws DateTimeError.

static parseHttpDate(s: string): DateTime

An HTTP date (RFC 7231: IMF-fixdate, RFC 850 or asctime). Throws DateTimeError.

toEpochMs(): i64

Milliseconds since the Unix epoch.

toEpochSeconds(): i64

Whole seconds since the Unix epoch (rounded down).

parts(): DateParts

UTC calendar fields.

localParts(): DateParts

Local calendar fields (the OS time zone at this instant, DST-aware).

get localOffsetMinutes(): i64

Minutes added to UTC to get local time at this instant (e.g. 60 for UTC+01:00).

get year(): i64

UTC year.

get month(): i64

UTC month, 1-12.

get day(): i64

UTC day of the month, 1-31.

get hour(): i64

UTC hour, 0-23.

get minute(): i64

UTC minute, 0-59.

get second(): i64

Second, 0-59.

get millisecond(): i64

Millisecond, 0-999.

get dayOfWeek(): i64

UTC day of the week: 0 = Sunday … 6 = Saturday.

get dayOfYear(): i64

UTC day of the year, 1-366.

toISOString(): string

JS toISOString: 2024-02-29T12:34:56.000Z (years outside 0-9999 as ±YYYYYY).

toLocalISOString(): string

Local time with its offset: 2024-02-29T13:34:56.000+01:00.

toUTCString(): string

RFC 7231 HTTP date (JS toUTCString): Thu, 29 Feb 2024 12:34:56 GMT.

toString(): string

Same as toISOString.

format(pattern: string): string

Formats in UTC. Tokens: YYYY YY year; M MM month; MMM Jan; MMMM January; D DD day; DDDD day of year (3 digits); ddd Mon; dddd Monday; H HH hour; h hh 12-hour; A AM/PM; a am/pm; m mm minute; s ss second; SSS millisecond; Z +01:00; ZZ +0100. Text in [brackets] and any other run of letters is copied as is.

formatLocal(pattern: string): string

format in local time.

addMs(n: i64): DateTimeNo doc comment yet

addSeconds(n: i64): DateTimeNo doc comment yet

addMinutes(n: i64): DateTimeNo doc comment yet

addHours(n: i64): DateTimeNo doc comment yet

addDays(n: i64): DateTime

Adds n days of 24 hours (UTC has no DST).

addMonths(n: i64): DateTime

Adds calendar months, clamping the day to the target month (Jan 31 + 1 month = Feb 28/29).

addYears(n: i64): DateTime

Adds calendar years (Feb 29 + 1 year = Feb 28).

add(d: Duration): DateTime

Adds a (possibly negative) duration.

diffMs(other: DateTime): i64

this - other in milliseconds.

since(other: DateTime): Duration

this - other as a Duration.

startOfDay(): DateTime

Midnight UTC of the same day.

compareTo(other: DateTime): i64

-1, 0 or 1 (Comparable: generic code can use < on DateTimes).

isBefore(other: DateTime): boolNo doc comment yet

isAfter(other: DateTime): boolNo doc comment yet

equals(other: DateTime): boolNo doc comment yet

struct

Duration

#std/time/duration.vlt:6

Re-exported from velt/time/duration

struct Duration implements Comparable<Duration>

A signed span of time with millisecond precision.

Parameter ofDateTime.addReturned byDateTime.since

static ofMs(n: i64): DurationNo doc comment yet

static ofSeconds(n: i64): DurationNo doc comment yet

static ofMinutes(n: i64): DurationNo doc comment yet

static ofHours(n: i64): DurationNo doc comment yet

static ofDays(n: i64): Duration

n days of 24 hours.

toMs(): i64No doc comment yet

toSeconds(): f64

Fractional seconds.

plus(other: Duration): DurationNo doc comment yet

minus(other: Duration): DurationNo doc comment yet

negated(): DurationNo doc comment yet

compareTo(other: Duration): i64No doc comment yet

toString(): string

ISO 8601 duration with days as the largest unit: P1DT2H3M4.005S, PT0S, -PT1.5S.

type

DateParts

#std/time/datetime.vlt:31

Re-exported from velt/time/datetime

type DateParts = Parts

Calendar fields of a DateTime: year month(1-12) day hour minute second millisecond dayOfWeek(0 = Sunday) dayOfYear(1-366) offsetMinutes.

Returned byDateTime.parts