@fluidframework/core-interfaces 2.0.0-dev.5.3.2.178189 → 2.0.0-dev.6.4.0.191457

package/src/logger.ts

@@ -5,6 +5,8 @@
 
 /**
  * Examples of known categories, however category can be any string for extensibility.
+ *
+ * @deprecated Moved to \@fluidframework/telemetry-utils package
  */
 export type TelemetryEventCategory = "generic" | "error" | "performance";
 
@@ -15,13 +17,32 @@ export type TelemetryEventCategory = "generic" | "error" | "performance";
  * 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 type TelemetryBaseEventPropertyType = TelemetryEventPropertyType;
+
+/**
+ * {@inheritDoc TelemetryBaseEventPropertyType}
+ *
+ * @deprecated Renamed to {@link TelemetryBaseEventPropertyType}
+ */
 export type TelemetryEventPropertyType = string | number | boolean | undefined;
 
 /**
- * A property to be logged to telemetry containing both the value and a tag. Tags are generic strings that can be used
- * to mark pieces of information that should be organized or handled differently by loggers in various first or third
+ * A property to be logged to telemetry may require a tag indicating the value may contain sensitive data.
+ * This type wraps a value of the given type V in an object along with a string tag (type can be further specified as T).
+ *
+ * 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.
  */
+export interface Tagged<V, T extends string = string> {
+	value: V;
+	tag: T;
+}
+
+/**
+ * @see {@link Tagged} for info on tagging
+ *
+ * @deprecated Use Tagged\<TelemetryBaseEventPropertyType\>
+ */
 export interface ITaggedTelemetryPropertyType {
 	value: TelemetryEventPropertyType;
 	tag: string;
@@ -30,8 +51,15 @@ export interface ITaggedTelemetryPropertyType {
 /**
  * JSON-serializable properties, which will be logged with telemetry.
  */
+export type ITelemetryBaseProperties = ITelemetryProperties;
+
+/**
+ * {@inheritDoc ITelemetryBaseProperties}
+ *
+ * @deprecated Renamed to {@link ITelemetryBaseProperties}
+ */
 export interface ITelemetryProperties {
-	[index: string]: TelemetryEventPropertyType | ITaggedTelemetryPropertyType;
+	[index: string]: TelemetryEventPropertyType | Tagged<TelemetryEventPropertyType>;
 }
 
 /**
@@ -40,22 +68,41 @@ export interface ITelemetryProperties {
  * @param category - category of the event, like "error", "performance", "generic", etc.
  * @param eventName - name of the event.
  */
-export interface ITelemetryBaseEvent extends ITelemetryProperties {
+export interface ITelemetryBaseEvent extends ITelemetryBaseProperties {
 	category: string;
 	eventName: string;
 }
 
+/**
+ * Specify levels of the logs.
+ */
+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;
+
+/**
+ * Specify a level to the log to filter out logs based on the level.
+ */
+export type LogLevel = typeof LogLevel[keyof typeof LogLevel];
+
 /**
  * Interface to output telemetry events.
  * Implemented by hosting app / loader
  */
 export interface ITelemetryBaseLogger {
-	send(event: ITelemetryBaseEvent): void;
+	send(event: ITelemetryBaseEvent, logLevel?: LogLevel): void;
+
+	minLogLevel?: LogLevel;
 }
 
 /**
  * Informational (non-error) telemetry event
  * Maps to category = "generic"
+ *
+ * @deprecated For internal use within FluidFramework, use ITelemetryGenericEventExt in \@fluidframework/telemetry-utils.
+ * No replacement intended for FluidFramework consumers.
  */
 export interface ITelemetryGenericEvent extends ITelemetryProperties {
 	eventName: string;
@@ -65,6 +112,9 @@ export interface ITelemetryGenericEvent extends ITelemetryProperties {
 /**
  * Error telemetry event.
  * Maps to category = "error"
+ *
+ * @deprecated For internal use within FluidFramework, use ITelemetryErrorEventExt in \@fluidframework/telemetry-utils.
+ * No replacement intended for FluidFramework consumers.
  */
 export interface ITelemetryErrorEvent extends ITelemetryProperties {
 	eventName: string;
@@ -73,6 +123,9 @@ export interface ITelemetryErrorEvent extends ITelemetryProperties {
 /**
  * Performance telemetry event.
  * Maps to category = "performance"
+ *
+ * @deprecated For internal use within FluidFramework, use ITelemetryPerformanceEventExt in \@fluidframework/telemetry-utils.
+ * No replacement intended for FluidFramework consumers.
  */
 export interface ITelemetryPerformanceEvent extends ITelemetryGenericEvent {
 	duration?: number; // Duration of event (optional)
@@ -85,33 +138,44 @@ export interface ILoggingError extends Error {
 	/**
 	 * Return all properties from this object that should be logged to telemetry
 	 */
-	getTelemetryProperties(): ITelemetryProperties;
+	getTelemetryProperties(): ITelemetryBaseProperties;
 }
 
 /**
  * ITelemetryLogger interface contains various helper telemetry methods,
  * encoding in one place schemas for various types of Fluid telemetry events.
  * Creates sub-logger that appends properties to all events
+ *
+ * @deprecated For internal use within FluidFramework, use ITelemetryLoggerExt in \@fluidframework/telemetry-utils.
+ * No replacement intended for FluidFramework consumers.
  */
 export interface ITelemetryLogger extends ITelemetryBaseLogger {
 	/**
 	 * Actual implementation that sends telemetry event
 	 * Implemented by derived classes
 	 * @param event - Telemetry event to send over
+	 * @param logLevel - optional level of the log.
 	 */
-	send(event: ITelemetryBaseEvent): void;
+	send(event: ITelemetryBaseEvent, logLevel?: LogLevel): void;
 
 	/**
 	 * Send information telemetry event
 	 * @param event - Event to send
 	 * @param error - optional error object to log
+	 * @param logLevel - optional level of the log.
 	 */
-	// eslint-disable-next-line @typescript-eslint/no-explicit-any
-	sendTelemetryEvent(event: ITelemetryGenericEvent, error?: any): void;
+	sendTelemetryEvent(
+		event: ITelemetryGenericEvent,
+		// TODO: Use `unknown` instead (API-Breaking)
+		// eslint-disable-next-line @typescript-eslint/no-explicit-any
+		error?: any,
+		logLevel?: typeof LogLevel.verbose | typeof LogLevel.default,
+	): void;
 
 	/**
 	 * Send error telemetry event
 	 * @param event - Event to send
+	 * @param error - optional error object to log
 	 */
 	// eslint-disable-next-line @typescript-eslint/no-explicit-any
 	sendErrorEvent(event: ITelemetryErrorEvent, error?: any): void;
@@ -119,7 +183,14 @@ export interface ITelemetryLogger extends ITelemetryBaseLogger {
 	/**
 	 * Send performance telemetry event
 	 * @param event - Event to send
+	 * @param error - optional error object to log
+	 * @param logLevel - optional level of the log.
 	 */
-	// eslint-disable-next-line @typescript-eslint/no-explicit-any
-	sendPerformanceEvent(event: ITelemetryPerformanceEvent, error?: any): void;
+	sendPerformanceEvent(
+		event: ITelemetryPerformanceEvent,
+		// TODO: Use `unknown` instead (API-Breaking)
+		// eslint-disable-next-line @typescript-eslint/no-explicit-any
+		error?: any,
+		logLevel?: typeof LogLevel.verbose | typeof LogLevel.default,
+	): void;
 }

package/src/provider.ts

@@ -4,13 +4,18 @@
  */
 
 /**
- * This utility type is meant for internal use by {@link FluidObject}
  * Produces a valid FluidObject key given a type and a property.
+ *
+ * @remarks
+ *
  * A valid FluidObject key is a property that exists on the incoming type
  * as well as on the type of the property itself. For example: `IProvideFoo.IFoo.IFoo`
  * This aligns with the FluidObject pattern expected to be used with all FluidObjects.
  *
+ * This utility type is meant for internal use by {@link FluidObject}
+ *
  * @example
+ *
  * ```typescript
  * interface IProvideFoo{
  *  IFoo: IFoo
@@ -19,10 +24,9 @@
  *  foobar();
  * }
  * ```
- * This pattern enables discovery, and delegation in a standard way which is central
- * to FluidObject pattern
  *
- * @internal
+ * This pattern enables discovery, and delegation in a standard way which is central
+ * to FluidObject pattern.
  */
 export type FluidObjectProviderKeys<T, TProp extends keyof T = keyof T> = string extends TProp
 	? never
@@ -43,7 +47,9 @@ export type FluidObjectProviderKeys<T, TProp extends keyof T = keyof T> = string
  * FluidObject without a generic argument.
  *
  * @example
- * For example, if we have an interface like below
+ *
+ * For example, if we have an interface like the following:
+ *
  * ```typescript
  * interface IProvideFoo{
  *  IFoo: IFoo