@fluidframework/map 1.4.0-121020 → 2.0.0-dev-rc.1.0.0.224419

package/dist/map-beta.d.ts

@@ -0,0 +1,275 @@
+/**
+ * The `map` library provides interfaces and implementing classes for map-like distributed data structures.
+ *
+ * @remarks The following distributed data structures are defined in this library:
+ *
+ * - {@link SharedMap}
+ *
+ * - {@link SharedDirectory}
+ *
+ * @packageDocumentation
+ */
+
+import { IChannelAttributes } from '@fluidframework/datastore-definitions';
+import { IChannelFactory } from '@fluidframework/datastore-definitions';
+import { IChannelServices } from '@fluidframework/datastore-definitions';
+import { IChannelStorageService } from '@fluidframework/datastore-definitions';
+import { IDisposable } from '@fluidframework/core-interfaces';
+import { IEvent } from '@fluidframework/core-interfaces';
+import { IEventProvider } from '@fluidframework/core-interfaces';
+import { IEventThisPlaceHolder } from '@fluidframework/core-interfaces';
+import { IFluidDataStoreRuntime } from '@fluidframework/datastore-definitions';
+import { IFluidHandle } from '@fluidframework/core-interfaces';
+import { IFluidSerializer } from '@fluidframework/shared-object-base';
+import { ISequencedDocumentMessage } from '@fluidframework/protocol-definitions';
+import { ISharedObject } from '@fluidframework/shared-object-base';
+import { ISharedObjectEvents } from '@fluidframework/shared-object-base';
+import { ISummaryTreeWithStats } from '@fluidframework/runtime-definitions';
+import { ITelemetryContext } from '@fluidframework/runtime-definitions';
+import { SharedObject } from '@fluidframework/shared-object-base';
+
+/* Excluded from this release type: DirectoryFactory */
+
+/* Excluded from this release type: ICreateInfo */
+
+/* Excluded from this release type: IDirectory */
+
+/* Excluded from this release type: IDirectoryClearOperation */
+
+/* Excluded from this release type: IDirectoryCreateSubDirectoryOperation */
+
+/* Excluded from this release type: IDirectoryDataObject */
+
+/* Excluded from this release type: IDirectoryDeleteOperation */
+
+/* Excluded from this release type: IDirectoryDeleteSubDirectoryOperation */
+
+/* Excluded from this release type: IDirectoryEvents */
+
+/* Excluded from this release type: IDirectoryKeyOperation */
+
+/* Excluded from this release type: IDirectoryNewStorageFormat */
+
+/* Excluded from this release type: IDirectoryOperation */
+
+/* Excluded from this release type: IDirectorySetOperation */
+
+/* Excluded from this release type: IDirectoryStorageOperation */
+
+/* Excluded from this release type: IDirectorySubDirectoryOperation */
+
+/* Excluded from this release type: IDirectoryValueChanged */
+
+/* Excluded from this release type: ILocalValue */
+
+/* Excluded from this release type: ISerializableValue */
+
+/* Excluded from this release type: ISerializedValue */
+
+/* Excluded from this release type: ISharedDirectory */
+
+/* Excluded from this release type: ISharedDirectoryEvents */
+
+/**
+ * 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/datastore#FluidObjectHandle}.
+ *
+ * For more information, including example usages, see {@link https://fluidframework.com/docs/data-structures/map/}.
+ * @sealed
+ * @public
+ */
+export declare interface ISharedMap extends ISharedObject<ISharedMapEvents>, Map<string, any> {
+    /**
+     * 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
+     */
+    get<T = any>(key: string): T | undefined;
+    /**
+     * Sets the value stored at key to the provided value.
+     * @param key - Key to set
+     * @param value - Value to set
+     * @returns The {@link ISharedMap} itself
+     */
+    set<T = unknown>(key: string, value: T): this;
+}
+
+/**
+ * Events emitted in response to changes to the {@link ISharedMap | map} data.
+ * @sealed
+ * @public
+ */
+export declare 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): any;
+    /**
+     * 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): any;
+}
+
+/**
+ * Type of "valueChanged" event parameter.
+ * @sealed
+ * @public
+ */
+export declare interface IValueChanged {
+    /**
+     * The key storing the value that changed.
+     */
+    key: string;
+    /**
+     * The value that was stored at the key prior to the change.
+     */
+    previousValue: any;
+}
+
+/* Excluded from this release type: LocalValueMaker */
+
+/* Excluded from this release type: MapFactory */
+
+/* Excluded from this release type: SharedDirectory */
+
+/**
+ * {@inheritDoc ISharedMap}
+ * @public
+ */
+export declare class SharedMap extends SharedObject<ISharedMapEvents> implements ISharedMap {
+    /**
+     * Create a new shared map.
+     * @param runtime - The data store runtime that the new shared map belongs to.
+     * @param id - Optional name of the shared map.
+     * @returns Newly created shared map.
+     *
+     * @example
+     * To create a `SharedMap`, call the static create method:
+     *
+     * ```typescript
+     * const myMap = SharedMap.create(this.runtime, id);
+     * ```
+     */
+    static create(runtime: IFluidDataStoreRuntime, id?: string): SharedMap;
+    /**
+     * Get a factory for SharedMap to register with the data store.
+     * @returns A factory that creates SharedMaps and loads them from storage.
+     */
+    static getFactory(): IChannelFactory;
+    /**
+     * String representation for the class.
+     */
+    readonly [Symbol.toStringTag]: string;
+    /**
+     * MapKernel which manages actual map operations.
+     */
+    private readonly kernel;
+    /**
+     * Do not call the constructor. Instead, you should use the {@link SharedMap.create | create method}.
+     *
+     * @param id - String identifier.
+     * @param runtime - Data store runtime.
+     * @param attributes - The attributes for the map.
+     */
+    constructor(id: string, runtime: IFluidDataStoreRuntime, attributes: IChannelAttributes);
+    /**
+     * Get an iterator over the keys in this map.
+     * @returns The iterator
+     */
+    keys(): IterableIterator<string>;
+    /**
+     * Get an iterator over the entries in this map.
+     * @returns The iterator
+     */
+    entries(): IterableIterator<[string, any]>;
+    /**
+     * Get an iterator over the values in this map.
+     * @returns The iterator
+     */
+    values(): IterableIterator<any>;
+    /**
+     * Get an iterator over the entries in this map.
+     * @returns The iterator
+     */
+    [Symbol.iterator](): IterableIterator<[string, any]>;
+    /**
+     * The number of key/value pairs stored in the map.
+     */
+    get size(): number;
+    /**
+     * Executes the given callback on each entry in the map.
+     * @param callbackFn - Callback function
+     */
+    forEach(callbackFn: (value: any, key: string, map: Map<string, any>) => void): void;
+    /**
+     * {@inheritDoc ISharedMap.get}
+     */
+    get<T = any>(key: string): T | undefined;
+    /**
+     * Check if a key exists in the map.
+     * @param key - The key to check
+     * @returns True if the key exists, false otherwise
+     */
+    has(key: string): boolean;
+    /**
+     * {@inheritDoc ISharedMap.set}
+     */
+    set(key: string, value: unknown): this;
+    /**
+     * Delete a key from the map.
+     * @param key - Key to delete
+     * @returns True if the key existed and was deleted, false if it did not exist
+     */
+    delete(key: string): boolean;
+    /**
+     * Clear all data from the map.
+     */
+    clear(): void;
+    /**
+     * {@inheritDoc @fluidframework/shared-object-base#SharedObject.summarizeCore}
+     */
+    protected summarizeCore(serializer: IFluidSerializer, telemetryContext?: ITelemetryContext): ISummaryTreeWithStats;
+    /**
+     * {@inheritDoc @fluidframework/shared-object-base#SharedObject.loadCore}
+     */
+    protected loadCore(storage: IChannelStorageService): Promise<void>;
+    /**
+     * {@inheritDoc @fluidframework/shared-object-base#SharedObject.onDisconnect}
+     */
+    protected onDisconnect(): void;
+    /**
+     * {@inheritDoc @fluidframework/shared-object-base#SharedObject.reSubmitCore}
+     */
+    protected reSubmitCore(content: unknown, localOpMetadata: unknown): void;
+    /**
+     * {@inheritDoc @fluidframework/shared-object-base#SharedObjectCore.applyStashedOp}
+     */
+    protected applyStashedOp(content: unknown): unknown;
+    /**
+     * {@inheritDoc @fluidframework/shared-object-base#SharedObject.processCore}
+     */
+    protected processCore(message: ISequencedDocumentMessage, local: boolean, localOpMetadata: unknown): void;
+    /**
+     * {@inheritDoc @fluidframework/shared-object-base#SharedObject.rollback}
+     */
+    protected rollback(content: unknown, localOpMetadata: unknown): void;
+}
+
+export { }

