@evolu/common 8.9.0 → 8.11.0

package/dist/src/Time.js

@@ -1,11 +1,21 @@
 /**
  * Time representations, durations, and scheduling utilities.
  *
+ * Durations follow a pattern that other quantities in Evolu repeat, such as
+ * sizes in Bytes.ts:
+ *
+ * - {@link Millis} is the canonical unit, a validated number of milliseconds.
+ * - {@link DurationLiteral} is the human-readable form, such as `"1.5s"`,
+ *   validated at compile time and runtime.
+ * - {@link Duration} is what APIs accept: `DurationLiteral | Millis`.
+ * - {@link durationToMillis} normalizes a `Duration` to `Millis`.
+ *
  * @module
  */
+import { safelyStringifyUnknownValue } from "./String.js";
 import { assert } from "./Assert.js";
 import { exhaustiveCheck } from "./Function.js";
-import { brand, Digit, Digit1To23, Digit1To51, Digit1To59, Digit1To6, Digit1To9, Digit1To99, lessThan, NonNegativeInt, positive, templateLiteral, union, } from "./Type.js";
+import { brand, createTypeWithError, Digit, Digit1To23, Digit1To51, Digit1To59, Digit1To6, Digit1To9, Digit1To99, lessThan, NonNegativeInt, positive, templateLiteral, union, } from "./Type.js";
 /**
  * Creates a {@link Time} using `Date.now()`, `performance`, and
  * `globalThis.setTimeout`.
@@ -17,6 +27,8 @@ import { brand, Digit, Digit1To23, Digit1To51, Digit1To59, Digit1To6, Digit1To9,
  *
  * Throws if the system clock returns an out-of-range value. This is intentional
  * — there's no reasonable fallback for a misconfigured clock.
+ *
+ * @group Core
  */
 export const createTime = () => {
     const timeoutOwner = Symbol("Time");
@@ -96,6 +108,8 @@ const clearTimeoutId = (owner, id) => {
  * wall-clock or performance `now()` call. `"microtask"` increments after the
  * current turn, while `"sync"` increments immediately after each read. Omit it
  * to keep time fixed until `advance()` is called.
+ *
+ * @group Testing
  */
 export const testCreateTime = (options) => {
     const startAt = options?.startAt ?? minMillis;
@@ -190,18 +204,34 @@ const maxMillisWithInfinity = 281474976710655;
  *
  * If a system clock exceeds this range, operations will throw. This is
  * intentional — there's no reasonable fallback for a misconfigured clock.
+ *
+ * @group Millis
  */
 export const Millis = /*#__PURE__*/ brand("Millis", 
 /*#__PURE__*/ lessThan(maxMillisWithInfinity)(NonNegativeInt));
-/** Positive {@link Millis} value. */
+/**
+ * Positive {@link Millis} value.
+ *
+ * @group Millis
+ */
 export const PositiveMillis = /*#__PURE__*/ positive(Millis);
-/** Minimum {@link Millis} value. */
+/**
+ * Minimum {@link Millis} value.
+ *
+ * @group Millis
+ */
 export const minMillis = 0;
-/** Maximum {@link Millis} value. */
+/**
+ * Maximum {@link Millis} value.
+ *
+ * @group Millis
+ */
 export const maxMillis = (maxMillisWithInfinity - 1);
 /**
  * Converts a number to {@link Millis}, rounding to the nearest millisecond and
  * saturating overflow at {@link maxMillis}.
+ *
+ * @group Millis
  */
 export const saturateMillis = (value) => Millis.orNull(Math.max(0, Math.round(value))) ?? maxMillis;
 /**
@@ -209,18 +239,28 @@ export const saturateMillis = (value) => Millis.orNull(Math.max(0, Math.round(va
  *
  * This is a safe cast because {@link Millis} guarantees a valid timestamp range
  * that always produces a valid ISO string.
+ *
+ * @group Millis
  */
 export const millisToDateIso = (value) => new Date(value).toISOString();
 /**
  * Returns the elapsed fractional milliseconds between two performance times.
  *
  * Throws if `end` precedes `start`.
+ *
+ * @group Performance
  */
 export const performanceDurationBetween = (start, end) => {
     assert(end >= start, "Performance end time must not precede start time");
     return (end - start);
 };
-/** Milliseconds duration: `"1ms"` to `"999ms"`. See {@link DurationLiteral}. */
+// Keep these annotations concrete. Generic unit wrappers add thousands of
+// compiler instantiations to pnpm bench:type.
+/**
+ * Milliseconds duration: `"1ms"` to `"999ms"`. See {@link DurationLiteral}.
+ *
+ * @group Durations
+ */
 export const DurationLiteralMilliseconds = /*#__PURE__*/ union(
 /*#__PURE__*/ templateLiteral(Digit1To9, "ms"), 
 /*#__PURE__*/ templateLiteral(Digit1To9, Digit, "ms"), 
@@ -228,6 +268,8 @@ export const DurationLiteralMilliseconds = /*#__PURE__*/ union(
 /**
  * Seconds duration: `"1s"` to `"59s"` or `"1.1s"` to `"59.9s"`. See
  * {@link DurationLiteral}.
+ *
+ * @group Durations
  */
 export const DurationLiteralSeconds = /*#__PURE__*/ union(
 /*#__PURE__*/ templateLiteral(Digit1To59, "s"), 
@@ -235,6 +277,8 @@ export const DurationLiteralSeconds = /*#__PURE__*/ union(
 /**
  * Minutes duration: `"1m"` to `"59m"` or `"1.1m"` to `"59.9m"`. See
  * {@link DurationLiteral}.
+ *
+ * @group Durations
  */
 export const DurationLiteralMinutes = /*#__PURE__*/ union(
 /*#__PURE__*/ templateLiteral(Digit1To59, "m"), 
@@ -242,6 +286,8 @@ export const DurationLiteralMinutes = /*#__PURE__*/ union(
 /**
  * Hours duration: `"1h"` to `"23h"` or `"1.1h"` to `"23.9h"`. See
  * {@link DurationLiteral}.
+ *
+ * @group Durations
  */
 export const DurationLiteralHours = /*#__PURE__*/ union(
 /*#__PURE__*/ templateLiteral(Digit1To23, "h"), 
@@ -249,6 +295,8 @@ export const DurationLiteralHours = /*#__PURE__*/ union(
 /**
  * Days duration: `"1d"` to `"6d"` or `"1.1d"` to `"6.9d"`. See
  * {@link DurationLiteral}.
+ *
+ * @group Durations
  */
 export const DurationLiteralDays = /*#__PURE__*/ union(
 /*#__PURE__*/ templateLiteral(Digit1To6, "d"), 
@@ -256,6 +304,8 @@ export const DurationLiteralDays = /*#__PURE__*/ union(
 /**
  * Weeks duration: `"1w"` to `"51w"` or `"1.1w"` to `"51.9w"`. See
  * {@link DurationLiteral}.
+ *
+ * @group Durations
  */
 export const DurationLiteralWeeks = /*#__PURE__*/ union(
 /*#__PURE__*/ templateLiteral(Digit1To51, "w"), 
@@ -263,10 +313,13 @@ export const DurationLiteralWeeks = /*#__PURE__*/ union(
 /**
  * Years duration: `"1y"` to `"99y"` or `"1.1y"` to `"99.9y"`. See
  * {@link DurationLiteral}.
+ *
+ * @group Durations
  */
 export const DurationLiteralYears = /*#__PURE__*/ union(
 /*#__PURE__*/ templateLiteral(Digit1To99, "y"), 
 /*#__PURE__*/ templateLiteral(Digit1To99, ".", Digit1To9, "y"));
+const durationLiteralSyntax = /*#__PURE__*/ union(DurationLiteralMilliseconds, DurationLiteralSeconds, DurationLiteralMinutes, DurationLiteralHours, DurationLiteralDays, DurationLiteralWeeks, DurationLiteralYears);
 /**
  * Duration literal Type with compile-time and runtime validation.
  *
@@ -294,8 +347,35 @@ export const DurationLiteralYears = /*#__PURE__*/ union(
  *
  * See {@link Duration} for a type that also accepts {@link Millis}. Use
  * {@link durationToMillis} to convert to milliseconds.
+ *
+ * Invalid values produce a {@link DurationLiteralError}.
+ *
+ * ### Example
+ *
+ * ```ts
+ * 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"));
+ * ```
+ *
+ * @group Durations
  */
-export const DurationLiteral = /*#__PURE__*/ union(DurationLiteralMilliseconds, DurationLiteralSeconds, DurationLiteralMinutes, DurationLiteralHours, DurationLiteralDays, DurationLiteralWeeks, DurationLiteralYears);
+export const DurationLiteral = /*#__PURE__*/ createTypeWithError("DurationLiteral", durationLiteralSyntax, (cause, value) => ({
+    type: "DurationLiteral",
+    value,
+    cause,
+}), (error) => `The value ${safelyStringifyUnknownValue(error.value)} is not a duration literal. Use a value such as "500ms" or "1.5s".`);
 export function durationToMillis(duration) {
     if (typeof duration === "number")
         return duration;
@@ -319,12 +399,16 @@ const durationUnits = {
  * Frame budget at 60fps (16ms).
  *
  * Work exceeding this blocks a frame, causing visible jank in animations.
+ *
+ * @group Millis
  */
 export const ms60fps = 16;
 /**
  * Frame budget at 120fps (8ms).
  *
  * For high refresh rate displays. Work exceeding this blocks a frame.
+ *
+ * @group Millis
  */
 export const ms120fps = 8;
 /**
@@ -333,6 +417,7 @@ export const ms120fps = 8;
  * Tasks exceeding this are "long tasks" per web standards. Use with
  * {@link yieldNow} to yield periodically and keep UI responsive.
  *
+ * @group Millis
  * @see https://web.dev/articles/optimize-long-tasks
  */
 export const msLongTask = 50;
@@ -364,6 +449,8 @@ export const msLongTask = 50;
  *   "1d1h1m1.000s",
  * );
  * ```
+ *
+ * @group Millis
  */
 export const formatMillisAsDuration = (millis) => {
     const seconds = ((millis % durationUnits.m) / durationUnits.s).toFixed(3);
@@ -403,6 +490,8 @@ export const formatMillisAsDuration = (millis) => {
  *   "14:32:15.234",
  * );
  * ```
+ *
+ * @group Millis
  */
 export const formatMillisAsClockTime = (millis) => {
     const date = new Date(millis);