@itwin/core-bentley/lib/cjs/BentleyError.d.ts

Bentley JavaScript core components

/** @packageDocumentation
 * @module Errors
 */
/** Uniquely identifies a specific kind of [[ITwinError]].
 * @beta
 */
export interface ITwinErrorId {
    /** A "namespace" serving as a qualifier for the [[key]]. It should be specific enough to ensure uniqueness across all applications.
     * For example, all errors originating from a given package should use that package's full name as their scope.
     */
    readonly scope: string;
    /** Uniquely identifies a specific kind of [[ITwinError]] within the [[scope]]. */
    readonly key: string;
}
/** The interface that all exceptions thrown by iTwin.js libraries and applications should implement.
 * Specific kinds of `ITwinError`s are identified by an [[ITwinErrorId]] that allows programmers to identify errors when they are caught without relying
 * on specific class hierarchies, which is especially important when errors are marshalled across process boundaries.
 * You can extend `ITwinError` to add properties that provide programmers with additional context for a particular kind of error.
 * When catching errors, programmers can use [[isError]] to determine if the error is of a specific sub-type, and if so access the
 * additional properties.
 * Those additional properties will also be logged as metadata by [[Logger.logException]].
 * @beta
 */
export interface ITwinError extends Error {
    /** Uniquely identifies the kind of error. */
    readonly iTwinErrorId: ITwinErrorId;
}
/** @beta */
export declare namespace ITwinError {
    /** Instantiate a new `ITwinError` or subtype thereof.
     * @see [[ITwinError.throwError]] to conveniently instantiate and throw the error.
     */
    function create<T extends ITwinError>(args: Omit<T, "name">): T;
    /** Instantiate and immediately throw an `ITwinError`.
     * @see [[ITwinError.create]] to instantiate an error without throwing it.
     */
    function throwError<T extends ITwinError>(args: Omit<T, "name">): never;
    /**
     * Determine whether an error object was thrown by iTwin.js and has a specific scope and key.
     *
     * If the test succeeds, the type of `error` is coerced to `T`
     * @param error The error to ve verified.
     * @param scope value for `error.iTwinErrorId.scope`
     * @param key value for `error.iTwinErrorId.key`
    */
    function isError<T extends ITwinError>(error: unknown, scope: string, key?: string): error is T;
}
/** Standard status code.
 * This status code should be rarely used.
 * Prefer to throw an exception to indicate an error, rather than returning a special status code.
 * If a status code is to be returned, prefer to return a more specific error status type such as IModelStatus or DbResult.
 * @public
 */
export declare enum BentleyStatus {
    SUCCESS = 0,
    ERROR = 32768
}
/** Status codes that are used in conjunction with [[BentleyError]].
 * Error status codes are divided into separate ranges for different kinds of errors. All known ranges at least should be defined here, to avoid collisions.
 * @public
 */
export declare enum IModelStatus {
    IMODEL_ERROR_BASE = 65536,
    Success = 0,
    AlreadyLoaded = 65537,
    AlreadyOpen = 65538,
    BadArg = 65539,
    BadElement = 65540,
    BadModel = 65541,
    BadRequest = 65542,
    BadSchema = 65543,
    CannotUndo = 65544,
    CodeNotReserved = 65545,
    DeletionProhibited = 65546,
    DuplicateCode = 65547,
    DuplicateName = 65548,
    ElementBlockedChange = 65549,
    FileAlreadyExists = 65550,
    FileNotFound = 65551,
    FileNotLoaded = 65552,
    ForeignKeyConstraint = 65553,
    IdExists = 65554,
    InDynamicTransaction = 65555,
    InvalidCategory = 65556,
    InvalidCode = 65557,
    InvalidCodeSpec = 65558,
    InvalidId = 65559,
    InvalidName = 65560,
    InvalidParent = 65561,
    InvalidProfileVersion = 65562,
    IsCreatingChangeSet = 65563,
    LockNotHeld = 65564,
    Mismatch2d3d = 65565,
    MismatchGcs = 65566,
    MissingDomain = 65567,
    MissingHandler = 65568,
    MissingId = 65569,
    NoGeometry = 65570,
    NoMultiTxnOperation = 65571,
    NotEnabled = 65573,
    NotFound = 65574,
    NotOpen = 65575,
    NotOpenForWrite = 65576,
    NotSameUnitBase = 65577,
    NothingToRedo = 65578,
    NothingToUndo = 65579,
    ParentBlockedChange = 65580,
    ReadError = 65581,
    ReadOnly = 65582,
    ReadOnlyDomain = 65583,
    RepositoryManagerError = 65584,
    SQLiteError = 65585,
    TransactionActive = 65586,
    UnitsMissing = 65587,
    UnknownFormat = 65588,
    UpgradeFailed = 65589,
    ValidationFailed = 65590,
    VersionTooNew = 65591,
    VersionTooOld = 65592,
    ViewNotFound = 65593,
    WriteError = 65594,
    WrongClass = 65595,
    WrongIModel = 65596,
    WrongDomain = 65597,
    WrongElement = 65598,
    WrongHandler = 65599,
    WrongModel = 65600,
    ConstraintNotUnique = 65601,
    NoGeoLocation = 65602,
    ServerTimeout = 65603,
    NoContent = 65604,
    NotRegistered = 65605,
    FunctionNotFound = 65606,
    NoActiveCommand = 65607,
    Aborted = 65608
}
/** Error statuses produced by various briefcase operations, typically encountered as the `errorNumber` of an [IModelError]($common).
 * @public
 */
