@evolu/common 6.0.1-preview.28 → 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,8 +12,8 @@ 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 "./Multiton.js";
 export * from "./Number.js";
 export * from "./Object.js";
 export * from "./Order.js";

package/dist/src/Multiton.d.ts

@@ -1,50 +0,0 @@
-/**
- * Manages multiple named instances using the Multiton pattern.
- *
- * Unlike Singleton (one instance globally), Multiton maintains one instance per
- * unique key.
- *
- * **Note:** Multiton is generally considered an anti-pattern because it
- * introduces hidden global state and makes testing harder. Use it only when
- * there's a compelling reason, such as:
- *
- * - Supporting hot reloading while preserving state across module reloads
- * - Enforcing physical constraints (e.g., preventing multiple SQLite connections
- *   to the same database, which causes corruption)
- * - Managing resources where instance identity is intrinsic to correctness
- *
- * For most cases, prefer explicit dependency injection and instance management.
- *
- * Compatibility and future work:
- *
- * - We will adopt the ECMAScript `DisposableStack` for structured cleanup and
- *   robust error handling as runtimes converge (Node.js ≥ 24, Safari stable).
- *   Safari Technology Preview already includes support, so broad availability
- *   is expected soon.
- * - Until then, this module uses a simple Map-based approach and calls
- *   `instance[Symbol.dispose]()` directly during disposal.
- * - We don't use a polyfill because we avoid global mutation, keep bundles lean,
- *   and prefer explicit feature detection.
- * - MDN reference:
- *   https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DisposableStack
- */
-export interface Multiton<K extends string, T extends Disposable> extends Disposable {
-    /**
-     * Ensures an instance exists for the given key, creating it if necessary. If
-     * the instance already exists, the optional `onCacheHit` callback is invoked
-     * to update the existing instance.
-     */
-    readonly ensure: (key: K, create: () => T, onCacheHit?: (instance: T) => void) => T;
-    /** Gets an instance by key, or returns `null` if it doesn't exist. */
-    readonly get: (key: K) => T | null;
-    /** Checks if an instance exists for the given key. */
-    readonly has: (key: K) => boolean;
-    /**
-     * Removes and disposes an instance by key. Returns `true` if the instance
-     * existed and was disposed, `false` otherwise.
-     */
-    readonly disposeInstance: (key: K) => boolean;
-}
-/** Creates a {@link Multiton} instance manager. */
-export declare const createMultiton: <K extends string, T extends Disposable>() => Multiton<K, T>;
-//# sourceMappingURL=Multiton.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"Multiton.d.ts","sourceRoot":"","sources":["../../src/Multiton.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,WAAW,QAAQ,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,UAAU,CAC9D,SAAQ,UAAU;IAClB;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,CACf,GAAG,EAAE,CAAC,EACN,MAAM,EAAE,MAAM,CAAC,EACf,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,CAAC,KAAK,IAAI,KAC/B,CAAC,CAAC;IAEP,sEAAsE;IACtE,QAAQ,CAAC,GAAG,EAAE,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC;IAEnC,sDAAsD;IACtD,QAAQ,CAAC,GAAG,EAAE,CAAC,GAAG,EAAE,CAAC,KAAK,OAAO,CAAC;IAElC;;;OAGG;IACH,QAAQ,CAAC,eAAe,EAAE,CAAC,GAAG,EAAE,CAAC,KAAK,OAAO,CAAC;CAC/C;AAED,mDAAmD;AACnD,eAAO,MAAM,cAAc,GACzB,CAAC,SAAS,MAAM,EAChB,CAAC,SAAS,UAAU,OACjB,QAAQ,CAAC,CAAC,EAAE,CAAC,CAqCjB,CAAC"}

package/src/Multiton.ts

@@ -1,98 +0,0 @@
-/**
- * Manages multiple named instances using the Multiton pattern.
- *
- * Unlike Singleton (one instance globally), Multiton maintains one instance per
- * unique key.
- *
- * **Note:** Multiton is generally considered an anti-pattern because it
- * introduces hidden global state and makes testing harder. Use it only when
- * there's a compelling reason, such as:
- *
- * - Supporting hot reloading while preserving state across module reloads
- * - Enforcing physical constraints (e.g., preventing multiple SQLite connections
- *   to the same database, which causes corruption)
- * - Managing resources where instance identity is intrinsic to correctness
- *
- * For most cases, prefer explicit dependency injection and instance management.
- *
- * Compatibility and future work:
- *
- * - We will adopt the ECMAScript `DisposableStack` for structured cleanup and
- *   robust error handling as runtimes converge (Node.js ≥ 24, Safari stable).
- *   Safari Technology Preview already includes support, so broad availability
- *   is expected soon.
- * - Until then, this module uses a simple Map-based approach and calls
- *   `instance[Symbol.dispose]()` directly during disposal.
- * - We don't use a polyfill because we avoid global mutation, keep bundles lean,
- *   and prefer explicit feature detection.
- * - MDN reference:
- *   https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DisposableStack
- */
-export interface Multiton<K extends string, T extends Disposable>
-  extends Disposable {
-  /**
-   * Ensures an instance exists for the given key, creating it if necessary. If
-   * the instance already exists, the optional `onCacheHit` callback is invoked
-   * to update the existing instance.
-   */
-  readonly ensure: (
-    key: K,
-    create: () => T,
-    onCacheHit?: (instance: T) => void,
-  ) => T;
-
-  /** Gets an instance by key, or returns `null` if it doesn't exist. */
-  readonly get: (key: K) => T | null;
-
-  /** Checks if an instance exists for the given key. */
-  readonly has: (key: K) => boolean;
-
-  /**
-   * Removes and disposes an instance by key. Returns `true` if the instance
-   * existed and was disposed, `false` otherwise.
-   */
-  readonly disposeInstance: (key: K) => boolean;
-}
-
-/** Creates a {@link Multiton} instance manager. */
-export const createMultiton = <
-  K extends string,
-  T extends Disposable,
->(): Multiton<K, T> => {
-  const instances = new Map<K, T>();
-
-  return {
-    ensure: (key, create, onCacheHit) => {
-      let instance = instances.get(key);
-
-      if (instance == null) {
-        instance = create();
-        instances.set(key, instance);
-      } else if (onCacheHit) {
-        onCacheHit(instance);
-      }
-
-      return instance;
-    },
-
-    get: (key) => instances.get(key) ?? null,
-
-    has: (key) => instances.has(key),
-
-    disposeInstance: (key) => {
-      const instance = instances.get(key);
-      if (instance) {
-        instance[Symbol.dispose]();
-        return instances.delete(key);
-      }
-      return false;
-    },
-
-    [Symbol.dispose]: () => {
-      for (const instance of instances.values()) {
-        instance[Symbol.dispose]();
-      }
-      instances.clear();
-    },
-  };
-};