@evolu/common 8.8.0 → 8.10.0

package/dist/src/Time.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Time.d.ts","sourceRoot":"","sources":["../../src/Time.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"Time.d.ts","sourceRoot":"","sources":["../../src/Time.ts"],"names":[],"mappings":"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"}

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;