feat: Kotlin 2.x/K2, version catalog, serialization & coroutines modules, docs

v3.4 modernization (continued):

- Migrate to Kotlin 2.x (K2); introduce gradle/libs.versions.toml version catalog;
  simplify the JS/Wasm/Node and iOS source-set wiring for the K2 hierarchy template.
- Apply binary-compatibility-validator and Kover plugins.
- New published module tree-structure-serialization: @Serializable TreeNodeDto with
  toDto()/toTreeNode() round-trip (kotlinx.serialization).
- New published module tree-structure-coroutines: asFlow()/pre/post/levelOrderFlow()
  (kotlinx.coroutines Flow traversal).
- Docs: README examples for Sequence/navigation/functional APIs, class-level KDoc
  (thread-safety/complexity), and a CHANGELOG.md.
- Ignore subproject build/ directories.
- Bump version to 3.4.0.

All JVM tests green (core + both modules).
This commit is contained in:
2026-06-06 13:47:20 +02:00
parent c45c5b7afa
commit e1f01c4e2d
14 changed files with 470 additions and 66 deletions

View File

@@ -5,8 +5,12 @@
Lightweight Kotlin Multiplatform tree data structure for Kotlin and Java. Includes a small DSL, multiple traversal iterators, and pretty-print support.
- Kotlin Multiplatform (JVM, JS, iOS, and Native host)
- Kotlin Multiplatform (JVM, JS, Wasm, iOS, and Native host)
- Pre-order, Post-order, and Level-order iteration
- Lazy `Sequence` traversal that composes with the Kotlin stdlib (`map`/`filter`/`firstOrNull`…)
- Navigation helpers: `root()`, `ancestors()`, `siblings()`, `leaves()`, `descendants()`, `isLeaf`, `degree`
- Functional helpers: `findNode`, `filterNodes`, `anyNode`, `allNodes`, `foldNodes`, `mapValues`, `deepCopy`, `structurallyEquals`
- Stack-safe: traversal and `height()`/`nodeCount()`/`clear()` handle arbitrarily deep trees without `StackOverflowError`
- Simple DSL: tree { child(...) }
- Utilities: nodeCount(), height(), depth(), path(), prettyString(), clear(), removeChild()
@@ -116,6 +120,55 @@ root.removeChild(child)
root.clear() // remove entire subtree
```
### Lazy traversal with Sequence
Traversal is exposed as a lazy `Sequence`, so it composes with the Kotlin standard library and
short-circuits (it never materializes the whole tree just to find one node):
```kotlin
val tree = tree("World") {
child("North America") { child("USA") }
child("Europe") {
child("Poland")
child("Germany")
}
}
// Pick an order explicitly — no need to mutate the node's state.
tree.preOrderSequence().map { it.value }.toList() // [World, North America, USA, Europe, Poland, Germany]
tree.levelOrderSequence().first { it.value == "USA" } // stops as soon as it's found
tree.asSequence(TreeNodeIterators.PostOrder).count() // 6
```
### Navigation
```kotlin
val usa = tree.findNode { it == "USA" }!!
usa.isLeaf // true
usa.depth() // 2
usa.root().value // "World"
usa.ancestors().map { it.value } // [North America, World]
tree.leaves().map { it.value } // [USA, Poland, Germany]
val europe = tree.findNode { it == "Europe" }!!
europe.children.first().siblings().map { it.value } // [Germany]
```
### Functional operations
```kotlin
tree.anyNode { it == "Poland" } // true
tree.filterNodes { it.length > 5 } // nodes whose value is longer than 5 chars
tree.countNodes { it.startsWith("U") } // 1
// Transform values into a brand-new tree (the original is untouched); stack-safe.
val lengths: TreeNode<Int> = tree.mapValues { it.length }
// Deep copy + structural comparison.
val copy = tree.deepCopy()
tree.structurallyEquals(copy) // true (same values, same shape, different nodes)
```
## Publishing to Maven Central (central.sonatype.com)
This project is configured to publish artifacts to Maven Central via the Sonatype Central Portal.