export declare enum BriefcaseStatus {
    BRIEFCASE_STATUS_BASE = 131072,
    CannotAcquire = 131072,
    CannotDownload = 131073,
    CannotUpload = 131074,
    CannotCopy = 131075,
    CannotDelete = 131076,
    VersionNotFound = 131077,
    CannotApplyChanges = 131078,
    DownloadCancelled = 131079,
    ContainsDeletedChangeSets = 131080
}
/** RpcInterface status codes
 * @beta
 */
export declare enum RpcInterfaceStatus {
    Success = 0,
    RPC_INTERFACE_ERROR_BASE = 135168,
    /** The RpcInterface implemented by the server is incompatible with the interface requested by the client. */
    IncompatibleVersion = 135168
}
/** Error statuses produced by various Changeset operations, typically encountered as the `errorNumber` of an [IModelError]($common).
 * @public
 */
export declare enum ChangeSetStatus {
    Success = 0,
    CHANGESET_ERROR_BASE = 90112,
    /** Error applying a change set when reversing or reinstating it */
    ApplyError = 90113,
    /** Change tracking has not been enabled. The ChangeSet API mandates this. */
    ChangeTrackingNotEnabled = 90114,
    /** Contents of the change stream are corrupted and does not match the ChangeSet */
    CorruptedChangeStream = 90115,
    /** File containing the changes to the change set is not found */
    FileNotFound = 90116,
    /** Error writing the contents of the change set to the backing change stream file */
    FileWriteError = 90117,
    /**  Cannot perform the operation since the Db has local changes */
    HasLocalChanges = 90118,
    /**  Cannot perform the operation since current transaction has uncommitted changes */
    HasUncommittedChanges = 90119,
    /**  Invalid ChangeSet Id */
    InvalidId = 90120,
    /**  Invalid version of the change set */
    InvalidVersion = 90121,
    /** Cannot perform the operation since system is in the middle of a dynamic transaction */
    InDynamicTransaction = 90122,
    /** Cannot perform operation since system is in the middle of a creating a change set */
    IsCreatingChangeSet = 90123,
    /** Cannot perform operation since the system is not creating a change set */
    IsNotCreatingChangeSet = 90124,
    /** Error propagating the changes after the merge */
    MergePropagationError = 90125,
    /** No change sets to merge */
    NothingToMerge = 90126,
    /** No transactions are available to create a change set */
    NoTransactions = 90127,
    /** Parent change set of the Db does not match the parent id of the change set */
    ParentMismatch = 90128,
    /** Error performing a SQLite operation on the Db */
    SQLiteError = 90129,
    /** ChangeSet originated in a different Db */
    WrongDgnDb = 90130,
    /** Could not open the DgnDb to merge change set */
    CouldNotOpenDgnDb = 90131,
    /** Cannot merge changes in in an open DgnDb. Close the DgnDb, and process the operation when it is opened. */
    MergeSchemaChangesOnOpen = 90132,
    /** Cannot reverse or reinstate schema changes. */
    ReverseOrReinstateSchemaChanges = 90133,
    /** Cannot process changes schema changes in an open DgnDb. Close the DgnDb, and process the operation when it is opened. */
    ProcessSchemaChangesOnOpen = 90134,
    /** Cannot merge changes into a Readonly DgnDb. */
    CannotMergeIntoReadonly = 90135,
    /**  Cannot merge changes into a Master DgnDb. */
    CannotMergeIntoMaster = 90136,
    /** Cannot merge changes into a DgnDb that has reversed change sets. */
    CannotMergeIntoReversed = 90137,
    /** ChangeSet(s) download was cancelled. */
    DownloadCancelled = 90138
}
/** Status from returned HTTP status code
 * @beta
 */
