API reference › @evolu/common › Time › DurationLiteral

DurationLiteral:  createTypeWithError(
  "DurationLiteral",
  durationLiteralSyntax,
  (cause, value): DurationLiteralError => ({
    type: "DurationLiteral",
    value,
    cause,
  }),
  (error) =>
    The value ${safelyStringifyUnknownValue(error.value)} is not a duration literal. Use a value such as "500ms" or "1.5s".,
) ;

Defined in: packages/common/src/Time.ts:638

Duration literal Type with compile-time and runtime validation.

Supported formats:

• Milliseconds: 1ms, 500ms, 999ms (1-999)
• Seconds: 1s, 59s, 12.5s (1-59, 1.1-59.9)
• Minutes: 1m, 59m, 12.5m (1-59, 1.1-59.9)
• Hours: 1h, 23h, 12.5h (1-23, 1.1-23.9)
• Days: 1d, 6d, 1.5d (1-6, 1.1-6.9)
• Weeks: 1w, 51w, 1.5w (1-51, 1.1-51.9)
• Months: not supported (variable length)
• Years: 1y, 99y, 1.5y (1-99, 1.1-99.9)

Each unit uses a bounded range. Where units convert exactly, this avoids equivalent representations (e.g., 1000ms must be written as "1s", not "1000ms").

Decimal values cover cases like 1.5s (1500ms) or 1.5h (90 minutes) without allowing redundant forms. For precise values that don't fit (e.g., 1050ms), use Millis directly.

Zero duration (0ms) is not supported. For yielding without delay, use await Promise.resolve() for microtasks or the yieldNow for macrotasks.

See Duration for a type that also accepts Millis. Use durationToMillis to convert to milliseconds.

Invalid values produce a DurationLiteralError.

Example

import {
  assertFalse,
  assertOk,
  assertType,
  DurationLiteral,
} from "@evolu/common";

// The TypeScript type accepts valid spellings and rejects the rest.
const literal: DurationLiteral = "1.5s";
assertType<Extract<DurationLiteral, "1000ms" | "60s" | "0s">, never>();

// The runtime Type validates the same grammar.
assertOk(DurationLiteral.fromUnknown(literal), "1.5s");
assertFalse(DurationLiteral.is("1000ms"));