@xmtp/browser-sdk 3.1.1 → 4.0.0

package/src/WorkerPreferences.ts

@@ -5,8 +5,8 @@ import {
   type Conversations,
   type UserPreference,
 } from "@xmtp/wasm-bindings";
-import type { StreamCallback } from "@/AsyncStream";
 import { fromSafeConsent, type SafeConsent } from "@/utils/conversions";
+import type { StreamCallback } from "@/utils/streams";
 
 export class WorkerPreferences {
   #client: Client;
@@ -47,26 +47,40 @@ export class WorkerPreferences {
     return this.#client.getConsentState(entityType, entity);
   }
 
-  streamConsent(callback?: StreamCallback<Consent[]>) {
+  streamConsent(callback: StreamCallback<Consent[]>, onFail: () => void) {
     const on_consent_update = (consent: Consent[]) => {
-      void callback?.(null, consent);
+      callback(null, consent);
     };
     const on_error = (error: Error | null) => {
-      void callback?.(error, undefined);
+      callback(error, undefined);
     };
-    return this.#conversations.streamConsent({ on_consent_update, on_error });
+    const on_close = () => {
+      onFail();
+    };
+    return this.#conversations.streamConsent({
+      on_consent_update,
+      on_error,
+      on_close,
+    });
   }
 
-  streamPreferences(callback?: StreamCallback<UserPreference[]>) {
+  streamPreferences(
+    callback: StreamCallback<UserPreference[]>,
+    onFail: () => void,
+  ) {
     const on_user_preference_update = (preferences: UserPreference[]) => {
-      void callback?.(null, preferences);
+      callback(null, preferences);
     };
     const on_error = (error: Error | null) => {
-      void callback?.(error, undefined);
+      callback(error, undefined);
+    };
+    const on_close = () => {
+      onFail();
     };
     return this.#conversations.streamPreferences({
       on_user_preference_update,
       on_error,
+      on_close,
     });
   }
 }

package/src/index.ts

@@ -10,7 +10,7 @@ export { Utils } from "./Utils";
 export { ApiUrls, HistorySyncUrls } from "./constants";
 export type * from "./types/options";
 export * from "./utils/conversions";
-export type { AsyncStream, StreamCallback } from "./AsyncStream";
+export type { AsyncStreamProxy } from "./AsyncStream";
 export type {
   Identifier,
   IdentifierKind,
@@ -53,3 +53,4 @@ export {
 export type { Signer, SafeSigner, EOASigner, SCWSigner } from "./utils/signer";
 export { toSafeSigner } from "./utils/signer";
 export * from "./utils/errors";
+export type * from "./utils/streams";

package/src/types/actions/streams.ts

@@ -25,6 +25,11 @@ export type StreamAction =
       action: "stream.preferences";
       streamId: string;
       result: UserPreference[] | undefined;
+    }
+  | {
+      action: "stream.fail";
+      streamId: string;
+      result: undefined;
     };
 
 export type StreamActionName = StreamAction["action"];

package/src/utils/errors.ts

@@ -59,3 +59,16 @@ export class MissingContentTypeError extends Error {
     super("Content type is required when sending content other than text");
   }
 }
+
+export class StreamFailedError extends Error {
+  constructor(retryAttempts: number) {
+    const times = `time${retryAttempts !== 1 ? "s" : ""}`;
+    super(`Stream failed, retried ${retryAttempts} ${times}`);
+  }
+}
+
+export class StreamInvalidRetryAttemptsError extends Error {
+  constructor() {
+    super("Stream retry attempts must be greater than 0");
+  }
+}

package/src/utils/streams.ts

