Blob Storage

Val Town comes with blob storage built-in. It allows for storing any data, like text, JSON, or images. You can access it via std/blob.

Blob storage comes in two flavors: scoped & global.

Scoped blob storage should be your default for new vals: it’s scoped to the val, so more secure and flexible. Scoped storage is available behind the https://esm.town/v/std/blob/main.ts export and is backed by Amazon S3.

Global blob storage was the norm before scoped blob storage was introduced: it’s available to any val in your account. It’s available at https://esm.town/v/std/blob and backed by Cloudflare R2.

Usage

The API for scoped blob storage and global storage is the same: to use these examples with global val storage, import from https://esm.town/v/std/blob instead.

Get JSON

Get JSON

import { blob } from "https://esm.town/v/std/blob/main.ts";

let blobDemo = await blob.getJSON("myKey");
console.log(blobDemo); // returns `undefined` if not found

Set JSON

Set JSON

import { blob } from "https://esm.town/v/std/blob/main.ts";

await blob.setJSON("myKey", { hello: "world" });

Set any content

Set any content

import { blob } from "https://esm.town/v/std/blob/main.ts";

await blob.set("myKey", "String, stream, etc");

Get any content

Get any content

import { blob } from "https://esm.town/v/std/blob/main.ts";

// Exposes a Response object with the same methods as a response from
// fetch: .json(), .text(), etc.
const text = await blob.get("myKey").then((response) => response.text());

List keys

List Keys

import { blob } from "https://esm.town/v/std/blob/main.ts";

let allKeys = await blob.list();
console.log(allKeys);

const appKeys = await blob.list("app_");
console.log(appKeys); // all keys that begin with `app_`

Delete by key

Delete

import { blob } from "https://esm.town/v/std/blob/main.ts";

await blob.delete("myKey");

Examples

• Counter
• RSS Notifications (saving the last run time)
• Picture: Save & Read

Error Handling

• blob.get can throw ValTownBlobNotFoundError
• Any method can throw ValTownBlobError for unexpected errors.

Utilities

Our Blob SDK also includes some utility functions to make working with blobs easier.

Copy

Copy

import { blob } from "https://esm.town/v/std/blob/main.ts";

await blob.copy("myKey", "myKeyCopy");

Move

Move

import { blob } from "https://esm.town/v/std/blob/main.ts";

await blob.move("myKey", "myKeyNew");

Blob Admin Panels

• Scoped
  • There’s a Blob Storage option in the sidebar of vals you own, that allows you to list, create, delete, and download blobs.
• Global
  • Blob Storage in Settings – built-into Val Town - list, download, delete blobs
  • Blob Admin – search, view, edit, upload blobs – built in a val – easy to customize in Val Town!

Lower-level API

We provide access to the lower-level getter and setters, which are useful if you are storing non-JSON or binary data, need to stream in your response or request data, or do anything else lower-level.

• async get(key: string): Retrieves a blob for a given key.
• async set(key: string, value: string | BodyInit): Sets the blob value for a given key. See BodyInit.

Limitations

• Blob-stored data counts towards your total Val Town storage – 10mb on the free plan and 1gb on pro. Check our pricing page to learn more.
• Keys for blobs can be up to 512 characters long.

📝 Edit docs