dash.storage

Save small JSON values for a pane. They are kept on Dotpane’s servers, so they are still there after a reload and in another browser.

dash.storage.get<T = unknown>(key: string): Promise<T | undefined>
dash.storage.set(key: string, value: unknown): Promise<void>
dash.storage.remove(key: string): Promise<void>
dash.storage.keys(): Promise<string[]>

Example

A notes pane. The text is loaded when the pane starts and saved two seconds after you stop typing, which keeps it well under the write limit.

const box = document.querySelector('textarea');
const saved = await dash.storage.get('note');
box.value = typeof saved === 'string' ? saved : '';

let timer;
box.addEventListener('input', () => {
  clearTimeout(timer);
  timer = setTimeout(() => {
    dash.storage.set('note', box.value).catch((err) => dash.log('not saved:', err.code));
  }, 2000);
});

Methods

Method	What it does
get(key)	Resolves with the saved value, or undefined when the key has none.
set(key, value)	Saves value under key and replaces any value saved there before. Resolves when the value is stored.
remove(key)	Deletes the key. Removing a key that does not exist is not an error.
keys()	Resolves with every key the pane has saved, in no particular order.

A key is a string of 1 to 128 characters with no NUL character.

Behaviour

• Storage belongs to each placed pane, not to the pane’s code. Two copies of the same pane on a canvas each have their own storage. Removing a pane from its canvas deletes its storage.
• In the editor’s preview, storage is kept in memory. It starts empty and is lost when the preview reloads. The size limits below still apply, so the preview fails where the canvas would.
• Values are saved as JSON, so you get back what JSON.parse(JSON.stringify(value)) gives: a Date comes back as a string, object fields that are undefined are dropped and NaN becomes null. A value with no JSON form at all, such as undefined or a function, is refused.
• Each call goes to Dotpane’s servers. Keep values you read often in a variable instead of calling get again.

Errors

Every method returns a promise that rejects with a DashError when the call fails. Read its code.

Code	Why
VALIDATION_FAILED	The key is not 1 to 128 characters, the value has no JSON form, or the value is larger than 64 KB as JSON.
LIMIT_REACHED	The write would leave the pane with more than 100 keys or more than 256 KB in total.
RATE_LIMITED	More than 60 writes in a minute from this pane, or more than 10 storage calls from it at once.
NOT_FOUND	The pane was removed from its canvas, for example in another tab, while it was still running.
UNAUTHENTICATED	You are no longer signed in.
INTERNAL	Something went wrong inside Dotpane.

Limits

• A key can be up to 128 characters.
• A value can be up to 64 KB, measured as JSON.
• A pane can keep up to 100 keys and 256 KB in total.
• A pane can make 60 writes a minute. Both set and remove count; get and keys do not.
• A pane can have 10 storage calls in flight at once.