Forem: Kevin Schildhorn

Under the hood of Relay, Android Studio plugin for exporting Figma components to compose

Kevin Schildhorn — Wed, 16 Nov 2022 20:18:53 +0000

Recently Google announced Relay, a new process that allows teams to create UI in Figma and generate high-fidelity Compose UI components. It's currently in open alpha, and can be installed as a plugin for Android Studio. It's a really interesting tool that automatically generates compose code based on the components you choose to export from Figma. There's a overview of what it does and how to run it here, but you may be asking: what's really going on under the hood? So let's go over in detail the process from Figma to Compose code using Relay.

Note: this is not a tutorial for Figma, rather just a look at what code is generated and how it compares to custom compose code.

Note: Relay is a new and constantly evolving library, so some of these findings may change in the future. For reference I am testing Relay version "0.3.00".

Step 1. Figma

For this blog I made an example Figma page with a simple component, a button.

This button is somewhat simple, it's a rectangular shape with a text as a subview. It has been exported as a component, and has some properties defined in its design.

If you're not familiar with Figma, that's fine. Here are the main things to point out:

The button:

has a radius of 15
Has external padding of 10
Is centrally aligned
Has a Color of Primary*

Most of these are straight forward properties, one to note is the Color, which is defined in Figma as a Color Style so it can be re-used.

The Text:

Fills the button
Has a Typography of Button*
Has a defined content(text)
Has Text Centered both horizontally and vertically
Has a Color of PrimaryText

Again most things are straight forward but it's worth noting the Text Style Button is defined in Figma. It contains the font name, style, and size (as well as some spacing).

Looks pretty good (I hope!), let's export it and see what we get in Android Studio.

Step 2. UI Packages

In Android Studio we've imported this button as a ui-package. Here we can see some small files like text files and a config file. We also see a font folder, containing all the variants of the font used in the button, which is interesting. By default Relay puts all the fonts into each ui-package, even if they are shared between components. In other words if you have two components(like a button and a textfield) and they both use the same custom font, then Relay will add two copies of that same font to your project rather than referencing one copy. There is an experimental feature to use shared typography but that's beyond the scope of this post.

Let's look at the json file. Here we can see everything we've defined. Each part of the component has its own name and id, and is defined in "atoms" (This seems to be in align with the concept of Atomic Design). Then in "modes" we can see all the properties from Figma.

{
  "name": "button_primary",
  "source-key": { ... },
  ...,
  "design": {
    "atoms": [
      {
        "type": "group",
        "id": "top_level",
        "root": "true"
      },
      {
        "type": "text",
        "id": "buttonText"
      }
    ],
    "modes": {
      "Button/Primary": {
        "rules": [
          {
            "id": "top_level",
            ...
          },
          {
            "id": "buttonText",
            ...
          }
        ]
      }
    }
  }
}

It's a large file so I'll break it up for clarity. We can see that we have our two atoms, and an array of rules associated with the atoms.

{
  "id": "top_level",
  "padding": "10.0",
  "border-radius": "15.0",
  "main-axis-align": "start",
  "cross-axis-align": "start",
  "children": ["buttonText"],
  "item-spacing": "10.0",
  "background-color": {
    "alpha": "1.0",
    "hue": "38.82352941176471",
    "saturation": "1.0",
    "value": "1.0"
  },
  "clip-content": "false"
}

First off we can see this layer has been renamed to "top_level", which makes sense but can seem odd. It has padding, border-radius, alignment, and the color.
We see that the color "Primary" has been set as an HSV color, with no mention of the color style. Again with the experimental feature we may be able to get this color style, but for now it is a raw color.

{
  "id": "buttonText",
  "size-constraints": {
    "width-constraints": {
      "sizing-mode": "proportional",
      "value": "1.0"
    },
    "height-constraints": {
      "sizing-mode": "proportional",
      "value": "1.0"
    }
  },
  "font-weight": "700.0",
  "color": {
    "alpha": "1.0",
    "hue": "38.4375",
    "saturation": "1.0",
    "value": "0.25098039215686274"
  },
  "text-content": "Test Text",
  "overflow": "visible",
  "max-lines": "-1",
  "text-align-vertical": "center",
  "line-height": "1.25",
  "typeface": "Quicksand"
}

buttonText gets to keep its name, and here we can see it has sizing constraints, color, text content, alignment and Typeface.

Here we see that the typeface we nicely set in Figma is gone. Instead we have the name of the font, a font weight rather than a style, and a line height. Strangely the size of the font doesn't appear. It's not the worst, but it does come across a little messy.

Ok! We've imported the json config, now we can build it and take a look at our generated compose code!

Step 3. Generated Code

@Composable
fun ButtonPrimary(
    modifier: Modifier = Modifier,
) {
    TopLevel(
        modifier = modifier
    ) {
        ButtonText(modifier = Modifier.rowWeight(1.0f).columnWeight(1.0f))
    }
}

Here we can see what looks like a straight forward compose function, with the atoms defined from the json. But what are these TopLevel and ButtonText functions? Well, as you can imagine there's a too much generated code to go into for this post, so for brevity I'm going to highlight some key points. If you want to dig deeper into what's generated, I've created a github gist here that contains the generated code. Now let's go over some noteworthy code.

Relay Wrappers

All of the code generated from Relay has wrapping compose functions with the prefix Relay. For example the ButtonText function contains the RelayText function, which takes in the properties defined in Figma. These wrapper functions are generated in the relay-runtime package while our particular Button is defined in the relay package.

This goes even as far as having a RelayColumn and RelayRow, which strangely do not wrap their compose counterparts.

Properties

