Merge branch 'main' into gradle-plugins-0.6.1-snapshot

.github/workflows/dokka-gh-pages.yml

@@ -0,0 +1,61 @@
+name: Deploy the API documentation to GitHub Pages with Dokka
+
+on:
+  push:
+    branches: [ "release" ]
+  pull_request:
+    branches: [ "release" ]
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  # Build job
+  build:
+    runs-on: macos-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
+
+      - name: Set up JDK 8
+        uses: actions/setup-java@v4
+        with:
+          java-version: "8"
+          distribution: "zulu"
+
+      - name: Setup Gradle
+        uses: gradle/actions/setup-gradle@v4
+
+      - name: Build the distribution with Gradle Wrapper
+        run: ./gradlew :dokkaGeneratePublicationHtml
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: build/dokka/html/
+
+  # Deployment job
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.github/workflows/kotlin-multiplatform-ci.yml

@@ -0,0 +1,45 @@
+name: CI
+
+on:
+  push:
+    branches: [ "*" ]
+#  pull_request:
+#    branches: [ "*" ]
+
+jobs:
+  check:
+
+    runs-on: macos-latest
+    permissions:
+      contents: read
+
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up JDK 8
+        uses: actions/setup-java@v4
+        with:
+          java-version: '8'
+          distribution: 'zulu'
+
+      - name: Setup Gradle
+        uses: gradle/actions/setup-gradle@v4
+
+      - name: Check with Gradle Wrapper
+        run: ./gradlew check
+
+  dependency-submission:
+
+    runs-on: macos-latest
+    permissions:
+      contents: write
+
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up JDK 8
+        uses: actions/setup-java@v4
+        with:
+          java-version: '8'
+          distribution: 'zulu'
+
+      - name: Generate and submit dependency graph
+        uses: gradle/actions/dependency-submission@v4

README.md

@@ -5,9 +5,11 @@
 
 Huanshankeji's common code libraries in Kotlin
 
