expo-modules-core 0.6.4 → 0.7.0

package/ios/Swift/Arguments/Convertibles.swift

@@ -3,11 +3,11 @@
 import UIKit
 import CoreGraphics
 
-/// Here we extend some common iOS types to implement `ConvertibleArgument` protocol and
-/// describe how they can be converted from primitive types received from JavaScript runtime.
-/// This allows these types to be used as argument types of functions callable from JavaScript.
-/// As an example, when the `CGPoint` type is used as an argument type, its instance can be
-/// created from an array of two doubles or an object with `x` and `y` fields.
+// Here we extend some common iOS types to implement `ConvertibleArgument` protocol and
+// describe how they can be converted from primitive types received from JavaScript runtime.
+// This allows these types to be used as argument types of functions callable from JavaScript.
+// As an example, when the `CGPoint` type is used as an argument type, its instance can be
+// created from an array of two doubles or an object with `x` and `y` fields.
 
 // MARK: - Foundation
 
@@ -19,7 +19,7 @@ extension URL: ConvertibleArgument {
       // If it has no scheme, we assume it was the file path.
       return url.scheme != nil ? url : URL(fileURLWithPath: uri)
     }
-    throw Conversions.ConvertingError<URL>(value: value)
+    throw Conversions.ConvertingException<URL>(value)
   }
 }
 
@@ -37,7 +37,7 @@ extension UIColor: ConvertibleArgument {
     if let value = value as? Int {
       return try Conversions.toColor(argb: UInt64(value)) as! Self
     }
-    throw Conversions.ConvertingError<UIColor>(value: value)
+    throw Conversions.ConvertingException<UIColor>(value)
   }
 }
 
@@ -52,7 +52,7 @@ extension CGPoint: ConvertibleArgument {
       let args = try Conversions.pickValues(from: value, byKeys: ["x", "y"], as: Double.self)
       return CGPoint(x: args[0], y: args[1])
     }
-    throw Conversions.ConvertingError<CGPoint>(value: value)
+    throw Conversions.ConvertingException<CGPoint>(value)
   }
 }
 
@@ -65,7 +65,7 @@ extension CGSize: ConvertibleArgument {
       let args = try Conversions.pickValues(from: value, byKeys: ["width", "height"], as: Double.self)
       return CGSize(width: args[0], height: args[1])
     }
-    throw Conversions.ConvertingError<CGSize>(value: value)
+    throw Conversions.ConvertingException<CGSize>(value)
   }
 }
 
@@ -78,7 +78,7 @@ extension CGVector: ConvertibleArgument {
       let args = try Conversions.pickValues(from: value, byKeys: ["dx", "dy"], as: Double.self)
       return CGVector(dx: args[0], dy: args[1])
     }
-    throw Conversions.ConvertingError<CGVector>(value: value)
+    throw Conversions.ConvertingException<CGVector>(value)
   }
 }
 
@@ -91,7 +91,7 @@ extension CGRect: ConvertibleArgument {
       let args = try Conversions.pickValues(from: value, byKeys: ["x", "y", "width", "height"], as: Double.self)
       return CGRect(x: args[0], y: args[1], width: args[2], height: args[3])
     }
-    throw Conversions.ConvertingError<CGRect>(value: value)
+    throw Conversions.ConvertingException<CGRect>(value)
   }
 }
 
@@ -99,9 +99,9 @@ extension CGColor: ConvertibleArgument {
   public static func convert(from value: Any?) throws -> Self {
     do {
       return try UIColor.convert(from: value).cgColor as! Self
-    } catch _ as Conversions.ConvertingError<UIColor> {
+    } catch _ as Conversions.ConvertingException<UIColor> {
       // Rethrow `ConvertingError` with proper type
-      throw Conversions.ConvertingError<CGColor>(value: value)
+      throw Conversions.ConvertingException<CGColor>(value)
     }
   }
 }

package/ios/Swift/Arguments/Types/EnumArgumentType.swift

