State storage

On this page

State that outlives one call, or crosses worker processes.

class BoundStorage

source

export class BoundStorage

Methods

method put

source

put(state: Uint8Array): Promise<void>

method collect

source

collect(): Promise<Uint8Array[]>

method workerScan

source

workerScan(): Promise<Array<[number, Uint8Array]>>

method queuePush

source

queuePush(items: Uint8Array[]): Promise<number>

method queuePop

source

queuePop(): Promise<Uint8Array | null>

method queueClear

source

queueClear(): Promise<number>

method stateGet

source

stateGet(ns: Uint8Array, key: Uint8Array): Promise<Uint8Array | null>

method statePut

source

statePut(ns: Uint8Array, key: Uint8Array, value: Uint8Array): Promise<void>

method stateAppend

source

stateAppend(ns: Uint8Array, key: Uint8Array, item: Uint8Array): Promise<number>

method stateLogScan

source

stateLogScan(
  ns: Uint8Array,
  key: Uint8Array,
  afterId: number = -1,
  limit: number | null = null,
): Promise<Array<[number, Uint8Array]>>

method executionClear

source

executionClear(): Promise<number>

type FetchLike

source

export type FetchLike = (
input: string,
init?: { method?: string; headers?: Record<string, string>; body?: string },
) => Promise<Response>;

Description

Minimal fetch signature satisfied by both the global fetch and a Cloudflare service-binding Fetcher (env.<BINDING>).

const functionStorage

source

const storage: FunctionStorage

Description

Default FunctionStorage instance. Backend is selected via env on first access.

interface FunctionStorage

source

export interface FunctionStorage

Fields

workerPut(executionId: Uint8Array, workerId: number, state: Uint8Array): Promise<void>

workerCollect(executionId: Uint8Array): Promise<Uint8Array[]>

workerScan(executionId: Uint8Array): Promise<Array<[number, Uint8Array]>>

queuePush(executionId: Uint8Array, items: Uint8Array[]): Promise<number>

queuePop(executionId: Uint8Array): Promise<Uint8Array | null>

queueClear(executionId: Uint8Array): Promise<number>

stateGet(scopeId: Uint8Array, ns: Uint8Array, key: Uint8Array): Promise<Uint8Array | null>

statePut(scopeId: Uint8Array, ns: Uint8Array, key: Uint8Array, value: Uint8Array): Promise<void>

stateAppend(scopeId: Uint8Array, ns: Uint8Array, key: Uint8Array, item: Uint8Array): Promise<number>

stateLogScan( scopeId: Uint8Array, ns: Uint8Array, key: Uint8Array, afterId?: number, limit?: number | null, ): Promise<Array<[number, Uint8Array]>>

executionClear(scopeId: Uint8Array): Promise<number>

Wipe all state + log rows for a scope across every namespace.

close(): Promise<void> | voidoptional

Optional cleanup hook. Implementations holding a connection should release it here.

class FunctionStorageCfDo

source

export class FunctionStorageCfDo implements FunctionStorage

Methods

method forShard

source

forShard(shardKey: string): FunctionStorageCfDo

Return a view of this backend pinned to one shard key, so callers can route per logical ATTACH. Shares the URL/token; only the shard key differs.

method workerPut

source

async workerPut(executionId: Uint8Array, workerId: number, state: Uint8Array): Promise<void>

method workerCollect

source

async workerCollect(executionId: Uint8Array): Promise<Uint8Array[]>

method workerScan

source

async workerScan(executionId: Uint8Array): Promise<Array<[number, Uint8Array]>>

method queuePush

source

async queuePush(executionId: Uint8Array, items: Uint8Array[]): Promise<number>

method queuePop

source

async queuePop(executionId: Uint8Array): Promise<Uint8Array | null>

method queueClear

source

async queueClear(executionId: Uint8Array): Promise<number>

method stateGet

source

async stateGet(scopeId: Uint8Array, ns: Uint8Array, key: Uint8Array): Promise<Uint8Array | null>

method statePut

source

async statePut(scopeId: Uint8Array, ns: Uint8Array, key: Uint8Array, value: Uint8Array): Promise<void>

method stateAppend

source

async stateAppend(scopeId: Uint8Array, ns: Uint8Array, key: Uint8Array, item: Uint8Array): Promise<number>

method stateLogScan

source

async stateLogScan(
  scopeId: Uint8Array,
  ns: Uint8Array,
  key: Uint8Array,
  afterId: number = -1,
  limit: number | null = null,
): Promise<Array<[number, Uint8Array]>>

method executionClear

source

async executionClear(scopeId: Uint8Array): Promise<number>

Wipe all state + log rows for a scope across every namespace.

class FunctionStorageSqlite

source

export class FunctionStorageSqlite implements FunctionStorage

Properties

property dbPath

source

readonly dbPath: string;

Methods

method close

source

close(): void

Optional cleanup hook. Implementations holding a connection should release it here.

method stateGet

source

async stateGet(scopeId: Uint8Array, ns: Uint8Array, key: Uint8Array): Promise<Uint8Array | null>

method statePut

source

async statePut(scopeId: Uint8Array, ns: Uint8Array, key: Uint8Array, value: Uint8Array): Promise<void>

method stateAppend

source

async stateAppend(scopeId: Uint8Array, ns: Uint8Array, key: Uint8Array, item: Uint8Array): Promise<number>

method stateLogScan

source

async stateLogScan(
  scopeId: Uint8Array,
  ns: Uint8Array,
  key: Uint8Array,
  afterId: number = -1,
  limit: number | null = null,
): Promise<Array<[number, Uint8Array]>>

method executionClear

source

async executionClear(scopeId: Uint8Array): Promise<number>

Wipe all state + log rows for a scope across every namespace.

method workerPut

source

async workerPut(
  executionId: Uint8Array,
  workerId: number,
  state: Uint8Array
): Promise<void>

method workerCollect

source

async workerCollect(executionId: Uint8Array): Promise<Uint8Array[]>

method workerScan

source

async workerScan(executionId: Uint8Array): Promise<Array<[number, Uint8Array]>>

method queuePush

source

async queuePush(executionId: Uint8Array, items: Uint8Array[]): Promise<number>

method queuePop

source

async queuePop(executionId: Uint8Array): Promise<Uint8Array | null>

method queueClear

source

async queueClear(executionId: Uint8Array): Promise<number>

function resolveStorageFromEnv

source

export function resolveStorageFromEnv(): FunctionStorage

Description

Resolve the FunctionStorage backend from environment variables.

Mirrors vgi-python’s _resolve_storage in vgi/function.py.

VGI_WORKER_SHARED_STORAGE selects the backend (default: sqlite):

• memory — FunctionStorageSqlite at :memory:. Process-local with no cross-process coordination — single-process deployments only. Ignores VGI_WORKER_SQLITE_PATH.
• sqlite — FunctionStorageSqlite. Honors VGI_WORKER_SQLITE_PATH (including :memory:).
• cloudflare-do — FunctionStorageCfDo. Requires VGI_CF_DO_URL; optional VGI_CF_DO_TOKEN for bearer auth.

function setStorage

source

export function setStorage(impl: FunctionStorage): void

Description

Override the default backend used by the storage singleton. Call once at worker startup to inject a pre-built backend that env-driven selection can’t construct — notably a FunctionStorageCfDo wired to a Cloudflare service-binding Fetcher (the binding lives on env, not process.env, and a same-zone public-URL fetch is rejected with CF error 1042). Takes precedence over VGI_WORKER_SHARED_STORAGE.

class UnknownInvocationError

source

export class UnknownInvocationError extends Error