@evolu/common 8.9.0 → 8.10.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`.
@@ -220,6 +230,8 @@ export const performanceDurationBetween = (start, end) => {
     assert(end >= start, "Performance end time must not precede start time");
     return (end - start);
 };
+// Keep these annotations concrete. Generic unit wrappers add thousands of
+// compiler instantiations to pnpm bench:type.
 /** Milliseconds duration: `"1ms"` to `"999ms"`. See {@link DurationLiteral}. */
 export const DurationLiteralMilliseconds = /*#__PURE__*/ union(
 /*#__PURE__*/ templateLiteral(Digit1To9, "ms"), 
@@ -267,6 +279,7 @@ export const DurationLiteralWeeks = /*#__PURE__*/ union(
 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 +307,33 @@ 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"));
+ * ```
  */
-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;