durable-utils/do-sharding.d.ts

Utilities for Cloudflare Durable Objects and Workers, including SQL migrations, sharding and retry utilities, and more.

import { DurableObjectLocationHint, DurableObjectNamespace, DurableObjectStub, Rpc } from "@cloudflare/workers-types";
export interface StaticShardedDOOptions {
    /**
     * The number of shards to use for spreading out the load among all requests.
     * The number of shards will decide how many DOs will be used internally.
     *
     * WARNING: You should NEVER change this value after it has already been used.
     *          Changing this value will cause the DOs to be re-sharded and requests
     *          will be spread out differently, which can cause data loss or corruption.
     */
    numShards: number;
    /**
     * The number of concurrent subrequests to make to the DOs.
     * This value should be kept low to avoid hitting the Cloudflare subrequest limit.
     * The default value is 10.
     */
    concurrency?: number;
    /**
     * The group name for all the Durable Object shards created within this `StaticShardedDO` instance.
     * This allows you to use multiple groups of sharded DOs in the same Durable Object namespace.
     *
     * Different groups of sharded DOs will not interfere with each other, and will have their own Durable Objects.
     */
    shardGroupName?: string;
    /**
     * A function that returns a location hint for a specific shard.
     * The location hint is used to specify the region where the Durable Object should be placed.
     * If the function returns `undefined`, the Durable Object will be placed in the closest region.
     */
    shardLocationHintFn?: (shard: ShardId) => DurableObjectLocationHint | undefined;
    /**
     * The prefix name to use for the Durable Objects created.
     * This allows you to use multiple groups of sharded DOs in the same namespace.
     * @deprecated Use `shardGroupName` instead.
     */
    prefixName?: string;
}
/**
 * A unique identifier for each shard. Zero-based index.
 */
export type ShardId = number;
/**
 * The result of a single request to a shard using the `trySome/tryAll` methods.
 */
export type TryResult<R> = {
    ok: true;
    shard: ShardId;
    result: R;
} | {
    ok: false;
    shard: ShardId;
    error: unknown;
};
/**
 * The options to control the behavior of the `trySome` method.
 */
export type TryOptions = {
    /**
     * A function to select which shards to use for the requests.
     * @param shardId The shard ID to decide if it should be queried.
     * @returns `true` for shards that should be used, and `false` for shards that should be skipped.
     */
    filterFn: (shardId: ShardId) => boolean;
    /**
     * A function to determine if a failed request should be retried.
     * The arguments of the function are:
     * @param error the error thrown by the request
     * @param attempt the attempt number (value 2 means it's the first retry after the failed first request)
     * @param shard the shard ID the request was made to
     * @returns `true` if the request should be retried, `false` otherwise.
     */
    shouldRetry?: (error: unknown, attempt: number, shard: ShardId) => boolean;
};
/**
 * The options to control the behavior of the `tryOne` method.
 */
export type TryOneOptions = Omit<TryOptions, "filterFn">;
/**
 * The options to control the behavior of the `tryAll` method.
 */
export type TryAllOptions = Omit<TryOptions, "filterFn">;
/**
 * @deprecated Use `tryAll` instead.
 */
export type AllMaybeResult<R> = {
    results: Array<R | undefined>;
    errors: Array<unknown>;
    hasErrors: boolean;
};
/**
 * A utility class to interact with a fixed number of sharded Durable Objects.
 * This class will automatically hash the given key to determine the shard to use.
 */
