expo-modules-core 0.6.4 → 0.8.0

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
+  }
+}

package/ios/Swift/Exceptions/ExceptionOrigin.swift

@@ -0,0 +1,28 @@
+// Copyright 2022-present 650 Industries. All rights reserved.
+
+/**
+ Represents the place in code where the exception was created.
+ */
+public struct ExceptionOrigin: CustomStringConvertible {
+  /**
+   The path to the file in which the exception was created.
+   */
+  let file: String
+
+  /**
+   The line number on which the exception was created.
+   */
+  let line: UInt
+
+  /**
+   The name (selector) of the declaration in which the exception was created.
+   */
+  let function: String
+
+  /**
+   Stringified representation of the exception origin.
+   */
+  public var description: String {
+    "at \(file):\(line) in \(function)"
+  }
+}

package/ios/Swift/Exceptions/GenericException.swift

@@ -0,0 +1,20 @@
+// Copyright 2022-present 650 Industries. All rights reserved.
+
+/**
+ The exception that needs some additional parameters to be best described.
+ */
+open class GenericException<ParamType>: Exception {
+  /**
+   The additional parameter passed to the initializer.
+   */
+  public let param: ParamType
+
+  /**
+   The default initializer that takes a param and captures the place in the code where the exception was created.
+   - Warning: Call it only with one argument! If you need to pass more parameters, use a tuple instead.
+   */
+  public init(_ param: ParamType, file: String = #fileID, line: UInt = #line, function: String = #function) {
+    self.param = param
+    super.init(file: file, line: line, function: function)
+  }
+}

package/ios/Swift/Exceptions/UnexpectedException.swift

@@ -0,0 +1,16 @@
+// Copyright 2022-present 650 Industries. All rights reserved.
+
+/**
+ Exception wrapper used to handle unexpected internal native errors.
+ */
+public class UnexpectedException: Exception {
+  private let errorDescription: String
+
+  public init(_ error: Error) {
+    self.errorDescription = error.localizedDescription
+  }
+
+  public override var reason: String {
+    return errorDescription
+  }
+}

package/ios/Swift/Functions/AnyFunction.swift

@@ -24,10 +24,15 @@ public protocol AnyFunction: AnyDefinition {
    */
   var queue: DispatchQueue? { get }
 
+  /**
+   Whether the function needs to be called asynchronously from JavaScript.
+   */
+  var isAsync: Bool { get }
+
   /**
    Calls the function on given module with arguments and a promise.
    */
-  func call(args: [Any], promise: Promise) -> Void
+  func call(args: [Any], promise: Promise)
 
   /**
    Synchronously calls the function with given arguments. If the function takes a promise,
@@ -39,4 +44,9 @@ public protocol AnyFunction: AnyDefinition {
    Specifies on which queue the function should run.
    */
   func runOnQueue(_ queue: DispatchQueue?) -> Self
+
+  /**
+   Makes the JavaScript function synchronous.
+   */
+  func runSynchronously() -> Self
 }

package/ios/Swift/Functions/AsyncFunction.swift

@@ -0,0 +1,17 @@
+// Copyright 2022-present 650 Industries. All rights reserved.
+
+/**
+ Represents a function that can only be called asynchronously, thus its JavaScript equivalent returns a Promise.
+
+ - ToDo: Move some asynchronous logic from `ConcreteFunction` (like `call(args:promise:)`) to this class and drop the `isAsync` property.
+ */
+public final class AsyncFunction<Args, ReturnType>: ConcreteFunction<Args, ReturnType> {
+  override init(
+    _ name: String,
+    argTypes: [AnyArgumentType],
+    _ closure: @escaping ConcreteFunction<Args, ReturnType>.ClosureType
+  ) {
+    super.init(name, argTypes: argTypes, closure)
+    self.isAsync = true
+  }
+}