@fluidframework/core-interfaces 2.92.0 → 2.100.0

package/src/erasedType.ts

@@ -13,13 +13,30 @@
  * allowing code outside of a package to have a reference/handle to something in the package in a type safe way without the package having to publicly export the types of the object.
  * This should not be confused with the more specific IFluidHandle which is also named after this design pattern.
  *
+ * As this is a class and not just an interface, to match derived types, the
+ * declarations for any two derivatives must come from the same source - the
+ * same package version. If a type must cross package boundaries, as may be the
+ * case for cross layer types, the derived type should pick a specific version
+ * of core-interfaces to import ErasedType from. Exact versions are best, but
+ * as security best practice, use ~ specification. Consumers are expected to
+ * use a package manager that will produce consistency over minor patches.
+ * A change in version should be considered a breaking change.
+ *
  * Recommended usage is to use `interface` instead of `type` so tooling (such as tsc and refactoring tools)
  * uses the type name instead of expanding it.
  *
  * @example
+ * package.json:
+ * ```json
+ *   "dependencies": {
+ *     "@fluidframework/erased-type-v1": "npm:@fluidframework/core-interfaces@~2.0.0"
+ *   }
+ * ```
+ * source.ts:
  * ```typescript
+ * import { ErasedType as ErasedTypeV1 } from "@fluidframework/erased-type-v1";
  * // public sealed type
- * export interface ErasedMyType extends ErasedType<"myPackage.MyType"> {}
+ * export interface ErasedMyType extends ErasedTypeV1<"myPackage.MyType"> {}
  * // internal type
  * export interface MyType {
  * 	example: number;
@@ -35,6 +52,7 @@
  *
  * Do not use this class with `instanceof`: this will always be false at runtime,
  * but the compiler may think it's true in some cases.
+ *
  * @privateRemarks
  * For this pattern to work well it needs to be difficult for a user of the erased type to
  * implicitly use something other than a instance received from the package as an instance of the erased type in type safe code.
@@ -57,7 +75,7 @@
  * @sealed
  * @public
  */
-export abstract class ErasedType<out Name = unknown> {
+export declare abstract class ErasedType<out Name = unknown> {
 	/**
 	 * Compile time only marker to make type checking more strict.
 	 * This method will not exist at runtime and accessing it is invalid.
@@ -70,31 +88,34 @@ export abstract class ErasedType<out Name = unknown> {
 	/**
 	 * This class should never exist at runtime, so make it un-constructable.
 	 */
-	private constructor() {}
+	private constructor();
 
 	/**
 	 * Since this class is a compile time only type brand, `instanceof` will never work with it.
-	 * This `Symbol.hasInstance` implementation ensures that `instanceof` will error if used,
-	 * and in TypeScript 5.3 and newer will produce a compile time error if used.
+	 * This `Symbol.hasInstance` declaration (no definition) ensures that `instanceof` will
+	 * produce `ReferenceError` if used at runtime. And in TypeScript 5.3 and newer will produce
+	 * a compile time error if used.
 	 */
-	public static [Symbol.hasInstance](value: never): value is never {
-		throw new Error(
-			"ErasedType is a compile time type brand not a real class that can be used with `instanceof` at runtime.",
-		);
-	}
+	public static [Symbol.hasInstance](value: never): value is never;
 }
 
 /**
  * Used to mark a `@sealed` interface in a strongly typed way to prevent external implementations.
+ *
  * @remarks
  * This is an alternative to {@link ErasedType} which is more ergonomic to implement in the case where the implementation can extend `ErasedTypeImplementation`.
  *
  * Users of interfaces extending this should never refer to anything about this class:
  * migrating the type branding to another mechanism, like {@link ErasedType} should be considered a non-breaking change.
+ *
+ * @see {@link ErasedType} for version compatibility notes.
+ *
  * @privateRemarks
  * Implement interfaces which extend this by sub-classing {@link ErasedTypeImplementation}.
  *
  * This class should only be a `type` package export, preventing users from extending it directly.
+ * But since {@link ErasedTypeImplementation} does extend it, an implementation
+ * of the constructor must be provided, unlike {@link ErasedType}.
  *
  * Since {@link ErasedTypeImplementation} is exported as `@internal`, this restricts implementations of the sealed interfaces to users of `@internal` APIs, which should be anything within this release group.
  * Any finer grained restrictions can be done as documentation, but not type enforced.

package/src/exposedInternalUtilityTypes.ts

@@ -27,7 +27,7 @@ const RecursionMarkerSymbol: unique symbol = Symbol("recursion here");
  * @privateRemarks
  * WeakRef should be added when lib is updated to ES2021 or later.
  *
- * @beta
+ * @public
  */
 export type ReadonlySupportedGenerics =
 	| IFluidHandle
@@ -46,7 +46,7 @@ export type ReadonlySupportedGenerics =
  * depth limit when a recursive type is found. Use of `0` will stop applying
  * `DeepReadonly` at the first point recursion is detected.
  *
- * @beta
+ * @public
  * @system
  */
 export type DeepReadonlyRecursionLimit = "NoLimit" | 0 | `+${string}`;
@@ -67,7 +67,7 @@ export type DeepReadonlyRecursionLimit = "NoLimit" | 0 | `+${string}`;
  * exported anyway. All in namespace are left exported to avoid api-extractor
  * potentially failing to validate other modules correctly.
  *
- * @beta
+ * @public
  * @system
  */
 // eslint-disable-next-line @typescript-eslint/no-namespace

package/src/fluidLoadable.ts

@@ -29,24 +29,3 @@ export interface IFluidLoadable extends IProvideFluidLoadable {
 	 */
 	readonly handle: IFluidHandle;
 }
-
-/**
- * @internal
- */
-export const IFluidRunnable: keyof IProvideFluidRunnable = "IFluidRunnable";
-
-/**
- * @internal
- */
-export interface IProvideFluidRunnable {
-	readonly IFluidRunnable: IFluidRunnable;
-}
-/**
- * @internal
- */
-export interface IFluidRunnable {
-	// TODO: Use `unknown` instead (API-Breaking)
-
-	run(...args: any[]): Promise<void>;
-	stop(reason?: string): void;
-}

package/src/fluidMap.ts

@@ -0,0 +1,151 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+/**
+ * Like TypeScript's built-in `Iterable` type.
+ *
+ * @privateRemarks
+ * This exists to be unaffected by TypeScript's version and configuration options.
+ *
+ * @sealed @beta
+ */
+export interface FluidIterable<T> {
+	/**
+	 * Returns an iterator over the elements in this iterable.
+	 *
+	 * @remarks Works like the built-in {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/iterator | \[Symbol.iterator\]} protocol.
+	 */
+	[Symbol.iterator](): FluidIterableIterator<T>;
+}
+
+/**
+ * Like TypeScript's built-in iterable iterator type.
+ *
+ * @privateRemarks
+ * The done branch uses `any` rather than `undefined` to match TypeScript's built-in IteratorReturnResult, which defaults to any for the same reason.
+ * Using `undefined` causes TypeScript to include it in type inference at call sites like `Array.from` which would infer `T | undefined` instead of `T`.
+ * The done value is rarely meaningful to callers since values are mainly consumed when done is false.
+ * Thus `any` is not particularly harmful here, and the unsafety is worth it as
+ * it interacts better with the existing TypeScript `IteratorResult` interfaces where `TReturn` defaults to any.
+ *
+ * @sealed @beta
+ */
+export interface FluidIterableIterator<T> extends FluidIterable<T> {
+	/**
+	 * Returns the next element in the iteration sequence.
+	 *
+	 * @remarks Works like the built-in {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_iterator_protocol | Iterator.next} method.
+	 * When there are remaining elements, returns `\{ value: T; done?: false \}`.
+	 * When the iteration is complete, returns `\{ value: any; done: true \}`.
+	 */
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	next(): { value: T; done?: false } | { value: any; done: true };
+}
+
+/**
+ * Like TypeScript's built in `ReadonlyMap` type.
+ * Unlike the built in `ReadonlyMap`, this interface includes Symbol.toStringTag.
+ *
+ * @privateRemarks
+ * This exists so that Fluid has a `ReadonlyMap` type which is unaffected by TypeScript's version and configuration options,
+ * and safe to implement without being broken by changes to TypeScript's default ReadonlyMap type.
+ * All behavior exposed through this interface should be compatible with the corresponding behavior of built in ReadonlyMaps,
+ * but it may lack some of the newer APIs,
+ * and might express the type slightly different from how TypeScript does in its `ReadonlyMap` type.
+ *
+ * @sealed @beta
+ */
+export interface FluidReadonlyMap<K, V> {
+	/**
+	 * Returns an iterable of entries in the map.
+	 */
+	[Symbol.iterator](): FluidIterableIterator<[K, V]>;
+
+	/**
+	 * The number of entries in the map.
+	 */
+	readonly size: number;
+
+	/**
+	 * Returns an iterable of key, value pairs for every entry in the map.
+	 */
+	entries(): FluidIterableIterator<[K, V]>;
+
+	/**
+	 * Executes the provided function once per each key/value pair in the map.
+	 */
+	forEach(
+		callbackfn: (value: V, key: K, map: FluidReadonlyMap<K, V>) => void,
+		// Typing inherited from ReadonlyMap.
+		// eslint-disable-next-line @typescript-eslint/no-explicit-any
+		thisArg?: any,
+	): void;
+
+	/**
+	 * Returns the value associated to the specified key, or undefined if there is none.
+	 */
+	get(key: K): V | undefined;
+
+	/**
+	 * Returns a boolean indicating whether an element with the specified key exists or not.
+	 */
+	has(key: K): boolean;
+
+	/**
+	 * Returns an iterable of keys in the map.
+	 */
+	keys(): FluidIterableIterator<K>;
+
+	/**
+	 * Returns an iterable of values in the map.
+	 */
+	values(): FluidIterableIterator<V>;
+
+	/**
+	 * {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/toStringTag | Symbol.toStringTag}
+	 */
+	readonly [Symbol.toStringTag]: string;
+}
+
+/**
+ * Like TypeScript's built in `Map` type.
+ *
+ * @privateRemarks
+ * This exists so that Fluid has a `Map` type which is unaffected by TypeScript's version and configuration options,
+ * and safe to implement without being broken by changes to TypeScript's default Map type.
+ * All behavior exposed through this interface should be compatible with the corresponding behavior of JavaScript Maps,
+ * but it may lack some of the newer APIs,
+ * and might express the type slightly different from how TypeScript does in its `Map` type.
+ *
+ * @sealed @beta
+ */
+export interface FluidMap<K, V> extends FluidReadonlyMap<K, V> {
+	/**
+	 * Removes the specified element from the map by its key.
+	 *
+	 * @remarks
+	 * Unlike the built-in `Map.delete`, this returns `void` instead of a boolean.
+	 * This is intentional: in a distributed system, the caller often cannot reliably know
+	 * whether the element existed at the time of deletion.
+	 * Subtypes may override this to return a boolean if appropriate.
+	 */
+	delete(key: K): void;
+
+	/**
+	 * Executes the provided function once per each key/value pair in the map.
+	 */
+	forEach(
+		callbackfn: (value: V, key: K, map: FluidMap<K, V>) => void,
+		// Typing inherited from Map.
+		// eslint-disable-next-line @typescript-eslint/no-explicit-any
+		thisArg?: any,
+	): void;
+
+	/**
+	 * Adds a new element with a specified key and value to the map.
+	 * If an element with the same key already exists, the element will be updated.
+	 */
+	set(key: K, value: V): void;
+}

package/src/index.ts

@@ -7,6 +7,13 @@ export type { BrandedType } from "./brandedType.js";
 
 export type { IDisposable } from "./disposable.js";
 
+export type {
+	FluidIterable,
+	FluidIterableIterator,
+	FluidMap,
+	FluidReadonlyMap,
+} from "./fluidMap.js";
+
 export type {
 	IErrorBase,
 	IGenericError,
@@ -30,8 +37,8 @@ export type {
 	TransformedEvent,
 } from "./events.js";
 
-export type { IProvideFluidLoadable, IProvideFluidRunnable } from "./fluidLoadable.js";
-export { IFluidLoadable, IFluidRunnable } from "./fluidLoadable.js";
+export type { IProvideFluidLoadable } from "./fluidLoadable.js";
+export { IFluidLoadable } from "./fluidLoadable.js";
 
 // TypeScript forgets the index signature when customers augment IRequestHeader if we export *.
 // So we export the explicit members as a workaround:
@@ -57,6 +64,7 @@ export type {
 	ITelemetryBaseEvent,
 	ITelemetryBaseLogger,
 	ITelemetryBaseProperties,
+	LogLevelConst,
 	Tagged,
 	TelemetryBaseEventPropertyType,
 } from "./logger.js";

package/src/jsonDeserialized.ts

@@ -8,7 +8,7 @@ import type { InternalUtilityTypes } from "./exposedInternalUtilityTypes.js";
 /**
  * Options for {@link JsonDeserialized}.
  *
- * @beta
+ * @public
  */
 export interface JsonDeserializedOptions {
 	/**
@@ -107,7 +107,7 @@ export interface JsonDeserializedOptions {
  * function foo<T>(): JsonDeserialized<T> { ... }
  * ```
  *
