@itwin/core-bentley 5.0.0-dev.10 → 5.0.0-dev.102

package/lib/esm/BentleyError.d.ts

@@ -1,6 +1,51 @@
 /** @packageDocumentation
  * @module Errors
  */
+import { Optional } from "./UtilityTypes";
+/** 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: Optional<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: Optional<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.
@@ -265,6 +310,9 @@ export declare enum GeoServiceStatus {
     NoDatumConverter = 147459,
     VerticalDatumConvertError = 147460,
     CSMapError = 147461,
+    /**
+     * @deprecated in 5.0. This status is never returned.
+     */
     Pending = 147462
 }
 /** Error status from various reality data operations
@@ -290,11 +338,29 @@ interface ErrorProps {
     stack?: string;
     metadata?: object;
 }
-/** Base exception class for iTwin.js exceptions.
+/**
+ * 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.
@@ -302,6 +368,21 @@ export declare class BentleyError extends Error {
      * @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. */
@@ -310,6 +391,8 @@ export declare class BentleyError extends Error {
     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

package/lib/esm/BentleyError.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"BentleyError.d.ts","sourceRoot":"","sources":["../../src/BentleyError.ts"],"names":[],"mappings":"AAIA;;GAEG;AAKH;;;;;GAKG;AACH,oBAAY,aAAa;IACvB,OAAO,IAAS;IAChB,KAAK,QAAS;CACf;AAED;;;GAGG;AACH,oBAAY,YAAY;IACtB,iBAAiB,QAAU;IAC3B,OAAO,IAAI;IACX,aAAa,QAAwB;IACrC,WAAW,QAAwB;IACnC,MAAM,QAAwB;IAC9B,UAAU,QAAwB;IAClC,QAAQ,QAAwB;IAChC,UAAU,QAAwB;IAClC,SAAS,QAAwB;IACjC,UAAU,QAAwB;IAClC,eAAe,QAAwB;IACvC,kBAAkB,QAAyB;IAC3C,aAAa,QAAyB;IACtC,aAAa,QAAyB;IACtC,oBAAoB,QAAyB;IAC7C,iBAAiB,QAAyB;IAC1C,YAAY,QAAyB;IACrC,aAAa,QAAyB;IACtC,oBAAoB,QAAyB;IAC7C,QAAQ,QAAyB;IACjC,oBAAoB,QAAyB;IAC7C,eAAe,QAAyB;IACxC,WAAW,QAAyB;IACpC,eAAe,QAAyB;IACxC,SAAS,QAAyB;IAClC,WAAW,QAAyB;IACpC,aAAa,QAAyB;IACtC,qBAAqB,QAAyB;IAC9C,mBAAmB,QAAyB;IAC5C,WAAW,QAAyB;IACpC,YAAY,QAAyB;IACrC,WAAW,QAAyB;IACpC,aAAa,QAAyB;IACtC,cAAc,QAAyB;IACvC,SAAS,QAAyB;IAClC,UAAU,QAAyB;IACnC,mBAAmB,QAAyB;IAC5C,UAAU,QAAyB;IACnC,QAAQ,QAAyB;IACjC,OAAO,QAAyB;IAChC,eAAe,QAAyB;IACxC,eAAe,QAAyB;IACxC,aAAa,QAAyB;IACtC,aAAa,QAAyB;IACtC,mBAAmB,QAAyB;IAC5C,SAAS,QAAyB;IAClC,QAAQ,QAAyB;IACjC,cAAc,QAAyB;IACvC,sBAAsB,QAAyB;IAC/C,WAAW,QAAyB;IACpC,iBAAiB,QAAyB;IAC1C,YAAY,QAAyB;IACrC,aAAa,QAAyB;IACtC,aAAa,QAAyB;IACtC,gBAAgB,QAAyB;IACzC,aAAa,QAAyB;IACtC,aAAa,QAAyB;IACtC,YAAY,QAAyB;IACrC,UAAU,QAAyB;IACnC,UAAU,QAAyB;IACnC,WAAW,QAAyB;IACpC,WAAW,QAAyB;IACpC,YAAY,QAAyB;IACrC,YAAY,QAAyB;IACrC,UAAU,QAAyB;IACnC,mBAAmB,QAAyB;IAC5C,aAAa,QAAyB;IACtC,aAAa,QAAyB;IACtC,SAAS,QAAyB;IAClC,aAAa,QAAyB;IACtC,gBAAgB,QAAyB;IACzC,eAAe,QAAyB;IACxC,OAAO,QAAyB;CACjC;AAED;;GAEG;AACH,oBAAY,eAAe;IACzB,qBAAqB,SAAU;IAC/B,aAAa,SAAwB;IACrC,cAAc,SAA4B;IAC1C,YAAY,SAA4B;IACxC,UAAU,SAA4B;IACtC,YAAY,SAA4B;IACxC,eAAe,SAA4B;IAC3C,kBAAkB,SAA4B;IAC9C,iBAAiB,SAA4B;IAC7C,yBAAyB,SAA4B;CACtD;AAED;;GAEG;AACH,oBAAY,kBAAkB;IAC5B,OAAO,IAAI;IACX,wBAAwB,SAAU;IAClC,6GAA6G;IAC7G,mBAAmB,SAA2B;CAC/C;AAED;;GAEG;AACH,oBAAY,eAAe;IACzB,OAAO,IAAI;IACX,oBAAoB,QAAU;IAC9B,mEAAmE;IACnE,UAAU,QAA2B;IACrC,6EAA6E;IAC7E,wBAAwB,QAA2B;IACnD,mFAAmF;IACnF,qBAAqB,QAA2B;IAChD,iEAAiE;IACjE,YAAY,QAA2B;IACvC,qFAAqF;IACrF,cAAc,QAA2B;IACzC,mEAAmE;IACnE,eAAe,QAA2B;IAC1C,sFAAsF;IACtF,qBAAqB,QAA2B;IAChD,4BAA4B;IAC5B,SAAS,QAA2B;IACpC,yCAAyC;IACzC,cAAc,QAA2B;IACzC,0FAA0F;IAC1F,oBAAoB,QAA4B;IAChD,wFAAwF;IACxF,mBAAmB,QAA4B;IAC/C,6EAA6E;IAC7E,sBAAsB,QAA4B;IAClD,oDAAoD;IACpD,qBAAqB,QAA4B;IACjD,8BAA8B;IAC9B,cAAc,QAA4B;IAC1C,2DAA2D;IAC3D,cAAc,QAA4B;IAC1C,iFAAiF;IACjF,cAAc,QAA4B;IAC1C,oDAAoD;IACpD,WAAW,QAA4B;IACvC,6CAA6C;IAC7C,UAAU,QAA4B;IACtC,mDAAmD;IACnD,iBAAiB,QAA4B;IAC7C,8GAA8G;IAC9G,wBAAwB,QAA4B;IACpD,kDAAkD;IAClD,+BAA+B,QAA4B;IAC3D,4HAA4H;IAC5H,0BAA0B,QAA4B;IACtD,kDAAkD;IAClD,uBAAuB,QAA4B;IACnD,iDAAiD;IACjD,qBAAqB,QAA4B;IACjD,uEAAuE;IACvE,uBAAuB,QAA4B;IACnD,2CAA2C;IAC3C,iBAAiB,QAA4B;CAC9C;AAED;;GAEG;AACH,oBAAY,UAAU;IACpB,kBAAkB;IAClB,OAAO,IAAI;IACX,kCAAkC;IAClC,IAAI,QAAU;IACd,sBAAsB;IACtB,WAAW,QAAU;IACrB,wBAAwB;IACxB,WAAW,QAAU;IACrB,wBAAwB;IACxB,WAAW,QAAU;CACtB;AAED;;GAEG;AACH,oBAAY,eAAe;IACzB,OAAO,IAAI;IACX,mBAAmB,SAAU;IAC7B,+BAA+B,SAAU;IACzC,OAAO,SAA0B;IACjC,yBAAyB,SAA0B;IACnD,uBAAuB,SAA0B;IACjD,yBAAyB,SAA0B;IACnD,qBAAqB,SAA0B;IAC/C,gBAAgB,SAA0B;IAC1C,qBAAqB,SAA0B;IAC/C,4BAA4B,SAA0B;IACtD,kBAAkB,SAA0B;IAC5C,sBAAsB,SAA2B;IACjD,qBAAqB,SAA2B;IAChD,iBAAiB,SAA2B;IAC5C,sBAAsB,SAA2B;IACjD,wBAAwB,SAA2B;IACnD,eAAe,SAA2B;IAC1C,cAAc,SAA2B;IACzC,gCAAgC,SAA2B;IAC3D,yCAAyC,SAA2B;IACpE,yBAAyB,SAA2B;IACpD,cAAc,SAA2B;IACzC,UAAU,SAA2B;IACrC,UAAU,SAA2B;IACrC,mBAAmB,SAA2B;IAC9C,kBAAkB,SAA2B;IAC7C,gBAAgB,SAA2B;IAC3C,iBAAiB,SAA2B;IAC5C,gBAAgB,SAA2B;IAC3C,2BAA2B,SAA2B;IACtD,gBAAgB,SAA2B;IAC3C,8BAA8B,SAA2B;IACzD,gBAAgB,SAA2B;IAC3C,qBAAqB,SAA2B;IAChD,6BAA6B,SAA2B;IACxD,8BAA8B,SAA2B;IACzD,qBAAqB,SAA2B;IAChD,2BAA2B,SAA2B;IACtD,uBAAuB,SAA2B;IAClD,0BAA0B,SAA2B;IACrD,oBAAoB,SAA2B;IAC/C,mBAAmB,SAA2B;IAC9C,kBAAkB,SAA2B;IAC7C,oBAAoB,SAA2B;IAE/C,uBAAuB,SAA2B;IAClD,4BAA4B,SAA2B;IAEvD,2BAA2B,SAA2B;IACtD,uBAAuB,SAA2B;IAClD,iBAAiB,SAA2B;IAE5C,qBAAqB,SAA2B;IAEhD,uBAAuB,SAA2B;IAClD,sBAAsB,SAA2B;IAGjD,sBAAsB,SAAsC;IAC5D,oBAAoB,SAAsC;IAC1D,uBAAuB,SAAsC;IAC7D,qBAAqB,SAAsC;IAC3D,iBAAiB,SAAsC;IACvD,YAAY,SAAsC;IAClD,qBAAqB,SAAsC;CAC5D;AAED;;GAEG;AACH,oBAAY,gBAAgB;IAC1B,OAAO,IAAI;IACX,qBAAqB,SAAU;IAE/B,aAAa,QAA6B;IAE1C,gBAAgB,SAA4B;IAC5C,uBAAuB,SAA4B;IACnD,gBAAgB,SAA4B;IAC5C,yBAAyB,SAA4B;IACrD,UAAU,SAA4B;IACtC,OAAO,SAA4B;CACpC;AAED;;GAEG;AACH,oBAAY,iBAAiB;IAC3B,OAAO,IAAI;IACX,sBAAsB,SAAU;IAChC,WAAW,SAA6B;CACzC;AAED;;;GAGG;AACH,MAAM,MAAM,mBAAmB,GAAG,MAAM,MAAM,GAAG,SAAS,CAAC;AAE3D;;;GAGG;AACH,MAAM,MAAM,eAAe,GAAG,mBAAmB,GAAG,MAAM,GAAG,SAAS,CAAC;AAMvE,UAAU,UAAU;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,qBAAa,YAAa,SAAQ,KAAK;IAQX,WAAW,EAAE,MAAM;IAP7C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAkB;IAE5C;;;;OAIG;gBACuB,WAAW,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,eAAe;IAO3F,sEAAsE;IACtE,IAAW,WAAW,IAAI,OAAO,CAAyC;IAE1E,mEAAmE;IAC5D,WAAW,IAAI,MAAM,GAAG,SAAS;IAIxC,4EAA4E;WAC9D,WAAW,CAAC,QAAQ,EAAE,eAAe,GAAG,MAAM,GAAG,SAAS;IAIxE,mHAAmH;IACnH,SAAS,CAAC,SAAS,IAAI,MAAM;IA0R7B;;;OAGG;WACW,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM;IAsBrD;;;OAGG;WACW,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS;IAO/D;;;;OAIG;WACW,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS;IAUlE;;;;OAIG;WACW,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,UAAU;CAexD"}
+{"version":3,"file":"BentleyError.d.ts","sourceRoot":"","sources":["../../src/BentleyError.ts"],"names":[],"mappings":"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"}

