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
| Constructor | Modifiers | Description |
|---|---|---|
| (constructor)(id, runtime, attributes) | Do not call the constructor. Instead, you should use the create method. |
Properties
| 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
| 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
| 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
| 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:
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
| 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
| Parameter | Type | Description |
|---|---|---|
| callbackFn | (value: any, key: string, map: Map |
Callback function |
Returns:
void
get
Retrieves the given key from the map.
Signature:
get<T = any>(key: string): T;
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:
A factory that creates SharedMaps and loads them from storage.
getSerializableStorage
Signature:
getSerializableStorage(): IMapDataObjectSerializable;
Returns:
has
Check if a key exists in the map.
Signature:
has(key: string): boolean;
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
| 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
| 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
| 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
| 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:
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
| Parameter | Type | Description |
|---|---|---|
| key | string | Key to retrieve from |
Returns:
Promise<T>
The stored value once available