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

List of constructors for this class
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

List of properties for this class
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

List of methods on this class
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

List of 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

List of parameters
Parameter Type Description
runtime IFluidDataStoreRuntime Data store runtime the new shared directory belongs to
id string Optional name of the shared directory

Returns:

SharedDirectory

Newly create shared directory (but not attached yet)

createSubDirectory

Creates an IDirectory child of this IDirectory.

Signature:

createSubDirectory(subdirName: string): IDirectory;

Parameters

List of parameters
Parameter Type Description
subdirName string Name of the new child directory to create

Returns:

IDirectory

The newly created IDirectory

delete

Deletes the given key from within this IDirectory.

Signature:

delete(key: string): boolean;

Parameters

List of 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

List of 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

List of parameters
Parameter Type Description
callback (value: any, key: string, map: Map) => void 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

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 SharedDirectory to register with the data store.

Signature:

static getFactory(): IChannelFactory;

Returns:

IChannelFactory

A factory that creates and load SharedDirectory

getSubDirectory

Gets an IDirectory child of this IDirectory, if it exists.

Signature:

getSubDirectory(subdirName: string): IDirectory;

Parameters

List of parameters
Parameter Type Description
subdirName string Name of the child directory to get

Returns:

IDirectory

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

List of parameters
Parameter Type Description
relativePath string Path of the IDirectory to get, relative to this IDirectory

Returns:

IDirectory

The requested IDirectory

has

Checks whether the given key exists in this IDirectory.

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

hasSubDirectory

Checks whether this directory has a child directory with the given name.

Signature:

hasSubDirectory(subdirName: string): boolean;

Parameters

List of 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

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<T = any>(key: string, value: T): this;

Parameters

List of 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:

ITree

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

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

Returns:

Promise<T>

The stored value once available