@cloudflare/actors/dist/core/src/index.d.ts

An easier way to build with Cloudflare Durable Objects

import { DurableObject, WorkerEntrypoint } from "cloudflare:workers";
import { Storage } from "../../storage/src/index";
import { Alarms } from "../../alarms/src/index";
import { Persist } from "./persist";
export { Persist };
/**
 * Alias type for DurableObjectState to match the adopted Actor nomenclature.
 * This type represents the state of a Durable Object in Cloudflare Workers.
 */
export type ActorState = DurableObjectState;
/**
 * Type definition for a constructor of an actor.
 * @template T - The type of the actor
 */
export type ActorConstructor<T extends Actor<any> = Actor<any>> = new (state: ActorState, env: any) => T;
/**
 * Configuration options for an actor.
 */
export type ActorConfiguration = {
    locationHint?: DurableObjectLocationHint;
};
/**
 * Base abstract class for Workers that provides common functionality and structure.
 * @template T - The type of the environment object that will be available to the worker
 */
export declare abstract class Entrypoint<T> extends WorkerEntrypoint {
    protected env: T;
    protected ctx: ExecutionContext;
    abstract fetch(request: Request): Promise<Response>;
}
/**
 * Extended Actor class that provides additional functionality for Durable Objects.
 * This class adds SQL storage capabilities and browsing functionality to the base DurableObject.
 * @template E - The type of the environment object that will be available to the actor
 */
export declare abstract class Actor<E> extends DurableObject<E> {
    identifier?: string;
    storage: Storage;
    alarms: Alarms<this>;
    __studio(_: any): Promise<any>;
    /**
     * Hook that is called whenever a @Persist decorated property is stored in the database.
     * Override this method to listen to persistence events.
     * @param key The property key that was persisted
     * @param value The value that was persisted
     */
    protected onPersist(key: string, value: any): void;
    /**
     * Set the identifier for the actor as named by the client
     * @param id The identifier to set
     */
    setIdentifier(id: string): Promise<void>;
    /**
     * Static method to extract an ID from a request URL. Default response "default".
     * @param request - The incoming request
     * @returns The name string value defined by the client application to reference an instance
     */
    static nameFromRequest(request: Request): Promise<string | undefined>;
    /**
     * Static method to configure the actor.
     * @param options
     * @returns
     */
    static configuration: (request: Request) => ActorConfiguration;
    /**
     * Static method to get an actor instance by ID
     * @param id - The ID of the actor to get
     * @returns The actor instance
     */
    static get<T extends Actor<any>>(this: new (state: ActorState, env: any) => T, id: string): DurableObjectStub<T>;
    /**
     * Creates a new instance of Actor.
     * @param ctx - The DurableObjectState for this actor
     * @param env - The environment object containing bindings and configuration
     */
    constructor(ctx?: ActorState, env?: E);
    /**
     * Initializes the persisted properties table and loads any stored values.
     * This is called during construction to ensure properties are loaded before any code uses them.
     * @private
     */
    private _initializePersistedProperties;
    /**
     * Persists a property value to the Durable Object storage.
     * @param propertyKey The name of the property to persist
     * @param value The value to persist
     * @private
     */
    private _persistProperty;
    /**
     * Abstract method that must be implemented by derived classes to handle incoming requests.
     * @param request - The incoming request to handle
     * @returns A Promise that resolves to a Response
     */
    fetch(request: Request): Promise<Response>;
    /**
     * Lifecycle method that is called when the actor is initialized.
     * @protected
     */
    protected onInit(): Promise<void>;
    /**
     * Lifecycle method that is called when the actor is notified of an alarm.
     * @protected
     * @param alarmInfo - Information about the alarm that was triggered
     */
    protected onAlarm(alarmInfo?: AlarmInvocationInfo): Promise<void>;
    /**
     * Execute SQL queries against the Agent's database
     * @template T Type of the returned rows
     * @param strings SQL query template strings
     * @param values Values to be inserted into the query
     * @returns Array of query results
     */
    sql<T = Record<string, string | number | boolean | null>>(strings: TemplateStringsArray, ...values: (string | number | boolean | null)[]): T[];
    alarm(alarmInfo?: AlarmInvocationInfo): Promise<void>;
    /**
     * Tracks the last access time of an actor instance.
     * @param idString The identifier of the actor instance to track.
     */
    track(idString: string): Promise<void>;
    /**
     * Destroy the Actor by removing all actor library specific tables and state
     * that is associated with the actor.
     * @param _ - Optional configuration object
     * @param _.trackingInstance - Optional tracking instance name
     * @param _.forceEviction - When true, forces eviction of the actor from the cache
     * @throws Will throw an exception when forceEviction is true
     */
    destroy(_?: {
        forceEviction?: boolean;
    }): Promise<void>;
}
/**
 * Type definition for a request handler function.
 * @template E - The type of the environment object
 */
type RequestHandler<E> = (request: Request, env?: E, ctx?: ExecutionContext) => Promise<Response> | Response;
/**
 * Union type for possible handler inputs.
 * Can be either a class constructor or a request handler function.
 * @template E - The type of the environment object
 */
type HandlerInput<E> = {
    new (ctx: ExecutionContext, env: E): {
        fetch(request: Request): Promise<Response>;
    };
} | {
    new (state: DurableObjectState, env: E): DurableObject<E>;
} | RequestHandler<E>;
type HandlerOptions = {
    track?: {
        enabled: boolean;
    };
};
/**
 * Creates a handler for a Worker or Actor.
 * This function can handle both class-based and function-based handlers.
 * @template E - The type of the environment object
 * @param input - The handler input (class or function)
 * @param opts - Optional options for integration features
 * @returns An ExportedHandler that can be used as a Worker
 */
export declare function handler<E>(input: HandlerInput<E>, opts?: HandlerOptions): {
    fetch(request: Request, env: E, ctx: ExecutionContext): Promise<Response>;
};
export declare function getActor<T extends Actor<any>>(ActorClass: ActorConstructor<T>, id: string): DurableObjectStub<T>;
//# sourceMappingURL=index.d.ts.map