@fluidframework/map 2.0.0-rc.2.0.1 → 2.0.0-rc.3.0.0

package/src/directory.ts

@@ -3,41 +3,38 @@
  * Licensed under the MIT License.
  */
 
-import { assert, unreachableCase } from "@fluidframework/core-utils";
 import { TypedEventEmitter } from "@fluid-internal/client-utils";
-import { ITelemetryLoggerExt, UsageError } from "@fluidframework/telemetry-utils";
-import { readAndParse } from "@fluidframework/driver-utils";
-import { ISequencedDocumentMessage, MessageType } from "@fluidframework/protocol-definitions";
+import { assert, unreachableCase } from "@fluidframework/core-utils/internal";
 import {
 	IChannelAttributes,
-	IFluidDataStoreRuntime,
 	IChannelStorageService,
-	IChannelServices,
-	IChannelFactory,
+	IFluidDataStoreRuntime,
 } from "@fluidframework/datastore-definitions";
+import { readAndParse } from "@fluidframework/driver-utils/internal";
+import { RedBlackTree } from "@fluidframework/merge-tree/internal";
+import { ISequencedDocumentMessage, MessageType } from "@fluidframework/protocol-definitions";
 import { ISummaryTreeWithStats, ITelemetryContext } from "@fluidframework/runtime-definitions";
-import {
-	IFluidSerializer,
-	SharedObject,
-	ValueType,
-	parseHandles,
-} from "@fluidframework/shared-object-base";
-import { SummaryTreeBuilder } from "@fluidframework/runtime-utils";
+import { SummaryTreeBuilder } from "@fluidframework/runtime-utils/internal";
+import { IFluidSerializer } from "@fluidframework/shared-object-base";
+import { SharedObject, ValueType, parseHandles } from "@fluidframework/shared-object-base/internal";
+import { ITelemetryLoggerExt } from "@fluidframework/telemetry-utils";
+import { UsageError } from "@fluidframework/telemetry-utils/internal";
 import path from "path-browserify";
-import { RedBlackTree } from "@fluidframework/merge-tree";
+
 import {
 	IDirectory,
 	IDirectoryEvents,
 	IDirectoryValueChanged,
-	// eslint-disable-next-line import/no-deprecated
-	ISerializableValue,
-	ISerializedValue,
 	ISharedDirectory,
 	ISharedDirectoryEvents,
 	IValueChanged,
 } from "./interfaces.js";
+import {
+	// eslint-disable-next-line import/no-deprecated
+	ISerializableValue,
+	ISerializedValue,
+} from "./internalInterfaces.js";
 import { ILocalValue, LocalValueMaker, makeSerializable } from "./localValues.js";
-import { pkgVersion } from "./packageVersion.js";
 
 // We use path-browserify since this code can run safely on the server or the browser.
 // We standardize on using posix slashes everywhere.
@@ -268,67 +265,6 @@ export interface IDirectoryNewStorageFormat {
 	content: IDirectoryDataObject;
 }
 
