@evolu/common 8.1.0 → 8.3.0

package/src/Time.ts

@@ -10,12 +10,6 @@ import type { yieldNow } from "./Task.ts";
 import {
   brand,
   type DateIso,
-  lessThan,
-  type NonNaNNumber,
-  NonNegativeInt,
-  positive,
-} from "./Type.ts";
-import type {
   Digit,
   Digit1To23,
   Digit1To51,
@@ -23,7 +17,13 @@ import type {
   Digit1To6,
   Digit1To9,
   Digit1To99,
-} from "./Types.ts";
+  lessThan,
+  type NonNaNNumber,
+  NonNegativeInt,
+  positive,
+  templateLiteral,
+  union,
+} from "./Type.ts";
 
 /** Time and timer operations. */
 export interface Time {
@@ -376,104 +376,150 @@ export const performanceDurationBetween = (
 };
 
 /**
- * Duration can be either a {@link DurationLiteral} or milliseconds as
- * {@link Millis}.
+ * {@link DurationLiteral} or {@link Millis}.
+ *
+ * Convenience input accepting a human-readable {@link DurationLiteral} or
+ * validated milliseconds as {@link Millis}. APIs normalize it to `Millis`.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import { Millis, spaced } from "@evolu/common";
+ *
+ * const readableSchedule = spaced("1s");
+ * const validatedSchedule = spaced(Millis.orThrow(1000));
+ *
+ * expectTypeOf(readableSchedule).toEqualTypeOf(validatedSchedule);
+ * ```
  */
 export type Duration = DurationLiteral | Millis;
 
-/** Positive duration accepted by timer-based APIs. */
-export type PositiveDuration = DurationLiteral | PositiveMillis;
-
 /**
- * Duration literal with compile-time validation.
+ * {@link DurationLiteral} or {@link PositiveMillis}.
  *
- * 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)
+ * Convenience input accepting a human-readable {@link DurationLiteral} or
+ * validated milliseconds as {@link PositiveMillis} for timer-based APIs.
  *
- * Each unit uses a bounded range. Where units convert exactly, this avoids
- * equivalent representations (e.g., 1000ms must be written as `"1s"`, not
- * `"1000ms"`).
+ * ### Example
  *
- * 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 {@link Millis} directly.
+ * ```ts
+ * import { PositiveMillis, sleep } from "@evolu/common";
  *
- * Zero duration (0ms) is not supported. For yielding without delay, use `await
- * Promise.resolve()` for microtasks or the {@link yieldNow} for macrotasks.
+ * const readableSleep = sleep("1s");
+ * const validatedSleep = sleep(PositiveMillis.orThrow(1000));
  *
- * See {@link Duration} for a type that also accepts {@link Millis}. Use
- * {@link durationToMillis} to convert to milliseconds.
+ * expectTypeOf(readableSleep).toEqualTypeOf(validatedSleep);
+ * ```
  */
-export type DurationLiteral =
-  | DurationLiteralMilliseconds
-  | DurationLiteralSeconds
-  | DurationLiteralMinutes
-  | DurationLiteralHours
-  | DurationLiteralDays
-  | DurationLiteralWeeks
-  | DurationLiteralYears;
+export type PositiveDuration = DurationLiteral | PositiveMillis;
 
 /** Milliseconds duration: `"1ms"` to `"999ms"`. See {@link DurationLiteral}. */
+export const DurationLiteralMilliseconds = /*#__PURE__*/ union(
+  /*#__PURE__*/ templateLiteral(Digit1To9, "ms"),
+  /*#__PURE__*/ templateLiteral(Digit1To9, Digit, "ms"),
+  /*#__PURE__*/ templateLiteral(Digit1To9, Digit, Digit, "ms"),
+);
 export type DurationLiteralMilliseconds =
-  | `${Digit1To9}ms` // 1-9
-  | `${Digit1To9}${Digit}ms` // 10-99
-  | `${Digit1To9}${Digit}${Digit}ms`; // 100-999
+  typeof DurationLiteralMilliseconds.Output;
 
 /**
  * Seconds duration: `"1s"` to `"59s"` or `"1.1s"` to `"59.9s"`. See
  * {@link DurationLiteral}.
  */
-export type DurationLiteralSeconds =
-  | `${Digit1To59}s` // 1-59
-  | `${Digit1To59}.${Digit1To9}s`; // 1.1-59.9
+export const DurationLiteralSeconds = /*#__PURE__*/ union(
+  /*#__PURE__*/ templateLiteral(Digit1To59, "s"),
+  /*#__PURE__*/ templateLiteral(Digit1To59, ".", Digit1To9, "s"),
+);
+export type DurationLiteralSeconds = typeof DurationLiteralSeconds.Output;
 
 /**
  * Minutes duration: `"1m"` to `"59m"` or `"1.1m"` to `"59.9m"`. See
  * {@link DurationLiteral}.
  */
-export type DurationLiteralMinutes =
-  | `${Digit1To59}m` // 1-59
-  | `${Digit1To59}.${Digit1To9}m`; // 1.1-59.9
+export const DurationLiteralMinutes = /*#__PURE__*/ union(
+  /*#__PURE__*/ templateLiteral(Digit1To59, "m"),
+  /*#__PURE__*/ templateLiteral(Digit1To59, ".", Digit1To9, "m"),
+);
+export type DurationLiteralMinutes = typeof DurationLiteralMinutes.Output;
 
 /**
  * Hours duration: `"1h"` to `"23h"` or `"1.1h"` to `"23.9h"`. See
  * {@link DurationLiteral}.
  */
-export type DurationLiteralHours =
-  | `${Digit1To23}h` // 1-23
-  | `${Digit1To23}.${Digit1To9}h`; // 1.1-23.9
+export const DurationLiteralHours = /*#__PURE__*/ union(
+  /*#__PURE__*/ templateLiteral(Digit1To23, "h"),
+  /*#__PURE__*/ templateLiteral(Digit1To23, ".", Digit1To9, "h"),
+);
+export type DurationLiteralHours = typeof DurationLiteralHours.Output;
 
 /**
  * Days duration: `"1d"` to `"6d"` or `"1.1d"` to `"6.9d"`. See
  * {@link DurationLiteral}.
  */
-export type DurationLiteralDays =
-  | `${Digit1To6}d` // 1-6
-  | `${Digit1To6}.${Digit1To9}d`; // 1.1-6.9
+export const DurationLiteralDays = /*#__PURE__*/ union(
+  /*#__PURE__*/ templateLiteral(Digit1To6, "d"),
+  /*#__PURE__*/ templateLiteral(Digit1To6, ".", Digit1To9, "d"),
+);
+export type DurationLiteralDays = typeof DurationLiteralDays.Output;
 
 /**
  * Weeks duration: `"1w"` to `"51w"` or `"1.1w"` to `"51.9w"`. See
  * {@link DurationLiteral}.
  */
-export type DurationLiteralWeeks =
-  | `${Digit1To51}w` // 1-51
-  | `${Digit1To51}.${Digit1To9}w`; // 1.1-51.9
+export const DurationLiteralWeeks = /*#__PURE__*/ union(
+  /*#__PURE__*/ templateLiteral(Digit1To51, "w"),
+  /*#__PURE__*/ templateLiteral(Digit1To51, ".", Digit1To9, "w"),
+);
+export type DurationLiteralWeeks = typeof DurationLiteralWeeks.Output;
 
 /**
  * Years duration: `"1y"` to `"99y"` or `"1.1y"` to `"99.9y"`. See
  * {@link DurationLiteral}.
  */
-export type DurationLiteralYears =
-  | `${Digit1To99}y` // 1-99
-  | `${Digit1To99}.${Digit1To9}y`; // 1.1-99.9
+export const DurationLiteralYears = /*#__PURE__*/ union(
+  /*#__PURE__*/ templateLiteral(Digit1To99, "y"),
+  /*#__PURE__*/ templateLiteral(Digit1To99, ".", Digit1To9, "y"),
+);
+export type DurationLiteralYears = typeof DurationLiteralYears.Output;
+
+/**
+ * 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 {@link Millis} directly.
+ *
+ * Zero duration (0ms) is not supported. For yielding without delay, use `await
+ * Promise.resolve()` for microtasks or the {@link yieldNow} for macrotasks.
+ *
+ * See {@link Duration} for a type that also accepts {@link Millis}. Use
+ * {@link durationToMillis} to convert to milliseconds.
+ */
+export const DurationLiteral = /*#__PURE__*/ union(
+  DurationLiteralMilliseconds,
+  DurationLiteralSeconds,
+  DurationLiteralMinutes,
+  DurationLiteralHours,
+  DurationLiteralDays,
+  DurationLiteralWeeks,
+  DurationLiteralYears,
+);
+export type DurationLiteral = typeof DurationLiteral.Output;
 
 /**
  * Converts a duration to milliseconds.
@@ -496,6 +542,8 @@ export type DurationLiteralYears =
 export function durationToMillis(
   duration: DurationLiteral | PositiveMillis,
 ): PositiveMillis;
+
+/** Converts a general {@link Duration}, including zero, to milliseconds. */
 export function durationToMillis(duration: Duration): Millis;
 export function durationToMillis(duration: Duration): Millis {
   if (typeof duration === "number") return duration;