Storage collection

Methods

set(...)

(key: string, value: title="Json">Json) => Promise<void>

🔒 Requires scope: boards:write

🚦 Rate limit: Level 1

The set() method saves the value for the specified key in the Collection.

It accepts key and value parameters and returns a Promise.

The key parameter specifies the key for the data element in the collection.
It is used to retrieve, set, or remove data, and should always be a string.

The value parameter specifies the data to assign to the specified key in the collection.
It can be any JavaScript value that is serializable to JSON.

Example:

const userId = '12345678';

// Select a 'votes' collection
const votes = miro.board.storage.collection('votes');

// Set the vote result for the specified user
await votes.set(userId, true);

// Read user vote result
console.log(await votes.get(userId)); // true

get(...)

(key: string) => Promise<undefined | T>

🔒 Requires scope: boards:read

🚦 Rate limit: Level 1

The get() method retrieves the value stored for a given key in the Collection.

It accepts a single key argument and returns a Promise resolving to the value. If the key does not exist, undefined is returned.

Note: get() is generic. You can specify the expected return type like collection.get<string>('key').

The key parameter specifies the key for the data element in the collection.
It is used to retrieve, set, or remove data, and should always be a string.

Example:

// Select a 'configuration' collection
const configuration = miro.board.storage.collection('configuration');

// Read color-theme value from the collection
const value = await configuration.get('color-theme'); // dark

remove(...)

(key: string) => Promise<void>

🔒 Requires scope: boards:read

🚦 Rate limit: Level 1

The remove() method deletes the value stored for a given key in the Collection.

It accepts a single key parameter and returns a Promise.

The key parameter specifies the key for the data element in the collection.
It is used to retrieve, set, or remove data, and should always be a string.

Example:

const userId = '12345678';

// Select a 'votes' collection
const votes = miro.board.storage.collection('votes');

// Set vote result for user
await votes.set(userId, true);

// Read user vote result
console.log(await votes.get(userId)); // true

// Remove user vote from collection
await votes.remove(userId);

console.log(await votes.get(userId)); // undefined

onValue(...)

(key: string, handler: (value: undefined | T, version: string) => void) => Promise<void>

🔒 Requires scope: boards:read

The onValue() method subscribes to changes for a given key in the Collection.

It accepts two parameters:

• key - The key to subscribe to changes for
• handler - The handler function to call on value changes

The handler executes every time the value for the subscribed key changes in the Collection.

When a new subscriber is added:

• The current value is emitted to the new subscriber immediately.
• If a value already exists for the key, the handler is called with that value right after subscribing.

Note: onValue() is generic. You can specify the expected value type like: collection.onValue<string>('key', (value) => processString(value))

Note: The handler will be invoked for all clients and users collaborating on the board..

The handler parameter specifies the callback function to execute when the value changes.

It should have the following function signature:

type Handler = (value: unknown | undefined) => void;

The value parameter passed to the handler contains the new value for the subscribed key.

Note: value will be the same type as specified in the call to onValue().

Example:

// User id for demo
const userId = "12345678";

// Get the 'votes' collection
const votes = miro.board.storage.collection("votes");

// Subscribe to change events for the user's vote
votes.onValue<boolean>(userId, (vote) => {
  console.log("Vote changed: ", vote);
});

// Update the user's vote
await votes.set(userId, true);

// Prints:
// Vote changed: true

await votes.set(userId, true);
await votes.set(userId, false);

// Prints:
// Vote changed: true
// Vote changed: false

offValue(...)

(key: string, handler: (value: undefined | T, version: string) => void) => Promise<void>

The offValue() method unsubscribes from changes for a given key in the Collection.

It accepts two parameters:

• key - The key to unsubscribe from changes for
• handler - The handler function to remove as a subscriber

This will stop the handler from executing when the value for the subscribed key changes in the Collection.

Example:

// User id for demo
const userId = "12345678";

// Get the 'votes' collection
const votes = miro.board.storage.collection("votes");

// Subscribe handler1 to value changes
const handler1 = (vote) => console.log("Handler 1: ", vote);
votes.onValue<boolean>(userId, handler1);

// Subscribe handler2 to value changes
const handler2 = (vote) => console.log("Handler 2: ", vote);
votes.onValue<boolean>(userId, handler2);

// Update vote value
await votes.set(userId, true);

// Prints:
// Handler 1: true
// Handler 2: true

// Unsubscribe handler1
votes.offValue(userId, handler1);

// Update vote value
await votes.set(userId, false);

// Prints:
// Handler 2: false

// handler1 was removed, handler2 still receives updates

All properties

(key: string) => Promise<undefined | T>

(key: string, handler: (value: undefined | T, version: string) => void) => Promise<void>

(key: string, handler: (value: undefined | T, version: string) => void) => Promise<void>

(key: string) => Promise<void>

(key: string, value: title="Json">Json) => Promise<void>