@fluidframework/telemetry-utils 2.0.0-dev.5.2.0.169897 → 2.0.0-dev.6.4.0.191258

package/lib/error.js

@@ -0,0 +1,125 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import { FluidErrorTypes, } from "@fluidframework/core-interfaces";
+import { LoggingError, NORMALIZED_ERROR_TYPE, isExternalError, normalizeError, wrapError, } from "./errorLogging";
+/**
+ * Generic wrapper for an unrecognized/uncategorized error object
+ */
+export class GenericError extends LoggingError {
+    /**
+     * Create a new GenericError
+     * @param message - Error message
+     * @param error - inner error object
+     * @param props - Telemetry props to include when the error is logged
+     */
+    // TODO: Use `unknown` instead (API breaking change because error is not just an input parameter, but a public member of the class)
+    // eslint-disable-next-line @typescript-eslint/explicit-module-boundary-types, @typescript-eslint/no-explicit-any
+    constructor(message, error, props) {
+        // Don't try to log the inner error
+        super(message, props, new Set(["error"]));
+        this.error = error;
+        this.errorType = FluidErrorTypes.genericError;
+    }
+}
+/**
+ * Error indicating an API is being used improperly resulting in an invalid operation.
+ */
+export class UsageError extends LoggingError {
+    constructor(message, props) {
+        super(message, { ...props, usageError: true });
+        this.errorType = FluidErrorTypes.usageError;
+    }
+}
+/**
+ * DataCorruptionError indicates that we encountered definitive evidence that the data at rest
+ * backing this container is corrupted, and this container would never be expected to load properly again
+ */
+export class DataCorruptionError extends LoggingError {
+    constructor(message, props) {
+        super(message, { ...props, dataProcessingError: 1 });
+        this.errorType = FluidErrorTypes.dataCorruptionError;
+        this.canRetry = false;
+    }
+}
+/**
+ * Indicates we hit a fatal error while processing incoming data from the Fluid Service.
+ *
+ * @remarks
+ *
+ * The error will often originate in the dataStore or DDS implementation that is responding to incoming changes.
+ * This differs from {@link DataCorruptionError} in that this may be a transient error that will not repro in another
+ * client or session.
+ */
+export class DataProcessingError extends LoggingError {
+    constructor(errorMessage, props) {
+        super(errorMessage, props);
+        /**
+         * {@inheritDoc IFluidErrorBase.errorType}
+         */
+        this.errorType = FluidErrorTypes.dataProcessingError;
+        this.canRetry = false;
+    }
+    /**
+     * Create a new `DataProcessingError` detected and raised within the Fluid Framework.
+     */
+    static create(errorMessage, dataProcessingCodepath, sequencedMessage, props = {}) {
+        const dataProcessingError = DataProcessingError.wrapIfUnrecognized(errorMessage, dataProcessingCodepath, sequencedMessage);
+        dataProcessingError.addTelemetryProperties(props);
+        return dataProcessingError;
+    }
+    /**
+     * Wrap the given error in a `DataProcessingError`, unless the error is already of a known type
+     * with the exception of a normalized {@link LoggingError}, which will still be wrapped.
+     *
+     * In either case, the error will have some relevant properties added for telemetry.
+     *
+     * @remarks
+     *
+     * We wrap conditionally since known error types represent well-understood failure modes, and ideally
+     * one day we will move away from throwing these errors but rather we'll return them.
+     * But an unrecognized error needs to be classified as `DataProcessingError`.
+     *
+     * @param originalError - The error to be converted.
+     * @param dataProcessingCodepath - Which code-path failed while processing data.
+     * @param messageLike - Message to include info about via telemetry props.
+     *
+     * @returns Either a new `DataProcessingError`, or (if wrapping is deemed unnecessary) the given error.
+     */
+    static wrapIfUnrecognized(originalError, dataProcessingCodepath, messageLike) {
+        const props = {
+            dataProcessingError: 1,
+            dataProcessingCodepath,
+            ...(messageLike === undefined
+                ? undefined
+                : extractSafePropertiesFromMessage(messageLike)),
+        };
+        const normalizedError = normalizeError(originalError, { props });
+        // Note that other errors may have the NORMALIZED_ERROR_TYPE errorType,
+        // but if so they are still suitable to be wrapped as DataProcessingError.
+        if (isExternalError(normalizedError) ||
+            normalizedError.errorType === NORMALIZED_ERROR_TYPE) {
+            // Create a new DataProcessingError to wrap this external error
+            const dataProcessingError = wrapError(normalizedError, (message) => new DataProcessingError(message));
+            // Copy over the props above and any others added to this error since first being normalized
+            dataProcessingError.addTelemetryProperties(normalizedError.getTelemetryProperties());
+            return dataProcessingError;
+        }
+        return normalizedError;
+    }
+}
+/**
+ * Extracts specific properties from the provided message that we know are safe to log.
+ *
+ * @param messageLike - Message to include info about via telemetry props.
+ */
+export const extractSafePropertiesFromMessage = (messageLike) => ({
+    messageClientId: messageLike.clientId === null ? "null" : messageLike.clientId,
+    messageSequenceNumber: messageLike.sequenceNumber,
+    messageClientSequenceNumber: messageLike.clientSequenceNumber,
+    messageReferenceSequenceNumber: messageLike.referenceSequenceNumber,
+    messageMinimumSequenceNumber: messageLike.minimumSequenceNumber,
+    messageTimestamp: messageLike.timestamp,
+});
+//# sourceMappingURL=error.js.map

