Readme
Blob Storage - Docs ↗
Val Town comes with blob storage built-in. It allows for storing any data: text, JSON, images. You can access it via std/blob.
Blob storage is scoped globally to your account. If you set a blob in one val, you can retrieve it by the same key in another val. It's backed by Cloudflare R2.
You may find this admin viewer helpful for viewing and editing your blobs.
Create valimport { blob } from "https://esm.town/v/std/blob";
let blobDemo = await blob.getJSON("myKey");
console.log(blobDemo); // returns `undefined` if not found
Create valimport { blob } from "https://esm.town/v/std/blob";
await blob.setJSON("myKey", { hello: "world" });
Create valimport { blob } from "https://esm.town/v/std/blob";
let allKeys = await blob.listKeys();
console.log(allKeys);
const appKeys = await blob.listKeys("app_");
console.log(appKeys); // all keys that begin with `app_`
- Counter
- RSS Notifications (saving the last run time)
- Picture: Save & Read
blob.getcan throwValTownBlobNotFoundError- Any method can throw
ValTownBlobErrorfor unexpected errors.
Our Blob SDK also includes some utility functions to make working with blobs easier.
Create valimport { blob } from "https://esm.town/v/std/blob";
await blob.copy("myKey", "myKeyCopy");
We do 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.
- 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.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
import { API_URL } from "https://esm.town/v/std/API_URL";
import { ValTownBlobError } from "https://esm.town/v/std/ValTownBlobError";
import { ValTownBlobNotFoundError } from "https://esm.town/v/std/ValTownBlobNotFoundError";
/**
* Provides functions for interacting with your account's blob storage.
* Blobs can store any data type (text, JSON, images, etc.) and allow
* retrieval across different vals using the same key.
* ([Docs ↗](https://docs.val.town/std/blob))
*/
export const blob = {
/**
* Gets the data of a blob with the given key.
*
* @param {string} key - The key of the blob to get.
* @returns {Promise<Response>} A promise that resolves with the blob data as a Response object.
* @throws {ValTownBlobNotFoundError} If the blob is not found.
* @throws {ValTownBlobError} If an error occurs while getting the blob data.
*/
get: get,
/**
* Sets the data of a blob with the given key.
*
* @param {string} key - The key of the blob to set.
* @param {BodyInit} value - The data to set for the blob.
* @throws {ValTownBlobError} If an error occurs while setting the blob data.
*/
set: set,
/**
* Copies the data of a blob from one key to another.
*
* @param {string} previous - The key of the blob to copy from.
* @param {string} next - The key of the blob to copy to.
*/
copy: copy,
/**
* Moves the data of a blob from one key to another by copying and then deleting the original.
*
* @param {string} previous - The key of the blob to move from.
* @param {string} next - The key of the blob to move to.
*/
move: move,
/**
* Lists blobs with an optional prefix filter.
*
* @param {string} [prefix] - The prefix to filter the blobs by.
* @returns {Promise<{ key: string; size: number; lastModified: string }[]>} A promise that resolves with an array of blob metadata.
*/
list: list,
/**
* Deletes a blob with the given key.
*
* @param {string} key - The key of the blob to delete.
* @throws {ValTownBlobError} If an error occurs while deleting the blob.
*/
delete: delete_,
/**
* Gets the JSON data of a blob with the given key.
*
* @param {string} key - The key of the blob to get.
* @returns {Promise<any | undefined>} A promise that resolves with the JSON data of the blob, or undefined if the blob is not found.
* @throws {ValTownBlobError} If an error occurs while getting the blob data.
*/
getJSON: getJSON,
/**
* Sets the JSON data of a blob with the given key.
*
* @param {string} key - The key of the blob to set.
* @param {any} value - The JSON data to set for the blob.
* @throws {ValTownBlobError} If an error occurs while setting the blob data.
*/
setJSON: setJSON,
};
async function list(prefix?: string): Promise<{ key: string; size: number; lastModified: string }[]> {
let querystring = prefix ? `?prefix=${encodeURIComponent(prefix)}` : "";
const res = await fetch(`${API_URL}/v1/blob${querystring}`, {
headers: {
Authorization: `Bearer ${Deno.env.get("valtown")}`,
},
});
if (!res.ok) {
const body = await res.text();
throw new ValTownBlobError(body ? body : "Error listing blobs");
}
return res.json();
}
async function delete_(key: string) {
const res = await fetch(`${API_URL}/v1/blob/${encodeURIComponent(key)}`, {
method: "DELETE",
headers: {
Authorization: `Bearer ${Deno.env.get("valtown")}`,
👆 This is a val. Vals are TypeScript snippets of code, written in the browser and run on our servers. Create scheduled functions, email yourself, and persist small pieces of data — all from the browser.
v12 was merged from the PR "Update JSDocs" by andreterron