SharedMap Class

Packages > @fluidframework/map > SharedMap

The SharedMap distributed data structure can be used to store key-value pairs. It provides the same API for setting and retrieving values that JavaScript developers are accustomed to with the Map built-in object. However, the keys of a SharedMap must be strings.

Signature:

export declare class SharedMap extends SharedObject<ISharedMapEvents> implements ISharedMap 

Extends: SharedObject<ISharedMapEvents>

Implements: ISharedMap

Constructors

List of constructors for this class
Constructor Modifiers Description
(constructor)(id, runtime, attributes) Do not call the constructor. Instead, you should use the create method.

Properties

List of properties for this class
Property Modifiers Type Description
[Symbol.toStringTag] string String representation for the class.
size number The number of key/value pairs stored in the map.

Methods

List of methods on this class
Method Modifiers Description
[Symbol.iterator]() Get an iterator over the entries in this map.
clear() Clear all data from the map.
create(runtime, id) static Create a new shared map.
delete(key) Delete a key from the map.
entries() Get an iterator over the entries in this map.
forEach(callbackFn) Executes the given callback on each entry in the map.
get(key) Retrieves the given key from the map.
getFactory() static Get a factory for SharedMap to register with the data store.
getSerializableStorage()
has(key) Check if a key exists in the map.
keys() Get an iterator over the keys in this map.
loadCore(branchId, storage) Allows the distributed data type to perform custom loading
onDisconnect() Called when the object has disconnected from the delta stream.
processCore(message, local, localOpMetadata) Derived classes must override this to do custom processing on a remote message.
registerCore() Allows the distributed data type the ability to perform custom processing once an attach has happened.
reSubmitCore(content, localOpMetadata) Called when a message has to be resubmitted. This typically happens after a reconnection for unacked messages. The default implementation here is to resubmit the same message. The client can override if different behavior is required. It can choose to resubmit the same message, submit different / multiple messages or not submit anything at all.
set(key, value) Sets the value stored at key to the provided value.
snapshot() Gets a form of the object that can be serialized.
values() Get an iterator over the values in this map.
wait(key) A form of get except it will only resolve the promise once the key exists in the map.

Constructors

SharedMap.(constructor)

Do not call the constructor. Instead, you should use the create method.

Signature:

constructor(id: string, runtime: IFluidDataStoreRuntime, attributes: IChannelAttributes);

Parameters

List of parameters
Parameter Type Description
id string String identifier.
runtime IFluidDataStoreRuntime Data store runtime.
attributes IChannelAttributes The attributes for the map.

Properties

[Symbol.toStringTag]

String representation for the class.

Signature:

readonly [Symbol.toStringTag]: string;

size

The number of key/value pairs stored in the map.

Signature:

get size(): number;

Methods

[Symbol.iterator]

Get an iterator over the entries in this map.

Signature:

[Symbol.iterator](): IterableIterator<[string, any]>;

Returns:

IterableIterator<[string, any]>

The iterator

clear

Clear all data from the map.

Signature:

clear(): void;

Returns:

void

create

Create a new shared map.

Signature:

static create(runtime: IFluidDataStoreRuntime, id?: string): SharedMap;

Parameters

List of parameters
Parameter Type Description
runtime IFluidDataStoreRuntime The data store runtime that the new shared map belongs to.
id string Optional name of the shared map.

Returns:

SharedMap

Newly created shared map.

Example

To create a SharedMap, call the static create method:

const myMap = SharedMap.create(this.runtime, id);

delete

Delete a key from the map.

Signature:

delete(key: string): boolean;

Parameters

List of parameters
Parameter Type Description
key string Key to delete

Returns:

boolean

True if the key existed and was deleted, false if it did not exist

entries

Get an iterator over the entries in this map.

Signature:

entries(): IterableIterator<[string, any]>;

Returns:

IterableIterator<[string, any]>

The iterator

forEach

Executes the given callback on each entry in the map.

Signature:

forEach(callbackFn: (value: any, key: string, map: Map<string, any>) => void): void;

Parameters

List of parameters
Parameter Type Description
callbackFn (value: any, key: string, map: Map) => void Callback function

Returns:

void

get

Retrieves the given key from the map.

Signature:

get<T = any>(key: string): T;

Parameters

List of parameters
Parameter Type Description
key string Key to retrieve from

Returns:

T

The stored value, or undefined if the key is not set

getFactory

Get a factory for SharedMap to register with the data store.

Signature:

static getFactory(): IChannelFactory;

Returns:

IChannelFactory

A factory that creates SharedMaps and loads them from storage.

getSerializableStorage

Signature:

getSerializableStorage(): IMapDataObjectSerializable;

Returns:

IMapDataObjectSerializable

has

Check if a key exists in the map.

Signature:

has(key: string): boolean;

Parameters

List of parameters
Parameter Type Description
key string The key to check

Returns:

boolean

True if the key exists, false otherwise

keys

Get an iterator over the keys in this map.

Signature:

keys(): IterableIterator<string>;

Returns:

IterableIterator<string>

The iterator

loadCore

Allows the distributed data type to perform custom loading

Signature:

protected loadCore(branchId: string | undefined, storage: IChannelStorageService): Promise<void>;

Parameters

List of parameters
Parameter Type Description
branchId string | undefined Branch ID
storage IChannelStorageService

Returns:

Promise<void>

onDisconnect

Called when the object has disconnected from the delta stream.

Signature:

protected onDisconnect(): void;

Returns:

void

processCore

Derived classes must override this to do custom processing on a remote message.

Signature:

protected processCore(message: ISequencedDocumentMessage, local: boolean, localOpMetadata: unknown): void;

Parameters

List of parameters
Parameter Type Description
message ISequencedDocumentMessage The message to process
local boolean True if the shared object is local
localOpMetadata unknown For local client messages, this is the metadata that was submitted with the message. For messages from a remote client, this will be undefined.

Returns:

void

registerCore

Allows the distributed data type the ability to perform custom processing once an attach has happened.

Signature:

protected registerCore(): void;

Returns:

void

reSubmitCore

Called when a message has to be resubmitted. This typically happens after a reconnection for unacked messages. The default implementation here is to resubmit the same message. The client can override if different behavior is required. It can choose to resubmit the same message, submit different / multiple messages or not submit anything at all.

Signature:

protected reSubmitCore(content: any, localOpMetadata: unknown): void;

Parameters

List of parameters
Parameter Type Description
content any The content of the original message.
localOpMetadata unknown The local metadata associated with the original message.

Returns:

void

set

Sets the value stored at key to the provided value.

Signature:

set(key: string, value: any): this;

Parameters

List of parameters
Parameter Type Description
key string Key to set at
value any Value to set

Returns:

this

The ISharedMap itself

snapshot

Gets a form of the object that can be serialized.

Signature:

snapshot(): ITree;

Returns:

ITree

A tree representing the snapshot of the shared object

values

Get an iterator over the values in this map.

Signature:

values(): IterableIterator<any>;

Returns:

IterableIterator<any>

The iterator

wait

A form of get except it will only resolve the promise once the key exists in the map.

Signature:

wait<T = any>(key: string): Promise<T>;

Parameters

List of parameters
Parameter Type Description
key string Key to retrieve from

Returns:

Promise<T>

The stored value once available