- * @beta
+ * @public
  */
 export type JsonDeserialized<
 	T,

package/src/jsonSerializable.ts

@@ -8,7 +8,7 @@ import type { InternalUtilityTypes } from "./exposedInternalUtilityTypes.js";
 /**
  * Options for {@link JsonSerializable}.
  *
- * @beta
+ * @public
  */
 export interface JsonSerializableOptions {
 	/**
@@ -130,7 +130,7 @@ export interface JsonSerializableOptions {
  * proper use, that will never be an issue as any filtering of types will happen
  * before T recursion.
  *
- * @beta
+ * @public
  */
 export type JsonSerializable<
 	T,

package/src/jsonSerializationErrors.ts

@@ -10,7 +10,7 @@
  * @privateRemarks type is used over interface; so inspection of type
  * result can be more informative than just the type name.
  *
- * @beta
+ * @public
  * @system
  */
 // eslint-disable-next-line @typescript-eslint/consistent-type-definitions
@@ -25,7 +25,7 @@ export type SerializationErrorPerUndefinedArrayElement = {
  * @privateRemarks type is used over interface; so inspection of type
  * result can be more informative than just the type name.
  *
- * @beta
+ * @public
  * @system
  */
 // eslint-disable-next-line @typescript-eslint/consistent-type-definitions

package/src/jsonType.ts

@@ -15,7 +15,7 @@
  * Prefer using `JsonSerializable<unknown>` or `JsonDeserialized<unknown>` over this type that
  * is an implementation detail.
  *
- * @beta
+ * @public
  */
 export type JsonTypeWith<T> =
 	// eslint-disable-next-line @rushstack/no-new-null
@@ -30,7 +30,7 @@ export type JsonTypeWith<T> =
 /**
  * Portion of {@link JsonTypeWith} that is an object (including array) and not null.
  *
- * @beta
+ * @public
  */
 export type NonNullJsonObjectWith<T> =
 	| { [key: string | number]: JsonTypeWith<T> }
@@ -51,7 +51,7 @@ export type NonNullJsonObjectWith<T> =
  * ```
  * does not prevent later `x = 5`. (Does prevent `x.a = 2`.)
  *
- * @beta
+ * @public
  */
 export type ReadonlyJsonTypeWith<TReadonlyAlternates> =
 	// eslint-disable-next-line @rushstack/no-new-null

package/src/logger.ts

@@ -52,13 +52,58 @@ export interface ITelemetryBaseEvent extends ITelemetryBaseProperties {
 
 /**
  * Specify levels of the logs.
+ *
+ * @privateRemarks This interface exists solely for documentation. API Extractor does not
+ * propagate TSDoc comments from a const's inline type to API reports, so we define the shape
+ * here and use LogLevelConst on the LogLevel const to surface member docs.
+ *
+ * @public
+ */
+export interface LogLevelConst {
+	/**
+	 * Chatty logs useful for debugging.
+	 * @remarks They need not be collected in production.
+	 */
+	readonly verbose: 10;
+
+	/**
+	 * Information about the session.
+	 * @remarks These logs could be omitted in some sessions if needed (e.g. to reduce overall telemetry volume).
+	 * If any are collected from a particular session, all should be.
+	 */
+	readonly info: 20;
+
+	/**
+	 * Essential information about the operation of Fluid.
+	 * @remarks It is recommended that these should always be collected, even in production, for diagnostic purposes.
+	 */
+	readonly essential: 30;
+
+	/**
+	 * Default LogLevel
+	 * @remarks Prefer {@link LogLevelConst.info | LogLevel.info} when selecting a level explicitly since this will be deprecated and removed in a future release.
+	 */
+	readonly default: 20;
+
+	/**
+	 * To log errors.
+	 * @remarks Prefer {@link LogLevelConst.essential | LogLevel.essential} when selecting a level since this will be deprecated and removed in a future release.
+	 */
+	readonly error: 30;
+}
+
+/**
+ * Provides runtime {@link (LogLevel:type)} values via symbolic names
+ * @see {@link LogLevelConst} type.
  * @public
  */
-export const LogLevel = {
-	verbose: 10, // To log any verbose event for example when you are debugging something.
-	default: 20, // Default log level
-	error: 30, // To log errors.
-} as const;
+export const LogLevel: LogLevelConst = {
+	verbose: 10,
+	info: 20,
+	essential: 30,
+	default: 20,
+	error: 30,
+};
 
 /**
  * Specify a level to the log to filter out logs based on the level.
@@ -75,13 +120,13 @@ export interface ITelemetryBaseLogger {
 	/**
 	 * Log a telemetry event, if it meets the appropriate log-level threshold (see {@link ITelemetryBaseLogger.minLogLevel}).
 	 * @param event - The event to log.
-	 * @param logLevel - The log level of the event. Default: {@link (LogLevel:variable).default}.
+	 * @param logLevel - The log level of the event. Default: {@link LogLevelConst.default | LogLevel.default}.
 	 */
 	send(event: ITelemetryBaseEvent, logLevel?: LogLevel): void;
 
 	/**
 	 * Minimum log level to be logged.
-	 * @defaultValue {@link (LogLevel:variable).default}
+	 * @defaultValue {@link LogLevelConst.default | LogLevel.default}.
 	 */
 	minLogLevel?: LogLevel;
 }

package/src/opaqueJson.ts

@@ -19,7 +19,7 @@ import { BrandedType } from "./brandedType.js";
  * be read.
  *
  * @sealed
- * @beta
+ * @public
  */
 export declare class OpaqueJsonDeserialized<
 	T,
@@ -59,7 +59,7 @@ export declare class OpaqueJsonDeserialized<
  * when "instance" will be forwarded along.
  *
  * @sealed
- * @beta
+ * @public
  */
 export declare class OpaqueJsonSerializable<
 	T,