@methodacting/actor-kit 0.47.0

package/src/createActorFetch.ts

@@ -0,0 +1,111 @@
+import { StateValueFrom } from "xstate";
+import { z } from "zod";
+import { AnyActorKitStateMachine, CallerSnapshotFrom, ClientEventFrom } from "./types";
+
+const ResponseSchema = z.object({
+  snapshot: z.record(z.any()),
+  checksum: z.string(),
+});
+
+export function createActorFetch<TMachine extends AnyActorKitStateMachine>({
+  actorType,
+  host,
+}: {
+  actorType: string;
+  host: string;
+}) {
+  return async function fetchActor(
+    props: {
+      actorId: string;
+      accessToken: string;
+      input?: Record<string, unknown>;
+      waitForEvent?: ClientEventFrom<TMachine>;
+      waitForState?: StateValueFrom<TMachine>;
+      timeout?: number;
+      errorOnWaitTimeout?: boolean;
+    },
+    options?: RequestInit
+  ): Promise<{
+    snapshot: CallerSnapshotFrom<TMachine>;
+    checksum: string;
+  }> {
+    const input = props.input ?? {};
+
+    if (!host) throw new Error("Actor Kit host is not defined");
+
+    const route = getActorRoute(actorType, props.actorId);
+    const protocol = getHttpProtocol(host);
+    const url = new URL(`${protocol}://${host}${route}`);
+
+    // Add input to URL parameters
+    url.searchParams.append("input", JSON.stringify(input));
+
+    // Add waitForEvent or waitForState to URL parameters
+    if (props.waitForEvent) {
+      url.searchParams.append(
+        "waitForEvent",
+        JSON.stringify(props.waitForEvent)
+      );
+    }
+    if (props.waitForState) {
+      url.searchParams.append(
+        "waitForState",
+        JSON.stringify(props.waitForState)
+      );
+    }
+
+    // Add timeout to URL parameters if specified
+    if (props.timeout) {
+      url.searchParams.append("timeout", props.timeout.toString());
+    }
+
+    // Add errorOnWaitTimeout to URL parameters if specified
+    if (props.errorOnWaitTimeout !== undefined) {
+      url.searchParams.append(
+        "errorOnWaitTimeout",
+        props.errorOnWaitTimeout.toString()
+      );
+    }
+
+    const response = await fetch(url.toString(), {
+      ...options,
+      headers: {
+        ...options?.headers,
+        Authorization: `Bearer ${props.accessToken}`,
+      },
+    });
+
+    if (!response.ok) {
+      if (response.status === 408 && props.errorOnWaitTimeout !== false) {
+        throw new Error(
+          `Timeout waiting for actor response: ${response.statusText}`
+        );
+      }
+      throw new Error(`Failed to fetch actor: ${response.statusText}`);
+    }
+
+    const data = await response.json();
+    const { checksum, snapshot } = ResponseSchema.parse(data);
+
+    return {
+      snapshot: snapshot as CallerSnapshotFrom<TMachine>,
+      checksum,
+    };
+  };
+}
+
+function getActorRoute(actorType: string, actorId: string) {
+  return `/api/${actorType}/${actorId}`;
+}
+
+function getHttpProtocol(host: string): "http" | "https" {
+  return isLocal(host) ? "http" : "https";
+}
+
+function isLocal(host: string): boolean {
+  return (
+    host.startsWith("localhost") ||
+    host.startsWith("127.0.0.1") ||
+    host.startsWith("0.0.0.0")
+  );
+}

package/src/createActorKitClient.ts