The properties in these wrappers have the same names as mentioned in figma, rather than compose names. For example instead of horizontalArrangement we have mainAxisAlignment. Similarly while Relay tries to use as many generic types as possible (i.e. floats, booleans, etc) it doesn't always use Compose types. It does some types like Color, FontWeight and more, but avoids others like Alignment and TextDecoration. I'm sure there are technical reasons for this but it really does make it feel like a plugin generated it.

Conversion

The conversion is interesting, albeit a bit messy. A lot of conversions are simply when statements, comparing the Figma variables to the compose variables. Most of the conversion is directly in the compose function, rather than having extensions or organizing the code a bit more. Generally speaking for the whole generated code, it's a bit messy and hard to read, but it gets the job done.

Bonus: Comparing to Typical code

Now that we've seen what the generated code looks like and how we've gotten there, I decided it would be fun to compare this to how I would personally create this component. Below is my version:

Button(
  onClick = { /*TODO*/ },
  modifier = Modifier.fillMaxWidth(1.0f),
  shape = RoundedCornerShape(15.dp),
  elevation = ButtonDefaults.elevation(defaultElevation = 0.dp),
  colors = ButtonDefaults.textButtonColors(backgroundColor = DesignColors.primary),
) {
  Text(
    text = text,
    style = typography.button,
    color = DesignColors.onPrimary,
    modifier = Modifier.padding(10.dp),
  )
}

Here I'm using the base jetpack components, with the addition of creating text and color styles for re-use.

It's interesting to see the differences between what a developer might make and what Relay is generating. If you look past the wrappers and name changes both functions are eventually calling the same code. Both use RoundedCornerShape, padding, and elevation, even if you have to dig deeper to see it. The only interesting difference is Relay does not use the composable Button or Text functions, but stick with their own custom implementation. That is to be expected when Figma has no concept of android components like buttons.

So yea, you can see that while different they both use similar code. Of course my code is more concise and easier to read, but does it really matter if no developer is going to manually update the composable?

Conclusion

So that's what's going on under the hood in Relay! There are some things I unfortunately didn't have time to cover such as nested components(spoilers, they work as expected!), adding custom parameters in Figma, mapping styles to compose, and vectors. If these are topics that you'd like me to cover let me know in the comments. Also if you have any questions or would like to see more of the code leave a comment or reach me at my twitter, dev.to, or on the Kotlin Slack (All under @kevinschildhorn).

Adding tests to your Discord Bot - Discord Bot Series (Part 3)

Kevin Schildhorn — Wed, 06 Jul 2022 16:00:53 +0000

Discord is a great platform for keeping in touch with friends, and adding a bot can enrich that experience. A bot can respond to messages, perform an action based on a command, or even add music to a voice chat.

In this series we'll be going over how to create a small example bot by using the NPM module for DiscordJS in a KotlinJS project.

Note: This is the third post in a series of three posts, about how to use KotlinJS and NPM modules to create a full fledged project, in this case a Discord Bot.

Previously

In my last post we went over how to add DiscordJS to our project, and start creating our bot. We added a listener for messages and replied to "hello" with a response of the computer name. I mentioned at the end that we weren't catching some edge cases with our response, and so in this post we'll be adding tests to our discord bot.

As a refresher, in this series we're going to create a small discord bot that responds to a specific message with its computer name.

Creating tests in kotlin

This article assumes you understand some basics about adding tests in a kotlin project, specifically using the kotlin.test library. You can see a helpful guide from jetbrains.

Adding testing dependencies

First off, we need to add dependencies to testing libraries. Make sure you have these dependencies in your build.gradle file.

dependencies {
    testImplementation(kotlin("test"))
    testImplementation(kotlin("test-js"))
}

Testing our logic

In the last post we added logic to respond to "hello" messages from users in the channel. We now want to test and make sure our bot says hello only when it gets a correct message. We want to have them ignore capitalization and not respond to other bots (I mean they can if they want, this is just for the example). Feel free to add any other requirements you want!

Separating out code

As it is now, we cannot test our code as it's just sitting inside the "messageCreate" callback. First we should move our code to a separate file. Let's make a new class called HelloHandler:

class HelloHandler {
    fun handleMessage(message: Message){
        if(message.content == "hello")
            message.channel.send("...")
    }
}

Now that we've moved our code to the handler we can update the existing code like so:

    val helloHandler = HelloHandler()
    client.on("messageCreate") { message ->
        helloHandler.handleMessage(message)
    }

Now we can call this code from a test. Let's make a quick test for testing a successful response:

class HelloGreetingTest {

    @Test
    fun testHelloWorldSuccess() {
        val message = Message()
        val helloHandler = HelloHandler()
        helloHandler.handleMessage(message)
        // assertTrue{ /* TODO: Assert the message was sent */ }
    }
}

Hopefully this seems straight forward, though you may notice that we aren't asserting anything at the moment. This is because we don't have a way to track that a message has been sent, and we don't really want that in our HelloHandler. For now it's commented out but we will update this in a later section.

Custom Messages

Another thing you may notice is there's no way to set the content of the Message, this is because the Message class is defined externally, which means that the bot is expecting the definition from the external Js.

Even if we didn't want a custom message, you cannot use external classes in testing, because there are variables that are expected but undefined

So how do we get around this?

Interfaces

The easiest way I've found to test external classes is to create a common interface. Then we can have two classes implementing this interface: the external class we already have, and a mocking class. Let's create an interface for Message:

external interface MessageInterface {
    val author: UserInterface
    val channel: ChannelInterface
    val content: String
}

Here we are defining the values we want to test, and we are setting it as external to match the existing Message class.

Note: You don't need to define values you don't need, or else your interface would be massive for no good reason.

Now we'll have:

external class Message : MessageInterface {
    override val author: User
    override val channel: TextChannel
    override val content: String
}