export declare class StaticShardedDO<T extends Rpc.DurableObjectBranded | undefined> {
    #private;
    constructor(doNamespace: DurableObjectNamespace<T>, options: StaticShardedDOOptions);
    /**
     * The number of shards used to spread out the load. Immutable after creation.
     */
    get N(): number;
    /**
     * Execute a single request against the Durable Object responsible for the given partitionKey.
     * @param partitionKey The partition key is used to determine the shard.
     * @param doer The callback function to execute with the Durable Object stub for each shard.
     * @param options The options to control the execution like retries.
     * @returns An array of the results from the given `doer` callback function for each shard,
     *          Each item in the array will be a `TryResult` object with the `ok` property indicating success or failure.
     */
    tryOne<R>(partitionKey: string, doer: (doStub: DurableObjectStub<T>, shard: ShardId) => Promise<R>, options?: TryOneOptions): Promise<TryResult<R>>;
    /**
     * Execute a single request against the Durable Object responsible for the given partitionKey.
     * @param partitionKey The partition key is used to determine the shard.
     * @param doer The callback function to execute with the Durable Object stub for the chosen shard.
     * @param options The options to control the execution like retries.
     * @returns The result of the given `doer` callback function. If `doer()` throws the error is propagated.
     */
    one<R>(partitionKey: string, doer: (doStub: DurableObjectStub<T>) => Promise<R>, options?: TryOneOptions): Promise<R>;
    /**
     * Execute a request to the shards selected by the `options.filterFn` callback, concurrently.
     * @param doer The callback function to execute with the Durable Object stub for each shard.
     * @param options The options to control the execution like retries and filtering of shards.
     * @returns An array of the results from the given `doer` callback function for each shard,
     *          Each item in the array will be a `TryResult` object with the `ok` property indicating success or failure.
     *          Only shards that pass the `options.filterFn` will be returned.
     */
    trySome<R>(doer: (doStub: DurableObjectStub<T>, shard: ShardId) => Promise<R>, options: TryOptions): Promise<Array<TryResult<R>>>;
    /**
     * Execute a request to the shards selected by the `options.filterFn` callback, concurrently.
     * @param doer The callback function to execute with the Durable Object stub for each shard.
     * @param options The options to control the execution like retries and filtering of shards.
     * @returns An array of results from the given `doer` callback function for each filtered shard.
     *          Only shards that pass the `options.filterFn` will be returned.
     *          In case of an error, the function will throw the error immediately.
     */
    some<R>(doer: (doStub: DurableObjectStub<T>, shard: ShardId) => Promise<R>, options: TryOptions): Promise<Array<R>>;
    /**
     * Execute a request to each of the shards, concurrently.
     * @param doer The callback function to execute with the Durable Object stub for each shard.
     * @param options The options to control the execution like retries.
     * @returns An array of the results from the given `doer` callback function for each shard,
     *          Each item in the array will be a `TryResult` object with the `ok` property indicating success or failure.
     */
    tryAll<R>(doer: (doStub: DurableObjectStub<T>, shard: ShardId) => Promise<R>, options?: TryAllOptions): Promise<Array<TryResult<R>>>;
    /**
     * Execute a request to each of the shards, concurrently.
     * @param doer The callback function to execute with the Durable Object stub for each shard.
     * @param options The options to control the execution like retries.
     * @returns An array of results from the given `doer` callback function for each shard.
     *          In case of an error, the function will throw the error immediately.
     */
    all<R>(doer: (doStub: DurableObjectStub<T>, shard: ShardId) => Promise<R>, options?: TryAllOptions): Promise<Array<R>>;
    /**
     * Execute a request to each of the shards, concurrently.
     * @deprecated Use `all` or `tryAll` instead.
     * @param doer The callback function to execute with the Durable Object stub for each shard.
     * @returns An async generator of results from the given `doer` callback function for each shard.
     *          In case of an error, the function will throw the error immediately.
     */
    genAll<R>(doer: (doStub: DurableObjectStub<T>, shard: ShardId) => Promise<R>): AsyncGenerator<R>;
    /**
     * Execute a request to each of the shards, concurrently.
     * @deprecated Use `tryAll` instead.
     * @param doer The callback function to execute with the Durable Object stub for each shard.
     * @returns An array of results from the given `doer` callback function for each shard,
     *          and an array of errors for each shard that failed.
     *          Items in the results array will be `undefined` if the shard failed, and similarly for the errors array.
     */
    allMaybe<R>(doer: (doStub: DurableObjectStub<T>, shard: ShardId) => Promise<R>): Promise<AllMaybeResult<R>>;
}
/**
 * @deprecated Use `StaticShardedDO` instead.
 */
export declare const FixedShardedDO: typeof StaticShardedDO;