feat: tree-structure-compose (LazyTree) + O(n) addChild cycle check

- New published module tree-structure-compose: a LazyTree composable for Compose
  Multiplatform (JVM/desktop, iOS, Wasm) with lazy rendering and expand/collapse.
- Fix an O(n^2) regression in addChild(): only walk ancestors for cycle detection
  when the child already has a subtree (a fresh leaf can never form a cycle), so
  building deep trees is O(n) again. Caught by the deep-chain stack-safety test on JS.
- README: Compose usage section; align all install snippets to 4.0.0.
- Version catalog: Compose Multiplatform + compose-compiler plugins.

Verified locally: JVM, JS(node), Wasm(node), iOS-simulator tests + apiCheck all green;
Compose module compiles for JVM, Wasm and iOS.

.github/dependabot.yml

@@ -1,11 +0,0 @@
-# To get started with Dependabot version updates, you'll need to specify which
-# package ecosystems to update and where the package manifests are located.
-# Please see the documentation for all configuration options:
-# https://docs.github.com/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file
-
-version: 2
-updates:
-  - package-ecosystem: "" # See documentation for possible values
-    directory: "/" # Location of package manifests
-    schedule:
-      interval: "weekly"

.github/workflows/publishRelease.yml

@@ -18,21 +18,19 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Check out code
-        uses: actions/checkout@v2
-      - name: Set up JDK 11
-        uses: actions/setup-java@v2
+        uses: actions/checkout@v4
+      - name: Set up JDK 21
+        uses: actions/setup-java@v4
         with:
-          distribution: adopt
-          java-version: 11
+          distribution: temurin
+          java-version: '21'
 
         # Runs upload, and then closes & releases the repository
       - name: Publish to MavenCentral
-        run: ./gradlew publish --max-workers 1
+        run: ./gradlew publishToMavenCentral
         env:
-          OSSRH_USERNAME: ${{ secrets.OSSRH_USERNAME }}
-          OSSRH_PASSWORD: ${{ secrets.OSSRH_PASSWORD }}
-          SIGNING_KEY_ID: ${{ secrets.SIGNING_KEY_ID }}
-          SIGNING_PASSWORD: ${{ secrets.SIGNING_PASSWORD }}
-          SIGNING_KEY: ${{ secrets.SIGNING_KEY }}
-          SONATYPE_STAGING_PROFILE_ID: ${{ secrets.SONATYPE_STAGING_PROFILE_ID }}
+          ORG_GRADLE_PROJECT_mavenCentralUsername: ${{ secrets.MAVEN_CENTRAL_USERNAME }}
+          ORG_GRADLE_PROJECT_mavenCentralPassword: ${{ secrets.MAVEN_CENTRAL_PASSWORD }}
+          ORG_GRADLE_PROJECT_signingInMemoryKey: ${{ secrets.SIGNING_KEY }}
+          ORG_GRADLE_PROJECT_signingInMemoryKeyPassword: ${{ secrets.SIGNING_PASSWORD }}
           SNAPSHOT: false

.github/workflows/publishSnapshot.yml

@@ -1,35 +0,0 @@
-name: Publish Snapshot
-
-on:
-  push:
-    branches: [master]
-
-jobs:
-  test:
-    uses: ./.github/workflows/test.yml
-    secrets: inherit
-
-  publish:
-    needs: test
-    name: Publish Snapshot
-    runs-on: ubuntu-latest
-    steps:
-      - name: Check out code
-        uses: actions/checkout@v2
-      - name: Set up JDK 11
-        uses: actions/setup-java@v2
-        with:
-          distribution: adopt
-          java-version: 11
-
-        # Runs upload, and then closes & releases the repository
-      - name: Publish to snapshot to Sonatype
-        run: ./gradlew publish --max-workers 1
-        env:
-          OSSRH_USERNAME: ${{ secrets.OSSRH_USERNAME }}
-          OSSRH_PASSWORD: ${{ secrets.OSSRH_PASSWORD }}
-          SIGNING_KEY_ID: ${{ secrets.SIGNING_KEY_ID }}
-          SIGNING_PASSWORD: ${{ secrets.SIGNING_PASSWORD }}
-          SIGNING_KEY: ${{ secrets.SIGNING_KEY }}
-          SONATYPE_STAGING_PROFILE_ID: ${{ secrets.SONATYPE_STAGING_PROFILE_ID }}
-          SNAPSHOT: true

.github/workflows/test.yml

@@ -6,18 +6,26 @@ on:
   workflow_call:
 
 jobs:
