@evolu/common 6.0.1-preview.2 → 6.0.1-preview.20

package/src/RefCountedResourceManager.ts

@@ -0,0 +1,368 @@
+import { err, ok, Result } from "./Result.js";
+import { PositiveInt } from "./Type.js";
+
+/**
+ * A generic resource manager that handles reference counting and delayed
+ * disposal of shared resources. Useful for managing expensive resources like
+ * WebSocket connections, database connections, or file handles that need to be
+ * shared among multiple consumers.
+ */
+export interface RefCountedResourceManager<
+  TResource extends Disposable,
+  TResourceKey extends string,
+  TResourceConfig,
+  TConsumer,
+  TConsumerId extends string,
+> extends Disposable {
+  /**
+   * Adds a consumer to resources, creating them if necessary. Increments
+   * reference counts for existing consumer-resource pairs.
+   */
+  readonly addConsumer: (
+    consumer: TConsumer,
+    resourceConfigs: ReadonlyArray<TResourceConfig>,
+  ) => void;
+
+  /**
+   * Removes a consumer from resources. Decrements reference counts and
+   * schedules disposal when no consumers remain.
+   *
+   * Returns an error if the resource doesn't exist or if the consumer wasn't
+   * added to the resource.
+   */
+  readonly removeConsumer: (
+    consumer: TConsumer,
+    resourceConfigs: ReadonlyArray<TResourceConfig>,
+  ) => Result<
+    void,
+    | ResourceNotFoundError<TResourceKey>
+    | ConsumerNotFoundError<TConsumerId, TResourceKey>
+  >;
+
+  /** Gets the resource for the specified key, or null if it doesn't exist. */
+  readonly getResource: (key: TResourceKey) => TResource | null;
+
+  /** Gets all consumer IDs currently using the specified resource key. */
+  readonly getConsumersForResource: (
+    key: TResourceKey,
+  ) => ReadonlyArray<TConsumerId>;
+
+  /** Checks if a consumer is currently using any resources. */
+  readonly hasConsumerAnyResource: (consumer: TConsumer) => boolean;
+
+  /**
+   * Gets the consumer for the specified consumer ID, or null if not found or
+   * not using any resources.
+   */
+  readonly getConsumer: (consumerId: TConsumerId) => TConsumer | null;
+}
+
+/** Error when trying to remove a consumer from a resource that doesn't exist. */
+export interface ResourceNotFoundError<TResourceKey extends string = string> {
+  readonly type: "ResourceNotFoundError";
+  readonly resourceKey: TResourceKey;
+}
+
+/** Error when trying to remove a consumer that wasn't added to a resource. */
+export interface ConsumerNotFoundError<
+  TConsumerId extends string = string,
+  TResourceKey extends string = string,
+> {
+  readonly type: "ConsumerNotFoundError";
+  readonly consumerId: TConsumerId;
+  readonly resourceKey: TResourceKey;
+}
+
+export interface ResourceManagerConfig<
+  TResource extends Disposable,
+  TResourceKey extends string,
+  TResourceConfig,
+  TConsumer,
+  TConsumerId extends string,
+> {
+  /** Creates a new resource for the given config. */
+  readonly createResource: (config: TResourceConfig) => TResource;
+
+  /** Extracts a unique key from a resource config for deduplication. */
+  readonly getResourceKey: (config: TResourceConfig) => TResourceKey;
+
+  /** Extracts a unique identifier from a consumer for reference counting. */
+  readonly getConsumerId: (consumer: TConsumer) => TConsumerId;
+
+  /**
+   * Delay in milliseconds before disposing unused resources. Helps avoid
+   * resource churn during rapid add/remove cycles. Defaults to 100ms.
+   */
+  readonly disposalDelay?: number;
+
+  /**
+   * Called when a consumer is added to a resource for the first time. This
+   * happens when the consumer's reference count goes from 0 to 1 for this
+   * resource.
+   */
+  readonly onConsumerAdded?: (
+    consumer: TConsumer,
+    resource: TResource,
+    resourceKey: TResourceKey,
+  ) => void;
+
+  /**
+   * Called when a consumer is completely removed from a resource. This happens
+   * when the consumer's reference count goes from 1 to 0 for this resource.
+   */
+  readonly onConsumerRemoved?: (
+    consumer: TConsumer,
+    resource: TResource,
+    resourceKey: TResourceKey,
+  ) => void;
+}
+
+/**
+ * Creates a reference-counted resource manager.
+ *
+ * This manager tracks which consumers are using which resources and maintains
+ * reference counts to know when it's safe to dispose resources. Resources are
+ * created on-demand and disposed with a configurable delay to avoid churn.
+ *
+ * ### Example Usage
+ *
+ * ```ts
+ * // WebSocket connections manager
+ * interface WebSocketConfig {
+ *   readonly url: WebSocketUrl;
+ * }
+ *
+ * type WebSocketUrl = string & Brand<"WebSocketUrl">;
+ * type UserId = string & Brand<"UserId">;
+ *
+ * const wsManager = createRefCountedResourceManager<
+ *   WebSocket,
+ *   WebSocketUrl,
+ *   WebSocketConfig,
+ *   User,
+ *   UserId
+ * >({
+ *   createResource: (config) => new WebSocket(config.url),
+ *   getResourceKey: (config) => config.url,
+ *   getConsumerId: (user) => user.id,
+ *   disposalDelay: 1000,
+ * });
+ *
+ * // Add users to WebSocket connections
+ * wsManager.addConsumer(user1, [
+ *   { url: "ws://server1.com" as WebSocketUrl },
+ *   { url: "ws://server2.com" as WebSocketUrl },
+ * ]);
+ * wsManager.addConsumer(user2, [
+ *   { url: "ws://server1.com" as WebSocketUrl },
+ * ]);
+ *
+ * // Remove users - server1 stays alive (user2 still using it)
+ * wsManager.removeConsumer(user1, [
+ *   { url: "ws://server1.com" as WebSocketUrl },
+ *   { url: "ws://server2.com" as WebSocketUrl },
+ * ]);
+ *
+ * // server2 gets disposed after delay, server1 stays alive
+ * ```
+ */
+export const createRefCountedResourceManager = <
+  TResource extends Disposable,
+  TResourceKey extends string,
+  TResourceConfig,
+  TConsumer,
+  TConsumerId extends string,
+>(
+  config: ResourceManagerConfig<
+    TResource,
+    TResourceKey,
+    TResourceConfig,
+    TConsumer,
+    TConsumerId
+  >,
+): RefCountedResourceManager<
+  TResource,
+  TResourceKey,
+  TResourceConfig,
+  TConsumer,
+  TConsumerId
+> => {
+  let isDisposed = false;
+
+  const resources = new Map<TResourceKey, TResource>();
+  const consumerCounts = new Map<TResourceKey, Map<TConsumerId, PositiveInt>>();
+  const consumers = new Map<TConsumerId, TConsumer>();
+  const disposalTimeouts = new Map<
+    TResourceKey,
+    ReturnType<typeof setTimeout>
+  >();
+
+  const disposalDelay = config.disposalDelay ?? 100;
+
+  const ensureResource = (resourceConfig: TResourceConfig) => {
+    const key = config.getResourceKey(resourceConfig);
+    const timeout = disposalTimeouts.get(key);
+    if (timeout) {
+      clearTimeout(timeout);
+      disposalTimeouts.delete(key);
+    }
+
+    if (!resources.has(key)) {
+      const resource = config.createResource(resourceConfig);
+      resources.set(key, resource);
+    }
+  };
+
+  const scheduleDisposal = (key: TResourceKey): void => {
+    const timeout = setTimeout(() => {
+      const resource = resources.get(key);
+      if (resource) {
+        resource[Symbol.dispose]();
+        resources.delete(key);
+      }
+      disposalTimeouts.delete(key);
+    }, disposalDelay);
+
+    disposalTimeouts.set(key, timeout);
+  };
+
+  const manager: RefCountedResourceManager<
+    TResource,
+    TResourceKey,
+    TResourceConfig,
+    TConsumer,
+    TConsumerId
+  > = {
+    addConsumer: (consumer, resourceConfigs) => {
+      if (isDisposed) return;
+
+      const consumerId = config.getConsumerId(consumer);
+
+      // Store consumer (last added consumer for this ID)
+      consumers.set(consumerId, consumer);
+
+      for (const resourceConfig of resourceConfigs) {
+        ensureResource(resourceConfig);
+        const resourceKey = config.getResourceKey(resourceConfig);
+
+        let counts = consumerCounts.get(resourceKey);
+        if (!counts) {
+          counts = new Map<TConsumerId, PositiveInt>();
+          consumerCounts.set(resourceKey, counts);
+        }
+
+        const currentCount = counts.get(consumerId) ?? 0;
+        const newCount = currentCount + 1;
+        counts.set(consumerId, PositiveInt.orThrow(newCount));
+
+        // Call onConsumerAdded callback only when consumer is added for the first time (0 -> 1)
+        if (currentCount === 0 && config.onConsumerAdded) {
+          const resource = resources.get(resourceKey);
+          if (resource) {
+            config.onConsumerAdded(consumer, resource, resourceKey);
+          }
+        }
+      }
+    },
+
+    removeConsumer: (consumer, resourceConfigs) => {
+      if (isDisposed) return ok();
+
+      const consumerId = config.getConsumerId(consumer);
+
+      for (const resourceConfig of resourceConfigs) {
+        const key = config.getResourceKey(resourceConfig);
+        const counts = consumerCounts.get(key);
+        if (!counts) {
+          return err({ type: "ResourceNotFoundError", resourceKey: key });
+        }
+
+        const currentCount = counts.get(consumerId);
+        if (currentCount == null) {
+          return err({
+            type: "ConsumerNotFoundError",
+            consumerId: consumerId,
+            resourceKey: key,
+          });
+        }
+
+        if (currentCount === 1) {
+          counts.delete(consumerId);
+
+          // Call onConsumerRemoved callback only when consumer is completely removed (1 -> 0)
+          if (config.onConsumerRemoved) {
+            const resource = resources.get(key);
+            if (resource) {
+              config.onConsumerRemoved(consumer, resource, key);
+            }
+          }
+
+          if (counts.size === 0) {
+            consumerCounts.delete(key);
+            scheduleDisposal(key);
+          }
+        } else {
+          counts.set(consumerId, PositiveInt.orThrow(currentCount - 1));
+        }
+      }
+
+      if (!manager.hasConsumerAnyResource(consumer)) {
+        consumers.delete(consumerId);
+      }
+
+      return ok();
+    },
+
+    getResource: (key) => {
+      if (isDisposed) return null;
+      return resources.get(key) ?? null;
+    },
+
+    getConsumersForResource: (key) => {
+      if (isDisposed) return [];
+      const counts = consumerCounts.get(key);
+      return counts ? Array.from(counts.keys()) : [];
+    },
+
+    hasConsumerAnyResource: (consumer) => {
+      if (isDisposed) return false;
+      const consumerId = config.getConsumerId(consumer);
+      // If slow, can be optimized with reverse index
+      return Array.from(consumerCounts.values()).some((counts) =>
+        counts.has(consumerId),
+      );
+    },
+
+    getConsumer: (consumerId) => {
+      if (isDisposed) return null;
+      const consumer = consumers.get(consumerId);
+      if (!consumer) return null;
+
+      // Only return consumer if it's currently using any resources
+      if (!manager.hasConsumerAnyResource(consumer)) {
+        return null;
+      }
+
+      return consumer;
+    },
+
+    [Symbol.dispose]: () => {
+      if (isDisposed) return;
+      isDisposed = true;
+
+      for (const timeout of disposalTimeouts.values()) {
+        clearTimeout(timeout);
+      }
+      disposalTimeouts.clear();
+
+      for (const resource of resources.values()) {
+        resource[Symbol.dispose]();
+      }
+      resources.clear();
+      consumerCounts.clear();
+      consumers.clear();
+    },
+  };
+
+  return manager;
+};