package/lib/error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"error.js","sourceRoot":"","sources":["../src/error.ts"],"names":[],"mappings":"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","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport {\n\tFluidErrorTypes,\n\tIGenericError,\n\tIErrorBase,\n\tITelemetryBaseProperties,\n\tIUsageError,\n} from \"@fluidframework/core-interfaces\";\nimport { ISequencedDocumentMessage } from \"@fluidframework/protocol-definitions\";\n\nimport {\n\tLoggingError,\n\tNORMALIZED_ERROR_TYPE,\n\tisExternalError,\n\tnormalizeError,\n\twrapError,\n} from \"./errorLogging\";\nimport { IFluidErrorBase } from \"./fluidErrorBase\";\n\n/**\n * Generic wrapper for an unrecognized/uncategorized error object\n */\nexport class GenericError extends LoggingError implements IGenericError, IFluidErrorBase {\n\treadonly errorType = FluidErrorTypes.genericError;\n\n\t/**\n\t * Create a new GenericError\n\t * @param message - Error message\n\t * @param error - inner error object\n\t * @param props - Telemetry props to include when the error is logged\n\t */\n\t// TODO: Use `unknown` instead (API breaking change because error is not just an input parameter, but a public member of the class)\n\t// eslint-disable-next-line @typescript-eslint/explicit-module-boundary-types, @typescript-eslint/no-explicit-any\n\tconstructor(message: string, public readonly error?: any, props?: ITelemetryBaseProperties) {\n\t\t// Don't try to log the inner error\n\t\tsuper(message, props, new Set([\"error\"]));\n\t}\n}\n\n/**\n * Error indicating an API is being used improperly resulting in an invalid operation.\n */\nexport class UsageError extends LoggingError implements IUsageError, IFluidErrorBase {\n\treadonly errorType = FluidErrorTypes.usageError;\n\n\tconstructor(message: string, props?: ITelemetryBaseProperties) {\n\t\tsuper(message, { ...props, usageError: true });\n\t}\n}\n\n/**\n * DataCorruptionError indicates that we encountered definitive evidence that the data at rest\n * backing this container is corrupted, and this container would never be expected to load properly again\n */\nexport class DataCorruptionError extends LoggingError implements IErrorBase, IFluidErrorBase {\n\treadonly errorType = FluidErrorTypes.dataCorruptionError;\n\treadonly canRetry = false;\n\n\tconstructor(message: string, props: ITelemetryBaseProperties) {\n\t\tsuper(message, { ...props, dataProcessingError: 1 });\n\t}\n}\n\n/**\n * Indicates we hit a fatal error while processing incoming data from the Fluid Service.\n *\n * @remarks\n *\n * The error will often originate in the dataStore or DDS implementation that is responding to incoming changes.\n * This differs from {@link DataCorruptionError} in that this may be a transient error that will not repro in another\n * client or session.\n */\nexport class DataProcessingError extends LoggingError implements IErrorBase, IFluidErrorBase {\n\t/**\n\t * {@inheritDoc IFluidErrorBase.errorType}\n\t */\n\tpublic readonly errorType = FluidErrorTypes.dataProcessingError;\n\n\tpublic readonly canRetry = false;\n\n\tprivate constructor(errorMessage: string, props?: ITelemetryBaseProperties) {\n\t\tsuper(errorMessage, props);\n\t}\n\n\t/**\n\t * Create a new `DataProcessingError` detected and raised within the Fluid Framework.\n\t */\n\tpublic static create(\n\t\terrorMessage: string,\n\t\tdataProcessingCodepath: string,\n\t\tsequencedMessage?: ISequencedDocumentMessage,\n\t\tprops: ITelemetryBaseProperties = {},\n\t): IFluidErrorBase {\n\t\tconst dataProcessingError = DataProcessingError.wrapIfUnrecognized(\n\t\t\terrorMessage,\n\t\t\tdataProcessingCodepath,\n\t\t\tsequencedMessage,\n\t\t);\n\t\tdataProcessingError.addTelemetryProperties(props);\n\n\t\treturn dataProcessingError;\n\t}\n\n\t/**\n\t * Wrap the given error in a `DataProcessingError`, unless the error is already of a known type\n\t * with the exception of a normalized {@link LoggingError}, which will still be wrapped.\n\t *\n\t * In either case, the error will have some relevant properties added for telemetry.\n\t *\n\t * @remarks\n\t *\n\t * We wrap conditionally since known error types represent well-understood failure modes, and ideally\n\t * one day we will move away from throwing these errors but rather we'll return them.\n\t * But an unrecognized error needs to be classified as `DataProcessingError`.\n\t *\n\t * @param originalError - The error to be converted.\n\t * @param dataProcessingCodepath - Which code-path failed while processing data.\n\t * @param messageLike - Message to include info about via telemetry props.\n\t *\n\t * @returns Either a new `DataProcessingError`, or (if wrapping is deemed unnecessary) the given error.\n\t */\n\tpublic static wrapIfUnrecognized(\n\t\toriginalError: unknown,\n\t\tdataProcessingCodepath: string,\n\t\tmessageLike?: Partial<\n\t\t\tPick<\n\t\t\t\tISequencedDocumentMessage,\n\t\t\t\t| \"clientId\"\n\t\t\t\t| \"sequenceNumber\"\n\t\t\t\t| \"clientSequenceNumber\"\n\t\t\t\t| \"referenceSequenceNumber\"\n\t\t\t\t| \"minimumSequenceNumber\"\n\t\t\t\t| \"timestamp\"\n\t\t\t>\n\t\t>,\n\t): IFluidErrorBase {\n\t\tconst props = {\n\t\t\tdataProcessingError: 1,\n\t\t\tdataProcessingCodepath,\n\t\t\t...(messageLike === undefined\n\t\t\t\t? undefined\n\t\t\t\t: extractSafePropertiesFromMessage(messageLike)),\n\t\t};\n\n\t\tconst normalizedError = normalizeError(originalError, { props });\n\t\t// Note that other errors may have the NORMALIZED_ERROR_TYPE errorType,\n\t\t// but if so they are still suitable to be wrapped as DataProcessingError.\n\t\tif (\n\t\t\tisExternalError(normalizedError) ||\n\t\t\tnormalizedError.errorType === NORMALIZED_ERROR_TYPE\n\t\t) {\n\t\t\t// Create a new DataProcessingError to wrap this external error\n\t\t\tconst dataProcessingError = wrapError(\n\t\t\t\tnormalizedError,\n\t\t\t\t(message: string) => new DataProcessingError(message),\n\t\t\t);\n\n\t\t\t// Copy over the props above and any others added to this error since first being normalized\n\t\t\tdataProcessingError.addTelemetryProperties(normalizedError.getTelemetryProperties());\n\n\t\t\treturn dataProcessingError;\n\t\t}\n\t\treturn normalizedError;\n\t}\n}\n\n/**\n * Extracts specific properties from the provided message that we know are safe to log.\n *\n * @param messageLike - Message to include info about via telemetry props.\n */\nexport const extractSafePropertiesFromMessage = (\n\tmessageLike: Partial<\n\t\tPick<\n\t\t\tISequencedDocumentMessage,\n\t\t\t| \"clientId\"\n\t\t\t| \"sequenceNumber\"\n\t\t\t| \"clientSequenceNumber\"\n\t\t\t| \"referenceSequenceNumber\"\n\t\t\t| \"minimumSequenceNumber\"\n\t\t\t| \"timestamp\"\n\t\t>\n\t>,\n): {\n\tmessageClientId: string | undefined;\n\tmessageSequenceNumber: number | undefined;\n\tmessageClientSequenceNumber: number | undefined;\n\tmessageReferenceSequenceNumber: number | undefined;\n\tmessageMinimumSequenceNumber: number | undefined;\n\tmessageTimestamp: number | undefined;\n} => ({\n\tmessageClientId: messageLike.clientId === null ? \"null\" : messageLike.clientId,\n\tmessageSequenceNumber: messageLike.sequenceNumber,\n\tmessageClientSequenceNumber: messageLike.clientSequenceNumber,\n\tmessageReferenceSequenceNumber: messageLike.referenceSequenceNumber,\n\tmessageMinimumSequenceNumber: messageLike.minimumSequenceNumber,\n\tmessageTimestamp: messageLike.timestamp,\n});\n"]}

