@methodacting/actor-kit 0.47.0

package/src/types.ts

@@ -0,0 +1,334 @@
+import { DurableObject } from "cloudflare:workers";
+import { Operation } from "fast-json-patch";
+import type {
+  AnyEventObject,
+  AnyStateMachine,
+  SnapshotFrom,
+  StateMachine,
+  StateValueFrom,
+} from "xstate";
+import type { z } from "zod";
+import type {
+  AnyEventSchema,
+  CallerSchema,
+  RequestInfoSchema,
+  SystemEventSchema,
+} from "./schemas";
+import type { AlarmManager } from "./alarms";
+import type { ActorKitStorage } from "./storage";
+
+export type EnvWithDurableObjects = {
+  ACTOR_KIT_SECRET: string;
+  [key: string]: DurableObjectNamespace<ActorServer<any>> | unknown;
+};
+
+export type AnyEvent = z.infer<typeof AnyEventSchema>;
+
+export interface ActorServerMethods<TMachine extends BaseActorKitStateMachine> {
+  fetch(request: Request): Promise<Response>;
+  spawn(props: {
+    actorType: string;
+    actorId: string;
+    caller: Caller;
+    input: Record<string, unknown>;
+  }): void;
+  send(event: ClientEventFrom<TMachine> | ServiceEventFrom<TMachine>): void;
+  getSnapshot(
+    caller: Caller,
+    options?: {
+      waitForEvent?: ClientEventFrom<TMachine>;
+      waitForState?: StateValueFrom<TMachine>;
+      timeout?: number;
+      errorOnWaitTimeout?: boolean;
+    }
+  ): Promise<{
+    checksum: string;
+    snapshot: CallerSnapshotFrom<TMachine>;
+  }>;
+}
+
+export type ActorServer<TMachine extends AnyActorKitStateMachine> =
+  DurableObject & ActorServerMethods<TMachine>;
+export type AnyActorServer = ActorServer<any>;
+
+export type Caller = z.infer<typeof CallerSchema>;
+export type RequestInfo = z.infer<typeof RequestInfoSchema>;
+
+export type ActorKitInputProps = {
+  id: string;
+  caller: Caller;
+  storage: DurableObjectStorage;
+  [key: string]: unknown;
+};
+
+export type CallerType = "client" | "system" | "service";
+
+type EventObject = {
+  type: string;
+};
+
+type EventSchemaUnion = z.ZodDiscriminatedUnion<
+  "type",
+  [
+    z.ZodObject<z.ZodRawShape & { type: z.ZodString }>,
+    ...z.ZodObject<z.ZodRawShape & { type: z.ZodString }>[]
+  ]
+>;
+
+export type EventSchemas = {
+  client: EventSchemaUnion;
+  service: EventSchemaUnion;
+};
+
+export type BaseActorKitContext<
+  TPublicProps extends { [key: string]: unknown },
+  TPrivateProps extends { [key: string]: unknown }
+> = {
+  public: TPublicProps;
+  private: Record<string, TPrivateProps>;
+};
+
+export type ActorKitStateMachine<
+  TEvent extends BaseActorKitEvent<EnvWithDurableObjects>,
+  TInput extends {
+    id: string;
+    caller: Caller;
+    storage: DurableObjectStorage;
+  },
+  TContext extends BaseActorKitContext<any, any> & {
+    [key: string]: unknown;
+  }
+> = StateMachine<
+  TContext,
+  TEvent & EventObject,
+  any,
+  any,
+  any,
+  any,
+  any,
+  any,
+  any,
+  TInput,
+  any,
+  any,
+  any,
+  any
+>;
+
+export type BaseActorKitInput<TEnv = EnvWithDurableObjects> = {
+  id: string;
+  caller: Caller;
+  env: TEnv;
+  storage: DurableObjectStorage;
+};
+
+export type WithActorKitInput<
+  TInputProps extends { [key: string]: unknown },
+  TEnv extends EnvWithDurableObjects
+> = TInputProps & BaseActorKitInput<TEnv>;
+
+export type AnyActorKitStateMachine = ActorKitStateMachine<any, any, any>;
+
+type AnyActorKitEvent = (
+  | WithActorKitEvent<AnyEventObject, "client">
+  | WithActorKitEvent<AnyEventObject, "service">
+  | ActorKitSystemEvent
+) &
+  BaseActorKitEvent<EnvWithDurableObjects>;
+
+type AnyActorKitInput = WithActorKitInput<
+  { [key: string]: unknown },
+  EnvWithDurableObjects
+> & {
+  storage: DurableObjectStorage;
+};
+
+type AnyActorKitContext = {
+  public: { [key: string]: unknown };
+  private: Record<string, { [key: string]: unknown }>;
+};
+
+export type BaseActorKitStateMachine = ActorKitStateMachine<
+  AnyActorKitEvent,
+  AnyActorKitInput,
+  AnyActorKitContext
+>;
+
+export type ExtraContext = {
+  requestId: string;
+};
+
+export interface BaseActorKitEvent<TEnv extends EnvWithDurableObjects> {
+  caller: Caller;
+  storage: DurableObjectStorage;
+  requestInfo?: RequestInfo;
+  env: TEnv;
+}
+
+export type ActorKitSystemEvent = z.infer<typeof SystemEventSchema>;
+
+// Utility type to merge custom event types with the base event
+export type WithActorKitEvent<
+  T extends { type: string },
+  C extends CallerType
+> = T & BaseActorKitEvent<EnvWithDurableObjects> & { caller: { type: C } };
+
+export type WithActorKitContext<
+  TExtraProps extends { [key: string]: unknown },
+  TPrivateProps extends { [key: string]: unknown },
+  TPublicProps extends { [key: string]: unknown }
+> = TExtraProps & {
+  public: TPublicProps;
+  private: Record<string, TPrivateProps>;
+};
+
+export type CallerSnapshotFrom<TMachine extends AnyStateMachine> = {
+  public: SnapshotFrom<TMachine> extends { context: { public: infer P } }
+    ? P
+    : unknown;
+  private: SnapshotFrom<TMachine> extends {
+    context: { private: Partial<Record<string, infer PR>> };
+  }
+    ? PR
+    : unknown;
+  value: SnapshotFrom<TMachine> extends { value: infer V } ? V : unknown;
+};
+
+export type ClientEventFrom<T extends AnyActorKitStateMachine> =
+  T extends StateMachine<
+    any,
+    infer TEvent,
+    any,
+    any,
+    any,
+    any,
+    any,
+    any,
+    any,
+    any,
+    any,
+    any,
+    any,
+    any
+  >
+    ? TEvent extends WithActorKitEvent<infer E, "client">
+      ? Omit<E, keyof BaseActorKitEvent<EnvWithDurableObjects>>
+      : never
+    : never;
+
+export type ServiceEventFrom<T extends AnyActorKitStateMachine> =
+  T extends StateMachine<
+    any,
+    infer TEvent,
+    any,
+    any,
+    any,
+    any,
+    any,
+    any,
+    any,
+    any,
+    any,
+    any,
+    any,
+    any
+  >
+    ? TEvent extends WithActorKitEvent<infer E, "service">
+      ? Omit<E, keyof BaseActorKitEvent<EnvWithDurableObjects>>
+      : never
+    : never;
+
+// Helper type to convert from SCREAMING_SNAKE_CASE to kebab-case
+export type ScreamingSnakeToKebab<S extends string> =
+  S extends `${infer T}_${infer U}`
+    ? `${Lowercase<T>}-${ScreamingSnakeToKebab<U>}`
+    : Lowercase<S>;
+
+export type DurableObjectActor<TMachine extends AnyActorKitStateMachine> =
+  ActorServer<TMachine>;
+
+type CamelToSnakeCase<S extends string> = S extends `${infer T}${infer U}`
+  ? U extends Uncapitalize<U>
+    ? `${Lowercase<T>}${CamelToSnakeCase<U>}`
+    : `${Lowercase<T>}_${CamelToSnakeCase<U>}`
+  : S;
+
+type KebabToCamelCase<S extends string> = S extends `${infer T}-${infer U}`
+  ? `${T}${Capitalize<KebabToCamelCase<U>>}`
+  : S;
+
+export type KebabToScreamingSnake<S extends string> = Uppercase<
+  CamelToSnakeCase<KebabToCamelCase<S>>
+>;
+export interface MatchesProps<TMachine extends AnyActorKitStateMachine> {
+  state: StateValueFrom<TMachine>;
+  and?: StateValueFrom<TMachine>;
+  or?: StateValueFrom<TMachine>;
+  not?: boolean;
+  initialValueOverride?: boolean;
+}
+
+export type MachineFromServer<T> = T extends ActorServer<infer M> ? M : never;
+
+export type ActorKitEmittedEvent = {
+  operations: Operation[];
+  checksum: string;
+};
+// | {
+//     snapshot: CallerSnapshotFrom<TMachine>;
+//     checksum: string;
+//   };
+
+export type ActorKitClient<TMachine extends AnyActorKitStateMachine> = {
+  connect: () => Promise<void>;
+  disconnect: () => void;
+  send: (event: ClientEventFrom<TMachine>) => void;
+  getState: () => CallerSnapshotFrom<TMachine>;
+  subscribe: (
+    listener: (state: CallerSnapshotFrom<TMachine>) => void
+  ) => () => void;
+  waitFor: (
+    predicateFn: (state: CallerSnapshotFrom<TMachine>) => boolean,
+    timeoutMs?: number
+  ) => Promise<void>;
+};
+
+// First define a helper to extract the event type from a machine
+type ExtractEventType<TMachine> = TMachine extends ActorKitStateMachine<
+  infer TEvent,
+  any,
+  any
+>
+  ? TEvent
+  : never;
+
+// Then extract the env type from the event
+type ExtractEnvType<TEvent> = TEvent extends { env: infer TEnv } ? TEnv : never;
+
+// Finally, our InferEnvFromMachine type that ensures EnvWithDurableObjects
+export type EnvFromMachine<TMachine extends AnyActorKitStateMachine> =
+  ExtractEnvType<ExtractEventType<TMachine>> extends never
+    ? EnvWithDurableObjects
+    : ExtractEnvType<ExtractEventType<TMachine>> & EnvWithDurableObjects;
+
+// ==================== Alarm & Storage Types ====================
+
+/**
+ * Options for creating a MachineServer with alarm support
+ */
+export interface MachineServerOptions {
+  persisted?: boolean;
+  /**
+   * Enable alarm-based scheduling for XState delayed events
+   * @default true
+   */
+  enableAlarms?: boolean;
+}
+
+/**
+ * Internal services available to the machine server
+ */
+export interface MachineServerServices {
+  storage: ActorKitStorage;
+  alarmManager: AlarmManager | null;
+}

