@evolu/common 6.0.1-preview.27 → 6.0.1-preview.29

package/src/Time.ts

@@ -4,6 +4,7 @@
  * @module
  */
 
+import { assert } from "./Assert.js";
 import { DateIso, NonNegativeInt } from "./Type.js";
 
 /** Retrieves the current time in milliseconds, similar to `Date.now()`. */
@@ -16,14 +17,24 @@ export interface TimeDep {
   readonly time: Time;
 }
 
-/** Creates a {@link Time} using Date.now(). */
+/**
+ * Creates a {@link Time} using Date.now().
+ *
+ * If the system clock is misconfigured (out of allowed range), the application
+ * will fail with an assertion error. This is intentional - there's no
+ * reasonable fallback when the system clock is fundamentally wrong.
+ */
 export const createTime = (): Time => {
   const time: Time = {
     now: () => {
       const iso = time.nowIso();
       return new globalThis.Date(iso).getTime();
     },
-    nowIso: () => DateIso.orThrow(new globalThis.Date().toISOString()),
+    nowIso: () => {
+      const iso = new globalThis.Date().toISOString();
+      assert(DateIso.is(iso), "System clock returned invalid ISO date");
+      return iso;
+    },
   };
   return time;
 };

package/src/Type.ts

@@ -215,6 +215,9 @@ export interface Type<
   /**
    * Creates `T` from an `Input` value, throwing an error if validation fails.
    *
+   * Throws an Error with the Type validation error in its `cause` property,
+   * making it debuggable while avoiding the need for custom error messages.
+   *
    * This is a convenience method that combines `from` with `getOrThrow`.
    *
    * **When to use:**
@@ -222,7 +225,11 @@ export interface Type<
    * - Configuration values that are guaranteed to be valid (e.g., hardcoded
    *   constants)
    * - Application startup where failure should crash the program
-   * - Test code with known valid inputs
+   * - As an alternative to assertions when the Type error in the thrown Error's
+   *   `cause` provides sufficient debugging information
+   * - Test code with known valid inputs (when error message clarity is not
+   *   critical; for better test error messages, use Vitest `schemaMatching` +
+   *   `assert` with `.is()`)
    *
    * ### Example
    *
@@ -233,6 +240,14 @@ export interface Type<
    * // ✅ Good: App configuration that should crash on invalid values
    * const appName = SimpleName.orThrow("MyApp");
    *
+   * // ✅ Good: Instead of assert when Type error is clear enough
+   * // Context makes it obvious: count increments from non-negative value
+   * const currentCount = counts.get(id) ?? 0;
+   * const newCount = PositiveInt.orThrow(currentCount + 1);
+   *
+   * // ✅ Good: Test setup with known valid values
+   * const testUser = User.orThrow({ name: "Alice", age: 30 });
+   *
    * // ❌ Avoid: User input (use `from` instead)
    * const userAge = PositiveInt.orThrow(userInput); // Could crash!
    *
@@ -1822,19 +1837,35 @@ export const formatNonNegativeError =
     (error) => `The value ${error.value} must be non-negative (≥ 0).`,
   );
 
-/** @category Number */
+/**
+ * Non-negative number (≥ 0).
+ *
+ * @category Number
+ */
 export const NonNegativeNumber = nonNegative(Number);
 export type NonNegativeNumber = typeof NonNegativeNumber.Type;
 
-/** @category Number */
+/**
+ * Positive number (> 0).
+ *
+ * @category Number
+ */
 export const PositiveNumber = positive(NonNegativeNumber);
 export type PositiveNumber = typeof PositiveNumber.Type;
 
-/** @category Number */
+/**
+ * Non-positive number (≤ 0).
+ *
+ * @category Number
+ */
 export const NonPositiveNumber = nonPositive(Number);
 export type NonPositiveNumber = typeof NonPositiveNumber.Type;
 
-/** @category Number */
+/**
+ * Negative number (< 0).
+ *
+ * @category Number
+ */
 export const NegativeNumber = negative(NonPositiveNumber);
 export type NegativeNumber = typeof NegativeNumber.Type;
 
@@ -1870,11 +1901,19 @@ export const formatIntError = createTypeErrorFormatter<IntError>(
 export const Int = int(Number);
 export type Int = typeof Int.Type;
 
-/** @category Number */
+/**
+ * Non-negative integer (≥ 0).
+ *
+ * @category Number
+ */
 export const NonNegativeInt = nonNegative(Int);
 export type NonNegativeInt = typeof NonNegativeInt.Type;
 
-/** @category Number */
+/**
+ * Positive integer (> 0).
+ *
+ * @category Number
+ */
 export const PositiveInt = positive(NonNegativeInt);
 export type PositiveInt = typeof PositiveInt.Type;
 
@@ -1883,11 +1922,19 @@ export const maxPositiveInt = PositiveInt.orThrow(
   globalThis.Number.MAX_SAFE_INTEGER,
 );
 
-/** @category Number */
+/**
+ * Non-positive integer (≤ 0).
+ *
+ * @category Number
+ */
 export const NonPositiveInt = nonPositive(Int);
 export type NonPositiveInt = typeof NonPositiveInt.Type;
 
-/** @category Number */
+/**
+ * Negative integer (< 0).
+ *
+ * @category Number
+ */
 export const NegativeInt = negative(NonPositiveInt);
 export type NegativeInt = typeof NegativeInt.Type;
 

package/src/index.ts

@@ -12,6 +12,7 @@ export * from "./Error.js";
 export * from "./Evolu/Public.js";
 export * from "./Function.js";
 export * from "./Identicon.js";
+export * from "./Instances.js";
 export * from "./ManyToManyMap.js";
 export * from "./Number.js";
 export * from "./Object.js";