package/lib/errorLogging.d.ts

@@ -2,21 +2,29 @@
  * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
  * Licensed under the MIT License.
  */
-import { ILoggingError, ITaggedTelemetryPropertyType, ITelemetryProperties } from "@fluidframework/common-definitions";
+import { ILoggingError, ITelemetryBaseProperties, Tagged } from "@fluidframework/core-interfaces";
 import { IFluidErrorBase } from "./fluidErrorBase";
-import { ITaggedTelemetryPropertyTypeExt, ITelemetryLoggerExt, TelemetryEventPropertyTypeExt } from "./telemetryTypes";
-/** Inspect the given error for common "safe" props and return them */
-export declare function extractLogSafeErrorProperties(error: any, sanitizeStack: boolean): {
+import { ITelemetryLoggerExt, TelemetryEventPropertyTypeExt } from "./telemetryTypes";
+/**
+ * Inspect the given error for common "safe" props and return them.
+ */
+export declare function extractLogSafeErrorProperties(error: unknown, sanitizeStack: boolean): {
     message: string;
     errorType?: string | undefined;
     stack?: string | undefined;
 };
-/** type guard for ILoggingError interface */
-export declare const isILoggingError: (x: any) => x is ILoggingError;
-/** Metadata to annotate an error object when annotating or normalizing it */
+/**
+ * type guard for ILoggingError interface
+ */
+export declare const isILoggingError: (x: unknown) => x is ILoggingError;
+/**
+ * Metadata to annotate an error object when annotating or normalizing it
+ */
 export interface IFluidErrorAnnotations {
-    /** Telemetry props to log with the error */
-    props?: ITelemetryProperties;
+    /**
+     * Telemetry props to log with the error
+     */
+    props?: ITelemetryBaseProperties;
 }
 /**
  * Normalize the given error yielding a valid Fluid Error
@@ -44,18 +52,31 @@ export declare function generateStack(): string | undefined;
  * @returns A new error object "wrapping" the given error
  */
 export declare function wrapError<T extends LoggingError>(innerError: unknown, newErrorFn: (message: string) => T): T;
-/** The same as wrapError, but also logs the innerError, including the wrapping error's instance id */
+/**
+ * The same as wrapError, but also logs the innerError, including the wrapping error's instance ID.
+ *
+ * @typeParam T - The kind of wrapper error to create.
+ */
 export declare function wrapErrorAndLog<T extends LoggingError>(innerError: unknown, newErrorFn: (message: string) => T, logger: ITelemetryLoggerExt): T;
+/**
+ * Attempts to overwrite the error's stack
+ *
+ * There have been reports of certain JS environments where overwriting stack will throw.
+ * If that happens, this adds the given stack as the telemetry property "stack2"
+ *
+ * @internal
+ */
+export declare function overwriteStack(error: IFluidErrorBase | LoggingError, stack: string): void;
 /**
  * True for any error object that is an (optionally normalized) external error
  * False for any error we created and raised within the FF codebase via LoggingError base class,
  * or wrapped in a well-known error type
  */
-export declare function isExternalError(e: any): boolean;
+export declare function isExternalError(error: unknown): boolean;
 /**
  * Type guard to identify if a particular telemetry property appears to be a tagged telemetry property
  */
-export declare function isTaggedTelemetryPropertyValue(x: ITaggedTelemetryPropertyTypeExt | TelemetryEventPropertyTypeExt): x is ITaggedTelemetryPropertyType | ITaggedTelemetryPropertyTypeExt;
+export declare function isTaggedTelemetryPropertyValue(x: Tagged<TelemetryEventPropertyTypeExt> | TelemetryEventPropertyTypeExt): x is Tagged<TelemetryEventPropertyTypeExt>;
 /**
  * Borrowed from
  * {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Errors/Cyclic_object_value#examples}
@@ -63,7 +84,7 @@ export declare function isTaggedTelemetryPropertyValue(x: ITaggedTelemetryProper
  * Not ideal, as will cut values that are not necessarily circular references.
  * Could be improved by implementing Node's util.inspect() for browser (minus all the coloring code)
  */
-export declare const getCircularReplacer: () => (key: string, value: any) => any;
+export declare const getCircularReplacer: () => (key: string, value: unknown) => any;
 /**
  * Base class for "trusted" errors we create, whose properties can generally be logged to telemetry safely.
  * All properties set on the object, or passed in (via the constructor or addTelemetryProperties),
@@ -76,7 +97,9 @@ export declare class LoggingError extends Error implements ILoggingError, Omit<I
     private _errorInstanceId;
     get errorInstanceId(): string;
     overwriteErrorInstanceId(id: string): void;
-    /** Back-compat to appease isFluidError typeguard in old code that may handle this error */
+    /**
+     * Backwards compatibility to appease {@link isFluidError} in old code that may handle this error.
+     */
     private readonly fluidErrorCode;
     /**
      * Create a new LoggingError
@@ -84,22 +107,24 @@ export declare class LoggingError extends Error implements ILoggingError, Omit<I
      * @param props - telemetry props to include on the error for when it's logged
      * @param omitPropsFromLogging - properties by name to omit from telemetry props
      */
-    constructor(message: string, props?: ITelemetryProperties, omitPropsFromLogging?: Set<string>);
+    constructor(message: string, props?: ITelemetryBaseProperties, omitPropsFromLogging?: Set<string>);
     /**
      * Determines if a given object is an instance of a LoggingError
      * @param object - any object
-     * @returns - true if the object is an instance of a LoggingError, false if not.
+     * @returns true if the object is an instance of a LoggingError, false if not.
      */
     static typeCheck(object: unknown): object is LoggingError;
     /**
      * Add additional properties to be logged
      */
-    addTelemetryProperties(props: ITelemetryProperties): void;
+    addTelemetryProperties(props: ITelemetryBaseProperties): void;
     /**
      * Get all properties fit to be logged to telemetry for this error
      */
-    getTelemetryProperties(): ITelemetryProperties;
+    getTelemetryProperties(): ITelemetryBaseProperties;
 }
