Enhances API contracts for JavaScript clients by generating JS-friendly functions and class constructors. Enables passing arguments via destructured objects, improving code readability and reducing bugs.
At Philo, as we look to leverage Kotlin Multiplatform, this plugin has helped provide nicer API contracts for our JS based clients, with friendlier methods and class constructors.
Consider the following function definition below. Generally, arguments are resolved based on their position in the function. However, in Kotlin, functions support named arguments, which allow the consumer of a function to specify the names of the input arguments.
fun myCoolFunction(number: Int, isValid: Boolean, username: String) { }
// Arguments resolved by order
myCoolFunction(8, true, "philo-user")
// Using named arguments
myCoolFunction(number = 9, username = "philo-user", isValid = true)
These named arguments ensure the consumer has control over what is passed to the function, makes the code more readable, and prevents bugs if arguments are reordered, have the same types, etc.
Javascript does not support named arguments; however, the conventional way to pass arguments to functions/constructors is through a destructured arguments object, often anonymous, that contains all of the desired inputs. For example,
function myCoolFunctionJs({number, isValid, username}) { }
// Arguments destructured in input object
myCoolFunctionJs({ number: 7, isValid: true, username: "js-user" })
By default, when exporting a KMP library to JS, there is no support for passing arguments as a destructured object, and as a result, JS consumers of functions are required to call the functions based on positional ordering. While this works, it is a bit cumbersome, especially as function inputs grow. Thus, there is a use case to generate JS functions/class constructors that support invocation via plain objects.
In order to support this JS/TS style invocation, a Kotlin external interface that contains the arguments as members is needed. Additionally, a new function is needed that accepts this interface, essentially as an overload of the original. This code could then be exported to JS using the JsExport annotation.
In the previous myCoolFunction example, the required Kotlin code to generate the JS functions we want would look like:
@JsExport
external interface MyCoolFunctionArgs {
val number: Int
val isValid: Boolean
val username: String
}
/**
* This function accepts the interface as the arguments and then maps
* them to the correct input for the original function
*/
@JsExport
fun myCoolFunctionWrapper {
myCoolFunction(
number = args.number,
isValid = args.isValid,
username = args.username
)
}
With this exported Kotlin code, the Javascript functions and Typescript types would be created such that the Javascript consumers can call this function in the idiomatic JS way:
// Call functioning using the specific function for argument passing
myCoolFunctionWrapper({
number: 8,
isValid: true,
username: "philo-user"
})
In order to turn all of our KMP functions and classes into JS friendly versions as described above, the @JsNamedArgs annotation has been created to automatically generate and export the required code. Simply add the annotation to any functions or classes that you'd like to create the new functions for.
@JsNamedArgs
@JsExport
fun myCoolFunction(number: Int, isValid: Boolean, username: String) { }
Note: The @JsExport annotation is also required in order for the generated method to be exported as well.
When used on top level functions, new Wrapper functions are created for use in JS
@JsNamedArgs
@JsExport
fun myCoolFunction(number: Int, isValid: Boolean, username: String) { }
// Example JS usage
myCoolFunctionWrapper({
number: 8,
isValid: true,
username: "philo-user"
})
When used on top level classes, new create...Wrapper functions are created for use in JS
@JsNamedArgs
@JsExport
data class MyCoolData(val id: Int, val name: String)
// Example JS usage
const data = createMyCoolDataWrapper({
id: 10,
name: "Pam Beasley"
})
When used on top level class that have public methods, new <Class-Name>Wrapper functions are created for use in JS as well. They vary slightly from top level functions with their use in JS.
@JsNamedArgs
@JsExport
class MyCoolData(val id: Int, val name: String) {
fun updateInfo(id: Int, name: String) { }
}
// Example JS usage - first create object
const data = createMyCoolDataWrapper({
id: 10,
name: "Pam Beasley"
})
// Now use member wrapper with object, and then the function arguments
updateInfoMyCoolDataWrapper(data, {
id: 10,
name: "Erin Hannon"
})
JsExport annotation, and any classes referenced in the arguments of the functions should also be exported.In order to build an application using the @JsNamedArgs annotation, the application must also install the KSP plugin in the build.gradle.kts
plugins {
kotlin("multiplatform")
id("com.google.devtools.ksp") version <kspVersion> // See gradle.properties for latest version used
}
With the KSP plugin installed, you will then have to define the dependencies to these libraries in the app/build.gradle.kts files and enable the compiler plugin when doing JS builds
repositories {
mavenCentral()
}
kotlin {
sourceSets {
commonMain.dependencies {
dependencies {
implementation("com.philo:jsnamedargs-annotations:<version>")
}
}
}
}
// This enables the compiler plugin to run when building a JS distribution. Without it, the
// annotation would do nothing
dependencies {
add("kspJs", "com.philo:jsnamedargs-compiler:<version>")
}
This application is licensed under the MIT License. See License for more license and copyright information.
The most up to date dependencies can always be found in the module build.gradle.kts files.
The main dependencies for this project include:
To build and publish the library to your local Maven repository, run:
./gradlew -PskipSigning publishToMavenLocal
The -PskipSigning flag skips GPG signing, which is only required for publishing to Maven Central.
The version published will be the one defined in the root build.gradle.kts file (currently set in allprojects { version = "..." }).
public, as it is assumed the JS consumers should not need access to internal or private methods/classes.Surfaced from shared tags and platforms — no rankings paid for.