package/src/Result.ts

@@ -1,36 +1,19 @@
 /**
  * 🛡️ Type-safe errors
  *
- * ## Intro
- *
  * The problem with throwing an exception in JavaScript is that the caught error
  * is always of an unknown type. The unknown type is a problem because we can't
  * be sure all errors have been handled because the TypeScript compiler can't
- * help us.
- *
- * Some other languages like Rust 🦀 or Haskell 📚 use a type-safe approach to
- * error handling, where errors are explicitly represented as part of the return
- * type, such as Result or Either, allowing the developer to handle all errors
- * safely. ✅
+ * tell us.
  *
- * ✨ Evolu uses {@link Result}, and it looks like this:
+ * Languages like Rust 🦀 or Haskell 📚 use a type-safe approach to error
+ * handling, where errors are explicitly represented as part of the return type,
+ * such as Result or Either, allowing the developer to handle errors safely.
+ * TypeScript can have this too via the `Result` type.
  *
- * ```ts
- * type Result<T, E> = Ok<T> | Err<E>;
- *
- * interface Ok<T> {
- *   readonly ok: true;
- *   readonly value: T;
- * }
- *
- * interface Err<E> {
- *   readonly ok: false;
- *   readonly error: E;
- * }
- *
- * const ok = <T>(value: T): Ok<T> => ({ ok: true, value });
- * const err = <E>(error: E): Err<E> => ({ ok: false, error });
- * ```
+ * The `Result` type can be either {@link Ok} (success) or {@link Err} (error).
+ * Use {@link ok} to create a successful result and {@link err} to create an error
+ * result.
  *
  * Now let's look at how `Result` can be used for safe JSON parsing:
  *
@@ -77,12 +60,10 @@
  *
  * Let's summarize it:
  *
- * - For synchronous safe code, use `ok` and `err`.
+ * - For safe code, use `ok` and `err`.
  * - For unsafe code, use `trySync` or `tryAsync`.
- * - For asynchronous safe code, use `Promise` with {@link Result}.
  *
- * Asynchronous safe (because of a Promise using Result) code is
- * straightforward:
+ * Asynchronous safe (because of a Promise using Result) code:
  *
  * ```ts
  * const fetchUser = async (
@@ -103,9 +84,33 @@
  * };
  * ```
  *
- * ## Examples
+ * ### Naming Convention
+ *
+ * - For values: `const user = getUser()`
+ * - For void operations: `const result = foo()` (unless it would clash)
+ * - For clashes, suffix the name: `const saveResult = save()`
+ *
+ * ```ts
+ * const processUser = () => {
+ *   // we have a value
+ *   const user = getUser();
+ *   if (!user.ok) return user;
+ *
+ *   // void operation
+ *   const result = saveToDatabase(user.value);
+ *   if (!result.ok) return result;
+ *
+ *   // avoiding clash
+ *   const deleteFromCacheResult = deleteFromCache();
+ *   if (!deleteFromCacheResult.ok) return deleteFromCacheResult;
+ *
+ *   return ok();
+ * };
+ * ```
+ *
+ * ### Examples
  *
- * ### Sequential Operations with Short-Circuiting
+ * #### Sequential Operations with Short-Circuiting
  *
  * When performing a sequence of operations where any failure should stop
  * further processing, use the `Result` type with early returns.
@@ -155,30 +160,114 @@
  * This approach ensures type-safe error handling, avoids nested try/catch
  * blocks, and clearly communicates the control flow.
  *
- * ### A function with two different errors:
+ * #### A function with two different errors:
  *
  * ```ts
  * const example = (value: string): Result<number, FooError | BarError> => {
  *   const foo = getFoo(value);
  *   if (!foo.ok) return foo;
  *
- *   const bar = barize(foo.value);
+ *   const bar = getBar(foo.value);
  *   if (!bar.ok) return bar;
  *
  *   return ok(barToNumber(bar.value));
  * };
  * ```
  *
- * ## FAQ
+ * ### Handling Unexpected Errors
+ *
+ * Even with disciplined use of `trySync` and `tryAsync`, unexpected errors can
+ * still occur due to programming mistakes, third-party library bugs, or edge
+ * cases. These should be logged for debugging, but **unexpected errors are not
+ * recoverable** - they represent bugs that must be fixed.
+ *
+ * **Important**: "Graceful shutdown" and error recovery can only come from
+ * expected errors handled via the `Result` type. Unexpected errors should fail
+ * fast - the operation fails immediately and the error bubbles up.
+ *
+ * #### In Browser Environments
+ *
+ * ```ts
+ * // Global error handler for unexpected errors
+ * window.addEventListener("error", (event) => {
+ *   console.error("Uncaught error:", event.error);
+ *   // Send to error reporting service
+ *   errorReportingService.report(event.error);
+ * });
+ *
+ * // For unhandled promise rejections
+ * window.addEventListener("unhandledrejection", (event) => {
+ *   console.error("Unhandled promise rejection:", event.reason);
+ *   errorReportingService.report(event.reason);
+ * });
+ * ```
+ *
+ * #### In Node.js Environments
+ *
+ * ```ts
+ * // Handle uncaught exceptions - log and fail fast
+ * process.on("uncaughtException", (error) => {
+ *   console.error("Uncaught exception:", error);
+ *   errorReportingService.report(error);
+ *   // Exit immediately - unexpected errors are not recoverable
+ *   process.exit(1);
+ * });
+ *
+ * // Handle unhandled promise rejections
+ * process.on("unhandledRejection", (reason) => {
+ *   console.error("Unhandled promise rejection:", reason);
+ *   errorReportingService.report(reason);
+ * });
+ * ```
+ *
+ * These global handlers serve as a safety net to log and report unexpected
+ * errors for debugging purposes. They do not attempt recovery - unexpected
+ * errors represent bugs that must be fixed. The discipline of explicit error
+ * handling through the `Result` pattern remains the primary approach for all
+ * recoverable scenarios.
+ *
+ * ### FAQ
  *
- * ### What if my function doesn't return a value on success?
+ * #### What if my function doesn't return a value on success?
  *
  * If your function performs an operation but doesn't need to return a value on
  * success, you can use `Result<void, E>`. Using `Result<void, E>` is clearer
  * than using `Result<true, E>` or `Result<null, E>` because it communicates
  * that the function doesn't produce a value but can produce errors.
  *
- * ### How do I short-circuit processing of an array on the first error?
+ * #### When can a function return `void` instead of `Result<void, E>`?
+ *
+ * A function can safely return `void` (instead of `Result<void, E>`) when all
+ * unsafe code within it is properly wrapped with `trySync` or `tryAsync`. If
+ * developers consistently wrap all potentially throwing operations, then any
+ * function returning `void` is guaranteed not to throw and can be called
+ * without error handling.
+ *
+ * ```ts
+ * // ✅ Safe to return void - all unsafe code is wrapped
+ * const processData = (data: string): void => {
+ *   const parseResult = trySync(
+ *     () => JSON.parse(data),
+ *     (error) => ({ type: "ParseError", message: String(error) }),
+ *   );
+ *
+ *   if (!parseResult.ok) {
+ *     logError(parseResult.error); // Handle error appropriately
+ *     return;
+ *   }
+ *
+ *   // Continue with safe operations...
+ * };
+ *
+ * // ✅ Can call without try-catch since it returns void
+ * processData(jsonString);
+ * ```
+ *
+ * This approach creates a clear contract: functions returning `void` are safe
+ * to call, while functions returning `Result<T, E>` require explicit error
+ * handling.
+ *
+ * #### How do I short-circuit processing of an array on the first error?
  *
  * If you want to stop processing as soon as an error occurs (short-circuit),
  * you should produce and check each `Result` inside a loop:
@@ -194,12 +283,11 @@
  * // All queries succeeded
  * ```
  *
- * ### How do I handle an array of operations and short-circuit on the first error?
+ * #### How do I handle an array of operations and short-circuit on the first error?
  *
  * If you have an array of operations (not results), you should make them
- * _lazy_—that is, represent each operation as a function (see `LazyValue` in
- * `Function.ts`). This way, you only execute each operation as needed, and can
- * stop on the first error:
+ * _lazy_—that is, represent each operation as a function. This way, you only
+ * execute each operation as needed, and can stop on the first error:
  *
  * ```ts
  * import type { LazyValue } from "./Function";
@@ -232,17 +320,7 @@
  * above) over monadic helpers. Imperative code is generally more readable,
  * easier to debug, and more familiar to most JavaScript and TypeScript
  * developers. While monads and functional helpers can be powerful, they often
- * obscure control flow and make debugging harder. Evolu's approach keeps error
- * handling explicit and straightforward.
- *
- * @module
- */
-
-/**
- * A `Result` can be either {@link Ok} (success) or {@link Err} (error).
- *
- * Use {@link ok} to create a successful result and {@link err} to create an error
- * result.
+ * obscure control flow and make debugging harder.
  */
 export type Result<T, E> = Ok<T> | Err<E>;
 
