# Dart js_interop 初探 (Dart 3.4)

[TOC]

## 💡 起因動機

### 專案內的套件
原先，專案內使用了一個名為 `flutter_web3` 的套件，我需要針對套件內的class `Log` 做一系列的邏輯處理，我先是寫了一個test ，後來要mock 該class 時，發現


`Log` 具有某個 private class 的泛型，並且繼承於 Interop class (如上圖)，而該 private class (如下圖) 是一個和JS 互動的class


這裡有個問題： `Log` class 可以被mock 嗎?

- 可以，但 `_LogImpl` 會被略過，沒有辦法被測試到

有甚麼方法是，**既可以測試到這個與JS 互動的介面，又可以測試到Dart 端的class model 的呢?**

### 官方文件內的技術內容
我參考了[js interop 的dart 官方文件](https://dart.dev/interop/js-interop)，裡面的[Mock 章節](https://dart.dev/interop/js-interop/mock)提到了
- 使用 extension type，加上
- 使用 `@JSExport()`
- 使用`createJSInteropWrapper()`

的組合拳，就可以達到測試 JS 介面和Dart class model 的需求。

// The Dart class must have `@JSExport` on it or at least one of its instance
// members.
@JSExport()
class FakeCounter {
  int value = 0;
  @JSExport('increment')
  void renamedIncrement() {
    value++;
  }
  void decrement() {
    value--;
  }
}

extension type Counter(JSObject _) implements JSObject {
  external int value;
  external void increment();
  void decrement() {
    value -= 2;
  }
}

void main() {
  var fakeCounter = FakeCounter();
  // Returns a JS object whose properties call the relevant instance members in
  // `fakeCounter`.
  var counter = createJSInteropWrapper<FakeCounter>(fakeCounter) as Counter;
  // Calls `FakeCounter.value`.
  expect(counter.value, 0);
  // `FakeCounter.renamedIncrement` is renamed to `increment`, so it gets
  // called.
  counter.increment();
  expect(counter.value, 1);
  expect(fakeCounter.value, 1);
   // Changes in the fake affect the wrapper and vice-versa.
  fakeCounter.value = 0;
  expect(counter.value, 0);
  counter.decrement();
  // Because `Counter.decrement` is non-`external`, we never called
  // `FakeCounter.decrement`.
  expect(counter.value, -2);
}

問題越來越多，甚麼是extension type，然後這些 annotaion 跟 method 是怎麼回事？

## 🔬 研究 Dart JS Interoperability

最根本的問題，Dart 是如何和 JS 互相溝通的呢？這裡就以[Usage](https://dart.dev/interop/js-interop/usage)的解釋來說明：

> To call and receive JS values from this API, you use external interop members. In order to construct and provide types for JS values, you use and declare interop types, which also contain interop members. To pass Dart values like Lists or Function to interop members or convert from JS values to Dart values, you use conversion functions unless the interop member contains a primitive type.

1. 要call JS Function 或是取得JS 的值的話，用 `external` 關鍵字
2. 要建構和提供JS 值的型別，用 interop type 來宣告
3. 要從Dart 傳List 或是Function 給JS，而其型別為原始型別(int, String, bool ...) 的話，用conversion function

### 基礎型別
對於基礎型別，`external` 關鍵字的用法如下，用法不難

// javascript
 
// 等同於 var name = 'global'
globalThis.name = 'global'; 

// 等同於
// function isNameEmpty() {
//     return name.length == 0;
// }
globalThis.isNameEmpty = function() {
  return globalThis.name.length == 0;
}

// Dart

@JS()
external String get name;

@JS('name')  // 對應到javascript 的變數名稱
external String get jsName;

@JS()
external set name(String value);

@JS()
external bool isNameEmpty();

### Async Function

若要JS 使用非同步Function，特別注意JS 的型別是interop type，在Dart 操作時需要轉換成dart type

// javascript

function resolveAfter2Seconds() {
    return new Promise((resolve) => {
        setTimeout(() => {
            resolve('resolved after 2 sec');
        }, 2000);
    });
}

async function asyncCall() {
    const result = await resolveAfter2Seconds();
    return result;
}

//dart

@JS()
external JSPromise<JSString> asyncCall();

final jsResult = await asyncCall();
print(jsResult.toDart) // resolved after 2 sec

### Callback Function、Function w/ arguments

若需要使用callback，例如當 JS 處理完後，對Dart 呼叫callback 並放入參數。

// javascript

function heavyWork(onWorkDone){
    var status = 0;
    // ... do some heavy things
    status = 1;
    console.log('Heavy work finished on JS');
    onWorkDone.call(this, status);
}

// dart

@JS('heavyWork')
external void jsHeavyWork(ExternalDartReference onDone);

void onDone(int statusCode){
    print('JS callback');
    print('status code: $statusCode');
}

jsHeavyWork(onDone.toJS.toExternalReference);

// Heavy work finished on JS
// JS callback
// status code: 1

Dart 的Callback function 需要被包裝成 `ExternalDartReference` 物件，而這個物件就只是Dart 的一個參照，但是要成為參照之前，需要
1. 先把function 變成 `JSExportedDartFunction` (`.toJS`)
2. 再轉換成`ExternalDartReference` (`.toExternalReference`)
::: info
如果 function 沒有先轉成`JSExportedDartFunction`
直接轉成 `ExternalDartReference` ，而被JS 調用的話
會出現下面的錯誤

Dart function requires `allowInterop` to be passed to JavaScript.
:::

---
### Interop Type & Extension type

但如果今天要取得的不是原始型別，我們可以用 JS type，或是用 extension type 來包裝型別。

JS Type (正式名稱為 interop type) 是 Dart 用來宣告 JS 來的型別，下面是和 Dart type 的對應表


而 extension type 則是除此之外、自定義的type或是class。對我而言，extension type 很像是Dart 用來描述型別的interface，而正好他在[文件](https://dart.dev/language/extension-types)的第一行也是這麼描述的
> An extension type is a compile-time abstraction that "wraps" an existing type with a different, static-only interface.

既然extension type 是拿來描述型別的介面，那也可以很自然的拿來描述JS interop 的型別。可以從原始檔內找到官方的定義方式。




---
### Extension type 實作

所以話說回來，當我們需要自定義一個來自JS 的結構，我們可以用 extension type 來實現。例如有個名為Empolyee 的JS class：

// javascript

class Employee{
    constructor(name, id, department){
        this._name = name;
        this._id = id;
        this._department = department;
        this._label = `Name: ${name}, id: ${id}`;
        this._greeting = `${name} says hello from JS`
    }
    // ...setter getter of the class members
}

class Department{
    constructor(name){
        this._name = name;
    }
    // ...setter getter of the class members
}

const depRD = new Department('RD');
const employee = new Employee('John', 1, depSE);

// dart

extension type Employee._(JSObject _) implements JSObject{
    external Employee(String name, int id, Department department);
    
    external String name;
    external int id;
    
    @JS('label')
    external String get jsLabel;
    
    external Department department;
    
    @JS('greeting') // @JS() 可以用來區別JavaScript 和Dart 的Function
    external String get greetingJS;
    
    String get greeting => "$name says hello from Dart";
}

extension type Department._(JSObject _) implements JSObject{
    external String name;
}

@JS('employee')
external Employee employeeJS;
    
print(employeeJS.name) // John
print(employeeJS.id) // 1
print(employeeJS.department.name) // RD
print(employeeJS.label) // Name: John, id: 1
    
print(employeeJS.greeting) // John says hello from Dart
print(employeeJS.greetingJS) // John says hello from JS

## 🕵🏼‍♂️ 檢視問題

### 問題重述
研究的 extension type 和 annotation 已經解釋的差不多了，再回來看看問題

**如何既可以測試到這個與JS 互動的介面，又可以測試到Dart 端的class model 的呢?**

這個問題經上述的研究後，可以知道 extension type 就是Dart 和JS 互動的介面結構，可以把問題換成：

**如何 mock JS 的 extension type？**

很幸運的，官方也提供了這樣的[文件](https://dart.dev/interop/js-interop/mock)，文件中提到

> Mocking classes in Dart is usually done through overriding instance members. However, since extension types are used to declare interop types, all extension type members are dispatched statically and therefore overriding can't be used. This limitation is true for extension members as well, and therefore instance extension type or extension members can't be mocked.
>
> While this applies to any non-external extension type member, external interop members are special as they invoke members on a JS value.
> ...
> Therefore, by using a different JSObject, a different implementation of getDay can be called.

簡單翻譯一下
大概就是說 extension type 是靜態分配的(在 compile time 就被定義，所以才能做型別的靜態分析)，所以沒辦法使用Override，且這個規則也套用於 extension type 的 member，也就是沒辦法被mock。
但是很湊巧的，因為 external member 會調用 JS 的值，所以當我提供了不一樣的`JSObject`，不一樣的 function 就會被呼叫，也就自然的達到mock 的目的。

所以我們可以再把問題重新敘述成：

**如何讓 extension type 可以使用被 mock 出的 JS 物件？**

文件中說有兩個關鍵的元件，`@JSExport()` 和 `createJSInteropWrapper()`

### @JSExport()
`@JSExport()` 的功能是讓 `createJSInteropWrapper()` 把 Dart class 或是其member 包裝成 `JSObject`，也就是標記讓哪個 class 或是 member 變成 JS 的物件。

### createJSInteropWrapper()
將Dart class 或是其member 包裝成 JS 物件的方法。就這麼簡單。

// dart 

@JSExport() // 把 FakeCounter 整個class 包裝成JSObject
class FakeCounter {
  int value = 0;
  @JSExport('increment') // 對應到 extension type 內的 member 名稱
  void renamedIncrement() {
    value++;
  }
  void decrement() {
    value--;
  }
}

var fakeCounter = FakeCounter();
// counter 是
var counter = createJSInteropWrapper<FakeCounter>(fakeCounter) as Counter;

expect(counter.value, 0);
counter.increment();
expect(counter.value, 1);

## 🏁 最後

研究出來後，`flutter_web3` 可以測試成功嗎？答案是 短時間內不行，原因是

- 執行測試時，該套件內有多處 import `dart:js`，而Dart VM 內並沒有 js 套件可以使用，會出現 `Dart library 'dart:js_interop' is not available on this platform` 的錯誤。
- 若把 `dart:js` 換成 `dart:js_interop`，就得改寫套件內所有舊API 寫法，要改非常多地方...