package/src/utils.ts

@@ -0,0 +1,171 @@
+import { jwtVerify, SignJWT } from "jose";
+import { PERSISTED_SNAPSHOT_KEY } from "./constants";
+import { CallerStringSchema } from "./schemas";
+import { Caller } from "./types";
+
+// Define log levels
+export enum LogLevel {
+  ERROR = 0,
+  WARN = 1,
+  INFO = 2,
+  DEBUG = 3,
+}
+
+// Declare a global variable to control debug level
+declare global {
+  var DEBUG_LEVEL: LogLevel | undefined;
+}
+
+// Set the current log level based on the global DEBUG_LEVEL variable
+// Default to INFO if not set
+const getCurrentLogLevel = (): LogLevel => {
+  return globalThis.DEBUG_LEVEL !== undefined
+    ? globalThis.DEBUG_LEVEL
+    : LogLevel.INFO;
+};
+
+/**
+ * Debug logging function
+ * @param message The message to log
+ * @param level The log level (default: DEBUG)
+ * @param data Additional data to log (optional)
+ */
+export function debug(
+  message: string,
+  level: LogLevel = LogLevel.DEBUG,
+  data?: any
+) {
+  const currentLogLevel = getCurrentLogLevel();
+  if (level <= currentLogLevel) {
+    const timestamp = new Date().toISOString();
+    const logMessage = `[${timestamp}] ${LogLevel[level]}: ${message}`;
+
+    if (data) {
+      console.log(logMessage, data);
+    } else {
+      console.log(logMessage);
+    }
+
+    // You can extend this to send logs to a service if needed
+    // For example:
+    // if (typeof fetch !== 'undefined') {
+    //   fetch('https://your-logging-service.com', {
+    //     method: 'POST',
+    //     body: JSON.stringify({ message: logMessage, level, data }),
+    //   });
+    // }
+  }
+}
+
+// Convenience methods for different log levels
+export const logError = (message: string, data?: any) =>
+  debug(message, LogLevel.ERROR, data);
+export const logWarn = (message: string, data?: any) =>
+  debug(message, LogLevel.WARN, data);
+export const logInfo = (message: string, data?: any) =>
+  debug(message, LogLevel.INFO, data);
+
+export const json = <T>(data: T, status = 200) =>
+  Response.json(data, { status });
+
+export const ok = () => json({ ok: true });
+
+export const error = (err: string | { message: string }, status = 500) => {
+  console.error("Error response", err);
+  return json(
+    {
+      ok: false,
+      error: typeof err === "string" ? err : err.message ?? "Unknown error",
+    },
+    status
+  );
+};
+
+export const notFound = () => error("Not found", 404);
+
+/**
+ * Parses query parameters from a URL string.
+ * @param url The URL to parse.
+ * @returns A URLSearchParams object containing the parsed query parameters.
+ */
+export const parseQueryParams = (url: string) => {
+  const index = url.indexOf("?");
+  const search = index !== -1 ? url.substring(index + 1) : "";
+  return new URLSearchParams(search);
+};
+
+export function assert<T>(
+  expression: T,
+  errorMessage: string
+): asserts expression {
+  if (!expression) {
+    const error = new Error(errorMessage);
+    const stack = error.stack?.split("\n");
+
+    // Find the line in the stack trace that corresponds to where the assert was called.
+    // This is typically the third line in the stack, but this may vary depending on the JS environment.
+    const assertLine =
+      stack && stack.length >= 3 ? stack[2] : "unknown location";
+
+    throw new Error(`${errorMessage} (Assert failed at ${assertLine?.trim()})`);
+  }
+}
+
+export async function getCallerFromRequest(
+  request: Request,
+  actorType: string,
+  actorId: string,
+  secret: string
+): Promise<Caller> {
+  let accessToken: string;
+  if (request.headers.get("Upgrade") !== "websocket") {
+    const authHeader = request.headers.get("Authorization");
+    const stringPart = authHeader?.split(" ")[1];
+    assert(stringPart, "Expected authorization header to be set");
+    accessToken = stringPart;
+  } else {
+    const searchParams = new URLSearchParams(request.url.split("?")[1]);
+    const paramString = searchParams.get("accessToken");
+    assert(paramString, "expected accessToken when connecting to socket");
+    accessToken = paramString;
+  }
+
+  return parseAccessTokenForCaller({
+    accessToken,
+    type: actorType,
+    id: actorId,
+    secret,
+  });
+}
+
+export async function parseAccessTokenForCaller({
+  accessToken,
+  type,
+  id,
+  secret,
+}: {
+  accessToken: string;
+  type: string;
+  id: string;
+  secret: string;
+}): Promise<Caller> {
+  const verified = await jwtVerify(
+    accessToken,
+    new TextEncoder().encode(secret)
+  );
+  if (!verified.payload.jti) {
+    throw new Error("Expected JTI on accessToken");
+  }
+  if (verified.payload.jti !== id) {
+    throw new Error(`Expected JTI on accessToken to match actor id: ${id}`);
+  }
+  if (!verified.payload.aud) {
+    throw new Error(
+      `Expected accessToken audience to match actor type: ${type}`
+    );
+  }
+  if (!verified.payload.sub) {
+    throw new Error("Expected accessToken to have subject");
+  }
+  return CallerStringSchema.parse(verified.payload.sub);
+}