export declare enum HttpStatus {
    /** 2xx Success */
    Success = 0,
    /** 1xx Informational responses */
    Info = 94209,
    /** 3xx Redirection */
    Redirection = 94210,
    /** 4xx Client errors */
    ClientError = 94211,
    /** 5xx Server errors */
    ServerError = 94212
}
/** Statuses produced by APIs that interact with iModelHub, typically encountered as the `errorNumber` of an [IModelError]($common).
 * @public
 */
export declare enum IModelHubStatus {
    Success = 0,
    IMODELHUBERROR_BASE = 102400,
    IMODELHUBERROR_REQUESTERRORBASE = 102656,
    Unknown = 102401,
    MissingRequiredProperties = 102402,
    InvalidPropertiesValues = 102403,
    UserDoesNotHavePermission = 102404,
    UserDoesNotHaveAccess = 102405,
    InvalidBriefcase = 102406,
    BriefcaseDoesNotExist = 102407,
    BriefcaseDoesNotBelongToUser = 102408,
    AnotherUserPushing = 102409,
    ChangeSetAlreadyExists = 102410,
    ChangeSetDoesNotExist = 102411,
    FileIsNotUploaded = 102412,
    iModelIsNotInitialized = 102413,
    ChangeSetPointsToBadSeed = 102414,
    OperationFailed = 102415,
    PullIsRequired = 102416,
    MaximumNumberOfBriefcasesPerUser = 102417,
    MaximumNumberOfBriefcasesPerUserPerMinute = 102418,
    DatabaseTemporarilyLocked = 102419,
    iModelIsLocked = 102420,
    CodesExist = 102421,
    LocksExist = 102422,
    iModelAlreadyExists = 102423,
    iModelDoesNotExist = 102424,
    FileDoesNotExist = 102425,
    FileAlreadyExists = 102426,
    LockDoesNotExist = 102427,
    LockOwnedByAnotherBriefcase = 102428,
    CodeStateInvalid = 102429,
    CodeReservedByAnotherBriefcase = 102430,
    CodeDoesNotExist = 102431,
    EventTypeDoesNotExist = 102432,
    EventSubscriptionDoesNotExist = 102433,
    EventSubscriptionAlreadyExists = 102434,
    ITwinIdIsNotSpecified = 102435,
    FailedToGetITwinPermissions = 102436,
    FailedToGetITwinMembers = 102437,
    ChangeSetAlreadyHasVersion = 102438,
    VersionAlreadyExists = 102439,
    JobSchedulingFailed = 102440,
    ConflictsAggregate = 102441,
    FailedToGetITwinById = 102442,
    DatabaseOperationFailed = 102443,
    SeedFileInitializationFailed = 102444,
    FailedToGetAssetPermissions = 102445,
    FailedToGetAssetMembers = 102446,
    ITwinDoesNotExist = 102447,
    LockChunkDoesNotExist = 102449,
    CheckpointAlreadyExists = 102450,
    CheckpointDoesNotExist = 102451,
    UndefinedArgumentError = 102657,
    InvalidArgumentError = 102658,
    MissingDownloadUrlError = 102659,
    NotSupportedInBrowser = 102660,
    FileHandlerNotSet = 102661,
    FileNotFound = 102662,
    InitializationTimeout = 102663
}
/** GeoServiceStatus errors
 * @public
 */
export declare enum GeoServiceStatus {
    Success = 0,
    GEOSERVICESTATUS_BASE = 147456,
    NoGeoLocation = 65602,
    OutOfUsefulRange = 147457,
    OutOfMathematicalDomain = 147458,
    NoDatumConverter = 147459,
    VerticalDatumConvertError = 147460,
    CSMapError = 147461,
    /**
     * @deprecated in 5.0 - will not be removed until after 2026-06-13. This status is never returned.
     */
    Pending = 147462
}
/** Error status from various reality data operations
 * @alpha
 */