data class MockMessage(
    override val author: MockUser,
    override val channel: MockChannel,
    override val content: String
) : MessageInterface

I've gone ahead and created a MockUser and a MockChannel, as we want to check the username for a bot name and check if the message was sent. These were created the same as the MockMessage, by creating an interface and implementing it.

Note that all other Mock classes should be referencing the Interfaces you've created, not the external classes. Don't forget to update the HelloHandler to use the interface.

So now we can test a custom message, great! How do we make sure our bot sent a greeting as a response?

Checking Responses

In order to test a response to an incoming message, we can create a MockChannel to track when messages are sent. We don't want to actually send a message, just keep track of its status. I've created a MockChannel that has a simple Boolean that tells whether a message was sent.

class MockChannel : ChannelInterface {

    var sentMessage: Boolean = false
        private set

    override fun send(content: Any): Promise<MessageInterface> {
        print("Sent Message!")
        sentMessage = true
        return Promise { _, _ -> }
    }
}

So now we can assert that the sentMessage variable is true or false, depending on our test. You can go a step further and keep a reference to the information for other tests, but for simplicity we'll stick to this. Now we can finally go back to the test function and update it with our new code.

Final Test

    @Test
    fun testHelloWorldSuccess() {
        val user = MockUser("Kevin")
        val channel = MockChannel()
        val message = MockMessage(user, channel, "Hello")

        val helloHandler = HelloHandler()
        helloHandler.handleMessage(message)
        assertTrue{ message.channel.sentMessage }
    }

Here we have a working test. We create the mock information, create the Handler, then handle the message. Then we assert that the bot sent a message back! Now let's run the test, by either clicking the arrow next to the test and selecting run, or calling ./gradlew test from the command line.

It failed!

Why did it fail? Let's check the HelloHandler:

    if(message.content == "hello")
        message.channel.send("...")

It looks like we didn't take capitalization into account. Lets quickly change the check to message.equals("hello", ignoreCase = true), and run again.

It passed!

Excellent, our bot is working as we'd expect. We can go ahead and add more tests to make sure that other messages don't trigger a response, and catch other edge cases. Maybe we want to include exclamation points, or other languages, or we want to ignore hellos from users named Kevin. The possibilities are endless.

Conclusion

Congrats, You've tested your Discord Bot! You now have the basics to test all different messages and how your bot responds to them.

Your bot should now be running, stable, and ready to join some channels. This is the last post of the series, at this point you should have everything you need to know to be able to run a simple Discord Bot in KotlinJs. There are many other references out there to expand your bot from here using KMP libraries. Hopefully this series has been helpful and given you an introduction into kotlinJs.

Thanks for reading! Let me know in the comments if you have questions. Also, you can reach out to me at @kevinschildhorn on Twitter.

Using KotlinJS and NPM to create a Discord Bot - Discord Bot Series (Part 2)

Kevin Schildhorn — Tue, 26 Apr 2022 18:37:31 +0000

In this series we'll be going over how to create a small example bot by using the NPM module for DiscordJS in a KotlinJS project.

Note: This is the second post in a series of three posts, about how to use KotlinJS and NPM modules to create a full fledged project, in this case a Discord Bot. You can find the first post here.

Previously

In my last post we went over how to import node modules into our KotlinJS project, and created a simple project to test our imports. In this post we'll go over how to add DiscordJS to our project, and start creating our bot! Let's get started.

As a refresher, in this series we're going to create a small discord bot that responds to a specific message with its computer name.

Registering a Discord Bot

Before digging into code make sure you register a bot. Choose New Application, add a name and click create.

You can find more documentation on this process here.

After you create your bot you should see this screen.

Click on the Bot tab on the left and in the Build-a-bot section click add bot. Once you've done this you'll have created a bot! Be sure to keep the token from this screen for use in the project.

Also be sure to register your bot to your Channel using this guide.

Initializing DiscordJS

For our KotlinJS project we'll be using DiscordJs, which is a well documented and widely used node module for discord.

So first we'll add the dependency to the build.gradle file like before:

dependencies {
    implementation(npm("discord.js", "13.6.0"))
}

Then we can reference the Creating the main file documents to find out how to launch the bot. We can see that the client is initialized, then it listens for messages, then finally calls to login.

This is in Javascript but the kotlin implementation will look mostly the same. First we need to define the Client class. So we'll go to the documentation for the client, and see what we need to define. We can see that:

Client takes in ClientOptions to init.
Client inherits from EventEmitter, which is how once is called
Client login function takes in a string token and returns a string promise.

Init

Before we go defining ClientOptions and potentially going down the rabbit hole, we can see that it's defined as an object. In this case we can just pass a Json object in the constructor.

@JsModule("discord.js")
external class Client(config: Json?)

const val GUILDS = 1 // 1 << 0
val client = Client(json(Pair("intents", arrayOf(GUILDS))))

The client takes in "intents", which is an array of just Intents.FLAGS.GUILDS. If we follow the documentation from DiscordJS to the intents we can find their definition here. We see that Intents.FLAGS.GUILDS is 1 << 0 (or 1) so we'll pass that.

Once

This function we can figure out by the simple call. This is just to let us know the client is ready, so we'll just print out a confirmation.

@JsModule("discord.js")
external class Client(config: Json?) {
    fun once(event: String, cb: (Unit) -> Unit)
}

client.once("ready") {
    println("Hello From ${computerName()}!")
}

We can tell that it takes in a string, and returns a block. Since there's no input or output we can just use Unit, which acts as void.

Login

Based on what we learned we can define this easily. The token we will pass in comes from your created bot on the discord site. This was the token that was grabbed from the beginning of this post.

@JsModule("discord.js")
external class Client(config: Json?) {
    //...
    fun login(token: String): Promise<String>
}