-/**
- * {@link @fluidframework/datastore-definitions#IChannelFactory} for {@link SharedDirectory}.
- *
- * @sealed
- * @alpha
- */
-export class DirectoryFactory implements IChannelFactory<ISharedDirectory> {
-	/**
-	 * {@inheritDoc @fluidframework/datastore-definitions#IChannelFactory."type"}
-	 */
-	public static readonly Type = "https://graph.microsoft.com/types/directory";
-
-	/**
-	 * {@inheritDoc @fluidframework/datastore-definitions#IChannelFactory.attributes}
-	 */
-	public static readonly Attributes: IChannelAttributes = {
-		type: DirectoryFactory.Type,
-		snapshotFormatVersion: "0.1",
-		packageVersion: pkgVersion,
-	};
-
-	/**
-	 * {@inheritDoc @fluidframework/datastore-definitions#IChannelFactory."type"}
-	 */
-	public get type(): string {
-		return DirectoryFactory.Type;
-	}
-
-	/**
-	 * {@inheritDoc @fluidframework/datastore-definitions#IChannelFactory.attributes}
-	 */
-	public get attributes(): IChannelAttributes {
-		return DirectoryFactory.Attributes;
-	}
-
-	/**
-	 * {@inheritDoc @fluidframework/datastore-definitions#IChannelFactory.load}
-	 */
-	public async load(
-		runtime: IFluidDataStoreRuntime,
-		id: string,
-		services: IChannelServices,
-		attributes: IChannelAttributes,
-	): Promise<ISharedDirectory> {
-		const directory = new SharedDirectory(id, runtime, attributes);
-		await directory.load(services);
-
-		return directory;
-	}
-
-	/**
-	 * {@inheritDoc @fluidframework/datastore-definitions#IChannelFactory.create}
-	 */
-	public create(runtime: IFluidDataStoreRuntime, id: string): ISharedDirectory {
-		const directory = new SharedDirectory(id, runtime, DirectoryFactory.Attributes);
-		directory.initializeLocal();
-
-		return directory;
-	}
-}
-
 /**
  * The comparator essentially performs the following procedure to determine the order of subdirectory creation:
  * 1. If subdirectory A has a non-negative 'seq' and subdirectory B has a negative 'seq', subdirectory A is always placed first due to
@@ -460,26 +396,6 @@ export class SharedDirectory
 	extends SharedObject<ISharedDirectoryEvents>
 	implements ISharedDirectory
 {
-	/**
-	 * Create a new shared directory
-	 *
-	 * @param runtime - Data store runtime the new shared directory belongs to
-	 * @param id - Optional name of the shared directory
-	 * @returns Newly create shared directory (but not attached yet)
-	 */
-	public static create(runtime: IFluidDataStoreRuntime, id?: string): ISharedDirectory {
-		return runtime.createChannel(id, DirectoryFactory.Type) as ISharedDirectory;
-	}
-
-	/**
-	 * Get a factory for SharedDirectory to register with the data store.
-	 *
-	 * @returns A factory that creates and load SharedDirectory
-	 */
-	public static getFactory(): IChannelFactory<ISharedDirectory> {
-		return new DirectoryFactory();
-	}
-
 	/**
 	 * String representation for the class.
 	 */

package/src/directoryFactory.ts

@@ -0,0 +1,120 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import type {
+	IChannelAttributes,
+	IChannelFactory,
+	IChannelServices,
+	IFluidDataStoreRuntime,
+} from "@fluidframework/datastore-definitions";
+import type { ISharedObjectKind } from "@fluidframework/shared-object-base";
+
+import { SharedDirectory as SharedDirectoryInternal } from "./directory.js";
+import type { ISharedDirectory } from "./interfaces.js";
+import { pkgVersion } from "./packageVersion.js";
+
+/**
+ * {@link @fluidframework/datastore-definitions#IChannelFactory} for {@link ISharedDirectory}.
+ *
+ * @sealed
+ * @alpha
+ */
+export class DirectoryFactory implements IChannelFactory<ISharedDirectory> {
+	/**
+	 * {@inheritDoc @fluidframework/datastore-definitions#IChannelFactory."type"}
+	 */
+	public static readonly Type = "https://graph.microsoft.com/types/directory";
+
+	/**
+	 * {@inheritDoc @fluidframework/datastore-definitions#IChannelFactory.attributes}
+	 */
+	public static readonly Attributes: IChannelAttributes = {
+		type: DirectoryFactory.Type,
+		snapshotFormatVersion: "0.1",
+		packageVersion: pkgVersion,
+	};
+
+	/**
+	 * {@inheritDoc @fluidframework/datastore-definitions#IChannelFactory."type"}
+	 */
+	public get type(): string {
+		return DirectoryFactory.Type;
+	}
+
+	/**
+	 * {@inheritDoc @fluidframework/datastore-definitions#IChannelFactory.attributes}
+	 */
+	public get attributes(): IChannelAttributes {
+		return DirectoryFactory.Attributes;
+	}
+
+	/**
+	 * {@inheritDoc @fluidframework/datastore-definitions#IChannelFactory.load}
+	 */
+	public async load(
+		runtime: IFluidDataStoreRuntime,
+		id: string,
+		services: IChannelServices,
+		attributes: IChannelAttributes,
+	): Promise<ISharedDirectory> {
+		const directory = new SharedDirectoryInternal(id, runtime, attributes);
+		await directory.load(services);
+
+		return directory;
+	}
+
+	/**
+	 * {@inheritDoc @fluidframework/datastore-definitions#IChannelFactory.create}
+	 */
+	public create(runtime: IFluidDataStoreRuntime, id: string): ISharedDirectory {
+		const directory = new SharedDirectoryInternal(id, runtime, DirectoryFactory.Attributes);
+		directory.initializeLocal();
+
+		return directory;
+	}
+}
+
+/**
+ * Entrypoint for {@link ISharedDirectory} creation.
+ * @sealed
+ * @alpha
+ */
+export const SharedDirectory: ISharedObjectKind<ISharedDirectory> = {
+	/**
+	 * Create a new shared directory
+	 *
+	 * @param runtime - Data store runtime the new shared directory belongs to
+	 * @param id - Optional name of the shared directory
+	 * @returns Newly create shared directory (but not attached yet)
+	 *
+	 * @example
+	 * To create a `SharedDirectory`, call the static create method:
+	 *
+	 * ```typescript
+	 * const myDirectory = SharedDirectory.create(this.runtime, id);
+	 * ```
+	 */
+	create(runtime: IFluidDataStoreRuntime, id?: string): ISharedDirectory {
+		return runtime.createChannel(id, DirectoryFactory.Type) as ISharedDirectory;
+	},
+
+	/**
+	 * Get a factory for SharedDirectory to register with the data store.
+	 *
+	 * @returns A factory that creates and load SharedDirectory
+	 */
+	getFactory(): IChannelFactory<ISharedDirectory> {
+		return new DirectoryFactory();
+	},
+};
+
+/**
+ * Entrypoint for {@link ISharedDirectory} creation.
+ * @alpha
+ * @deprecated Use ISharedDirectory instead.
+ * @privateRemarks
+ * This alias is for legacy compat from when the SharedDirectory class was exported as public.
+ */
+export type SharedDirectory = ISharedDirectory;

