@fluidframework/core-interfaces - npm Package Compare versions

Comparing version 2.0.0-dev-rc.4.0.0.261659 to 2.0.0-dev-rc.5.0.0.263932

api-report/core-interfaces.api.md

@@ -32,2 +32,5 @@ ## API Report File for "@fluidframework/core-interfaces"
 // @public
+export const fluidHandleSymbol: unique symbol;
+
+// @public
 export type FluidObject<T = unknown> = {
@@ -244,9 +247,4 @@ [P in FluidObjectProviderKeys<T>]?: T[P];
 // @public
-export interface IFluidHandle<out T = FluidObject & IFluidLoadable> extends IProvideFluidHandle {
-    // @deprecated (undocumented)
-    readonly absolutePath: string;
-    // @deprecated (undocumented)
-    attachGraph(): void;
-    // @deprecated (undocumented)
-    bind(handle: IFluidHandle): void;
+export interface IFluidHandle<out T = unknown> {
+    readonly [fluidHandleSymbol]: IFluidHandleErased<T>;
     get(): Promise<T>;
@@ -269,2 +267,13 @@ readonly isAttached: boolean;
 
+// @public
+export interface IFluidHandleErased<T> extends ErasedType<readonly ["IFluidHandle", T]> {
+}
+
+// @alpha
+export interface IFluidHandleInternal<out T = unknown> extends IFluidHandle<T>, IProvideFluidHandle {
+    readonly absolutePath: string;
+    attachGraph(): void;
+    bind(handle: IFluidHandleInternal): void;
+}
+
 // @public (undocumented)
@@ -297,3 +306,3 @@ export const IFluidLoadable: keyof IProvideFluidLoadable;
 
-// @internal
+// @alpha
 export interface ILoggingError extends Error {
@@ -303,6 +312,6 @@ getTelemetryProperties(): ITelemetryBaseProperties;
 
-// @public (undocumented)
+// @alpha @deprecated (undocumented)
 export interface IProvideFluidHandle {
-    // (undocumented)
-    readonly [IFluidHandle]: IFluidHandle;
+    // @deprecated (undocumented)
+    readonly [IFluidHandle]: IFluidHandleInternal;
 }
@@ -309,0 +318,0 @@

CHANGELOG.md

 # @fluidframework/core-interfaces
 
+## 2.0.0-rc.4.0.0
+
+### Minor Changes
+
+-   Deprecated members of IFluidHandle are split off into new IFluidHandleInternal interface [96872186d0](https://github.com/microsoft/FluidFramework/commit/96872186d0d0f245c1fece7d19b3743e501679b6)
+
+    Split IFluidHandle into two interfaces, `IFluidHandle` and `IFluidHandleInternal`.
+    Code depending on the previously deprecated members of IFluidHandle can access them by using `toFluidHandleInternal` from `@fluidframework/runtime-utils/legacy`.
+
+    External implementation of the `IFluidHandle` interface are not supported: this change makes the typing better convey this using the `ErasedType` pattern.
+    Any existing and previously working, and now broken, external implementations of `IFluidHandle` should still work at runtime, but will need some unsafe type casts to compile.
+    Such handle implementation may break in the future and thus should be replaced with use of handles produced by the Fluid Framework client packages.
+
 ## 2.0.0-rc.3.0.0
@@ -4,0 +17,0 @@

dist/handles.d.ts

@@ -5,5 +5,4 @@ /*!
  */
-import type { IFluidLoadable } from "./fluidLoadable.js";
+import { type ErasedType } from "./erasedType.js";
 import type { IRequest, IResponse } from "./fluidRouter.js";
-import type { FluidObject } from "./provider.js";
 /**
@@ -45,18 +44,27 @@ * @public
  * @public
+ * @privateRemarks
+ * This really should be deprecated and alpha, but since its a merged export with the public interface,
+ * it can't have its own docs or different tags.
  */
 export declare const IFluidHandle = "IFluidHandle";
 /**
- * @public
+ * @deprecated {@link IFluidHandleInternal} and {@link IFluidHandleInternal} should be identified should be identified using the {@link fluidHandleSymbol} symbol.
+ * @alpha
  */
 export interface IProvideFluidHandle {
-    readonly [IFluidHandle]: IFluidHandle;
+    /**
+     * @deprecated {@link IFluidHandleInternal} and {@link IFluidHandleInternal} should be identified should be identified using the {@link fluidHandleSymbol} symbol.
+     * @privateRemarks
+     * This field must be kept so that code from before 2.0.0-rc.4.0.0 (When fluidHandleSymbol was added) still detects handles.
+     * This is required due to some use-cases mixing package versions.
+     * More details in packages/runtime/runtime-utils/src/handles.ts and on {@link fluidHandleSymbol}.
+     */
+    readonly [IFluidHandle]: IFluidHandleInternal;
 }
 /**
  * Handle to a shared {@link FluidObject}.
- * @public
+ * @alpha
  */
-export interface IFluidHandle<out T = FluidObject & IFluidLoadable> extends IProvideFluidHandle {
+export interface IFluidHandleInternal<out T = unknown> extends IFluidHandle<T>, IProvideFluidHandle {
     /**
-     * @deprecated Do not use handle's path for routing. Use `get` to get the underlying object.
-     *
      * The absolute path to the handle context from the root.
@@ -66,2 +74,32 @@ */
     /**
+     * Runs through the graph and attach the bounded handles.
+     */
+    attachGraph(): void;
+    /**
+     * Binds the given handle to this one or attach the given handle if this handle is attached.
+     * A bound handle will also be attached once this handle is attached.
+     */
+    bind(handle: IFluidHandleInternal): void;
+}
+/**
+ * Symbol which must only be used on an {@link (IFluidHandle:interface)}, and is used to identify such objects.
+ *
+ * @remarks
+ * To narrow arbitrary objects to handles do not simply check for this symbol:
+ * instead use {@link @fluidframework/runtime-utils#isFluidHandle} which has improved compatibility
+ * with older implementations of handles that may exist due to dynamic code loading of older packages.
+ *
+ * @privateRemarks
+ * Normally `Symbol` would be used here instead of `Symbol.for` since just using Symbol (and avoiding the global symbol registry) removes the risk of collision, which is the main point of using a symbol for this in the first place.
+ * In this case however, some users of this library do dynamic code loading, and can end up with multiple versions of packages, and mix data from one version with another.
+ * Using the global symbol registry allows duplicate copies of this library to share a single symbol, though reintroduces the risk of collision, which is mitigated via the use of a UUIDv4 randomly generated when this code was authored:
+ * @public
+ */
+export declare const fluidHandleSymbol: unique symbol;
+/**
+ * Handle to a shared {@link FluidObject}.
+ * @public
+ */
+export interface IFluidHandle<out T = unknown> {
+    /**
      * Flag indicating whether or not the entity has services attached.
@@ -71,8 +109,2 @@ */
     /**
-     * @deprecated To be removed. This is part of an internal API surface and should not be called.
-     *
-     * Runs through the graph and attach the bounded handles.
-     */
-    attachGraph(): void;
-    /**
      * Returns a promise to the Fluid Object referenced by the handle.
@@ -82,9 +114,19 @@ */
     /**
-     * @deprecated To be removed. This is part of an internal API surface and should not be called.
+     * Symbol used to mark an object as a {@link (IFluidHandle:interface)}
+     * and to recover the underlying handle implementation.
      *
-     * Binds the given handle to this one or attach the given handle if this handle is attached.
-     * A bound handle will also be attached once this handle is attached.
+     * @privateRemarks
+     * Used to recover {@link IFluidHandleInternal}, see {@link toFluidHandleInternal}.
      */
-    bind(handle: IFluidHandle): void;
+    readonly [fluidHandleSymbol]: IFluidHandleErased<T>;
 }
+/**
+ * A type erased Fluid Handle.
+ * These can only be produced by the Fluid Framework and provide the implementation details needed to power {@link (IFluidHandle:interface)}.
+ * @privateRemarks
+ * Created from {@link IFluidHandleInternal} using {@link toFluidHandleErased}.
+ * @public
+ */
+export interface IFluidHandleErased<T> extends ErasedType<readonly ["IFluidHandle", T]> {
+}
 //# sourceMappingURL=handles.d.ts.map

dist/handles.js

@@ -7,3 +7,3 @@ "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.IFluidHandle = exports.IFluidHandleContext = void 0;
+exports.fluidHandleSymbol = exports.IFluidHandle = exports.IFluidHandleContext = void 0;
 /**
@@ -15,4 +15,22 @@ * @public
  * @public
+ * @privateRemarks
+ * This really should be deprecated and alpha, but since its a merged export with the public interface,
+ * it can't have its own docs or different tags.
  */
 exports.IFluidHandle = "IFluidHandle";
+/**
+ * Symbol which must only be used on an {@link (IFluidHandle:interface)}, and is used to identify such objects.
+ *
+ * @remarks
+ * To narrow arbitrary objects to handles do not simply check for this symbol:
+ * instead use {@link @fluidframework/runtime-utils#isFluidHandle} which has improved compatibility
+ * with older implementations of handles that may exist due to dynamic code loading of older packages.
+ *
+ * @privateRemarks
+ * Normally `Symbol` would be used here instead of `Symbol.for` since just using Symbol (and avoiding the global symbol registry) removes the risk of collision, which is the main point of using a symbol for this in the first place.
+ * In this case however, some users of this library do dynamic code loading, and can end up with multiple versions of packages, and mix data from one version with another.
+ * Using the global symbol registry allows duplicate copies of this library to share a single symbol, though reintroduces the risk of collision, which is mitigated via the use of a UUIDv4 randomly generated when this code was authored:
+ * @public
+ */
+exports.fluidHandleSymbol = Symbol.for("FluidHandle-3978c7cf-4675-49ba-a20c-bf35efbf43da");
 //# sourceMappingURL=handles.js.map

dist/index.d.ts

@@ -12,4 +12,4 @@ /*!
 export type { IRequest, IRequestHeader, IResponse } from "./fluidRouter.js";
-export type { IProvideFluidHandleContext, IProvideFluidHandle } from "./handles.js";
-export { IFluidHandleContext, IFluidHandle } from "./handles.js";
+export type { IProvideFluidHandleContext, IProvideFluidHandle, IFluidHandleInternal, IFluidHandleErased, } from "./handles.js";
+export { IFluidHandleContext, IFluidHandle, fluidHandleSymbol } from "./handles.js";
 export type { ILoggingError, ITelemetryBaseEvent, ITelemetryBaseLogger, ITelemetryBaseProperties, Tagged, TelemetryBaseEventPropertyType, } from "./logger.js";
@@ -16,0 +16,0 @@ export { LogLevel } from "./logger.js";

dist/index.js

@@ -7,3 +7,3 @@ "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.LogLevel = exports.IFluidHandle = exports.IFluidHandleContext = exports.IFluidRunnable = exports.IFluidLoadable = exports.FluidErrorTypes = void 0;
+exports.LogLevel = exports.fluidHandleSymbol = exports.IFluidHandle = exports.IFluidHandleContext = exports.IFluidRunnable = exports.IFluidLoadable = exports.FluidErrorTypes = void 0;
 var error_js_1 = require("./error.js");
@@ -17,4 +17,5 @@ Object.defineProperty(exports, "FluidErrorTypes", { enumerable: true, get: function () { return error_js_1.FluidErrorTypes; } });
 Object.defineProperty(exports, "IFluidHandle", { enumerable: true, get: function () { return handles_js_1.IFluidHandle; } });
+Object.defineProperty(exports, "fluidHandleSymbol", { enumerable: true, get: function () { return handles_js_1.fluidHandleSymbol; } });
 var logger_js_1 = require("./logger.js");
 Object.defineProperty(exports, "LogLevel", { enumerable: true, get: function () { return logger_js_1.LogLevel; } });
 //# sourceMappingURL=index.js.map

dist/legacy.d.ts

@@ -29,4 +29,4 @@ /*!
 	IFluidHandleContext, 
+	IFluidHandleErased, 
 	IFluidLoadable, 
-	IProvideFluidHandle, 
 	IProvideFluidHandleContext, 
@@ -44,7 +44,11 @@ IProvideFluidLoadable,
 	TelemetryBaseEventPropertyType, 
-	TransformedEvent,
+	TransformedEvent, 
+	fluidHandleSymbol,
  
 	// @alpha APIs
 	FluidErrorTypes, 
+	IFluidHandleInternal, 
+	ILoggingError, 
+	IProvideFluidHandle, 
 	IThrottlingWarning
 } from "./index.js";

dist/logger.d.ts

@@ -84,3 +84,3 @@ /*!
  * An error object that supports exporting its properties to be logged to telemetry
- * @internal
+ * @alpha
  */
@@ -87,0 +87,0 @@ export interface ILoggingError extends Error {

dist/public.d.ts

@@ -29,4 +29,4 @@ /*!
 	IFluidHandleContext, 
+	IFluidHandleErased, 
 	IFluidLoadable, 
-	IProvideFluidHandle, 
 	IProvideFluidHandleContext, 
@@ -44,3 +44,4 @@ IProvideFluidLoadable,
 	TelemetryBaseEventPropertyType, 
-	TransformedEvent
+	TransformedEvent, 
+	fluidHandleSymbol
 } from "./index.js";

lib/handles.d.ts

@@ -5,5 +5,4 @@ /*!
  */
-import type { IFluidLoadable } from "./fluidLoadable.js";
+import { type ErasedType } from "./erasedType.js";
 import type { IRequest, IResponse } from "./fluidRouter.js";
-import type { FluidObject } from "./provider.js";
 /**
@@ -45,18 +44,27 @@ * @public
  * @public
+ * @privateRemarks
+ * This really should be deprecated and alpha, but since its a merged export with the public interface,
+ * it can't have its own docs or different tags.
  */
 export declare const IFluidHandle = "IFluidHandle";
 /**
- * @public
+ * @deprecated {@link IFluidHandleInternal} and {@link IFluidHandleInternal} should be identified should be identified using the {@link fluidHandleSymbol} symbol.
+ * @alpha
  */
 export interface IProvideFluidHandle {
-    readonly [IFluidHandle]: IFluidHandle;
+    /**
+     * @deprecated {@link IFluidHandleInternal} and {@link IFluidHandleInternal} should be identified should be identified using the {@link fluidHandleSymbol} symbol.
+     * @privateRemarks
+     * This field must be kept so that code from before 2.0.0-rc.4.0.0 (When fluidHandleSymbol was added) still detects handles.
+     * This is required due to some use-cases mixing package versions.
+     * More details in packages/runtime/runtime-utils/src/handles.ts and on {@link fluidHandleSymbol}.
+     */
+    readonly [IFluidHandle]: IFluidHandleInternal;
 }
 /**
  * Handle to a shared {@link FluidObject}.
- * @public
+ * @alpha
  */
-export interface IFluidHandle<out T = FluidObject & IFluidLoadable> extends IProvideFluidHandle {
+export interface IFluidHandleInternal<out T = unknown> extends IFluidHandle<T>, IProvideFluidHandle {
     /**
-     * @deprecated Do not use handle's path for routing. Use `get` to get the underlying object.
-     *
      * The absolute path to the handle context from the root.
@@ -66,2 +74,32 @@ */
     /**
+     * Runs through the graph and attach the bounded handles.
+     */
+    attachGraph(): void;
+    /**
+     * Binds the given handle to this one or attach the given handle if this handle is attached.
+     * A bound handle will also be attached once this handle is attached.
+     */
+    bind(handle: IFluidHandleInternal): void;
+}
+/**
+ * Symbol which must only be used on an {@link (IFluidHandle:interface)}, and is used to identify such objects.
+ *
+ * @remarks
+ * To narrow arbitrary objects to handles do not simply check for this symbol:
+ * instead use {@link @fluidframework/runtime-utils#isFluidHandle} which has improved compatibility
+ * with older implementations of handles that may exist due to dynamic code loading of older packages.
+ *
+ * @privateRemarks
+ * Normally `Symbol` would be used here instead of `Symbol.for` since just using Symbol (and avoiding the global symbol registry) removes the risk of collision, which is the main point of using a symbol for this in the first place.
+ * In this case however, some users of this library do dynamic code loading, and can end up with multiple versions of packages, and mix data from one version with another.
+ * Using the global symbol registry allows duplicate copies of this library to share a single symbol, though reintroduces the risk of collision, which is mitigated via the use of a UUIDv4 randomly generated when this code was authored:
+ * @public
+ */
+export declare const fluidHandleSymbol: unique symbol;
+/**
+ * Handle to a shared {@link FluidObject}.
+ * @public
+ */
+export interface IFluidHandle<out T = unknown> {
+    /**
      * Flag indicating whether or not the entity has services attached.
@@ -71,8 +109,2 @@ */
     /**
-     * @deprecated To be removed. This is part of an internal API surface and should not be called.
-     *
-     * Runs through the graph and attach the bounded handles.
-     */
-    attachGraph(): void;
-    /**
      * Returns a promise to the Fluid Object referenced by the handle.
@@ -82,9 +114,19 @@ */
     /**
-     * @deprecated To be removed. This is part of an internal API surface and should not be called.
+     * Symbol used to mark an object as a {@link (IFluidHandle:interface)}
+     * and to recover the underlying handle implementation.
      *
-     * Binds the given handle to this one or attach the given handle if this handle is attached.
-     * A bound handle will also be attached once this handle is attached.
+     * @privateRemarks
+     * Used to recover {@link IFluidHandleInternal}, see {@link toFluidHandleInternal}.
      */
-    bind(handle: IFluidHandle): void;
+    readonly [fluidHandleSymbol]: IFluidHandleErased<T>;
 }
+/**
+ * A type erased Fluid Handle.
+ * These can only be produced by the Fluid Framework and provide the implementation details needed to power {@link (IFluidHandle:interface)}.
+ * @privateRemarks
+ * Created from {@link IFluidHandleInternal} using {@link toFluidHandleErased}.
+ * @public
+ */
+export interface IFluidHandleErased<T> extends ErasedType<readonly ["IFluidHandle", T]> {
+}
 //# sourceMappingURL=handles.d.ts.map

lib/handles.js

@@ -11,4 +11,22 @@ /*!
  * @public
+ * @privateRemarks
+ * This really should be deprecated and alpha, but since its a merged export with the public interface,
+ * it can't have its own docs or different tags.
  */
 export const IFluidHandle = "IFluidHandle";
+/**
+ * Symbol which must only be used on an {@link (IFluidHandle:interface)}, and is used to identify such objects.
+ *
+ * @remarks
+ * To narrow arbitrary objects to handles do not simply check for this symbol:
+ * instead use {@link @fluidframework/runtime-utils#isFluidHandle} which has improved compatibility
+ * with older implementations of handles that may exist due to dynamic code loading of older packages.
+ *
+ * @privateRemarks
+ * Normally `Symbol` would be used here instead of `Symbol.for` since just using Symbol (and avoiding the global symbol registry) removes the risk of collision, which is the main point of using a symbol for this in the first place.
+ * In this case however, some users of this library do dynamic code loading, and can end up with multiple versions of packages, and mix data from one version with another.
+ * Using the global symbol registry allows duplicate copies of this library to share a single symbol, though reintroduces the risk of collision, which is mitigated via the use of a UUIDv4 randomly generated when this code was authored:
+ * @public
+ */
+export const fluidHandleSymbol = Symbol.for("FluidHandle-3978c7cf-4675-49ba-a20c-bf35efbf43da");
 //# sourceMappingURL=handles.js.map

lib/index.d.ts

@@ -12,4 +12,4 @@ /*!
 export type { IRequest, IRequestHeader, IResponse } from "./fluidRouter.js";
-export type { IProvideFluidHandleContext, IProvideFluidHandle } from "./handles.js";
-export { IFluidHandleContext, IFluidHandle } from "./handles.js";
+export type { IProvideFluidHandleContext, IProvideFluidHandle, IFluidHandleInternal, IFluidHandleErased, } from "./handles.js";
+export { IFluidHandleContext, IFluidHandle, fluidHandleSymbol } from "./handles.js";
 export type { ILoggingError, ITelemetryBaseEvent, ITelemetryBaseLogger, ITelemetryBaseProperties, Tagged, TelemetryBaseEventPropertyType, } from "./logger.js";
@@ -16,0 +16,0 @@ export { LogLevel } from "./logger.js";

lib/index.js

@@ -7,4 +7,4 @@ /*!
 export { IFluidLoadable, IFluidRunnable } from "./fluidLoadable.js";
-export { IFluidHandleContext, IFluidHandle } from "./handles.js";
+export { IFluidHandleContext, IFluidHandle, fluidHandleSymbol } from "./handles.js";
 export { LogLevel } from "./logger.js";
 //# sourceMappingURL=index.js.map

lib/legacy.d.ts

@@ -29,4 +29,4 @@ /*!
 	IFluidHandleContext, 
+	IFluidHandleErased, 
 	IFluidLoadable, 
-	IProvideFluidHandle, 
 	IProvideFluidHandleContext, 
@@ -44,7 +44,11 @@ IProvideFluidLoadable,
 	TelemetryBaseEventPropertyType, 
-	TransformedEvent,
+	TransformedEvent, 
+	fluidHandleSymbol,
  
 	// @alpha APIs
 	FluidErrorTypes, 
+	IFluidHandleInternal, 
+	ILoggingError, 
+	IProvideFluidHandle, 
 	IThrottlingWarning
 } from "./index.js";

lib/logger.d.ts

@@ -84,3 +84,3 @@ /*!
  * An error object that supports exporting its properties to be logged to telemetry
- * @internal
+ * @alpha
  */
@@ -87,0 +87,0 @@ export interface ILoggingError extends Error {

lib/public.d.ts

@@ -29,4 +29,4 @@ /*!
 	IFluidHandleContext, 
+	IFluidHandleErased, 
 	IFluidLoadable, 
-	IProvideFluidHandle, 
 	IProvideFluidHandleContext, 
@@ -44,3 +44,4 @@ IProvideFluidLoadable,
 	TelemetryBaseEventPropertyType, 
-	TransformedEvent
+	TransformedEvent, 
+	fluidHandleSymbol
 } from "./index.js";

lib/tsdoc-metadata.json

@@ -8,5 +8,5 @@ // This file is read by tools that parse documentation comments conforming to the TSDoc standard.
       "packageName": "@microsoft/api-extractor",
-      "packageVersion": "7.42.3"
+      "packageVersion": "7.43.1"
     }
   ]
 }

package.json

 {
   "name": "@fluidframework/core-interfaces",
-  "version": "2.0.0-dev-rc.4.0.0.261659",
+  "version": "2.0.0-dev-rc.5.0.0.263932",
   "description": "Fluid object interfaces",
@@ -52,8 +52,8 @@ "homepage": "https://fluidframework.com",
     "@biomejs/biome": "^1.6.2",
-    "@fluid-tools/build-cli": "0.38.0-259537",
+    "@fluid-tools/build-cli": "^0.38.0",
     "@fluidframework/build-common": "^2.0.3",
-    "@fluidframework/build-tools": "0.38.0-259537",
+    "@fluidframework/build-tools": "^0.38.0",
     "@fluidframework/core-interfaces-previous": "npm:@fluidframework/core-interfaces@2.0.0-rc.3.0.0",
     "@fluidframework/eslint-config-fluid": "^5.1.0",
-    "@microsoft/api-extractor": "^7.42.3",
+    "@microsoft/api-extractor": "^7.43.1",
     "@types/node": "^18.19.0",
@@ -67,3 +67,23 @@ "copyfiles": "^2.4.1",
   "typeValidation": {
-    "broken": {}
+    "broken": {
+      "RemovedVariableDeclaration_isFluidPackage": {
+        "backCompat": false,
+        "forwardCompat": false
+      },
+      "InterfaceDeclaration_IFluidHandle": {
+        "forwardCompat": false,
+        "backCompat": false
+      },
+      "InterfaceDeclaration_IProvideFluidHandle": {
+        "forwardCompat": false
+      },
+      "InterfaceDeclaration_IProvideFluidLoadable": {
+        "forwardCompat": false,
+        "backCompat": false
+      },
+      "InterfaceDeclaration_IFluidLoadable": {
+        "forwardCompat": false,
+        "backCompat": false
+      }
+    }
   },
@@ -96,4 +116,5 @@ "scripts": {
     "lint:fix": "fluid-build . --task eslint:fix --task format",
-    "tsc": "fluid-tsc commonjs --project ./tsconfig.cjs.json && copyfiles -f ../../../common/build/build-common/src/cjs/package.json ./dist",
-    "tsc:watch": "tsc --watch",
+    "place:cjs:package-stub": "copyfiles -f ../../../common/build/build-common/src/cjs/package.json ./dist",
+    "tsc": "fluid-tsc commonjs --project ./tsconfig.cjs.json && npm run place:cjs:package-stub",
+    "tsc:watch": "npm run place:cjs:package-stub && fluid-tsc commonjs --project ./tsconfig.cjs.json --watch",
     "typetests:gen": "flub generate typetests --dir . -v --publicFallback",
@@ -100,0 +121,0 @@ "typetests:prepare": "flub typetests --dir . --reset --previous --normalize"

src/handles.ts

@@ -6,5 +6,4 @@ /*!
 
-import type { IFluidLoadable } from "./fluidLoadable.js";
+import { type ErasedType } from "./erasedType.js";
 import type { IRequest, IResponse } from "./fluidRouter.js";
-import type { FluidObject } from "./provider.js";
 
@@ -54,2 +53,5 @@ /**
  * @public
+ * @privateRemarks
+ * This really should be deprecated and alpha, but since its a merged export with the public interface,
+ * it can't have its own docs or different tags.
  */
@@ -59,6 +61,14 @@ export const IFluidHandle = "IFluidHandle";
 /**
- * @public
+ * @deprecated {@link IFluidHandleInternal} and {@link IFluidHandleInternal} should be identified should be identified using the {@link fluidHandleSymbol} symbol.
+ * @alpha
  */
 export interface IProvideFluidHandle {
-	readonly [IFluidHandle]: IFluidHandle;
+	/**
+	 * @deprecated {@link IFluidHandleInternal} and {@link IFluidHandleInternal} should be identified should be identified using the {@link fluidHandleSymbol} symbol.
+	 * @privateRemarks
+	 * This field must be kept so that code from before 2.0.0-rc.4.0.0 (When fluidHandleSymbol was added) still detects handles.
+	 * This is required due to some use-cases mixing package versions.
+	 * More details in packages/runtime/runtime-utils/src/handles.ts and on {@link fluidHandleSymbol}.
+	 */
+	readonly [IFluidHandle]: IFluidHandleInternal;
 }
@@ -68,11 +78,10 @@
  * Handle to a shared {@link FluidObject}.
- * @public
+ * @alpha
  */
-export interface IFluidHandle<
+export interface IFluidHandleInternal<
 	// REVIEW: Constrain `T` to something? How do we support dds and datastores safely?
-	out T = FluidObject & IFluidLoadable,
-> extends IProvideFluidHandle {
+	out T = unknown, // FluidObject & IFluidLoadable,
+> extends IFluidHandle<T>,
+		IProvideFluidHandle {
 	/**
-	 * @deprecated Do not use handle's path for routing. Use `get` to get the underlying object.
-	 *
 	 * The absolute path to the handle context from the root.
@@ -83,14 +92,42 @@ */
 	/**
-	 * Flag indicating whether or not the entity has services attached.
+	 * Runs through the graph and attach the bounded handles.
 	 */
-	readonly isAttached: boolean;
+	attachGraph(): void;
 
 	/**
-	 * @deprecated To be removed. This is part of an internal API surface and should not be called.
-	 *
-	 * Runs through the graph and attach the bounded handles.
+	 * Binds the given handle to this one or attach the given handle if this handle is attached.
+	 * A bound handle will also be attached once this handle is attached.
 	 */
-	attachGraph(): void;
+	bind(handle: IFluidHandleInternal): void;
+}
 
+/**
+ * Symbol which must only be used on an {@link (IFluidHandle:interface)}, and is used to identify such objects.
+ *
+ * @remarks
+ * To narrow arbitrary objects to handles do not simply check for this symbol:
+ * instead use {@link @fluidframework/runtime-utils#isFluidHandle} which has improved compatibility
+ * with older implementations of handles that may exist due to dynamic code loading of older packages.
+ *
+ * @privateRemarks
+ * Normally `Symbol` would be used here instead of `Symbol.for` since just using Symbol (and avoiding the global symbol registry) removes the risk of collision, which is the main point of using a symbol for this in the first place.
+ * In this case however, some users of this library do dynamic code loading, and can end up with multiple versions of packages, and mix data from one version with another.
+ * Using the global symbol registry allows duplicate copies of this library to share a single symbol, though reintroduces the risk of collision, which is mitigated via the use of a UUIDv4 randomly generated when this code was authored:
+ * @public
+ */
+export const fluidHandleSymbol: unique symbol = Symbol.for(
+	"FluidHandle-3978c7cf-4675-49ba-a20c-bf35efbf43da",
+);
+
+/**
+ * Handle to a shared {@link FluidObject}.
+ * @public
+ */
+export interface IFluidHandle<out T = unknown> {
 	/**
+	 * Flag indicating whether or not the entity has services attached.
+	 */
+	readonly isAttached: boolean;
+
+	/**
 	 * Returns a promise to the Fluid Object referenced by the handle.
@@ -101,8 +138,19 @@ */
 	/**
-	 * @deprecated To be removed. This is part of an internal API surface and should not be called.
+	 * Symbol used to mark an object as a {@link (IFluidHandle:interface)}
+	 * and to recover the underlying handle implementation.
 	 *
-	 * Binds the given handle to this one or attach the given handle if this handle is attached.
-	 * A bound handle will also be attached once this handle is attached.
+	 * @privateRemarks
+	 * Used to recover {@link IFluidHandleInternal}, see {@link toFluidHandleInternal}.
 	 */
-	bind(handle: IFluidHandle): void;
+	readonly [fluidHandleSymbol]: IFluidHandleErased<T>;
 }
+
+/**
+ * A type erased Fluid Handle.
+ * These can only be produced by the Fluid Framework and provide the implementation details needed to power {@link (IFluidHandle:interface)}.
+ * @privateRemarks
+ * Created from {@link IFluidHandleInternal} using {@link toFluidHandleErased}.
+ * @public
+ */
+// eslint-disable-next-line @typescript-eslint/no-empty-interface
+export interface IFluidHandleErased<T> extends ErasedType<readonly ["IFluidHandle", T]> {}

src/index.ts

@@ -30,4 +30,9 @@ /*!
 
-export type { IProvideFluidHandleContext, IProvideFluidHandle } from "./handles.js";
-export { IFluidHandleContext, IFluidHandle } from "./handles.js";
+export type {
+	IProvideFluidHandleContext,
+	IProvideFluidHandle,
+	IFluidHandleInternal,
+	IFluidHandleErased,
+} from "./handles.js";
+export { IFluidHandleContext, IFluidHandle, fluidHandleSymbol } from "./handles.js";
 
@@ -34,0 +39,0 @@ export type {

src/logger.ts

@@ -94,3 +94,3 @@ /*!
  * An error object that supports exporting its properties to be logged to telemetry
- * @internal
+ * @alpha
  */
@@ -97,0 +97,0 @@ export interface ILoggingError extends Error {

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

352577

increased by5.72%

Lines of code

3638

increased by5.24%

No dependency changes