-/** The Error class used when normalizing an external error */
+/**
+ * The Error class used when normalizing an external error
+ */
 export declare const NORMALIZED_ERROR_TYPE = "genericError";
 //# sourceMappingURL=errorLogging.d.ts.map

package/lib/errorLogging.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errorLogging.d.ts","sourceRoot":"","sources":["../src/errorLogging.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EACN,aAAa,EACb,4BAA4B,EAC5B,oBAAoB,EAEpB,MAAM,oCAAoC,CAAC;AAE5C,OAAO,EAEN,eAAe,EAGf,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACN,+BAA+B,EAC/B,mBAAmB,EACnB,6BAA6B,EAC7B,MAAM,kBAAkB,CAAC;AAO1B,sEAAsE;AACtE,wBAAgB,6BAA6B,CAAC,KAAK,EAAE,GAAG,EAAE,aAAa,EAAE,OAAO;aAenD,MAAM;;;EAkBlC;AAED,6CAA6C;AAC7C,eAAO,MAAM,eAAe,MAAO,GAAG,uBACU,CAAC;AAWjD,6EAA6E;AAC7E,MAAM,WAAW,sBAAsB;IACtC,4CAA4C;IAC5C,KAAK,CAAC,EAAE,oBAAoB,CAAC;CAC7B;AAYD;;;;;GAKG;AACH,wBAAgB,cAAc,CAC7B,KAAK,EAAE,OAAO,EACd,WAAW,GAAE,sBAA2B,GACtC,eAAe,CAqDjB;AAID;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,IAAI,KAAK,CAgB9C;AAED,wBAAgB,aAAa,IAAI,MAAM,GAAG,SAAS,CAElD;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,CAAC,SAAS,YAAY,EAC/C,UAAU,EAAE,OAAO,EACnB,UAAU,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,CAAC,GAChC,CAAC,CA6BH;AAED,sGAAsG;AACtG,wBAAgB,eAAe,CAAC,CAAC,SAAS,YAAY,EACrD,UAAU,EAAE,OAAO,EACnB,UAAU,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,CAAC,EAClC,MAAM,EAAE,mBAAmB,KAoB3B;AAWD;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,GAAG,GAAG,OAAO,CAW/C;AAED;;GAEG;AACH,wBAAgB,8BAA8B,CAC7C,CAAC,EAAE,+BAA+B,GAAG,6BAA6B,GAChE,CAAC,IAAI,4BAA4B,GAAG,+BAA+B,CAErE;AAwDD;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,cAElB,MAAM,SAAS,GAAG,KAAG,GASlC,CAAC;AAEF;;;;;;GAMG;AACH,qBAAa,YACZ,SAAQ,KACR,YAAW,aAAa,EAAE,IAAI,CAAC,eAAe,EAAE,WAAW,CAAC;IAuB3D,OAAO,CAAC,QAAQ,CAAC,oBAAoB;IArBtC,OAAO,CAAC,gBAAgB,CAAU;IAClC,IAAI,eAAe,WAElB;IACD,wBAAwB,CAAC,EAAE,EAAE,MAAM;IAInC,2FAA2F;IAE3F,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAY;IAE3C;;;;;OAKG;gBAEF,OAAO,EAAE,MAAM,EACf,KAAK,CAAC,EAAE,oBAAoB,EACX,oBAAoB,GAAE,GAAG,CAAC,MAAM,CAAa;IAa/D;;;;OAIG;WACW,SAAS,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,IAAI,YAAY;IAWhE;;OAEG;IACI,sBAAsB,CAAC,KAAK,EAAE,oBAAoB;IAIzD;;OAEG;IACI,sBAAsB,IAAI,oBAAoB;CAUrD;AAED,8DAA8D;AAC9D,eAAO,MAAM,qBAAqB,iBAAiB,CAAC"}
+{"version":3,"file":"errorLogging.d.ts","sourceRoot":"","sources":["../src/errorLogging.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EACN,aAAa,EACb,wBAAwB,EAExB,MAAM,EACN,MAAM,iCAAiC,CAAC;AAEzC,OAAO,EAEN,eAAe,EAGf,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,mBAAmB,EAAE,6BAA6B,EAAE,MAAM,kBAAkB,CAAC;AAStF;;GAEG;AACH,wBAAgB,6BAA6B,CAC5C,KAAK,EAAE,OAAO,EACd,aAAa,EAAE,OAAO,GACpB;IACF,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC3B,CAoCA;AAED;;GAEG;AACH,eAAO,MAAM,eAAe,MAAO,OAAO,uBACkC,CAAC;AAgB7E;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACtC;;OAEG;IACH,KAAK,CAAC,EAAE,wBAAwB,CAAC;CACjC;AAeD;;;;;GAKG;AACH,wBAAgB,cAAc,CAC7B,KAAK,EAAE,OAAO,EACd,WAAW,GAAE,sBAA2B,GACtC,eAAe,CAqDjB;AAID;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,IAAI,KAAK,CAgB9C;AAED,wBAAgB,aAAa,IAAI,MAAM,GAAG,SAAS,CAElD;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,CAAC,SAAS,YAAY,EAC/C,UAAU,EAAE,OAAO,EACnB,UAAU,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,CAAC,GAChC,CAAC,CA6BH;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,CAAC,SAAS,YAAY,EACrD,UAAU,EAAE,OAAO,EACnB,UAAU,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,CAAC,EAClC,MAAM,EAAE,mBAAmB,GACzB,CAAC,CAmBH;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,eAAe,GAAG,YAAY,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAMzF;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAWvD;AAED;;GAEG;AACH,wBAAgB,8BAA8B,CAC7C,CAAC,EAAE,MAAM,CAAC,6BAA6B,CAAC,GAAG,6BAA6B,GACtE,CAAC,IAAI,MAAM,CAAC,6BAA6B,CAAC,CAE5C;AA0DD;;;;;;GAMG;AAGH,eAAO,MAAM,mBAAmB,cAAc,MAAM,SAAS,OAAO,KAAK,GAWxE,CAAC;AAGF;;;;;;GAMG;AACH,qBAAa,YACZ,SAAQ,KACR,YAAW,aAAa,EAAE,IAAI,CAAC,eAAe,EAAE,WAAW,CAAC;IA0B3D,OAAO,CAAC,QAAQ,CAAC,oBAAoB;IAxBtC,OAAO,CAAC,gBAAgB,CAAU;IAClC,IAAI,eAAe,IAAI,MAAM,CAE5B;IACD,wBAAwB,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAI1C;;OAEG;IAGH,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAY;IAE3C;;;;;OAKG;gBAEF,OAAO,EAAE,MAAM,EACf,KAAK,CAAC,EAAE,wBAAwB,EACf,oBAAoB,GAAE,GAAG,CAAC,MAAM,CAAa;IAa/D;;;;OAIG;WACW,SAAS,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,IAAI,YAAY;IAWhE;;OAEG;IACI,sBAAsB,CAAC,KAAK,EAAE,wBAAwB,GAAG,IAAI;IAIpE;;OAEG;IACI,sBAAsB,IAAI,wBAAwB;CAUzD;AAED;;GAEG;AACH,eAAO,MAAM,qBAAqB,iBAAiB,CAAC"}

package/lib/errorLogging.js

@@ -4,11 +4,15 @@
  */
 import { v4 as uuid } from "uuid";
 import { hasErrorInstanceId, isFluidError, isValidLegacyError, } from "./fluidErrorBase";
-/** @returns true if value is an object but neither null nor an array */
+/**
+ * Determines if the provided value is an object but neither null nor an array.
+ */
 const isRegularObject = (value) => {
     return value !== null && !Array.isArray(value) && typeof value === "object";
 };
-/** Inspect the given error for common "safe" props and return them */
+/**
+ * Inspect the given error for common "safe" props and return them.
+ */
 export function extractLogSafeErrorProperties(error, sanitizeStack) {
     const removeMessageFromStack = (stack, errorName) => {
         if (!sanitizeStack) {
@@ -21,7 +25,9 @@ export function extractLogSafeErrorProperties(error, sanitizeStack) {
         }
         return stackFrames.join("\n");
     };
-    const message = typeof (error === null || error === void 0 ? void 0 : error.message) === "string" ? error.message : String(error);
+    const message = typeof error?.message === "string"
+        ? error.message
+        : String(error);
     const safeProps = {
         message,
     };
@@ -37,9 +43,13 @@ export function extractLogSafeErrorProperties(error, sanitizeStack) {
     }
     return safeProps;
 }
-/** type guard for ILoggingError interface */
-export const isILoggingError = (x) => typeof (x === null || x === void 0 ? void 0 : x.getTelemetryProperties) === "function";
-/** Copy props from source onto target, but do not overwrite an existing prop that matches */
+/**
+ * type guard for ILoggingError interface
+ */
+export const isILoggingError = (x) => typeof x?.getTelemetryProperties === "function";
+/**
+ * Copy props from source onto target, but do not overwrite an existing prop that matches
+ */
 function copyProps(target, source) {
     for (const key of Object.keys(source)) {
         if (target[key] === undefined) {
@@ -47,8 +57,11 @@ function copyProps(target, source) {
         }
     }
 }
-/** For backwards compatibility with pre-errorInstanceId valid errors */
+/**
+ * For backwards compatibility with pre-errorInstanceId valid errors
+ */
 function patchLegacyError(legacyError) {
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-explicit-any
     const patchMe = legacyError;
     if (patchMe.errorInstanceId === undefined) {
         patchMe.errorInstanceId = uuid();
@@ -61,14 +74,13 @@ function patchLegacyError(legacyError) {
  * @param annotations - Annotations to apply to the normalized error
  */
 export function normalizeError(error, annotations = {}) {
-    var _a;
     // Back-compat, while IFluidErrorBase is rolled out
     if (isValidLegacyError(error)) {
         patchLegacyError(error);
     }
     if (isFluidError(error)) {
         // We can simply add the telemetry props to the error and return it
-        error.addTelemetryProperties((_a = annotations.props) !== null && _a !== void 0 ? _a : {});
+        error.addTelemetryProperties(annotations.props ?? {});
         return error;
     }
     // We have to construct a new Fluid Error, copying safe properties over
@@ -84,11 +96,11 @@ export function normalizeError(error, annotations = {}) {
         const maybeHasRetry = error;
         let retryProps;
         if ("canRetry" in error) {
-            retryProps !== null && retryProps !== void 0 ? retryProps : (retryProps = {});
+            retryProps ?? (retryProps = {});
             retryProps.canRetry = maybeHasRetry.canRetry;
         }
         if ("retryAfterSeconds" in error) {
-            retryProps !== null && retryProps !== void 0 ? retryProps : (retryProps = {});
+            retryProps ?? (retryProps = {});
             retryProps.retryAfterSeconds = maybeHasRetry.retryAfterSeconds;
         }
         if (retryProps !== undefined) {
@@ -102,7 +114,10 @@ export function normalizeError(error, annotations = {}) {
     const errorTelemetryProps = LoggingError.typeCheck(error)
         ? error.getTelemetryProperties()
         : { untrustedOrigin: 1 }; // This will let us filter errors that did not originate from our own codebase
-    fluidError.addTelemetryProperties(Object.assign(Object.assign({}, errorTelemetryProps), annotations.props));
+    fluidError.addTelemetryProperties({
+        ...errorTelemetryProps,
+        ...annotations.props,
+    });
     return fluidError;
 }
 let stackPopulatedOnCreation;
@@ -126,8 +141,8 @@ export function generateErrorWithStack() {
     try {
         throw err;
     }
-    catch (e) {
-        return e;
+    catch (error) {
+        return error;
     }
 }
 export function generateStack() {
@@ -163,7 +178,11 @@ export function wrapError(innerError, newErrorFn) {
     }
     return newError;
 }
-/** The same as wrapError, but also logs the innerError, including the wrapping error's instance id */
+/**
+ * The same as wrapError, but also logs the innerError, including the wrapping error's instance ID.
+ *
+ * @typeParam T - The kind of wrapper error to create.
+ */
 export function wrapErrorAndLog(innerError, newErrorFn, logger) {
     const newError = wrapError(innerError, newErrorFn);
     // This will match innerError.errorInstanceId if present (see wrapError)
@@ -177,12 +196,19 @@ export function wrapErrorAndLog(innerError, newErrorFn, logger) {
     }, innerError);
     return newError;
 }
-function overwriteStack(error, stack) {
-    // supposedly setting stack on an Error can throw.
+/**
+ * Attempts to overwrite the error's stack
+ *
+ * There have been reports of certain JS environments where overwriting stack will throw.
+ * If that happens, this adds the given stack as the telemetry property "stack2"
+ *
+ * @internal
+ */
+export function overwriteStack(error, stack) {
     try {
         Object.assign(error, { stack });
     }
-    catch (errorSettingStack) {
+    catch {
         error.addTelemetryProperties({ stack2: stack });
     }
 }
@@ -191,29 +217,28 @@ function overwriteStack(error, stack) {
  * False for any error we created and raised within the FF codebase via LoggingError base class,
  * or wrapped in a well-known error type
  */
-export function isExternalError(e) {
+export function isExternalError(error) {
     // LoggingErrors are an internal FF error type. However, an external error can be converted
     // into a LoggingError if it is normalized. In this case we must use the untrustedOrigin flag to
     // determine whether the original error was infact external.
-    if (LoggingError.typeCheck(e)) {
-        if (e.errorType === NORMALIZED_ERROR_TYPE) {
-            return e.getTelemetryProperties().untrustedOrigin === 1;
+    if (LoggingError.typeCheck(error)) {
+        if (error.errorType === NORMALIZED_ERROR_TYPE) {
+            return error.getTelemetryProperties().untrustedOrigin === 1;
         }
         return false;
     }
-    return !isValidLegacyError(e);
+    return !isValidLegacyError(error);
 }
 /**
  * Type guard to identify if a particular telemetry property appears to be a tagged telemetry property
  */
 export function isTaggedTelemetryPropertyValue(x) {
-    var _a;
-    return typeof ((_a = x) === null || _a === void 0 ? void 0 : _a.tag) === "string";
+    return typeof x?.tag === "string";
 }
 /**
  * Filter serializable telemetry properties
- * @param x - any telemetry prop
- * @returns - as-is if x is primitive. returns stringified if x is an array of primitive.
+ * @param x - Any telemetry prop
+ * @returns As-is if x is primitive. returns stringified if x is an array of primitive.
  * otherwise returns null since this is what we support at the moment.
  */
 function filterValidTelemetryProps(x, key) {
@@ -269,6 +294,8 @@ function getValidTelemetryProps(obj, keysToOmit) {
  * Not ideal, as will cut values that are not necessarily circular references.
  * Could be improved by implementing Node's util.inspect() for browser (minus all the coloring code)
  */
+// TODO: Use `unknown` instead (API breaking change)
+/* eslint-disable @typescript-eslint/no-explicit-any */
 export const getCircularReplacer = () => {
     const seen = new WeakSet();
     return (key, value) => {
@@ -281,6 +308,7 @@ export const getCircularReplacer = () => {
         return value;
     };
 };
+/* eslint-enable @typescript-eslint/no-explicit-any */
 /**
  * Base class for "trusted" errors we create, whose properties can generally be logged to telemetry safely.
  * All properties set on the object, or passed in (via the constructor or addTelemetryProperties),
@@ -299,8 +327,11 @@ export class LoggingError extends Error {
         super(message);
         this.omitPropsFromLogging = omitPropsFromLogging;
         this._errorInstanceId = uuid();
-        /** Back-compat to appease isFluidError typeguard in old code that may handle this error */
+        /**
+         * Backwards compatibility to appease {@link isFluidError} in old code that may handle this error.
+         */
         // @ts-expect-error - This field shouldn't be referenced in the current version, but needs to exist at runtime.
+        // eslint-disable-next-line @typescript-eslint/prefer-as-const
         this.fluidErrorCode = "-";
         // Don't log this list itself, or the private _errorInstanceId
         omitPropsFromLogging.add("omitPropsFromLogging");
@@ -318,7 +349,7 @@ export class LoggingError extends Error {
     /**
      * Determines if a given object is an instance of a LoggingError
      * @param object - any object
-     * @returns - true if the object is an instance of a LoggingError, false if not.
+     * @returns true if the object is an instance of a LoggingError, false if not.
      */
     static typeCheck(object) {
         if (typeof object === "object" && object !== null) {
@@ -340,10 +371,17 @@ export class LoggingError extends Error {
     getTelemetryProperties() {
         const taggableProps = getValidTelemetryProps(this, this.omitPropsFromLogging);
         // Include non-enumerable props that are not returned by getValidTelemetryProps
-        return Object.assign(Object.assign({}, taggableProps), { stack: this.stack, message: this.message, errorInstanceId: this._errorInstanceId });
+        return {
+            ...taggableProps,
+            stack: this.stack,
+            message: this.message,
+            errorInstanceId: this._errorInstanceId,
+        };
     }
 }
-/** The Error class used when normalizing an external error */
+/**
+ * The Error class used when normalizing an external error
+ */
 export const NORMALIZED_ERROR_TYPE = "genericError";
 class NormalizedLoggingError extends LoggingError {
     constructor(errorProps) {