-  build:
-    name: Run unit tests
-    runs-on: ubuntu-latest
+  test:
+    name: ${{ matrix.name }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - name: JVM / JS / Wasm / Native + API check
+            os: ubuntu-latest
+            tasks: jvmTest jsNodeTest wasmJsNodeTest nativeTest apiCheck
+          - name: iOS
+            os: macos-latest
+            tasks: iosSimulatorArm64Test
     steps:
       - name: Check out code
-        uses: actions/checkout@v2
-      - name: Set up JDK 11
-        uses: actions/setup-java@v2
+        uses: actions/checkout@v4
+      - name: Set up JDK 21
+        uses: actions/setup-java@v4
         with:
-          distribution: adopt
-          java-version: 11
-
-        # Builds the release artifacts of the library
+          distribution: temurin
+          java-version: '21'
       - name: Test
-        run: ./gradlew test
+        run: ./gradlew ${{ matrix.tasks }} --console=plain

.gitignore

@@ -9,6 +9,7 @@
 /.idea/assetWizardSettings.xml
 .DS_Store
 /build
+build/
 /captures
 .externalNativeBuild
 .cxx
@@ -16,3 +17,4 @@
 /.idea/compiler.xml
 /.idea/jarRepositories.xml
 /.idea/deploymentTargetDropDown.xml
+/.idea/

.idea/.gitignore

@@ -1,4 +0,0 @@
-# Default ignored files
-/shelf/
-/workspace.xml
-artifacts

.idea/codeStyles/Project.xml

@@ -1,10 +0,0 @@
-<component name="ProjectCodeStyleConfiguration">
-  <code_scheme name="Project" version="173">
-    <JetCodeStyleSettings>
-      <option name="CODE_STYLE_DEFAULTS" value="KOTLIN_OFFICIAL" />
-    </JetCodeStyleSettings>
-    <codeStyleSettings language="kotlin">
-      <option name="CODE_STYLE_DEFAULTS" value="KOTLIN_OFFICIAL" />
-    </codeStyleSettings>
-  </code_scheme>
-</component>

.idea/codeStyles/codeStyleConfig.xml

@@ -1,5 +0,0 @@
-<component name="ProjectCodeStyleConfiguration">
-  <state>
-    <option name="USE_PER_PROJECT_SETTINGS" value="true" />
-  </state>
-</component>

.idea/gradle.xml

@@ -1,17 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<project version="4">
-  <component name="GradleMigrationSettings" migrationVersion="1" />
-  <component name="GradleSettings">
-    <option name="linkedExternalProjectsSettings">
-      <GradleProjectSettings>
-        <option name="distributionType" value="WRAPPED" />
-        <option name="externalProjectPath" value="$PROJECT_DIR$" />
-        <option name="modules">
-          <set>
-            <option value="$PROJECT_DIR$" />
-          </set>
-        </option>
-      </GradleProjectSettings>
-    </option>
-  </component>
-</project>

.idea/inspectionProfiles/Project_Default.xml

@@ -1,6 +0,0 @@
-<component name="InspectionProjectProfileManager">
-  <profile version="1.0">
-    <option name="myName" value="Project Default" />
-    <inspection_tool class="ReplaceUntilWithRangeUntil" enabled="true" level="WEAK WARNING" enabled_by_default="true" />
-  </profile>
-</component>

.idea/kotlinScripting.xml

@@ -1,9 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<project version="4">
-  <component name="KotlinScriptingSettings">
-    <scriptDefinition className="org.jetbrains.kotlin.scripting.resolve.KotlinScriptDefinitionFromAnnotatedTemplate" definitionName="KotlinBuildScript">
-      <order>2147483647</order>
-      <autoReloadConfigurations>true</autoReloadConfigurations>
-    </scriptDefinition>
-  </component>
-</project>

.idea/misc.xml

@@ -1,7 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<project version="4">
-  <component name="ExternalStorageConfigurationManager" enabled="true" />
-  <component name="ProjectRootManager" version="2" languageLevel="JDK_11" default="true" project-jdk-name="11" project-jdk-type="JavaSDK">
-    <output url="file://$PROJECT_DIR$/out" />
-  </component>
-</project>

.idea/vcs.xml

@@ -1,6 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<project version="4">
-  <component name="VcsDirectoryMappings">
-    <mapping directory="" vcs="Git" />
-  </component>
-</project>

CHANGELOG.md

@@ -0,0 +1,79 @@
+# Changelog
+
+All notable changes to this project are documented here. The format is based on
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [4.0.0]
+
+A breaking release that cleans up the core API and enforces an explicit public surface.
+
+### Changed (breaking)
+- `TreeNode.treeIterator` is now a read-only `val` (set it via the constructor). Use
+  `iterator(order)` or `asSequence(order)` to traverse in a different order per call.
+- `removeChild(child)` now only removes a **direct** child of the receiver (previously it removed
+  the node from its actual parent regardless). Use `child.detach()` to unhook a node from wherever
+  it lives.
+- `addChild(child)` now throws `TreeNodeException` if `child` already has a parent or if the
+  attachment would create a cycle. Call `detach()` first to move a node.
+- `clear()` no longer detaches the receiver from its own parent; it only removes its descendants.
+- `path(descendant)` now returns `List<TreeNode<T>>?` (`null` when `descendant` is the root or not a
+  descendant) instead of throwing `TreeNodeException`.
+
+### Added
+- `TreeNode.detach()` — removes a node from its parent.
+- `TreeNode.iterator(order)` — a one-shot iterator in a specific order.
+- Strict `explicitApi()` mode across all modules.
+- New `tree-structure-compose` module: a `LazyTree` composable for Compose Multiplatform.
+
+### Migration
+- `node.treeIterator = PostOrder; for (n in node) { … }` → `for (n in node.asSequence(PostOrder)) { … }`
+- `root.removeChild(deepNode)` → `deepNode.detach()`
+- `try { node.path(x) } catch (e: TreeNodeException) { … }` → `node.path(x)?.let { … }`
+
+## [3.4.0]
+
+### Added
+- Lazy `Sequence` traversal: `asSequence(order)`, `preOrderSequence()`, `postOrderSequence()`,
+  `levelOrderSequence()` — composes with the Kotlin stdlib and short-circuits.
+- Navigation extensions: `isLeaf`, `degree`, `root()`, `ancestors()`, `siblings()`, `leaves()`,
+  `descendants()`.
+- Functional extensions: `findNode`, `filterNodes`, `anyNode`, `allNodes`, `countNodes`,
+  `foldNodes`, `mapValues`, `deepCopy`, `structurallyEquals` (all stack-safe).
+- New optional modules published as separate artifacts:
+  - `tree-structure-serialization` — `kotlinx.serialization` support via a `TreeNodeDto`.
+  - `tree-structure-coroutines` — `Flow` traversal (`asFlow`, `preOrderFlow`, …).
+- `CHANGELOG.md`, expanded README examples, and class-level KDoc (thread-safety / complexity).
+
+### Changed
+- `nodeCount()`, `height()`, `clear()` and the post-order iterator are now iterative — deep or
+  degenerate (linear) trees no longer throw `StackOverflowError`.
+- Migrated to Kotlin 2.x (K2 compiler) and introduced a Gradle version catalog.
+- Build now uses `binary-compatibility-validator` (committed `.api` baselines) and Kover.
+
+## [3.1.5]
+
+### Fixed
+- Removed a stray `println` in `TreeNode.removeChild()` that printed to stdout on every removal.
+
+### Removed
+- Deleted the `Example.ws.kts` worksheet and the `kotlin("script-runtime")` dependency from the
+  published JVM artifact, plus the leftover `ExampleUnitTest` template test.
+
+### Changed
+- Bumped `actions/checkout` v2 → v4 in CI workflows.
+
+## [3.1.4]
+- Updated Kotlin and JS dependencies; added the `wasmJs` target.
+
+## [3.1.3]
+- iOS targets and Maven Central (Sonatype Central Portal) publishing.
+
+[Unreleased]: https://github.com/AdrianKuta/Tree-Data-Structure/compare/v4.0.0...HEAD
+[4.0.0]: https://github.com/AdrianKuta/Tree-Data-Structure/compare/v3.4.0...v4.0.0
+[3.4.0]: https://github.com/AdrianKuta/Tree-Data-Structure/compare/v3.1.5...v3.4.0
+[3.1.5]: https://github.com/AdrianKuta/Tree-Data-Structure/compare/v3.1.3...v3.1.5
+[3.1.4]: https://github.com/AdrianKuta/Tree-Data-Structure/releases/tag/v3.1.4
+[3.1.3]: https://github.com/AdrianKuta/Tree-Data-Structure/releases/tag/v3.1.3

README.md

@@ -1,9 +1,44 @@
 # Tree (Data Structure)
 [![maven](https://img.shields.io/maven-central/v/com.github.adriankuta/tree-structure?style=plastic)](https://mvnrepository.com/artifact/com.github.adriankuta/tree-structure)
 [![License: MIT](https://img.shields.io/github/license/AdrianKuta/Tree-Data-Structure?style=plastic)](https://github.com/AdrianKuta/Tree-Data-Structure/blob/master/LICENSE)
-[![Publish](https://github.com/AdrianKuta/Tree-Data-Structure/actions/workflows/publishRelease.yml/badge.svg)](https://github.com/AdrianKuta/Tree-Data-Structure/actions/workflows/publish.yml)
+[![Publish](https://github.com/AdrianKuta/Tree-Data-Structure/actions/workflows/publishRelease.yml/badge.svg)](https://github.com/AdrianKuta/Tree-Data-Structure/actions/workflows/publishRelease.yml)
 
-Simple implementation to store object in tree structure.
+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, 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()
+
+## Installation
+
+Gradle (Kotlin DSL):
+```kotlin
+// commonMain for KMP projects, or any sourceSet/module where you need it
+dependencies {
+    implementation("com.github.adriankuta:tree-structure:4.0.0") // see badge above for the latest version
+}
+```
+
+Gradle (Groovy):
+```groovy
+dependencies {
+    implementation "com.github.adriankuta:tree-structure:4.0.0" // see badge above for the latest
+}
+```
+
+Maven:
+```xml
+<dependency>
+  <groupId>com.github.adriankuta</groupId>
+  <artifactId>tree-structure</artifactId>
+  <version>4.0.0</version>
+</dependency>
+```
 
 ## Usage
 
@@ -25,19 +60,15 @@ europe.addChild(france)
 println(root.prettyString())
 ```
 
-**Pretty Kotlin**
-
+**Pretty Kotlin (DSL)**
 ```kotlin
-val root =
-    tree("World") {
-        child("North America") {
-            child("USA")
-        }
-        child("Europe") {
-            child("Poland")
-            child("Germany")
-        }
+val root = tree("World") {
+    child("North America") { child("USA") }
+    child("Europe") {
+        child("Poland")
+        child("Germany")
     }
+}
 ```
 
 **Java**
@@ -58,8 +89,7 @@ europe.addChild(france);
 System.out.println(root.prettyString());
 ```
 
-*Output:*
-
+Output:
 ```
 World
 ├── North America
@@ -69,11 +99,157 @@ World
     └── France
 ```
 
+### Traversal and utilities
+```kotlin
+val root = TreeNode("root")
+// ... build your tree
 
-## Download
+// Choose iteration order per call (the default order is set in the constructor and is read-only)
+for (node in root.asSequence(TreeNodeIterators.PostOrder)) println(node.value)
+
+// Utilities
+root.nodeCount()   // number of descendants
+root.height()      // longest path to a leaf (in edges)
+root.depth()       // distance from current node to the root
+val path = root.path(root.children.first()) // nodes from descendant up to root
+
+// Mutations — removeChild removes a *direct* child; detach() unhooks a node from wherever it lives
+val child = root.children.first()
+root.removeChild(child)   // child is now detached from root
+root.clear()              // remove all descendants of root
+```
+
+### 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)
+```
+
+## Optional modules
+
+The core `tree-structure` artifact has no third-party dependencies. Ecosystem integrations ship as
+separate, opt-in artifacts that depend on the core.
+
+### Serialization — `tree-structure-serialization`
+
+`kotlinx.serialization` support. A `TreeNode` holds a parent back-reference (a cycle), so it cannot
+be `@Serializable` directly — convert to/from the acyclic `TreeNodeDto` instead.
+
+```kotlin
+implementation("com.github.adriankuta:tree-structure-serialization:4.0.0")
+```
+
+```kotlin
+val json = Json.encodeToString(tree.toDto())
+val restored = Json.decodeFromString<TreeNodeDto<String>>(json).toTreeNode()
+```
+
+### Coroutines — `tree-structure-coroutines`
+
+Traverse a tree as a cold `Flow` (handy in coroutine/`ViewModel` pipelines).
+
+```kotlin
+implementation("com.github.adriankuta:tree-structure-coroutines:4.0.0")
+```
+
+```kotlin
+tree.preOrderFlow().collect { println(it.value) }
+tree.asFlow(TreeNodeIterators.LevelOrder).map { it.value }
+```
+
+### Compose UI — `tree-structure-compose`
+
+A `LazyTree` composable for Compose Multiplatform (JVM/desktop, iOS, Wasm). Only the visible nodes
+are composed, and you decide how each node looks:
+
+```kotlin
+implementation("com.github.adriankuta:tree-structure-compose:4.0.0")
+```
+
+```kotlin
+LazyTree(root) { node, depth, expanded, toggle ->
+    Row(Modifier.padding(start = (depth * 16).dp).clickable(onClick = toggle)) {
+        if (!node.isLeaf) Text(if (expanded) "▾ " else "▸ ")
+        Text(node.value.toString())
+    }
+}
+```
+
+## Publishing to Maven Central (central.sonatype.com)
+
+This project is configured to publish artifacts to Maven Central via the Sonatype Central Portal.
+
+There are two supported ways to publish:
+
+1) Via GitHub Actions (recommended)
+- Create a GitHub Release (tag) in this repository. When a release is published, the workflow .github/workflows/publishRelease.yml runs automatically.
+- The workflow uses the Gradle task publishToMavenCentral to upload artifacts through the Central Portal.
+- Make sure these repository secrets are configured in GitHub:
+  - MAVEN_CENTRAL_USERNAME — Your Sonatype Central username (not email).
+  - MAVEN_CENTRAL_PASSWORD — Your Sonatype Central password or a token from central.sonatype.com.
+  - SIGNING_KEY — ASCII‑armored GPG private key (exported, single line; for in‑memory signing).
+  - SIGNING_PASSWORD — Passphrase for the key above.
+- The workflow uses JDK 21 and publishes the version defined in build.gradle.kts.
+
+2) Locally via Gradle
+- Ensure you have a Sonatype Central account and that the groupId com.github.adriankuta is verified in central.sonatype.com (Namespace Rules → Verify).
+- Export the same credentials/signing values as environment variables or pass them as Gradle properties:
+  - ORG_GRADLE_PROJECT_mavenCentralUsername
+  - ORG_GRADLE_PROJECT_mavenCentralPassword
+  - ORG_GRADLE_PROJECT_signingInMemoryKey
+  - ORG_GRADLE_PROJECT_signingInMemoryKeyPassword
+- Then run:
+  - ./gradlew publishToMavenCentral
+- For snapshot publishing, set -Psnapshot=true (the version is derived from PUBLISH_VERSION with -SNAPSHOT).
+
+Notes
+- Publishing is powered by the com.vanniktech.maven.publish Gradle plugin and Sonatype Central Portal (no legacy Nexus staging URLs needed).
+- The plugin is configured to sign all publications. Coordinates and POM metadata are defined in build.gradle.kts.
+- If using the combined task is preferred, you can also run publishAndReleaseToMavenCentral when automatic release is enabled; this repository currently uploads with publishToMavenCentral from CI.
 
-    implementation "com.github.adriankuta:tree-structure:$latest_versions"
-    
 ## License
 
 MIT License
@@ -97,3 +273,5 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
+
+---

api/tree-structure.api

@@ -0,0 +1,101 @@
+public abstract interface class com/github/adriankuta/datastructure/tree/ChildDeclarationInterface {
+	public abstract synthetic fun child (Ljava/lang/Object;Lkotlin/jvm/functions/Function1;)Lcom/github/adriankuta/datastructure/tree/TreeNode;
+}
+
+public final class com/github/adriankuta/datastructure/tree/ChildDeclarationInterface$DefaultImpls {
+	public static synthetic fun child$default (Lcom/github/adriankuta/datastructure/tree/ChildDeclarationInterface;Ljava/lang/Object;Lkotlin/jvm/functions/Function1;ILjava/lang/Object;)Lcom/github/adriankuta/datastructure/tree/TreeNode;
+}
+
+public class com/github/adriankuta/datastructure/tree/TreeNode : com/github/adriankuta/datastructure/tree/ChildDeclarationInterface, java/lang/Iterable, kotlin/jvm/internal/markers/KMappedMarker {
+	public fun <init> (Ljava/lang/Object;Lcom/github/adriankuta/datastructure/tree/iterators/TreeNodeIterators;)V
+	public synthetic fun <init> (Ljava/lang/Object;Lcom/github/adriankuta/datastructure/tree/iterators/TreeNodeIterators;ILkotlin/jvm/internal/DefaultConstructorMarker;)V
+	public final fun addChild (Lcom/github/adriankuta/datastructure/tree/TreeNode;)V
+	public synthetic fun child (Ljava/lang/Object;Lkotlin/jvm/functions/Function1;)Lcom/github/adriankuta/datastructure/tree/TreeNode;
+	public final fun clear ()V
+	public final fun depth ()I
+	public final fun detach ()Z
+	public final fun getChildren ()Ljava/util/List;
+	public final fun getParent ()Lcom/github/adriankuta/datastructure/tree/TreeNode;
+	public final fun getTreeIterator ()Lcom/github/adriankuta/datastructure/tree/iterators/TreeNodeIterators;
+	public final fun getValue ()Ljava/lang/Object;
+	public final fun height ()I
+	public final fun isRoot ()Z
+	public fun iterator ()Ljava/util/Iterator;
+	public final fun iterator (Lcom/github/adriankuta/datastructure/tree/iterators/TreeNodeIterators;)Ljava/util/Iterator;
+	public final fun nodeCount ()I
+	public final fun path (Lcom/github/adriankuta/datastructure/tree/TreeNode;)Ljava/util/List;
+	public final fun prettyString ()Ljava/lang/String;
+	public final fun removeChild (Lcom/github/adriankuta/datastructure/tree/TreeNode;)Z
+	public fun toString ()Ljava/lang/String;
+}
+
+public final class com/github/adriankuta/datastructure/tree/TreeNodeFunctionalExtKt {
+	public static final fun allNodes (Lcom/github/adriankuta/datastructure/tree/TreeNode;Lkotlin/jvm/functions/Function1;)Z
+	public static final fun anyNode (Lcom/github/adriankuta/datastructure/tree/TreeNode;Lkotlin/jvm/functions/Function1;)Z
+	public static final fun countNodes (Lcom/github/adriankuta/datastructure/tree/TreeNode;Lkotlin/jvm/functions/Function1;)I
+	public static final fun deepCopy (Lcom/github/adriankuta/datastructure/tree/TreeNode;)Lcom/github/adriankuta/datastructure/tree/TreeNode;
+	public static final fun filterNodes (Lcom/github/adriankuta/datastructure/tree/TreeNode;Lkotlin/jvm/functions/Function1;)Ljava/util/List;
+	public static final fun findNode (Lcom/github/adriankuta/datastructure/tree/TreeNode;Lkotlin/jvm/functions/Function1;)Lcom/github/adriankuta/datastructure/tree/TreeNode;
+	public static final fun foldNodes (Lcom/github/adriankuta/datastructure/tree/TreeNode;Ljava/lang/Object;Lkotlin/jvm/functions/Function2;)Ljava/lang/Object;
+	public static final fun mapValues (Lcom/github/adriankuta/datastructure/tree/TreeNode;Lkotlin/jvm/functions/Function1;)Lcom/github/adriankuta/datastructure/tree/TreeNode;
+	public static final fun structurallyEquals (Lcom/github/adriankuta/datastructure/tree/TreeNode;Lcom/github/adriankuta/datastructure/tree/TreeNode;)Z
+}
+
+public final class com/github/adriankuta/datastructure/tree/TreeNodeNavigationExtKt {
+	public static final fun ancestors (Lcom/github/adriankuta/datastructure/tree/TreeNode;)Ljava/util/List;
+	public static final fun descendants (Lcom/github/adriankuta/datastructure/tree/TreeNode;)Ljava/util/List;
+	public static final fun getDegree (Lcom/github/adriankuta/datastructure/tree/TreeNode;)I
+	public static final fun isLeaf (Lcom/github/adriankuta/datastructure/tree/TreeNode;)Z
+	public static final fun leaves (Lcom/github/adriankuta/datastructure/tree/TreeNode;)Ljava/util/List;
+	public static final fun root (Lcom/github/adriankuta/datastructure/tree/TreeNode;)Lcom/github/adriankuta/datastructure/tree/TreeNode;
+	public static final fun siblings (Lcom/github/adriankuta/datastructure/tree/TreeNode;)Ljava/util/List;
+}
+
+public final class com/github/adriankuta/datastructure/tree/TreeNodeSequenceExtKt {
+	public static final fun asSequence (Lcom/github/adriankuta/datastructure/tree/TreeNode;Lcom/github/adriankuta/datastructure/tree/iterators/TreeNodeIterators;)Lkotlin/sequences/Sequence;
+	public static synthetic fun asSequence$default (Lcom/github/adriankuta/datastructure/tree/TreeNode;Lcom/github/adriankuta/datastructure/tree/iterators/TreeNodeIterators;ILjava/lang/Object;)Lkotlin/sequences/Sequence;
+	public static final fun levelOrderSequence (Lcom/github/adriankuta/datastructure/tree/TreeNode;)Lkotlin/sequences/Sequence;
+	public static final fun postOrderSequence (Lcom/github/adriankuta/datastructure/tree/TreeNode;)Lkotlin/sequences/Sequence;
+	public static final fun preOrderSequence (Lcom/github/adriankuta/datastructure/tree/TreeNode;)Lkotlin/sequences/Sequence;
+}
+
+public final class com/github/adriankuta/datastructure/tree/exceptions/TreeNodeException : java/lang/RuntimeException {
+	public fun <init> ()V
+	public fun <init> (Ljava/lang/String;)V
+	public fun <init> (Ljava/lang/String;Ljava/lang/Throwable;)V
+	public synthetic fun <init> (Ljava/lang/String;Ljava/lang/Throwable;ILkotlin/jvm/internal/DefaultConstructorMarker;)V
+}
+
+public final class com/github/adriankuta/datastructure/tree/iterators/LevelOrderTreeIterator : java/util/Iterator, kotlin/jvm/internal/markers/KMappedMarker {
+	public fun <init> (Lcom/github/adriankuta/datastructure/tree/TreeNode;)V
+	public fun hasNext ()Z
+	public fun next ()Lcom/github/adriankuta/datastructure/tree/TreeNode;
+	public synthetic fun next ()Ljava/lang/Object;
+	public fun remove ()V
+}
+
+public final class com/github/adriankuta/datastructure/tree/iterators/PostOrderTreeIterator : java/util/Iterator, kotlin/jvm/internal/markers/KMappedMarker {
+	public fun <init> (Lcom/github/adriankuta/datastructure/tree/TreeNode;)V
+	public fun hasNext ()Z
+	public fun next ()Lcom/github/adriankuta/datastructure/tree/TreeNode;
+	public synthetic fun next ()Ljava/lang/Object;
+	public fun remove ()V
+}
+
+public final class com/github/adriankuta/datastructure/tree/iterators/PreOrderTreeIterator : java/util/Iterator, kotlin/jvm/internal/markers/KMappedMarker {
+	public fun <init> (Lcom/github/adriankuta/datastructure/tree/TreeNode;)V
+	public fun hasNext ()Z
+	public fun next ()Lcom/github/adriankuta/datastructure/tree/TreeNode;
+	public synthetic fun next ()Ljava/lang/Object;
+	public fun remove ()V
+}
+
+public final class com/github/adriankuta/datastructure/tree/iterators/TreeNodeIterators : java/lang/Enum {
+	public static final field LevelOrder Lcom/github/adriankuta/datastructure/tree/iterators/TreeNodeIterators;
+	public static final field PostOrder Lcom/github/adriankuta/datastructure/tree/iterators/TreeNodeIterators;
+	public static final field PreOrder Lcom/github/adriankuta/datastructure/tree/iterators/TreeNodeIterators;
+	public static fun getEntries ()Lkotlin/enums/EnumEntries;
+	public static fun valueOf (Ljava/lang/String;)Lcom/github/adriankuta/datastructure/tree/iterators/TreeNodeIterators;
+	public static fun values ()[Lcom/github/adriankuta/datastructure/tree/iterators/TreeNodeIterators;
+}
+

build.gradle.kts

@@ -1,149 +1,99 @@
-import org.jetbrains.kotlin.konan.properties.Properties
+import org.jetbrains.kotlin.gradle.ExperimentalWasmDsl
 
 plugins {
-    kotlin("multiplatform") version "1.7.20"
-    id("org.jetbrains.dokka") version "1.7.20"
-    id("maven-publish")
+    alias(libs.plugins.kotlinMultiplatform)
+    alias(libs.plugins.dokka)
+    alias(libs.plugins.mavenPublish)
+    alias(libs.plugins.binaryCompatibilityValidator)
+    alias(libs.plugins.kover)
     signing
 }
 
 val PUBLISH_GROUP_ID = "com.github.adriankuta"
-val PUBLISH_ARTIFACT_ID = "tree-structure"
-val PUBLISH_VERSION = "3.0.2"
+val PUBLISH_ARTIFACT_ID = "tree-structure"    // base artifact; KMP will add -jvm, -ios*, etc.
+val PUBLISH_VERSION = "4.0.0"
 
-val secretFile = File(rootProject.rootDir, "local.properties")
-if (secretFile.exists()) {
-    secretFile.reader().use {
-        Properties().apply {
-            load(it)
-        }
-    }.onEach { (name, value) ->
-        project.ext[name.toString()] = value
-    }
-} else {
-    project.ext["ossrhUsername"] = System.getenv("OSSRH_USERNAME")
-    project.ext["ossrhPassword"] = System.getenv("OSSRH_PASSWORD")
-    project.ext["sonatypeStagingProfileId"] = System.getenv("SONATYPE_STAGING_PROFILE_ID")
-    project.ext["signingKeyId"] = System.getenv("SIGNING_KEY_ID")
-    project.ext["signingPassword"] = System.getenv("SIGNING_PASSWORD")
-    project.ext["signingKey"] = System.getenv("SIGNING_KEY")
-    project.ext["snapshot"] = System.getenv("SNAPSHOT")
-}
 val snapshot: String? by project
 
 group = PUBLISH_GROUP_ID
 version = if (snapshot.toBoolean()) "$PUBLISH_VERSION-SNAPSHOT" else PUBLISH_VERSION
 
-val dokkaHtml by tasks.getting(org.jetbrains.dokka.gradle.DokkaTask::class)
+mavenPublishing {
+    // Central Portal + auto release when we call publishAndReleaseToMavenCentral
+    publishToMavenCentral(automaticRelease = false)
+    signAllPublications()
 
-val javadocJar: TaskProvider<Jar> by tasks.registering(Jar::class) {
-    dependsOn(dokkaHtml)
-    archiveClassifier.set("javadoc")
-    from(dokkaHtml.outputDirectory)
-}
+    coordinates(PUBLISH_GROUP_ID, PUBLISH_ARTIFACT_ID, version.toString())
 
-publishing {
-    publications {
+    pom {
+        name.set("Tree Data Structure")
+        description.set(
+            "Lightweight n-ary tree data structure for Kotlin Multiplatform (JVM, JS, Wasm, iOS, " +
+                "Native). DSL, pre/post/level-order traversal, lazy Sequence traversal, and pretty-print.",
+        )
+        url.set("https://github.com/AdrianKuta/Tree-Data-Structure")
 
-        withType<MavenPublication> {
-            artifact(javadocJar)
-            pom {
-                name.set("Tree Data Structure")
-                description.set("Simple implementation to store object in tree structure.")
-                url.set("https://github.com/AdrianKuta/Tree-Data-Structure")
-                licenses {
-                    license {
-                        name.set("MIT License")
-                        url.set("https://www.mit.edu/~amini/LICENSE.md")
-                    }
-                }
-                developers {
-                    developer {
-                        name.set("Adrian Kuta")
-                        email.set("adrian.kuta93@gmail.com")
-                    }
-                }
-                scm {
-                    connection.set("scm:git:github.com/AdrianKuta/Tree-Data-Structure.git")
-                    developerConnection.set("scm:git:ssh://github.com/AdrianKuta/Tree-Data-Structure.git")
-                    url.set("https://github.com/AdrianKuta/Tree-Data-Structure/tree/master")
-                }
+        licenses {
+            license {
+                name.set("MIT License")
+                url.set("https://opensource.org/licenses/MIT")
+                distribution.set("repo")
             }
         }
-    }
-
-    repositories {
-        maven {
-            name = "Sonatype"
-            val releasesRepoUrl = "https://oss.sonatype.org/service/local/staging/deploy/maven2"
-            val snapshotsRepoUrl = "https://oss.sonatype.org/content/repositories/snapshots"
-            url = uri(if (version.toString().endsWith("SNAPSHOT")) snapshotsRepoUrl else releasesRepoUrl)
-            credentials {
-                val ossrhUsername: String? by project
-                val ossrhPassword: String? by project
-                username = ossrhUsername
-                password = ossrhPassword
+        developers {
+            developer {
+                id.set("AdrianKuta")
+                name.set("Adrian Kuta")
+                email.set("adrian.kuta93@gmail.com")
             }
         }
+        scm {
+            url.set("https://github.com/AdrianKuta/Tree-Data-Structure")
+            connection.set("scm:git:https://github.com/AdrianKuta/Tree-Data-Structure.git")
+            developerConnection.set("scm:git:ssh://git@github.com/AdrianKuta/Tree-Data-Structure.git")
+        }
     }
 }
 
-signing {
-    val signingKeyId: String? by project
-    val signingPassword: String? by project
-    val signingKey: String? by project
-    useInMemoryPgpKeys(signingKeyId, signingKey, signingPassword)
-
-    sign(publishing.publications)
-}
-
 repositories {
     mavenCentral()
 }
 
 kotlin {
-    jvm {
-        compilations.all {
-            kotlinOptions.jvmTarget = "1.8"
-        }
-        withJava()
-        testRuns["test"].executionTask.configure {
-            useJUnitPlatform()
-        }
+    explicitApi()
+    jvmToolchain(21)
+
+    jvm()
+
+    js(IR) {
+        browser()
+        nodejs()
     }
-    js(BOTH) {
-        browser {
-            commonWebpackConfig {
-                cssSupport.enabled = true
-            }
-        }
+
+    @OptIn(ExperimentalWasmDsl::class)
+    wasmJs {
+        browser()
+        nodejs()
     }
+
+    // Apple targets
+    iosX64()
+    iosArm64()
+    iosSimulatorArm64()
+
+    // Native host target
     val hostOs = System.getProperty("os.name")
     val isMingwX64 = hostOs.startsWith("Windows")
-    val nativeTarget = when {
+    when {
         hostOs == "Mac OS X" -> macosX64("native")
         hostOs == "Linux" -> linuxX64("native")
         isMingwX64 -> mingwX64("native")
         else -> throw GradleException("Host OS is not supported in Kotlin/Native.")
     }
 
-
     sourceSets {
-        val commonMain by getting
-        val commonTest by getting {
-            dependencies {
-                implementation(kotlin("test"))
-            }
+        commonTest.dependencies {
+            implementation(kotlin("test"))
         }
-        val jvmMain by getting {
-            dependencies {
-                implementation(kotlin("script-runtime"))
-            }
-        }
-        val jvmTest by getting
-        val jsMain by getting
-        val jsTest by getting
-        val nativeMain by getting
-        val nativeTest by getting
     }
 }

gradle.properties

@@ -1,2 +1 @@
 kotlin.code.style=official
-kotlin.js.compiler=ir

gradle/libs.versions.toml

@@ -0,0 +1,24 @@
+[versions]
+kotlin = "2.1.0"
+dokka = "1.9.20"
+mavenPublish = "0.34.0"
+binaryCompatibilityValidator = "0.16.3"
+kover = "0.8.3"
+coroutines = "1.9.0"
+kotlinxSerialization = "1.7.3"
+composeMultiplatform = "1.7.3"
+
+[plugins]
+kotlinMultiplatform = { id = "org.jetbrains.kotlin.multiplatform", version.ref = "kotlin" }
+kotlinSerialization = { id = "org.jetbrains.kotlin.plugin.serialization", version.ref = "kotlin" }
+dokka = { id = "org.jetbrains.dokka", version.ref = "dokka" }
+mavenPublish = { id = "com.vanniktech.maven.publish", version.ref = "mavenPublish" }
+binaryCompatibilityValidator = { id = "org.jetbrains.kotlinx.binary-compatibility-validator", version.ref = "binaryCompatibilityValidator" }
+kover = { id = "org.jetbrains.kotlinx.kover", version.ref = "kover" }
+composeMultiplatform = { id = "org.jetbrains.compose", version.ref = "composeMultiplatform" }
+composeCompiler = { id = "org.jetbrains.kotlin.plugin.compose", version.ref = "kotlin" }
+
+[libraries]
+kotlinx-coroutines-core = { module = "org.jetbrains.kotlinx:kotlinx-coroutines-core", version.ref = "coroutines" }
+kotlinx-coroutines-test = { module = "org.jetbrains.kotlinx:kotlinx-coroutines-test", version.ref = "coroutines" }
+kotlinx-serialization-json = { module = "org.jetbrains.kotlinx:kotlinx-serialization-json", version.ref = "kotlinxSerialization" }

gradle/wrapper/gradle-wrapper.properties

@@ -1,5 +1,7 @@
 distributionBase=GRADLE_USER_HOME
 distributionPath=wrapper/dists
-distributionUrl=https\://services.gradle.org/distributions/gradle-7.4.2-bin.zip
+distributionUrl=https\://services.gradle.org/distributions/gradle-8.5-bin.zip
+networkTimeout=10000
+validateDistributionUrl=true
 zipStoreBase=GRADLE_USER_HOME
 zipStorePath=wrapper/dists

gradlew

@@ -55,7 +55,7 @@
 #       Darwin, MinGW, and NonStop.
 #
 #   (3) This script is generated from the Groovy template
-#       https://github.com/gradle/gradle/blob/master/subprojects/plugins/src/main/resources/org/gradle/api/internal/plugins/unixStartScript.txt
+#       https://github.com/gradle/gradle/blob/HEAD/subprojects/plugins/src/main/resources/org/gradle/api/internal/plugins/unixStartScript.txt
 #       within the Gradle project.
 #
 #       You can find Gradle at https://github.com/gradle/gradle/.
@@ -80,13 +80,11 @@ do
     esac
 done
 
-APP_HOME=$( cd "${APP_HOME:-./}" && pwd -P ) || exit
-
-APP_NAME="Gradle"
+# This is normally unused
+# shellcheck disable=SC2034
 APP_BASE_NAME=${0##*/}
-
-# Add default JVM options here. You can also use JAVA_OPTS and GRADLE_OPTS to pass JVM options to this script.
-DEFAULT_JVM_OPTS='"-Xmx64m" "-Xms64m"'
+# Discard cd standard output in case $CDPATH is set (https://github.com/gradle/gradle/issues/25036)
+APP_HOME=$( cd "${APP_HOME:-./}" > /dev/null && pwd -P ) || exit
 
 # Use the maximum available, or set MAX_FD != -1 to use that value.
 MAX_FD=maximum
@@ -133,22 +131,29 @@ location of your Java installation."
     fi
 else
     JAVACMD=java
-    which java >/dev/null 2>&1 || die "ERROR: JAVA_HOME is not set and no 'java' command could be found in your PATH.
+    if ! command -v java >/dev/null 2>&1
+    then
+        die "ERROR: JAVA_HOME is not set and no 'java' command could be found in your PATH.
 
 Please set the JAVA_HOME variable in your environment to match the
 location of your Java installation."
+    fi
 fi
 
 # Increase the maximum file descriptors if we can.
 if ! "$cygwin" && ! "$darwin" && ! "$nonstop" ; then
     case $MAX_FD in #(
       max*)
+        # In POSIX sh, ulimit -H is undefined. That's why the result is checked to see if it worked.
+        # shellcheck disable=SC2039,SC3045
         MAX_FD=$( ulimit -H -n ) ||
             warn "Could not query maximum file descriptor limit"
     esac
     case $MAX_FD in  #(
       '' | soft) :;; #(
       *)
+        # In POSIX sh, ulimit -n is undefined. That's why the result is checked to see if it worked.
+        # shellcheck disable=SC2039,SC3045
         ulimit -n "$MAX_FD" ||
             warn "Could not set maximum file descriptor limit to $MAX_FD"
     esac
@@ -193,11 +198,15 @@ if "$cygwin" || "$msys" ; then
     done
 fi
 
-# Collect all arguments for the java command;
-#   * $DEFAULT_JVM_OPTS, $JAVA_OPTS, and $GRADLE_OPTS can contain fragments of
-#     shell script including quotes and variable substitutions, so put them in
-#     double quotes to make sure that they get re-expanded; and
-#   * put everything else in single quotes, so that it's not re-expanded.
+
+# Add default JVM options here. You can also use JAVA_OPTS and GRADLE_OPTS to pass JVM options to this script.
+DEFAULT_JVM_OPTS='"-Xmx64m" "-Xms64m"'
+
+# Collect all arguments for the java command:
+#   * DEFAULT_JVM_OPTS, JAVA_OPTS, JAVA_OPTS, and optsEnvironmentVar are not allowed to contain shell fragments,
+#     and any embedded shellness will be escaped.
+#   * For example: A user cannot expect ${Hostname} to be expanded, as it is an environment variable and will be
+#     treated as '${Hostname}' itself on the command line.
 
 set -- \
         "-Dorg.gradle.appname=$APP_BASE_NAME" \
@@ -205,6 +214,12 @@ set -- \
         org.gradle.wrapper.GradleWrapperMain \
         "$@"
 
+# Stop when "xargs" is not available.
+if ! command -v xargs >/dev/null 2>&1
+then
+    die "xargs is not available"
+fi
+
 # Use "xargs" to parse quoted args.
 #
 # With -n1 it outputs one arg per line, with the quotes and backslashes removed.

gradlew.bat

@@ -14,7 +14,7 @@
 @rem limitations under the License.
 @rem
 
-@if "%DEBUG%" == "" @echo off
+@if "%DEBUG%"=="" @echo off
 @rem ##########################################################################
 @rem
 @rem  Gradle startup script for Windows
@@ -25,7 +25,8 @@
 if "%OS%"=="Windows_NT" setlocal
 
 set DIRNAME=%~dp0
-if "%DIRNAME%" == "" set DIRNAME=.
+if "%DIRNAME%"=="" set DIRNAME=.
+@rem This is normally unused
 set APP_BASE_NAME=%~n0
 set APP_HOME=%DIRNAME%
 
@@ -40,7 +41,7 @@ if defined JAVA_HOME goto findJavaFromJavaHome
 
 set JAVA_EXE=java.exe
 %JAVA_EXE% -version >NUL 2>&1
-if "%ERRORLEVEL%" == "0" goto execute
+if %ERRORLEVEL% equ 0 goto execute
 
 echo.
 echo ERROR: JAVA_HOME is not set and no 'java' command could be found in your PATH.
@@ -75,13 +76,15 @@ set CLASSPATH=%APP_HOME%\gradle\wrapper\gradle-wrapper.jar
 
 :end
 @rem End local scope for the variables with windows NT shell
-if "%ERRORLEVEL%"=="0" goto mainEnd
+if %ERRORLEVEL% equ 0 goto mainEnd
 
 :fail
 rem Set variable GRADLE_EXIT_CONSOLE if you need the _script_ return code instead of
 rem the _cmd.exe /c_ return code!
-if  not "" == "%GRADLE_EXIT_CONSOLE%" exit 1
-exit /b 1
+set EXIT_CODE=%ERRORLEVEL%
+if %EXIT_CODE% equ 0 set EXIT_CODE=1
+if not ""=="%GRADLE_EXIT_CONSOLE%" exit %EXIT_CODE%
+exit /b %EXIT_CODE%
 
 :mainEnd
 if "%OS%"=="Windows_NT" endlocal

settings.gradle.kts

@@ -1,3 +1,5 @@
-
 rootProject.name = "tree-structure"
 
+include(":tree-structure-serialization")
+include(":tree-structure-coroutines")
+include(":tree-structure-compose")

src/commonMain/kotlin/com.github.adriankuta/datastructure/tree/ChildDeclarationInterface.kt

@@ -2,7 +2,7 @@ package com.github.adriankuta.datastructure.tree
 
 import kotlin.jvm.JvmSynthetic
 
-interface ChildDeclarationInterface<T> {
+public interface ChildDeclarationInterface<T> {
 
     /**
      * This method is used to easily create child in node.
@@ -20,5 +20,5 @@ interface ChildDeclarationInterface<T> {
      * @return New created TreeNode.
      */
     @JvmSynthetic
-    fun child(value: T, childDeclaration: ChildDeclaration<T>? = null): TreeNode<T>
+    public fun child(value: T, childDeclaration: ChildDeclaration<T>? = null): TreeNode<T>
 }

src/commonMain/kotlin/com.github.adriankuta/datastructure/tree/TreeNode.kt

@@ -9,16 +9,32 @@ import com.github.adriankuta.datastructure.tree.iterators.TreeNodeIterators.*
 import kotlin.jvm.JvmSynthetic
 
 /**
- * @param treeIterator Choose one of available iterators from [TreeNodeIterators]
+ * A node in a generic, mutable n-ary tree. Each node holds a [value], a reference to its [parent]
+ * and an ordered list of [children].
+ *
+ * Iterating a node (via [iterator], or the lazy [asSequence]/[preOrderSequence] extensions) visits
+ * the node and all of its descendants. Traversal and the [height]/[nodeCount]/[clear] helpers are
+ * implemented iteratively, so they are safe on arbitrarily deep trees.
+ *
+ * **Not thread-safe.** Nodes are mutable ([addChild]/[removeChild]/[clear] mutate the structure and
+ * parent pointers). Sharing a tree across threads requires external synchronization, and the tree
+ * must not be modified while it is being iterated.
+ *
+ * Equality is by reference (identity); use the `structurallyEquals` extension to compare two trees
+ * by value and shape.
+ *
+ * @param value the value stored in this node.
+ * @param treeIterator the default traversal order used by [iterator]. Prefer the
+ *   `asSequence(order)` / `preOrderSequence()` extensions to choose an order without mutating state.
  */
-open class TreeNode<T>(val value: T, var treeIterator: TreeNodeIterators = PreOrder) : Iterable<TreeNode<T>>, ChildDeclarationInterface<T> {
+public open class TreeNode<T>(public val value: T, public val treeIterator: TreeNodeIterators = PreOrder) : Iterable<TreeNode<T>>, ChildDeclarationInterface<T> {
 
     private var _parent: TreeNode<T>? = null
 
     /**
      * The converse notion of a child, an immediate ancestor.
      */
-    val parent: TreeNode<T>?
+    public val parent: TreeNode<T>?
         get() = _parent
 
     private val _children = mutableListOf<TreeNode<T>>()
@@ -26,28 +42,60 @@ open class TreeNode<T>(val value: T, var treeIterator: TreeNodeIterators = PreOr
     /**
      * A group of nodes with the same parent.
      */
-    val children: List<TreeNode<T>>
+    public val children: List<TreeNode<T>>
         get() = _children
 
     /**
      * Checks whether the current tree node is the root of the tree
      * @return `true` if the current tree node is root of the tree, `false` otherwise.
      */
-    val isRoot: Boolean
+    public val isRoot: Boolean
         get() = _parent == null
 
     /**
-     * Add new child to current node or root.
+     * Adds [child] as a direct child of this node.
      *
-     * @param child A node which will be directly connected to current node.
+     * @param child a node that is not already attached to a tree. To move a node that already has a
+     *   parent, call [detach] on it first.
+     * @throws TreeNodeException if [child] already has a parent, or if attaching it here would create
+     *   a cycle (i.e. [child] is this node or one of its ancestors).
      */
-    fun addChild(child: TreeNode<T>) {
+    public fun addChild(child: TreeNode<T>) {
+        if (child._parent != null) {
+            throw TreeNodeException("$child already has a parent; call detach() before re-attaching it.")
+        }
+        if (child === this) {
+            throw TreeNodeException("Adding $child here would create a cycle.")
+        }
+        // Only a node that already has its own subtree can contain `this` and thus form a cycle.
+        // Skipping this walk for leaves keeps building deep trees O(n) instead of O(n²).
+        if (child._children.isNotEmpty()) {
+            var ancestor: TreeNode<T>? = _parent
+            while (ancestor != null) {
+                if (ancestor === child) {
+                    throw TreeNodeException("Adding $child here would create a cycle.")
+                }
+                ancestor = ancestor._parent
+            }
+        }
         child._parent = this
         _children.add(child)
     }
 
+    /**
+     * Detaches this node from its parent, removing it from the parent's [children].
+     *
+     * @return `true` if this node was attached and is now detached; `false` if it was already a root.
+     */
+    public fun detach(): Boolean {
+        val currentParent = _parent ?: return false
+        currentParent._children.remove(this)
+        _parent = null
+        return true
+    }
+
     @JvmSynthetic
-    override fun child(value: T, childDeclaration: ChildDeclaration<T>?): TreeNode<T> {
+    public override fun child(value: T, childDeclaration: ChildDeclaration<T>?): TreeNode<T> {
         val newChild = TreeNode(value)
         newChild._parent = this
         if (childDeclaration != null)
@@ -57,43 +105,55 @@ open class TreeNode<T>(val value: T, var treeIterator: TreeNodeIterators = PreOr
     }
 
     /**
-     * Removes a single instance of the specified node from this tree, if it is present.
+     * Removes [child] from this node's direct [children], if present.
      *
-     * @return `true` if the node has been successfully removed; `false` if it was not present in the tree.
+     * This only removes a *direct* child of the receiver; it does not reach into other nodes. To
+     * remove a node from wherever it currently lives, call [detach] on it instead.
+     *
+     * @return `true` if [child] was a direct child and has been removed; `false` otherwise.
      */
-    fun removeChild(child: TreeNode<T>): Boolean {
-        println(child.value)
-        val removed = child._parent?._children?.remove(child)
-        child._parent = null
-        return removed ?: false
+    public fun removeChild(child: TreeNode<T>): Boolean {
+        val removed = _children.remove(child)
+        if (removed) child._parent = null
+        return removed
     }
 
     /**
      * This function go through tree and counts children. Root element is not counted.
      * @return All child and nested child count.
      */
-    fun nodeCount(): Int {
-        if (_children.isEmpty())
-            return 0
-        return _children.size +
-                _children.sumOf { it.nodeCount() }
+    public fun nodeCount(): Int {
+        var count = 0
+        val stack = ArrayDeque<TreeNode<T>>()
+        stack.addAll(_children)
+        while (stack.isNotEmpty()) {
+            val node = stack.removeLast()
+            count++
+            stack.addAll(node._children)
+        }
+        return count
     }
 
     /**
      * @return The number of edges on the longest path between current node and a descendant leaf.
      */
-    fun height(): Int {
-        val childrenMaxDepth = _children.map { it.height() }
-            .maxOrNull()
-            ?: -1 // -1 because this method counts nodes, and edges are always one less then nodes.
-        return childrenMaxDepth + 1
+    public fun height(): Int {
+        var maxDepth = 0
+        val stack = ArrayDeque<Pair<TreeNode<T>, Int>>()
+        stack.addLast(this to 0)
+        while (stack.isNotEmpty()) {
+            val (node, depthSoFar) = stack.removeLast()
+            if (depthSoFar > maxDepth) maxDepth = depthSoFar
+            node._children.forEach { stack.addLast(it to depthSoFar + 1) }
+        }
+        return maxDepth
     }
 
     /**
      * Distance is the number of edges along the shortest path between two nodes.
      * @return The distance between current node and the root.
      */
-    fun depth(): Int {
+    public fun depth(): Int {
         var depth = 0
         var tempParent = parent
 
@@ -105,44 +165,52 @@ open class TreeNode<T>(val value: T, var treeIterator: TreeNodeIterators = PreOr
     }
 
     /**
-     * Returns the collection of nodes, which connect the current node
-     * with its descendants
+     * Returns the chain of nodes from [descendant] up to and including this node, or `null` if
+     * [descendant] is not a strict descendant of this node.
      *
-     * @param descendant the bottom child node for which the path is calculated
-     * @return collection of nodes, which connect the current node with its descendants
-     * @throws TreeNodeException exception that may be thrown in case if the
-     *                           current node does not have such descendant or if the
-     *                           specified tree node is root
+     * @param descendant the node to walk up from.
+     * @return the path `[descendant, …, this]`, or `null` if [descendant] is the root or is not
+     *   located in this node's subtree.
      */
-    @Throws(TreeNodeException::class)
-    fun path(descendant: TreeNode<T>): List<TreeNode<T>> {
-
+    public fun path(descendant: TreeNode<T>): List<TreeNode<T>>? {
+        if (descendant.isRoot) return null
         val path = mutableListOf<TreeNode<T>>()
         var node = descendant
         path.add(node)
         while (!node.isRoot) {
             node = node.parent!!
             path.add(node)
-            if (node == this)
-                return path
+            if (node == this) return path
         }
-        throw TreeNodeException("The specified tree node $descendant is not the descendant of tree node $this")
+        return null
     }
 
     /**
-     * Remove all children from root and every node in tree.
+     * Removes every descendant of this node. Afterwards [children] is empty and all former
+     * descendants are detached (their parent is `null`). This node itself stays attached to its own
+     * parent.
      */
-    fun clear() {
-        _parent = null
-        _children.forEach { it.clear() }
+    public fun clear() {
+        val descendants = ArrayDeque<TreeNode<T>>()
+        val stack = ArrayDeque<TreeNode<T>>()
+        stack.addAll(_children)
+        while (stack.isNotEmpty()) {
+            val node = stack.removeLast()
+            descendants.addLast(node)
+            stack.addAll(node._children)
+        }
+        descendants.forEach { node ->
+            node._parent = null
+            node._children.clear()
+        }
         _children.clear()
     }
 
-    override fun toString(): String {
+    public override fun toString(): String {
         return value.toString()
     }
 
-    fun prettyString(): String {
+    public fun prettyString(): String {
         val stringBuilder = StringBuilder()
         print(stringBuilder, "", "")
         return stringBuilder.toString()
@@ -164,9 +232,14 @@ open class TreeNode<T>(val value: T, var treeIterator: TreeNodeIterators = PreOr
     }
 
     /**
-     * You can change default iterator by changing [treeIterator] property.
+     * Returns an iterator over this node and its descendants using the default [treeIterator] order.
+     * Use [iterator] with an explicit order, or the `asSequence(order)` extension, to traverse in a
+     * different order without changing this node's default.
      */
-    override fun iterator(): Iterator<TreeNode<T>> = when (treeIterator) {
+    public override fun iterator(): Iterator<TreeNode<T>> = iterator(treeIterator)
+
+    /** Returns an iterator over this node and its descendants in the given [order]. */
+    public fun iterator(order: TreeNodeIterators): Iterator<TreeNode<T>> = when (order) {
         PreOrder -> PreOrderTreeIterator(this)
         PostOrder -> PostOrderTreeIterator(this)
         LevelOrder -> LevelOrderTreeIterator(this)

src/commonMain/kotlin/com.github.adriankuta/datastructure/tree/TreeNodeExt.kt

@@ -3,7 +3,7 @@ package com.github.adriankuta.datastructure.tree
 import com.github.adriankuta.datastructure.tree.iterators.TreeNodeIterators
 import kotlin.jvm.JvmSynthetic
 
-typealias ChildDeclaration<T> = ChildDeclarationInterface<T>.() -> Unit
+public typealias ChildDeclaration<T> = ChildDeclarationInterface<T>.() -> Unit
 
 /**
  * This method can be used to initialize new tree.
@@ -14,7 +14,7 @@ typealias ChildDeclaration<T> = ChildDeclarationInterface<T>.() -> Unit
  * @see [ChildDeclarationInterface.child]
  */
 @JvmSynthetic
-inline fun <reified T> tree(
+public inline fun <reified T> tree(
     root: T,
     defaultIterator: TreeNodeIterators = TreeNodeIterators.PreOrder,
     childDeclaration: ChildDeclaration<T>

src/commonMain/kotlin/com.github.adriankuta/datastructure/tree/TreeNodeFunctionalExt.kt

@@ -0,0 +1,65 @@
+package com.github.adriankuta.datastructure.tree
+
+/** Returns the first node (pre-order) whose value matches [predicate], or `null`. Short-circuits. */
+public fun <T> TreeNode<T>.findNode(predicate: (T) -> Boolean): TreeNode<T>? =
+    preOrderSequence().firstOrNull { predicate(it.value) }
+
+/** All nodes (pre-order) whose value matches [predicate]. */
+public fun <T> TreeNode<T>.filterNodes(predicate: (T) -> Boolean): List<TreeNode<T>> =
+    preOrderSequence().filter { predicate(it.value) }.toList()
+
+/** `true` if any node's value matches [predicate]. Short-circuits. */
+public fun <T> TreeNode<T>.anyNode(predicate: (T) -> Boolean): Boolean =
+    preOrderSequence().any { predicate(it.value) }
+
+/** `true` if every node's value matches [predicate]. Short-circuits. */
+public fun <T> TreeNode<T>.allNodes(predicate: (T) -> Boolean): Boolean =
+    preOrderSequence().all { predicate(it.value) }
+
+/** Counts nodes whose value matches [predicate]. */
+public fun <T> TreeNode<T>.countNodes(predicate: (T) -> Boolean): Int =
+    preOrderSequence().count { predicate(it.value) }
+
+/** Folds [operation] over all nodes in pre-order, starting from [initial]. */
+public fun <T, R> TreeNode<T>.foldNodes(initial: R, operation: (acc: R, node: TreeNode<T>) -> R): R =
+    preOrderSequence().fold(initial) { acc, node -> operation(acc, node) }
+
+/**
+ * Returns a new tree with the same shape whose values are produced by [transform]. The original is
+ * left untouched. Stack-safe (iterative), so it handles arbitrarily deep trees.
+ */
+public fun <T, R> TreeNode<T>.mapValues(transform: (T) -> R): TreeNode<R> {
+    val newRoot = TreeNode(transform(value), treeIterator)
+    val stack = ArrayDeque<Pair<TreeNode<T>, TreeNode<R>>>()
+    stack.addLast(this to newRoot)
+    while (stack.isNotEmpty()) {
+        val (source, target) = stack.removeLast()
+        source.children.forEach { child ->
+            val mappedChild = TreeNode(transform(child.value), child.treeIterator)
+            target.addChild(mappedChild)
+            stack.addLast(child to mappedChild)
+        }
+    }
+    return newRoot
+}
+
+/** Returns an independent deep copy of this subtree (same values, same shape, new nodes). */
+public fun <T> TreeNode<T>.deepCopy(): TreeNode<T> = mapValues { it }
+
+/**
+ * Structural equality: `true` when [other] holds the same values in the same shape. Unlike
+ * [TreeNode]'s reference equality, this compares the entire subtree. Stack-safe.
+ */
+public fun <T> TreeNode<T>.structurallyEquals(other: TreeNode<T>): Boolean {
+    val stack = ArrayDeque<Pair<TreeNode<T>, TreeNode<T>>>()
+    stack.addLast(this to other)
+    while (stack.isNotEmpty()) {
+        val (a, b) = stack.removeLast()
+        if (a.value != b.value) return false
+        if (a.children.size != b.children.size) return false
+        for (i in a.children.indices) {
+            stack.addLast(a.children[i] to b.children[i])
+        }
+    }
+    return true
+}

src/commonMain/kotlin/com.github.adriankuta/datastructure/tree/TreeNodeNavigationExt.kt

@@ -0,0 +1,41 @@
+package com.github.adriankuta.datastructure.tree
+
+/** `true` when this node has no children. */
+public val <T> TreeNode<T>.isLeaf: Boolean get() = children.isEmpty()
+
+/** The number of direct children of this node. */
+public val <T> TreeNode<T>.degree: Int get() = children.size
+
+/** Walks up the parent chain and returns the topmost ancestor (the tree root). */
+public fun <T> TreeNode<T>.root(): TreeNode<T> {
+    var node = this
+    var parent = node.parent
+    while (parent != null) {
+        node = parent
+        parent = node.parent
+    }
+    return node
+}
+
+/** The chain of ancestors from the immediate [parent] up to (and including) the root. */
+public fun <T> TreeNode<T>.ancestors(): List<TreeNode<T>> {
+    val result = mutableListOf<TreeNode<T>>()
+    var parent = this.parent
+    while (parent != null) {
+        result.add(parent)
+        parent = parent.parent
+    }
+    return result
+}
+
+/** The other children of this node's parent (excludes this node). Empty for the root. */
+public fun <T> TreeNode<T>.siblings(): List<TreeNode<T>> =
+    parent?.children?.filter { it !== this } ?: emptyList()
+
+/** All leaf nodes in this subtree, in pre-order. */
+public fun <T> TreeNode<T>.leaves(): List<TreeNode<T>> =
+    preOrderSequence().filter { it.isLeaf }.toList()
+
+/** All nodes in this subtree except this node, in pre-order. */
+public fun <T> TreeNode<T>.descendants(): List<TreeNode<T>> =
+    preOrderSequence().filter { it !== this }.toList()

src/commonMain/kotlin/com.github.adriankuta/datastructure/tree/TreeNodeSequenceExt.kt

@@ -0,0 +1,31 @@
+package com.github.adriankuta.datastructure.tree
+
+import com.github.adriankuta.datastructure.tree.iterators.LevelOrderTreeIterator
+import com.github.adriankuta.datastructure.tree.iterators.PostOrderTreeIterator
+import com.github.adriankuta.datastructure.tree.iterators.PreOrderTreeIterator
+import com.github.adriankuta.datastructure.tree.iterators.TreeNodeIterators
+
+/**
+ * Lazily traverses this subtree in the given [order] as a [Sequence], without forcing the whole
+ * traversal up front. Pairs with the Kotlin stdlib, e.g.
+ * `root.asSequence().map { it.value }.firstOrNull { it == target }`.
+ */
+public fun <T> TreeNode<T>.asSequence(
+    order: TreeNodeIterators = TreeNodeIterators.PreOrder,
+): Sequence<TreeNode<T>> {
+    val self = this
+    return when (order) {
+        TreeNodeIterators.PreOrder -> Sequence { PreOrderTreeIterator(self) }
+        TreeNodeIterators.PostOrder -> Sequence { PostOrderTreeIterator(self) }
+        TreeNodeIterators.LevelOrder -> Sequence { LevelOrderTreeIterator(self) }
+    }
+}
+
+/** Lazy pre-order traversal as a [Sequence]. */
+public fun <T> TreeNode<T>.preOrderSequence(): Sequence<TreeNode<T>> = asSequence(TreeNodeIterators.PreOrder)
+
+/** Lazy post-order traversal as a [Sequence]. */
+public fun <T> TreeNode<T>.postOrderSequence(): Sequence<TreeNode<T>> = asSequence(TreeNodeIterators.PostOrder)
+
+/** Lazy level-order (breadth-first) traversal as a [Sequence]. */
+public fun <T> TreeNode<T>.levelOrderSequence(): Sequence<TreeNode<T>> = asSequence(TreeNodeIterators.LevelOrder)

src/commonMain/kotlin/com.github.adriankuta/datastructure/tree/exceptions/TreeNodeException.kt

@@ -2,5 +2,5 @@ package com.github.adriankuta.datastructure.tree.exceptions
 
 import kotlin.jvm.JvmOverloads
 
-class TreeNodeException @JvmOverloads constructor(message: String? = null, cause: Throwable? = null) :
+public class TreeNodeException @JvmOverloads constructor(message: String? = null, cause: Throwable? = null) :
     RuntimeException(message, cause)

src/commonMain/kotlin/com.github.adriankuta/datastructure/tree/iterators/LevelOrderTreeIterator.kt

@@ -20,7 +20,7 @@ import com.github.adriankuta.datastructure.tree.TreeNode
  * Output: 1 2 3 4 5 6 7 8 9 10 11 12 13
  * ```
  */
-class LevelOrderTreeIterator<T>(root: TreeNode<T>) : Iterator<TreeNode<T>> {
+public class LevelOrderTreeIterator<T>(root: TreeNode<T>) : Iterator<TreeNode<T>> {
 
     private val stack = ArrayDeque<TreeNode<T>>()
 
@@ -28,9 +28,9 @@ class LevelOrderTreeIterator<T>(root: TreeNode<T>) : Iterator<TreeNode<T>> {
         stack.addLast(root)
     }
 
-    override fun hasNext(): Boolean = stack.isNotEmpty()
+    public override fun hasNext(): Boolean = stack.isNotEmpty()
 
-    override fun next(): TreeNode<T> {
+    public override fun next(): TreeNode<T> {
         val node =  stack.removeFirst()
         node.children
             .forEach { stack.addLast(it) }

src/commonMain/kotlin/com.github.adriankuta/datastructure/tree/iterators/PostOrderTreeIterator.kt

@@ -20,29 +20,24 @@ import com.github.adriankuta.datastructure.tree.TreeNode
  * Output: 10 5 11 12 13 6 2 3 7 8 9 4 1
  * ```
  */
-class PostOrderTreeIterator<T>(root: TreeNode<T>) : Iterator<TreeNode<T>> {
+public class PostOrderTreeIterator<T>(root: TreeNode<T>) : Iterator<TreeNode<T>> {
 
-    private val stack = ArrayDeque<TreeNode<T>>()
+    private val result = ArrayDeque<TreeNode<T>>()
 
     init {
-        stack.addAll(getChildrenStack(root))
-    }
-
-    override fun hasNext(): Boolean = stack.isNotEmpty()
-
-    override fun next(): TreeNode<T> {
-        return stack.removeFirst()
-    }
-
-    private fun getChildrenStack(node: TreeNode<T>): ArrayDeque<TreeNode<T>> {
+        // Iterative post-order: pop a node, prepend it to `result`, then push its children
+        // left-to-right. Reading `result` front-to-back yields post-order — without the deep
+        // recursion that overflowed the stack on degenerate (linear) trees.
         val stack = ArrayDeque<TreeNode<T>>()
-        if(node.children.isEmpty()) {
-            return ArrayDeque(listOf(node))
+        stack.addLast(root)
+        while (stack.isNotEmpty()) {
+            val node = stack.removeLast()
+            result.addFirst(node)
+            node.children.forEach { stack.addLast(it) }
         }
-        node.children.forEach {
-            stack.addAll(getChildrenStack(it))
-        }
-        stack.addLast(node)
-        return stack
     }
+
+    public override fun hasNext(): Boolean = result.isNotEmpty()
+
+    public override fun next(): TreeNode<T> = result.removeFirst()
 }

src/commonMain/kotlin/com.github.adriankuta/datastructure/tree/iterators/PreOrderTreeIterator.kt

@@ -20,7 +20,7 @@ import com.github.adriankuta.datastructure.tree.TreeNode
  * Output: 1 2 5 10 6 11 12 13 3 4 7 8 9
  * ```
  */
-class PreOrderTreeIterator<T>(root: TreeNode<T>) : Iterator<TreeNode<T>> {
+public class PreOrderTreeIterator<T>(root: TreeNode<T>) : Iterator<TreeNode<T>> {
 
     private val stack = ArrayDeque<TreeNode<T>>()
 
@@ -28,9 +28,9 @@ class PreOrderTreeIterator<T>(root: TreeNode<T>) : Iterator<TreeNode<T>> {
         stack.addLast(root)
     }
 
-    override fun hasNext(): Boolean = stack.isNotEmpty()
+    public override fun hasNext(): Boolean = stack.isNotEmpty()
 
-    override fun next(): TreeNode<T> {
+    public override fun next(): TreeNode<T> {
         val node = stack.removeLast()
         node.children
             .asReversed()

src/commonMain/kotlin/com.github.adriankuta/datastructure/tree/iterators/TreeNodeIterators.kt

@@ -5,7 +5,7 @@ package com.github.adriankuta.datastructure.tree.iterators
  * @see PostOrder
  * @see LevelOrder
  */
-enum class TreeNodeIterators {
+public enum class TreeNodeIterators {
     /**
      * Tree is iterated by using `Pre-order Traversal Algorithm"
      * The pre-order traversal is a topologically sorted one,

src/commonTest/kotlin/com.github.adriankuta/datastructure.tree/ExampleUnitTest.kt

@@ -1,16 +0,0 @@
-package com.github.adriankuta.datastructure.tree
-
-import kotlin.test.Test
-import kotlin.test.assertEquals
-
-/**
- * Example local unit test, which will execute on the development machine (host).
- *
- * See [testing documentation](http://d.android.com/tools/testing).
- */
-class ExampleUnitTest {
-    @Test
-    fun addition_isCorrect() {
-        assertEquals(4, 2 + 2)
-    }
-}

src/commonTest/kotlin/com.github.adriankuta/datastructure.tree/TreeNodeFunctionalTest.kt

@@ -0,0 +1,78 @@
+package com.github.adriankuta.datastructure.tree
+
+import kotlin.test.Test
+import kotlin.test.assertContentEquals
+import kotlin.test.assertEquals
+import kotlin.test.assertFalse
+import kotlin.test.assertNotSame
+import kotlin.test.assertNull
+import kotlin.test.assertSame
+import kotlin.test.assertTrue
+
+class TreeNodeFunctionalTest {
+
+    private fun sample() = tree(1) {
+        child(2) {
+            child(4)
+            child(5)
+        }
+        child(3) {
+            child(6)
+        }
+    }
+
+    @Test
+    fun findNode() {
+        assertEquals(6, sample().findNode { it == 6 }?.value)
+        assertNull(sample().findNode { it == 99 })
+    }
+
+    @Test
+    fun filterNodes() =
+        assertContentEquals(listOf(2, 4, 6), sample().filterNodes { it % 2 == 0 }.map { it.value })
+
+    @Test
+    fun anyNode() {
+        assertTrue(sample().anyNode { it == 6 })
+        assertFalse(sample().anyNode { it == 99 })
+    }
+
+    @Test
+    fun allNodes() {
+        assertTrue(sample().allNodes { it > 0 })
+        assertFalse(sample().allNodes { it < 5 })
+    }
+
+    @Test
+    fun countNodes() = assertEquals(3, sample().countNodes { it > 3 })
+
+    @Test
+    fun foldNodes() = assertEquals(21, sample().foldNodes(0) { acc, node -> acc + node.value })
+
+    @Test
+    fun mapPreservesStructureAndTransformsValues() {
+        val mapped = sample().mapValues { it * 10 }
+        assertContentEquals(
+            listOf(10, 20, 40, 50, 30, 60),
+            mapped.preOrderSequence().map { it.value }.toList(),
+        )
+    }
+
+    @Test
+    fun deepCopyIsStructurallyEqualButDistinct() {
+        val original = sample()
+        val copy = original.deepCopy()
+        assertNotSame(original, copy)
+        assertTrue(original.structurallyEquals(copy))
+    }
+
+    @Test
+    fun structurallyEqualsDistinguishesByValueAndShape() {
+        assertTrue(sample().structurallyEquals(sample()))
+        val different = tree(1) {
+            child(2) { child(4) }
+            child(3) { child(6) }
+        }
+        assertFalse(sample().structurallyEquals(different))
+    }
+}

src/commonTest/kotlin/com.github.adriankuta/datastructure.tree/TreeNodeNavigationTest.kt

@@ -0,0 +1,66 @@
+package com.github.adriankuta.datastructure.tree
+
+import kotlin.test.Test
+import kotlin.test.assertContentEquals
+import kotlin.test.assertEquals
+import kotlin.test.assertFalse
+import kotlin.test.assertSame
+import kotlin.test.assertTrue
+
+class TreeNodeNavigationTest {
+
+    private val root = TreeNode(1)
+    private val n2 = TreeNode(2)
+    private val n3 = TreeNode(3)
+    private val n4 = TreeNode(4)
+    private val n5 = TreeNode(5)
+    private val n6 = TreeNode(6)
+
+    init {
+        root.addChild(n2)
+        root.addChild(n3)
+        n2.addChild(n4)
+        n2.addChild(n5)
+        n3.addChild(n6)
+    }
+
+    @Test
+    fun isLeaf() {
+        assertTrue(n4.isLeaf)
+        assertFalse(root.isLeaf)
+    }
+
+    @Test
+    fun degree() {
+        assertEquals(2, root.degree)
+        assertEquals(0, n4.degree)
+    }
+
+    @Test
+    fun root() {
+        assertSame(root, n6.root())
+        assertSame(root, root.root())
+    }
+
+    @Test
+    fun ancestors() {
+        assertContentEquals(listOf(n2, root), n4.ancestors())
+        assertContentEquals(emptyList(), root.ancestors())
+    }
+
+    @Test
+    fun siblings() {
+        assertContentEquals(listOf(n5), n4.siblings())
+        assertContentEquals(emptyList(), root.siblings())
+    }
+
+    @Test
+    fun leaves() {
+        assertContentEquals(listOf(n4, n5, n6), root.leaves())
+    }
+
+    @Test
+    fun descendants() {
+        assertContentEquals(listOf(n2, n4, n5, n3, n6), root.descendants())
+    }
+}

src/commonTest/kotlin/com.github.adriankuta/datastructure.tree/TreeNodeSequenceTest.kt

@@ -0,0 +1,46 @@
+package com.github.adriankuta.datastructure.tree
+
+import com.github.adriankuta.datastructure.tree.iterators.TreeNodeIterators
+import kotlin.test.Test
+import kotlin.test.assertContentEquals
+import kotlin.test.assertEquals
+
+class TreeNodeSequenceTest {
+
+    private fun sample() = tree(1) {
+        child(2) {
+            child(4)
+            child(5)
+        }
+        child(3) {
+            child(6)
+        }
+    }
+
+    @Test
+    fun preOrderSequence() =
+        assertContentEquals(listOf(1, 2, 4, 5, 3, 6), sample().preOrderSequence().map { it.value }.toList())
+
+    @Test
+    fun postOrderSequence() =
+        assertContentEquals(listOf(4, 5, 2, 6, 3, 1), sample().postOrderSequence().map { it.value }.toList())
+
+    @Test
+    fun levelOrderSequence() =
+        assertContentEquals(listOf(1, 2, 3, 4, 5, 6), sample().levelOrderSequence().map { it.value }.toList())
+
+    @Test
+    fun asSequenceDefaultsToPreOrder() =
+        assertContentEquals(listOf(1, 2, 4, 5, 3, 6), sample().asSequence().map { it.value }.toList())
+
+    @Test
+    fun asSequenceHonorsExplicitOrder() =
+        assertContentEquals(
+            listOf(1, 2, 3, 4, 5, 6),
+            sample().asSequence(TreeNodeIterators.LevelOrder).map { it.value }.toList(),
+        )
+
+    @Test
+    fun sequenceShortCircuitsLazily() =
+        assertEquals(4, sample().preOrderSequence().map { it.value }.first { it == 4 })
+}

src/commonTest/kotlin/com.github.adriankuta/datastructure.tree/TreeNodeStackSafetyTest.kt

@@ -0,0 +1,47 @@
+package com.github.adriankuta.datastructure.tree
+
+import com.github.adriankuta.datastructure.tree.iterators.TreeNodeIterators
+import kotlin.test.Test
+import kotlin.test.assertEquals
+
+/**
+ * A deep, degenerate (linear) tree must not overflow the call stack. These tests build a chain
+ * thousands of nodes deep — recursive implementations of [TreeNode.height], [TreeNode.nodeCount]
+ * and the post-order iterator blow the stack here, so they pin the iterative rewrites.
+ */
+class TreeNodeStackSafetyTest {
+
+    private val depth = 50_000
+
+    private fun deepChain(): TreeNode<Int> {
+        val root = TreeNode(0)
+        var current = root
+        for (i in 1..depth) {
+            val child = TreeNode(i)
+            current.addChild(child)
+            current = child
+        }
+        return root
+    }
+
+    @Test
+    fun heightDoesNotOverflowOnDeepTree() {
+        assertEquals(depth, deepChain().height())
+    }
+
+    @Test
+    fun nodeCountDoesNotOverflowOnDeepTree() {
+        // nodeCount() excludes the root, so a chain of `depth` extra nodes counts as `depth`.
+        assertEquals(depth, deepChain().nodeCount())
+    }
+
+    @Test
+    fun postOrderIterationDoesNotOverflowOnDeepTree() {
+        assertEquals(depth + 1, deepChain().asSequence(TreeNodeIterators.PostOrder).count())
+    }
+
+    @Test
+    fun preOrderIterationDoesNotOverflowOnDeepTree() {
+        assertEquals(depth + 1, deepChain().asSequence(TreeNodeIterators.PreOrder).count())
+    }
+}

src/commonTest/kotlin/com.github.adriankuta/datastructure.tree/TreeNodeTest.kt

@@ -4,7 +4,9 @@ import com.github.adriankuta.datastructure.tree.iterators.TreeNodeIterators
 import kotlin.test.Test
 import kotlin.test.assertContentEquals
 import kotlin.test.assertEquals
+import kotlin.test.assertFalse
 import kotlin.test.assertNull
+import kotlin.test.assertTrue
 
 class TreeNodeTest {
 
@@ -49,7 +51,7 @@ class TreeNodeTest {
         )
 
         root.removeChild(curdNode)
-        root.removeChild(gingerTeaNode)
+        gingerTeaNode.detach()
         assertEquals(
             "Root\n" +
                     "└── Beverages\n" +
@@ -62,6 +64,18 @@ class TreeNodeTest {
         )
     }
 
+    @Test
+    fun removeChildReturnsTrueWhenPresentFalseOtherwise() {
+        val root = TreeNode("Root")
+        val child = TreeNode("Child")
+        root.addChild(child)
+
+        assertTrue(root.removeChild(child), "Removing a present child returns true")
+        assertFalse(root.removeChild(child), "Removing an already-removed child returns false")
+        assertNull(child.parent, "Removed child is detached from its parent")
+        assertEquals(emptyList(), root.children)
+    }
+
     @Test
     fun clearTest() {
         val root = TreeNode("Root")

src/commonTest/kotlin/com.github.adriankuta/datastructure.tree/TreeNodeUtilitiesTest.kt

@@ -0,0 +1,53 @@
+package com.github.adriankuta.datastructure.tree
+
+import kotlin.test.Test
+import kotlin.test.assertContentEquals
+import kotlin.test.assertEquals
+import kotlin.test.assertNull
+
+class TreeNodeUtilitiesTest {
+
+    private val root = TreeNode(1)
+    private val a = TreeNode(2)
+    private val b = TreeNode(3)
+
+    init {
+        root.addChild(a)
+        a.addChild(b)
+    }
+
+    @Test
+    fun nodeCountCountsDescendantsExcludingRoot() {
+        assertEquals(0, TreeNode("solo").nodeCount())
+        assertEquals(2, root.nodeCount())
+    }
+
+    @Test
+    fun heightIsLongestEdgePathToLeaf() {
+        assertEquals(0, TreeNode("solo").height())
+        assertEquals(2, root.height())
+        assertEquals(1, a.height())
+    }
+
+    @Test
+    fun depthIsDistanceToRoot() {
+        assertEquals(0, root.depth())
+        assertEquals(1, a.depth())
+        assertEquals(2, b.depth())
+    }
+
+    @Test
+    fun pathReturnsDescendantToReceiverChain() {
+        assertContentEquals(listOf(b, a, root), root.path(b))
+    }
+
+    @Test
+    fun pathReturnsNullWhenNotADescendant() {
+        assertNull(root.path(TreeNode(99)))
+    }
+
+    @Test
+    fun pathReturnsNullWhenDescendantIsRootItself() {
+        assertNull(root.path(root))
+    }
+}

src/commonTest/kotlin/com.github.adriankuta/datastructure.tree/TreeNodeV4Test.kt

@@ -0,0 +1,105 @@
+package com.github.adriankuta.datastructure.tree
+
+import com.github.adriankuta.datastructure.tree.exceptions.TreeNodeException
+import com.github.adriankuta.datastructure.tree.iterators.TreeNodeIterators
+import kotlin.test.Test
+import kotlin.test.assertContentEquals
+import kotlin.test.assertEquals
+import kotlin.test.assertFailsWith
+import kotlin.test.assertFalse
+import kotlin.test.assertNull
+import kotlin.test.assertSame
+import kotlin.test.assertTrue
+
+class TreeNodeV4Test {
+
+    @Test
+    fun addChildRejectsNodeThatAlreadyHasAParent() {
+        val a = TreeNode("a")
+        val b = TreeNode("b")
+        a.addChild(b)
+
+        val other = TreeNode("other")
+        assertFailsWith<TreeNodeException> { other.addChild(b) }
+    }
+
+    @Test
+    fun addChildRejectsCycles() {
+        val root = TreeNode("root")
+        val child = TreeNode("child")
+        root.addChild(child)
+
+        // Attaching an ancestor under its own descendant would create a cycle.
+        assertFailsWith<TreeNodeException> { child.addChild(root) }
+        // Attaching a node under itself is also a cycle.
+        assertFailsWith<TreeNodeException> { root.addChild(root) }
+    }
+
+    @Test
+    fun detachRemovesFromParent() {
+        val root = TreeNode("root")
+        val child = TreeNode("child")
+        root.addChild(child)
+
+        assertTrue(child.detach())
+        assertNull(child.parent)
+        assertContentEquals(emptyList(), root.children)
+        // Detached node can now be re-attached elsewhere.
+        val newParent = TreeNode("newParent")
+        newParent.addChild(child)
+        assertSame(newParent, child.parent)
+    }
+
+    @Test
+    fun detachOnRootReturnsFalse() {
+        assertFalse(TreeNode("root").detach())
+    }
+
+    @Test
+    fun removeChildOnlyRemovesDirectChildren() {
+        val root = TreeNode("root")
+        val parent = TreeNode("parent")
+        val grandchild = TreeNode("grandchild")
+        root.addChild(parent)
+        parent.addChild(grandchild)
+
+        // grandchild is not a direct child of root -> no-op, returns false.
+        assertFalse(root.removeChild(grandchild))
+        assertSame(parent, grandchild.parent)
+
+        // direct child removal works.
+        assertTrue(parent.removeChild(grandchild))
+        assertNull(grandchild.parent)
+    }
+
+    @Test
+    fun clearOnNonRootKeepsItAttachedToItsParent() {
+        val root = TreeNode("root")
+        val branch = TreeNode("branch")
+        val leaf = TreeNode("leaf")
+        root.addChild(branch)
+        branch.addChild(leaf)
+
+        branch.clear()
+
+        assertContentEquals(emptyList(), branch.children)
+        assertSame(root, branch.parent)          // branch stays attached to root
+        assertContentEquals(listOf(branch), root.children)
+        assertNull(leaf.parent)                  // former descendant is detached
+    }
+
+    @Test
+    fun iteratorAcceptsExplicitOrderWithoutMutatingDefault() {
+        val tree = tree(1) {
+            child(2) { child(4) }
+            child(3)
+        }
+
+        val postOrder = tree.iterator(TreeNodeIterators.PostOrder).asSequence().map { it.value }.toList()
+        assertContentEquals(listOf(4, 2, 3, 1), postOrder)
+
+        // Default order is unchanged (PreOrder).
+        assertEquals(TreeNodeIterators.PreOrder, tree.treeIterator)
+        assertContentEquals(listOf(1, 2, 4, 3), tree.map { it.value })
+    }
+}

src/jvmMain/kotlin/Example.ws.kts

@@ -1,14 +0,0 @@
-import com.github.adriankuta.datastructure.tree.tree
-
-val root =
-    tree("World") {
-        child("North America") {
-            child("USA")
-        }
-        child("Europe") {
-            child("Poland")
-            child("Germany")
-        }
-    }
-
-print(root.prettyString())

tree-structure-compose/api/tree-structure-compose.api

@@ -0,0 +1,4 @@
+public final class com/github/adriankuta/datastructure/tree/compose/LazyTreeKt {
+	public static final fun LazyTree (Lcom/github/adriankuta/datastructure/tree/TreeNode;Landroidx/compose/ui/Modifier;ZLkotlin/jvm/functions/Function6;Landroidx/compose/runtime/Composer;II)V
+}
+

tree-structure-compose/build.gradle.kts

@@ -0,0 +1,74 @@
+import org.jetbrains.kotlin.gradle.ExperimentalWasmDsl
+
+plugins {
+    alias(libs.plugins.kotlinMultiplatform)
+    alias(libs.plugins.composeMultiplatform)
+    alias(libs.plugins.composeCompiler)
+    alias(libs.plugins.dokka)
+    alias(libs.plugins.mavenPublish)
+    signing
+}
+
+group = "com.github.adriankuta"
+version = rootProject.version
+
+mavenPublishing {
+    publishToMavenCentral(automaticRelease = false)
+    signAllPublications()
+
+    coordinates("com.github.adriankuta", "tree-structure-compose", version.toString())
+
+    pom {
+        name.set("Tree Data Structure — Compose Multiplatform")
+        description.set("A LazyTree composable (expand/collapse, lazy rendering) for the tree-structure library.")
+        url.set("https://github.com/AdrianKuta/Tree-Data-Structure")
+        licenses {
+            license {
+                name.set("MIT License")
+                url.set("https://opensource.org/licenses/MIT")
+                distribution.set("repo")
+            }
+        }
+        developers {
+            developer {
+                id.set("AdrianKuta")
+                name.set("Adrian Kuta")
+                email.set("adrian.kuta93@gmail.com")
+            }
+        }
+        scm {
+            url.set("https://github.com/AdrianKuta/Tree-Data-Structure")
+            connection.set("scm:git:https://github.com/AdrianKuta/Tree-Data-Structure.git")
+            developerConnection.set("scm:git:ssh://git@github.com/AdrianKuta/Tree-Data-Structure.git")
+        }
+    }
+}
+
+repositories {
+    mavenCentral()
+    google()
+}
+
+kotlin {
+    explicitApi()
+    jvmToolchain(21)
+
+    jvm()
+
+    @OptIn(ExperimentalWasmDsl::class)
+    wasmJs {
+        browser()
+    }
+
+    iosX64()
+    iosArm64()
+    iosSimulatorArm64()
+
+    sourceSets {
+        commonMain.dependencies {
+            api(project(":"))
+            implementation(compose.runtime)
+            implementation(compose.foundation)
+        }
+    }
+}

tree-structure-compose/src/commonMain/kotlin/com.github.adriankuta/datastructure/tree/compose/LazyTree.kt

@@ -0,0 +1,71 @@
+package com.github.adriankuta.datastructure.tree.compose
+
+import androidx.compose.foundation.lazy.LazyColumn
+import androidx.compose.runtime.Composable
+import androidx.compose.runtime.mutableStateMapOf
+import androidx.compose.runtime.remember
+import androidx.compose.ui.Modifier
+import com.github.adriankuta.datastructure.tree.TreeNode
+
+/**
+ * A lazily-rendered, expand/collapse tree for Compose Multiplatform. Only the currently-visible
+ * nodes are composed, so it scales to large trees. Expansion state is remembered internally, keyed
+ * by node identity.
+ *
+ * ```
+ * LazyTree(root) { node, depth, expanded, toggle ->
+ *     Row(Modifier.padding(start = (depth * 16).dp).clickable(onClick = toggle)) {
+ *         if (!node.isLeaf) Text(if (expanded) "▾" else "▸")
+ *         Text(node.value.toString())
+ *     }
+ * }
+ * ```
+ *
+ * @param root the root of the tree to display.
+ * @param modifier the [Modifier] applied to the underlying [LazyColumn].
+ * @param initiallyExpanded whether nodes start expanded.
+ * @param nodeContent renders a single node. Receives the node, its depth (root = 0), whether it is
+ *   expanded, and a `toggle` callback that flips this node's expansion state.
+ */
+@Composable
+public fun <T> LazyTree(
+    root: TreeNode<T>,
+    modifier: Modifier = Modifier,
+    initiallyExpanded: Boolean = true,
+    nodeContent: @Composable (node: TreeNode<T>, depth: Int, expanded: Boolean, toggle: () -> Unit) -> Unit,
+) {
+    val expansion = remember(root) { mutableStateMapOf<TreeNode<T>, Boolean>() }
+    val isExpanded: (TreeNode<T>) -> Boolean = { node -> expansion[node] ?: initiallyExpanded }
+
+    val visible = flattenVisible(root, isExpanded)
+
+    LazyColumn(modifier = modifier) {
+        items(visible.size) { index ->
+            val (node, depth) = visible[index]
+            nodeContent(node, depth, isExpanded(node)) {
+                expansion[node] = !isExpanded(node)
+            }
+        }
+    }
+}
+
+/**
+ * Flattens the tree into the list of currently-visible `(node, depth)` pairs in pre-order, skipping
+ * the subtrees of collapsed nodes. Iterative, so it is safe on deep trees.
+ */
+private fun <T> flattenVisible(
+    root: TreeNode<T>,
+    isExpanded: (TreeNode<T>) -> Boolean,
+): List<Pair<TreeNode<T>, Int>> {
+    val result = mutableListOf<Pair<TreeNode<T>, Int>>()
+    val stack = ArrayDeque<Pair<TreeNode<T>, Int>>()
+    stack.addLast(root to 0)
+    while (stack.isNotEmpty()) {
+        val (node, depth) = stack.removeLast()
+        result.add(node to depth)
+        if (isExpanded(node)) {
+            node.children.asReversed().forEach { child -> stack.addLast(child to depth + 1) }
+        }
+    }
+    return result
+}

tree-structure-coroutines/api/tree-structure-coroutines.api

@@ -0,0 +1,8 @@
+public final class com/github/adriankuta/datastructure/tree/coroutines/TreeNodeFlowExtKt {
+	public static final fun asFlow (Lcom/github/adriankuta/datastructure/tree/TreeNode;Lcom/github/adriankuta/datastructure/tree/iterators/TreeNodeIterators;)Lkotlinx/coroutines/flow/Flow;
+	public static synthetic fun asFlow$default (Lcom/github/adriankuta/datastructure/tree/TreeNode;Lcom/github/adriankuta/datastructure/tree/iterators/TreeNodeIterators;ILjava/lang/Object;)Lkotlinx/coroutines/flow/Flow;
+	public static final fun levelOrderFlow (Lcom/github/adriankuta/datastructure/tree/TreeNode;)Lkotlinx/coroutines/flow/Flow;
+	public static final fun postOrderFlow (Lcom/github/adriankuta/datastructure/tree/TreeNode;)Lkotlinx/coroutines/flow/Flow;
+	public static final fun preOrderFlow (Lcom/github/adriankuta/datastructure/tree/TreeNode;)Lkotlinx/coroutines/flow/Flow;
+}
+

tree-structure-coroutines/build.gradle.kts

@@ -0,0 +1,89 @@
+import org.jetbrains.kotlin.gradle.ExperimentalWasmDsl
+
+plugins {
+    alias(libs.plugins.kotlinMultiplatform)
+    alias(libs.plugins.dokka)
+    alias(libs.plugins.mavenPublish)
+    signing
+}
+
+group = "com.github.adriankuta"
+version = rootProject.version
+
+mavenPublishing {
+    publishToMavenCentral(automaticRelease = false)
+    signAllPublications()
+
+    coordinates("com.github.adriankuta", "tree-structure-coroutines", version.toString())
+
+    pom {
+        name.set("Tree Data Structure — coroutines")
+        description.set("kotlinx.coroutines Flow traversal for the tree-structure library.")
+        url.set("https://github.com/AdrianKuta/Tree-Data-Structure")
+        licenses {
+            license {
+                name.set("MIT License")
+                url.set("https://opensource.org/licenses/MIT")
+                distribution.set("repo")
+            }
+        }
+        developers {
+            developer {
+                id.set("AdrianKuta")
+                name.set("Adrian Kuta")
+                email.set("adrian.kuta93@gmail.com")
+            }
+        }
+        scm {
+            url.set("https://github.com/AdrianKuta/Tree-Data-Structure")
+            connection.set("scm:git:https://github.com/AdrianKuta/Tree-Data-Structure.git")
+            developerConnection.set("scm:git:ssh://git@github.com/AdrianKuta/Tree-Data-Structure.git")
+        }
+    }
+}
+
+repositories {
+    mavenCentral()
+}
+
+kotlin {
+    explicitApi()
+    jvmToolchain(21)
+
+    jvm()
+
+    js(IR) {
+        browser()
+        nodejs()
+    }
+
+    @OptIn(ExperimentalWasmDsl::class)
+    wasmJs {
+        browser()
+        nodejs()
+    }
+
+    iosX64()
+    iosArm64()
+    iosSimulatorArm64()
+
+    val hostOs = System.getProperty("os.name")
+    val isMingwX64 = hostOs.startsWith("Windows")
+    when {
+        hostOs == "Mac OS X" -> macosX64("native")
+        hostOs == "Linux" -> linuxX64("native")
+        isMingwX64 -> mingwX64("native")
+        else -> throw GradleException("Host OS is not supported in Kotlin/Native.")
+    }
+
+    sourceSets {
+        commonMain.dependencies {
+            api(project(":"))
+            api(libs.kotlinx.coroutines.core)
+        }
+        commonTest.dependencies {
+            implementation(kotlin("test"))
+            implementation(libs.kotlinx.coroutines.test)
+        }
+    }
+}

tree-structure-coroutines/src/commonMain/kotlin/com.github.adriankuta/datastructure/tree/coroutines/TreeNodeFlowExt.kt

@@ -0,0 +1,24 @@
+package com.github.adriankuta.datastructure.tree.coroutines
+
+import com.github.adriankuta.datastructure.tree.TreeNode
+import com.github.adriankuta.datastructure.tree.asSequence
+import com.github.adriankuta.datastructure.tree.iterators.TreeNodeIterators
+import kotlinx.coroutines.flow.Flow
+import kotlinx.coroutines.flow.asFlow
+
+/**
+ * Emits this node and all of its descendants as a cold [Flow], traversed in the given [order].
+ * Useful for plugging tree traversal into coroutine/Flow pipelines (e.g. in a ViewModel).
+ */
+public fun <T> TreeNode<T>.asFlow(
+    order: TreeNodeIterators = TreeNodeIterators.PreOrder,
+): Flow<TreeNode<T>> = asSequence(order).asFlow()
+
+/** Pre-order traversal as a cold [Flow]. */
+public fun <T> TreeNode<T>.preOrderFlow(): Flow<TreeNode<T>> = asFlow(TreeNodeIterators.PreOrder)
+
+/** Post-order traversal as a cold [Flow]. */
+public fun <T> TreeNode<T>.postOrderFlow(): Flow<TreeNode<T>> = asFlow(TreeNodeIterators.PostOrder)
+
+/** Level-order (breadth-first) traversal as a cold [Flow]. */
+public fun <T> TreeNode<T>.levelOrderFlow(): Flow<TreeNode<T>> = asFlow(TreeNodeIterators.LevelOrder)

tree-structure-coroutines/src/commonTest/kotlin/com.github.adriankuta/datastructure/tree/coroutines/TreeNodeFlowTest.kt

@@ -0,0 +1,35 @@
+package com.github.adriankuta.datastructure.tree.coroutines
+
+import com.github.adriankuta.datastructure.tree.iterators.TreeNodeIterators
+import com.github.adriankuta.datastructure.tree.tree
+import kotlinx.coroutines.flow.map
+import kotlinx.coroutines.flow.toList
+import kotlinx.coroutines.test.runTest
+import kotlin.test.Test
+import kotlin.test.assertEquals
+
+class TreeNodeFlowTest {
+
+    private fun sample() = tree(1) {
+        child(2) {
+            child(4)
+            child(5)
+        }
+        child(3) {
+            child(6)
+        }
+    }
+
+    @Test
+    fun preOrderFlowEmitsInPreOrder() = runTest {
+        assertEquals(listOf(1, 2, 4, 5, 3, 6), sample().preOrderFlow().map { it.value }.toList())
+    }
+
+    @Test
+    fun levelOrderFlowEmitsInLevelOrder() = runTest {
+        assertEquals(
+            listOf(1, 2, 3, 4, 5, 6),
+            sample().asFlow(TreeNodeIterators.LevelOrder).map { it.value }.toList(),
+        )
+    }
+}

tree-structure-serialization/api/tree-structure-serialization.api

@@ -0,0 +1,35 @@
+public final class com/github/adriankuta/datastructure/tree/serialization/TreeNodeDto {
+	public static final field Companion Lcom/github/adriankuta/datastructure/tree/serialization/TreeNodeDto$Companion;
+	public fun <init> (Ljava/lang/Object;Ljava/util/List;)V
+	public synthetic fun <init> (Ljava/lang/Object;Ljava/util/List;ILkotlin/jvm/internal/DefaultConstructorMarker;)V
+	public final fun component1 ()Ljava/lang/Object;
+	public final fun component2 ()Ljava/util/List;
+	public final fun copy (Ljava/lang/Object;Ljava/util/List;)Lcom/github/adriankuta/datastructure/tree/serialization/TreeNodeDto;
+	public static synthetic fun copy$default (Lcom/github/adriankuta/datastructure/tree/serialization/TreeNodeDto;Ljava/lang/Object;Ljava/util/List;ILjava/lang/Object;)Lcom/github/adriankuta/datastructure/tree/serialization/TreeNodeDto;
+	public fun equals (Ljava/lang/Object;)Z
+	public final fun getChildren ()Ljava/util/List;
+	public final fun getValue ()Ljava/lang/Object;
+	public fun hashCode ()I
+	public fun toString ()Ljava/lang/String;
+}
+
+public synthetic class com/github/adriankuta/datastructure/tree/serialization/TreeNodeDto$$serializer : kotlinx/serialization/internal/GeneratedSerializer {
+	public fun <init> (Lkotlinx/serialization/KSerializer;)V
+	public final fun childSerializers ()[Lkotlinx/serialization/KSerializer;
+	public final fun deserialize (Lkotlinx/serialization/encoding/Decoder;)Lcom/github/adriankuta/datastructure/tree/serialization/TreeNodeDto;
+	public synthetic fun deserialize (Lkotlinx/serialization/encoding/Decoder;)Ljava/lang/Object;
+	public final fun getDescriptor ()Lkotlinx/serialization/descriptors/SerialDescriptor;
+	public final fun serialize (Lkotlinx/serialization/encoding/Encoder;Lcom/github/adriankuta/datastructure/tree/serialization/TreeNodeDto;)V
+	public synthetic fun serialize (Lkotlinx/serialization/encoding/Encoder;Ljava/lang/Object;)V
+	public final fun typeParametersSerializers ()[Lkotlinx/serialization/KSerializer;
+}
+
+public final class com/github/adriankuta/datastructure/tree/serialization/TreeNodeDto$Companion {
+	public final fun serializer (Lkotlinx/serialization/KSerializer;)Lkotlinx/serialization/KSerializer;
+}
+
+public final class com/github/adriankuta/datastructure/tree/serialization/TreeNodeDtoKt {
+	public static final fun toDto (Lcom/github/adriankuta/datastructure/tree/TreeNode;)Lcom/github/adriankuta/datastructure/tree/serialization/TreeNodeDto;
+	public static final fun toTreeNode (Lcom/github/adriankuta/datastructure/tree/serialization/TreeNodeDto;)Lcom/github/adriankuta/datastructure/tree/TreeNode;
+}
+

tree-structure-serialization/build.gradle.kts

@@ -0,0 +1,89 @@
+import org.jetbrains.kotlin.gradle.ExperimentalWasmDsl
+
+plugins {
+    alias(libs.plugins.kotlinMultiplatform)
+    alias(libs.plugins.kotlinSerialization)
+    alias(libs.plugins.dokka)
+    alias(libs.plugins.mavenPublish)
+    signing
+}
+
+group = "com.github.adriankuta"
+version = rootProject.version
+
+mavenPublishing {
+    publishToMavenCentral(automaticRelease = false)
+    signAllPublications()
+
+    coordinates("com.github.adriankuta", "tree-structure-serialization", version.toString())
+
+    pom {
+        name.set("Tree Data Structure — kotlinx.serialization")
+        description.set("kotlinx.serialization support (TreeNodeDto round-trip) for the tree-structure library.")
+        url.set("https://github.com/AdrianKuta/Tree-Data-Structure")
+        licenses {
+            license {
+                name.set("MIT License")
+                url.set("https://opensource.org/licenses/MIT")
+                distribution.set("repo")
+            }
+        }
+        developers {
+            developer {
+                id.set("AdrianKuta")
+                name.set("Adrian Kuta")
+                email.set("adrian.kuta93@gmail.com")
+            }
+        }
+        scm {
+            url.set("https://github.com/AdrianKuta/Tree-Data-Structure")
+            connection.set("scm:git:https://github.com/AdrianKuta/Tree-Data-Structure.git")
+            developerConnection.set("scm:git:ssh://git@github.com/AdrianKuta/Tree-Data-Structure.git")
+        }
+    }
+}
+
+repositories {
+    mavenCentral()
+}
+
+kotlin {
+    explicitApi()
+    jvmToolchain(21)
+
+    jvm()
+
+    js(IR) {
+        browser()
+        nodejs()
+    }
+
+    @OptIn(ExperimentalWasmDsl::class)
+    wasmJs {
+        browser()
+        nodejs()
+    }
+
+    iosX64()
+    iosArm64()
+    iosSimulatorArm64()
+
+    val hostOs = System.getProperty("os.name")
+    val isMingwX64 = hostOs.startsWith("Windows")
+    when {
+        hostOs == "Mac OS X" -> macosX64("native")
+        hostOs == "Linux" -> linuxX64("native")
+        isMingwX64 -> mingwX64("native")
+        else -> throw GradleException("Host OS is not supported in Kotlin/Native.")
+    }
+
+    sourceSets {
+        commonMain.dependencies {
+            api(project(":"))
+            api(libs.kotlinx.serialization.json)
+        }
+        commonTest.dependencies {
+            implementation(kotlin("test"))
+        }
+    }
+}

tree-structure-serialization/src/commonMain/kotlin/com.github.adriankuta/datastructure/tree/serialization/TreeNodeDto.kt

@@ -0,0 +1,30 @@
+package com.github.adriankuta.datastructure.tree.serialization
+
+import com.github.adriankuta.datastructure.tree.TreeNode
+import kotlinx.serialization.Serializable
+
+/**
+ * A serializable, acyclic view of a [TreeNode] subtree. [TreeNode] itself holds a back-reference to
+ * its parent (a cycle), so it cannot be `@Serializable` directly — convert to/from this DTO instead.
+ *
+ * ```
+ * val json = Json.encodeToString(tree.toDto())
+ * val restored = Json.decodeFromString<TreeNodeDto<String>>(json).toTreeNode()
+ * ```
+ */
+@Serializable
+public data class TreeNodeDto<T>(
+    public val value: T,
+    public val children: List<TreeNodeDto<T>> = emptyList(),
+)
+
+/** Converts this subtree into a serializable [TreeNodeDto], preserving values and shape. */
+public fun <T> TreeNode<T>.toDto(): TreeNodeDto<T> =
+    TreeNodeDto(value, children.map { it.toDto() })
+
+/** Rebuilds a mutable [TreeNode] tree from this DTO. */
+public fun <T> TreeNodeDto<T>.toTreeNode(): TreeNode<T> {
+    val node = TreeNode(value)
+    children.forEach { node.addChild(it.toTreeNode()) }
+    return node
+}

tree-structure-serialization/src/commonTest/kotlin/com.github.adriankuta/datastructure/tree/serialization/TreeNodeSerializationTest.kt

@@ -0,0 +1,40 @@
+package com.github.adriankuta.datastructure.tree.serialization
+
+import com.github.adriankuta.datastructure.tree.structurallyEquals
+import com.github.adriankuta.datastructure.tree.tree
+import kotlinx.serialization.encodeToString
+import kotlinx.serialization.json.Json
+import kotlin.test.Test
+import kotlin.test.assertEquals
+import kotlin.test.assertTrue
+
+class TreeNodeSerializationTest {
+
+    @Test
+    fun roundTripsThroughJson() {
+        val original = tree("World") {
+            child("North America") { child("USA") }
+            child("Europe") {
+                child("Poland")
+                child("Germany")
+            }
+        }
+
+        val json = Json.encodeToString(original.toDto())
+        val restored = Json.decodeFromString<TreeNodeDto<String>>(json).toTreeNode()
+
+        assertTrue(original.structurallyEquals(restored))
+    }
+
+    @Test
+    fun dtoMirrorsTreeShape() {
+        val dto = tree(1) {
+            child(2)
+            child(3) { child(4) }
+        }.toDto()
+
+        assertEquals(1, dto.value)
+        assertEquals(2, dto.children.size)
+        assertEquals(4, dto.children[1].children[0].value)
+    }
+}