@@ -0,0 +1,224 @@
+import { applyPatch } from "fast-json-patch";
+import { produce } from "immer";
+
+import {
+  ActorKitClient,
+  ActorKitEmittedEvent,
+  AnyActorKitStateMachine,
+  CallerSnapshotFrom,
+  ClientEventFrom,
+} from "./types";
+
+export type ActorKitClientProps<TMachine extends AnyActorKitStateMachine> = {
+  host: string;
+  actorType: string;
+  actorId: string;
+  checksum: string;
+  accessToken: string;
+  initialSnapshot: CallerSnapshotFrom<TMachine>;
+  onStateChange?: (newState: CallerSnapshotFrom<TMachine>) => void;
+  onError?: (error: Error) => void;
+};
+
+type Listener<T> = (state: T) => void;
+
+/**
+ * Creates an Actor Kit client for managing state and communication with the server.
+ *
+ * @template TMachine - The type of the state machine.
+ * @param {ActorKitClientProps<TMachine>} props - Configuration options for the client.
+ * @returns {ActorKitClient<TMachine>} An object with methods to interact with the actor.
+ */
+export function createActorKitClient<TMachine extends AnyActorKitStateMachine>(
+  props: ActorKitClientProps<TMachine>
+): ActorKitClient<TMachine> {
+  let currentSnapshot = props.initialSnapshot;
+  let socket: WebSocket | null = null;
+  const listeners: Set<Listener<CallerSnapshotFrom<TMachine>>> = new Set();
+  let reconnectAttempts = 0;
+  const maxReconnectAttempts = 5;
+
+  /**
+   * Notifies all registered listeners with the current state.
+   */
+  const notifyListeners = () => {
+    listeners.forEach((listener) => listener(currentSnapshot));
+  };
+
+  /**
+   * Establishes a WebSocket connection to the Actor Kit server.
+   * @returns {Promise<void>} A promise that resolves when the connection is established.
+   */
+  const connect = async () => {
+    const url = getWebSocketUrl(props);
+
+    socket = new WebSocket(url);
+
+    socket.addEventListener("open", () => {
+      reconnectAttempts = 0;
+    });
+
+    socket.addEventListener("message", (event: MessageEvent) => {
+      try {
+        const data = JSON.parse(
+          typeof event.data === "string"
+            ? event.data
+            : new TextDecoder().decode(event.data)
+        ) as ActorKitEmittedEvent;
+
+        currentSnapshot = produce(currentSnapshot, (draft) => {
+          applyPatch(draft, data.operations);
+        });
+
+        props.onStateChange?.(currentSnapshot);
+        notifyListeners();
+      } catch (error) {
+        console.error(`[ActorKitClient] Error processing message:`, error);
+        props.onError?.(error as Error);
+      }
+    });
+
+    socket.addEventListener("error", (error: any) => {
+      console.error(`[ActorKitClient] WebSocket error:`, error);
+      console.error(`[ActorKitClient] Error details:`, {
+        message: error.message,
+        type: error.type,
+        target: error.target,
+        eventPhase: error.eventPhase,
+      });
+      props.onError?.(new Error(`WebSocket error: ${JSON.stringify(error)}`));
+    });
+
+    // todo, how do we reconnect when a user returns to the tab
+    // later after it's disconnected
+
+    socket.addEventListener("close", (event) => {
+      // Implement reconnection logic
+      if (reconnectAttempts < maxReconnectAttempts) {
+        reconnectAttempts++;
+        const delay = Math.min(1000 * Math.pow(2, reconnectAttempts), 30000);
+        setTimeout(connect, delay);
+      } else {
+        console.error(`[ActorKitClient] Max reconnection attempts reached`);
+      }
+    });
+
+    return new Promise<void>((resolve) => {
+      socket!.addEventListener("open", () => resolve());
+    });
+  };
+
+  /**
+   * Closes the WebSocket connection to the Actor Kit server.
+   */
+  const disconnect = () => {
+    if (socket) {
+      socket.close();
+      socket = null;
+    }
+  };
+
+  /**
+   * Sends an event to the Actor Kit server.
+   * @param {ClientEventFrom<TMachine>} event - The event to send.
+   */
+  const send = (event: ClientEventFrom<TMachine>) => {
+    if (socket && socket.readyState === WebSocket.OPEN) {
+      socket.send(JSON.stringify(event));
+    } else {
+      props.onError?.(
+        new Error("Cannot send event: WebSocket is not connected")
+      );
+    }
+  };
+
+  /**
+   * Retrieves the current state of the actor.
+   * @returns {CallerSnapshotFrom<TMachine>} The current state.
+   */
+  const getState = () => currentSnapshot;
+
+  /**
+   * Subscribes a listener to state changes.
+   * @param {Listener<CallerSnapshotFrom<TMachine>>} listener - The listener function to be called on state changes.
+   * @returns {() => void} A function to unsubscribe the listener.
+   */
+  const subscribe = (listener: Listener<CallerSnapshotFrom<TMachine>>) => {
+    listeners.add(listener);
+    return () => {
+      listeners.delete(listener);
+    };
+  };
+
+  /**
+   * Waits for a state condition to be met.
+   * @param {(state: CallerSnapshotFrom<TMachine>) => boolean} predicateFn - Function that returns true when condition is met
+   * @param {number} [timeoutMs=5000] - Maximum time to wait in milliseconds
+   * @returns {Promise<void>} Resolves when condition is met, rejects on timeout
+   */
+  const waitFor = async (
+    predicateFn: (state: CallerSnapshotFrom<TMachine>) => boolean,
+    timeoutMs: number = 5000
+  ): Promise<void> => {
+    // Check if condition is already met
+    if (predicateFn(currentSnapshot)) {
+      return Promise.resolve();
+    }
+    return new Promise((resolve, reject) => {
+      let timeoutId: number | null = null;
+
+      // Set up timeout to reject if condition isn't met in time
+      if (timeoutMs > 0) {
+        timeoutId = setTimeout(() => {
+          unsubscribe();
+          reject(
+            new Error(`Timeout waiting for condition after ${timeoutMs}ms`)
+          );
+        }, timeoutMs);
+      }
+
+      // Subscribe to state changes
+      const unsubscribe = subscribe((state) => {
+        if (predicateFn(state)) {
+          if (timeoutId) {
+            clearTimeout(timeoutId);
+          }
+          unsubscribe();
+          resolve();
+        }
+      });
+    });
+  };
+
+  return {
+    connect,
+    disconnect,
+    send,
+    getState,
+    subscribe,
+    waitFor,
+  };
+}
+
+function getWebSocketUrl(props: ActorKitClientProps<any>): string {
+  const { host, actorId, actorType, accessToken, checksum } = props;
+
+  // Determine protocol (ws or wss)
+  const protocol =
+    /^(localhost|127\.0\.0\.1|192\.168\.|10\.|172\.(1[6-9]|2[0-9]|3[0-1])\.)/.test(
+      host
+    )
+      ? "ws"
+      : "wss";
+
+  // Construct base URL
+  const baseUrl = `${protocol}://${host}/api/${actorType}/${actorId}`;
+
+  // Add query parameters
+  const params = new URLSearchParams({ accessToken });
+  if (checksum) params.append("checksum", checksum);
+
+  const finalUrl = `${baseUrl}?${params.toString()}`;
+
+  return finalUrl;
+}