@@ -301,6 +379,22 @@ export interface Err<E> {
   readonly error: E;
 }
 
+/**
+ * Extracts the value type from a {@link Result}.
+ *
+ * @category Utilities
+ */
+export type InferOk<R extends Result<any, any>> =
+  R extends Ok<infer T> ? T : never;
+
+/**
+ * Extracts the error type from a {@link Result}.
+ *
+ * @category Utilities
+ */
+export type InferErr<R extends Result<any, any>> =
+  R extends Err<infer E> ? E : never;
+
 /**
  * Creates an {@link Ok} result.
  *
@@ -355,12 +449,14 @@ export const err = <E>(error: E): Err<E> => ({ ok: false, error });
  * const config = getOrThrow(loadConfig());
  * // Safe to use config here
  * ```
+ *
+ * Throws: `Error` with the original error attached as `cause`.
  */
 export const getOrThrow = <T, E>(result: Result<T, E>): T => {
   if (result.ok) {
     return result.value;
   } else {
-    throw new Error(`Result error: ${JSON.stringify(result.error)}`);
+    throw new Error("getOrThrow", { cause: result.error });
   }
 };
 
@@ -384,7 +480,10 @@ export const getOrThrow = <T, E>(result: Result<T, E>): T => {
  * const parseJson = (value: string): Result<unknown, ParseJsonError> =>
  *   trySync(
  *     () => JSON.parse(value) as unknown,
- *     (error) => ({ type: "ParseJsonError", message: String(error) }),
+ *     (error): ParseJsonError => ({
+ *       type: "ParseJsonError",
+ *       message: String(error),
+ *     }),
  *   );
  * ```
  */