actor-kit/dist/worker.d.ts

Actor Kit is a library for running state machines in Cloudflare Workers, leveraging XState for robust state management. It provides a framework for managing the logic, lifecycle, persistence, synchronization, and access control of actors in a distributed

import { ExecutionContext as ExecutionContext$1 } from '@cloudflare/workers-types';
import { DurableObject } from 'cloudflare:workers';
import { StateMachine, AnyStateMachine, SnapshotFrom, AnyEventObject } from 'xstate';
import { z } from 'zod';

declare const RequestInfoSchema: z.ZodObject<{
    longitude: z.ZodString;
    latitude: z.ZodString;
    continent: z.ZodString;
    country: z.ZodString;
    city: z.ZodString;
    timezone: z.ZodString;
    postalCode: z.ZodString;
    region: z.ZodString;
    regionCode: z.ZodString;
    metroCode: z.ZodString;
    botManagement: z.ZodObject<{
        corporateProxy: z.ZodBoolean;
        verifiedBot: z.ZodBoolean;
        jsDetection: z.ZodObject<{
            passed: z.ZodBoolean;
        }, "strip", z.ZodTypeAny, {
            passed: boolean;
        }, {
            passed: boolean;
        }>;
        staticResource: z.ZodBoolean;
        detectionIds: z.ZodRecord<z.ZodString, z.ZodAny>;
        score: z.ZodNumber;
    }, "strip", z.ZodTypeAny, {
        corporateProxy: boolean;
        verifiedBot: boolean;
        jsDetection: {
            passed: boolean;
        };
        staticResource: boolean;
        detectionIds: Record<string, any>;
        score: number;
    }, {
        corporateProxy: boolean;
        verifiedBot: boolean;
        jsDetection: {
            passed: boolean;
        };
        staticResource: boolean;
        detectionIds: Record<string, any>;
        score: number;
    }>;
}, "strip", z.ZodTypeAny, {
    longitude: string;
    latitude: string;
    continent: string;
    country: string;
    city: string;
    timezone: string;
    postalCode: string;
    region: string;
    regionCode: string;
    metroCode: string;
    botManagement: {
        corporateProxy: boolean;
        verifiedBot: boolean;
        jsDetection: {
            passed: boolean;
        };
        staticResource: boolean;
        detectionIds: Record<string, any>;
        score: number;
    };
}, {
    longitude: string;
    latitude: string;
    continent: string;
    country: string;
    city: string;
    timezone: string;
    postalCode: string;
    region: string;
    regionCode: string;
    metroCode: string;
    botManagement: {
        corporateProxy: boolean;
        verifiedBot: boolean;
        jsDetection: {
            passed: boolean;
        };
        staticResource: boolean;
        detectionIds: Record<string, any>;
        score: number;
    };
}>;
declare const CallerSchema: z.ZodObject<{
    id: z.ZodString;
    type: z.ZodEnum<["client", "system", "service"]>;
}, "strip", z.ZodTypeAny, {
    id: string;
    type: "system" | "client" | "service";
}, {
    id: string;
    type: "system" | "client" | "service";
}>;
declare const SystemEventSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
    type: z.ZodLiteral<"INITIALIZE">;
    caller: z.ZodObject<{
        type: z.ZodLiteral<"system">;
        id: z.ZodString;
    }, "strip", z.ZodTypeAny, {
        id: string;
        type: "system";
    }, {
        id: string;
        type: "system";
    }>;
}, "strip", z.ZodTypeAny, {
    type: "INITIALIZE";
    caller: {
        id: string;
        type: "system";
    };
}, {
    type: "INITIALIZE";
    caller: {
        id: string;
        type: "system";
    };
}>, z.ZodObject<{
    type: z.ZodLiteral<"CONNECT">;
    caller: z.ZodObject<{
        type: z.ZodLiteral<"system">;
        id: z.ZodString;
    }, "strip", z.ZodTypeAny, {
        id: string;
        type: "system";
    }, {
        id: string;
        type: "system";
    }>;
    connectingCaller: z.ZodObject<{
        id: z.ZodString;
        type: z.ZodEnum<["client", "system", "service"]>;
    }, "strip", z.ZodTypeAny, {
        id: string;
        type: "system" | "client" | "service";
    }, {
        id: string;
        type: "system" | "client" | "service";
    }>;
}, "strip", z.ZodTypeAny, {
    type: "CONNECT";
    caller: {
        id: string;
        type: "system";
    };
    connectingCaller: {
        id: string;
        type: "system" | "client" | "service";
    };
}, {
    type: "CONNECT";
    caller: {
        id: string;
        type: "system";
    };
    connectingCaller: {
        id: string;
        type: "system" | "client" | "service";
    };
}>, z.ZodObject<{
    type: z.ZodLiteral<"DISCONNECT">;
    caller: z.ZodObject<{
        type: z.ZodLiteral<"system">;
        id: z.ZodString;
    }, "strip", z.ZodTypeAny, {
        id: string;
        type: "system";
    }, {
        id: string;
        type: "system";
    }>;
    disconnectingCaller: z.ZodObject<{
        id: z.ZodString;
        type: z.ZodEnum<["client", "system", "service"]>;
    }, "strip", z.ZodTypeAny, {
        id: string;
        type: "system" | "client" | "service";
    }, {
        id: string;
        type: "system" | "client" | "service";
    }>;
}, "strip", z.ZodTypeAny, {
    type: "DISCONNECT";
    caller: {
        id: string;
        type: "system";
    };
    disconnectingCaller: {
        id: string;
        type: "system" | "client" | "service";
    };
}, {
    type: "DISCONNECT";
    caller: {
        id: string;
        type: "system";
    };
    disconnectingCaller: {
        id: string;
        type: "system" | "client" | "service";
    };
}>, z.ZodObject<{
    type: z.ZodLiteral<"RESUME">;
    caller: z.ZodObject<{
        type: z.ZodLiteral<"system">;
        id: z.ZodString;
    }, "strip", z.ZodTypeAny, {
        id: string;
        type: "system";
    }, {
        id: string;
        type: "system";
    }>;
}, "strip", z.ZodTypeAny, {
    type: "RESUME";
    caller: {
        id: string;
        type: "system";
    };
}, {
    type: "RESUME";
    caller: {
        id: string;
        type: "system";
    };
}>, z.ZodObject<{
    type: z.ZodLiteral<"MIGRATE">;
    caller: z.ZodObject<{
        type: z.ZodLiteral<"system">;
        id: z.ZodString;
    }, "strip", z.ZodTypeAny, {
        id: string;
        type: "system";
    }, {
        id: string;
        type: "system";
    }>;
    operations: z.ZodArray<z.ZodAny, "many">;
}, "strip", z.ZodTypeAny, {
    type: "MIGRATE";
    caller: {
        id: string;
        type: "system";
    };
    operations: any[];
}, {
    type: "MIGRATE";
    caller: {
        id: string;
        type: "system";
    };
    operations: any[];
}>]>;

