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

_Lightweight Libraries for Backends_

import { AnyActorDefinition, Registry } from '@rivetkit/core';
import { ActorConn, ActorHandle, Client, ExtractActorsFromRegistry } from '@rivetkit/core/client';
import { Derived, Store, Updater } from '@tanstack/store';
export 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;
    /**
     * Whether the actor is enabled.
     */
    isConnected?: boolean;
    /**
     * Whether the actor is currently connecting, indicating that a connection attempt is in progress.
     */
    isConnecting?: boolean;
    /**
     * Whether there was an error connecting to the actor.
     */
    isError?: boolean;
    /**
     * 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.
 */
export 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;
}
export 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;
}>;
export type AnyActorOptions = ActorOptions<AnyActorRegistry, any>;
export interface CreateRivetKitOptions<Registry extends AnyActorRegistry> {
    hashFunction?: (opts: ActorOptions<Registry, any>) => string;
}
export declare function createRivetKit<Registry extends AnyActorRegistry, Actors extends ExtractActorsFromRegistry<Registry>, ActorNames extends keyof Actors>(client: Client<Registry>, opts?: CreateRivetKitOptions<Registry>): {
    getOrCreateActor: <ActorName extends ActorNames>(opts: ActorOptions<Registry, ActorName>) => {
        state: ActorsStateDerived<Registry, ActorName>;
        key: string;
        mount: () => void;
        setState: (set: Updater<ActorStateReference<Actors>>) => void;
        create: () => void;
        addEventListener?: (event: string, handler: (...args: any[]) => void) => void;
    };
    store: Store<InternalRivetKitStore<Registry, Actors>, (cb: InternalRivetKitStore<Registry, Actors>) => InternalRivetKitStore<Registry, Actors>>;
};
export {};