package/lib/esm/BentleyError.js

@@ -7,6 +7,41 @@
  */
 import { DbResult } from "./BeSQLite";
 import { RepositoryStatus } from "./internal/RepositoryStatus";
+import { JsonUtils } from "./JsonUtils";
+/** @beta */
+export var ITwinError;
+(function (ITwinError) {
+    /** Instantiate a new `ITwinError` or subtype thereof.
+     * @see [[ITwinError.throwError]] to conveniently instantiate and throw the error.
+     */
+    function create(args) {
+        const err = new Error(args.message);
+        Object.assign(err, args);
+        err.name = args.iTwinErrorId.key; // helpful because this is used by `toString` for Error class
+        return err;
+    }
+    ITwinError.create = create;
+    /** Instantiate and immediately throw an `ITwinError`.
+     * @see [[ITwinError.create]] to instantiate an error without throwing it.
+     */
+    function throwError(args) {
+        throw create(args);
+    }
+    ITwinError.throwError = throwError;
+    /**
+     * 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(error, scope, key) {
+        return JsonUtils.isObject(error) && "iTwinErrorId" in error && JsonUtils.isObject(error.iTwinErrorId)
+            && error.iTwinErrorId.scope === scope && (undefined === key || error.iTwinErrorId.key === key);
+    }
+    ITwinError.isError = isError;
+})(ITwinError || (ITwinError = {}));
 /** 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.
@@ -282,6 +317,9 @@ export var GeoServiceStatus;
     GeoServiceStatus[GeoServiceStatus["NoDatumConverter"] = 147459] = "NoDatumConverter";
     GeoServiceStatus[GeoServiceStatus["VerticalDatumConvertError"] = 147460] = "VerticalDatumConvertError";
     GeoServiceStatus[GeoServiceStatus["CSMapError"] = 147461] = "CSMapError";
+    /**
+     * @deprecated in 5.0. This status is never returned.
+     */
     GeoServiceStatus[GeoServiceStatus["Pending"] = 147462] = "Pending";
 })(GeoServiceStatus || (GeoServiceStatus = {}));
 /** Error status from various reality data operations
@@ -293,13 +331,15 @@ export var RealityDataStatus;
     RealityDataStatus[RealityDataStatus["REALITYDATA_ERROR_BASE"] = 151552] = "REALITYDATA_ERROR_BASE";
     RealityDataStatus[RealityDataStatus["InvalidData"] = 151553] = "InvalidData";
 })(RealityDataStatus || (RealityDataStatus = {}));
-function isObject(obj) {
-    return typeof obj === "object" && obj !== null;
-}
-/** Base exception class for iTwin.js exceptions.
+/**
+ * Base exception class for legacy iTwin.js errors.
+ * For backwards compatibility only. Do not create new subclasses of BentleyError. Instead use [[ITwinError]].
  * @public
  */
 export class BentleyError extends Error {
+    errorNumber;
+    static iTwinErrorScope = "bentley-error";
+    _metaData;
     /**
      * @param errorNumber The a number that identifies of the problem.
      * @param message  message that describes the problem (should not be localized).
@@ -312,6 +352,23 @@ export class BentleyError extends Error {
         this._metaData = metaData;
         this.name = this._initName();
     }
+    /** supply the value for iTwinErrorId  */
+    get iTwinErrorId() {
+        return { scope: BentleyError.iTwinErrorScope, key: this.name };
+    }
+    /** value for logging metadata */
+    get loggingMetadata() { return this.getMetaData(); }
+    /**
+     * 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(error, errorNumber) {
+        return ITwinError.isError(error, BentleyError.iTwinErrorScope) &&
+            typeof error.errorNumber === "number" && (errorNumber === undefined || error.errorNumber === errorNumber);
+    }
     /** Returns true if this BentleyError includes (optional) metadata. */
     get hasMetaData() { return undefined !== this._metaData; }
     /** get the meta data associated with this BentleyError, if any. */
@@ -324,7 +381,11 @@ export class BentleyError extends Error {
     }
     /** This function returns the name of each error status. Override this method to handle more error status codes. */
     _initName() {
-        switch (this.errorNumber) {
+        return BentleyError.getErrorKey(this.errorNumber);
+    }
+    /** This function returns the name of each error status. */
+    static getErrorKey(errorNumber) {
+        switch (errorNumber) {
             case IModelStatus.AlreadyLoaded: return "Already Loaded";
             case IModelStatus.AlreadyOpen: return "Already Open";
             case IModelStatus.BadArg: return "Bad Arg";
@@ -591,7 +652,7 @@ export class BentleyError extends Error {
             case GeoServiceStatus.NoDatumConverter: return "No datum converter";
             case GeoServiceStatus.VerticalDatumConvertError: return "Vertical datum convert error";
             case GeoServiceStatus.CSMapError: return "CSMap error";
-            case GeoServiceStatus.Pending: return "Pending";
+            case GeoServiceStatus.Pending: return "Pending"; // eslint-disable-line @typescript-eslint/no-deprecated
             case RealityDataStatus.InvalidData: return "Invalid or unknown data";
             case DbResult.BE_SQLITE_OK:
             case DbResult.BE_SQLITE_ROW:
@@ -599,7 +660,7 @@ export class BentleyError extends Error {
             case BentleyStatus.SUCCESS:
                 return "Success";
             default:
-                return `Error (${this.errorNumber})`;
+                return `Error (${errorNumber})`;
         }
     }
     /** Use run-time type checking to safely get a useful string summary of an unknown error value, or `""` if none exists.
@@ -611,7 +672,7 @@ export class BentleyError extends Error {
             return error;
         if (error instanceof Error)
             return error.toString();
-        if (isObject(error)) {
+        if (JsonUtils.isObject(error)) {
             if (typeof error.message === "string")
                 return error.message;
             if (typeof error.msg === "string")
@@ -627,7 +688,7 @@ export class BentleyError extends Error {
      * @public
      */
     static getErrorStack(error) {
-        if (isObject(error) && typeof error.stack === "string")
+        if (JsonUtils.isObject(error) && typeof error.stack === "string")
             return error.stack;
         return undefined;
     }
@@ -637,7 +698,7 @@ export class BentleyError extends Error {
      * @public
      */
     static getErrorMetadata(error) {
-        if (isObject(error) && typeof error.getMetaData === "function") {
+        if (JsonUtils.isObject(error) && typeof error.getMetaData === "function") {
             const metadata = error.getMetaData();
             if (typeof metadata === "object" && metadata !== null)
                 return metadata;