type EnvWithDurableObjects = {
    ACTOR_KIT_SECRET: string;
    [key: string]: DurableObjectNamespace<ActorServer<any>> | unknown;
};
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): {
        checksum: string;
        snapshot: CallerSnapshotFrom<TMachine>;
    };
}
type ActorServer<TMachine extends AnyActorKitStateMachine> = DurableObject & ActorServerMethods<TMachine>;
type Caller = z.infer<typeof CallerSchema>;
type RequestInfo = z.infer<typeof RequestInfoSchema>;
type CallerType = "client" | "system" | "service";
type EventObject = {
    type: string;
};
type BaseActorKitContext<TPublicProps extends {
    [key: string]: unknown;
}, TPrivateProps extends {
    [key: string]: unknown;
}> = {
    public: TPublicProps;
    private: Record<string, TPrivateProps>;
};
type ActorKitStateMachine<TEvent extends BaseActorKitEvent & EventObject, TInput extends {
    id: string;
    caller: Caller;
    storage: DurableObjectStorage;
}, TContext extends BaseActorKitContext<any, any> & {
    [key: string]: unknown;
}> = StateMachine<TContext, TEvent, any, any, any, any, any, any, any, TInput, any, any, any, any>;
type BaseActorKitInput = {
    id: string;
    caller: Caller;
    env: EnvWithDurableObjects;
    storage: DurableObjectStorage;
};
type WithActorKitInput<T extends {
    [key: string]: unknown;
}> = T & BaseActorKitInput;
type AnyActorKitStateMachine = ActorKitStateMachine<any, any, any>;
type AnyActorKitEvent = (WithActorKitEvent<AnyEventObject, "client"> | WithActorKitEvent<AnyEventObject, "service"> | ActorKitSystemEvent) & BaseActorKitEvent;
type AnyActorKitInput = WithActorKitInput<{
    [key: string]: unknown;
}> & {
    storage: DurableObjectStorage;
};
type AnyActorKitContext = {
    public: {
        [key: string]: unknown;
    };
    private: Record<string, {
        [key: string]: unknown;
    }>;
};
type BaseActorKitStateMachine = ActorKitStateMachine<AnyActorKitEvent, AnyActorKitInput, AnyActorKitContext>;
type MachineServerOptions = {
    persisted?: boolean;
};
interface BaseActorKitEvent {
    caller: Caller;
    storage: DurableObjectStorage;
    requestInfo?: RequestInfo;
    env: EnvWithDurableObjects;
}
type ActorKitSystemEvent = z.infer<typeof SystemEventSchema>;
type WithActorKitEvent<T extends {
    type: string;
}, C extends CallerType> = T & BaseActorKitEvent & {
    caller: {
        type: C;
    };
};
type WithActorKitContext<TExtraProps extends {
    [key: string]: unknown;
}, TPrivateProps extends {
    [key: string]: unknown;
}, TPublicProps extends {
    [key: string]: unknown;
}> = TExtraProps & {
    public: TPublicProps;
    private: Record<string, TPrivateProps>;
};
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;
};
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"> ? E : never : never;
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"> ? E : never : never;
type ScreamingSnakeToKebab<S extends string> = S extends `${infer T}_${infer U}` ? `${Lowercase<T>}-${ScreamingSnakeToKebab<U>}` : Lowercase<S>;