package/src/index.ts

@@ -15,86 +15,15 @@
  * @packageDocumentation
  */
 
-export {
-	DirectoryFactory,
-	ICreateInfo,
-	IDirectoryClearOperation,
-	IDirectoryCreateSubDirectoryOperation,
-	IDirectoryDataObject,
-	IDirectoryDeleteOperation,
-	IDirectoryDeleteSubDirectoryOperation,
-	IDirectoryKeyOperation,
-	IDirectoryNewStorageFormat,
-	IDirectoryOperation,
-	IDirectorySetOperation,
-	IDirectoryStorageOperation,
-	IDirectorySubDirectoryOperation,
-	SharedDirectory,
-} from "./directory.js";
 export {
 	IDirectory,
 	IDirectoryEvents,
 	IDirectoryValueChanged,
-	ISerializableValue,
-	ISerializedValue,
 	ISharedDirectory,
 	ISharedDirectoryEvents,
 	ISharedMap,
 	ISharedMapEvents,
 	IValueChanged,
 } from "./interfaces.js";
-export { LocalValueMaker, ILocalValue } from "./localValues.js";
-export { MapFactory } from "./map.js";
-
-import type {
-	IChannelFactory,
-	IFluidDataStoreRuntime,
-} from "@fluidframework/datastore-definitions";
-import { MapFactory } from "./map.js";
-import { ISharedMap } from "./interfaces.js";
-
-/**
- * {@inheritDoc ISharedMap}
- * @public
- * @deprecated Please use SharedTree for new containers.  SharedMap is supported for loading preexisting Fluid Framework 1.0 containers only.
- */
-export const SharedMap = {
-	/**
-	 * Get a factory for SharedMap to register with the data store.
-	 * @returns A factory that creates SharedMaps and loads them from storage.
-	 */
-	getFactory(): IChannelFactory<ISharedMap> {
-		return new MapFactory();
-	},
-
-	/**
-	 * 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);
-	 * ```
-	 * @privateRemarks
-	 * TODO:
-	 * Clarify how this differs from `MapFactory.create`.
-	 * They are different since making this forward to MapFactory.create breaks some things,
-	 * but the difference is unclear from the documentation.
-	 */
-	create(runtime: IFluidDataStoreRuntime, id?: string): ISharedMap {
-		return runtime.createChannel(id, MapFactory.Type) as ISharedMap;
-	},
-};
-
-/**
- * {@inheritDoc ISharedMap}
- * @public
- * @deprecated Use ISharedMap instead.
- * @privateRemarks
- * This alias is for legacy compat from when the SharedMap class was exported as public.
- */
-export type SharedMap = ISharedMap;
+export { MapFactory, SharedMap } from "./mapFactory.js";
+export { DirectoryFactory, SharedDirectory } from "./directoryFactory.js";

package/src/interfaces.ts

@@ -3,31 +3,31 @@
  * Licensed under the MIT License.
  */
 
-import { ISharedObject, ISharedObjectEvents } from "@fluidframework/shared-object-base";
 import {
 	IDisposable,
 	IEvent,
 	IEventProvider,
 	IEventThisPlaceHolder,
 } from "@fluidframework/core-interfaces";