-These include a core library to extend the Kotlin language and its standard library, and extension libraries for various Kotlin and Java libraries such as [Λrrow](https://arrow-kt.io/), Coroutines ([docs here](https://kotlinlang.org/docs/coroutines-overview.html) and [repository here](https://github.com/Kotlin/kotlinx.coroutines)), [Exposed](https://github.com/JetBrains/Exposed), [Ktor](https://ktor.io/), [reflection](https://kotlinlang.org/docs/reflection.html), Serialization ([docs here](https://kotlinlang.org/docs/serialization.html) and [repository here](https://github.com/Kotlin/kotlinx.serialization)), [Vert.x](https://vertx.io/), etc. For common extensions for Compose Multiplatform, check out [compose-multiplatform-common](https://github.com/huanshankeji/compose-multiplatform-material/tree/main/compose-multiplatform-common).
+These include a core library to extend the Kotlin language and its standard library, and extension libraries for various Kotlin and Java libraries such as [Λrrow](https://arrow-kt.io/), Coroutines ([docs here](https://kotlinlang.org/docs/coroutines-overview.html) and [repository here](https://github.com/Kotlin/kotlinx.coroutines)), [Exposed](https://github.com/JetBrains/Exposed), [Ktor](https://ktor.io/), [reflection](https://kotlinlang.org/docs/reflection.html), Serialization ([docs here](https://kotlinlang.org/docs/serialization.html) and [repository here](https://github.com/Kotlin/kotlinx.serialization)), [Vert.x](https://vertx.io/) (along with extensions for [kotlinx-io](https://github.com/Kotlin/kotlinx-io) and [Okio](https://square.github.io/okio/)), etc. For common extensions for Compose Multiplatform, check out [compose-multiplatform-common](https://github.com/huanshankeji/compose-multiplatform-material/tree/main/compose-multiplatform-common).
 
-Currently supported targets by multiplatform libraries: JVM, JS (browser), iOS (`iosX64`, `iosArm64`, and `iosSimulatorArm64`) (except for the Coroutines module), and Wasm JS.
+Currently supported targets by multiplatform libraries: JVM, JS (browser), iOS (`iosX64`, `iosArm64`, and `iosSimulatorArm64`), and Wasm JS.
+
+[Check out the API documentation here.](https://huanshankeji.github.io/kotlin-common/.)
 
 ## Maven coordinates
 

build.gradle.kts

@@ -1,3 +1,28 @@
+import com.huanshankeji.cpnProject
+
 tasks.wrapper {
     distributionType = Wrapper.DistributionType.ALL
 }
+
+plugins {
+    id("org.jetbrains.dokka")
+}
+
+dependencies {
+    listOf(
+        "core",
+        "net",
+        "web",
+
+        "arrow",
+        "coroutines",
+        "exposed",
+        "ktor:client",
+        "reflect",
+        "serialization",
+        "vertx",
+        //"vertx:with-context-receivers",
+    ).forEach {
+        dokka(cpnProject(project, ":$it"))
+    }
+}

buildSrc/build.gradle.kts

@@ -19,4 +19,5 @@ dependencies {
     implementation(kotlin("gradle-plugin", "2.0.10"))
     implementation("com.huanshankeji:common-gradle-dependencies:0.8.0-20241016") // don't use a snapshot version in a main branch
     implementation("com.huanshankeji.team:gradle-plugins:0.6.1-SNAPSHOT") // don't use a snapshot version in a main branch
+    implementation("org.jetbrains.dokka:dokka-gradle-plugin:2.0.0-Beta")
 }

buildSrc/src/main/kotlin/VersionsAndDependencies.kt

@@ -2,7 +2,7 @@ import com.huanshankeji.CommonDependencies
 import com.huanshankeji.CommonGradleClasspathDependencies
 import com.huanshankeji.CommonVersions
 
-val projectVersion = "0.5.2-SNAPSHOT"
+val projectVersion = "0.6.0-SNAPSHOT"
 
 val commonVersions = CommonVersions(arrow = "2.0.0-alpha.4") // for Wasm JS
 val commonDependencies = CommonDependencies(commonVersions)
@@ -11,4 +11,6 @@ val commonGradleClasspathDependencies = CommonGradleClasspathDependencies(common
 object DependencyVersions {
     val protobufPlugin = "0.9.4"
     val protobuf = "3.25.2" // Not bumped. The version is a bit chaotic.
+    val kotlinxIo = "0.5.4"
+    val okio = "3.9.1"
 }

buildSrc/src/main/kotlin/common-conventions.gradle.kts

@@ -5,6 +5,7 @@ plugins {
     id("com.huanshankeji.team.with-group")
     id("maven-central")
     id("com.huanshankeji.team.default-github-packages-maven-publish")
+    id("dokka-convention")
 }
 
 version = projectVersion

buildSrc/src/main/kotlin/dokka-convention.gradle.kts

@@ -0,0 +1,24 @@
+plugins {
+    id("org.jetbrains.dokka")
+}
+
+dokka {
+    //moduleName.set("Huanshankeji Kotlin Common")
+    dokkaSourceSets.all {
+        //includes.from("README.md")
+        sourceLink {
+            //localDirectory.set(file("src/main/kotlin"))
+            remoteUrl(
+                "https://github.com/huanshankeji/kotlin-common/tree/v${version}/${
+                    with(project) {
+                        name.removePrefix(parent!!.name + '-')
+                    }
+                }"
+            )
+            remoteLineSuffix.set("#L")
+        }
+        /*pluginsConfiguration.html {
+            footerMessage.set("(c) Yongshun Ye")
+        }*/
+    }
+}

exposed/build.gradle.kts

@@ -1,8 +1,12 @@
+import com.huanshankeji.cpnProject
+
 plugins {
     id("jvm-conventions")
 }
 
 dependencies {
+    implementation(cpnProject(project, ":core")) // for the `@Untested` annotation
+
     implementation(commonDependencies.exposed.core())
     testImplementation(kotlin("test"))
 }

exposed/src/main/kotlin/com/huanshankeji/exposed/Slice.kt

@@ -1,5 +1,6 @@
 package com.huanshankeji.exposed
 
+import com.huanshankeji.Untested
 import org.jetbrains.exposed.sql.ColumnSet
 
 /**
@@ -9,3 +10,7 @@ import org.jetbrains.exposed.sql.ColumnSet
 @Deprecated("This causes \"java.lang.IllegalArgumentException: Can't prepare SELECT statement without columns or expressions to retrieve\" in the latest version of Exposed.")
 fun ColumnSet.emptySlice() =
     slice(emptyList())
+
+@Untested
+fun ColumnSet.selectEmpty() =
+    select(emptyList())

exposed/src/main/kotlin/com/huanshankeji/exposed/Statements.kt

@@ -3,22 +3,55 @@ package com.huanshankeji.exposed
 import org.jetbrains.exposed.sql.*
 import org.jetbrains.exposed.sql.statements.*
 
+private const val SELECT_DSL_DEPRECATION_MESSAGE =
+    "As part of Exposed SELECT DSL design changes, this will be removed in future releases."
+
 // The select queries are not executed eagerly so just use them directly.
 /**
  * Adapted from [org.jetbrains.exposed.sql.select].
  */
+@Deprecated(
+    SELECT_DSL_DEPRECATION_MESSAGE,
+    ReplaceWith("selectAllStatement().where(where)")
+)
 fun FieldSet.selectStatement(where: WhereOp): Query =
     select(where)
 
 /**
  * Adapted from [org.jetbrains.exposed.sql.select].
  */
+@Deprecated(
+    SELECT_DSL_DEPRECATION_MESSAGE,
+    ReplaceWith("selectAllStatement().where(where)")
+)
 fun FieldSet.selectStatement(where: BuildWhere): Query =
     select(where)
 
+@Deprecated(
+    SELECT_DSL_DEPRECATION_MESSAGE,
+    ReplaceWith("selectAllStatement().where(where)")
+)
 fun <T : FieldSet> T.selectStatementTableAware(where: TableAwareBuildWhere<T>): Query =
     selectStatement(where())
 
+/**
+ * You can also just use [selectAll].
+ */
+fun FieldSet.selectAllStatement() =
+    selectAll()
+
+/**
+ * You can also just use [select].
+ */
+fun ColumnSet.selectStatement(columns: List<Expression<*>>) =
+    select(columns)
+
+/**
+ * You can also just use [select].
+ */
+fun ColumnSet.selectStatement(column: Expression<*>, vararg columns: Expression<*>): Query =
+    select(column, *columns)
+
 /**
  * @see org.jetbrains.exposed.sql.deleteAll
  */

gradle.properties

@@ -1 +1,5 @@
 kotlin.mpp.stability.nowarn=true
+# needed for the GitHub Actions CI
+org.gradle.jvmargs=-Xmx4G
+# for Dokka
+org.jetbrains.dokka.experimental.gradle.pluginMode=V2Enabled

reflect/src/commonTest/kotlin/com/huanshankeji/kotlin/reflect/ConcreteTypeTest.kt

@@ -7,9 +7,9 @@ import kotlin.test.assertTrue
 
 class ConcreteTypeTest {
     @Test
-    fun testIsConcreteType() {
-        assertTrue(typeOf<Unit>().isConcreteType())
-        assertTrue(typeOf<List<Unit>>().isConcreteType())
-        assertFalse(typeOf<List<*>>().isConcreteType())
+    fun testIsConcreteTypeWithAllActualKClasses() {
+        assertTrue(typeOf<Unit>().isConcreteTypeWithAllActualKClasses())
+        assertTrue(typeOf<List<Unit>>().isConcreteTypeWithAllActualKClasses())
+        assertFalse(typeOf<List<*>>().isConcreteTypeWithAllActualKClasses())
     }
 }

reflect/src/jvmMain/kotlin/com/huanshankeji/kotlin/reflect/KTypeUnification.kt

@@ -9,7 +9,7 @@ import kotlin.reflect.KTypeParameter
  * @return `null` when it fails
  */
 fun concreteTypeUnify(knowConcreteType: KType, typeWithVariables: KType): Substitution? {
-    require(knowConcreteType.isConcreteType())
+    require(knowConcreteType.isConcreteTypeWithAllActualKClasses())
     val result = mutableMapOf<KTypeParameter, KType>()
     return if (doConcreteTypeUnify(knowConcreteType, typeWithVariables, result)) result
     else null

settings.gradle.kts

@@ -15,6 +15,10 @@ include(
     "serialization:benchmark:jvm-only",
     "vertx",
     "vertx:with-context-receivers",
+    /*
+    "vertx:kotlinx-io",
+    "vertx:okio",
+    */
 )
 
 fun ProjectDescriptor.setProjectConcatenatedNames(prefix: String) {
@@ -24,7 +28,7 @@ fun ProjectDescriptor.setProjectConcatenatedNames(prefix: String) {
 }
 rootProject.setProjectConcatenatedNames("")
 
-// This is needed for Kotlin Native.
+// This is needed for Kotlin Native and Dokka.
 dependencyResolutionManagement {
     @Suppress("UnstableApiUsage")
     repositories {

vertx/build.gradle.kts

@@ -11,6 +11,12 @@ java {
     registerFeature("vertxSqlClient") {
         usingSourceSet(sourceSets["main"])
     }
+    registerFeature("kotlinxIo") {
+        usingSourceSet(sourceSets["main"])
+    }
+    registerFeature("okio") {
+        usingSourceSet(sourceSets["main"])
+    }
 }
 
 dependencies {
@@ -23,6 +29,9 @@ dependencies {
         implementation(moduleWithoutVersion("lang-kotlin-coroutines"))
     }
 
+    "kotlinxIoImplementation"("org.jetbrains.kotlinx:kotlinx-io-core:${DependencyVersions.kotlinxIo}")
+    "okioImplementation"("com.squareup.okio:okio:${DependencyVersions.okio}")
+
     implementation(cpnProject(project, ":core"))
     implementation(cpnProject(project, ":coroutines"))
 

vertx/src/main/kotlin/com/huanshankeji/vertx/core/Buffer.kt

@@ -2,10 +2,11 @@ package com.huanshankeji.vertx.core
 
 import io.netty.buffer.Unpooled
 import io.vertx.core.buffer.Buffer
+import io.vertx.core.buffer.impl.BufferImpl
 
 /**
  * Creates a wrapped [Buffer] so that unnecessary copy is avoided.
  * Also see https://github.com/eclipse-vertx/vert.x/issues/4407.
  */
 fun wrappedBuffer(byteArray: ByteArray): Buffer =
-    Buffer.buffer(Unpooled.wrappedBuffer(byteArray))
+    BufferImpl.buffer(Unpooled.wrappedBuffer(byteArray))

vertx/src/main/kotlin/com/huanshankeji/vertx/core/kotlinx/io/Primitives.kt

@@ -0,0 +1,7 @@
+package com.huanshankeji.vertx.core.kotlinx.io
+
+@Suppress("NOTHING_TO_INLINE")
+internal inline fun Long.toIntOrThrow(): Int {
+    require(this in Int.MIN_VALUE.toLong()..Int.MAX_VALUE.toLong())
+    return toInt()
+}