Val Town Blob Storage - https://docs.val.town/std/blob

Readme
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.
Comments
stevekrouse avatar

Can simplify the top comment like I mentioned on the other ones

I'm surprised that your JSDoc strings are on the object and not on the functions themselves. Does that show up when you reference them in another Val Editor?

Cool that you did the params and return types and throws. I don't know if all that data is necessary. Check it out and send over screenshots?

Would be neat to export all these methods as well

andreterron avatar

I'm surprised that your JSDoc strings are on the object and not on the functions themselves.

Yeah, if I add them to the function, they're not displayed when hovering on blob.setJSON.

Would be neat to export all these methods as well

Unless there's a way to "re-use" a JSDoc comment, we'd likely need to duplicate the JSDocs for that. I think it would be weird exporting the method AND a blob object. I could see it making sense using the default export, but then it would break the interface. And since there are some vals that use the unversioned blob import, I don't think it's worth it right now.

Cool that you did the params and return types and throws. [...] send over screenshots?

The Promise<void> returns looked empty, so I removed them. Otherwise, here's a screenshot:

image.png

stevekrouse avatar

Perfect! Ready to merge!

For the future (or now if you wanted to experiment) I'm wondering if we should show example usage in the jsdoc string as well. That could be super handy to have right at hand...