//Main.kt
client.login("YOUR_TOKEN")

In this case we can tell the function returns a Promise from the DiscordJS documentation.

Running your bot

At this point all the calls should be in, your Main.kt should look something like this:

const val GUILDS = 1 // 1 << 0
val client = Client(json(Pair("intents", arrayOf(GUILDS))))
client.once("ready") {
    println("Hello From ${computerName()}!")
}
client.login(token)

If you run it you should be able to see your computer name in the terminal and your bot should be online!

Responding to Messages

This is great that the bot is running, however right now it's not doing anything. So let's get the bot to respond to a message.

Note: intent

In order for the bot to get messages, the client needs to register another intent, GUILDS_MESSAGES.

const val GUILDS = 1 // 1 << 0
const val GUILDS_MESSAGES = 512  //1 << 9
val client = Client(json(Pair("intents", arrayOf(GUILDS, GUILDS_MESSAGES))))

Defining Messages

So first we'll quickly define a message, as that's what's passed in. From the docs we can see a message contains a content string, the author, and the channel it was sent in. we're going to use the channel to send the reply to, and use the author to create a personalized message.
To make things quicker I've defined what we need from the documentation below:

external class Message {
    val author: User
    val channel: TextChannel
    val content: String
}

external class User {
    val avatar: String
    val username: String
}

external class TextChannel {
    fun send(content: Any): Promise<Message>
}

Listening for Messages

With that being set we can then go to the Client definition and add a listener for the message:

external class Client(config: Json?) {
    // ...
    fun on(event: String, cb: (item: Message) -> Unit)
}

So now we can listen for "message" events (or rather "messageCreate" events defined in the migration guide).

client.on("messageCreate") { message ->
    print(message.content)
}

To go even further let's implement our desired code. We'll check to see if someone says hello, and if they do respond with their name and the bots computer name.

client.on("messageCreate") { message ->
    if(message.content == "hello")
        message.channel.send("Hello ${message.author.username} From ${computerName()}!")
}

Now build and run the bot, and say hello! You should see a response like so.

Conclusion

Congrats, You've made a working Discord Bot! You now have the basics to expand your bot to respond to lots of different messages in many ways.

After playing around with the bot you may realize that there are some uncaught issues, for example the bot won't respond if there's a space in the message or if "Hello" is capitalized. In the next post of this series, we'll go over how we can write tests to catch these issues and make sure our bot works the way we expect.

Thanks for reading! Let me know in the comments if you have questions. Also, you can reach out to me at @kevinschildhorn on Twitter.

How to use NPM modules in Kotlin/JS - Discord Bot Series (Part 1)

Kevin Schildhorn — Tue, 12 Apr 2022 16:05:14 +0000

KotlinJS is an exciting new method of creating javascript projects that combines the benefits of javascripts speed and versatility and kotlins strong typing and conciseness. Plus the ability to easily add testing and even share code across platforms.

Since KotlinJS transpiles kotlin code to javascript it gives you all the advantages of executing a NodeJS program, while enjoying the benefits of the kotlin language.

There are many use cases for KotlinJS and in this series we'll be creating a Discord bot. Discord is a great platform for keeping in touch with friends, and adding a bot can enrich that experience. We can create this bot by using the NPM module for DiscordJS.

So how do you create a discord bot using KotlinJS? Well since this is a somewhat large topic this post will be the first in a series of three posts:

In this post we'll go over how kotlinJS uses node modules. This is more of an intro to KotlinJS and doesn't cover Discord.
In the next post we'll go over implementing DiscordJS and responding to messages.
In the last post we'll add some unit tests to make sure the bot works as expected before deploying.

Overview

By the end of this series we'll have a small discord bot that responds to a specific message with the computer name it's running on. In this first part the bot will just print to console on startup, but responding to messages will come later in another part.

Prerequisites

Some Kotlin Experience
Some JS Experience
IntelliJ IDEA (I'm using Community Edition)

New Project

To get started, first follow the js project setup on the kotlin site. (Be sure to choose NodeJS Application, not browser)

This will create a project with a Main.kt file and a greeting function. To run the project, call ./gradlew run in the terminal. You should see Hello, YOUR_BOT_NAME in the terminal!

Importing Node Modules in KotlinJS

Lets start off by getting familiar with how KotlinJS handles Node Modules.

To have the bot send a message with its name, let's use a simple node module called computer-name. As mentioned in the project setup, node modules are implemented as dependencies in the build.gradle file. No need for require or special imports. Add this line to your dependencies.

dependencies {
    implementation(npm("computer-name", "0.1.0"))
}

If you try to call computerName() now, you'll get an Unresolved reference error. This is because of a crucial difference between javascript and kotlin:

Javascript is loosely typed and kotlin is strongly typed

So in order to use this function we need to define it by using external functions.

External

The kotlin docs mention the External Modifier, which is used to declare pure javascript code. This tells the compiler that we're expecting this class or function to be defined externally by the node module. Whenever we want to use a module we have to define functions and classes. An important note about this is:

You only need to define what you are using

So you don't need to define the entire module, just what you need to reference.

So for us to use computerName() we need to define it and tell the compiler where it's defined, like so:

@JsModule("computer-name")
external fun computerName(): String

Note that we also need to annotate the function with the module name or else we'll hit a runtime error(compilerReferenceError).

This definition was easy to figure out based on the npm page, but as we'll see you may have to dig into the documentation and source code of node modules to find the original definition.

Module System

Another thing we have to define is the module system. You can find more information here, but in short KotlinJS supports UMD, AMD and commonJS systems. commonJS is widely used for NodeJS so we'll add useCommonJs() to our build.gradle file.

kotlin {
    js(IR) {
        useCommonJs()
    }
}

Now try adding println(computerName()) to main() and run the project.

You should see the name of your computer in the terminal! congrats! Now let's look at importing classes.

Importing NodeJS Classes

So far we've covered importing a function by using computerName() as an example, but that's a small module with one function. It's also important to be able to import classes and interfaces from modules to use in our project.

For this example we'll use youtube-search, which is a small module that lets you search for youtube videos (Note: You won't get results without a youtube api key, but the calls will still work which is all we need). From the npm page you can see there's a search function that returns custom results. So how do we define this in kotlin?

