/// `JSException` is a wrapper that handles exceptions thrown during JavaScript execution as Swift

/// `Error` objects.

/// When a JavaScript function throws an exception, it's wrapped as a `JSException` and propagated

/// through Swift's error handling mechanism.

///

/// Example:

/// ```swift

/// do {

/// try jsFunction.throws()

/// } catch let error as JSException {

/// // Access the value thrown from JavaScript

/// let jsErrorValue = error.thrownValue

/// }

/// ```

public struct JSException: Error, Equatable, CustomStringConvertible {

/// The value thrown from JavaScript.

/// This can be any JavaScript value (error object, string, number, etc.).

public var thrownValue: JSValue {

return _thrownValue

}

/// The actual JavaScript value that was thrown.

///

/// Marked as `nonisolated(unsafe)` to satisfy `Sendable` requirement

/// from `Error` protocol.

private nonisolated(unsafe) let _thrownValue: JSValue

/// A description of the exception.

public let description: String

/// The stack trace of the exception.

public let stack: String?

/// Initializes a new JSException instance with a value thrown from JavaScript.

///

/// Only available within the package. This must be called on the thread where the exception object created.

@usableFromInline

package init(_ thrownValue: JSValue) {

self._thrownValue = thrownValue

// Capture the stringified representation on the object owner thread

// to bring useful info to the catching thread even if they are different threads.

if let errorObject = thrownValue.object, let stack = errorObject.stack.string {

self.description = "JSException(\(stack))"

self.stack = stack

} else {

self.description = "JSException(\(thrownValue))"

self.stack = nil

}

}

/// Initializes a new JavaScript `Error` instance with a message and prepare it to be thrown.

///

/// - Parameters:

/// - message: The message to throw.

public init(message: String) {

self.init(JSError(message: message).jsValue)

}

}