@@ -0,0 +1,210 @@
+import { AsyncStream, createAsyncStreamProxy } from "@/AsyncStream";
+import { StreamFailedError, StreamInvalidRetryAttemptsError } from "./errors";
+
+const isPromise = <T = unknown>(value: unknown): value is Promise<T> => {
+  return (
+    !!value &&
+    (typeof value === "object" || typeof value === "function") &&
+    "then" in value &&
+    typeof value.then === "function"
+  );
+};
+
+const wait = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
+
+export const DEFAULT_RETRY_DELAY = 10000; // milliseconds
+export const DEFAULT_RETRY_ATTEMPTS = 6;
+
+export type StreamOptions<T = unknown, V = T> = {
+  /**
+   * Called when the stream ends
+   */
+  onEnd?: () => void;
+  /**
+   * Called when a stream error occurs
+   */
+  onError?: (error: Error) => void;
+  /**
+   * Called when the stream fails
+   */
+  onFail?: () => void;
+  /**
+   * Called when the stream is restarted
+   */
+  onRestart?: () => void;
+  /**
+   * Called when the stream is retried
+   */
+  onRetry?: (attempts: number, maxAttempts: number) => void;
+  /**
+   * Called when a value is emitted from the stream
+   */
+  onValue?: (value: V) => void;
+  /**
+   * The number of times to retry the stream
+   * (default: 6)
+   */
+  retryAttempts?: number;
+  /**
+   * The delay between retries (in milliseconds)
+   * (default: 10000)
+   */
+  retryDelay?: number;
+  /**
+   * Whether to retry the stream if it fails
+   * (default: true)
+   */
+  retryOnFail?: boolean;
+};
+
+export type StreamCallback<T = unknown> = (
+  error: Error | null,
+  value: T | undefined,
+) => void;
+
+export type StreamFunction<T = unknown> = (
+  callback: StreamCallback<T>,
+  onFail: () => void,
+) => Promise<() => void>;
+
+export type StreamValueMutator<T = unknown, V = T> = (
+  value: T,
+) => V | Promise<V>;
+
+/**
+ * Creates a stream from a stream function
+ *
+ * If the stream fails, an attempt will be made to restart it.
+ *
+ * This function is not intended to be used directly.
+ *
+ * @param streamFunction - The stream function to create a stream from
+ * @param streamValueMutator - An optional function to mutate the value emitted from the stream
+ * @param options - The options for the stream
+ * @param args - Additional arguments to pass to the stream function
+ * @returns An async iterable stream proxy
+ * @throws {StreamInvalidRetryAttemptsError} if the retryAttempts option is less than 0 and retryOnFail is true
+ * @throws {StreamFailedError} if the stream fails and can't be restarted
+ */
+export const createStream = async <T = unknown, V = T>(
+  streamFunction: StreamFunction<T>,
+  streamValueMutator?: StreamValueMutator<T, V>,
+  options?: StreamOptions<T, V>,
+) => {
+  const {
+    onEnd,
+    onError,
+    onFail,
+    onRestart,
+    onRetry,
+    onValue,
+    retryAttempts = DEFAULT_RETRY_ATTEMPTS,
+    retryDelay = DEFAULT_RETRY_DELAY,
+    retryOnFail = true,
+  } = options ?? {};
+  // retry attempts must be greater than 0
+  if (retryOnFail && retryAttempts < 0) {
+    throw new StreamInvalidRetryAttemptsError();
+  }
+
+  const asyncStream = new AsyncStream<V>();
+  const streamCallback: StreamCallback<T> = (error, value) => {
+    // if a stream error occurs, call the onError callback
+    if (error) {
+      onError?.(error);
+      return;
+    }
+    // ensure the value is not undefined
+    if (value !== undefined) {
+      try {
+        // if a streamValueMutator is provided, mutate the value
+        if (streamValueMutator) {
+          const mutatedValue = streamValueMutator(value);
+          if (isPromise(mutatedValue)) {
+            void mutatedValue
+              .then((mutatedValue) => {
+                asyncStream.push(mutatedValue);
+                onValue?.(mutatedValue);
+              })
+              .catch((error: unknown) => {
+                onError?.(error as Error);
+              });
+          } else {
+            asyncStream.push(mutatedValue);
+            onValue?.(mutatedValue);
+          }
+        } else {
+          asyncStream.push(value as unknown as V);
+          onValue?.(value as unknown as V);
+        }
+      } catch (error) {
+        onError?.(error as Error);
+      }
+    }
+  };
+  const retry = async (retries: number = retryAttempts) => {
+    try {
+      // if the stream has been retried the maximum number of times without
+      // success, throw an error
+      if (retries === 0) {
+        void asyncStream.end();
+        throw new StreamFailedError(retryAttempts);
+      }
+
+      // wait for the retry delay before attempting to restart the stream
+      await wait(retryDelay);
+      // call the onRetry callback
+      onRetry?.(retryAttempts - retries + 1, retryAttempts);
+
+      // attempt to restart the stream
+      const streamCloser = await streamFunction(streamCallback, () => {
+        // call the onFail callback
+        onFail?.();
+        void retry();
+      });
+
+      // when the async stream is done, end the stream
+      asyncStream.onDone = () => {
+        streamCloser();
+        onEnd?.();
+      };
+
+      // stream restarted, call the onRestart callback
+      onRestart?.();
+    } catch (error) {
+      onError?.(error as Error);
+      // retry
+      void retry(retries - 1);
+    }
+  };
+  const startRetry = () => {
+    // if the stream should be retried, start the process
+    if (retryOnFail) {
+      void retry();
+    } else {
+      void asyncStream.end();
+      // stream failed and should not be retried, throw an error
+      throw new StreamFailedError(0);
+    }
+  };
+
+  try {
+    // create the stream
+    const streamCloser = await streamFunction(streamCallback, () => {
+      // call the onFail callback
+      onFail?.();
+      startRetry();
+    });
+    // when the async stream is done, end the stream
+    asyncStream.onDone = () => {
+      streamCloser();
+      onEnd?.();
+    };
+  } catch (error) {
+    onError?.(error as Error);
+    startRetry();
+  }
+
+  // return a proxy for the async stream
+  return createAsyncStreamProxy(asyncStream);
+};

