docs(client): update stability of map APIs (#21836)

where possible without running into those that should not be stabilized (committed to). Additionally, apply `@sealed` and `@readonly` doc tags.
microsoft · Jul 15, 2024 · b1d0427 · b1d0427
1 parent 38a6ea0
commit b1d0427
Show file tree

Hide file tree

Showing 6 changed files with 106 additions and 16 deletions.
diff --git a/.changeset/khaki-hairs-vanish.md b/.changeset/khaki-hairs-vanish.md
@@ -0,0 +1,14 @@
+---
+"fluid-framework": patch
+"@fluidframework/map": patch
+---
+
+Map API documentation updates
+
+Remaining top-level APIs within `@fluidframework/map` have had docs updated to reflect their sealed/readonly nature, i.e. they are not to be implemented externally to Fluid Framework and not changed, as has already been the case. Impacted APIs:
+- [IDirectory](https://fluidframework.com/docs/api/v2/fluid-framework/idirectory-interface) sealed
+- [IDirectoryEvents](https://fluidframework.com/docs/api/v2/fluid-framework/idirectoryevents-interface) sealed
+- [IDirectoryValueChanged](https://fluidframework.com/docs/api/v2/fluid-framework/idirectoryvaluechanged-interface) sealed and path property is readonly
+- [ISharedDirectory](https://fluidframework.com/docs/api/v2/fluid-framework/ishareddirectory-interface) sealed
+- [ISharedDirectoryEvents](https://fluidframework.com/docs/api/v2/fluid-framework/ishareddirectoryevents-interface) sealed
+- [IValueChanged](https://fluidframework.com/docs/api/v2/fluid-framework/ivaluechanged-interface) sealed
diff --git a/packages/dds/map/api-report/map.legacy.alpha.api.md b/packages/dds/map/api-report/map.legacy.alpha.api.md
@@ -20,7 +20,7 @@ export interface ICreateInfo {
     csn: number;
 }
 
-// @alpha
+// @public @sealed
 export interface IDirectory extends Map<string, any>, IEventProvider<IDirectoryEvents>, Partial<IDisposable> {
     readonly absolutePath: string;
     countSubDirectory?(): number;
@@ -41,7 +41,7 @@ export interface IDirectoryDataObject {
     subdirectories?: Record<string, IDirectoryDataObject>;
 }
 
-// @alpha
+// @public @sealed
 export interface IDirectoryEvents extends IEvent {
     (event: "containedValueChanged", listener: (changed: IValueChanged, local: boolean, target: IEventThisPlaceHolder) => void): any;
     (event: "subDirectoryCreated", listener: (path: string, local: boolean, target: IEventThisPlaceHolder) => void): any;
@@ -56,7 +56,7 @@ export interface IDirectoryNewStorageFormat {
     content: IDirectoryDataObject;
 }
 
-// @alpha
+// @public @sealed
 export interface IDirectoryValueChanged extends IValueChanged {
     path: string;
 }
@@ -67,15 +67,15 @@ export interface ISerializableValue {
     value: any;
 }
 
-// @alpha
+// @alpha @sealed
 export interface ISharedDirectory extends ISharedObject<ISharedDirectoryEvents & IDirectoryEvents>, Omit<IDirectory, "on" | "once" | "off"> {
     // (undocumented)
     [Symbol.iterator](): IterableIterator<[string, any]>;
     // (undocumented)
     readonly [Symbol.toStringTag]: string;
 }
 
-// @alpha
+// @alpha @sealed
 export interface ISharedDirectoryEvents extends ISharedObjectEvents {
     (event: "valueChanged", listener: (changed: IDirectoryValueChanged, local: boolean, target: IEventThisPlaceHolder) => void): any;
     (event: "clear", listener: (local: boolean, target: IEventThisPlaceHolder) => void): any;
@@ -95,7 +95,7 @@ export interface ISharedMapEvents extends ISharedObjectEvents {
     (event: "clear", listener: (local: boolean, target: IEventThisPlaceHolder) => void): any;
 }
 
-// @alpha @sealed
+// @public @sealed
 export interface IValueChanged {
     readonly key: string;
     readonly previousValue: any;

diff --git a/packages/dds/map/api-report/map.legacy.public.api.md b/packages/dds/map/api-report/map.legacy.public.api.md
@@ -4,4 +4,38 @@
 
 ```ts
 
+// @public @sealed
+export interface IDirectory extends Map<string, any>, IEventProvider<IDirectoryEvents>, Partial<IDisposable> {
+    readonly absolutePath: string;
+    countSubDirectory?(): number;
+    createSubDirectory(subdirName: string): IDirectory;
+    deleteSubDirectory(subdirName: string): boolean;
+    get<T = any>(key: string): T | undefined;
+    getSubDirectory(subdirName: string): IDirectory | undefined;
+    getWorkingDirectory(relativePath: string): IDirectory | undefined;
+    hasSubDirectory(subdirName: string): boolean;
+    set<T = unknown>(key: string, value: T): this;
+    subdirectories(): IterableIterator<[string, IDirectory]>;
+}
+
+// @public @sealed
+export interface IDirectoryEvents extends IEvent {
+    (event: "containedValueChanged", listener: (changed: IValueChanged, local: boolean, target: IEventThisPlaceHolder) => void): any;
+    (event: "subDirectoryCreated", listener: (path: string, local: boolean, target: IEventThisPlaceHolder) => void): any;
+    (event: "subDirectoryDeleted", listener: (path: string, local: boolean, target: IEventThisPlaceHolder) => void): any;
+    (event: "disposed", listener: (target: IEventThisPlaceHolder) => void): any;
+    (event: "undisposed", listener: (target: IEventThisPlaceHolder) => void): any;
+}
+
+// @public @sealed
+export interface IDirectoryValueChanged extends IValueChanged {
+    path: string;
+}
+
+// @public @sealed
+export interface IValueChanged {
+    readonly key: string;
+    readonly previousValue: any;
+}
+
 ```
diff --git a/packages/dds/map/src/interfaces.ts b/packages/dds/map/src/interfaces.ts
@@ -18,7 +18,7 @@ import type {
  * Type of "valueChanged" event parameter.
  * @sealed
  * @legacy
- * @alpha
+ * @public
  */
 export interface IValueChanged {
 	/**
@@ -38,8 +38,9 @@ export interface IValueChanged {
  * Interface describing actions on a directory.
  *
  * @remarks When used as a Map, operates on its keys.
+ * @sealed
  * @legacy
- * @alpha
+ * @public
  */
 export interface IDirectory
 	// TODO: Use `unknown` instead (breaking change).
@@ -123,6 +124,7 @@ export interface IDirectory
  *
  * @remarks
  * These events only emit on the {@link ISharedDirectory} itself, and not on subdirectories.
+ * @sealed
  * @legacy
  * @alpha
  */
@@ -197,8 +199,9 @@ export interface ISharedDirectoryEvents extends ISharedObjectEvents {
 
 /**
  * Events emitted in response to changes to the directory data.
+ * @sealed
  * @legacy
- * @alpha
+ * @public
  */
 export interface IDirectoryEvents extends IEvent {
 	/**
@@ -279,6 +282,7 @@ export interface IDirectoryEvents extends IEvent {
  * 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.
+ * @sealed
  * @legacy
  * @alpha
  */
@@ -295,12 +299,16 @@ export interface ISharedDirectory
 
 /**
  * Type of "valueChanged" event parameter for {@link ISharedDirectory}.
+ * @sealed
  * @legacy
- * @alpha
+ * @public
  */
 export interface IDirectoryValueChanged extends IValueChanged {
 	/**
 	 * The absolute path to the IDirectory storing the key which changed.
+	 * @readonly
+	 * @privateRemarks
+	 * When breaking changes can be made, `readonly` should be added.
 	 */
 	path: string;
 }

diff --git a/packages/framework/fluid-framework/api-report/fluid-framework.legacy.alpha.api.md b/packages/framework/fluid-framework/api-report/fluid-framework.legacy.alpha.api.md
@@ -148,7 +148,7 @@ export interface IConnection {
 // @public
 export type ICriticalContainerError = IErrorBase;
 
-// @alpha
+// @public @sealed
 export interface IDirectory extends Map<string, any>, IEventProvider<IDirectoryEvents>, Partial<IDisposable> {
     readonly absolutePath: string;
     countSubDirectory?(): number;
@@ -162,7 +162,7 @@ export interface IDirectory extends Map<string, any>, IEventProvider<IDirectoryE
     subdirectories(): IterableIterator<[string, IDirectory]>;
 }
 
-// @alpha
+// @public @sealed
 export interface IDirectoryEvents extends IEvent {
     (event: "containedValueChanged", listener: (changed: IValueChanged, local: boolean, target: IEventThisPlaceHolder) => void): any;
     (event: "subDirectoryCreated", listener: (path: string, local: boolean, target: IEventThisPlaceHolder) => void): any;
@@ -171,7 +171,7 @@ export interface IDirectoryEvents extends IEvent {
     (event: "undisposed", listener: (target: IEventThisPlaceHolder) => void): any;
 }
 
-// @alpha
+// @public @sealed
 export interface IDirectoryValueChanged extends IValueChanged {
     path: string;
 }
@@ -682,15 +682,15 @@ export interface IServiceAudienceEvents<M extends IMember> extends IEvent {
     (event: "memberRemoved", listener: MemberChangedListener<M>): void;
 }
 
-// @alpha
+// @alpha @sealed
 export interface ISharedDirectory extends ISharedObject<ISharedDirectoryEvents & IDirectoryEvents>, Omit<IDirectory, "on" | "once" | "off"> {
     // (undocumented)
     [Symbol.iterator](): IterableIterator<[string, any]>;
     // (undocumented)
     readonly [Symbol.toStringTag]: string;
 }
 
-// @alpha
+// @alpha @sealed
 export interface ISharedDirectoryEvents extends ISharedObjectEvents {
     (event: "valueChanged", listener: (changed: IDirectoryValueChanged, local: boolean, target: IEventThisPlaceHolder) => void): any;
     (event: "clear", listener: (local: boolean, target: IEventThisPlaceHolder) => void): any;
@@ -830,7 +830,7 @@ export interface ITreeViewConfiguration<TSchema extends ImplicitFieldSchema = Im
     readonly schema: TSchema;
 }
 
-// @alpha @sealed
+// @public @sealed
 export interface IValueChanged {
     readonly key: string;
     readonly previousValue: any;

diff --git a/packages/framework/fluid-framework/api-report/fluid-framework.legacy.public.api.md b/packages/framework/fluid-framework/api-report/fluid-framework.legacy.public.api.md
@@ -138,6 +138,34 @@ export interface IConnection {
 // @public
 export type ICriticalContainerError = IErrorBase;
 
+// @public @sealed
+export interface IDirectory extends Map<string, any>, IEventProvider<IDirectoryEvents>, Partial<IDisposable> {
+    readonly absolutePath: string;
+    countSubDirectory?(): number;
+    createSubDirectory(subdirName: string): IDirectory;
+    deleteSubDirectory(subdirName: string): boolean;
+    get<T = any>(key: string): T | undefined;
+    getSubDirectory(subdirName: string): IDirectory | undefined;
+    getWorkingDirectory(relativePath: string): IDirectory | undefined;
+    hasSubDirectory(subdirName: string): boolean;
+    set<T = unknown>(key: string, value: T): this;
+    subdirectories(): IterableIterator<[string, IDirectory]>;
+}
+
+// @public @sealed
+export interface IDirectoryEvents extends IEvent {
+    (event: "containedValueChanged", listener: (changed: IValueChanged, local: boolean, target: IEventThisPlaceHolder) => void): any;
+    (event: "subDirectoryCreated", listener: (path: string, local: boolean, target: IEventThisPlaceHolder) => void): any;
+    (event: "subDirectoryDeleted", listener: (path: string, local: boolean, target: IEventThisPlaceHolder) => void): any;
+    (event: "disposed", listener: (target: IEventThisPlaceHolder) => void): any;
+    (event: "undisposed", listener: (target: IEventThisPlaceHolder) => void): any;
+}
+
+// @public @sealed
+export interface IDirectoryValueChanged extends IValueChanged {
+    path: string;
+}
+
 // @public @sealed
 export interface IDisposable {
     dispose(error?: Error): void;
@@ -524,6 +552,12 @@ export interface ITreeViewConfiguration<TSchema extends ImplicitFieldSchema = Im
     readonly schema: TSchema;
 }
 
+// @public @sealed
+export interface IValueChanged {
+    readonly key: string;
+    readonly previousValue: any;
+}
+
 // @public
 export type LazyItem<Item = unknown> = Item | (() => Item);