While there is definition in this module, we'll need to go to the repository to get more information. Lucky for us this module is conveniently written in typescript so it's very easy to find the definition, which is written in index.d.ts.

Dukat

Before we get into manually converting typescript to kotlin code, I should mention there is a tool to do this automatically called Dukat. It is a powerful tool that can help with easy conversion, however for this post I want to go over how to manually convert typescript to kotlin so that you have a good understanding of how it works.

Manually Converting Typescript

From the repo open the index.d.ts file and scroll to the bottom to see the search function.

declare function search(
  term: string,
  opts: search.YouTubeSearchOptions,
  cb?: (err: Error, result?: search.YouTubeSearchResults[], pageInfo?: search.YouTubeSearchPageResults) => void
): Promise<{results: search.YouTubeSearchResults[], pageInfo: search.YouTubeSearchPageResults}>;

We can see it takes in:

a string
a custom options class
a callback that returns an optional error, results array, and pageInfo array

The fuction then returns a Promise. Luckily kotlin already defines errors in the stdlib and it also includes an import for promises:

import kotlin.js.Promise

So the difficult parts are the Results and options. We can see that YouTubeSearchResults and YouTubeSearchPageResults are interfaces, so we can easily define them like so:

@file:JsModule("youtube-search")
// Note that for multiple definitions in the same file you can use @file

external interface YouTubeSearchPageResults {
  val totalResults: Int
  ...
}

external interface YouTubeSearchResults {
  val id: String
  ...
}

Now for YouTubeSearchOptions we could do the same approach, but there's another option we can use.

Json

We can simply use a Json class object, which acts similarly to a HashMap. This way we can just pass in what we want without defining the entire interface. This also works well if you can't find a clear definition of an object being passed in.

import kotlin.js.Json

val options = json(
    Pair("maxResults", 1),
    Pair("key", YOUR_YOUTUBE_API_KEY) // Leave this blank if you don't have one
)

So from all of this, we can then create the external search function:

@JsModule("youtube-search")
external fun search(
    term: String,
    opts: Json,
    cb: (
        err: Error?,
        result: Array<YouTubeSearchResults>?,
        pageInfo: YouTubeSearchPageResults?
    ) -> Unit // Unit acts as Void in kotlin
) : Promise<Json>

search("your search", options) { err, result, pageInfo ->
    print("Youtube callback $err, $result, $pageInfo\n")
}

Try adding this to your project and run. If you don't have an api key you should see this in the terminal:

Youtube callback Error: Request failed with status code 403, null, null

If you do have the api key you should see this:

Youtube callback null, [...], [object Object]

Conclusion

Congratulations you have a working KotlinJS project with imported NPM modules! In the next post we'll go over the specifics of creating our Discord bot using DiscordJS.

Thanks for reading! Let me know in the comments if you have questions. Also, you can reach out to me at @kevinschildhorn on Twitter.

Dividing Kotlin Multiplatform work in teams

Kevin Schildhorn — Mon, 28 Feb 2022 19:02:28 +0000

Kotlin Multiplatform is a great way to share code between multiple platforms, but this new approach can be confusing to navigate. There's a variety of sourceSets for platform specific code, plus intermediate sourceSets(such as mobileMain) that cover multiple platforms at once. One of the difficulties that can arise is how to divide work among your team.

This gets more difficult the larger your team is and the more platforms you're developing for. It sounds straightforward at first: the iOS developer works on the iOS code, the javascript works on the JS code, and so on. In practice however, you may run into unforeseen challenges.

Challenges

Languages: KMP is of course written in Kotlin, but if you have iOS developers or Javascript developers that only know Swift or JS, then there's going to be a learning curve.
Android Bias: You may think if you're writing Kotlin code then get the Android developer to do it. Not only are you pushing all the work on your Android devs, but there's chances for Android biases in their code.
Conflicts: If you have all devs working on their own platforms at the same time, that can lead to conflicts when merging PRs and arguments about the best approach.
Assigning Tasks: Beyond writing code there is an issue of issue tracking. When assigning work how do you know who's working on what layers? An Android task could include shared code.

So how do you assign work to multiple developers effectively, without causing the team to step on each others toes?

Our Approach

The best approach we've found is to split up the work into two camps:

PlatformSpecificUI and KMP

For example, if our project is written for Android, iOS and JS we'll have four groups:

androidUI, iosUI, jsUI and KMP

This again may sound straightforward, but there are some things worth mentioning. First let's visualize the layers.

Here we can see the different layers in our example. We have:
androidMain, iOSMain, jsMain, mobileMain and commonMain

So in our example we have the four groups and their work:

androidUI works in androidMain and the Android layer
iOSUI works in iosMain and the iOS layer
jsUI works in the js layer
KMP works in commonMain, mobileMain, and jsMain

With this approach all the platforms are dependent on the KMP groups work(The common layer).

An Example

So as an example, we want to add a new feature:

A new screen that fetches an image from an api and displays it when a button is pressed. This feature will be on every platform, and it's going to be tracked via an issue tracker.

Above we have an example of what your architecture might look like a lot at first, but let's go over it.

In Android, we have:
Fragment -> ViewModel -> Coordinator -> Repo -> network api