@@ -43,10 +43,10 @@ public protocol EnumArgument: AnyArgument {
 public extension EnumArgument where Self: RawRepresentable, Self: Hashable {
   static func create<ArgType>(fromRawValue rawValue: ArgType) throws -> Self {
     guard let rawValue = rawValue as? RawValue else {
-      throw EnumCastingError(type: RawValue.self, value: rawValue)
+      throw EnumCastingException((type: RawValue.self, value: rawValue))
     }
     guard let enumCase = Self.init(rawValue: rawValue) else {
-      throw EnumNoSuchValueError(type: Self.self, value: rawValue)
+      throw EnumNoSuchValueException((type: Self.self, value: rawValue))
     }
     return enumCase
   }
@@ -75,31 +75,25 @@ public extension EnumArgument where Self: RawRepresentable, Self: Hashable {
 }
 
 /**
- An error that is thrown when the value cannot be casted to associated `RawValue`.
+ An error that is thrown when the value cannot be cast to associated `RawValue`.
  */
-internal struct EnumCastingError: CodedError {
-  let type: Any.Type
-  let value: Any
-
-  var description: String {
-    "Cannot cast value `\(value)` to expected type `\(type)`"
+internal class EnumCastingException: GenericException<(type: Any.Type, value: Any)> {
+  override var reason: String {
+    "Unable to cast '\(param.value)' to expected type \(param.type)"
   }
 }
 
 /**
  An error that is thrown when the value doesn't match any available case.
  */
-internal struct EnumNoSuchValueError: CodedError {
-  let type: EnumArgument.Type
-  let value: Any
-
+internal class EnumNoSuchValueException: GenericException<(type: EnumArgument.Type, value: Any)> {
   var allRawValuesFormatted: String {
-    return type.allRawValues
-      .map { "`\($0)`" }
+    return param.type.allRawValues
+      .map { "'\($0)'" }
       .joined(separator: ", ")
   }
 
-  var description: String {
-    "Cannot create `\(type)` enum from value `\(value)`. It must be one of: \(allRawValuesFormatted)"
+  override var reason: String {
+    "'\(param.value)' is not present in \(param.type) enum, it must be one of: \(allRawValuesFormatted)"
   }
 }

package/ios/Swift/Arguments/Types/PromiseArgumentType.swift

@@ -8,7 +8,7 @@ internal struct PromiseArgumentType: AnyArgumentType {
     if let value = value as? Promise {
       return value
     }
-    throw Conversions.CastingError<Promise>(value: value)
+    throw Conversions.CastingException<Promise>(value)
   }
 
   var description: String = "Promise"

package/ios/Swift/Arguments/Types/RawArgumentType.swift

@@ -14,9 +14,9 @@ internal struct RawArgumentType<InnerType>: AnyArgumentType {
     // Raw arguments are always non-optional, but they may receive `nil` values.
     // Let's throw more specific error in this case.
     if Optional.isNil(value) {
-      throw Conversions.NullCastError<InnerType>()
+      throw Conversions.NullCastException<InnerType>()
     }
-    throw Conversions.CastingError<InnerType>(value: value)
+    throw Conversions.CastingException<InnerType>(value)
   }
 
   var description: String {

package/ios/Swift/Conversions.swift

@@ -1,10 +1,9 @@
-
 internal final class Conversions {
   /**
    Converts an array to tuple. Because of tuples nature, it's not possible to convert an array of any size, so we can support only up to some fixed size.
    */
   static func toTuple(_ array: [Any?]) throws -> Any? {
-    switch (array.count) {
+    switch array.count {
     case 0:
       return ()
     case 1:
@@ -28,7 +27,7 @@ internal final class Conversions {
     case 10:
       return (array[0], array[1], array[2], array[3], array[4], array[5], array[6], array[7], array[8], array[9])
     default:
-      throw TooManyArgumentsError(count: array.count, limit: 10)
+      throw TooManyArgumentsException((count: array.count, limit: 10))
     }
   }
 
@@ -47,9 +46,9 @@ internal final class Conversions {
   }
 
   /**
-   Picks values under given keys from the dictionary, casted to a specific type. Can throw errors when
-   - The dictionary is missing some of the given keys (`MissingKeysError`)
-   - Some of the values cannot be casted to specified type (`CastingValuesError`)
+   Picks values under given keys from the dictionary, cast to a specific type. Can throw exceptions when
+   - The dictionary is missing some of the given keys (`MissingKeysException`)
+   - Some of the values cannot be cast to specified type (`CastingValuesException`)
    */
   static func pickValues<ValueType>(from dict: [String: Any], byKeys keys: [String], as type: ValueType.Type) throws -> [ValueType] {
     var result = (
@@ -68,17 +67,17 @@ internal final class Conversions {
         result.invalidKeys.append(key)
       }
     }
-    if result.missingKeys.count > 0 {
-      throw MissingKeysError<ValueType>(keys: result.missingKeys)
+    if !result.missingKeys.isEmpty {
+      throw MissingKeysException<ValueType>(result.missingKeys)
     }
-    if result.invalidKeys.count > 0 {
-      throw CastingValuesError<ValueType>(keys: result.invalidKeys)
+    if !result.invalidKeys.isEmpty {
+      throw CastingValuesException<ValueType>(result.invalidKeys)
     }
     return result.values
   }
 
   /**
-   Converts hex string to `UIColor` or throws an error if the string is corrupted.
+   Converts hex string to `UIColor` or throws an exception if the string is corrupted.
    */
   static func toColor(hexString hex: String) throws -> UIColor {
     var hexStr = hex
@@ -104,7 +103,7 @@ internal final class Conversions {
 
     guard hexStr.range(of: #"^[0-9a-fA-F]{8}$"#, options: .regularExpression) != nil,
           Scanner(string: hexStr).scanHexInt64(&rgba) else {
-      throw InvalidHexColorError(hex: hex)
+      throw InvalidHexColorException(hex)
     }
     return try toColor(rgba: rgba)
   }
@@ -115,7 +114,7 @@ internal final class Conversions {
    */
   static func toColor(argb: UInt64) throws -> UIColor {
     guard argb <= UInt32.max else {
-      throw HexColorOverflowError(hex: argb)
+      throw HexColorOverflowException(argb)
     }
     let alpha = CGFloat((argb >> 24) & 0xff) / 255.0
     let red   = CGFloat((argb >> 16) & 0xff) / 255.0
@@ -129,7 +128,7 @@ internal final class Conversions {
    */
   static func toColor(rgba: UInt64) throws -> UIColor {
     guard rgba <= UInt32.max else {
-      throw HexColorOverflowError(hex: rgba)
+      throw HexColorOverflowException(rgba)
     }
     let red   = CGFloat((rgba >> 24) & 0xff) / 255.0
     let green = CGFloat((rgba >> 16) & 0xff) / 255.0
@@ -145,90 +144,86 @@ internal final class Conversions {
     return keys.map { "`\($0)`" }.joined(separator: ", ")
   }
 
-  // MARK: - Errors
+  static func formatPlural(_ number: Int, _ singular: String, _ plural: String? = nil) -> String {
+    return String(number) + (number == 1 ? singular : (plural ?? singular + "s"))
+  }
+
+  // MARK: - Exceptions
 
   /**
-   An error meaning that the number of arguments exceeds the limit.
+   An exception meaning that the number of arguments exceeds the limit.
    */
-  internal struct TooManyArgumentsError: CodedError {
-    let count: Int
-    let limit: Int
-    var description: String {
-      "A number of arguments `\(count)` exceeds the limit of `\(limit)`"
+  internal class TooManyArgumentsException: GenericException<(count: Int, limit: Int)> {
+    override var reason: String {
+      "Native function expects \(formatPlural(param.limit, "argument")), but received \(param.count)"
     }
   }
 
   /**
-   An error that can be thrown by convertible types, when given value cannot be converted.
+   An exception that can be thrown by convertible types, when given value cannot be converted.
    */
-  internal struct ConvertingError<TargetType>: CodedError {
-    let value: Any?
+  internal class ConvertingException<TargetType>: GenericException<Any?> {
     var code: String = "ERR_CONVERTING_FAILED"
-    var description: String {
-      "Cannot convert `\(String(describing: value))` to `\(TargetType.self)`"
+    override var reason: String {
+      "Cannot convert '\(String(describing: param))' to \(TargetType.self)"
     }
   }
 
   /**
-   An error that is thrown when given value cannot be casted.
+   An exception that is thrown when given value cannot be cast.
    */
-  internal struct CastingError<TargetType>: CodedError {
-    let value: Any
+  internal class CastingException<TargetType>: GenericException<Any> {
     var code: String = "ERR_CASTING_FAILED"
-    var description: String {
-      "Cannot cast `\(String(describing: value))` to `\(TargetType.self)`"
+    override var reason: String {
+      "Cannot cast '\(String(describing: param))' to \(TargetType.self)"
     }
   }
 
   /**
-   An error that can be thrown by convertible types,
-   when the values in given dictionary cannot be casted to specific type.
+   An exception that can be thrown by convertible types,
+   when the values in given dictionary cannot be cast to specific type.
    */
-  internal struct CastingValuesError<ValueType>: CodedError {
-    let keys: [String]
+  internal class CastingValuesException<ValueType>: GenericException<[String]> {
     var code: String = "ERR_CASTING_VALUES_FAILED"
-    var description: String {
-      "Cannot cast keys \(formatKeys(keys)) to `\(ValueType.self)`"
+    override var reason: String {
+      "Cannot cast keys \(formatKeys(param)) to \(ValueType.self)"
     }
   }
 
   /**
-   An error that can be throw by convertible types,
+   An exception that can be thrown by convertible types,
    when given dictionary is missing some required keys.
    */
-  internal struct MissingKeysError<ValueType>: CodedError {
-    let keys: [String]
-    var description: String {
-      "Missing keys \(formatKeys(keys)) of type `\(ValueType.self)`"
+  internal class MissingKeysException<ValueType>: GenericException<[String]> {
+    override var reason: String {
+      "Missing keys \(formatKeys(param)) to create \(ValueType.self) record"
     }
   }
 
   /**
-   An error that is thrown when null value is tried to be casted to non-optional type.
+   An exception that is thrown when null value is tried to be cast to non-optional type.
    */
-  internal struct NullCastError<TargetType>: CodedError {
-    var description: String {
-      "Cannot cast null value to non-optional `\(TargetType.self)`"
+  internal class NullCastException<TargetType>: Exception {
+    override var reason: String {
+      "Cannot cast null to non-optional '\(TargetType.self)'"
     }
   }
 
   /**
-   An error used when the hex color string is invalid (e.g. contains non-hex characters).
+   An exception used when the hex color string is invalid (e.g. contains non-hex characters).
    */
-  internal struct InvalidHexColorError: CodedError {
-    let hex: String
-    var description: String {
-      "Provided hex color `\(hex)` is invalid"
+  internal class InvalidHexColorException: GenericException<String> {
+    override var reason: String {
+      "Provided hex color '\(param)' is invalid"
     }
   }
 
   /**
-   An error used when the integer value of the color would result in an overflow of `UInt32`.
+   An exception used when the integer value of the color would result in an overflow of `UInt32`.
    */
-  internal struct HexColorOverflowError: CodedError {
-    let hex: UInt64
-    var description: String {
-      "Provided hex color `\(hex)` would result in an overflow"
+  internal class HexColorOverflowException: GenericException<UInt64> {
+    override var reason: String {
+      "Provided hex color '\(param)' would result in an overflow"
     }
   }
 }

package/ios/Swift/EventListener.swift

@@ -10,7 +10,7 @@ internal struct EventListener: AnyDefinition {
    */
   init(_ name: EventName, _ listener: @escaping () -> Void) {
     self.name = name
-    self.call = { (sender, payload) in listener() }
+    self.call = { _, _ in listener() }
   }
 
   /**
@@ -18,9 +18,9 @@ internal struct EventListener: AnyDefinition {
    */
   init<Sender>(_ name: EventName, _ listener: @escaping (Sender) -> Void) {
     self.name = name
-    self.call = { (sender, payload) in
+    self.call = { sender, _ in
       guard let sender = sender as? Sender else {
-        throw InvalidSenderTypeError(eventName: name, senderType: Sender.self)
+        throw InvalidSenderTypeException((eventName: name, senderType: Sender.self))
       }
       listener(sender)
     }
@@ -31,20 +31,18 @@ internal struct EventListener: AnyDefinition {
    */
   init<Sender, PayloadType>(_ name: EventName, _ listener: @escaping (Sender, PayloadType?) -> Void) {
     self.name = name
-    self.call = { (sender, payload) in
+    self.call = { sender, payload in
       guard let sender = sender as? Sender else {
-        throw InvalidSenderTypeError(eventName: name, senderType: Sender.self)
+        throw InvalidSenderTypeException((eventName: name, senderType: Sender.self))
       }
       listener(sender, payload as? PayloadType)
     }
   }
 }
 
-struct InvalidSenderTypeError: CodedError {
-  var eventName: EventName
-  var senderType: Any.Type
-  var description: String {
-    "Sender for event `\(eventName)` must be of type `\(senderType)`."
+class InvalidSenderTypeException: GenericException<(eventName: EventName, senderType: Any.Type)> {
+  override var reason: String {
+    "Sender for event '\(param.eventName)' must be of type \(param.senderType)"
   }
 }
 

package/ios/Swift/Events/Callback.swift

@@ -0,0 +1,66 @@
+// Copyright 2021-present 650 Industries. All rights reserved.
+
+/**
+ An alias for type-erased callback handler.
+ */
+typealias AnyCallbackHandlerType = (Any) -> Void
+
+/**
+ Public type-erased protocol that `Callback` object conforms to.
+ */
+public protocol AnyCallback {
+  /**
+   Initializes an empty callback (no-op).
+   */
+  init()
+}
+
+/**
+ Internal type-erased protocol for `Callback` object.
+ */
+internal protocol AnyCallbackInternal: AnyCallback {
+  /**
+   Sets the callback handler. By default the callback
+   is not settled which means it has no handler, thus is no-op.
+   */
+  func settle(_ handler: @escaping AnyCallbackHandlerType)
+
+  /**
+   Invalidates the callback, making its handler no-op.
+   */
+  func invalidate()
+}
+
+/**
+ Callable object that represents a JavaScript function.
+ */
+public class Callback<ArgType>: AnyCallback, AnyCallbackInternal {
+  /**
+   The underlying closure to invoke when the callback is called.
+   */
+  private var handler: AnyCallbackHandlerType?
+
+  // MARK: AnyCallback
+
+  public required init() {}
+
+  // MARK: AnyCallbackInternal
+
+  internal func settle(_ handler: @escaping AnyCallbackHandlerType) {
+    self.handler = handler
+  }
+
+  internal func invalidate() {
+    self.handler = nil
+  }
+
+  // MARK: Calling as function
+
+  /**
+   Allows the callback instance to be called as a function.
+   */
+  public func callAsFunction(_ arg: ArgType) {
+    // TODO: Convert records to dictionaries (@tsapeta)
+    handler?(arg as Any)
+  }
+}

package/ios/Swift/Events/Event.swift

@@ -0,0 +1,43 @@
+// Copyright 2021-present 650 Industries. All rights reserved.
+
+/**
+ Internal type-erased protocol for the instances of the `Event` property wrapper.
+ */
+internal protocol AnyEventInternal {
+  /**
+   Sets the handler on the wrapped callback.
+   */
+  func settle(_ handler: @escaping AnyCallbackHandlerType)
+
+  /**
+   Invalidates the callback.
+   */
+  func invalidate()
+}
+
+/**
+ The class used as a property wrapper on view's or object's callbacks.
+ */
+@propertyWrapper
+public final class Event<CallbackType: AnyCallback>: AnyEventInternal {
+  public var wrappedValue: CallbackType
+
+  /**
+   The property wrapper initializer. The wrapped value falls back to the empty callback.
+   */
+  public init(wrappedValue: CallbackType = CallbackType()) {
+    self.wrappedValue = wrappedValue
+  }
+
+  internal func settle(_ handler: @escaping AnyCallbackHandlerType) {
+    if let callback = wrappedValue as? AnyCallbackInternal {
+      callback.settle(handler)
+    }
+  }
+
+  internal func invalidate() {
+    if let callback = wrappedValue as? AnyCallbackInternal {
+      callback.invalidate()
+    }
+  }
+}

package/ios/Swift/Exceptions/ChainableException.swift

@@ -0,0 +1,51 @@
+// Copyright 2022-present 650 Industries. All rights reserved.
+
+/**
+ An exception that may have been caused by another error.
+ */
+public protocol ChainableException: Error, AnyObject {
+  /**
+   The direct cause of the exception.
+   */
+  var cause: Error? { get set }
+
+  /**
+   The first error that started the chain of exceptions.
+   */
+  var rootCause: Error? { get }
+
+  /**
+   Sets the direct cause of the exception and returns itself.
+   */
+  func causedBy(_ error: Error) -> Self
+
+  /**
+   Tells whether any of the cause in chain is of given type.
+   */
+  func isCausedBy<ErrorType: Error>(_ errorType: ErrorType.Type) -> Bool
+}
+
+public extension ChainableException {
+  var rootCause: Error? {
+    if let cause = cause as? ChainableException {
+      return cause.rootCause ?? cause
+    }
+    return cause
+  }
+
+  @discardableResult
+  func causedBy(_ error: Error) -> Self {
+    cause = error
+    return self
+  }
+
+  func isCausedBy<ErrorType: Error>(_ errorType: ErrorType.Type) -> Bool {
+    if cause is ErrorType {
+      return true
+    }
+    if let cause = cause as? ChainableException {
+      return cause.isCausedBy(errorType)
+    }
+    return false
+  }
+}

package/ios/Swift/{CodedError.swift → Exceptions/CodedError.swift}

@@ -18,7 +18,7 @@ public extension CodedError {
    */
   var code: String {
     let className = String(describing: type(of: self))
-      .replacingOccurrences(of: #"(Error)?(<.*>)?$"#, with: "", options: .regularExpression)
+      .replacingOccurrences(of: #"(Error|Exception)?(<.*>)?$"#, with: "", options: .regularExpression)
     let regex = try! NSRegularExpression(pattern: "(.)([A-Z])", options: [])
     let range = NSRange(location: 0, length: className.count)
 
@@ -48,14 +48,3 @@ public struct SimpleCodedError: CodedError {
     self.description = description
   }
 }
-
-/**
- Coded wrapper for uncoded errors. Intended to be used to handle unexpected native errors.
- */
-public struct UnexpectedError: CodedError {
-  public let description: String
-
-  init(_ error: Error) {
-    self.description = error.localizedDescription
-  }
-}

package/ios/Swift/Exceptions/Exception.swift

@@ -0,0 +1,62 @@
+// Copyright 2022-present 650 Industries. All rights reserved.
+
+open class Exception: CodedError, ChainableException, CustomStringConvertible, CustomDebugStringConvertible {
+  open var name: String {
+    return String(describing: Self.self)
+  }
+
+  /**
+   String describing the reason of the exception.
+   */
+  open var reason: String {
+    "undefined reason"
+  }
+
+  /**
+   The origin in code where the exception was created.
+   */
+  open var origin: ExceptionOrigin
+
+  /**
+   The default initializer that captures the place in the code where the exception was created.
+   - Warning: Call it only without arguments!
+   */
+  public init(file: String = #fileID, line: UInt = #line, function: String = #function) {
+    self.origin = ExceptionOrigin(file: file, line: line, function: function)
+  }
+
+  // MARK: ChainableException
+
+  open var cause: Error?
+
+  // MARK: CustomStringConvertible
+
+  open var description: String {
+    return concatDescription(reason, withCause: cause, debug: false)
+  }
+
+  // MARK: CustomDebugStringConvertible
+
+  open var debugDescription: String {
+    let debugDescription = "\(name): \(reason) (at \(origin.file):\(origin.line))"
+    return concatDescription(debugDescription, withCause: cause, debug: true)
+  }
+}
+
+/**
+ Concatenates the exception description with its cause description.
+ */
+private func concatDescription(_ description: String, withCause cause: Error?, debug: Bool = false) -> String {
+  let causeSeparator = "\n→ Caused by: "
+  switch cause {
+  case let cause as Exception:
+    return description + causeSeparator + (debug ? cause.debugDescription : cause.description)
+  case let cause as CodedError:
+    // `CodedError` is deprecated but we need to provide backwards compatibility as some modules already used it.
+    return description + causeSeparator + cause.description
+  case let cause?:
+    return description + causeSeparator + cause.localizedDescription
+  default:
+    return description
+  }
+}