/*!
 * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
 * Licensed under the MIT License.
 */
import type { ITelemetryBaseProperties, Tagged } from "@fluidframework/core-interfaces";
import type { ILoggingError } from "@fluidframework/core-interfaces/internal";
import { type IFluidErrorBase } from "./fluidErrorBase.js";
import type { TelemetryLoggerExt, ITelemetryPropertiesExt, TelemetryEventPropertyTypeExt } from "./telemetryTypes.js";
/**
 * Inspect the given error for common "safe" props and return them.
 *
 * @internal
 */
export declare function extractLogSafeErrorProperties(error: unknown, sanitizeStack: boolean): {
    message: string;
    errorType?: string | undefined;
    stack?: string | undefined;
};
/**
 * Type-guard for {@link @fluidframework/core-interfaces#ILoggingError}.
 *
 * @internal
 */
export declare const isILoggingError: (x: unknown) => x is ILoggingError;
/**
 * Metadata to annotate an error object when annotating or normalizing it
 *
 * @internal
 */
export interface IFluidErrorAnnotations {
    /**
     * Telemetry props to log with the error
     */
    props?: ITelemetryBaseProperties;
}
/**
 * Normalize the given error yielding a valid Fluid Error
 * @returns A valid Fluid Error with any provided annotations applied
 * @param error - The error to normalize
 * @param annotations - Annotations to apply to the normalized error
 *
 * @internal
 */
export declare function normalizeError(error: unknown, annotations?: IFluidErrorAnnotations): IFluidErrorBase;
/**
 * The purpose of this function is to provide ability to capture stack context quickly.
 * Accessing new Error().stack is slow, and the slowest part is accessing stack property itself.
 * There are scenarios where we generate error with stack, but error is handled in most cases and
 * stack property is not accessed.
 * For such cases it's better to not read stack property right away, but rather delay it until / if it's needed
 * Some browsers will populate stack right away, others require throwing Error, so we do auto-detection on the fly.
 * @param stackTraceLimit - stack trace limit for an error
 * @returns Error object that has stack populated.
 *
 * @internal
 */
export declare function generateErrorWithStack(stackTraceLimit?: number): Error;
/**
 * Generate a stack at this callsite as if an error were thrown from here.
 * @param stackTraceLimit - stack trace limit for an error
 * @returns the callstack (does not throw)
 *
 * @internal
 */
export declare function generateStack(stackTraceLimit?: number): string | undefined;
/**
 * Create a new error using newErrorFn, wrapping and caused by the given unknown error.
 * Copies the inner error's stack, errorInstanceId and telemetry props over to the new error if present
 * @param innerError - An error from untrusted/unknown origins
 * @param newErrorFn - callback that will create a new error given the original error's message
 * @returns A new error object "wrapping" the given error
 *
 * @internal
 */
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.
 *
 * @typeParam T - The kind of wrapper error to create.
 *
 * @internal
 */
export declare function wrapErrorAndLog<T extends LoggingError>(innerError: unknown, newErrorFn: (message: string) => T, logger: TelemetryLoggerExt): 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
 *
 * @internal
 */
export declare function isExternalError(error: unknown): boolean;
/**
 * Type guard to identify if a particular telemetry property appears to be a
 * {@link @fluidframework/core-interfaces#Tagged} telemetry property.
 *
 * @internal
 */
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}
 * Avoids runtime errors with circular references.
 * 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)
 *
 * @internal
 */
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),
 * will be logged in accordance with their tag, if present.
 *
 * PLEASE take care to avoid setting sensitive data on this object without proper tagging!
 *
 * @internal
 */
export declare class LoggingError extends Error implements ILoggingError, Omit<IFluidErrorBase, "errorType"> {
    private readonly omitPropsFromLogging;
    cause?: unknown;
    private _errorInstanceId;
    get errorInstanceId(): string;
    overwriteErrorInstanceId(id: string): void;
    /**
     * Create a new LoggingError
     * @param message - Error message to use for Error base class
     * @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?: 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.
     */
    static typeCheck(object: unknown): object is LoggingError;
    /**
     * Add additional properties to be logged
     */
    addTelemetryProperties(props: ITelemetryPropertiesExt): void;
    /**
     * Get all properties fit to be logged to telemetry for this error
     */
    getTelemetryProperties(): ITelemetryBaseProperties;
}
/**
 * The Error class used when normalizing an external error
 *
 * @internal
 */
export declare const NORMALIZED_ERROR_TYPE = "genericError";
//# sourceMappingURL=errorLogging.d.ts.map