feat(model-datastructure): introduced IModelTree.builder as a public API for creating new instances

Author: slisson

datastructures/src/commonMain/kotlin/org/modelix/datastructures/IPersistentMap.kt

@@ -1,6 +1,7 @@
 package org.modelix.datastructures
 
 import org.modelix.datastructures.objects.IDataTypeConfiguration
+import org.modelix.datastructures.objects.IObjectData
 import org.modelix.datastructures.objects.Object
 import org.modelix.streams.IStream
 import org.modelix.streams.IStreamExecutorProvider
@@ -28,3 +29,11 @@ interface IPersistentMap<K, V> : IStreamExecutorProvider {
 
     fun getChanges(oldMap: IPersistentMap<K, V>, changesOnly: Boolean): IStream.Many<MapChangeEvent<K, V>>
 }
+
+interface IPersistentMapRootData<K, V> : IObjectData {
+    fun createMapInstance(self: Object<IPersistentMapRootData<K, V>>): IPersistentMap<K, V>
+}
+
+fun <K, V> Object<IPersistentMapRootData<K, V>>.createMapInstance(): IPersistentMap<K, V> {
+    return data.createMapInstance(this)
+}

datastructures/src/commonMain/kotlin/org/modelix/datastructures/MapWithObjectReferenceValues.kt

@@ -83,3 +83,7 @@ class MapWithObjectReferenceValues<K, V : IObjectData>(
         }
     }
 }
+
+fun <K, V : IObjectData> IPersistentMap<K, ObjectReference<V>>.autoResolveValues(): IPersistentMap<K, V> {
+    return MapWithObjectReferenceValues(asObject().graph, this)
+}

datastructures/src/commonMain/kotlin/org/modelix/datastructures/hamt/HamtNode.kt

@@ -1,25 +1,31 @@
 package org.modelix.datastructures.hamt
 
+import org.modelix.datastructures.IPersistentMap
+import org.modelix.datastructures.IPersistentMapRootData
 import org.modelix.datastructures.MapChangeEvent
 import org.modelix.datastructures.btree.BTree
 import org.modelix.datastructures.btree.BTreeConfig
 import org.modelix.datastructures.btree.BTreeNode
 import org.modelix.datastructures.objects.IDataTypeConfiguration
-import org.modelix.datastructures.objects.IObjectData
 import org.modelix.datastructures.objects.IObjectDeserializer
 import org.modelix.datastructures.objects.IObjectGraph
 import org.modelix.datastructures.objects.IObjectReferenceFactory
 import org.modelix.datastructures.objects.Object
 import org.modelix.datastructures.objects.hash
+import org.modelix.datastructures.objects.upcast
 import org.modelix.streams.IStream
 import kotlin.jvm.JvmName
 
 /**
  * Implementation of a hash array mapped trie.
  */