package/src/createActorKitContext.tsx

@@ -0,0 +1,228 @@
+"use client";
+
+import React, {
+  createContext,
+  memo,
+  ReactNode,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  useSyncExternalStore,
+} from "react";
+import { matchesState, StateValueFrom } from "xstate";
+import type { ActorKitClientProps } from "./createActorKitClient";
+import { createActorKitClient } from "./createActorKitClient";
+import type {
+  ActorKitClient,
+  AnyActorKitStateMachine,
+  CallerSnapshotFrom,
+  ClientEventFrom,
+  MatchesProps,
+} from "./types";
+
+export function createActorKitContext<TMachine extends AnyActorKitStateMachine>(
+  actorType: string
+) {
+  const ActorKitContext = createContext<ActorKitClient<TMachine> | null>(null);
+
+  const ProviderFromClient: React.FC<{
+    children: ReactNode;
+    client: ActorKitClient<TMachine>;
+  }> = ({ children, client }) => {
+    return (
+      <ActorKitContext.Provider value={client}>
+        {children}
+      </ActorKitContext.Provider>
+    );
+  };
+
+  const Provider: React.FC<
+    {
+      children: ReactNode;
+    } & Omit<ActorKitClientProps<TMachine>, "actorType">
+  > = memo((props) => {
+    const clientRef = useRef(
+      createActorKitClient<TMachine>({
+        host: props.host,
+        actorId: props.actorId,
+        accessToken: props.accessToken,
+        checksum: props.checksum,
+        initialSnapshot: props.initialSnapshot,
+        actorType,
+      })
+    );
+    const initializedRef = useRef(false);
+
+    useEffect(() => {
+      if (!initializedRef.current) {
+        initializedRef.current = true;
+        clientRef.current.connect().then(() => {});
+      }
+    }, [initializedRef]);
+
+    return (
+      <ActorKitContext.Provider value={clientRef.current}>
+        {props.children}
+      </ActorKitContext.Provider>
+    );
+  });
+
+  function useClient(): ActorKitClient<TMachine> {
+    const client = useContext(ActorKitContext);
+    if (!client) {
+      throw new Error(
+        "useClient must be used within an ActorKitContext.Provider"
+      );
+    }
+    return client;
+  }
+
+  const useSelector = <T,>(
+    selector: (snapshot: CallerSnapshotFrom<TMachine>) => T
+  ) => {
+    const client = useClient();
+
+    return useSyncExternalStoreWithSelector(
+      client.subscribe,
+      client.getState,
+      client.getState,
+      selector,
+      defaultCompare
+    );
+  };
+
+  function useSend(): (event: ClientEventFrom<TMachine>) => void {
+    const client = useClient();
+    return client.send;
+  }
+
+  function useMatches(stateValue: StateValueFrom<TMachine>): boolean {
+    return useSelector((state) => matchesState(stateValue, state.value as any));
+  }
+
+  const Matches: React.FC<MatchesProps<TMachine> & { children: ReactNode }> & {
+    create: (
+      state: StateValueFrom<TMachine>,
+      options?: {
+        and?: StateValueFrom<TMachine>;
+        or?: StateValueFrom<TMachine>;
+        not?: boolean;
+      }
+    ) => React.FC<
+      Omit<MatchesProps<TMachine>, "state" | "and" | "or" | "not"> & {
+        children: ReactNode;
+      }
+    >;
+  } = (props) => {
+    const active = useMatches(props.state);
+    const matchesAnd = props.and ? useMatches(props.and) : true;
+    const matchesOr = props.or ? useMatches(props.or) : false;
+    const value =
+      typeof props.initialValueOverride === "boolean"
+        ? props.initialValueOverride
+        : (active && matchesAnd) || matchesOr;
+    const finalValue = props.not ? !value : value;
+    return finalValue ? <>{props.children}</> : null;
+  };
+
+  Matches.create = (state, options = {}) => {
+    const Component: React.FC<
+      Omit<MatchesProps<TMachine>, "state" | "and" | "or" | "not"> & {
+        children: ReactNode;
+      }
+    > = ({ children, initialValueOverride }) => (
+      <Matches
+        state={state}
+        and={options.and}
+        or={options.or}
+        not={options.not}
+        initialValueOverride={initialValueOverride}
+      >
+        {children}
+      </Matches>
+    );
+    Component.displayName = `MatchesComponent(${state.toString()})`;
+    return Component;
+  };
+
+  return {
+    Provider,
+    ProviderFromClient,
+    useClient,
+    useSelector,
+    useSend,
+    useMatches,
+    Matches,
+  };
+}
+
+function useSyncExternalStoreWithSelector<Snapshot, Selection>(
+  subscribe: (onStoreChange: () => void) => () => void,
+  getSnapshot: () => Snapshot,
+  getServerSnapshot: undefined | null | (() => Snapshot),
+  selector: (snapshot: Snapshot) => Selection,
+  isEqual?: (a: Selection, b: Selection) => boolean
+): Selection {
+  const [getSelection, getServerSelection] = useMemo(() => {
+    let hasMemo = false;
+    let memoizedSnapshot: Snapshot;
+    let memoizedSelection: Selection;
+
+    const memoizedSelector = (nextSnapshot: Snapshot) => {
+      if (!hasMemo) {
+        hasMemo = true;
+        memoizedSnapshot = nextSnapshot;
+        memoizedSelection = selector(nextSnapshot);
+        return memoizedSelection;
+      }
+
+      if (Object.is(memoizedSnapshot, nextSnapshot)) {
+        return memoizedSelection;
+      }
+
+      const nextSelection = selector(nextSnapshot);
+
+      if (isEqual && isEqual(memoizedSelection, nextSelection)) {
+        memoizedSnapshot = nextSnapshot;
+        return memoizedSelection;
+      }
+
+      memoizedSnapshot = nextSnapshot;
+      memoizedSelection = nextSelection;
+      return nextSelection;
+    };
+
+    const getSnapshotWithSelector = () => memoizedSelector(getSnapshot());
+    const getServerSnapshotWithSelector = getServerSnapshot
+      ? () => memoizedSelector(getServerSnapshot())
+      : undefined;
+
+    return [getSnapshotWithSelector, getServerSnapshotWithSelector];
+  }, [getSnapshot, getServerSnapshot, selector, isEqual]);
+
+  const subscribeWithSelector = useCallback(
+    (onStoreChange: () => void) => {
+      let previousSelection = getSelection();
+      return subscribe(() => {
+        const nextSelection = getSelection();
+        if (!isEqual || !isEqual(previousSelection, nextSelection)) {
+          previousSelection = nextSelection;
+          onStoreChange();
+        }
+      });
+    },
+    [subscribe, getSelection, isEqual]
+  );
+
+  return useSyncExternalStore(
+    subscribeWithSelector,
+    getSelection,
+    getServerSelection
+  );
+}
+
+function defaultCompare<T>(a: T, b: T) {
+  return a === b;
+}