declare const createActorKitRouter: <Env extends EnvWithDurableObjects>(routes: Array<ScreamingSnakeToKebab<Extract<keyof Env, string>>>) => (request: Request, env: Env, ctx: ExecutionContext$1) => Promise<Response>;

declare const createMachineServer: <TClientEvent extends AnyEventObject, TServiceEvent extends AnyEventObject, TInputSchema extends z.ZodObject<z.ZodRawShape>, TMachine extends ActorKitStateMachine<(WithActorKitEvent<TClientEvent, "client"> | WithActorKitEvent<TServiceEvent, "service"> | ActorKitSystemEvent) & {
    storage: DurableObjectStorage;
    env: TEnv;
}, z.infer<TInputSchema> & {
    id: string;
    caller: Caller;
    storage: DurableObjectStorage;
}, WithActorKitContext<any, any, any>>, TEnv extends {
    ACTOR_KIT_SECRET: string;
}>({ machine, schemas, options, }: {
    machine: TMachine;
    schemas: {
        clientEvent: z.ZodSchema<TClientEvent>;
        serviceEvent: z.ZodSchema<TServiceEvent>;
        inputProps: TInputSchema;
    };
    options?: MachineServerOptions;
}) => new (state: DurableObjectState, env: TEnv, ctx: ExecutionContext) => ActorServer<TMachine>;

export { createActorKitRouter, createMachineServer };