/**
 * @license
 * Copyright 2022-2026 Matter.js Authors
 * SPDX-License-Identifier: Apache-2.0
 */
import { Duration } from "#time/Duration.js";
import { Timestamp } from "#time/Timestamp.js";
import type { Lifecycle } from "../util/Lifecycle.js";
import { DiagnosticPresentation } from "./DiagnosticPresentation.js";
import { LogLevel } from "./LogLevel.js";
/**
 * Logged values may implement this interface to customize presentation.
 *
 * You can use the utility functions such as {@link Diagnostic.dict} to create
 * Diagnostics from common value types.
 */
export type Diagnostic = {};
/**
 * Create a diagnostic giving a value a specific presentation.
 */
export declare function Diagnostic(presentation: Diagnostic.Presentation | Lifecycle.Status, value: unknown): Diagnostic;
/**
 * An extension of {@link Error} with additional diagnostic fields.
 */
export interface DiagnosticError extends Error {
    /**
     * The string used to tag formatted messages.
     */
    id?: string;
    /**
     * The origin of the error.
     */
    path?: Diagnostic;
}
export declare namespace Diagnostic {
    type Presentation = `${DiagnosticPresentation}`;
    const Presentation: typeof DiagnosticPresentation;
    const presentation: symbol;
    const value: symbol;
    function presentationOf(diagnostic: unknown): unknown;
    function valueOf(diagnostic: unknown): unknown;
    interface Context {
        run<T>(fn: () => T): T;
    }
    /**
     * Diagnostic context provides contextual information that affects formatting.
     */
    function Context(): Context;
    interface Message {
        now: Date;
        level: LogLevel;
        facility: string;
        prefix: string;
        values: unknown[];
    }
    /**
     * Create an object representing a log message.
     */
    function message(value: Partial<Message>): Message;
    /**
     * Create a value presented emphatically.
     */
    function strong(value: unknown): Diagnostic;
    /**
     * Create a value presented less emphatically than the default.
     */
    function weak(value: unknown): Diagnostic;
    /**
     * Create a value presented as key
     */
    function flag(value: string): Diagnostic;
    /**
     * Create a value identifying the source of a diagnostic event.
     *
     * Conventions for via:
     *
     *   - Use padded hex for random(ish) fixed-width numbers
     *
     *   - If there is an ID associated with a name, associate using "name#id"
     *
     *   - If there are subcomponents, associate with ":" (e.g. "sessionId:exchangeId:messageId")
     *
     *   - Use "/" as a separator if there are distinct subcomponents commonly delineated with ":"
     */
    function via(value: string): string;
    /**
     * Create a value identifying a resource that was added.
     */
    function added(value: unknown): Diagnostic;
    /**
     * Create a value identifying a resource that was removed.
     */
    function deleted(value: unknown): Diagnostic;
    /**
     * A node in a diagnostic tree.  Top-level diagnostic sources registered with DiagnosticSource should present as
     * nodes.
     */
    function node(icon: string, label: unknown, detail: {
        self?: unknown;
        children?: Iterable<unknown>;
    }): unknown[];
    /**
     * Create a value presenting as a list of separate lines.
     */
    function list(value: Iterable<unknown>): Diagnostic;
    /**
     * Create a value presenting as segments of the same string without intervening spaces.
     */
    function squash(...values: unknown[]): Diagnostic;
    /**
     * Create a K/V map that presents with formatted keys.
     */
    function dict(entries: object, suppressUndefinedValues?: boolean): Record<string, unknown> & Diagnostic;
    /**
     * Create a Diagnostic for an error.
     */
    function error(error: unknown): unknown;
    interface ErrorMessageDetails {
        id?: string;
        message: string;
        path?: unknown;
        cause?: unknown;
    }
    /**
     * Create a diagnostic for error messages that may have a code.
     *
     * Useful for errors when we don't want to present the stack trace.
     *
     * Includes singular causes but not components of aggregate errors.
     */
    function errorMessage(details: ErrorMessageDetails): unknown;
    /**
     * Create a diagnostic with a specific {@link Lifecycle}.
     */
    function lifecycle(status: Lifecycle.Status, value: unknown): Diagnostic;
    /**
     * Create a diagnostic for a {@link Lifecycle.Map}.
     */
    function lifecycleList(map: Lifecycle.Map<any>): Diagnostic[];
    interface Elapsed {
        readonly startedAt: Timestamp;
        readonly time: Duration;
        toString(): string;
    }
    /**
     * Create a diagnostic that renders as elapsed time since creation.
     */
    function elapsed(): Elapsed;
    /**
     * Upgrade a value to support specialized diagnostic rendering.
     */
    function upgrade<T>(value: boolean | number | string | object, diagnostic: unknown): T;
    /**
     * Convert a number or bigint to a hex string which is prefixed by "0x" for logging purposes
     * @param value The number or bigint to convert
     * @param padding Optional padding width (pads with leading zeros). When padding is specified, the "0x" prefix is omitted for cleaner aligned output.
     */
    function hex(value: number | bigint, padding?: number): string;
    /**
     * Convert a value to unstyled JSON.
     *
     * Specializes support for bigints and byte arrays.
     */
    function json(data: any): string;
    /**
     * Convert an object with keys to a flag list listing the truthy keys in a keylike/flag presentation.
     */
    function asFlags(flags: Record<string, unknown>): Diagnostic;
    /**
     * Convert an object with keys to a space-separated list of truthy keys.
     */
    function toFlagString(flags: Record<string, unknown>): string;
    /**
     * Extract message and stack diagnostic details.
     */
    function messageAndStackFor(error: unknown, parentStack?: string[]): {
        message: string;
        id?: string;
        path?: unknown;
        stack?: unknown[];
        stackLines?: string[];
    };
}
//# sourceMappingURL=Diagnostic.d.ts.map