@indietabletop/appkit 4.0.0 → 4.1.1

package/lib/store/index.tsx

@@ -0,0 +1,227 @@
+import { createActorContext } from "@xstate/react";
+import { createContext, useContext, useMemo, type ReactNode } from "react";
+import { fromCallback, fromPromise } from "xstate";
+import { Failure, Success } from "../async-op.ts";
+import type { GameCode, IndieTabletopClient, UserGameData } from "../client.ts";
+import type { ModernIDB } from "../ModernIDB/ModernIDB.ts";
+import type { ModernIDBIndexes, ModernIDBSchema } from "../ModernIDB/types.ts";
+import type { CurrentUser } from "../types.ts";
+import {
+  machine,
+  type PullChangesInput,
+  type PushChangesInput,
+} from "./store.ts";
+import type { MachineEvent, PullResult, PushResult } from "./types.ts";
+import { toSyncedItems } from "./utils.ts";
+
+export type AppActions = {
+  clientLogout: (params: { serverUser: CurrentUser }) => Promise<void>;
+  serverLogout: () => Promise<void>;
+  logout: () => Promise<void>;
+  push: () => void;
+  pull: () => void;
+};
+
+export const AppActionsContext = createContext<null | AppActions>(null);
+
+const {
+  Provider: InternalMachineProvider,
+  useSelector,
+  useActorRef,
+} = createActorContext(machine);
+
+export { useActorRef, useSelector };
+
+export function useCurrentUser() {
+  return useSelector((s) => s.context.currentUser);
+}
+
+export function useSessionInfo() {
+  return useSelector((s) => s.context.sessionInfo);
+}
+
+export function useAppActions() {
+  const actions = useContext(AppActionsContext);
+
+  if (!actions) {
+    throw new Error(`Missing context value for app actions.`);
+  }
+
+  return actions;
+}
+
+export type DatabaseAppMachineMethods = {
+  upsertGameData(data: UserGameData): Promise<Success<string[]>>;
+
+  getUpdatedGameDataSince(props: {
+    sinceTs: number | null;
+    exclude: Set<string>;
+  }): Promise<Success<UserGameData>>;
+
+  clearAll(): Promise<Success<string> | Failure<string>>;
+};
+
+export function createAppMachineProvider<
+  Schema extends ModernIDBSchema,
+  Indexes extends ModernIDBIndexes<Schema>,
+>(options: {
+  database: ModernIDB<Schema, Indexes> & DatabaseAppMachineMethods;
+  client: IndieTabletopClient;
+  pullGameDataFor: GameCode | GameCode[];
+}) {
+  const { client, database } = options;
+
+  // Concrete implementations of actors that our machine requires.
+
+  const auth = fromCallback<MachineEvent>(({ sendBack }) => {
+    const controller = new AbortController();
+
+    client.addEventListener(
+      "currentUser",
+      ({ detail }) => void sendBack({ type: "currentUser", ...detail }),
+      controller,
+    );
+
+    client.addEventListener(
+      "sessionInfo",
+      ({ detail }) => void sendBack({ type: "sessionInfo", ...detail }),
+      controller,
+    );
+
+    client.addEventListener(
+      "sessionExpired",
+      () => void sendBack({ type: "sessionExpired" }),
+      controller,
+    );
+
+    return () => {
+      controller.abort();
+    };
+  });
+
+  const sync = fromCallback<MachineEvent>(({ sendBack }) => {
+    const controller = new AbortController();
+
+    // As long as sync is active, make sure to `pull` after every window focus.
+    window.addEventListener(
+      "focus",
+      () => void sendBack({ type: "pull" }),
+      controller,
+    );
+
+    // If there is a `readwrite` transaction in IndexedDB trigger a `push`.
+    database.addEventListener(
+      "readwrite",
+      () => void sendBack({ type: "push" }),
+      controller,
+    );
+
+    return () => {
+      controller.abort();
+    };
+  });
+
+  const pullChanges = fromPromise<PullResult, PullChangesInput>(
+    async ({ input }) => {
+      const result = await client.pullUserData({
+        include: options.pullGameDataFor,
+        sinceTs: input.sinceTs,
+        expectCurrentUserId: input.currentUser.id,
+      });
+
+      const userGameData = result.valueOrThrow();
+      await database.upsertGameData(userGameData);
+
+      return new Success({ pulled: toSyncedItems(userGameData) });
+    },
+  );
+
+  const pushChanges = fromPromise<PushResult, PushChangesInput>(
+    async ({ input }) => {
+      const { value: changedData } = await database.getUpdatedGameDataSince({
+        sinceTs: input.sinceTs,
+        exclude: new Set(input.ignoredItems.map((i) => i.id)),
+      });
+
+      const changed = toSyncedItems(changedData);
+
+      if (changed.length === 0) {
+        return new Success({ pushed: [], pulled: [] });
+      }
+
+      const result = await client.pushUserData({
+        data: changedData,
+        pullSinceTs: input.currentSyncTs,
+        currentSyncTs: input.currentSyncTs,
+        expectCurrentUserId: input.currentUser.id,
+      });
+
+      const userGameData = result.valueOrThrow();
+      await database.upsertGameData(userGameData);
+
+      return new Success({
+        pushed: changed,
+        pulled: toSyncedItems(userGameData),
+      });
+    },
+  );
+
+  // Bound provider components
+
+  function AppActionsProvider(props: { children: ReactNode }) {
+    const { children } = props;
+    const app = useActorRef();
+
+    const actions: AppActions = useMemo(() => {
+      async function clientLogout(params: { serverUser: CurrentUser }) {
+        await database.clearAll();
+        app.send({ type: "serverUser", ...params });
+
+        // Get new session info
+        await client.refreshTokens();
+      }
+
+      async function serverLogout() {
+        await client.logout();
+      }
+
+      async function logout() {
+        await client.logout();
+        await database.clearAll();
+        app.send({ type: "reset" });
+      }
+
+      function push() {
+        app.send({ type: "push" });
+      }
+
+      function pull() {
+        app.send({ type: "pull" });
+      }
+
+      return {
+        pull,
+        push,
+        logout,
+        serverLogout,
+        clientLogout,
+      };
+    }, [app]);
+
+    return <AppActionsContext value={actions}>{children}</AppActionsContext>;
+  }
+
+  return function AppMachineProvider(props: { children: ReactNode }) {
+    const { children } = props;
+
+    return (
+      <InternalMachineProvider
+        logic={machine.provide({
+          actors: { auth, sync, pullChanges, pushChanges },
+        })}
+      >
+        <AppActionsProvider>{children}</AppActionsProvider>
+      </InternalMachineProvider>
+    );
+  };
+}

