TaskStateStore

interface TaskStateStore { clear(): Promise<void>; delete(key: string): Promise<void>; get<T = unknown>(key: string): Promise<T | null>; set(key: string, value: NonNullable<JsonValue>, opts?: TaskStateStoreSetOpts): Promise<void>; }

Source: client.ts:143

Key/value state private to one task instance, kept across its retries within the same Dag run.

Reach it through TaskClient.taskStateStore:

CODE
const store = getClient().taskStateStore;
let jobId = await store.get<string>("job_id");
if (jobId == null) {
  jobId = await submit();
  await store.set("job_id", jobId, { retention: NEVER_EXPIRE });
}

Values are stored in the metadata database as-is; the [workers] state_store_backend that Python tasks can configure is not applied here.


Methods

clear(): Promise<void>

Delete every key stored for this task instance.

Returns

  • Promise<void>

delete(key: string): Promise<void>

Delete a key.

Resolves even when the key does not exist — the Execution API's delete route is idempotent and does not report a missing key as an error.

Parameters

  • key (string)

Returns

  • Promise<void>

Throws

  • TypeError when key is not a string.
  • RangeError when key is empty.

get<T = unknown>(key: string): Promise<T | null>

Look up a value.

Returns null when the key is missing. Throws on any other error.

The generic T lets callers narrow the return type when the shape is known.

Type Parameters

  • T = unknown

Parameters

  • key (string)

Returns

  • Promise<T | null>

Throws

  • TypeError when key is not a string.
  • RangeError when key is empty.

set( key: string, value: NonNullable<JsonValue>, opts?: TaskStateStoreSetOpts, ): Promise<void>

Store a value, replacing any existing value for the key.

opts.retention is how long to keep the key, in seconds.

Parameters

Returns

  • Promise<void>

Throws

  • TypeError when key is not a string, or value is null, undefined, NaN, or Infinity.
  • RangeError when key is empty; when retention is negative, NaN, or Infinity; when the deployment's [state_store] default_retention_days is invalid; or when the resolved expiry would overflow the wire timestamp (year 9999).