diff --git a/packages/framework/fluid-static/src/types.ts b/packages/framework/fluid-static/src/types.ts index bbb525137846..573009c9a9bf 100644 --- a/packages/framework/fluid-static/src/types.ts +++ b/packages/framework/fluid-static/src/types.ts @@ -121,7 +121,7 @@ interface IProvideStaticEntryPoint { } /** - * @internal + * This is the internal entry point fluid-static creates. */ export interface IStaticEntryPoint extends IProvideStaticEntryPoint { readonly rootDataObject: IRootDataObject; diff --git a/packages/framework/presence/src/broadcastControls.ts b/packages/framework/presence/src/broadcastControls.ts index 5caf41681b39..b90f0afbd698 100644 --- a/packages/framework/presence/src/broadcastControls.ts +++ b/packages/framework/presence/src/broadcastControls.ts @@ -89,7 +89,8 @@ class ForcedRefreshControl } /** - * @internal + * Implements {@link BroadcastControls} for States Managers + * where returning `undefined` settings are allowed. */ export class OptionalBroadcastControl extends ForcedRefreshControl @@ -109,8 +110,6 @@ export class OptionalBroadcastControl * * If {@link BroadcastControls.allowableUpdateLatencyMs | allowableUpdateLatencyMs} * is set to `undefined`, the default will be restored. - * - * @internal */ export class RequiredBroadcastControl extends ForcedRefreshControl diff --git a/packages/framework/presence/src/datastoreSupport.ts b/packages/framework/presence/src/datastoreSupport.ts index 925d23d867fe..06eed1a90fbb 100644 --- a/packages/framework/presence/src/datastoreSupport.ts +++ b/packages/framework/presence/src/datastoreSupport.ts @@ -3,6 +3,11 @@ * Licensed under the MIT License. */ +/** + * This module provided collection of minimal (slim) helpers to support + * DataObject creation for temporary {@link ExperimentalPresenceManager}. + */ + import type { FluidObject, IFluidLoadable, @@ -19,8 +24,9 @@ import type { import { create404Response } from "@fluidframework/runtime-utils/internal"; /** - * Extends the FluidDataStoreRuntime to provide a request method that routes requests to - * the entrypoint Fluid object that is expected to be a {@link LoadableFluidObject}. + * `BasicFluidDataStoreRuntime` extends the FluidDataStoreRuntime to provide a request + * method that routes requests to the entrypoint Fluid object that is expected to be a + * {@link LoadableFluidObject}. */ class BasicFluidDataStoreRuntime extends FluidDataStoreRuntime { public override async request(request: IRequest): Promise { @@ -47,7 +53,7 @@ class BasicFluidDataStoreRuntime extends FluidDataStoreRuntime { } /** - * @internal + * `BasicDataStoreFactory` is the factory for creating a {@link BasicFluidDataStoreRuntime}. */ export class BasicDataStoreFactory implements IFluidDataStoreFactory { public get IFluidDataStoreFactory(): IFluidDataStoreFactory { @@ -82,7 +88,8 @@ export class BasicDataStoreFactory implements IFluidDataSto } /** - * @internal + * `LoadableFluidObject` is helper to build a DataObject handling the {@link FluidObject} + * and {@link IFluidLoadable} requirements. */ export abstract class LoadableFluidObject implements FluidObject, IFluidLoadable { public constructor(protected readonly runtime: FluidDataStoreRuntime) {} diff --git a/packages/framework/presence/src/internalTypes.ts b/packages/framework/presence/src/internalTypes.ts index 1aabba9d66b1..9ef052ab1c96 100644 --- a/packages/framework/presence/src/internalTypes.ts +++ b/packages/framework/presence/src/internalTypes.ts @@ -15,19 +15,20 @@ import type { /** * Presence {@link ContainerExtension} version of {@link @fluidframework/container-runtime-definitions#ExtensionRuntimeProperties} - * @internal */ export interface ExtensionRuntimeProperties { SignalMessages: SignalMessages; } /** * Presence specific ExtensionHost - * @internal */ export type ExtensionHost = ContainerExtensionHost; /** - * @internal + * Basic structure of set of {@link Attendee} records within Presence datastore + * + * @remarks + * This is commonly exists per named state in State Managers. */ export interface ClientRecord> { // Caution: any particular item may or may not exist @@ -42,8 +43,6 @@ export interface ClientRecord & // Apart from tests, there is always a logger. So this could be promoted to required. @@ -60,7 +59,10 @@ export type IEphemeralRuntime = Omit void; diff --git a/packages/framework/presence/src/internalUtils.ts b/packages/framework/presence/src/internalUtils.ts index 8a078191adb0..eb741cbe8e46 100644 --- a/packages/framework/presence/src/internalUtils.ts +++ b/packages/framework/presence/src/internalUtils.ts @@ -29,8 +29,6 @@ type RequiredAndNotUndefined = { * The is a defect in this utility when a string index appears in the object. * In such a case, the only result is `[string, T]`, where `T` is the type * of the string index entry. - * - * @internal */ export const objectEntries = Object.entries as (o: T) => KeyValuePairs; @@ -41,8 +39,6 @@ export const objectEntries = Object.entries as (o: T) => KeyValuePairs< * Given `T` should not contain `undefined` values. If it does, use * {@link objectEntries} instead. Without `undefined` values, this * typing provides best handling of objects with optional properties. - * - * @internal */ export const objectEntriesWithoutUndefined = Object.entries as ( o: T, @@ -50,8 +46,6 @@ export const objectEntriesWithoutUndefined = Object.entries as ( /** * Object.keys retyped to preserve known keys and their types. - * - * @internal */ export const objectKeys = Object.keys as ( o: T, diff --git a/packages/framework/presence/src/presence.ts b/packages/framework/presence/src/presence.ts index 5e4d6d74c9c1..408aa040dc2e 100644 --- a/packages/framework/presence/src/presence.ts +++ b/packages/framework/presence/src/presence.ts @@ -109,8 +109,6 @@ export interface Attendee { /** * Utility type limiting to a specific attendee. (A attendee with * a specific session ID - not just any session ID.) - * - * @internal */ export type SpecificAttendee = string extends SpecificAttendeeId ? never : Attendee; diff --git a/packages/framework/presence/src/presenceDatastoreManager.ts b/packages/framework/presence/src/presenceDatastoreManager.ts index 267ba36236ea..2ec38b9e2642 100644 --- a/packages/framework/presence/src/presenceDatastoreManager.ts +++ b/packages/framework/presence/src/presenceDatastoreManager.ts @@ -72,7 +72,7 @@ function isPresenceMessage( } /** - * @internal + * High-level contract for manager of singleton Presence datastore */ export interface PresenceDatastoreManager { joinSession(clientId: ClientConnectionId): void; diff --git a/packages/framework/presence/src/presenceManager.ts b/packages/framework/presence/src/presenceManager.ts index b2e1711fec66..97307b26e5ab 100644 --- a/packages/framework/presence/src/presenceManager.ts +++ b/packages/framework/presence/src/presenceManager.ts @@ -40,8 +40,6 @@ import type { /** * Portion of the container extension requirements ({@link ContainerExtension}) that are delegated to presence manager. - * - * @internal */ export type PresenceExtensionInterface = Required< Pick, "processSignal"> @@ -184,8 +182,6 @@ function setupSubComponents( /** * Instantiates Presence Manager - * - * @internal */ export function createPresenceManager( runtime: IEphemeralRuntime, diff --git a/packages/framework/presence/src/presenceStates.ts b/packages/framework/presence/src/presenceStates.ts index f63ba400fd9c..f5326d38721e 100644 --- a/packages/framework/presence/src/presenceStates.ts +++ b/packages/framework/presence/src/presenceStates.ts @@ -26,8 +26,6 @@ import { unbrandIVM } from "./valueManager.js"; * If the `Part` is an optional property, undefined will be included in the * result. Applying `Required` to the return type prior to extracting `Part` * does not work as expected. Use Exclude\<, undefined\> can be used as needed. - * - * @internal */ export type MapSchemaElement< TSchema extends StatesWorkspaceSchema, @@ -36,9 +34,13 @@ export type MapSchemaElement< > = ReturnType[Part]; /** - * @internal + * Miscellaneous options for local state updates */ export interface RuntimeLocalUpdateOptions { + /** + * The maximum time in milliseconds that this update is allowed to be + * delayed before it must be sent to the service. + */ allowableUpdateLatencyMs: number; /** @@ -48,7 +50,7 @@ export interface RuntimeLocalUpdateOptions { } /** - * @internal + * Contract for `PresenceDatastoreManager` as required by States Workspaces ({@link PresenceStatesImpl}). */ export interface PresenceRuntime { readonly presence: Presence; @@ -79,8 +81,6 @@ type MapEntries = PresenceSubSchemaFromWo * * This generic aspect makes some typing difficult. The loose typing is not broadcast to the * consumers that are expected to maintain their schema over multiple versions of clients. - * - * @internal */ export interface ValueElementMap<_TSchema extends StatesWorkspaceSchema> { [key: string]: ClientRecord>; @@ -108,7 +108,7 @@ export interface ValueElementMap<_TSchema extends StatesWorkspaceSchema> { // } /** - * @internal + * Data content of a datastore entry in update messages */ export type ClientUpdateEntry = InternalTypes.ValueDirectoryOrState & { ignoreUnmonitored?: true; @@ -121,7 +121,7 @@ interface ValueUpdateRecord { } /** - * @internal + * Contract for Workspaces as required by `PresenceDatastoreManager` */ export interface PresenceStatesInternal { ensureContent( @@ -149,8 +149,6 @@ function isValueDirectory< /** * Merge a value directory. - * - * @internal */ export function mergeValueDirectory< T, @@ -203,8 +201,6 @@ export function mergeValueDirectory< * @remarks * In the case of ignored unmonitored data, the client entries are not stored, * though the value keys will be populated and often remain empty. - * - * @internal */ export function mergeUntrackedDatastore( key: string, diff --git a/packages/framework/presence/src/protocol.ts b/packages/framework/presence/src/protocol.ts index d4259a223513..1eec56252b31 100644 --- a/packages/framework/presence/src/protocol.ts +++ b/packages/framework/presence/src/protocol.ts @@ -14,14 +14,14 @@ import type { ClientUpdateEntry } from "./presenceStates.js"; import type { SystemWorkspaceDatastore } from "./systemWorkspace.js"; /** - * @internal + * Datastore that contains system workspace data */ export interface SystemDatastore { "system:presence": SystemWorkspaceDatastore; } /** - * @internal + * General datastore (and message) structure. */ export interface GeneralDatastoreMessageContent { [WorkspaceAddress: string]: { @@ -34,7 +34,7 @@ export interface GeneralDatastoreMessageContent { type DatastoreMessageContent = GeneralDatastoreMessageContent & SystemDatastore; /** - * @internal + * Datastore update message type. */ export const datastoreUpdateMessageType = "Pres:DatastoreUpdate"; interface DatastoreUpdateMessage { @@ -48,18 +48,18 @@ interface DatastoreUpdateMessage { } /** - * @internal + * Outbound datastore update message */ export type OutboundDatastoreUpdateMessage = OutboundExtensionMessage; /** - * @internal + * Inbound and verified datastore update message */ export type InboundDatastoreUpdateMessage = VerifiedInboundExtensionMessage; /** - * @internal + * Client join message type. */ export const joinMessageType = "Pres:ClientJoin"; interface ClientJoinMessage { @@ -73,16 +73,16 @@ interface ClientJoinMessage { } /** - * @internal + * Outbound client join message */ export type OutboundClientJoinMessage = OutboundExtensionMessage; /** - * @internal + * Inbound and verified client join message */ export type InboundClientJoinMessage = VerifiedInboundExtensionMessage; /** - * @internal + * Messages structures that can be sent and received as understood in the presence protocol */ export type SignalMessages = ClientJoinMessage | DatastoreUpdateMessage; diff --git a/packages/framework/presence/src/stateDatastore.ts b/packages/framework/presence/src/stateDatastore.ts index ef04e585d480..b60d48b47fcc 100644 --- a/packages/framework/presence/src/stateDatastore.ts +++ b/packages/framework/presence/src/stateDatastore.ts @@ -12,9 +12,6 @@ import type { AttendeeId, PresenceWithNotifications as Presence } from "./presen // TValue extends InternalTypes.ValueDirectoryOrState = InternalTypes.ValueDirectoryOrState, // > = TValue extends InternalTypes.ValueDirectoryOrState ? InternalTypes.ValueDirectoryOrState : never; -// /** -// * @internal -// */ // export interface StateDatastoreSchema { // // This type is not precise. It may // // need to be replaced with StatesWorkspace schema pattern @@ -24,9 +21,14 @@ import type { AttendeeId, PresenceWithNotifications as Presence } from "./presen // } /** - * @internal + * Miscellaneous options for local state updates */ export interface LocalStateUpdateOptions { + /** + * When defined, this is the maximum time in milliseconds that this + * update is allowed to be delayed before it must be sent to service. + * When `undefined`, the callee may determine maximum delay. + */ allowableUpdateLatencyMs: number | undefined; /** @@ -36,7 +38,8 @@ export interface LocalStateUpdateOptions { } /** - * @internal + * Contract for States Workspace to support State Manager access to + * datastore and general internal presence knowledge. */ export interface StateDatastore< TKey extends string, @@ -59,8 +62,6 @@ export interface StateDatastore< /** * Helper to get a handle from a datastore. - * - * @internal */ export function handleFromDatastore< // Constraining TSchema would be great, but it seems nested types (at least with undefined) cause trouble. @@ -79,8 +80,6 @@ export function handleFromDatastore< /** * Helper to get the datastore back from its handle. - * - * @internal */ export function datastoreFromHandle< TKey extends string, diff --git a/packages/framework/presence/src/systemWorkspace.ts b/packages/framework/presence/src/systemWorkspace.ts index b4675e4221fe..342de7818f5e 100644 --- a/packages/framework/presence/src/systemWorkspace.ts +++ b/packages/framework/presence/src/systemWorkspace.ts @@ -18,8 +18,6 @@ import type { AnyWorkspace, StatesWorkspaceSchema } from "./types.js"; /** * The system workspace's datastore structure. - * - * @internal */ export interface SystemWorkspaceDatastore { clientToSessionId: { @@ -62,7 +60,7 @@ class SessionClient implements Attendee { } /** - * @internal + * Internal workspace that manages metadata for session attendees. */ export interface SystemWorkspace // Portion of Presence that is handled by SystemWorkspace along with @@ -287,8 +285,6 @@ class SystemWorkspaceImpl implements PresenceStatesInternal, SystemWorkspace { /** * Instantiates the system workspace. - * - * @internal */ export function createSystemWorkspace( attendeeId: AttendeeId, diff --git a/packages/framework/presence/src/types.ts b/packages/framework/presence/src/types.ts index 5a3d64120be3..db30f301260b 100644 --- a/packages/framework/presence/src/types.ts +++ b/packages/framework/presence/src/types.ts @@ -181,8 +181,6 @@ export interface NotificationsWorkspace` when value of or containing expected type `T` is yet unknown. + * - Cast any value to `UnverifiedBrand` using `as unknown as UnverifiedBrand` + * when it is not yet confirmed that value is of type `T`. + * + * - When `T` value is needed, use narrowing type guards to check (preferred) + * or cast from `UnverifiedBrand` using `as unknown` when "instance" must + * be parsed to `T`. * - * - Cast from with `as unknown` when "instance" will be parsed to `T`. + * @example Example narrowing type guard: + * ```typescript + * function validateFoo( + * unverified: Foo | (Record & UnverifiedBrand) + * ): unverified is Foo { + * return unverified.IFooProvider === unverified; + * } + * ``` * * @sealed * @internal @@ -136,6 +149,12 @@ export type InboundExtensionMessage; /** + * Runtime properties of an extension. + * + * @remarks + * This is used to coordinate select types that are known only to the extension, but + * that host will respect where it calls back or provides extension specific data. + * * @internal */ export interface ExtensionRuntimeProperties {