package/src/workers/client.ts

@@ -448,7 +448,17 @@ self.onmessage = async (
             });
           }
         };
-        const streamCloser = client.preferences.streamConsent(streamCallback);
+        const streamCloser = client.preferences.streamConsent(
+          streamCallback,
+          () => {
+            streamClosers.delete(data.streamId);
+            postStreamMessage({
+              action: "stream.fail",
+              streamId: data.streamId,
+              result: undefined,
+            });
+          },
+        );
         streamClosers.set(data.streamId, streamCloser);
         postMessage({
           id,
@@ -476,8 +486,17 @@ self.onmessage = async (
             });
           }
         };
-        const streamCloser =
-          client.preferences.streamPreferences(streamCallback);
+        const streamCloser = client.preferences.streamPreferences(
+          streamCallback,
+          () => {
+            streamClosers.delete(data.streamId);
+            postStreamMessage({
+              action: "stream.fail",
+              streamId: data.streamId,
+              result: undefined,
+            });
+          },
+        );
         streamClosers.set(data.streamId, streamCloser);
         postMessage({
           id,
@@ -490,7 +509,7 @@ self.onmessage = async (
        * Conversations actions
        */
       case "conversations.stream": {
-        const streamCallback = async (
+        const streamCallback = (
           error: Error | null,
           value: Conversation | undefined,
         ) => {
@@ -501,19 +520,41 @@ self.onmessage = async (
               error,
             });
           } else {
-            postStreamMessage({
-              action: "stream.conversation",
-              streamId: data.streamId,
-              result: value
-                ? await toSafeConversation(
-                    new WorkerConversation(client, value),
-                  )
-                : undefined,
-            });
+            if (value) {
+              toSafeConversation(new WorkerConversation(client, value))
+                .then((result) => {
+                  postStreamMessage({
+                    action: "stream.conversation",
+                    streamId: data.streamId,
+                    result,
+                  });
+                })
+                .catch((error: unknown) => {
+                  postStreamMessageError({
+                    action: "stream.conversation",
+                    streamId: data.streamId,
+                    error: error as Error,
+                  });
+                });
+            } else {
+              postStreamMessage({
+                action: "stream.conversation",
+                streamId: data.streamId,
+                result: undefined,
+              });
+            }
           }
         };
         const streamCloser = client.conversations.stream(
           streamCallback,
+          () => {
+            streamClosers.delete(data.streamId);
+            postStreamMessage({
+              action: "stream.fail",
+              streamId: data.streamId,
+              result: undefined,
+            });
+          },
           data.conversationType,
         );
         streamClosers.set(data.streamId, streamCloser);
@@ -541,6 +582,14 @@ self.onmessage = async (
         };
         const streamCloser = client.conversations.streamAllMessages(
           streamCallback,
+          () => {
+            streamClosers.delete(data.streamId);
+            postStreamMessage({
+              action: "stream.fail",
+              streamId: data.streamId,
+              result: undefined,
+            });
+          },
           data.conversationType,
           data.consentStates,
         );
@@ -876,7 +925,14 @@ self.onmessage = async (
             });
           }
         };
-        const streamCloser = group.stream(streamCallback);
+        const streamCloser = group.stream(streamCallback, () => {
+          streamClosers.delete(data.streamId);
+          postStreamMessage({
+            action: "stream.fail",
+            streamId: data.streamId,
+            result: undefined,
+          });
+        });
         streamClosers.set(data.streamId, streamCloser);
         postMessage({ id, action, result: undefined });
         break;