@evolu/common 8.10.0 → 8.12.0

package/dist/src/Time.js

@@ -27,6 +27,8 @@ import { brand, createTypeWithError, Digit, Digit1To23, Digit1To51, Digit1To59,
  *
  * 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");
@@ -106,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;
@@ -200,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;
 /**
@@ -219,12 +239,16 @@ 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");
@@ -232,7 +256,11 @@ export const performanceDurationBetween = (start, end) => {
 };
 // Keep these annotations concrete. Generic unit wrappers add thousands of
 // compiler instantiations to pnpm bench:type.
-/** Milliseconds duration: `"1ms"` to `"999ms"`. See {@link DurationLiteral}. */
+/**
+ * Milliseconds duration: `"1ms"` to `"999ms"`. See {@link DurationLiteral}.
+ *
+ * @group Durations
+ */
 export const DurationLiteralMilliseconds = /*#__PURE__*/ union(
 /*#__PURE__*/ templateLiteral(Digit1To9, "ms"), 
 /*#__PURE__*/ templateLiteral(Digit1To9, Digit, "ms"), 
@@ -240,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"), 
@@ -247,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"), 
@@ -254,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"), 
@@ -261,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"), 
@@ -268,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"), 
@@ -275,6 +313,8 @@ 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"), 
@@ -328,6 +368,8 @@ const durationLiteralSyntax = /*#__PURE__*/ union(DurationLiteralMilliseconds, D
  * assertOk(DurationLiteral.fromUnknown(literal), "1.5s");
  * assertFalse(DurationLiteral.is("1000ms"));
  * ```
+ *
+ * @group Durations
  */
 export const DurationLiteral = /*#__PURE__*/ createTypeWithError("DurationLiteral", durationLiteralSyntax, (cause, value) => ({
     type: "DurationLiteral",
@@ -357,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;
 /**
@@ -371,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;
@@ -402,6 +449,8 @@ export const msLongTask = 50;
  *   "1d1h1m1.000s",
  * );
  * ```
+ *
+ * @group Millis
  */
 export const formatMillisAsDuration = (millis) => {
     const seconds = ((millis % durationUnits.m) / durationUnits.s).toFixed(3);
@@ -441,6 +490,8 @@ export const formatMillisAsDuration = (millis) => {
  *   "14:32:15.234",
  * );
  * ```
+ *
+ * @group Millis
  */
 export const formatMillisAsClockTime = (millis) => {
     const date = new Date(millis);