package/src/withActorKit.tsx

@@ -0,0 +1,103 @@
+import type { StoryContext, StoryFn } from "@storybook/react";
+import React from "react";
+import { createActorKitContext } from "./createActorKitContext";
+import { createActorKitMockClient } from "./createActorKitMockClient";
+import type { AnyActorKitStateMachine, CallerSnapshotFrom } from "./types";
+import { ActorKitParameters } from "./storybook";
+
+/**
+ * Storybook decorator that sets up actor-kit state machines.
+ *
+ * There are two main patterns for testing with actor-kit:
+ *
+ * 1. Static Stories (Use parameters.actorKit + within):
+ * - Use this decorator with parameters.actorKit
+ * - Use `within(canvasElement)` in play functions
+ * - Good for simple stories that don't need state manipulation
+ *
+ * 2. Interactive Stories (Use mount + direct client):
+ * - Don't use this decorator
+ * - Create client manually and use mount in play function
+ * - Good for stories that need to manipulate state
+ *
+ * @example
+ * ```tsx
+ * // Pattern 1: Static Story
+ * export const Static: Story = {
+ *   parameters: {
+ *     actorKit: {
+ *       session: {
+ *         "session-123": { ... }
+ *       }
+ *     }
+ *   },
+ *   play: async ({ canvasElement }) => {
+ *     const canvas = within(canvasElement);
+ *     // Test UI state...
+ *   }
+ * };
+ *
+ * // Pattern 2: Interactive Story
+ * export const Interactive: Story = {
+ *   play: async ({ canvasElement, mount }) => {
+ *     const client = createActorKitMockClient({...});
+ *     const canvas = within(canvasElement);
+ *
+ *     await mount(
+ *       <Context.ProviderFromClient client={client}>
+ *         <Component />
+ *       </Context.ProviderFromClient>
+ *     );
+ *
+ *     // Now you can manipulate client state...
+ *     client.produce((draft) => { ... });
+ *   }
+ * };
+ * ```
+ */
+export const withActorKit = <TMachine extends AnyActorKitStateMachine>({
+  actorType,
+  context,
+}: {
+  actorType: string;
+  context: ReturnType<typeof createActorKitContext<TMachine>>;
+}) => {
+  return (Story: StoryFn, storyContext: StoryContext): React.ReactElement => {
+    const actorKitParams = storyContext.parameters?.actorKit as
+      | ActorKitParameters<TMachine>["actorKit"]
+      | undefined;
+
+    // If no params provided, just render the story without any providers
+    if (!actorKitParams?.[actorType]) {
+      return <Story />;
+    }
+
+    // Create nested providers for each actor ID
+    const actorSnapshots = actorKitParams[actorType];
+
+    // Recursively nest providers
+    const createNestedProviders = (
+      actorIds: string[],
+      index: number,
+      children: React.ReactNode
+    ): React.ReactElement => {
+      if (index >= actorIds.length) {
+        return children as React.ReactElement;
+      }
+
+      const actorId = actorIds[index];
+      const snapshot = actorSnapshots[actorId];
+      const client = createActorKitMockClient<TMachine>({
+        initialSnapshot: snapshot,
+      });
+
+      return (
+        <context.ProviderFromClient client={client}>
+          {createNestedProviders(actorIds, index + 1, children)}
+        </context.ProviderFromClient>
+      );
+    };
+
+    return createNestedProviders(Object.keys(actorSnapshots), 0, <Story />);
+  };
+};

package/src/worker.ts

@@ -0,0 +1,2 @@
+export { createActorKitRouter } from "./createActorKitRouter";
+export { createMachineServer } from "./createMachineServer";