react-native-nitro-modules 0.4.0 → 0.5.0

package/NitroModules.podspec

@@ -37,7 +37,9 @@ Pod::Spec.new do |s|
     "cpp/utils/NitroHash.hpp",
     "cpp/utils/NitroDefines.hpp",
     # Public iOS-specific headers that will be exposed in modulemap (for Swift)
-    "ios/core/HybridContext.hpp"
+    "ios/core/ArrayBufferHolder.hpp",
+    "ios/core/PromiseHolder.hpp",
+    "ios/core/HybridContext.hpp",
   ]
 
   s.pod_target_xcconfig = {

package/README.md

@@ -111,67 +111,98 @@ The following C++ / JS types are supported out of the box:
   <tr>
     <th>JS Type</th>
     <th>C++ Type</th>
+    <th>Swift Type</th>
   </tr>
 
   <tr>
     <td><code>number</code></td>
     <td><code>double</code> / <code>int</code> / <code>float</code></td>
+    <td><code>Double</code> / <code>Int</code> / <code>Float</code></td>
   </tr>
   <tr>
     <td><code>boolean</code></td>
     <td><code>bool</code></td>
+    <td><code>Bool</code></td>
   </tr>
   <tr>
     <td><code>string</code></td>
     <td><code>std::string</code></td>
+    <td><code>String</code></td>
   </tr>
   <tr>
     <td><code>bigint</code></td>
     <td><code>int64_t</code> / <code>uint64_t</code></td>
+    <td><code>Int64</code> / <code>UInt64</code></td>
   </tr>
   <tr>
     <td><code>T[]</code></td>
     <td><code>std::vector&lt;T&gt;</code></td>
+    <td><code>[T]</code></td>
   </tr>
   <tr>
     <td><code>[A, B, C, ...]</code></td>
     <td><code>std::tuple&lt;A, B, C, ...&gt;</code></td>
+    <td><code>(A, B, C)</code></td>
   </tr>
   <tr>
     <td><code>A | B | C | ...</code></td>
     <td><code>std::variant&lt;A, B, C, ...&gt;</code></td>
+    <td><code>Variant_A_B_C</code></td>
   </tr>
   <tr>
     <td><code>Record&lt;string, T&gt;</code></td>
     <td><code>std::unordered_map&lt;std::string, T&gt;</code></td>
+    <td><code>Dictionary&lt;String, T&gt;</code></td>
   </tr>
   <tr>
     <td><code>T?</code></td>
     <td><code>std::optional&lt;T&gt;</code></td>
+    <td><code>T?</code></td>
   </tr>
   <tr>
     <td><code>Promise&lt;T&gt;</code></td>
     <td><code>std::future&lt;T&gt;</code></td>
+    <td><code><a href="./ios/core/Promise.swift">Promise&lt;T&gt;</a></code></td>
   </tr>
   <tr>
     <td><code>(TArgs...) =&gt; void</code></td>
     <td><code>std::function&lt;void (TArgs...)&gt;</code></td>
+    <td><code>@escaping (TArgs...) -&gt; Void</code></td>
   </tr>
   <tr>
     <td><code>(TArgs...) =&gt; TReturn</code></td>
     <td><code>std::function&lt;std::future&lt;TReturn&gt; (TArgs...)&gt;</code></td>
+    <td>❌</td>
   </tr>
   <tr>
     <td><code>{ ... }</code></td>
     <td><code>std::shared_ptr&lt;<a href="./cpp/core/AnyMap.hpp">AnyMap</a>&gt;</code></td>
+    <td>❌</td>
   </tr>
   <tr>
     <td><code>ArrayBuffer</code></td>
     <td><code>std::shared_ptr&lt;<a href="./cpp/core/ArrayBuffer.hpp">ArrayBuffer</a>&gt;</code></td>
+    <td><code><a href="./ios/core/ArrayBufferHolder.hpp">ArrayBufferHolder</a></code></td>
   </tr>
   <tr>
-    <td><code><a href="./src/HybridObject.ts">HybridObject</a></code></td>
+    <td>..any <code><a href="./src/HybridObject.ts">HybridObject</a></code></td>
     <td><code>std::shared_ptr&lt;<a href="./cpp/core/HybridObject.hpp">HybridObject</a>&gt;</code></td>
+    <td><code><a href="./ios/core/HybridObjectSpec.swift">HybridObjectSpec</a></code></td>
+  </tr>
+  <tr>
+    <td>..any <code>interface</code></td>
+    <td><code>T</code></td>
+    <td><code>T</code></td>
+  </tr>
+  <tr>
+    <td>..any <code>enum</code></td>
+    <td><code>T</code></td>
+    <td><code>T</code></td>
+  </tr>
+  <tr>
+    <td>..any <code>union</code></td>
+    <td><code>T</code></td>
+    <td><code>T</code></td>
   </tr>
 </table>
 

package/android/gradle.properties

@@ -2,4 +2,4 @@ Nitro_kotlinVersion=1.7.0
 Nitro_minSdkVersion=21
 Nitro_targetSdkVersion=31
 Nitro_compileSdkVersion=31
-Nitro_ndkversion=21.4.7075529
+Nitro_ndkVersion=21.4.7075529

package/cpp/core/ArrayBuffer.cpp

@@ -0,0 +1,88 @@
+//
+//  ArrayBuffer.cpp
+//  react-native-nitro
+//
+//  Created by Marc Rousavy on 14.07.24.
+//
+
+#include "ArrayBuffer.hpp"
+#include "OwningReference.hpp"
+#include <functional>
+#include <jsi/jsi.h>
+#include <thread>
+
+namespace margelo::nitro {
+
+using namespace facebook;
+
+// 1. ArrayBuffer
+
+std::shared_ptr<ArrayBuffer> ArrayBuffer::makeBuffer(uint8_t* data, size_t size, DeleteFn deleteFunc, void* deleteFuncContext) {
+  return std::make_shared<NativeArrayBuffer>(data, size, deleteFunc, deleteFuncContext);
+}
+
+// 2. NativeArrayBuffer
+
+NativeArrayBuffer::NativeArrayBuffer(uint8_t* data, size_t size, DeleteFn deleteFunc, void* deleteFuncContext)
+    : ArrayBuffer(), _data(data), _size(size), _deleteFunc(deleteFunc), _deleteFuncContext(deleteFuncContext) {}
+
+NativeArrayBuffer::~NativeArrayBuffer() {
+  if (_deleteFunc != nullptr) {
+    _deleteFunc(_deleteFuncContext);
+  }
+}
+
+uint8_t* NativeArrayBuffer::data() {
+  return _data;
+}
+
+size_t NativeArrayBuffer::size() const {
+  return _size;
+}
+
+bool NativeArrayBuffer::isOwner() const noexcept {
+  return _deleteFunc != nullptr;
+}
+
+// 3. JSArrayBuffer
+
+JSArrayBuffer::JSArrayBuffer(jsi::Runtime* runtime, OwningReference<jsi::ArrayBuffer> jsReference)
+    : ArrayBuffer(), _runtime(runtime), _jsReference(jsReference), _initialThreadId(std::this_thread::get_id()) {}
+
+JSArrayBuffer::~JSArrayBuffer() {}
+
+uint8_t* JSArrayBuffer::data() {
+  if (_initialThreadId != std::this_thread::get_id()) [[unlikely]] {
+    throw std::runtime_error("`data()` can only be accessed synchronously on the JS Thread! "
+                             "If you want to access it elsewhere, copy it first.");
+  }
+
+  OwningLock<jsi::ArrayBuffer> lock = _jsReference.lock();
+  if (!_jsReference) [[unlikely]] {
+    // JS Part has been deleted - data is now nullptr.
+    return nullptr;
+  }
+  // JS Part is still alive - we can assume that the jsi::Runtime is safe to access here too.
+  return _jsReference->data(*_runtime);
+}
+
+size_t JSArrayBuffer::size() const {
+  if (_initialThreadId != std::this_thread::get_id()) [[unlikely]] {
+    throw std::runtime_error("`size()` can only be accessed synchronously on the JS Thread! "
+                             "If you want to access it elsewhere, copy it first.");
+  }
+
+  OwningLock<jsi::ArrayBuffer> lock = _jsReference.lock();
+  if (!_jsReference) [[unlikely]] {
+    // JS Part has been deleted - size is now 0.
+    return 0;
+  }
+  // JS Part is still alive - we can assume that the jsi::Runtime is safe to access here too.
+  return _jsReference->size(*_runtime);
+}
+
+bool JSArrayBuffer::isOwner() const noexcept {
+  return false;
+}
+
+} // namespace margelo::nitro

package/cpp/core/ArrayBuffer.hpp

@@ -8,7 +8,6 @@
 #pragma once
 
 #include "OwningReference.hpp"
-#include <functional>
 #include <jsi/jsi.h>
 #include <thread>
 
@@ -16,9 +15,7 @@ namespace margelo::nitro {
 
 using namespace facebook;
 
-using DeleteFn = std::function<void(uint8_t*)>;
-
-static DeleteFn defaultDeleteFn = [](uint8_t* buffer) { delete[] buffer; };
+using DeleteFn = void (*)(void* context);
 
 /**
  * Represents a raw byte buffer that can be read from-, and
@@ -41,7 +38,7 @@ public:
   ArrayBuffer(const ArrayBuffer&) = delete;
   ArrayBuffer(ArrayBuffer&&) = delete;
   virtual ~ArrayBuffer() = default;
-
+  
 public:
   /**
    * Returns whether this `ArrayBuffer` is actually owning the data,
@@ -49,6 +46,13 @@ public:
    * memory that we didn't allocate, or from JS - which can be deleted at any point).
    */
   virtual bool isOwner() const noexcept = 0;
+  
+public:
+  /**
+   * Create a new `NativeArrayBuffer` that wraps the given data (without copy) of the given size,
+   * and calls `deleteFunc` with the given `deleteFuncContext` as a parameter in which `data` should be deleted.
+   */
+  static std::shared_ptr<ArrayBuffer> makeBuffer(uint8_t* data, size_t size, DeleteFn deleteFunc, void* deleteFuncContext);
 };
 
 /**
@@ -62,46 +66,31 @@ public:
  *
  * It is safe to access `data()` and `size()` from any Thread, but there are no synchronization/mutexes implemented by default.
  */
-class NativeArrayBuffer : public ArrayBuffer {
+class NativeArrayBuffer final : public ArrayBuffer {
 public:
   /**
    * Create a new **owning** `ArrayBuffer`.
    * The `ArrayBuffer` can be kept in memory, as C++ owns the data
-   * and will only delete it once this `ArrayBuffer` gets deleted
-   */
-  NativeArrayBuffer(uint8_t* data, size_t size, DeleteFn&& deleteFunc)
-      : ArrayBuffer(), _data(data), _size(size), _deleteFunc(std::move(deleteFunc)) {}
-  /**
-   * Create a new `ArrayBuffer`.
-   * If `destroyOnDeletion` is `true`, the `ArrayBuffer` is **owning**, otherwise it is **non-owning**.
-   * The `ArrayBuffer` can only be safely kept in memory if it is owning (`isOwning()`).
+   * and will only delete it once this `ArrayBuffer` gets deleted.
+   *
+   * Once this `ArrayBuffer` goes out of scope, `deleteFunc` will be called.
+   * The caller is responsible for deleting the memory (`data` and `deleteFuncContext`) here.
    */
-  NativeArrayBuffer(uint8_t* data, size_t size, bool destroyOnDeletion) : ArrayBuffer(), _data(data), _size(size) {
-    _deleteFunc = destroyOnDeletion ? defaultDeleteFn : nullptr;
-  }
-
-  ~NativeArrayBuffer() {
-    if (_deleteFunc != nullptr) {
-      _deleteFunc(_data);
-    }
-  }
+  NativeArrayBuffer(uint8_t* data, size_t size, DeleteFn deleteFunc, void* deleteFuncContext);
+  ~NativeArrayBuffer();
 
-  uint8_t* data() override {
-    return _data;
-  }
-
-  size_t size() const override {
-    return _size;
-  }
+public:
+  uint8_t* data() override;
+  size_t size() const override;
+  bool isOwner() const noexcept override;
 
-  bool isOwner() const noexcept override {
-    return _deleteFunc != nullptr;
-  }
+  double something();
 
 private:
   uint8_t* _data;
   size_t _size;
   DeleteFn _deleteFunc;
+  void* _deleteFuncContext;
 };
 
 /**
@@ -115,52 +104,24 @@ private:
  *
  * If the JS ArrayBuffer (or it's JS Runtime) have already been deleted, `data()` returns `nullptr`.
  */
-class JSArrayBuffer : public ArrayBuffer {
+class JSArrayBuffer final : public ArrayBuffer {
 public:
-  explicit JSArrayBuffer(jsi::Runtime* runtime, OwningReference<jsi::ArrayBuffer> jsReference)
-      : ArrayBuffer(), _runtime(runtime), _jsReference(jsReference), _initialThreadId(std::this_thread::get_id()) {}
-  ~JSArrayBuffer() {}
+  explicit JSArrayBuffer(jsi::Runtime* runtime, OwningReference<jsi::ArrayBuffer> jsReference);
+  ~JSArrayBuffer();
 
 public:
   /**
    * Gets the data this `ArrayBuffer` points to, or `nullptr` if it has already been deleted.
    */
-  uint8_t* data() override {
-    if (_initialThreadId != std::this_thread::get_id()) [[unlikely]] {
-      throw std::runtime_error("`data()` can only be accessed synchronously on the JS Thread! "
-                               "If you want to access it elsewhere, copy it first.");
-    }
-
-    OwningLock<jsi::ArrayBuffer> lock = _jsReference.lock();
-    if (!_jsReference) [[unlikely]] {
-      // JS Part has been deleted - data is now nullptr.
-      return nullptr;
-    }
-    // JS Part is still alive - we can assume that the jsi::Runtime is safe to access here too.
-    return _jsReference->data(*_runtime);
-  }
-
+  uint8_t* data() override;
   /**
    * Gets the size of the data this `ArrayBuffer` points to, or `0` if it has already been deleted.
    */
-  size_t size() const override {
-    if (_initialThreadId != std::this_thread::get_id()) [[unlikely]] {
-      throw std::runtime_error("`size()` can only be accessed synchronously on the JS Thread! "
-                               "If you want to access it elsewhere, copy it first.");
-    }
-
-    OwningLock<jsi::ArrayBuffer> lock = _jsReference.lock();
-    if (!_jsReference) [[unlikely]] {
-      // JS Part has been deleted - size is now 0.
-      return 0;
-    }
-    // JS Part is still alive - we can assume that the jsi::Runtime is safe to access here too.
-    return _jsReference->size(*_runtime);
-  }
-
-  bool isOwner() const noexcept override {
-    return false;
-  }
+  size_t size() const override;
+  /**
+   * Returns `false` for JS-based ArrayBuffers.
+   */
+  bool isOwner() const noexcept override;
 
 private:
   jsi::Runtime* _runtime;

package/cpp/jsi/JSIConverter+Function.hpp

@@ -67,9 +67,9 @@ struct JSIConverter<std::function<ReturnType(Args...)>> {
     };
   }
 
-  static inline jsi::Value toJSI(jsi::Runtime& runtime, std::function<ReturnType(Args...)>&& function) {
-    jsi::HostFunctionType jsFunction = [function = std::move(function)](jsi::Runtime& runtime, const jsi::Value& thisValue,
-                                                                        const jsi::Value* args, size_t count) -> jsi::Value {
+  static inline jsi::Value toJSI(jsi::Runtime& runtime, const std::function<ReturnType(Args...)>& function) {
+    jsi::HostFunctionType jsFunction = [function](jsi::Runtime& runtime, const jsi::Value& thisValue,
+                                                  const jsi::Value* args, size_t count) -> jsi::Value {
       if (count != sizeof...(Args)) [[unlikely]] {
         throw jsi::JSError(runtime, "Function expected " + std::to_string(sizeof...(Args)) + " arguments, but received " +
                                         std::to_string(count) + "!");

package/cpp/jsi/JSIConverter+Promise.hpp

@@ -7,7 +7,8 @@
 // Forward declare a few of the common types that might have cyclic includes.
 namespace margelo::nitro {
 class Dispatcher;
-class Promise;
+
+class JSPromise;
 
 template <typename T, typename Enable>
 struct JSIConverter;

package/ios/core/ArrayBufferHolder.hpp

@@ -0,0 +1,78 @@
+//
+//  ArrayBufferHolder.hpp
+//  react-native-nitro
+//
+//  Created by Marc Rousavy on 14.08.24.
+//
+
+#pragma once
+
+#include "ArrayBuffer.hpp"
+#include <swift/bridging>
+#include <memory>
+
+namespace margelo::nitro {
+
+using namespace facebook;
+
+/**
+ * Holds instances of `std::shared_ptr<ArrayBuffer>`.
+ * The reason this exists is because we cannot directly use `shared_ptr`,
+ * nor virtual functions (`jsi::MutableBuffer`) in Swift.
+ *
+ * Passing around instances of `ArrayBufferHolder` (or `std::shared_ptr<ArrayBuffer>`)
+ * does not involve any data copies and is almost zero-overhead - even when passed to JS.
+ */
+class ArrayBufferHolder {
+public:
+  ArrayBufferHolder(const std::shared_ptr<ArrayBuffer>& arrayBuffer) : _arrayBuffer(arrayBuffer) {}
+
+public:
+  /**
+   * Create a new `NativeArrayBuffer` that wraps the given data of the given size, without copying it.
+   *
+   * Once the `ArrayBuffer` is no longer in use, the given `deleteFunc` will be called with the given `deleteFuncContext`
+   * as an argument. The caller is responsible for deleting `data` (and `deleteFuncContext`) once this is called.
+   */
+  static ArrayBufferHolder makeBuffer(uint8_t* data, size_t size, DeleteFn deleteFunc, void* deleteFuncContext) {
+    auto arrayBuffer = ArrayBuffer::makeBuffer(data, size, deleteFunc, deleteFuncContext);
+    return ArrayBufferHolder(arrayBuffer);
+  }
+
+public:
+  /**
+   * Gets the raw bytes the underlying `ArrayBuffer` points to.
+   */
+  void* getData() const SWIFT_COMPUTED_PROPERTY {
+    return _arrayBuffer->data();
+  }
+  /**
+   * Gets the size of the raw bytes the underlying `ArrayBuffer` points to.
+   */
+  size_t getSize() const SWIFT_COMPUTED_PROPERTY {
+    return _arrayBuffer->size();
+  }
+
+  /**
+   * Whether the underlying `ArrayBuffer` actually owns the data it points to, or not.
+   *
+   * - If an `ArrayBuffer` owns the data, it is likely an ArrayBuffer created on the native side (C++/Swift).
+   *   This means the `ArrayBuffer` is safe to access as long as you have a reference to it, and cannot be deleted otherwise.
+   * - If an `ArrayBuffer` doesn't own the data, it is likely an ArrayBuffer coming from JS.
+   *   This means the `ArrayBuffer` is **NOT** safe to access outside of the synchronous function's scope.
+   *   If you plan on hopping do a different Thread, or storing a long-lived reference to it, make sure to **copy** the data.
+   */
+  bool getIsOwner() const SWIFT_COMPUTED_PROPERTY {
+    return _arrayBuffer->isOwner();
+  }
+
+public:
+  inline std::shared_ptr<ArrayBuffer> getArrayBuffer() const {
+    return _arrayBuffer;
+  }
+
+private:
+  std::shared_ptr<ArrayBuffer> _arrayBuffer;
+};
+
+} // namespace margelo::nitro

package/ios/core/ArrayBufferHolder.swift

@@ -0,0 +1,48 @@
+//
+//  ArrayBufferHolder.swift
+//  NitroModules
+//
+//  Created by Marc Rousavy on 17.07.24.
+//
+
+import Foundation
+
+/**
+ * Holds instances of `std::shared_ptr<ArrayBuffer>`, which can be passed
+ * between native and JS **without copy**.
+ *
+ * See `data`, `size` and `isOwning`.
+ */
+public typealias ArrayBufferHolder = margelo.nitro.ArrayBufferHolder
+
+public extension ArrayBufferHolder {
+  /**
+   * Create a new `ArrayBufferHolder` that wraps the given `data` of the given `size`
+   * without performing a copy.
+   * When the `ArrayBuffer` is no longer used, `onDelete` will be called, in which
+   * you as a caller are responsible for deleting `data`.
+   */
+  static func wrap(dataWithoutCopy data: UnsafeMutablePointer<UInt8>,
+                   size: Int,
+                   onDelete delete: @escaping () -> Void) -> ArrayBufferHolder {
+    // Convert escaping Swift closure to a `void*`
+    let (wrappedClosure, context) = ClosureWrapper.wrap(closure: delete)
+    // Create ArrayBufferHolder with our wrapped Swift closure to make it callable as a C-function pointer
+    return ArrayBufferHolder.makeBuffer(data, size, wrappedClosure, context)
+  }
+  
+  /**
+   * Allocate a new buffer of the given `size`.
+   * If `initializeToZero` is `true`, all bytes are set to `0`, otherwise they are left untouched.
+   */
+  static func allocate(size: Int, initializeToZero: Bool = false) -> ArrayBufferHolder {
+    let data = UnsafeMutablePointer<UInt8>.allocate(capacity: size)
+    if initializeToZero {
+      data.initialize(repeating: 0, count: size)
+    }
+    
+    return ArrayBufferHolder.makeBuffer(data, size, { data in
+      data?.deallocate()
+    }, data)
+  }
+}

package/ios/core/Promise.swift

@@ -0,0 +1,162 @@
+//
+//  Promise.swift
+//  NitroModules
+//
+//  Created by Marc Rousavy on 15.08.24.
+//
+
+import Foundation
+
+/**
+ * Represents a Promise that can be passed to JS.
+ *
+ * Create a new Promise with the following APIs:
+ * - `Promise<T>.async { ... }` - Creates a new Promise that runs the given code in a Swift `async`/`await` Task.
+ * - `Promise<T>.parallel { ... }` - Creates a new Promise that runs the given code in a parallel `DispatchQueue`.
+ * - `Promise<T>.resolved(withResult:)` - Creates a new already resolved Promise.
+ * - `Promise<T>.rejected(withError:)` - Creates a new already rejected Promise.
+ * - `Promise<T>()` - Creates a new Promise with fully manual control over the `resolve(..)`/`reject(..)` functions.
+ */
+public class Promise<T> {
+  private enum State {
+    case result(T)
+    case error(Error)
+  }
+  
+  private var state: State?
+  private var onResolvedListeners: [(T) -> Void] = []
+  private var onRejectedListeners: [(Error) -> Void] = []
+  
+  /**
+   * Create a new pending Promise.
+   * It can (and must) be resolved **or** rejected later.
+   */
+  public init() {
+    state = nil
+  }
+  
+  deinit {
+    if state == nil {
+      print("⚠️ Promise<\(String(describing: T.self))> got destroyed, but was never resolved or rejected! It is probably left hanging in JS now.")
+    }
+  }
+  
+  /**
+   * Resolves this `Promise<T>` with the given `T` and notifies all listeners.
+   */
+  public func resolve(withResult result: T) {
+    guard state == nil else {
+      fatalError("Failed to resolve promise with \(result) - it has already been resolved or rejected!")
+    }
+    state = .result(result)
+    onResolvedListeners.forEach { listener in listener(result) }
+  }
+  
+  /**
+   * Rejects this `Promise<T>` with the given `Error` and notifies all listeners.
+   */
+  public func reject(withError error: Error) {
+    guard state == nil else {
+      fatalError("Failed to reject promise with \(error) - it has already been resolved or rejected!")
+    }
+    state = .error(error)
+    onRejectedListeners.forEach { listener in listener(error) }
+  }
+}
+
+/**
+ * Extensions to easily create new Promises.
+ */
+extension Promise {
+  /**
+   * Create a new `Promise<T>` already resolved with the given `T`.
+   */
+  public static func resolved(withResult result: T) -> Promise {
+    let promise = Promise()
+    promise.state = .result(result)
+    return promise
+  }
+  
+  /**
+   * Create a new `Promise<T>` already rejected with the given `Error`.
+   */
+  public static func rejected(withError error: Error) -> Promise {
+    let promise = Promise()
+    promise.state = .error(error)
+    return promise
+  }
+  
+  /**
+   * Create a new `Promise<T>` that runs the given `async` code in a `Task`.
+   * This does not necessarily run the code in a different Thread, but supports Swift's `async`/`await`.
+   */
+  public static func `async`(_ priority: TaskPriority? = nil,
+                             _ run: @escaping () async throws -> T) -> Promise {
+    let promise = Promise()
+    Task(priority: priority) {
+      do {
+        let result = try await run()
+        promise.resolve(withResult: result)
+      } catch {
+        promise.reject(withError: error)
+      }
+    }
+    return promise
+  }
+  
+  /**
+   * Create a new `Promise<T>` that runs the given `run` function on a parallel Thread/`DispatchQueue`.
+   */
+  public static func parallel(_ queue: DispatchQueue = .global(),
+                              _ run: @escaping () throws -> T) -> Promise {
+    let promise = Promise()
+    queue.async {
+      do {
+        let result = try run()
+        promise.resolve(withResult: result)
+      } catch {
+        promise.reject(withError: error)
+      }
+    }
+    return promise
+  }
+}
+
+/**
+ * Extensions to support then/catch syntax.
+ */
+extension Promise {
+  /**
+   * Add a continuation listener to this `Promise<T>`.
+   * Once the `Promise<T>` resolves, the `onResolvedListener` will be called.
+   */
+  @discardableResult
+  public func then(_ onResolvedListener: @escaping (T) -> Void) -> Promise {
+    switch state {
+    case .result(let result):
+      onResolvedListener(result)
+      break
+    default:
+      onResolvedListeners.append(onResolvedListener)
+      break
+    }
+    return self
+  }
+  
+  /**
+   * Add an error continuation listener to this `Promise<T>`.
+   * Once the `Promise<T>` rejects, the `onRejectedListener` will be called with the error.
+   */
+  @discardableResult
+  public func `catch`(_ onRejectedListener: @escaping (Error) -> Void) -> Promise {
+    switch state {
+    case .error(let error):
+      onRejectedListener(error)
+      break
+    default:
+      onRejectedListeners.append(onRejectedListener)
+      break
+    }
+    return self
+  }
+}