export declare enum RealityDataStatus {
    Success = 0,
    REALITYDATA_ERROR_BASE = 151552,
    InvalidData = 151553
}
/** A function that returns a metadata object for a [[BentleyError]].
 * This is generally used for logging. However not every exception is logged, so use this if the metadata for an exception is expensive to create.
 * @public
 */
export type GetMetaDataFunction = () => object | undefined;
/** Optional metadata attached to a [[BentleyError]]. May either be an object or a function that returns an object.
 * If this exception is logged and metadata is present, the metaData object is attached to the log entry via `JSON.stringify`
 * @public
 */
export type LoggingMetaData = GetMetaDataFunction | object | undefined;
interface ErrorProps {
    message: string;
    stack?: string;
    metadata?: object;
}
/**
 * An [[ITwinError]] that also supplies an `errorNumber`.
 * @note this interface exists *only* for legacy errors derived from `BentleyError`. The concept of "error number" is
 * problematic since it is impossible to enforce across the iTwin.js library, let alone across applications. New code should
 * use `ITwinError` and identify errors with strings instead.
 * @beta */
export interface LegacyITwinErrorWithNumber extends ITwinError {
    /** a number to identify the error. */
    readonly errorNumber: number;
    /** Logging metadata
     * @note exceptions should *not* include logging data. Logging should be done where exceptions are caught. This member exists
     * only for backwards compatibility.
     */
    loggingMetadata?: object;
}
/**
 * Base exception class for legacy iTwin.js errors.
 * For backwards compatibility only. Do not create new subclasses of BentleyError. Instead use [[ITwinError]].
 * @public
 */
export declare class BentleyError extends Error {
    errorNumber: number;
    static readonly iTwinErrorScope = "bentley-error";
    private readonly _metaData;
    /**
     * @param errorNumber The a number that identifies of the problem.
     * @param message  message that describes the problem (should not be localized).
     * @param metaData metaData about the exception.
     */
    constructor(errorNumber: number, message?: string, metaData?: LoggingMetaData);
    /** supply the value for iTwinErrorId  */
    get iTwinErrorId(): {
        scope: string;
        key: string;
    };
    /** value for logging metadata */
    get loggingMetadata(): object | undefined;
    /**
     * Determine if an error object implements the `LegacyITwinErrorWithNumber` interface.
     *
     * If the test succeeds, the type of `error` is coerced to `T`
     * @note this method does *not* test that the object is an `instanceOf BentleyError`.
     * @beta
     */
    static isError<T extends LegacyITwinErrorWithNumber>(error: unknown, errorNumber?: number): error is T;
    /** Returns true if this BentleyError includes (optional) metadata. */
    get hasMetaData(): boolean;
    /** get the meta data associated with this BentleyError, if any. */
    getMetaData(): object | undefined;
    /** get the metadata object associated with an ExceptionMetaData, if any. */
    static getMetaData(metaData: LoggingMetaData): object | undefined;
    /** This function returns the name of each error status. Override this method to handle more error status codes. */
    protected _initName(): string;
    /** This function returns the name of each error status. */
    static getErrorKey(errorNumber: number): string;
    /** Use run-time type checking to safely get a useful string summary of an unknown error value, or `""` if none exists.
     * @note It's recommended to use this function in `catch` clauses, where a caught value cannot be assumed to be `instanceof Error`
     * @public
     */
    static getErrorMessage(error: unknown): string;
    /** Use run-time type checking to safely get the call stack of an unknown error value, if possible.
     * @note It's recommended to use this function in `catch` clauses, where a caught value cannot be assumed to be `instanceof Error`
     * @public
     */
    static getErrorStack(error: unknown): string | undefined;
    /** Use run-time type checking to safely get the metadata with an unknown error value, if possible.
     * @note It's recommended to use this function in `catch` clauses, where a caught value cannot be assumed to be `instanceof BentleyError`
     * @see [[BentleyError.getMetaData]]
     * @public
     */
    static getErrorMetadata(error: unknown): object | undefined;
    /** Returns a new `ErrorProps` object representing an unknown error value.  Useful for logging or wrapping/re-throwing caught errors.
     * @note Unlike `Error` objects (which lose messages and call stacks when serialized to JSON), objects
     *       returned by this are plain old JavaScript objects, and can be easily logged/serialized to JSON.
     * @public
     */
    static getErrorProps(error: unknown): ErrorProps;
}
export {};
//# sourceMappingURL=BentleyError.d.ts.map