A button is pressed in the Fragment, an action is sent to the ViewModel which using a coroutine calls the coordinator. The coordinator then gets the image from the repository and processes it to bring back to the ui.

A similar flow can be seen for iOS and Javascript, but with their own implementations. In this example we have the interfaces RepositoryCommon and Api, which are then implemented platform specific.

Splitting the work

You may be asking why the jsUI doesn't work in jsMain, while the other two groups work in their respective sourceSets?

It's better to think of it in this way:

The KMP group is working on the common code and its implementations

In the example above the KMP group is working on the CommonRepository, as well as the implementations. They even work on the next level up(The Coordinator and js Service). The Coordinator and service are still in business logic, and despite having their own platforms they are still using shared libraries.

Why this approach

This approach prevents some of the issues mentioned prior:

No platform delays: Since all the platform specific work relies on the KMP groups work, there is no one platform that has an extra workload and all platforms start at the same starting line.
Increasing Platform Knowledge: The KMP group creating the groundwork for all the different platforms means that they can grow their knowledge of all the platforms in development.
No conflicts: All the platforms relying on the common layer ensures that all the platforms are in agreement with the business logic before working on the platform-specific code.

Note:With this method all platform developers would review and approve this foundational code, to make sure it fits all their requirements. This also helps maintain feature parity across platforms, and avoid platform biases.

Platform Equality

One key issue that I think a lot of KMP developers struggle with is platform equality. It's easy to start with the Android implementation since it's in Kotlin and the KMP library is easily debuggable. This approach puts a focus on Android, and other platforms can lose out because of it. They're seen as afterthoughts and don't get as much focus as Android.

A small example is that lists are not supported in KotlinJS, so if the developer starts using lists in the android implementation they may not notice until the JS project is built.

One of the advantages to having one group work in KMP is that it gives even attention to every platform, as the KMP developer has to write code with all the platforms in mind.

Layer Intermingling

There are some issues that may come up, especially when working between business and UI logic. Developers have different levels of experience in languages and Platforms, so crossing the bridge between logic layers can be tricky.

Examples of these issues are:

Platform specifics: shared code can still call platform libraries, such as iosMain calling Foundation, so Kotlin developers may not know these libraries.
Different Languages: In our approach platform developers are working in Kotlin sourceSets(i.e. an iOS developer has to work in iOSMain). An iOS dev may be familiar with UIKit and Swift, but is unsure how to write the code in Kotlin.

In cases like this where a there is an intersection between shared code and platform specific code, pair programming is a great option. Not only does it ensure that the code meets both sides' requirements, but it encourages knowledge sharing.

The KMP developer working on the shared code can create a base implementation, then work alongside the platform-specific developer to find the best approach to the issue. All the while both developers are sharing their knowledge of Kotlin and platform-specific code.

Downsides

The main downside to this approach, is that the KMP dev cannot easily test their implementation. For example if they are writing a network call and tries to serialize it into what they think the format is, it's only until one of the platform developers implements the call that they will realize it's incorrect.

One way to get ahead of this issue is to create tests whenever possible. Testing network layers can be tricky, but writing some form of test to make sure your code works for the platforms will help nip these issues in the bud.

If there is an issue like this, then it should be communicated with the team so that the other platform developers know that there is an issue, and the team can work to resolve the bug.

Conclusion

Every team is different, and every project is different. While this approach may not suit everyone, at Touchlab we have found that it can help organize work and increase knowledge sharing.

Thanks for reading! Let me know in the comments if you have questions. Also, you can reach out to me at @kevinschildhorn on Twitter, or on the Kotlin Slack. And if you find all this interesting, maybe you'd like to work with or work at Touchlab.

Kotlin 1.4 suspend functions

Kevin Schildhorn — Wed, 24 Jun 2020 16:33:16 +0000

It's that time again, when a new version of Kotlin is released and a new promising Kotlin Multiplatform feature is announced. Much like my last past post I saw this new release of 1.4-M2 with a new feature and was curious how it would work in practice. This time it's the addition of:

Support for Kotlin’s suspending functions in Swift and Objective-C

Again, this is a great feature but there isn't a lot of information to go off of in the release notes. Sure it shows some sample code and mentions you can only run it in the main thread, but the implementation seems simplified and leaves out customization options. This is most likely because there are many useful features of coroutines (like Jobs and Dispatchers) that are part of kotlinx libraries and are not available in the stdlib. So with all that said, how do these suspending functions work in swift and objective-c? Will this be useful in your Kotlin Multiplatform project? Let's find out.

The Code

So first off, I've made a simple example of this new feature on Github, which can be found here. In this example there is a suspend function in the shared kmp library called helloWorld in the class SuspendSampleHandler. This function is called twice in the ViewController of the matching XCode project to showcase a success and failure. Let's jump into the details of how this function is called.

SuspendSampleHandler().helloWorld(showError: false,  completionHandler:
{ result, error in
   if let errorReal = error {
      print(errorReal.localizedDescription)
   }
   if let resultReal = result {
      print(resultReal)
   }
})

Prior to 1.4-M2, suspend functions would not generate Objective-C output, and were not callable from iOS. In 1.4, suspend functions will generate Objective-C functions which take in a block with two arguments: a result and an NSError, both of which are Optional.

So in this case the result will be the successful result, and the error would be any errors or throwables that may have happened during the call. In the example code we have the function returning either a success or a failure based on the showError boolean variable.

The Results

This method of calling suspend functions does work successfully, however a lot of this implementation still remains a mystery. Even after testing the sample and attempting to dig into the source code, I'm unable to clarify how the suspend function is called. I cannot find a way to pass in Scopes or Dispatchers, or having it return a Job. Another thing I couldn't get working are Flow's. While they did compile successfully in XCode I was unable to get them to work during runtime. This could be a mistake on my part, but as far as I could tell there wasn't a successful way to use Flow from iOS.

