store

Exposes namespaced Key-Value Stores you can access inside of your Jobs.

Only use this for small values - there’s a 256KB size limit per item.

Namespaces

• store.env to access and store data within the Environment
• store.job to access and store data within the Job
• store.run to access and store data within the Run

You will only be able to access Run-scoped data from inside the same Run when using store.run.

To share data across Runs you can use store.job:

client.defineJob({
  ...
  run: async (payload, io, ctx) => {
    // Run-scoped get - this will always return undefined
    await io.store.run.get("run-get", "counter")

    // Job-scoped get - this will only be undefined on the first run
    const counter = await io.store.job.get<number | undefined>("job-get", "counter")

    const currentCount = counter ?? 0
    const incrementedCounter = currentCount++

    // Run-scoped set - somewhat pointless as we don't access it again in this Run
    await io.store.run.set("run-set", "counter", incrementedCounter);

    // Job-scoped set
    await io.store.job.set("job-set", "counter", incrementedCounter);
  }
})

And to share data across Jobs you can use store.env instead:

client.defineJob({
  id: "job-1",
  ...
  run: async (payload, io, ctx) => {
    // store data in one job
    await io.store.env.set("cacheKey", "cross-run-shared-key", { foo: "bar" });
  }
})

client.defineJob({
  id: "job-2",
  ...
  run: async (payload, io, ctx) => {
    // access from a different job
    const value = await io.store.env.get<{ foo: string }>("cacheKey", "cross-run-shared-key");
  }
})

Methods

delete()

Deletes an item from the Key-Value Store.

cacheKey · string · required

Should be a stable and unique cache key inside the run(). See resumability for more information.

key · string · required

The key of the item to delete.

Returns

A Promise that resolves when the item has been deleted.

await client.store.env.delete("cacheKey", "key")

has()

Checks if an item exists in the Key-Value Store.

cacheKey · string · required

Should be a stable and unique cache key inside the run(). See resumability for more information.

key · string · required

The key of the item to check existence of.

Returns

A Promise that resolves to a boolean value indicating existence.

const exists = await client.store.env.has("cacheKey", "key")

get()

Retrieves an item from the Key-Value Store.

cacheKey · string · required

Should be a stable and unique cache key inside the run(). See resumability for more information.

key · string · required

The key of the item to retrieve.

Returns

A Promise that resolves to the stored value or undefined if missing.

const val = await client.store.env.get("cacheKey", "key")

set()

Stores an item in the Key-Value Store.

cacheKey · string · required

Should be a stable and unique cache key inside the run(). See resumability for more information.

key · string · required

The key of the item to store.

value · any · required

The serializable value to store.

const val = await client.store.env.set("cacheKey", "key", "value")

Returns

A Promise that resolves to the stored value.

Example

await io.store.env.set("cacheKey", "key", "foo")
await io.store.job.set("cacheKey", "key", "bar")
await io.store.run.set("cacheKey", "key", "baz")

await io.store.env.get("cacheKey", "key") // "foo"
await io.store.job.get("cacheKey", "key") // "bar"
await io.store.run.get("cacheKey", "key") // "baz"

await io.store.env.has("cacheKey", "key") // true
await io.store.job.has("cacheKey", "missing") // false
await io.store.run.has("cacheKey", "key") // true

// cleanup
await io.store.env.delete("cacheKey", "key")
await io.store.job.delete("cacheKey", "key")
await io.store.run.delete("cacheKey", "key")