package/lib/store/store.ts

@@ -0,0 +1,453 @@
+import { number } from "superstruct";
+import {
+  and,
+  assertEvent,
+  assign,
+  fromCallback,
+  fromPromise,
+  setup,
+} from "xstate";
+import {
+  createSafeStorage,
+  type SafeStorageKey,
+} from "../createSafeStorage.ts";
+import { currentUser, sessionInfo } from "../structs.ts";
+import type { CurrentUser, SessionInfo } from "../types.ts";
+import type {
+  MachineContext,
+  MachineEvent,
+  PullResult,
+  PushResult,
+  SyncedItem,
+} from "./types.ts";
+import { assertNonNullish, caughtToResult } from "./utils.ts";
+
+const safeStorage = createSafeStorage({
+  currentUser: currentUser(),
+  sessionInfo: sessionInfo(),
+  lastSuccessfulSyncTs: number(),
+});
+
+function createInMemoryContext(): Omit<
+  MachineContext,
+  SafeStorageKey<typeof safeStorage>
+> {
+  return {
+    currentSync: null,
+    pushOnceIdle: false,
+    syncLog: [],
+  };
+}
+
+function createInitialContext(): MachineContext {
+  return {
+    ...createInMemoryContext(),
+    currentUser: safeStorage.getItem("currentUser"),
+    sessionInfo: safeStorage.getItem("sessionInfo"),
+    lastSuccessfulSyncTs: safeStorage.getItem("lastSuccessfulSyncTs"),
+  };
+}
+
+const sync = fromCallback<MachineEvent>(() => {
+  throw new Error(`Sync actor not provided.`);
+});
+
+const auth = fromCallback<MachineEvent>(() => {
+  throw new Error(`Auth actor not provided.`);
+});
+
+export type PullChangesInput = {
+  sinceTs: number | null;
+  currentUser: CurrentUser;
+};
+
+const pullChanges = fromPromise<PullResult, PullChangesInput>(() => {
+  throw new Error(`Pull changes actor not provided.`);
+});
+
+export type PushChangesInput = {
+  sinceTs: number | null;
+  currentSyncTs: number;
+  ignoredItems: SyncedItem[];
+  currentUser: CurrentUser;
+};
+
+const pushChanges = fromPromise<PushResult, PushChangesInput>(async () => {
+  throw new Error(`Push changes actor not provided.`);
+});
+
+const config = setup({
+  types: {
+    context: {} as MachineContext,
+    events: {} as MachineEvent,
+    children: {} as {
+      sync: "sync";
+      auth: "auth";
+    },
+  },
+
+  actors: {
+    auth,
+    sync,
+    pullChanges,
+    pushChanges,
+  },
+
+  actions: {
+    setCurrentSync: assign({
+      currentSync: () => ({ startedTs: Date.now(), pull: null, push: null }),
+    }),
+
+    flushCurrentSync: assign(({ context }) => {
+      const { currentSync, syncLog } = context;
+
+      assertNonNullish(
+        currentSync,
+        "Flushing current sync but context.currentSync is nullish.",
+      );
+
+      return {
+        currentSync: null,
+        syncLog: [currentSync, ...syncLog],
+      };
+    }),
+
+    setLastSuccessfulSync: assign(({ context }) => {
+      assertNonNullish(
+        context.currentSync,
+        "Setting last successful sync but context.currentSync is nullish.",
+      );
+
+      const lastSuccessfulSyncTs = context.currentSync.startedTs;
+      safeStorage.setItem("lastSuccessfulSyncTs", lastSuccessfulSyncTs);
+      return { lastSuccessfulSyncTs };
+    }),
+
+    markSyncStepResult: assign({
+      currentSync: (
+        { context },
+        params: { pull?: PullResult; push?: PushResult },
+      ) => {
+        assertNonNullish(
+          context.currentSync,
+          "Marking sync step result but context.currentSync is nullish.",
+        );
+
+        return {
+          ...context.currentSync,
+          ...params,
+        };
+      },
+    }),
+
+    queuePush: assign({ pushOnceIdle: true }),
+
+    clearPushQueue: assign({ pushOnceIdle: false }),
+
+    setCurrentUser: assign((_, currentUser: CurrentUser) => {
+      safeStorage.setItem("currentUser", currentUser);
+      return { currentUser };
+    }),
+
+    patchSessionInfo: assign(({ context }, newSessionInfo: SessionInfo) => {
+      const sessionInfo = context.sessionInfo
+        ? { ...context.sessionInfo, expiresTs: newSessionInfo.expiresTs }
+        : newSessionInfo;
+
+      safeStorage.setItem("sessionInfo", sessionInfo);
+      return { sessionInfo };
+    }),
+
+    resetContext: assign((): MachineContext => {
+      safeStorage.clear();
+
+      return {
+        ...createInMemoryContext(),
+        currentUser: null,
+        sessionInfo: null,
+        lastSuccessfulSyncTs: null,
+      };
+    }),
+
+    resetWithServerUser: assign((_, serverUser: CurrentUser) => {
+      safeStorage.clear();
+      safeStorage.setItem("currentUser", serverUser);
+
+      return {
+        ...createInMemoryContext(),
+        currentUser: serverUser,
+        sessionInfo: null,
+        lastSuccessfulSyncTs: null,
+      };
+    }),
+  },
+
+  guards: {
+    shouldPushOnceIdle: ({ context }) => {
+      return context.pushOnceIdle;
+    },
+
+    isEligibleForSync: and(["isUserVerified", "isNotMismatched"]),
+
+    isUserVerified: ({ event }) => {
+      assertEvent(event, "currentUser");
+
+      return event.currentUser.isVerified;
+    },
+
+    isNotMismatched: ({ event, context }) => {
+      assertEvent(event, "currentUser");
+
+      // If there is no current user, there cannot be a mismatch
+      if (!context.currentUser) {
+        return true;
+      }
+
+      // Otherwise check that user IDs match.
+      return context.currentUser.id === event.currentUser.id;
+    },
+  },
+});
+
+export const machine = config.createMachine({
+  /** @xstate-layout N4IgpgJg5mDOIC5QEMAOqDEAnOYAuA2gAwC6ioqA9rAJZ42UB25IAHogLQBMRAbAHQBOQbwCMggOy8ALES7DRAGhABPTvIn8AzAA5B0rdN4BWCRKKDRvAL7XlaVPwCujZE7wALMI3oBjZHiQGL5OWDg+AKqwYFjEZEggVLT0TCzsCMai0vzSejrGRIayvLwSymoIHLmi-MZcvIa6+bk8xrb26M6u7l4+NP6BEMGh4XhRMQSi8RTUdAzMCem5RPw6WlziZryWEqJKqojCK1oSgvXrRMZXRu0gDl1unt5+AUEhYc-jsVzTibMpC1ASx05UOolu9xcj16L0GGGiWAAbjEvnEWEk5qlFoguDoiKDKntwXY7p1oc9+q8hu9RqjSOj-vM0ohpCIhKJClwuFIdnsCaIuEZ+LxcdzpLtpFxMhCyT0KQM3iNPgjJr8MQDmYSOfzBDLHOS+gqhtFYLQmABJRgAM0oaIS6qZ2IQOiF6y0gh0OismQken5goEIp0YolUuJHX1csNVPhcDNjAAoqxUDQcBA7TNko6gYhDDUtIUBUQDBIpTxeASOO6uPwNroJNIBcZPQ2bCT7gbYZB+LAVIxfD2+74aIwoBgIEwwD28K9+B2o12IIP+8vh6OM38s1icwguTJaqIG4IC3sG1oCdzjPxzJJjFpxBz78W9XOF5TBqvVyOx6gnLAPBuDrbmwiAckQNT6HogimPopiGAS0imPwoh6Fy5iSmsegvp277dr2K74WuUD8L+AA2pHfuOk78COiKUAA1lO85PNGH6EV+o4kU45HfggtGUAM8xxIBjLAekRbZPk+gGAWLolOeBwIFYqynMe+QSuB0nYW+RqfoR35cTxo4YDEWCUFgJGkQENpYAAtnOsosYuelDgZZEUaOfGMHRglMMJ9L2qJgIgUpWTZGI5imKWDY6BWilZFotasiYDS5MYurto5MK4Uu7H6Zxv7-pRE6MFO-GMQ5kZOTlLn9m5f4eLx-G+Yw-lqkFmpWL6qzgeYBZELs3L7BUBbIXwBSiLouJiMGXDadVul5a5BUNZRpnmZZ1nmfZzHZYtQ4ccRhWNZ5zUBEJpAiVuwXicYJSrDJvAuni+goRegq1IYZYeqeWRtJlVV7VSn40BApFgBgx1XZiN2gYIfAHkeJxELFLoElI2QodBJ6CnoDbzUDbEHaD4OQ9xpHQxqTobPUPUCp6hQlFKxgEg0gi1FyxjSIhWiyVKBPysD7EkxDlPZiFKFiNovMnOYoqIVwBJeolMtaHUkoNMG4akoDgtEyuADuyBzMZUMBZmMOdVINY+qyBY-WUilPTWWOtJK7oNBIAusXhB1GybY6sLAM6BHOVqBFgAAUogFEQACUGC7XrvuG8b9Drubm6W06WRcrW1vine0HSQSzaaCKyO8EQcgDdztgkowlAQHALAOAy12atwXNCCImwyHICiVmIAhyKlTRc8GL5QjpVLt9nO4cIe2TmIU1exWXa+VkYNQx8GDQyJN-X-RGr4LbPgUd06wbZFwuiXEjIjHlvUjCgYrLwwK3ImN7zkjmAFFQBoAAI3BnPKmO5PSJVOOBXQx4Ni+gJEcVYVxgymCsDoUsc0Aan0JinXwYDxbpAwTWW+eJTB20fgpCoVZuav0MEcT+Uhj46xwcnXKB18pQAIWJQ4PBax33IceShlZDw6Doe-cCaEZBthPjhfaBFlpHXJt+bhsMEAiDEaQ++FDthUNAuFca4FeqyA9BlWRM99YDk4VxIqo5VGdQwjkBoVgUYum9HopSkleZ8DVjwSaVhDw-xqktOqnFCKQHsTnSwNRIrNmELkSUjsKiTW0HdWOHozC3zqDoIJ8irGKP4FaY24MICRJ3H4zQaDGzpQ5DHBBilb7s0PDFQUgoRBbFyULYmYMwBlJChsFC2hJEYLWOYDB6MRSpIihIK4DYhqdMsfwf26cuEX3nhLRsYiTiHyyKWSUAoJk1jVtM2ZiStD12sEAA */
+  id: "app",
+  context: () => createInitialContext(),
+
+  invoke: {
+    id: "auth",
+    src: "auth",
+  },
+
+  initial: "unauthenticated",
+
+  on: {
+    reset: [
+      {
+        actions: "resetContext",
+        target: ".unauthenticated",
+      },
+    ],
+  },
+
+  states: {
+    unauthenticated: {
+      description:
+        "The user is either completely anonymous, authenticated via insecure means (localStorage), or in an otherwise no-correctly-authenticated state (e.g. user mismatch).",
+
+      on: {
+        currentUser: [
+          {
+            guard: "isEligibleForSync",
+            target: "authenticated",
+
+            actions: {
+              type: "setCurrentUser",
+              params: ({ event }) => event.currentUser,
+            },
+          },
+          {
+            guard: "isNotMismatched",
+            target: "authenticated.ineligible",
+
+            actions: {
+              type: "setCurrentUser",
+              params: ({ event }) => event.currentUser,
+            },
+          },
+          { target: "unauthenticated" },
+        ],
+        serverUser: {
+          target: "authenticated",
+          actions: {
+            type: "resetWithServerUser",
+            params: ({ event }) => event.serverUser,
+          },
+        },
+      },
+    },
+
+    authenticated: {
+      description: "The user has a session with ITC.",
+
+      initial: "sync",
+
+      on: {
+        currentUser: [
+          {
+            guard: "isNotMismatched",
+            actions: {
+              type: "setCurrentUser",
+              params: ({ event }) => event.currentUser,
+            },
+          },
+          {
+            target: "unauthenticated",
+          },
+        ],
+
+        sessionInfo: {
+          actions: {
+            type: "patchSessionInfo",
+            params: ({ event }) => event.sessionInfo,
+          },
+        },
+
+        sessionExpired: {
+          target: "unauthenticated",
+        },
+      },
+
+      states: {
+        ineligible: {
+          description: "The user is not eligible for sync (e.g. unverified)",
+        },
+
+        sync: {
+          description: "The user is eligible for the sync feature.",
+          invoke: {
+            id: "sync",
+            src: "sync",
+          },
+
+          initial: "syncing",
+
+          states: {
+            syncing: {
+              description: "The sync operation is in progress.",
+              initial: "pulling",
+              entry: "setCurrentSync",
+              exit: "flushCurrentSync",
+
+              on: {
+                push: {
+                  actions: "queuePush",
+                },
+              },
+
+              states: {
+                pulling: {
+                  invoke: {
+                    src: "pullChanges",
+                    input: ({ context }) => ({
+                      sinceTs: context.lastSuccessfulSyncTs,
+                      currentUser: context.currentUser!,
+                    }),
+                    onDone: {
+                      target: "pushing",
+                      actions: [
+                        {
+                          type: "markSyncStepResult",
+                          params: ({ event }) => ({
+                            pull: event.output,
+                          }),
+                        },
+                      ],
+                    },
+                    onError: {
+                      target: "failed",
+                      actions: {
+                        type: "markSyncStepResult",
+                        params: ({ event }) => ({
+                          pull: caughtToResult(event.error),
+                        }),
+                      },
+                    },
+                  },
+                },
+                pushing: {
+                  entry: "clearPushQueue",
+
+                  invoke: {
+                    src: "pushChanges",
+                    input: ({ context }) => {
+                      assertNonNullish(
+                        context.currentSync,
+                        "Setting pushChanges input but context.currentSync is unset.",
+                      );
+
+                      assertNonNullish(
+                        context.currentUser,
+                        "Setting pushChanges input but context.currentUser is unset.",
+                      );
+
+                      // This value might be unset if no push was made during
+                      // this sync attempt.
+                      const pulledItems =
+                        context.currentSync.pull?.valueOrNull()?.pulled ?? [];
+
+                      return {
+                        ignoredItems: pulledItems,
+                        currentSyncTs: context.currentSync.startedTs,
+                        sinceTs: context.lastSuccessfulSyncTs,
+                        currentUser: context.currentUser,
+                      };
+                    },
+                    onDone: {
+                      target: "synced",
+                      actions: {
+                        type: "markSyncStepResult",
+                        params: ({ event }) => ({
+                          push: event.output,
+                        }),
+                      },
+                    },
+                    onError: {
+                      target: "failed",
+                      actions: {
+                        type: "markSyncStepResult",
+                        params: ({ event }) => ({
+                          push: caughtToResult(event.error),
+                        }),
+                      },
+                    },
+                  },
+                },
+                synced: {
+                  type: "final",
+                  entry: "setLastSuccessfulSync",
+                },
+
+                failed: {
+                  type: "final",
+                },
+              },
+
+              onDone: "idle",
+            },
+
+            idle: {
+              description: "The app is listening for sync events.",
+              always: {
+                guard: "shouldPushOnceIdle",
+                target: "waiting",
+              },
+              on: {
+                push: "waiting",
+                pull: "syncing",
+              },
+            },
+
+            waiting: {
+              description:
+                "We are waiting for further push events to batch them.",
+
+              after: {
+                1500: {
+                  target: "syncing.pushing",
+                },
+              },
+
+              on: {
+                push: {
+                  target: "waiting",
+                  reenter: true,
+                },
+              },
+            },
+          },
+        },
+      },
+    },
+  },
+});