@edgeone/pages-blob

Blob storage SDK for EdgeOne Pages Functions, providing persistent key-value storage across deployments.

Installation

npm install @edgeone/pages-blob

Usage

Inside Pages Functions (automatic authentication)

import { getStore } from "@edgeone/pages-blob";

const store = getStore("my-store");

// Write
await store.set("key", "value");
await store.setJSON("config", { theme: "dark" });

// Read
const text = await store.get("key");
const json = await store.get("config", { type: "json" });

// Delete
await store.delete("key");

// List
const { blobs } = await store.list({ prefix: "users/" });

External access (API Token mode)

When calling from outside Pages Functions, you must supply both token and projectId:

const store = getStore({
  name: "my-store",
  projectId: "pages-urtsvuwmfvli", // required
  token: "c+KH5...", // required
});

Omitting projectId throws MissingProjectIdError.

Strong consistency (read-after-write)

By default reads use eventual consistency (CDN-cached, lower latency). To guarantee read-after-write consistency, use "strong":

// Store-level default — all reads use strong consistency
const store = getStore({ name: "my-store", consistency: "strong" });

// Per-call override
await store.get("key", { consistency: "strong" });
await store.list({ consistency: "strong" });

"eventual" (the default) has lower latency; "strong" guarantees the freshest value at the cost of bypassing the cache layer.

List all stores

import { listStores } from "@edgeone/pages-blob";

// Inside Pages Functions
const { stores } = await listStores();

// External access (token mode) - both fields required
const { stores } = await listStores({
  projectId: "pages-urtsvuwmfvli",
  token: "c+KH5...",
});

API

getStore(name | options)

Get a Store instance.

| Parameter | Type | Description | | --------------------- | ------------------------ | ----------------------------------------------- | | name | string | Store name | | options.name | string | Store name | | options.projectId | string | Project ID (required for external access) | | options.token | string | Access token (required for external access) | | options.consistency | "eventual" \| "strong" | Default read consistency (default "eventual") |

store.set(key, value, options?)

Write a Blob. value supports string | ArrayBuffer | Blob | ReadableStream.

• options.onlyIfNew: only write if the key does not already exist

store.setJSON(key, value, options?)

Write JSON (serialized automatically). Accepts the same options as store.set.

store.get(key, options?)

Read a Blob. Returns null if it does not exist.

• options.type: "text" (default) | "json" | "arrayBuffer" | "blob" | "stream"
• options.consistency: "eventual" | "strong" (overrides Store-level default)

store.getWithHeaders(key, options?)

Read a blob along with all response headers. Returns null if the key does not exist.

Returns: { body: string, headers: Record<string, string> }

• options.consistency: "eventual" | "strong"

store.delete(key)

Delete a Blob.

store.list(options?)

List Blobs. Automatically aggregates all pages by default.

• options.prefix: prefix filter
• options.directories: group by directory
• options.paginate: set to false for manual pagination
• options.cursor: resume from a previous pagination cursor
• options.consistency: "eventual" | "strong"

Returns: { blobs: Array<{ key, etag }>, directories: string[] }

listStores(options?)

List all Stores under the project.

• options.projectId: Project ID (required for external access)
• options.token: Access token (required for external access)
• options.consistency: "eventual" | "strong"

Returns: { stores: Array<{ name: string }> }