@fluidframework/core-interfaces 2.0.0-internal.7.3.0 → 2.0.0-internal.8.0.0

package/lib/core-interfaces-alpha.d.ts

@@ -1,3 +1,9 @@
+/**
+ * Types supported by {@link IConfigProviderBase}.
+ * @alpha
+ */
+export declare type ConfigTypes = string | number | boolean | number[] | string[] | boolean[] | undefined;
+
 /**
  * Allows an interface to extend interfaces that already extend an {@link IEventProvider}.
  *
@@ -20,37 +26,11 @@
  * ```
  *
  * interface B will now extend interface A and its events
- *
+ * @alpha
  */
 export declare type ExtendEventProvider<TBaseEvent extends IEvent, TBase extends IEventProvider<TBaseEvent>, TEvent extends TBaseEvent> = Omit<Omit<Omit<TBase, "on">, "once">, "off"> & IEventProvider<TBaseEvent> & IEventProvider<TEvent>;
 
-/**
- * Error types the Fluid Framework may report.
- */
-export declare const FluidErrorTypes: {
-    /**
-     * Some error, most likely an exception caught by runtime and propagated to container as critical error
-     */
-    readonly genericError: "genericError";
-    /**
-     * Throttling error from server. Server is busy and is asking not to reconnect for some time
-     */
-    readonly throttlingError: "throttlingError";
-    /**
-     * Data loss error detected by Container / DeltaManager. Likely points to storage issue.
-     */
-    readonly dataCorruptionError: "dataCorruptionError";
-    /**
-     * Error encountered when processing an operation. May correlate with data corruption.
-     */
-    readonly dataProcessingError: "dataProcessingError";
-    /**
-     * Error indicating an API is being used improperly resulting in an invalid operation.
-     */
-    readonly usageError: "usageError";
-};
-
-export declare type FluidErrorTypes = (typeof FluidErrorTypes)[keyof typeof FluidErrorTypes];
+/* Excluded from this release type: FluidErrorTypes */
 
 /**
  * This utility type take interface(s) that follow the FluidObject pattern, and produces
@@ -83,7 +63,7 @@ export declare type FluidErrorTypes = (typeof FluidErrorTypes)[keyof typeof Flui
  *
  * You can inspect multiple types via a intersection. For example:
  * `FluidObject<IFoo & IBar>`
- *
+ * @alpha
  */
 export declare type FluidObject<T = unknown> = {
     [P in FluidObjectProviderKeys<T>]?: T[P];
@@ -96,7 +76,7 @@ export declare type FluidObject<T = unknown> = {
  * See {@link FluidObject}
  *
  * For example `FluidObjectKeys<IFoo & IBar>` would result in `"IFoo" | "IBar"`
- *
+ * @alpha
  */
 export declare type FluidObjectKeys<T> = keyof FluidObject<T>;
 
@@ -124,11 +104,39 @@ export declare type FluidObjectKeys<T> = keyof FluidObject<T>;
  *
  * This pattern enables discovery, and delegation in a standard way which is central
  * to FluidObject pattern.
+ * @alpha
  */
 export declare type FluidObjectProviderKeys<T, TProp extends keyof T = keyof T> = string extends TProp ? never : number extends TProp ? never : TProp extends keyof Required<T>[TProp] ? Required<T>[TProp] extends Required<Required<T>[TProp]>[TProp] ? TProp : never : never;
 
+/**
+ * Base interface for providing configurations to enable/disable/control features.
+ * @alpha
+ */
+export declare interface IConfigProviderBase {
+    /**
+     * For the specified config name this function gets the value.
+     *
+     * This type is meant be easy to implement by Fluid Framework consumers
+     * so the returned valued needs minimal type coercion, and allows consumers to
+     * return values in a natural way from whatever source they retrieve them.
+     *
+     * For instance a value of 1 maybe be returned as a string or a number.
+     * For array types a json string or an object are allowable.
+     *
+     * It should return undefined if there is no value available for the config name.
+     *
+     * @param name - The name of the config to get the value for.
+     *
+     * @privateRemarks Generally, this type should only be taken as input, and be wrapped by an
+     * internal monitoring context from the fluidframework/telemetry-utils package. That will provide
+     * a wrapper with provides strongly typed access to values via consistent type coercion.
+     */
+    getRawConfig(name: string): ConfigTypes;
+}
+
 /**
  * Base interface for objects that require lifetime management via explicit disposal.
+ * @alpha
  */
 export declare interface IDisposable {
     /**
@@ -153,6 +161,8 @@ export declare interface IDisposable {
  * those from container-definitions. Once fully migrated, this will be a base interface for all errors and
  * warnings emitted by the Fluid Framework. Currently only the container layer is using IErrorBase.
  * Runtime and others will follow soon.
+ *
+ * @alpha
  */
 export declare interface IErrorBase extends Partial<Error> {
     /**
@@ -191,6 +201,7 @@ export declare interface IErrorBase extends Partial<Error> {
 
 /**
  * Base interface for error event emitters.
+ * @alpha
  */
 export declare interface IErrorEvent extends IEvent {
     /**
@@ -203,6 +214,7 @@ export declare interface IErrorEvent extends IEvent {
 
 /**
  * Base interface for event emitters.
+ * @alpha
  */
 export declare interface IEvent {
     /**
@@ -220,6 +232,7 @@ export declare interface IEvent {
 
 /**
  * Base interface for event providers.
+ * @alpha
  */
 export declare interface IEventProvider<TEvent extends IEvent> {
     /**
@@ -238,6 +251,7 @@ export declare interface IEventProvider<TEvent extends IEvent> {
 
 /**
  * The placeholder type that should be used instead of `this` in events.
+ * @alpha
  */
 export declare type IEventThisPlaceHolder = {
     thisPlaceHolder: "thisPlaceHolder";
@@ -251,6 +265,7 @@ export declare type IEventThisPlaceHolder = {
  * It currently supports the max of 15 event overloads which is more than we use anywhere.
  * At more than 15 overloads we start to hit {@link https://github.com/microsoft/TypeScript/issues/37209 | TS2589}.
  * If we need to move beyond 15 we should evaluate using a mapped type pattern like `{"event":(listenerArgs)=>void}`
+ * @alpha
  */
 export declare type IEventTransformer<TThis, TEvent extends IEvent> = TEvent extends {
     (event: infer E0, listener: (...args: infer A0) => void): any;
@@ -404,75 +419,20 @@ export declare type IEventTransformer<TThis, TEvent extends IEvent> = TEvent ext
     (event: string, listener: (...args: any[]) => void): any;
 } ? TransformedEvent<TThis, E0, A0> : TransformedEvent<TThis, string, any[]>;
 
-/**
- * Data structure used to describe the code to load on the Fluid document.
- *
- * @deprecated in favor of {@link @fluidframework/container-definitions#IFluidCodeDetails}
- * to have code loading modules in same package.
- */
-export declare interface IFluidCodeDetails {
-    /**
-     * The code package to be used on the Fluid document. This is either the package name which will be loaded
-     * from a package manager. Or the expanded Fluid package.
-     */
-    readonly package: string | Readonly<IFluidPackage>;
-    /**
-     * Configuration details. This includes links to the package manager and base CDNs.
-     */
-    readonly config?: IFluidCodeDetailsConfig;
-}
+/* Excluded from this release type: IFluidCodeDetails */
 
-/**
- * @deprecated in favor of {@link @fluidframework/container-definitions#IFluidCodeDetailsComparer}
- * to have code loading modules in same package.
- */
-export declare const IFluidCodeDetailsComparer: keyof IProvideFluidCodeDetailsComparer;
+/* Excluded from this release type: IFluidCodeDetailsComparer */
 
-/**
- * Provides capability to compare Fluid code details.
- *
- * @deprecated in favor of {@link @fluidframework/container-definitions#IFluidCodeDetailsComparer}
- * to have code loading modules in same package.
- */
-export declare interface IFluidCodeDetailsComparer extends IProvideFluidCodeDetailsComparer {
-    /**
-     * Determines if the `candidate` code details satisfy the constraints specified in `constraint` code details.
-     *
-     * Similar semantics to:
-     * {@link https://github.com/npm/node-semver#usage}
-     */
-    satisfies(candidate: IFluidCodeDetails, constraint: IFluidCodeDetails): Promise<boolean>;
-    /**
-     * Returns a number representing the ascending sort order of the `a` and `b` code details:
-     *
-     * - `< 0` if `a < b`.
-     *
-     * - `= 0` if `a === b`.
-     *
-     * - `> 0` if `a > b`.
-     *
-     * - `undefined` if `a` is not comparable to `b`.
-     *
-     * Similar semantics to:
-     * {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort#description | Array.sort}
-     */
-    compare(a: IFluidCodeDetails, b: IFluidCodeDetails): Promise<number | undefined>;
-}
+/* Excluded from this release type: IFluidCodeDetailsConfig */
 
 /**
- * Package manager configuration. Provides a key value mapping of config values.
- *
- * @deprecated in favor of {@link @fluidframework/container-definitions#IFluidCodeDetailsConfig}
- * to have code loading modules in same package.
+ * @alpha
  */
-export declare interface IFluidCodeDetailsConfig {
-    readonly [key: string]: string;
-}
-
 export declare const IFluidHandle: keyof IProvideFluidHandle;
 
 /**
  * Handle to a shared {@link FluidObject}.
+ * @alpha
  */
 export declare interface IFluidHandle<T = FluidObject & IFluidLoadable> extends IProvideFluidHandle {
     /**
@@ -504,10 +464,14 @@ export declare interface IFluidHandle<T = FluidObject & IFluidLoadable> extends
     bind(handle: IFluidHandle): void;
 }
 
+/**
+ * @alpha
+ */
 export declare const IFluidHandleContext: keyof IProvideFluidHandleContext;
 
 /**
  * Describes a routing context from which other `IFluidHandleContext`s are defined.
+ * @alpha
  */
 export declare interface IFluidHandleContext extends IProvideFluidHandleContext {
     /**
@@ -530,155 +494,72 @@ export declare interface IFluidHandleContext extends IProvideFluidHandleContext
     resolveHandle(request: IRequest): Promise<IResponse>;
 }
 
+/**
+ * @alpha
+ */
 export declare const IFluidLoadable: keyof IProvideFluidLoadable;
 
 /**
  * A shared FluidObject has a URL from which it can be referenced
+ * @alpha
  */
 export declare interface IFluidLoadable extends IProvideFluidLoadable {
     handle: IFluidHandle;
 }
 
-/**
- * Fluid-specific properties expected on a package to be loaded by the code loader.
- * While compatible with the npm package format it is not necessary that that package is an
- * npm package:
- * {@link https://stackoverflow.com/questions/10065564/add-custom-metadata-or-config-to-package-json-is-it-valid}
- *
- * @deprecated In favor of {@link @fluidframework/container-definitions#IFluidPackage}
- * to have code loading modules in same package.
- */
-export declare interface IFluidPackage {
-    /**
-     * The name of the package that this code represnets
-     */
-    name: string;
-    /**
-     * This object represents the Fluid specific properties of the package
-     */
-    fluid: {
-        /**
-         * The name of the of the environment. This should be something like browser, or node
-         * and contain the necessary targets for loading this code in that environment.
-         */
-        [environment: string]: undefined | IFluidPackageEnvironment;
-    };
-    /**
-     * General access for extended fields as specific usages will
-     * likely have additional infornamation like a definition of
-     * compatible versions, or deployment information like rings or rollouts.
-     */
-    [key: string]: unknown;
-}
+/* Excluded from this release type: IFluidPackage */
 
-/**
- * Specifies an environment on Fluid property of an {@link IFluidPackage}.
- *
- * @deprecated In favor of {@link @fluidframework/container-definitions#IFluidPackageEnvironment}
- * to have code loading modules in same package.
- */
-export declare interface IFluidPackageEnvironment {
-    /**
-     * The name of the target. For a browser environment, this could be umd for scripts
-     * or css for styles.
-     */
-    [target: string]: undefined | {
-        /**
-         * List of files for the target. These can be relative or absolute.
-         * The code loader should resolve relative paths, and validate all
-         * full urls.
-         */
-        files: string[];
-        /**
-         * General access for extended fields as specific usages will
-         * likely have additional infornamation like a definition
-         * of Library, the entrypoint for umd packages
-         */
-        [key: string]: unknown;
-    };
-}
-
-/**
- * @deprecated Will be removed in future major release. Migrate all usage of IFluidRouter to the "entryPoint" pattern. Refer to Removing-IFluidRouter.md
- */
-export declare const IFluidRouter: keyof IProvideFluidRouter;
-
-/**
- * @deprecated Will be removed in future major release. Migrate all usage of IFluidRouter to the "entryPoint" pattern. Refer to Removing-IFluidRouter.md
- */
-export declare interface IFluidRouter extends IProvideFluidRouter {
-    request(request: IRequest): Promise<IResponse>;
-}
+/* Excluded from this release type: IFluidPackageEnvironment */
 
-export declare const IFluidRunnable: keyof IProvideFluidRunnable;
+/* Excluded from this release type: IFluidRunnable */
 
-export declare interface IFluidRunnable {
-    run(...args: any[]): Promise<void>;
-    stop(reason?: string): void;
-}
+/* Excluded from this release type: IGenericError */
 
-/**
- * Generic wrapper for an unrecognized/uncategorized error object
- */
-export declare interface IGenericError extends IErrorBase {
-    /**
-     * {@inheritDoc IErrorBase.errorType}
-     */
-    readonly errorType: typeof FluidErrorTypes.genericError;
-    error?: any;
-}
+/* Excluded from this release type: ILoggingError */
 
-/**
- * An error object that supports exporting its properties to be logged to telemetry
- */
-export declare interface ILoggingError extends Error {
-    /**
-     * Return all properties from this object that should be logged to telemetry
-     */
-    getTelemetryProperties(): ITelemetryBaseProperties;
-}
+/* Excluded from this release type: IProvideFluidCodeDetailsComparer */
 
 /**
- * @deprecated in favor of {@link @fluidframework/container-definitions#IProvideFluidCodeDetailsComparer}
- * to have code loading modules in same package.
+ * @alpha
  */
-export declare interface IProvideFluidCodeDetailsComparer {
-    readonly IFluidCodeDetailsComparer: IFluidCodeDetailsComparer;
-}
-
 export declare interface IProvideFluidHandle {
     readonly IFluidHandle: IFluidHandle;
 }
 
+/**
+ * @alpha
+ */
 export declare interface IProvideFluidHandleContext {
     readonly IFluidHandleContext: IFluidHandleContext;
 }
 
+/**
+ * @alpha
+ */
 export declare interface IProvideFluidLoadable {
     readonly IFluidLoadable: IFluidLoadable;
 }
 
+/* Excluded from this release type: IProvideFluidRunnable */
+
 /**
- * Request routing
- * @deprecated Will be removed in future major release. Migrate all usage of IFluidRouter to the "entryPoint" pattern. Refer to Removing-IFluidRouter.md
+ * @alpha
  */
-export declare interface IProvideFluidRouter {
-    readonly IFluidRouter: IFluidRouter;
-}
-
-export declare interface IProvideFluidRunnable {
-    readonly IFluidRunnable: IFluidRunnable;
-}
-
 export declare interface IRequest {
     url: string;
     headers?: IRequestHeader;
 }
 
+/**
+ * @alpha
+ */
 export declare interface IRequestHeader {
     [index: string]: any;
 }
 
+/**
+ * @alpha
+ */
 export declare interface IResponse {
     mimeType: string;
     status: number;
@@ -689,37 +570,18 @@ export declare interface IResponse {
     stack?: string;
 }
 
-/**
- * @deprecated in favor of {@link @fluidframework/container-definitions#isFluidCodeDetails}
- * to have code loading modules in same package.
- */
-export declare const isFluidCodeDetails: (details: unknown) => details is Readonly<IFluidCodeDetails>;
+/* Excluded from this release type: isFluidCodeDetails */
 
-/**
- * Check if the package.json defines a Fluid package.
- *
- * @deprecated in favor of {@link @fluidframework/container-definitions#isFluidPackage}
- * to have code loading modules in same package.
- *
- * @param pkg - The package json data to check if it is a Fluid package.
- */
-export declare const isFluidPackage: (pkg: unknown) => pkg is Readonly<IFluidPackage>;
+/* Excluded from this release type: isFluidPackage */
 
-/**
- * @see {@link Tagged} for info on tagging
- *
- * @deprecated Use Tagged\<TelemetryBaseEventPropertyType\>
- */
-export declare interface ITaggedTelemetryPropertyType {
-    value: TelemetryEventPropertyType;
-    tag: string;
-}
+/* Excluded from this release type: ITaggedTelemetryPropertyType */
 
 /**
  * Base interface for logging telemetry statements.
  * Can contain any number of properties that get serialized as json payload.
  * @param category - category of the event, like "error", "performance", "generic", etc.
  * @param eventName - name of the event.
+ * @alpha
  */
 export declare interface ITelemetryBaseEvent extends ITelemetryBaseProperties {
     category: string;
@@ -729,6 +591,7 @@ export declare interface ITelemetryBaseEvent extends ITelemetryBaseProperties {
 /**
  * Interface to output telemetry events.
  * Implemented by hosting app / loader
+ * @alpha
  */
 export declare interface ITelemetryBaseLogger {
     send(event: ITelemetryBaseEvent, logLevel?: LogLevel): void;
@@ -737,6 +600,7 @@ export declare interface ITelemetryBaseLogger {
 
 /**
  * JSON-serializable properties, which will be logged with telemetry.
+ * @alpha
  */
 export declare type ITelemetryBaseProperties = ITelemetryProperties;
 
@@ -746,6 +610,7 @@ export declare type ITelemetryBaseProperties = ITelemetryProperties;
  *
  * @deprecated For internal use within FluidFramework, use ITelemetryErrorEventExt in \@fluidframework/telemetry-utils.
  * No replacement intended for FluidFramework consumers.
+ * @alpha
  */
 export declare interface ITelemetryErrorEvent extends ITelemetryProperties {
     eventName: string;
@@ -757,6 +622,7 @@ export declare interface ITelemetryErrorEvent extends ITelemetryProperties {
  *
  * @deprecated For internal use within FluidFramework, use ITelemetryGenericEventExt in \@fluidframework/telemetry-utils.
  * No replacement intended for FluidFramework consumers.
+ * @alpha
  */
 export declare interface ITelemetryGenericEvent extends ITelemetryProperties {
     eventName: string;
@@ -770,6 +636,7 @@ export declare interface ITelemetryGenericEvent extends ITelemetryProperties {
  *
  * @deprecated For internal use within FluidFramework, use ITelemetryLoggerExt in \@fluidframework/telemetry-utils.
  * No replacement intended for FluidFramework consumers.
+ * @alpha
  */
 export declare interface ITelemetryLogger extends ITelemetryBaseLogger {
     /**
@@ -807,6 +674,7 @@ export declare interface ITelemetryLogger extends ITelemetryBaseLogger {
  *
  * @deprecated For internal use within FluidFramework, use ITelemetryPerformanceEventExt in \@fluidframework/telemetry-utils.
  * No replacement intended for FluidFramework consumers.
+ * @alpha
  */
 export declare interface ITelemetryPerformanceEvent extends ITelemetryGenericEvent {
     duration?: number;
@@ -816,34 +684,19 @@ export declare interface ITelemetryPerformanceEvent extends ITelemetryGenericEve
  * {@inheritDoc ITelemetryBaseProperties}
  *
  * @deprecated Renamed to {@link ITelemetryBaseProperties}
+ * @alpha
  */
 export declare interface ITelemetryProperties {
     [index: string]: TelemetryEventPropertyType | Tagged<TelemetryEventPropertyType>;
 }
 
-/**
- * Warning emitted when requests to storage are being throttled
- */
-export declare interface IThrottlingWarning extends IErrorBase {
-    /**
-     * {@inheritDoc IErrorBase.errorType}
-     */
-    readonly errorType: typeof FluidErrorTypes.throttlingError;
-    readonly retryAfterSeconds: number;
-}
+/* Excluded from this release type: IThrottlingWarning */
 
-/**
- * Error indicating an API is being used improperly resulting in an invalid operation.
- */
-export declare interface IUsageError extends IErrorBase {
-    /**
-     * {@inheritDoc IErrorBase.errorType}
-     */
-    readonly errorType: typeof FluidErrorTypes.usageError;
-}
+/* Excluded from this release type: IUsageError */
 
 /**
  * Specify levels of the logs.
+ * @alpha
  */
 export declare const LogLevel: {
     readonly verbose: 10;
@@ -853,11 +706,13 @@ export declare const LogLevel: {
 
 /**
  * Specify a level to the log to filter out logs based on the level.
+ * @alpha
  */
 export declare type LogLevel = (typeof LogLevel)[keyof typeof LogLevel];
 
 /**
  * Does the type replacement by changing types of {@link IEventThisPlaceHolder} to `TThis`
+ * @alpha
  */
 export declare type ReplaceIEventThisPlaceHolder<L extends any[], TThis> = L extends any[] ? {
     [K in keyof L]: L[K] extends IEventThisPlaceHolder ? TThis : L[K];
@@ -869,25 +724,20 @@ export declare type ReplaceIEventThisPlaceHolder<L extends any[], TThis> = L ext
  *
  * This indicates that the value should be organized or handled differently by loggers in various first or third
  * party scenarios. For example, tags are used to mark data that should not be stored in logs for privacy reasons.
+ * @alpha
  */
 export declare interface Tagged<V, T extends string = string> {
     value: V;
     tag: T;
 }
 
-/**
- * Property types that can be logged.
- *
- * @remarks Logging entire objects is considered extremely dangerous from a telemetry point of view because people can
- * easily add fields to objects that shouldn't be logged and not realize it's going to be logged.
- * General best practice is to explicitly log the fields you care about from objects.
- */
-export declare type TelemetryBaseEventPropertyType = TelemetryEventPropertyType;
+/* Excluded from this release type: TelemetryBaseEventPropertyType */
 
 /**
  * Examples of known categories, however category can be any string for extensibility.
  *
  * @deprecated Moved to \@fluidframework/telemetry-utils package
+ * @alpha
  */
 export declare type TelemetryEventCategory = "generic" | "error" | "performance";
 
@@ -895,12 +745,14 @@ export declare type TelemetryEventCategory = "generic" | "error" | "performance"
  * {@inheritDoc TelemetryBaseEventPropertyType}
  *
  * @deprecated Renamed to {@link TelemetryBaseEventPropertyType}
+ * @alpha
  */
 export declare type TelemetryEventPropertyType = string | number | boolean | undefined;
 
 /**
  * Transforms the event overload by replacing {@link IEventThisPlaceHolder} with `TThis` in the event listener
  * arguments and having the overload return `TTHis` as well
+ * @alpha
  */
 export declare type TransformedEvent<TThis, E, A extends any[]> = (event: E, listener: (...args: ReplaceIEventThisPlaceHolder<A, TThis>) => void) => TThis;