-sealed class HamtNode<K, V : Any> : IObjectData {
+sealed class HamtNode<K, V : Any> : IPersistentMapRootData<K, V> {
     abstract val config: Config<K, V>
 
+    override fun createMapInstance(self: Object<IPersistentMapRootData<K, V>>): IPersistentMap<K, V> {
+        return HamtTree(self.upcast<HamtNode<K, V>>())
+    }
+
     protected operator fun V.compareTo(other: V): Int = config.valueConfig.compare(this, other)
 
     override fun getDeserializer() = config.deserializer

datastructures/src/commonMain/kotlin/org/modelix/datastructures/patricia/PatriciaNode.kt

@@ -1,59 +1,67 @@
 package org.modelix.datastructures.patricia
 
+import org.modelix.datastructures.IPersistentMap
+import org.modelix.datastructures.IPersistentMapRootData
 import org.modelix.datastructures.objects.IObjectData
 import org.modelix.datastructures.objects.IObjectDeserializer
 import org.modelix.datastructures.objects.IObjectGraph
 import org.modelix.datastructures.objects.IObjectReferenceFactory
+import org.modelix.datastructures.objects.Object
 import org.modelix.datastructures.objects.ObjectReference
 import org.modelix.datastructures.objects.getHashString
+import org.modelix.datastructures.objects.upcast
 import org.modelix.datastructures.serialization.SplitJoinSerializer
 import org.modelix.kotlin.utils.urlDecode
 import org.modelix.kotlin.utils.urlEncode
 import org.modelix.streams.IStream
 import org.modelix.streams.plus
 
-data class PatriciaNode<V : Any>(
-    val config: PatriciaTrieConfig<*, V>,
+data class PatriciaNode<K, V : Any>(
+    val config: PatriciaTrieConfig<K, V>,
     val ownPrefix: String,
     val firstChars: String,
-    val children: List<ObjectReference<PatriciaNode<V>>>,
+    val children: List<ObjectReference<PatriciaNode<K, V>>>,
 
     /**
      * [ownPrefix] is part of the key for entry that s stored in this node
      */
     val value: V?,
-) : IObjectData {
-    constructor(config: PatriciaTrieConfig<*, V>) : this(config, "", "", emptyList(), null)
+) : IPersistentMapRootData<K, V> {
+    constructor(config: PatriciaTrieConfig<K, V>) : this(config, "", "", emptyList(), null)
 
-    constructor(config: PatriciaTrieConfig<*, V>, key: String, value: V) :
+    constructor(config: PatriciaTrieConfig<K, V>, key: String, value: V) :
         this(config = config, ownPrefix = key, value = value, firstChars = "", children = emptyList())
 
+    override fun createMapInstance(self: Object<IPersistentMapRootData<K, V>>): IPersistentMap<K, V> {
+        return PatriciaTrie(self.upcast<PatriciaNode<K, V>>())
+    }
+
     fun calculateDepth(): Int = (children.maxOfOrNull { it.resolveNow().data.calculateDepth() } ?: 0) + 1
 
-    fun withChildInserted(index: Int, firstChar: Char, child: PatriciaNode<V>): PatriciaNode<V> {
+    fun withChildInserted(index: Int, firstChar: Char, child: PatriciaNode<K, V>): PatriciaNode<K, V> {
         return copy(
             firstChars = firstChars.take(index) + firstChar + firstChars.drop(index),
             children = children.take(index) + config.graph.fromCreated(child) + children.drop(index),
         )
     }
 
-    private fun withChildReplacedNullable(index: Int, child: PatriciaNode<V>?): PatriciaNode<V>? {
+    private fun withChildReplacedNullable(index: Int, child: PatriciaNode<K, V>?): PatriciaNode<K, V>? {
         return if (child == null) withoutChild(index) else withChildReplaced(index, config.graph.fromCreated(child))
     }
 
-    private fun withChildReplaced(index: Int, child: ObjectReference<PatriciaNode<V>>): PatriciaNode<V> {
+    private fun withChildReplaced(index: Int, child: ObjectReference<PatriciaNode<K, V>>): PatriciaNode<K, V> {
         if (children[index] === child) return this
         return copy(children = children.take(index) + child + children.drop(index + 1))
     }
 
-    fun withoutChild(index: Int): PatriciaNode<V>? {
+    fun withoutChild(index: Int): PatriciaNode<K, V>? {
         return copy(
             firstChars = firstChars.take(index) + firstChars.drop(index + 1),
             children = children.take(index) + children.drop(index + 1),
         )
     }
 
-    fun tryMerge(): IStream.ZeroOrOne<PatriciaNode<V>> {
+    fun tryMerge(): IStream.ZeroOrOne<PatriciaNode<K, V>> {
         if (value != null) return IStream.of(this)
         return when (children.size) {
             0 -> IStream.empty()
@@ -89,14 +97,14 @@ data class PatriciaNode<V : Any>(
     /**
      * Returns a new root that contains only those entries that start with the given prefix.
      */
-    fun slice(prefix: CharSequence): IStream.ZeroOrOne<PatriciaNode<V>> {
+    fun slice(prefix: CharSequence): IStream.ZeroOrOne<PatriciaNode<K, V>> {
         return getSubtree(prefix).map { it.copy(ownPrefix = prefix.toString() + it.ownPrefix) }
     }
 
     /**
      * Returns a subtree with all known suffixes of the provided prefix.
      */
-    fun getSubtree(prefix: CharSequence): IStream.ZeroOrOne<PatriciaNode<V>> {
+    fun getSubtree(prefix: CharSequence): IStream.ZeroOrOne<PatriciaNode<K, V>> {
         if (ownPrefix.startsWith(prefix)) {
             return if (ownPrefix.length == prefix.length) {
                 IStream.of(this.copy(ownPrefix = ""))
@@ -127,7 +135,7 @@ data class PatriciaNode<V : Any>(
         }
     }
 
-    fun put(newKey: CharSequence, newValue: V?): IStream.ZeroOrOne<PatriciaNode<V>> {
+    fun put(newKey: CharSequence, newValue: V?): IStream.ZeroOrOne<PatriciaNode<K, V>> {
         val commonPrefix = newKey.commonPrefixWith(this.ownPrefix)
         val remainingNewKey = newKey.drop(commonPrefix.length)
         val remainingOwnPrefix = this.ownPrefix.drop(commonPrefix.length)
@@ -144,7 +152,7 @@ data class PatriciaNode<V : Any>(
                         .mapNotNull { withChildReplacedNullable(index, it) }
                 } else {
                     val insertionIndex = (-index) - 1
-                    val newChild = PatriciaNode<V>(
+                    val newChild = PatriciaNode<K, V>(
                         config = config,
                         ownPrefix = remainingNewKey.toString(),
                         value = newValue,
@@ -160,16 +168,16 @@ data class PatriciaNode<V : Any>(
             ).flatMapZeroOrOne { it.tryMerge() }
     }
 
-    fun split(commonPrefix: CharSequence): PatriciaNode<V> {
+    fun split(commonPrefix: CharSequence): PatriciaNode<K, V> {
         val remainingPrefix = this.ownPrefix.drop(commonPrefix.length)
-        return PatriciaNode<V>(
+        return PatriciaNode<K, V>(
             config = config,
             ownPrefix = commonPrefix.toString(),
             value = null,
             firstChars = remainingPrefix.take(1),
             children = listOf(
                 config.graph.fromCreated(
-                    PatriciaNode<V>(
+                    PatriciaNode<K, V>(
                         config = config,
                         ownPrefix = remainingPrefix,
                         firstChars = this.firstChars,
@@ -191,24 +199,24 @@ data class PatriciaNode<V : Any>(
     }
 
     override fun getDeserializer(): IObjectDeserializer<*> {
-        return Deserializer(config)
+        return Deserializer<K, V>(config)
     }
 
     override fun getContainmentReferences(): List<ObjectReference<IObjectData>> {
         return children + (value?.let { config.valueConfig.getContainmentReferences(it) } ?: emptyList())
     }
 
-    class Deserializer<V : Any>(val config: (IObjectGraph) -> PatriciaTrieConfig<*, V>) : IObjectDeserializer<PatriciaNode<V>> {
-        constructor(config: PatriciaTrieConfig<*, V>) : this({ config })
+    class Deserializer<K, V : Any>(val config: (IObjectGraph) -> PatriciaTrieConfig<K, V>) : IObjectDeserializer<PatriciaNode<K, V>> {
+        constructor(config: PatriciaTrieConfig<K, V>) : this({ config })
         override fun deserialize(
             serialized: String,
             referenceFactory: IObjectReferenceFactory,
-        ): PatriciaNode<V> {
+        ): PatriciaNode<K, V> {
             val S1 = SplitJoinSerializer.SEPARATORS[0]
             val S2 = SplitJoinSerializer.SEPARATORS[1]
             val parts = serialized.split(S1, limit = 4)
             val config = config(referenceFactory as IObjectGraph)
-            return PatriciaNode<V>(
+            return PatriciaNode<K, V>(
                 config,
                 parts[0].urlDecode()!!,
                 parts[1].urlDecode()!!,

datastructures/src/commonMain/kotlin/org/modelix/datastructures/patricia/PatriciaTrie.kt

@@ -15,10 +15,10 @@ import org.modelix.streams.IStreamExecutorProvider
  */
 class PatriciaTrie<K, V : Any>(
     val config: PatriciaTrieConfig<K, V>,
-    val root: Object<PatriciaNode<V>>,
+    val root: Object<PatriciaNode<K, V>>,
 ) : IPersistentMap<K, V>, IStreamExecutorProvider by root.graph {
     constructor(config: PatriciaTrieConfig<K, V>) : this(config, PatriciaNode(config).asObject(config.graph))
-    constructor(root: Object<PatriciaNode<V>>) : this(root.data.config as PatriciaTrieConfig<K, V>, root)
+    constructor(root: Object<PatriciaNode<K, V>>) : this(root.data.config as PatriciaTrieConfig<K, V>, root)
 
     override fun asObject(): Object<*> {
         return root
@@ -32,7 +32,7 @@ class PatriciaTrie<K, V : Any>(
         return config.keyConfig.serialize(key)
     }
 
-    private fun withNewRoot(newRoot: PatriciaNode<V>?): PatriciaTrie<K, V> {
+    private fun withNewRoot(newRoot: PatriciaNode<K, V>?): PatriciaTrie<K, V> {
         return PatriciaTrie(config, (newRoot ?: PatriciaNode(config)).asObject(config.graph))
     }
 

model-datastructure/src/commonMain/kotlin/org/modelix/datastructures/model/DefaultModelTree.kt

@@ -1,16 +1,15 @@
 package org.modelix.datastructures.model
 
 import org.modelix.datastructures.IPersistentMap
-import org.modelix.datastructures.hamt.HamtNode
 import org.modelix.datastructures.objects.Object
-import org.modelix.datastructures.objects.ObjectReference
 import org.modelix.datastructures.objects.asObject
-import org.modelix.datastructures.patricia.PatriciaNode
+import org.modelix.datastructures.objects.upcast
 import org.modelix.model.TreeId
 import org.modelix.model.api.INodeReference
 import org.modelix.model.api.ITree
 import org.modelix.model.api.PNodeReference
 import org.modelix.model.persistent.CPTree
+import kotlin.jvm.JvmName
 
 /**
  * Legacy storage with new API that hides details about the type of IDs that's used internally.
@@ -23,7 +22,7 @@ class Int64ModelTree(nodesMap: IPersistentMap<Long, NodeObjectData<Long>>, treeI
     override fun asObject(): Object<CPTree> {
         return CPTree(
             id = getId(),
-            int64Hamt = nodesMap.asObject().ref as ObjectReference<HamtNode<Long, ObjectReference<NodeObjectData<Long>>>>,
+            int64Hamt = nodesMap.asObject().ref.upcast(),
             trieWithNodeRefIds = null,
             usesRoleIds = true,
         ).asObject(graph)
@@ -41,7 +40,7 @@ class DefaultModelTree(nodesMap: IPersistentMap<INodeReference, NodeObjectData<I
         return CPTree(
             id = getId(),
             int64Hamt = null,
-            trieWithNodeRefIds = nodesMap.asObject() as ObjectReference<PatriciaNode<ObjectReference<NodeObjectData<INodeReference>>>>,
+            trieWithNodeRefIds = nodesMap.asObject().ref.upcast(),
             usesRoleIds = true,
         ).asObject(graph)
     }
@@ -54,3 +53,13 @@ class DefaultModelTree(nodesMap: IPersistentMap<INodeReference, NodeObjectData<I
 }
 
 class NodeNotFoundException(nodeId: Any?) : RuntimeException("Node doesn't exist: $nodeId")
+
+@JvmName("asModelTreeWithNodeReferences")
+fun IPersistentMap<INodeReference, NodeObjectData<INodeReference>>.asModelTree(treeId: TreeId): IModelTree<INodeReference> {
+    return DefaultModelTree(this, treeId)
+}
+
+@JvmName("asModelTreeWithInt64")
+fun IPersistentMap<Long, NodeObjectData<Long>>.asModelTree(treeId: TreeId): IModelTree<Long> {
+    return Int64ModelTree(this, treeId)
+}

model-datastructure/src/commonMain/kotlin/org/modelix/datastructures/model/IModelTree.kt

@@ -59,6 +59,10 @@ interface IModelTree<NodeId> : IStreamExecutorProvider {
     fun mutate(operations: Iterable<MutationParameters<NodeId>>): IStream.One<IModelTree<NodeId>>
 
     fun mutate(operation: MutationParameters<NodeId>): IStream.One<IModelTree<NodeId>> = mutate(listOf(operation))
+
+    companion object {
+        fun builder(): ModelTreeBuilder<Long> = ModelTreeBuilder.newWithInt64Ids()
+    }
 }
 
 sealed class MutationParameters<NodeId> {

model-datastructure/src/commonMain/kotlin/org/modelix/datastructures/model/IdTranslatingModelTree.kt

@@ -13,6 +13,7 @@ import org.modelix.streams.IStream
 import org.modelix.streams.IStreamExecutor
 import org.modelix.streams.mapFirst
 import org.modelix.streams.mapSecond
+import kotlin.jvm.JvmName
 
 class NodeReferenceAsLongModelTree(tree: IModelTree<INodeReference>) : IdTranslatingModelTree<Long, INodeReference>(tree) {
     override fun Long.toInternal(): INodeReference = PNodeReference(this, getId().id)
@@ -186,3 +187,13 @@ abstract class IdTranslatingModelTree<ExternalId, InternalId>(val tree: IModelTr
         }
     }
 }
+
+@JvmName("withIdTranslationToInt64")
+fun IModelTree<INodeReference>.withIdTranslation(): IModelTree<Long> {
+    return NodeReferenceAsLongModelTree(this)
+}
+
+@JvmName("withIdTranslationToNodeReferences")
+fun IModelTree<Long>.withIdTranslation(): IModelTree<INodeReference> {
+    return LongAsNodeReferenceModelTree(this)
+}