package/src/createActorKitMockClient.ts

@@ -0,0 +1,138 @@
+import { Draft, produce } from "immer";
+import {
+  ActorKitClient,
+  AnyActorKitStateMachine,
+  CallerSnapshotFrom,
+  ClientEventFrom,
+} from "./types";
+
+export type ActorKitMockClientProps<TMachine extends AnyActorKitStateMachine> = {
+  initialSnapshot: CallerSnapshotFrom<TMachine>;
+  onSend?: (event: ClientEventFrom<TMachine>) => void;
+};
+
+export type ActorKitMockClient<TMachine extends AnyActorKitStateMachine> = ActorKitClient<TMachine> & {
+  produce: (recipe: (draft: Draft<CallerSnapshotFrom<TMachine>>) => void) => void;
+};
+
+/**
+ * Creates a mock Actor Kit client for testing purposes.
+ *
+ * @template TMachine - The type of the state machine.
+ * @param {ActorKitMockClientProps<TMachine>} props - Configuration options for the mock client.
+ * @returns {ActorKitMockClient<TMachine>} An object with methods to interact with the mock actor.
+ */
+export function createActorKitMockClient<TMachine extends AnyActorKitStateMachine>(
+  props: ActorKitMockClientProps<TMachine>
+): ActorKitMockClient<TMachine> {
+  let currentSnapshot = props.initialSnapshot;
+  const listeners: Set<(state: CallerSnapshotFrom<TMachine>) => void> = new Set();
+
+  /**
+   * Notifies all registered listeners with the current state.
+   */
+  const notifyListeners = () => {
+    listeners.forEach((listener) => listener(currentSnapshot));
+  };
+
+  /**
+   * Updates the state using an Immer producer function.
+   * @param {(draft: Draft<CallerSnapshotFrom<TMachine>>) => void} recipe - The state update recipe.
+   */
+  const produceFn = (recipe: (draft: Draft<CallerSnapshotFrom<TMachine>>) => void) => {
+    currentSnapshot = produce(currentSnapshot, recipe);
+    notifyListeners();
+  };
+
+  /**
+   * Sends an event to the mock client.
+   * @param {ClientEventFrom<TMachine>} event - The event to send.
+   */
+  const send = (event: ClientEventFrom<TMachine>) => {
+    props.onSend?.(event);
+    notifyListeners();
+  };
+
+  /**
+   * Retrieves the current state of the mock actor.
+   * @returns {CallerSnapshotFrom<TMachine>} The current state.
+   */
+  const getState = () => currentSnapshot;
+
+  /**
+   * Subscribes a listener to state changes.
+   * @param {(state: CallerSnapshotFrom<TMachine>) => void} listener - The listener function to be called on state changes.
+   * @returns {() => void} A function to unsubscribe the listener.
+   */
+  const subscribe = (listener: (state: CallerSnapshotFrom<TMachine>) => void) => {
+    listeners.add(listener);
+    return () => {
+      listeners.delete(listener);
+    };
+  };
+
+  /**
+   * Mock connect method.
+   * @returns {Promise<void>} A promise that resolves immediately.
+   */
+  const connect = async () => {
+    // Mock implementation, resolves immediately
+    return Promise.resolve();
+  };
+
+  /**
+   * Mock disconnect method.
+   */
+  const disconnect = () => {
+    // Mock implementation, does nothing
+  };
+
+  /**
+   * Waits for a state condition to be met.
+   * @param {(state: CallerSnapshotFrom<TMachine>) => boolean} predicateFn - Function that returns true when condition is met
+   * @param {number} [timeoutMs=5000] - Maximum time to wait in milliseconds
+   * @returns {Promise<void>} Resolves when condition is met, rejects on timeout
+   */
+  const waitFor = async (
+    predicateFn: (state: CallerSnapshotFrom<TMachine>) => boolean,
+    timeoutMs: number = 5000
+  ): Promise<void> => {
+    // Check if condition is already met
+    if (predicateFn(currentSnapshot)) {
+      return Promise.resolve();
+    }
+
+    return new Promise((resolve, reject) => {
+      let timeoutId: number | null = null;
+
+      // Set up timeout to reject if condition isn't met in time
+      if (timeoutMs > 0) {
+        timeoutId = setTimeout(() => {
+          unsubscribe();
+          reject(new Error(`Timeout waiting for condition after ${timeoutMs}ms`));
+        }, timeoutMs);
+      }
+
+      // Subscribe to state changes
+      const unsubscribe = subscribe((state) => {
+        if (predicateFn(state)) {
+          if (timeoutId) {
+            clearTimeout(timeoutId);
+          }
+          unsubscribe();
+          resolve();
+        }
+      });
+    });
+  };
+
+  return {
+    connect,
+    disconnect,
+    send,
+    getState,
+    subscribe,
+    produce: produceFn,
+    waitFor,
+  };
+}