microsoft
/
FluidFramework
зеркало из https://github.com/microsoft/FluidFramework.git
1
0
Форкнуть 0
Код Задачи Пакеты Проекты Релизы Вики Активность

docs: Improve `@fluidframework/map` API docs (#10641) 

# Improve `@fluidframework/map` API docs

The intention behind this PR is to improve API documentation on the consumer-facing APIs of the `@fluidframework/map` package. It also includes some changes in transitively exposed APIs from packages upon which it depends. 

See here for the public-facing, generated docs: https://fluidframework.com/docs/apis/map/

[ADO #624](https://dev.azure.com/fluidframework/internal/_workitems/edit/624)
This commit is contained in:
Joshua Smithrud 2022-07-15 15:44:21 -07:00 коммит произвёл GitHub
Родитель 24ac749c8b
Коммит b0635754b5
Не найден ключ, соответствующий данной подписи
Идентификатор ключа GPG: 4AEE18F83AFDEB23
10 изменённых файлов: 248 добавлений и 230 удалений
Показать статистику Скачать Patch файл Скачать Diff файл Показать все файлы Свернуть все файлы

22
api-report/map.api.md
Просмотреть файл

@ -23,7 +23,7 @@ import { ITelemetryContext } from '@fluidframework/runtime-definitions';
import { SharedObject } from '@fluidframework/shared-object-base';
// @public @sealed
export class DirectoryFactory {
export class DirectoryFactory implements IChannelFactory {
// (undocumented)
static readonly Attributes: IChannelAttributes;
// (undocumented)
@ -67,11 +67,9 @@ export interface IDirectoryCreateSubDirectoryOperation {
// @public
export interface IDirectoryDataObject {
// (undocumented)
storage?: {
[key: string]: ISerializableValue;
};
// (undocumented)
subdirectories?: {
[subdirName: string]: IDirectoryDataObject;
};
@ -93,24 +91,18 @@ export interface IDirectoryDeleteSubDirectoryOperation {
// @public
export interface IDirectoryEvents extends IEvent {
// (undocumented)
(event: "containedValueChanged", listener: (changed: IValueChanged, local: boolean, target: IEventThisPlaceHolder) => void): any;
// (undocumented)
(event: "subDirectoryCreated", listener: (path: string, local: boolean, target: IEventThisPlaceHolder) => void): any;
// (undocumented)
(event: "subDirectoryDeleted", listener: (path: string, local: boolean, target: IEventThisPlaceHolder) => void): any;
// (undocumented)
(event: "disposed", listener: (target: IEventThisPlaceHolder) => void): any;
}
// @public
export type IDirectoryKeyOperation = IDirectorySetOperation | IDirectoryDeleteOperation;
// @public (undocumented)
// @internal
export interface IDirectoryNewStorageFormat {
// (undocumented)
blobs: string[];
// (undocumented)
content: IDirectoryDataObject;
}
@ -143,13 +135,13 @@ export interface ILocalValue {
readonly value: any;
}
// @public
// @public @deprecated
export interface ISerializableValue {
type: string;
value: any;
}
// @public (undocumented)
// @public
export interface ISerializedValue {
type: string;
value: string | undefined;
@ -165,13 +157,9 @@ export interface ISharedDirectory extends ISharedObject<ISharedDirectoryEvents &
// @public
export interface ISharedDirectoryEvents extends ISharedObjectEvents {
// (undocumented)
(event: "valueChanged", listener: (changed: IDirectoryValueChanged, local: boolean, target: IEventThisPlaceHolder) => void): any;
// (undocumented)
(event: "clear", listener: (local: boolean, target: IEventThisPlaceHolder) => void): any;
// (undocumented)
(event: "subDirectoryCreated", listener: (path: string, local: boolean, target: IEventThisPlaceHolder) => void): any;
// (undocumented)
(event: "subDirectoryDeleted", listener: (path: string, local: boolean, target: IEventThisPlaceHolder) => void): any;
}
@ -183,9 +171,7 @@ export interface ISharedMap extends ISharedObject<ISharedMapEvents>, Map<string,
// @public
export interface ISharedMapEvents extends ISharedObjectEvents {
// (undocumented)
(event: "valueChanged", listener: (changed: IValueChanged, local: boolean, target: IEventThisPlaceHolder) => void): any;
// (undocumented)
(event: "clear", listener: (local: boolean, target: IEventThisPlaceHolder) => void): any;
}

8
api-report/shared-object-base.api.md
Просмотреть файл

@ -65,10 +65,12 @@ export interface ISharedObject<TEvent extends ISharedObjectEvents = ISharedObjec
getGCData(fullGC?: boolean): IGarbageCollectionData;
}
// @public (undocumented)
// @public
export interface ISharedObjectEvents extends IErrorEvent {
// (undocumented)
(event: "pre-op" | "op", listener: (op: ISequencedDocumentMessage, local: boolean, target: IEventThisPlaceHolder) => void): any;
// @eventProperty
(event: "pre-op", listener: (op: ISequencedDocumentMessage, local: boolean, target: IEventThisPlaceHolder) => void): any;
// @eventProperty
(event: "op", listener: (op: ISequencedDocumentMessage, local: boolean, target: IEventThisPlaceHolder) => void): any;
}
// @public (undocumented)

37
packages/dds/map/src/directory.ts
Просмотреть файл

@ -192,24 +192,47 @@ export type IDirectoryOperation = IDirectoryStorageOperation | IDirectorySubDire
/**
* Defines the in-memory object structure to be used for the conversion to/from serialized.
* @privateRemarks
* Directly used in JSON.stringify, direct result from JSON.parse.
*
* @remarks Directly used in
* {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify
* | JSON.stringify}, direct result from
* {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/parse | JSON.parse}.
*/
export interface IDirectoryDataObject {
/**
* Key/value date set by the user.
*/
storage?: { [key: string]: ISerializableValue; };
/**
* Recursive sub-directories {@link IDirectoryDataObject | objects}.
*/
subdirectories?: { [subdirName: string]: IDirectoryDataObject; };
}
/**
* {@link IDirectory} storage format.
*
* @internal
*/
export interface IDirectoryNewStorageFormat {
/**
* Blob IDs representing larger directory data that was serialized.
*/
blobs: string[];
/**
* Storage content representing directory data that was not serialized.
*/
content: IDirectoryDataObject;
}
/**
* The factory that defines the directory.
* {@link @fluidframework/datastore-definitions#IChannelFactory} for {@link SharedDirectory}.
*
* @sealed
*/
export class DirectoryFactory {
export class DirectoryFactory implements IChannelFactory {
/**
* {@inheritDoc @fluidframework/datastore-definitions#IChannelFactory."type"}
*/
@ -264,9 +287,7 @@ export class DirectoryFactory {
}
/**
* 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.
* {@inheritDoc ISharedDirectory}
*
* @example
* ```typescript
@ -544,7 +565,7 @@ export class SharedDirectory extends SharedObject<ISharedDirectoryEvents> implem
* {@inheritDoc @fluidframework/shared-object-base#SharedObject.onDisconnect}
* @internal
*/
protected onDisconnect() {}
protected onDisconnect() { }
/**
* {@inheritDoc @fluidframework/shared-object-base#SharedObject.reSubmitCore}

327
packages/dds/map/src/interfaces.ts
Просмотреть файл

@ -98,94 +98,73 @@ export interface IDirectory extends Map<string, any>, IEventProvider<IDirectoryE
}
/**
* Events emitted in response to changes to the directory data. These events only emit on the ISharedDirectory itself,
* and not on subdirectories.
*
* @remarks
*
* The following is the list of events emitted.
*
* ### "valueChanged"
*
* The valueChanged event is emitted when a key is set or deleted. This is emitted for any key in the ISharedDirectory
* or any subdirectory.
*
* #### Listener signature
*
* ```typescript
* (
* changed: IDirectoryValueChanged,
* local: boolean,
* target: IEventThisPlaceHolder,
* ) => void
* ```
* - `changed` - Information on the key that changed, its value prior to the change, and the path to the key that
* changed.
*
* - `local` - Whether the change originated from this client.
*
* - `target` - The ISharedDirectory itself.
*
* ### "clear"
*
* The clear event is emitted when the ISharedDirectory is cleared.
*
* #### Listener signature
*
* ```typescript
* (local: boolean, target: IEventThisPlaceHolder) => void
* ```
* - `local` - Whether the clear originated from this client.
*
* - `target` - The ISharedDirectory itself.
*
* ### "subDirectoryCreated"
*
* The subDirectoryCreated event is emitted when a subdirectory is created.
*
* #### Listener signature
*
* ```typescript
* (path: string, local: boolean, target: IEventThisPlaceHolder) => void
* ```
* - `path` - The relative path to the subdirectory that is created.
* It is relative from the object which raises the event.
*
* - `local` - Whether the create originated from the this client.
*
* - `target` - The ISharedDirectory itself.
*
* ###"subDirectoryDeleted"
*
* The subDirectoryDeleted event is emitted when a subdirectory is deleted.
*
* #### Listener signature
*
* ```typescript
* (path: string, local: boolean, target: IEventThisPlaceHolder) => void
* ```
* - `path` - The relative path to the subdirectory that is deleted.
* It is relative from the object which raises the event.
*
* - `local` - Whether the delete originated from the this client.
*
* - `target` - The ISharedDirectory itself.
* Events emitted in response to changes to the directory data.
* These events only emit on the {@link ISharedDirectory} itself, and not on subdirectories.
*/
export interface ISharedDirectoryEvents extends ISharedObjectEvents {
/**
* Emitted when a key is set or deleted. This is emitted for any key in the {@link ISharedDirectory} or any
* subdirectory.
*
* @remarks Listener parameters:
*
* - `changed` - Information on the key that changed, its value prior to the change, and the path to the
* key that changed.
*
* - `local` - Whether the change originated from this client.
*
* - `target` - The {@link ISharedDirectory} itself.
*/
(event: "valueChanged", listener: (
changed: IDirectoryValueChanged,
local: boolean,
target: IEventThisPlaceHolder,
) => void);
/**
* Emitted when the {@link ISharedDirectory} is cleared.
*
* @remarks Listener parameters:
*
* - `local` - Whether the clear originated from this client.
*
* - `target` - The {@link ISharedDirectory} itself.
*/
(event: "clear", listener: (
local: boolean,
target: IEventThisPlaceHolder,
) => void);
/**
* Emitted when a subdirectory is created.
*
* @remarks Listener parameters:
*
* - `path` - The relative path to the subdirectory that is created.
* It is relative from the object which raises the event.
*
* - `local` - Whether the create originated from the this client.
*
* - `target` - The {@link ISharedDirectory} itself.
*/
(event: "subDirectoryCreated", listener: (
path: string,
local: boolean,
target: IEventThisPlaceHolder,
) => void);
/**
* Emitted when a subdirectory is deleted.
*
* @remarks Listener parameters:
*
* - `path` - The relative path to the subdirectory that is deleted.
* It is relative from the object which raises the event.
*
* - `local` - Whether the delete originated from the this client.
*
* - `target` - The {@link ISharedDirectory} itself.
*/
// eslint-disable-next-line @typescript-eslint/unified-signatures
(event: "subDirectoryDeleted", listener: (
path: string,
@ -196,95 +175,80 @@ export interface ISharedDirectoryEvents extends ISharedObjectEvents {
/**
* Events emitted in response to changes to the directory data.
*
* @remarks
*
* The following is the list of events emitted.
*
* ### "containedValueChanged"
*
* The containedValueChanged event is emitted when a key is set or deleted. As opposed to the SharedDirectory's
* valueChanged event, this is emitted only on the IDirectory that directly contains the key.
*
* #### Listener signature
*
* ```typescript
* (changed: IValueChanged, local: boolean, target: IEventThisPlaceHolder) => void
* ```
* - `changed` - Information on the key that changed and its value prior to the change.
*
* - `local` - Whether the change originated from this client.
*
* - `target` - The IDirectory itself.
*
* ### "subDirectoryCreated"
*
* The subDirectoryCreated event is emitted when a subdirectory is created.
*
* #### Listener signature
*
* ```typescript
* (path: string, local: boolean, target: IEventThisPlaceHolder) => void
* ```
* - `path` - The relative path to the subdirectory that is created.
* It is relative from the object which raises the event.
*
* - `local` - Whether the creation originated from the this client.
*
* - `target` - The ISharedDirectory itself.
*
* ### "subDirectoryDeleted"
*
* The subDirectoryDeleted event is emitted when a subdirectory is deleted.
*
* #### Listener signature
*
* ```typescript
* (path: string, local: boolean, target: IEventThisPlaceHolder) => void
* ```
* - `path` - The relative path to the subdirectory that is deleted.
* It is relative from the object which raises the event.
*
* - `local` - Whether the delete originated from the this client.
*
* - `target` - The ISharedDirectory itself.
*
* ### "disposed"
*
* The dispose event is emitted when this sub directory is deleted.
*
* #### Listener signature
*
* ```typescript
* (local: boolean, target: IEventThisPlaceHolder) => void
* ```
*
* - `target` - The IDirectory itself.
*/
export interface IDirectoryEvents extends IEvent {
/**
* Emitted when a key is set or deleted. As opposed to the
* {@link SharedDirectory}'s valueChanged event, this is emitted only on the {@link IDirectory} that directly
* contains the key.
*
* @remarks Listener parameters:
*
* - `changed` - Information on the key that changed and its value prior to the change.
*
* - `local` - Whether the change originated from this client.
*
* - `target` - The {@link IDirectory} itself.
*/
(event: "containedValueChanged", listener: (
changed: IValueChanged,
local: boolean,
target: IEventThisPlaceHolder,
) => void);
/**
* Emitted when a subdirectory is created.
*
* @remarks Listener parameters:
*
* - `path` - The relative path to the subdirectory that is created.
* It is relative from the object which raises the event.
*
* - `local` - Whether the creation originated from the this client.
*
* - `target` - The {@link ISharedDirectory} itself.
*/
(event: "subDirectoryCreated", listener: (
path: string,
local: boolean,
target: IEventThisPlaceHolder,
) => void);
/**
* Emitted when a subdirectory is deleted.
*
* @remarks Listener parameters:
*
* - `path` - The relative path to the subdirectory that is deleted.
* It is relative from the object which raises the event.
*
* - `local` - Whether the delete originated from the this client.
*
* - `target` - The {@link ISharedDirectory} itself.
*/
// eslint-disable-next-line @typescript-eslint/unified-signatures
(event: "subDirectoryDeleted", listener: (
path: string,
local: boolean,
target: IEventThisPlaceHolder,
) => void);
/**
* Emitted when this sub directory is deleted.
*
* @remarks Listener parameters:
*
* - `target` - The {@link IDirectory} itself.
*/
(event: "disposed", listener: (
target: IEventThisPlaceHolder,
) => void);
}
/**
* Interface describing a shared directory.
* 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.
*/
export interface ISharedDirectory extends
ISharedObject<ISharedDirectoryEvents & IDirectoryEvents>,
@ -296,7 +260,7 @@ export interface ISharedDirectory extends
}
/**
* Type of "valueChanged" event parameter for SharedDirectory.
* Type of "valueChanged" event parameter for {@link ISharedDirectory}
*/
export interface IDirectoryValueChanged extends IValueChanged {
/**
@ -306,60 +270,51 @@ export interface IDirectoryValueChanged extends IValueChanged {
}
/**
* Events emitted in response to changes to the map data.
*
* @remarks
*
* The following is the list of events emitted.
*
* ### "valueChanged"
*
* The valueChanged event is emitted when a key is set or deleted.
*
* #### Listener signature
*
* ```typescript
* (
* changed: IValueChanged,
* local: boolean,
* target: IEventThisPlaceHolder,
* ) => void
* ```
* - `changed` - Information on the key that changed and its value prior to the change.
*
* - `local` - Whether the change originated from this client.
*
* - `target` - The map itself.
*
* ### "clear"
*
* The clear event is emitted when the map is cleared.
*
* #### Listener signature
*
* ```typescript
* (local: boolean, target: IEventThisPlaceHolder) => void
* ```
* - `local` - Whether the clear originated from this client.
*
* - `target` - The map itself.
* Events emitted in response to changes to the {@link ISharedMap | map} data.
*/
export interface ISharedMapEvents extends ISharedObjectEvents {
/**
* Emitted when a key is set or deleted.
*
* @remarks Listener parameters:
*
* - `changed` - Information on the key that changed and its value prior to the change.
*
* - `local` - Whether the change originated from this client.
*
* - `target` - The {@link ISharedMap} itself.
*/
(event: "valueChanged", listener: (
changed: IValueChanged,
local: boolean,
target: IEventThisPlaceHolder) => void);
/**
* Emitted when the map is cleared.
*
* @remarks Listener parameters:
*
* - `local` - Whether the clear originated from this client.
*
* - `target` - The {@link ISharedMap} itself.
*/
(event: "clear", listener: (
local: boolean,
target: IEventThisPlaceHolder) => void);
}
/**
* Shared map interface
* 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
* {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map | Map} built-in object.
* However, the keys of a SharedMap must be strings, and the values must either be a JSON-serializable object or a
* {@link @fluidframework/shared-object-base#SharedObjectHandle}.
*
* For more information, including example usages, see {@link https://fluidframework.com/docs/data-structures/map/}.
*/
export interface ISharedMap extends ISharedObject<ISharedMapEvents>, Map<string, any> {
/**
* Retrieves the given key from the map.
* Retrieves the given key from the map if it exists.
* @param key - Key to retrieve from
* @returns The stored value, or undefined if the key is not set
*/
@ -367,16 +322,17 @@ export interface ISharedMap extends ISharedObject<ISharedMapEvents>, Map<string,
/**
* Sets the value stored at key to the provided value.
* @param key - Key to set at
* @param key - Key to set
* @param value - Value to set
* @returns The ISharedMap itself
* @returns The {@link ISharedMap} itself
*/
set<T = any>(key: string, value: T): this;
}
/**
* The _ready-for-serialization_ format of values contained in DDS contents. This allows us to use
* ISerializableValue.type to understand whether they're storing a Plain JS object, a SharedObject, or a value type.
* {@link ISerializableValue."type"} to understand whether they're storing a Plain JavaScript object,
* a {@link @fluidframework/shared-object-base#SharedObject}, or a value type.
*
* @remarks
*
@ -384,13 +340,17 @@ export interface ISharedMap extends ISharedObject<ISharedMapEvents>, Map<string,
* the _in-memory representation_ of the value instead). An ISerializableValue is what gets passed to
* JSON.stringify and comes out of JSON.parse. This format is used both for snapshots (loadCore/populate)
* and ops (set).
*
* If type is Plain, it must be a plain JS object that can survive a JSON.stringify/parse. E.g. a URL object will
* just get stringified to a URL string and not rehydrate as a URL object on the other side. It may contain members
* that are ISerializedHandle (the serialized form of a handle).
*
* If type is a value type then it must be amongst the types registered via registerValueType or we won't know how
* to serialize/deserialize it (we rely on its factory via .load() and .store()). Its value will be type-dependent.
* If type is Shared, then the in-memory value will just be a reference to the SharedObject. Its value will be a
* channel ID. This type is legacy and deprecated.
* channel ID.
*
* @deprecated This type is legacy and deprecated.
*/
export interface ISerializableValue {
/**
@ -404,6 +364,9 @@ export interface ISerializableValue {
value: any;
}
/**
* Serialized {@link ISerializableValue} counterpart.
*/
export interface ISerializedValue {
/**
* A type annotation to help indicate how the value serializes.
@ -412,6 +375,8 @@ export interface ISerializedValue {
/**
* String representation of the value.
*
* @remarks Will be undefined if the original value was undefined.
*/
value: string | undefined;
}

6
packages/dds/map/src/localValues.ts
Просмотреть файл

@ -17,7 +17,7 @@ import {
} from "./interfaces";
/**
* A local value to be stored in a container type DDS.
* A local value to be stored in a container type Distributed Data Store (DDS).
*/
export interface ILocalValue {
/**
@ -90,8 +90,8 @@ export class PlainLocalValue implements ILocalValue {
}
/**
* A LocalValueMaker enables a container type DDS to produce and store local values with minimal awareness of how
* those objects are stored, serialized, and deserialized.
* Enables a container type {@link https://fluidframework.com/docs/build/dds/ | DDS} to produce and store local
* values with minimal awareness of how those objects are stored, serialized, and deserialized.
*/
export class LocalValueMaker {
/**

16
packages/dds/map/src/map.ts
Просмотреть файл

@ -33,7 +33,8 @@ interface IMapSerializationFormat {
const snapshotFileName = "header";
/**
* The factory that defines the map.
* {@link @fluidframework/datastore-definitions#IChannelFactory} for {@link SharedMap}.
*
* @sealed
*/
export class MapFactory implements IChannelFactory {
@ -91,10 +92,7 @@ export class MapFactory implements IChannelFactory {
}
/**
* 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
* {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map | Map} built-in object.
* However, the keys of a SharedMap must be strings.
* {@inheritDoc ISharedMap}
*/
export class SharedMap extends SharedObject<ISharedMapEvents> implements ISharedMap {
/**
@ -340,7 +338,7 @@ export class SharedMap extends SharedObject<ISharedMapEvents> implements IShared
* {@inheritDoc @fluidframework/shared-object-base#SharedObject.onDisconnect}
* @internal
*/
protected onDisconnect() {}
protected onDisconnect() { }
/**
* {@inheritDoc @fluidframework/shared-object-base#SharedObject.reSubmitCore}
@ -372,7 +370,7 @@ export class SharedMap extends SharedObject<ISharedMapEvents> implements IShared
* {@inheritDoc @fluidframework/shared-object-base#SharedObject.rollback}
* @internal
*/
protected rollback(content: any, localOpMetadata: unknown) {
this.kernel.rollback(content, localOpMetadata);
}
protected rollback(content: any, localOpMetadata: unknown) {
this.kernel.rollback(content, localOpMetadata);
}
}

9
packages/dds/map/src/mapKernel.ts
Просмотреть файл

@ -101,12 +101,19 @@ export type IMapOperation = IMapKeyOperation | IMapClearOperation;
/**
* Defines the in-memory object structure to be used for the conversion to/from serialized.
* Directly used in JSON.stringify, direct result from JSON.parse
*
* @remarks Directly used in
* {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify
* | JSON.stringify}, direct result from
* {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/parse | JSON.parse}.
*/
export interface IMapDataObjectSerializable {
[key: string]: ISerializableValue;
}
/**
* Serialized key/value data.
*/
export interface IMapDataObjectSerialized {
[key: string]: ISerializedValue;
}

25
packages/dds/shared-object-base/src/types.ts
Просмотреть файл

@ -8,9 +8,30 @@ import { IChannel } from "@fluidframework/datastore-definitions";
import { ISequencedDocumentMessage } from "@fluidframework/protocol-definitions";
import { IGarbageCollectionData } from "@fluidframework/runtime-definitions";
/**
* Events emitted by {@link ISharedObject}.
*/
export interface ISharedObjectEvents extends IErrorEvent {
(event: "pre-op" | "op",
listener: (op: ISequencedDocumentMessage, local: boolean, target: IEventThisPlaceHolder) => void);
/**
* Fires before an incoming operation (op) is applied to the shared object.
*
* @remarks Note: this should be considered an internal implementation detail. It is not recommended for external
* use.
*
* @eventProperty
*/
(event: "pre-op", listener: (op: ISequencedDocumentMessage, local: boolean, target: IEventThisPlaceHolder) => void);
/**
* Fires after an incoming op is applied to the shared object.
*
* @remarks Note: this should be considered an internal implementation detail. It is not recommended for external
* use.
*
* @eventProperty
*/
// eslint-disable-next-line @typescript-eslint/unified-signatures
(event: "op", listener: (op: ISequencedDocumentMessage, local: boolean, target: IEventThisPlaceHolder) => void);
}
/**

13
packages/loader/driver-utils/src/readAndParse.ts
Просмотреть файл

@ -7,11 +7,16 @@ import { bufferToString } from "@fluidframework/common-utils";
import { IDocumentStorageService } from "@fluidframework/driver-definitions";
/**
* Read a blob from IDocumentStorageService and JSON.parse it into object of type T
* Read a blob from {@link @fluidframework/driver-definitions#IDocumentStorageService} and
* {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/parse | JSON.parse}
* it into object of type `T`.
*
* @param storage - the IDocumentStorageService to read from
* @param id - the id of the blob to read and parse
* @returns the object that we decoded and JSON.parse
* @param storage - The `DocumentStorageService` to read from.
* @param id - The ID of the blob to read and parse.
*
* @typeParam T - Output type matching JSON format of inpyt blob data.
*
* @returns The object that we decoded and parsed via `JSON.parse`.
*/
export async function readAndParse<T>(storage: Pick<IDocumentStorageService, "readBlob">, id: string): Promise<T> {
const blob = await storage.readBlob(id);

15
packages/runtime/datastore-definitions/src/channel.ts
Просмотреть файл

@ -194,7 +194,20 @@ export interface IChannelServices {
}
/**
* Definitions of a channel factory. Factories follow a common model but enable custom behavior.
* Definitions of a channel factory.
*
* The runtime must be able to produce "channels" of the correct in-memory object type for the collaborative session.
* Here "channels" are typically distributed data structures (DDSs).
*
* The runtime will consult with a registry of such factories during
* {@link https://fluidframework.com/docs/build/containers/ | Container} load and when receiving "attach" operations
* (ops), which indicate a new instance of a channel being introduced to the collaboration session, to produce the
* appropriate in-memory object.
*
* @example If a collaboration includes a {@link https://fluidframework.com/docs/data-structures/map/ | SharedMap},
* a the collaborating clients will need to have access to a factory that can produce the `SharedMap` obect.
*
* @remarks Factories follow a common model but enable custom behavior.
*/
export interface IChannelFactory {
/**