+import { ISharedObject, ISharedObjectEvents } from "@fluidframework/shared-object-base";
 
 /**
  * Type of "valueChanged" event parameter.
  * @sealed
- * @public
+ * @alpha
  */
 export interface IValueChanged {
 	/**
 	 * The key storing the value that changed.
 	 */
-	key: string;
+	readonly key: string;
 
 	/**
 	 * The value that was stored at the key prior to the change.
 	 */
 	// TODO: Use `unknown` instead (breaking change).
 	// eslint-disable-next-line @typescript-eslint/no-explicit-any
-	previousValue: any;
+	readonly previousValue: any;
 }
 
 /**
@@ -196,7 +196,7 @@ export interface ISharedDirectoryEvents extends ISharedObjectEvents {
 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
+	 * {@link ISharedDirectory}'s valueChanged event, this is emitted only on the {@link IDirectory} that directly
 	 * contains the key.
 	 *
 	 * @remarks Listener parameters:
@@ -299,7 +299,7 @@ export interface IDirectoryValueChanged extends IValueChanged {
 /**
  * Events emitted in response to changes to the {@link ISharedMap | map} data.
  * @sealed
- * @public
+ * @alpha
  */
 export interface ISharedMapEvents extends ISharedObjectEvents {
 	/**
@@ -339,7 +339,7 @@ export interface ISharedMapEvents extends ISharedObjectEvents {
  *
  * For more information, including example usages, see {@link https://fluidframework.com/docs/data-structures/map/}.
  * @sealed
- * @public
+ * @alpha
  */
 // TODO: Use `unknown` instead (breaking change).
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -361,58 +361,3 @@ export interface ISharedMap extends ISharedObject<ISharedMapEvents>, Map<string,
 	 */
 	set<T = unknown>(key: string, value: T): this;
 }
-
-/**
- * The _ready-for-serialization_ format of values contained in DDS contents. This allows us to use
- * {@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
- *
- * Note that the in-memory equivalent of ISerializableValue is ILocalValue (similarly holding a type, but with
- * 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.
- *
- * @deprecated This type is legacy and deprecated.
- * @alpha
- */
-export interface ISerializableValue {
-	/**
-	 * A type annotation to help indicate how the value serializes.
-	 */
-	type: string;
-
-	/**
-	 * The JSONable representation of the value.
-	 */
-	// eslint-disable-next-line @typescript-eslint/no-explicit-any
-	value: any;
-}
-
-/**
- * Serialized {@link ISerializableValue} counterpart.
- * @alpha
- */
-export interface ISerializedValue {
-	/**
-	 * A type annotation to help indicate how the value serializes.
-	 */
-	type: string;
-
-	/**
-	 * String representation of the value.
-	 *
-	 * @remarks Will be undefined if the original value was undefined.
-	 */
-	value: string | undefined;
-}

package/src/internalInterfaces.ts

@@ -3,8 +3,6 @@
  * Licensed under the MIT License.
  */
 
-// eslint-disable-next-line import/no-deprecated
-import { ISerializableValue } from "./interfaces.js";
 import { ILocalValue } from "./localValues.js";
 
 /**
@@ -117,3 +115,58 @@ export type MapKeyLocalOpMetadata = IMapKeyEditLocalOpMetadata | IMapKeyAddLocal
  * Metadata for a local operation.
  */
 export type MapLocalOpMetadata = IMapClearLocalOpMetadata | MapKeyLocalOpMetadata;
+
+/**
+ * The _ready-for-serialization_ format of values contained in DDS contents. This allows us to use
+ * {@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
+ *
+ * Note that the in-memory equivalent of ISerializableValue is ILocalValue (similarly holding a type, but with
+ * 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.
+ *
+ * @deprecated This type is legacy and deprecated.
+ * @alpha
+ */
+export interface ISerializableValue {
+	/**
+	 * A type annotation to help indicate how the value serializes.
+	 */
+	type: string;
+
+	/**
+	 * The JSONable representation of the value.
+	 */
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	value: any;
+}
+
+/**
+ * Serialized {@link ISerializableValue} counterpart.
+ * @alpha
+ */
+export interface ISerializedValue {
+	/**
+	 * A type annotation to help indicate how the value serializes.
+	 */
+	type: string;
+
+	/**
+	 * String representation of the value.
+	 *
+	 * @remarks Will be undefined if the original value was undefined.
+	 */
+	value: string | undefined;
+}

package/src/localValues.ts

@@ -4,15 +4,16 @@
  */
 
 import { IFluidHandle } from "@fluidframework/core-interfaces";
