@rivetkit/framework-base/dist/mod.d.mts

Base framework utilities for RivetKit client integrations

import { Derived, Store } from '@tanstack/store';
import { Registry, AnyActorDefinition } from 'rivetkit';
import { ExtractActorsFromRegistry, ActorHandle, ActorConn, ActorConnStatus, Client } from 'rivetkit/client';
export { ActorConnStatus } from 'rivetkit/client';

type AnyActorRegistry = Registry<any>;

interface ActorStateReference<AD extends AnyActorDefinition> {
    /**
     * The unique identifier for the actor.
     * This is a hash generated from the actor's options.
     * It is used to identify the actor instance in the store.
     * @internal
     */
    hash: string;
    /**
     * The state of the actor, derived from the store.
     * This includes the actor's connection and handle.
     */
    handle: ActorHandle<AD> | null;
    /**
     * The connection to the actor.
     * This is used to communicate with the actor in realtime.
     */
    connection: ActorConn<AD> | null;
    /**
     * The connection status of the actor.
     */
    connStatus: ActorConnStatus;
    /**
     * The error that occurred while trying to connect to the actor, if any.
     */
    error: Error | null;
    /**
     * Options for the actor, including its name, key, parameters, and whether it is enabled.
     */
    opts: {
        name: keyof AD;
        /**
         * Unique key for the actor instance.
         * This can be a string or an array of strings to create multiple instances.
         * @example "abc" or ["abc", "def"]
         */
        key: string | string[];
        /**
         * Parameters for the actor.
         * These are additional options that can be passed to the actor.
         */
        params?: Record<string, string>;
        /** Region to create the actor in if it doesn't exist. */
        createInRegion?: string;
        /** Input data to pass to the actor. */
        createWithInput?: unknown;
        /**
         * Whether the actor is enabled.
         * Defaults to true.
         */
        enabled?: boolean;
    };
}
interface InternalRivetKitStore<Registry extends AnyActorRegistry, Actors extends ExtractActorsFromRegistry<Registry>> {
    actors: Record<string, ActorStateReference<Actors>>;
}
/**
 * Options for configuring a actor in RivetKit.
 */
interface ActorOptions<Registry extends AnyActorRegistry, ActorName extends keyof ExtractActorsFromRegistry<Registry>> {
    /**
     * Typesafe name of the actor.
     * This should match the actor's name in the app's actor definitions.
     * @example "chatRoom"
     */
    name: ActorName;
    /**
     * Unique key for the actor instance.
     * This can be a string or an array of strings to create multiple instances.
     * @example "abc" or ["abc", "def"]
     */
    key: string | string[];
    /**
     * Parameters for the actor.
     */
    params?: Registry[ExtractActorsFromRegistry<Registry>]["params"];
    /** Region to create the actor in if it doesn't exist. */
    createInRegion?: string;
    /** Input data to pass to the actor. */
    createWithInput?: unknown;
    /**
     * Whether the actor is enabled.
     * Defaults to true.
     */
    enabled?: boolean;
}
type ActorsStateDerived<Registry extends AnyActorRegistry, WorkerName extends keyof ExtractActorsFromRegistry<Registry>> = Derived<Omit<InternalRivetKitStore<Registry, ExtractActorsFromRegistry<Registry>>["actors"][string], "handle" | "connection"> & {
    handle: ActorHandle<ExtractActorsFromRegistry<Registry>[WorkerName]> | null;
    connection: ActorConn<ExtractActorsFromRegistry<Registry>[WorkerName]> | null;
    /** @deprecated Use `connStatus === "connected"` instead */
    isConnected: boolean;
}>;
type AnyActorOptions = ActorOptions<AnyActorRegistry, any>;
interface CreateRivetKitOptions<Registry extends AnyActorRegistry> {
    hashFunction?: (opts: ActorOptions<Registry, any>) => string;
}
declare function createRivetKit<Registry extends AnyActorRegistry, Actors extends ExtractActorsFromRegistry<Registry>>(client: Client<Registry>, createOpts?: CreateRivetKitOptions<Registry>): {
    getOrCreateActor: <ActorName extends keyof Actors>(actorOpts: ActorOptions<Registry, ActorName>) => {
        state: ActorsStateDerived<Registry, ActorName>;
        key: string;
        mount: () => () => void;
        create: () => void;
        refCount: number;
        cleanupTimeout: ReturnType<typeof setTimeout> | null;
    } | {
        mount: () => () => void;
        state: ActorsStateDerived<Registry, ActorName>;
        key: string;
    };
    store: Store<InternalRivetKitStore<Registry, Actors>, (cb: InternalRivetKitStore<Registry, Actors>) => InternalRivetKitStore<Registry, Actors>>;
};

export { type ActorOptions, type ActorsStateDerived, type AnyActorOptions, type AnyActorRegistry, type CreateRivetKitOptions, createRivetKit };