@fluidframework/runtime-definitions 2.0.0-internal.7.3.0 → 2.0.0-internal.7.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fluidframework/runtime-definitions",
-  "version": "2.0.0-internal.7.3.0",
+  "version": "2.0.0-internal.7.4.0",
   "description": "Fluid Runtime definitions",
   "homepage": "https://fluidframework.com",
   "repository": {
@@ -14,24 +14,39 @@
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "dependencies": {
-    "@fluidframework/container-definitions": ">=2.0.0-internal.7.3.0 <2.0.0-internal.7.4.0",
-    "@fluidframework/core-interfaces": ">=2.0.0-internal.7.3.0 <2.0.0-internal.7.4.0",
-    "@fluidframework/driver-definitions": ">=2.0.0-internal.7.3.0 <2.0.0-internal.7.4.0",
+    "@fluidframework/container-definitions": ">=2.0.0-internal.7.4.0 <2.0.0-internal.7.5.0",
+    "@fluidframework/core-interfaces": ">=2.0.0-internal.7.4.0 <2.0.0-internal.7.5.0",
+    "@fluidframework/driver-definitions": ">=2.0.0-internal.7.4.0 <2.0.0-internal.7.5.0",
+    "@fluidframework/id-compressor": ">=2.0.0-internal.7.4.0 <2.0.0-internal.7.5.0",
     "@fluidframework/protocol-definitions": "^3.0.0"
   },
   "devDependencies": {
+    "@arethetypeswrong/cli": "^0.13.3",
     "@fluid-tools/build-cli": "^0.28.0",
     "@fluidframework/build-common": "^2.0.3",
     "@fluidframework/build-tools": "^0.28.0",
     "@fluidframework/eslint-config-fluid": "^3.1.0",
     "@fluidframework/runtime-definitions-previous": "npm:@fluidframework/runtime-definitions@2.0.0-internal.7.2.0",
     "@microsoft/api-extractor": "^7.38.3",
+    "copyfiles": "^2.4.1",
     "eslint": "~8.50.0",
     "eslint-plugin-deprecation": "~2.0.0",
     "prettier": "~3.0.3",
     "rimraf": "^4.4.0",
     "typescript": "~5.1.6"
   },
+  "fluidBuild": {
+    "tasks": {
+      "build:docs": {
+        "dependsOn": [
+          "...",
+          "api-extractor:commonjs",
+          "api-extractor:esnext"
+        ],
+        "script": false
+      }
+    }
+  },
   "typeValidation": {
     "broken": {
       "TypeAliasDeclaration_IdCreationRangeWithStashedState": {
@@ -45,19 +60,24 @@
     }
   },
   "scripts": {
+    "api": "fluid-build . --task api",
+    "api-extractor:commonjs": "api-extractor run --local",
+    "api-extractor:esnext": "copyfiles -u 1 \"dist/**/*-@(alpha|beta|public|untrimmed).d.ts\" lib",
     "build": "fluid-build . --task build",
     "build:compile": "fluid-build . --task compile",
-    "build:docs": "api-extractor run --local",
+    "build:docs": "fluid-build . --task api",
     "build:test": "tsc --project ./src/test/tsconfig.json",
+    "check:are-the-types-wrong": "attw --pack",
+    "check:release-tags": "api-extractor run --local --config ./api-extractor-lint.json",
     "ci:build:docs": "api-extractor run",
     "clean": "rimraf --glob dist \"**/*.tsbuildinfo\" \"**/*.build.log\" _api-extractor-temp",
     "eslint": "eslint --format stylish src",
     "eslint:fix": "eslint --format stylish src --fix --fix-type problem,suggestion,layout",
     "format": "npm run prettier:fix",
-    "lint": "npm run prettier && npm run eslint",
+    "lint": "npm run prettier && npm run check:release-tags && npm run eslint",
     "lint:fix": "npm run prettier:fix && npm run eslint:fix",
-    "prettier": "prettier --check . --ignore-path ../../../.prettierignore",
-    "prettier:fix": "prettier --write . --ignore-path ../../../.prettierignore",
+    "prettier": "prettier --check . --cache --ignore-path ../../../.prettierignore",
+    "prettier:fix": "prettier --write . --cache --ignore-path ../../../.prettierignore",
     "tsc": "tsc",
     "typetests:gen": "fluid-type-test-generator",
     "typetests:prepare": "flub typetests --dir . --reset --previous --normalize"

package/src/attribution.ts

@@ -8,7 +8,6 @@ import type { IUser } from "@fluidframework/protocol-definitions";
 /**
  * AttributionKey representing a reference to some op in the op stream.
  * Content associated with this key aligns with content modified by that op.
- *
  * @alpha
  */
 export interface OpAttributionKey {
@@ -33,7 +32,6 @@ export interface OpAttributionKey {
  * is currently unsupported, as applications can effectively modify content anonymously while detached.
  * The runtime has no mechanism for reliably obtaining the user. It would be reasonable to start supporting
  * this functionality if the host provided additional context to their attributor or attach calls.
- *
  * @alpha
  */
 export interface DetachedAttributionKey {
@@ -52,7 +50,6 @@ export interface DetachedAttributionKey {
 
 /**
  * AttributionKey associated with content that has been made locally but not yet acked by the server.
- *
  * @alpha
  */
 export interface LocalAttributionKey {
@@ -67,7 +64,7 @@ export type AttributionKey = OpAttributionKey | DetachedAttributionKey | LocalAt
 
 /**
  * Attribution information associated with a change.
- * @alpha
+ * @internal
  */
 export interface AttributionInfo {
 	/**

package/src/dataStoreContext.ts

@@ -31,6 +31,7 @@ import {
 	ISequencedDocumentMessage,
 	ISnapshotTree,
 } from "@fluidframework/protocol-definitions";
+import { IIdCompressor } from "@fluidframework/id-compressor";
 import { IProvideFluidDataStoreFactory } from "./dataStoreFactory";
 import { IProvideFluidDataStoreRegistry } from "./dataStoreRegistry";
 import { IGarbageCollectionData, IGarbageCollectionDetailsBase } from "./garbageCollection";
@@ -42,10 +43,10 @@ import {
 	ITelemetryContext,
 	SummarizeInternalFn,
 } from "./summary";
-import { IIdCompressor } from "./id-compressor";
 
 /**
  * Runtime flush mode handling
+ * @alpha
  */
 export enum FlushMode {
 	/**
@@ -60,6 +61,9 @@ export enum FlushMode {
 	TurnBased,
 }
 
+/**
+ * @internal
+ */
 export enum FlushModeExperimental {
 	/**
 	 * When in Async flush mode, the runtime will accumulate all operations across JS turns and send them as a single
@@ -76,6 +80,7 @@ export enum FlushModeExperimental {
 /**
  * This tells the visibility state of a Fluid object. It basically tracks whether the object is not visible, visible
  * locally within the container only or visible globally to all clients.
+ * @alpha
  */
 export const VisibilityState = {
 	/**
@@ -101,8 +106,14 @@ export const VisibilityState = {
 	 */
 	GloballyVisible: "GloballyVisible",
 };
+/**
+ * @alpha
+ */
 export type VisibilityState = (typeof VisibilityState)[keyof typeof VisibilityState];
 
+/**
+ * @alpha
+ */
 export interface IContainerRuntimeBaseEvents extends IEvent {
 	(event: "batchBegin", listener: (op: ISequencedDocumentMessage) => void);
 	/**
@@ -122,6 +133,7 @@ export interface IContainerRuntimeBaseEvents extends IEvent {
  * the `IContainerRuntime.getAliasedDataStoreEntryPoint` function. The current datastore should be discarded
  * and will be garbage collected. The current datastore cannot be aliased to a different value.
  * 'AlreadyAliased' - the datastore has already been previously bound to another alias name.
+ * @alpha
  */
 export type AliasResult = "Success" | "Conflict" | "AlreadyAliased";
 
@@ -130,6 +142,7 @@ export type AliasResult = "Success" | "Conflict" | "AlreadyAliased";
  * - Handle to the data store's entryPoint
  * - Fluid router for the data store
  * - Can be assigned an alias
+ * @alpha
  */
 export interface IDataStore {
 	/**
@@ -184,6 +197,7 @@ export interface IDataStore {
 /**
  * A reduced set of functionality of IContainerRuntime that a data store context/data store runtime will need
  * TODO: this should be merged into IFluidDataStoreContext
+ * @alpha
  */
 export interface IContainerRuntimeBase extends IEventProvider<IContainerRuntimeBaseEvents> {
 	readonly logger: ITelemetryBaseLogger;
@@ -210,7 +224,6 @@ export interface IContainerRuntimeBase extends IEventProvider<IContainerRuntimeB
 
 	/**
 	 * @deprecated 0.16 Issue #1537, #3631
-	 * @internal
 	 */
 	_createDataStoreWithProps(
 		pkg: string | string[],
@@ -264,6 +277,7 @@ export interface IContainerRuntimeBase extends IEventProvider<IContainerRuntimeB
  *
  * Functionality include attach, snapshot, op/signal processing, request routes, expose an entryPoint,
  * and connection state notifications
+ * @alpha
  */
 export interface IFluidDataStoreChannel extends IDisposable {
 	readonly id: string;
@@ -369,6 +383,9 @@ export interface IFluidDataStoreChannel extends IDisposable {
 	readonly IFluidRouter: IFluidRouter;
 }
 
+/**
+ * @alpha
+ */
 export type CreateChildSummarizerNodeFn = (
 	summarizeInternal: SummarizeInternalFn,
 	getGCDataFn: (fullGC?: boolean) => Promise<IGarbageCollectionData>,
@@ -378,6 +395,9 @@ export type CreateChildSummarizerNodeFn = (
 	getBaseGCDetailsFn?: () => Promise<IGarbageCollectionDetailsBase>,
 ) => ISummarizerNodeWithGC;
 
+/**
+ * @alpha
+ */
 export interface IFluidDataStoreContextEvents extends IEvent {
 	(event: "attaching" | "attached", listener: () => void);
 }
@@ -385,6 +405,7 @@ export interface IFluidDataStoreContextEvents extends IEvent {
 /**
  * Represents the context for the data store. It is used by the data store runtime to
  * get information and call functionality to the container.
+ * @alpha
  */
 export interface IFluidDataStoreContext
 	extends IEventProvider<IFluidDataStoreContextEvents>,
@@ -520,6 +541,9 @@ export interface IFluidDataStoreContext
 	addedGCOutboundReference?(srcHandle: IFluidHandle, outboundHandle: IFluidHandle): void;
 }
 
+/**
+ * @alpha
+ */
 export interface IFluidDataStoreContextDetached extends IFluidDataStoreContext {
 	/**
 	 * Binds a runtime to the context.

package/src/dataStoreFactory.ts

@@ -5,8 +5,14 @@
 
 import { IFluidDataStoreContext, IFluidDataStoreChannel } from "./dataStoreContext";
 
+/**
+ * @alpha
+ */
 export const IFluidDataStoreFactory: keyof IProvideFluidDataStoreFactory = "IFluidDataStoreFactory";
 
+/**
+ * @alpha
+ */
 export interface IProvideFluidDataStoreFactory {
 	readonly IFluidDataStoreFactory: IFluidDataStoreFactory;
 }
@@ -14,6 +20,7 @@ export interface IProvideFluidDataStoreFactory {
 /**
  * IFluidDataStoreFactory create data stores.  It is associated with an identifier (its `type` member)
  * and usually provided to consumers using this mapping through a data store registry.
+ * @alpha
  */
 export interface IFluidDataStoreFactory extends IProvideFluidDataStoreFactory {
 	/**

package/src/dataStoreRegistry.ts

@@ -8,6 +8,7 @@ import { IProvideFluidDataStoreFactory } from "./dataStoreFactory";
 /**
  * A single registry entry that may be used to create data stores
  * It has to have either factory or registry, or both.
+ * @alpha
  */
 export type FluidDataStoreRegistryEntry = Readonly<
 	Partial<IProvideFluidDataStoreRegistry & IProvideFluidDataStoreFactory>
@@ -15,16 +16,24 @@ export type FluidDataStoreRegistryEntry = Readonly<
 /**
  * An associated pair of an identifier and registry entry.  Registry entries
  * may be dynamically loaded.
+ * @alpha
  */
 export type NamedFluidDataStoreRegistryEntry = [string, Promise<FluidDataStoreRegistryEntry>];
 /**
  * An iterable identifier/registry entry pair list
+ * @alpha
  */
 export type NamedFluidDataStoreRegistryEntries = Iterable<NamedFluidDataStoreRegistryEntry>;
 
+/**
+ * @alpha
+ */
 export const IFluidDataStoreRegistry: keyof IProvideFluidDataStoreRegistry =
 	"IFluidDataStoreRegistry";
 
+/**
+ * @alpha
+ */
 export interface IProvideFluidDataStoreRegistry {
 	readonly IFluidDataStoreRegistry: IFluidDataStoreRegistry;
 }
@@ -32,6 +41,7 @@ export interface IProvideFluidDataStoreRegistry {
 /**
  * An association of identifiers to data store registry entries, where the
  * entries can be used to create data stores.
+ * @alpha
  */
 export interface IFluidDataStoreRegistry extends IProvideFluidDataStoreRegistry {
 	get(name: string): Promise<FluidDataStoreRegistryEntry | undefined>;

package/src/garbageCollection.ts

@@ -3,18 +3,35 @@
  * Licensed under the MIT License.
  */
 
-/** The key for the GC tree in summary. */
+/**
+ * The key for the GC tree in summary.
+ *
+ * @internal
+ */
 export const gcTreeKey = "gc";
-/** They prefix for GC blobs in the GC tree in summary. */
+/**
+ * They prefix for GC blobs in the GC tree in summary.
+ *
+ * @internal
+ */
 export const gcBlobPrefix = "__gc";
-/** The key for tombstone blob in the GC tree in summary. */
+/**
+ * The key for tombstone blob in the GC tree in summary.
+ *
+ * @internal
+ */
 export const gcTombstoneBlobKey = "__tombstones";
-/** The key for deleted nodes blob in the GC tree in summary. */
+/**
+ * The key for deleted nodes blob in the GC tree in summary.
+ *
+ * @internal
+ */
 export const gcDeletedBlobKey = "__deletedNodes";
 
 /**
  * Garbage collection data returned by nodes in a Container.
  * Used for running GC in the Container.
+ * @alpha
  */
 export interface IGarbageCollectionData {
 	/**
@@ -25,6 +42,7 @@ export interface IGarbageCollectionData {
 
 /**
  * GC details provided to each node during creation.
+ * @alpha
  */
 export interface IGarbageCollectionDetailsBase {
 	/**

package/src/index.ts

@@ -65,16 +65,56 @@ export {
 	SummarizeInternalFn,
 	totalBlobSizePropertyName,
 } from "./summary";
+
+// Re-exports for backwards compatibility.
+// Will be removed in the future.
 export {
-	IIdCompressorCore,
+	/**
+	 * @deprecated Import from `@fluidframework/id-compressor` instead.
+	 */
+	IdCompressor,
+	/**
+	 * @deprecated Import from `@fluidframework/id-compressor` instead.
+	 */
 	IIdCompressor,
+	/**
+	 * @deprecated Import from `@fluidframework/id-compressor` instead.
+	 */
+	IIdCompressorCore,
+	/**
+	 * @deprecated Import from `@fluidframework/id-compressor` instead.
+	 */
+	IdCreationRange,
+	/**
+	 * @deprecated Import from `@fluidframework/id-compressor` instead.
+	 */
+	OpSpaceCompressedId,
+	/**
+	 * @deprecated Import from `@fluidframework/id-compressor` instead.
+	 */
 	SerializedIdCompressor,
-	SerializedIdCompressorWithOngoingSession,
+	/**
+	 * @deprecated Import from `@fluidframework/id-compressor` instead.
+	 */
 	SerializedIdCompressorWithNoSession,
-	SessionSpaceCompressedId,
-	OpSpaceCompressedId,
+	/**
+	 * @deprecated Import from `@fluidframework/id-compressor` instead.
+	 */
+	SerializedIdCompressorWithOngoingSession,
+	/**
+	 * @deprecated Import from `@fluidframework/id-compressor` instead.
+	 */
 	SessionId,
+	/**
+	 * @deprecated Import from `@fluidframework/id-compressor` instead.
+	 */
+	SessionSpaceCompressedId,
+	/**
+	 * @deprecated Import from `@fluidframework/id-compressor` instead.
+	 */
 	StableId,
-	IdCreationRange,
+	/**
+	 * @deprecated Import from `@fluidframework/id-compressor` instead.
+	 */
 	initialClusterCapacity,
-} from "./id-compressor";
+} from "@fluidframework/id-compressor";

package/src/protocol.ts

@@ -7,6 +7,7 @@ import { ISignalMessage, ITree } from "@fluidframework/protocol-definitions";
 
 /**
  * An envelope wraps the contents with the intended target
+ * @internal
  */
 export interface IEnvelope {
 	/**
@@ -20,6 +21,9 @@ export interface IEnvelope {
 	contents: any;
 }
 
+/**
+ * @internal
+ */
 export interface ISignalEnvelope {
 	/**
 	 * The target for the envelope, undefined for the container
@@ -42,6 +46,7 @@ export interface ISignalEnvelope {
 
 /**
  * Represents ISignalMessage with its type.
+ * @alpha
  */
 export interface IInboundSignalMessage extends ISignalMessage {
 	type: string;
@@ -50,6 +55,7 @@ export interface IInboundSignalMessage extends ISignalMessage {
 /**
  * Message send by client attaching local data structure.
  * Contains snapshot of data structure which is the current state of this data structure.
+ * @internal
  */
 export interface IAttachMessage {
 	/**
@@ -73,6 +79,7 @@ export interface IAttachMessage {
  * but it should not be used when creating a new attach op.
  * Older versions of attach messages could have null snapshots,
  * so this gives correct typings for writing backward compatible code.
+ * @internal
  */
 export type InboundAttachMessage = Omit<IAttachMessage, "snapshot"> & {
 	snapshot: IAttachMessage["snapshot"] | null;

package/src/summary.ts

@@ -15,6 +15,7 @@ import { IGarbageCollectionData, IGarbageCollectionDetailsBase } from "./garbage
 
 /**
  * Contains the aggregation data from a Tree/Subtree.
+ * @alpha
  */
 export interface ISummaryStats {
 	treeNodeCount: number;
@@ -30,6 +31,7 @@ export interface ISummaryStats {
  * each of its DDS.
  * Any component that implements IChannelContext, IFluidDataStoreChannel or extends SharedObject
  * will be taking part of the summarization process.
+ * @alpha
  */
 export interface ISummaryTreeWithStats {
 	/**
@@ -45,6 +47,7 @@ export interface ISummaryTreeWithStats {
 
 /**
  * Represents a summary at a current sequence number.
+ * @alpha
  */
 export interface ISummarizeResult {
 	stats: ISummaryStats;
@@ -65,6 +68,7 @@ export interface ISummarizeResult {
  *   ...
  *     "path1":
  * ```
+ * @alpha
  */
 export interface ISummarizeInternalResult extends ISummarizeResult {
 	id: string;
@@ -77,6 +81,7 @@ export interface ISummarizeInternalResult extends ISummarizeResult {
 /**
  * @experimental - Can be deleted/changed at any time
  * Contains the necessary information to allow DDSes to do incremental summaries
+ * @alpha
  */
 export interface IExperimentalIncrementalSummaryContext {
 	/**
@@ -101,6 +106,9 @@ export interface IExperimentalIncrementalSummaryContext {
 	summaryPath: string;
 }
 
+/**
+ * @alpha
+ */
 export type SummarizeInternalFn = (
 	fullTree: boolean,
 	trackState: boolean,
@@ -108,6 +116,9 @@ export type SummarizeInternalFn = (
 	incrementalSummaryContext?: IExperimentalIncrementalSummaryContext,
 ) => Promise<ISummarizeInternalResult>;
 
+/**
+ * @alpha
+ */
 export interface ISummarizerNodeConfig {
 	/**
 	 * True to reuse previous handle when unchanged since last acked summary.
@@ -126,6 +137,9 @@ export interface ISummarizerNodeConfig {
 	readonly throwOnFailure?: true;
 }
 
+/**
+ * @alpha
+ */
 export interface ISummarizerNodeConfigWithGC extends ISummarizerNodeConfig {
 	/**
 	 * True if GC is disabled. If so, don't track GC related state for a summary.
@@ -134,11 +148,17 @@ export interface ISummarizerNodeConfigWithGC extends ISummarizerNodeConfig {
 	readonly gcDisabled?: boolean;
 }
 
+/**
+ * @alpha
+ */
 export enum CreateSummarizerNodeSource {
 	FromSummary,
 	FromAttach,
 	Local,
 }
+/**
+ * @alpha
+ */
 export type CreateChildSummarizerNodeParam =
 	| {
 			type: CreateSummarizerNodeSource.FromSummary;
@@ -152,6 +172,9 @@ export type CreateChildSummarizerNodeParam =
 			type: CreateSummarizerNodeSource.Local;
 	  };
 
+/**
+ * @alpha
+ */
 export interface ISummarizerNode {
 	/**
 	 * Latest successfully acked summary reference sequence number
@@ -240,6 +263,7 @@ export interface ISummarizerNode {
  * `isReferenced`: This tells whether this node is referenced in the document or not.
  *
  * `updateUsedRoutes`: Used to notify this node of routes that are currently in use in it.
+ * @alpha
  */
 export interface ISummarizerNodeWithGC extends ISummarizerNode {
 	createChild(
@@ -298,11 +322,15 @@ export interface ISummarizerNodeWithGC extends ISummarizerNode {
 	updateUsedRoutes(usedRoutes: string[]): void;
 }
 
+/**
+ * @internal
+ */
 export const channelsTreeName = ".channels";
 
 /**
  * Contains telemetry data relevant to summarization workflows.
  * This object is expected to be modified directly by various summarize methods.
+ * @alpha
  */
 export interface ITelemetryContext {
 	/**
@@ -340,6 +368,12 @@ export interface ITelemetryContext {
 	serialize(): string;
 }
 
+/**
+ * @internal
+ */
 export const blobCountPropertyName = "BlobCount";
 
+/**
+ * @internal
+ */
 export const totalBlobSizePropertyName = "TotalBlobSize";