In short, I've come to these conclusions about this feature:

The Scope and Dispatcher is unknown
There is no way to supply a Context or Scope
There is no way to cancel a coroutine in flight
There is no real Flow support

Should you use it

The answer isn't a simple yes or no, it depends on your usage.

This new feature is a nice straight forward way to call suspend functions from iOS, so if you're going the simplified route then I'd recommend it.

On the other hand this feature is missing a lot of options for customization that you would get with kotlinx coroutines. Things like the ability to cancel jobs, set scopes, use Flows, and set contexts. With this new language-level style you don't get these features.

With all that said, I most likely won't be using this feature. We are able to create something similar to this approach while still having the options for customization and Flow's. For an example you can look at how we implement suspend functions in our KaMPKit sample. This implementation supports a custom scope, Flows, and could easily be updated to support cancellation.

Our approach includes non-suspending functions which launches a predefined kotlinx.coroutine scope. The results are then sent to a callback that is set when creating the object. If you want to avoid some boilerplate and have consistent interfaces, you could expose suspend functions to the compiler and wrap those calls in your own kotlinx.coroutines scope once you’re on the Kotlin side.
Writing your own interface involves a little more work, but you gain much better control over the concurrency lifecycle.

Conclusion

It's nice that Kotlin added support for suspend functions in swift and objective-c. It provides a simplified and easy to use implementation for suspend functions, but as a trade-off you lose a lot of customization and control in the process. I personally would not use this new feature, and would instead choose a custom implementation in the common code.

Multiple Kotlin Frameworks in an Application

Kevin Schildhorn — Fri, 17 Apr 2020 19:39:55 +0000

Recently Kotlin 1.3.70 was released, adding many improvements and fixes for Kotlin. One of the most exciting improvements is the one mentioned below:

Support for multiple Kotlin frameworks in a single application

Previously, there was a known issue that an application could not use more than one dynamic Kotlin/Native framework because Obj-C classes defined in runtime were conflicting, coming from different instances of runtime. We’ve fixed this in 1.3.70, so now an application can use multiple Kotlin/Native frameworks. Any common dependencies are present in the frameworks under different Swift modules (and with different Obj-C prefixes).

This is an exciting update! Prior to 1.3.70 you had to have all of your Kotlin code in one framework, essentially having a monolithic library. Now this update supports multiple frameworks which opens the door for library developers to publish KMP built frameworks for usage in iOS.

This is a great feature, but as your mind starts to wander about the possibilities of having multiple frameworks you may begin to have some questions about the specifics of implementing these frameworks. You may be thinking things like:

Does this include static frameworks? The notes only mention dynamic frameworks
Are there any naming restrictions? What if I have multiple classes or modules with the same name?

And for that matter..

How well do the modules talk to each other? Do the multiple frameworks work together easily?

We had these questions too and we decided to do some research to try and find answers. So here are some of the results to our questions about multiple Kotlin frameworks.

Does this include static frameworks?

Answer: yes and no. While asking around the Kotlin slack (Which you can join via this link if you haven’t already here), and researching some of the existing Github issues, we’ve found out that the 1.3.70 supports static libraries...when they’re set to release. Currently multiple debug static frameworks are not supported in 1.3.70, as mentioned in this comment on the Kotlin-Native Repo in GitHub.
Note: Multiple debug static frameworks should work in Kotlin 1.4

Just to confirm this, and do some testing ourselves, we tested a bunch of different configurations to see what does and doesn’t work. Our findings are below

Results

Library 1	Build Type	Library 2	Build Type	Result
Dynamic	Debug	Dynamic	Debug	Success
Dynamic	Release	Dynamic	Release	Success
Dynamic	Debug	Dynamic	Release	Success

Static	Debug	Static	Debug	Failure*
Static	Release	Static	Release	Success
Static	Debug	Static	Release	Success

Dynamic	Debug	Static	Debug	Success
Dynamic	Release	Static	Release	Success
Dynamic	Debug	Static	Release	Success
Dynamic	Release	Static	Debug	Success

*Fails with both named and unnamed libraries with code:
runtime assert: runtime injected twice

Testing environment

Using simple framework importing, no cocoapods used.
Statics set using isStatic in gradle
binaries.getFramework(“DEBUG”) or binaries.getFramework(“RELEASE”) for build type
Kotlin 1.3.70

So the only combination that fails is two debug static frameworks. Note that this will build successfully, however it will get a runtime assert of runtime assert: runtime injected twice when running.

Are there any naming restrictions?

Answer: Yes, but that’s true for any kind of framework

As you can imagine, you cannot have two frameworks with the same name. This would obviously confuse the compiler, even when using the baseName variable in gradle. That being said you can have same-named classes in multiple libraries. If XCode gives you an Ambiguous use of ___ error, you can clarify by referencing it by its library.

i.e. framework1.MyClass vs framework2.MyClass.

How well do the modules talk to each other?

This question is a little open ended, so to clarify we wanted to know what classes you can pass between your two Kotlin frameworks. The answer is actually more straightforward than you may think.

Answer: Essentially, simple types and built-in classes like String work. Other types do not.

The reason for this is because these built-in classes are using default Swift/Obj-C classes, so there’s no duplication. This does not work for custom classes because of how they’re defined in the framework. Custom classes described in one library are not identical, at a binary level, to that same class referenced in the second library. They are not interchangeable. Let’s look at an example.

Example:

(You have two Kotlin modules, K1 and K2. Both create their own iOS framework. Both K1 and K2 have a dependency on the Kotlin library BizLib. In BizLib is a class called Person. To iOS, they are different, and you cannot pass a K1.Person into K2)

