Skip to content

Commit 1ced505

Browse files
committed
Update README
1 parent 6d0f4de commit 1ced505

File tree

2 files changed

+256
-178
lines changed

2 files changed

+256
-178
lines changed

README.md

Lines changed: 122 additions & 85 deletions
Original file line numberDiff line numberDiff line change
@@ -86,7 +86,12 @@ class Foo {
8686
}
8787
}
8888

89-
//// some custom types or functions...
89+
// Some functions or types customised by **you**...
90+
// They are not included in the runtime.
91+
// Since there are a lot of restrictions on the use of various types in WasmJS...
92+
// so I'm not sure how to handle them perfectly yet.
93+
// Until then, you can customise functions and types to control the behaviour of the compiler plugin yourself.
94+
// just like you can customise other platforms.
9095

9196
fun <T> runInAsync(block: suspend () -> T): AsyncResult<T> = AsyncResult(block)
9297

@@ -108,7 +113,7 @@ class Foo {
108113
}
109114
@Api4Js // RequiresOptIn annotation, provide warnings to Kotlin
110115
fun waitAndGetAsync(): AsyncResult<String> = runInAsync { waitAndGet() } // 'runInAsync' from the runtime provided by the plugin
111-
// AsyncResult is a custom type
116+
// AsyncResult is a custom type by **you**
112117
}
113118
```
114119

@@ -117,9 +122,6 @@ class Foo {
117122

118123
**Using the [plugins DSL](https://docs.gradle.org/current/userguide/plugins.html#sec:plugins_block):**
119124

120-
<details open>
121-
<summary>Kotlin</summary>
122-
123125
_build.gradle.kts_
124126

125127
```kotlin
@@ -135,50 +137,55 @@ plugins {
135137
suspendTransform {
136138
enabled = true // default: true
137139
includeRuntime = true // default: true
140+
includeAnnotation = true // default: true
141+
142+
/*
143+
* Use both `useJvmDefault` and `useJsDefault`.
144+
* Need to include the runtime and annotation.
145+
*/
146+
// useDefault()
147+
148+
/*
149+
* Use the default configuration for JVM platform,
150+
* Equivalent:
151+
* addJvmTransformers(
152+
* SuspendTransformConfiguration.jvmBlockingTransformer,
153+
* SuspendTransformConfiguration.jvmAsyncTransformer,
154+
* )
155+
*
156+
* Need to include the runtime and annotation.
157+
*/
158+
useJvmDefault()
159+
160+
// or custom by yourself
138161
jvm {
139162
// ...
140163
}
164+
// or
165+
addJvmTransformers(...)
166+
167+
/*
168+
* Use the default configuration for JS platform,
169+
* Equivalent:
170+
* addJvmTransformers(
171+
* SuspendTransformConfiguration.jsPromiseTransformer,
172+
* )
173+
*
174+
* Need to include the runtime and annotation.
175+
*/
176+
useJsDefault()
177+
178+
// or custom by yourself
141179
js {
142180
// ...
143181
}
182+
// or
183+
addJsTransformers(...)
144184
}
145185
```
146186

147-
</details>
148-
149-
<details>
150-
<summary>Groovy</summary>
151-
152-
_build.gradle_
153-
154-
```groovy
155-
plugins {
156-
id "org.jetbrains.kotlin.jvm" version "$KOTLIN_VERSION" // or js? or multiplatform?
157-
id "love.forte.plugin.suspend-transform" version "$PLUGIN_VERSION"
158-
// other...
159-
}
160-
161-
// other...
162-
163-
// config it.
164-
suspendTransform {
165-
enabled = true // default: true
166-
includeRuntime = true // default: true
167-
168-
// or custom transformers
169-
transformers = listOf(...)
170-
}
171-
```
172-
173-
</details>
174-
175-
176-
177187
**Using [legacy plugin application](https://docs.gradle.org/current/userguide/plugins.html#sec:old_plugin_application):**
178188

179-
<details open>
180-
<summary>Kotlin</summary>
181-
182189
_build.gradle.kts_
183190

184191
```kotlin
@@ -204,55 +211,53 @@ plugins {
204211
suspendTransform {
205212
enabled = true // default: true
206213
includeRuntime = true // default: true
207-
useDefault()
208-
209-
// or custom transformers
210-
transformers = listOf(...)
211-
}
212-
```
213-
214-
</details>
215-
216-
<details>
217-
<summary>Groovy</summary>
218-
219-
_build.gradle_
220-
221-
```groovy
222-
buildscript {
223-
repositories {
224-
maven {
225-
url "https://plugins.gradle.org/m2/"
226-
}
214+
includeAnnotation = true // default: true
215+
216+
/*
217+
* Use both `useJvmDefault` and `useJsDefault`.
218+
* Need to include the runtime and annotation.
219+
*/
220+
// useDefault()
221+
222+
/*
223+
* Use the default configuration for JVM platform,
224+
* Equivalent:
225+
* addJvmTransformers(
226+
* SuspendTransformConfiguration.jvmBlockingTransformer,
227+
* SuspendTransformConfiguration.jvmAsyncTransformer,
228+
* )
229+
*
230+
* Need to include the runtime and annotation.
231+
*/
232+
useJvmDefault()
233+
234+
// or custom by yourself
235+
jvm {
236+
// ...
227237
}
228-
dependencies {
229-
classpath "love.forte.plugin.suspend-transform:suspend-transform-plugin-gradle:$VERSION"
238+
// or
239+
addJvmTransformers(...)
240+
241+
/*
242+
* Use the default configuration for JS platform,
243+
* Equivalent:
244+
* addJvmTransformers(
245+
* SuspendTransformConfiguration.jsPromiseTransformer,
246+
* )
247+
*
248+
* Need to include the runtime and annotation.
249+
*/
250+
useJsDefault()
251+
252+
// or custom by yourself
253+
js {
254+
// ...
230255
}
231-
}
232-
233-
234-
235-
plugins {
236-
id "org.jetbrains.kotlin.jvm" // or js? or multiplatform?
237-
id "love.forte.plugin.suspend-transform"
238-
// other...
239-
}
240-
241-
// other...
242-
243-
// config it.
244-
suspendTransform {
245-
enabled = true // default: true
246-
includeRuntime = true // default: true
247-
useDefault()
248-
249-
// or custom transformers
250-
transformers = listOf(...)
256+
// or
257+
addJsTransformers(...)
251258
}
252259
```
253260

254-
</details>
255-
256261
## Cautions
257262

258263
### Gradle JVM
@@ -266,6 +271,41 @@ K2 is supported since `v0.7.0`.
266271
> [!warning]
267272
> In experiments.
268273
274+
### JsExport
275+
276+
If you want to use `@JsExport` with default configuration in JS,
277+
try this:
278+
279+
_build.gradle.kts_
280+
281+
```kotlin
282+
plugins {
283+
...
284+
}
285+
286+
suspendTransform {
287+
addJsTransformers(
288+
SuspendTransformConfiguration.jsPromiseTransformer.copy(
289+
copyAnnotationExcludes = listOf(
290+
// The generated function does not include `@JsExport.Ignore`.
291+
ClassInfo("kotlin.js", "JsExport.Ignore")
292+
)
293+
)
294+
)
295+
}
296+
```
297+
298+
```Kotlin
299+
@file:OptIn(ExperimentalJsExport::class)
300+
301+
@JsExport
302+
class Foo {
303+
@JsPromise
304+
@JsExport.Ignore
305+
suspend fun run(): Int = ...
306+
}
307+
```
308+
269309
## Effect
270310

271311
**source:**
@@ -475,9 +515,6 @@ suspendTransform {
475515
}
476516
```
477517

478-
## Useful Links
479-
[Kotlin Suspend Interface reversal](https://github.com/ForteScarlet/kotlin-suspend-interface-reversal)
480-
: Generate platform-compatible extension types for interfaces or abstract classes that contain suspend functions, based on KSP.
481518

482519
## License
483520

0 commit comments

Comments
 (0)