SharedDirectory Class
Packages > @fluidframework/map > SharedDirectory
SharedDirectory provides a hierarchical organization of map-like data structures as SubDirectories. The values stored within can be accessed like a map, and the hierarchy can be navigated using path syntax. SubDirectories can be retrieved for use as working directories.
Signature:
/** @sealed */
export declare class SharedDirectory extends SharedObject<ISharedDirectoryEvents> implements ISharedDirectory
Extends: SharedObject<ISharedDirectoryEvents>
Implements: ISharedDirectory
Example
mySharedDirectory.createSubDirectory("a").createSubDirectory("b").createSubDirectory("c").set("foo", val1);
const mySubDir = mySharedDirectory.getWorkingDirectory("/a/b/c");
mySubDir.get("foo"); // returns val1
Constructors
| Constructor | Modifiers | Description |
|---|---|---|
| (constructor)(id, runtime, attributes) | Constructs a new shared directory. If the object is non-local an id and service interfaces will be provided. |
Properties
| Property | Modifiers | Type | Description |
|---|---|---|---|
| [Symbol.toStringTag] | string | String representation for the class. | |
| absolutePath | string | The absolute path of the directory. | |
| size | number | The number of entries under this IDirectory. |
Methods
| Method | Modifiers | Description |
|---|---|---|
| [Symbol.iterator]() | Get an iterator over the entries under this IDirectory. | |
| clear() | Deletes all keys from within this IDirectory. | |
| create(runtime, id) | static |
Create a new shared directory |
| createSubDirectory(subdirName) | Creates an IDirectory child of this IDirectory. | |
| delete(key) | Deletes the given key from within this IDirectory. | |
| deleteSubDirectory(subdirName) | Deletes an IDirectory child of this IDirectory, if it exists, along with all descendent keys and directories. | |
| entries() | Get an iterator over the entries under this IDirectory. | |
| forEach(callback) | Issue a callback on each entry under this IDirectory. | |
| get(key) | Retrieves the value stored at the given key from the directory. | |
| getFactory() | static |
Get a factory for SharedDirectory to register with the data store. |
| getSubDirectory(subdirName) | Gets an IDirectory child of this IDirectory, if it exists. | |
| getWorkingDirectory(relativePath) | Get an IDirectory within the directory, in order to use relative paths from that location. | |
| has(key) | Checks whether the given key exists in this IDirectory. | |
| hasSubDirectory(subdirName) | Checks whether this directory has a child directory with the given name. | |
| keys() | Get an iterator over the keys under this IDirectory. | |
| 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. | |
| subdirectories() | Gets an iterator over the IDirectory children of this IDirectory. | |
| values() | Get an iterator over the values under this IDirectory. | |
| wait(key) | A form of get except it will only resolve the promise once the key exists in the directory. |
Constructors
SharedDirectory.(constructor)
Constructs a new shared directory. If the object is non-local an id and service interfaces will be provided.
Signature:
constructor(id: string, runtime: IFluidDataStoreRuntime, attributes: IChannelAttributes);
Parameters
| Parameter | Type | Description |
|---|---|---|
| id | string | String identifier for the SharedDirectory |
| runtime | IFluidDataStoreRuntime | Data store runtime |
| attributes | IChannelAttributes |
Properties
[Symbol.toStringTag]
String representation for the class.
Signature:
[Symbol.toStringTag]: string;
absolutePath
The absolute path of the directory.
Signature:
get absolutePath(): string;
size
The number of entries under this IDirectory.
Signature:
get size(): number;
Methods
[Symbol.iterator]
Get an iterator over the entries under this IDirectory.
Signature:
[Symbol.iterator](): IterableIterator<[string, any]>;
Returns:
IterableIterator<[string, any]>
The iterator
clear
Deletes all keys from within this IDirectory.
Signature:
clear(): void;
Returns:
void
create
Create a new shared directory
Signature:
static create(runtime: IFluidDataStoreRuntime, id?: string): SharedDirectory;
Parameters
| Parameter | Type | Description |
|---|---|---|
| runtime | IFluidDataStoreRuntime | Data store runtime the new shared directory belongs to |
| id | string | Optional name of the shared directory |
Returns:
Newly create shared directory (but not attached yet)
createSubDirectory
Creates an IDirectory child of this IDirectory.
Signature:
createSubDirectory(subdirName: string): IDirectory;
Parameters
| Parameter | Type | Description |
|---|---|---|
| subdirName | string | Name of the new child directory to create |
Returns:
The newly created IDirectory
delete
Deletes the given key from within this IDirectory.
Signature:
delete(key: string): boolean;
Parameters
| Parameter | Type | Description |
|---|---|---|
| key | string | The key to delete |
Returns:
boolean
True if the key existed and was deleted, false if it did not exist
deleteSubDirectory
Deletes an IDirectory child of this IDirectory, if it exists, along with all descendent keys and directories.
Signature:
deleteSubDirectory(subdirName: string): boolean;
Parameters
| Parameter | Type | Description |
|---|---|---|
| subdirName | string | Name of the child directory to delete |
Returns:
boolean
True if the IDirectory existed and was deleted, false if it did not exist
entries
Get an iterator over the entries under this IDirectory.
Signature:
entries(): IterableIterator<[string, any]>;
Returns:
IterableIterator<[string, any]>
The iterator
forEach
Issue a callback on each entry under this IDirectory.
Signature:
forEach(callback: (value: any, key: string, map: Map<string, any>) => void): void;
Parameters
| Parameter | Type | Description |
|---|---|---|
| callback | (value: any, key: string, map: Map |
Callback to issue |
Returns:
void
get
Retrieves the value stored at the given key from the directory.
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 SharedDirectory to register with the data store.
Signature:
static getFactory(): IChannelFactory;
Returns:
A factory that creates and load SharedDirectory
getSubDirectory
Gets an IDirectory child of this IDirectory, if it exists.
Signature:
getSubDirectory(subdirName: string): IDirectory;
Parameters
| Parameter | Type | Description |
|---|---|---|
| subdirName | string | Name of the child directory to get |
Returns:
The requested IDirectory
getWorkingDirectory
Get an IDirectory within the directory, in order to use relative paths from that location.
Signature:
getWorkingDirectory(relativePath: string): IDirectory;
Parameters
| Parameter | Type | Description |
|---|---|---|
| relativePath | string | Path of the IDirectory to get, relative to this IDirectory |
Returns:
The requested IDirectory
has
Checks whether the given key exists in this IDirectory.
Signature:
has(key: string): boolean;
Parameters
| Parameter | Type | Description |
|---|---|---|
| key | string | The key to check |
Returns:
boolean
True if the key exists, false otherwise
hasSubDirectory
Checks whether this directory has a child directory with the given name.
Signature:
hasSubDirectory(subdirName: string): boolean;
Parameters
| Parameter | Type | Description |
|---|---|---|
| subdirName | string | Name of the child directory to check |
Returns:
boolean
True if it exists, false otherwise
keys
Get an iterator over the keys under this IDirectory.
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<T = any>(key: string, value: T): this;
Parameters
| Parameter | Type | Description |
|---|---|---|
| key | string | Key to set at |
| value | T | Value to set |
Returns:
this
The IDirectory 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
subdirectories
Gets an iterator over the IDirectory children of this IDirectory.
Signature:
subdirectories(): IterableIterator<[string, IDirectory]>;
Returns:
IterableIterator<[string, IDirectory]>
The IDirectory iterator
values
Get an iterator over the values under this IDirectory.
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 directory.
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