So when you try to pass in a class from one framework to another, you get this type of error:

Cannot convert value of type K2Person to expected argument type K1Person

So you cannot pass custom objects into different frameworks, even if they’re referenced in the Kotlin code.

As before, we did some testing of our own. We made some examples and saw what compiled and what gave errors. Here are our findings:

Element	Working?	Notes
Arrays	Do Not Work	Error: Cannot convert value of type 'Shared.KotlinArray' to expected argument type 'SecondLib.KotlinArray'
Lists	Works	Works unless the Element type is incompatible
MutableLists	Works	Works unless the Element type is incompatible
Maps	Works	Works unless the Key or Value type is incompatible
MutableMaps	Works	Works unless the Key or Value type is incompatible
String	Works	If a string is passed into the Map it is converted to an NSString
Boolean	Works	Can be compared successfully from both libraries
Int	Sometimes works	For some reason, if an Int is passed into a list or map, it is converted to a “KotlinInt” and is not interchangeable. This is weird because just the int itself works fine.

Functions that return simple types (i.e. string, bool, int) work between frameworks

We tested various classes you may use, and came up with some interesting results. As mentioned earlier built-in class seems to work successfully, as well as simple types. This is because there’s already existing swift classes, thus not making new and duplicate classes. The strange finding is that simple types in collections are in a boxed form, but those are classes specific to the framework. For example both classes appear as Lib1.KotlinInt and Lib2.KotlinInt when in a collection.

Recommendations

While you can have multiple frameworks, because the same dependency between frameworks won't be compatible, having many Kotlin iOS frameworks won't really be practical. It'll make more sense to have very few or one Kotlin iOS framework that is composed of multiple features. However, in cases where your modules are very different, it may make sense to have multiple Kotlin iOS frameworks. The bottom line is, you can have multiple Kotlin frameworks, and while it is not as flexible as some had hoped, it's another configuration you can consider as you expand your Kotlin Multiplatform codebase.

Conclusion

So those were our findings! While there is still a lot to explore with using multiple Kotlin frameworks we think this helps clear up a lot of things. We now know what does and doesn’t work at the moment when working with multiple frameworks, at least as of 1.3.70. With 1.4 being worked on right now some of these answers may change for the better. We'll be watching for these changes and looking into binary size considerations, debugging, and other issues soon.

Kotlin Coroutines Cheat Sheet

Kevin Schildhorn — Thu, 12 Dec 2019 15:54:40 +0000

Recently I was refreshing myself on kotlin coroutines, as I had worked with them before but never fulled grasped all the ins and outs of coroutines, and I decided to make some notes while I was reading through the docs (https://kotlinlang.org/docs/reference/coroutines/coroutines-guide.html).
I figured they would be helpful to other kotlin developers. Note that these are quick notes I jotted down and isn't a fully grammatical tutorial-esque article.

Summary

Coroutines are light-weight threads

CoroutineScope - Used to build coroutines, contains CoroutineContext
Scope Types:

GlobalScope - Lifetime of the new coroutine is limited only by the lifetime of the whole application
CoroutineScope - Is destroyed after all launched children are completed
MainScope - Scope for UI applications and uses Dispatchers.Main

CoroutineContext - A collection of various elements. Contains Job and CoroutineDispatcher
CoroutineDispatcher - Determines the thread(s) to use
Dispatcher types:

Unconfined - I’m working in thread main (appropriate for coroutines which neither consume CPU time nor update any shared data (like UI) confined to a specific thread)
Default - I'm working in thread DefaultDispatcher-worker-1
newSingleThreadContext - I’m working in thread MyOwnThread
main runBlocking - I’m working in thread main
newSingleThreadContext() - Creates new thread, can be used to switch between using withContext

Launch

Launch is a coroutine builder that returns a Job
Launch inherits the context from the scope it’s launched from
Customizing Launch:
- Can pass variables between threads using asContextElement
- Can name Coroutines using CoroutineName

Async

Async is like launch, but returns a Deferred (i.e. future)
Async CoroutineStart.LAZY only starts when await is called

Cancellation

Jobs can be cancelled or call join, which works like pthread_join
Coroutine cancellation is cooperative, meaning if the coroutine isn’t checking if it’s cancelled then it won’t be cancelled
SupervisorJob is a job where cancellation is only propagated downwards
withTimeout creates a timeout for the coroutines (throws TimeoutCancellationException)
When cancelled:
- Job throws an exception which can be handled with finally or catch (CancellationException)
- All child coroutines are cancelled as well

Suspend

Suspend can be used inside coroutines, but can also use other suspending functions
If a coroutine builder is inside suspend function a CoroutineScope needs to be added as well

Blocking

runBlocking runs a new coroutine and blocks the current thread, interruptible until it’s completion
Delay is non blocking

Flow

Flow is an asynchronous stream of values . Uses Emit and Collect to send and collect data
Flow runs in the context that is provided the collector
The code inside a flow isn’t run until the flow is collected
Flows can be cancelled with withTimeoutOrNull
Useful functions:
- transform - customize data, such as emitting a header first
- take - only take a certain amount of the flow
- flowOn - change the context of preceding code
- zip - combine multiple flows
- catch - catch any exceptions of preceding code
- onCompletion - perform any final tasks after the flow is done

Channel

Similar to a blocking queue, a way to transfer values between coroutines
Uses send and receive for normal values, produce and consume for streams
Channels can be closed to indicate no more elements are coming

Actor

Actor is an entity that can receive a class of messages using sealed classes. Meaning a consumer that takes in sealed classes

Let me know if I got anything wrong, or if I missed anything. Hope this helps!