package/dist/map-public.d.ts

@@ -0,0 +1,275 @@
+/**
+ * The `map` library provides interfaces and implementing classes for map-like distributed data structures.
+ *
+ * @remarks The following distributed data structures are defined in this library:
+ *
+ * - {@link SharedMap}
+ *
+ * - {@link SharedDirectory}
+ *
+ * @packageDocumentation
+ */
+
+import { IChannelAttributes } from '@fluidframework/datastore-definitions';
+import { IChannelFactory } from '@fluidframework/datastore-definitions';
+import { IChannelServices } from '@fluidframework/datastore-definitions';
+import { IChannelStorageService } from '@fluidframework/datastore-definitions';
+import { IDisposable } from '@fluidframework/core-interfaces';
+import { IEvent } from '@fluidframework/core-interfaces';
+import { IEventProvider } from '@fluidframework/core-interfaces';
+import { IEventThisPlaceHolder } from '@fluidframework/core-interfaces';
+import { IFluidDataStoreRuntime } from '@fluidframework/datastore-definitions';
+import { IFluidHandle } from '@fluidframework/core-interfaces';
+import { IFluidSerializer } from '@fluidframework/shared-object-base';
+import { ISequencedDocumentMessage } from '@fluidframework/protocol-definitions';
+import { ISharedObject } from '@fluidframework/shared-object-base';
+import { ISharedObjectEvents } from '@fluidframework/shared-object-base';
+import { ISummaryTreeWithStats } from '@fluidframework/runtime-definitions';
+import { ITelemetryContext } from '@fluidframework/runtime-definitions';
+import { SharedObject } from '@fluidframework/shared-object-base';
+
+/* Excluded from this release type: DirectoryFactory */
+
+/* Excluded from this release type: ICreateInfo */
+
+/* Excluded from this release type: IDirectory */
+
+/* Excluded from this release type: IDirectoryClearOperation */
+
+/* Excluded from this release type: IDirectoryCreateSubDirectoryOperation */
+
+/* Excluded from this release type: IDirectoryDataObject */
+
+/* Excluded from this release type: IDirectoryDeleteOperation */
+
+/* Excluded from this release type: IDirectoryDeleteSubDirectoryOperation */
+
+/* Excluded from this release type: IDirectoryEvents */
+
+/* Excluded from this release type: IDirectoryKeyOperation */
+
+/* Excluded from this release type: IDirectoryNewStorageFormat */
+
+/* Excluded from this release type: IDirectoryOperation */
+
+/* Excluded from this release type: IDirectorySetOperation */
+
+/* Excluded from this release type: IDirectoryStorageOperation */
+
+/* Excluded from this release type: IDirectorySubDirectoryOperation */
+
+/* Excluded from this release type: IDirectoryValueChanged */
+
+/* Excluded from this release type: ILocalValue */
+
+/* Excluded from this release type: ISerializableValue */
+
+/* Excluded from this release type: ISerializedValue */
+
+/* Excluded from this release type: ISharedDirectory */
+
+/* Excluded from this release type: ISharedDirectoryEvents */
+
+/**
+ * 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/datastore#FluidObjectHandle}.
+ *
+ * For more information, including example usages, see {@link https://fluidframework.com/docs/data-structures/map/}.
+ * @sealed
+ * @public
+ */
+export declare interface ISharedMap extends ISharedObject<ISharedMapEvents>, Map<string, any> {
+    /**
+     * 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
+     */
+    get<T = any>(key: string): T | undefined;
+    /**
+     * Sets the value stored at key to the provided value.
+     * @param key - Key to set
+     * @param value - Value to set
+     * @returns The {@link ISharedMap} itself
+     */
+    set<T = unknown>(key: string, value: T): this;
+}
+
+/**
+ * Events emitted in response to changes to the {@link ISharedMap | map} data.
+ * @sealed
+ * @public
+ */
+export declare 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): any;
+    /**
+     * 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): any;
+}
+
+/**
+ * Type of "valueChanged" event parameter.
+ * @sealed
+ * @public
+ */
+export declare interface IValueChanged {
+    /**
+     * The key storing the value that changed.
+     */
+    key: string;
+    /**
+     * The value that was stored at the key prior to the change.
+     */
+    previousValue: any;
+}
+
+/* Excluded from this release type: LocalValueMaker */
+
+/* Excluded from this release type: MapFactory */
+
+/* Excluded from this release type: SharedDirectory */
+
+/**
+ * {@inheritDoc ISharedMap}
+ * @public
+ */
+export declare class SharedMap extends SharedObject<ISharedMapEvents> implements ISharedMap {
+    /**
+     * Create a new shared map.
+     * @param runtime - The data store runtime that the new shared map belongs to.
+     * @param id - Optional name of the shared map.
+     * @returns Newly created shared map.
+     *
+     * @example
+     * To create a `SharedMap`, call the static create method:
+     *
+     * ```typescript
+     * const myMap = SharedMap.create(this.runtime, id);
+     * ```
+     */
+    static create(runtime: IFluidDataStoreRuntime, id?: string): SharedMap;
+    /**
+     * Get a factory for SharedMap to register with the data store.
+     * @returns A factory that creates SharedMaps and loads them from storage.
+     */
+    static getFactory(): IChannelFactory;
+    /**
+     * String representation for the class.
+     */
+    readonly [Symbol.toStringTag]: string;
+    /**
+     * MapKernel which manages actual map operations.
+     */
+    private readonly kernel;
+    /**
+     * Do not call the constructor. Instead, you should use the {@link SharedMap.create | create method}.
+     *
+     * @param id - String identifier.
+     * @param runtime - Data store runtime.
+     * @param attributes - The attributes for the map.
+     */
+    constructor(id: string, runtime: IFluidDataStoreRuntime, attributes: IChannelAttributes);
+    /**
+     * Get an iterator over the keys in this map.
+     * @returns The iterator
+     */
+    keys(): IterableIterator<string>;
+    /**
+     * Get an iterator over the entries in this map.
+     * @returns The iterator
+     */
+    entries(): IterableIterator<[string, any]>;
+    /**
+     * Get an iterator over the values in this map.
+     * @returns The iterator
+     */
+    values(): IterableIterator<any>;
+    /**
+     * Get an iterator over the entries in this map.
+     * @returns The iterator
+     */
+    [Symbol.iterator](): IterableIterator<[string, any]>;
+    /**
+     * The number of key/value pairs stored in the map.
+     */
+    get size(): number;
+    /**
+     * Executes the given callback on each entry in the map.
+     * @param callbackFn - Callback function
+     */
+    forEach(callbackFn: (value: any, key: string, map: Map<string, any>) => void): void;
+    /**
+     * {@inheritDoc ISharedMap.get}
+     */
+    get<T = any>(key: string): T | undefined;
+    /**
+     * Check if a key exists in the map.
+     * @param key - The key to check
+     * @returns True if the key exists, false otherwise
+     */
+    has(key: string): boolean;
+    /**
+     * {@inheritDoc ISharedMap.set}
+     */
+    set(key: string, value: unknown): this;
+    /**
+     * Delete a key from the map.
+     * @param key - Key to delete
+     * @returns True if the key existed and was deleted, false if it did not exist
+     */
+    delete(key: string): boolean;
+    /**
+     * Clear all data from the map.
+     */
+    clear(): void;
+    /**
+     * {@inheritDoc @fluidframework/shared-object-base#SharedObject.summarizeCore}
+     */
+    protected summarizeCore(serializer: IFluidSerializer, telemetryContext?: ITelemetryContext): ISummaryTreeWithStats;
+    /**
+     * {@inheritDoc @fluidframework/shared-object-base#SharedObject.loadCore}
+     */
+    protected loadCore(storage: IChannelStorageService): Promise<void>;
+    /**
+     * {@inheritDoc @fluidframework/shared-object-base#SharedObject.onDisconnect}
+     */
+    protected onDisconnect(): void;
+    /**
+     * {@inheritDoc @fluidframework/shared-object-base#SharedObject.reSubmitCore}
+     */
+    protected reSubmitCore(content: unknown, localOpMetadata: unknown): void;
+    /**
+     * {@inheritDoc @fluidframework/shared-object-base#SharedObjectCore.applyStashedOp}
+     */
+    protected applyStashedOp(content: unknown): unknown;
+    /**
+     * {@inheritDoc @fluidframework/shared-object-base#SharedObject.processCore}
+     */
+    protected processCore(message: ISequencedDocumentMessage, local: boolean, localOpMetadata: unknown): void;
+    /**
+     * {@inheritDoc @fluidframework/shared-object-base#SharedObject.rollback}
+     */
+    protected rollback(content: unknown, localOpMetadata: unknown): void;
+}
+
+export { }