+import { ISerializedHandle } from "@fluidframework/runtime-utils/internal";
+import { IFluidSerializer } from "@fluidframework/shared-object-base";
 import {
-	IFluidSerializer,
+	ValueType,
 	parseHandles,
 	serializeHandles,
-	ValueType,
-} from "@fluidframework/shared-object-base";
-import { ISerializedHandle } from "@fluidframework/runtime-utils";
+} from "@fluidframework/shared-object-base/internal";
+
 // eslint-disable-next-line import/no-deprecated
-import { ISerializableValue, ISerializedValue } from "./interfaces.js";
+import { ISerializableValue, ISerializedValue } from "./internalInterfaces.js";
 
 /**
  * A local value to be stored in a container type Distributed Data Store (DDS).

package/src/map.ts

@@ -3,21 +3,20 @@
  * Licensed under the MIT License.
  */
 
-import { ISequencedDocumentMessage, MessageType } from "@fluidframework/protocol-definitions";
 import {
 	IChannelAttributes,
-	IFluidDataStoreRuntime,
 	IChannelStorageService,
-	IChannelServices,
-	IChannelFactory,
+	IFluidDataStoreRuntime,
 } from "@fluidframework/datastore-definitions";
+import { readAndParse } from "@fluidframework/driver-utils/internal";
+import { ISequencedDocumentMessage, MessageType } from "@fluidframework/protocol-definitions";
 import { ISummaryTreeWithStats, ITelemetryContext } from "@fluidframework/runtime-definitions";
-import { readAndParse } from "@fluidframework/driver-utils";
-import { IFluidSerializer, SharedObject } from "@fluidframework/shared-object-base";
-import { SummaryTreeBuilder } from "@fluidframework/runtime-utils";
+import { SummaryTreeBuilder } from "@fluidframework/runtime-utils/internal";
+import { IFluidSerializer } from "@fluidframework/shared-object-base";
+import { SharedObject } from "@fluidframework/shared-object-base/internal";
+
 import { ISharedMap, ISharedMapEvents } from "./interfaces.js";
 import { IMapDataObjectSerializable, IMapOperation, MapKernel } from "./mapKernel.js";
-import { pkgVersion } from "./packageVersion.js";
 
 interface IMapSerializationFormat {
 	blobs?: string[];
@@ -26,71 +25,9 @@ interface IMapSerializationFormat {
 
 const snapshotFileName = "header";
 
-/**
- * {@link @fluidframework/datastore-definitions#IChannelFactory} for {@link ISharedMap}.
- *
- * @sealed
- * @alpha
- */
-export class MapFactory implements IChannelFactory<ISharedMap> {
-	/**
-	 * {@inheritDoc @fluidframework/datastore-definitions#IChannelFactory."type"}
-	 */
-	public static readonly Type = "https://graph.microsoft.com/types/map";
-
-	/**
-	 * {@inheritDoc @fluidframework/datastore-definitions#IChannelFactory.attributes}
-	 */
-	public static readonly Attributes: IChannelAttributes = {
-		type: MapFactory.Type,
-		snapshotFormatVersion: "0.2",
-		packageVersion: pkgVersion,
-	};
-
-	/**
-	 * {@inheritDoc @fluidframework/datastore-definitions#IChannelFactory."type"}
-	 */
-	public get type(): string {
-		return MapFactory.Type;
-	}
-
-	/**
-	 * {@inheritDoc @fluidframework/datastore-definitions#IChannelFactory.attributes}
-	 */
-	public get attributes(): IChannelAttributes {
-		return MapFactory.Attributes;
-	}
-
-	/**
-	 * {@inheritDoc @fluidframework/datastore-definitions#IChannelFactory.load}
-	 */
-	public async load(
-		runtime: IFluidDataStoreRuntime,
-		id: string,
-		services: IChannelServices,
-		attributes: IChannelAttributes,
-	): Promise<ISharedMap> {
-		const map = new SharedMap(id, runtime, attributes);
-		await map.load(services);
-
-		return map;
-	}
-
-	/**
-	 * {@inheritDoc @fluidframework/datastore-definitions#IChannelFactory.create}
-	 */
-	public create(runtime: IFluidDataStoreRuntime, id: string): ISharedMap {
-		const map = new SharedMap(id, runtime, MapFactory.Attributes);
-		map.initializeLocal();
-
-		return map;
-	}
-}
-
 /**
  * {@inheritDoc ISharedMap}
- * @public
- * @deprecated Please use SharedTree for new containers.  SharedMap is supported for loading preexisting Fluid Framework 1.0 containers only.
+ * @alpha
  */
 export class SharedMap extends SharedObject<ISharedMapEvents> implements ISharedMap {
 	/**