refactor(model-client): addressed a load of detekt issues

Author: abstraktor

model-client/src/commonMain/kotlin/org/modelix/model/client2/ReplicatedModel.kt

@@ -58,9 +58,12 @@ import org.modelix.model.mutable.asModel
  * Dispose should be called on this, as otherwise a regular polling will go on.
  *
  * @property client the model client to connect to the model server
- * @property branchRef branch or repository reference
- * @property providedScope the CoroutineScope to use for the suspendable tasks
- * @property initialRemoteVersion the last version on the server from which we want to start the synchronization
+ * @param branchRefOrNull branch reference, null if strictly version-based
+ * @property idGenerator the generator for node IDs
+ * @param providedScope the CoroutineScope to use for the suspendable tasks
+ * @param initialRemoteVersion the last version on the server from which we want to start the synchronization
+ * @param repositoryId the repository ID, required if [versionHash] is provided
+ * @param versionHash the version hash to replicate, if not using a branch reference
  */
 class ReplicatedModel(
     val client: IModelClientV2,
@@ -80,7 +83,7 @@ class ReplicatedModel(
         initialRemoteVersion: CLVersion? = null,
     ) : this(client, branchRef, idGenerator, providedScope, initialRemoteVersion, null, null)
 
-    val branchRef: BranchReference get() = branchRefOrNull ?: throw IllegalStateException("ReplicatedModel is in read-only version mode")
+    val branchRef: BranchReference get() = branchRefOrNull ?: error("ReplicatedModel is in read-only version mode")
 
     private val scope = providedScope ?: CoroutineScope(Dispatchers.Default)
     private var state = State.New
@@ -98,24 +101,33 @@ class ReplicatedModel(
         if (branchRefOrNull != null) {
             check(versionHash == null) { "Cannot provide both branchRef and versionHash" }
             remoteVersion = RemoteVersionFromBranch(client, branchRefOrNull, initialRemoteVersion)
-        } else if (versionHash != null) {
-            val repoId = repositoryId ?: throw IllegalArgumentException("repositoryId is required when versionHash is provided")
-            remoteVersion = RemoteVersionFromHash(client, repoId, versionHash)
         } else {
-            throw IllegalArgumentException("Either branchRef or versionHash must be provided")
+            require(versionHash != null) { "Either branchRef or versionHash must be provided" }
+            require(repositoryId != null) { "repositoryId is required when versionHash is provided" }
+            remoteVersion = RemoteVersionFromHash(client, repositoryId, versionHash)
         }
     }
 
     private fun getLocalModel(): LocalModel = checkNotNull(localModel) { "Model is not initialized yet" }
 
+    /**
+     * Returns the model as an [IMutableModel].
+     */
     fun getModel(): IMutableModel {
         return getLocalModel().versionedModelTree.asModel()
     }
 
+    /**
+     * Returns the underlying [VersionedModelTree].
+     */
     fun getVersionedModelTree(): IMutableModelTree = getLocalModel().versionedModelTree
 
+    /**
+     * Starts the synchronization process.
+     * Use [dispose] to stop it.
+     */
     suspend fun start(): IMutableModelTree {
-        if (state != State.New) throw IllegalStateException("already started")
+        check(state == State.New) { "already started" }
         state = State.Starting
 
         if (localModel == null) {
@@ -137,7 +149,7 @@ class ReplicatedModel(
                     throw ex
                 } catch (ex: Throwable) {
                     LOG.error(ex) { "Failed polling" }
-                    nextDelayMs = (nextDelayMs * 3 / 2).coerceIn(1000, 30000)
+                    nextDelayMs = (nextDelayMs * 3 / 2).coerceIn(POLLING_MIN_DELAY, POLLING_MAX_DELAY)
                 }
             }
         }
@@ -160,18 +172,23 @@ class ReplicatedModel(
         return getVersionedModelTree()
     }
 
+    /**
+     * Resets the local model to the latest version on the server.
+     */
     suspend fun resetToServerVersion() {
         // This delegates to remoteVersion which handles pull/load
         val version = remoteVersion.getInitialVersion()
         getLocalModel().resetToVersion(version)
     }
 
+    /**
+     * Returns true if this [ReplicatedModel] has been disposed.
+     */
     fun isDisposed(): Boolean = state == State.Disposed
 
-    private fun checkDisposed() {
-        if (state == State.Disposed) throw IllegalStateException("disposed")
-    }
-
+    /**
+     * Stops the synchronization and releases resources.
+     */
     fun dispose() {
         if (state == State.Disposed) return
         pollingJob?.cancel("disposed")
@@ -208,16 +225,19 @@ class ReplicatedModel(
     private suspend fun pushLocalChanges() {
         if (isDisposed()) return
 
-        for (attempt in 1..10) {
+        repeat(PUSH_MAX_ATTEMPTS) {
             val version = getLocalModel().createNewLocalVersion() ?: getLocalModel().getCurrentVersion()
             val received = remoteVersion.push(version)
             if (received.getContentHash() == version.getContentHash()) return
             remoteVersionReceived(received, version)
         }
 
-        throw IllegalStateException("Failed to push local changes after 10 attempts")
+        error("Failed to push local changes after $PUSH_MAX_ATTEMPTS attempts")
     }
 
+    /**
+     * Returns the current version of the local model.
+     */
     fun getCurrentVersion(): CLVersion {
         return getLocalModel().getCurrentVersion()
     }
@@ -231,13 +251,22 @@ class ReplicatedModel(
 
     companion object {
         private val LOG = KotlinLogging.logger { }
+        private const val POLLING_MIN_DELAY = 1000L
+        private const val POLLING_MAX_DELAY = 30000L
+        private const val PUSH_MAX_ATTEMPTS = 10
     }
 }
 
+/**
+ * Creates a [ReplicatedModel] for the given branch.
+ */
 fun IModelClientV2.getReplicatedModel(branchRef: BranchReference, idGenerator: (TreeId) -> INodeIdGenerator<INodeReference>): ReplicatedModel {
     return ReplicatedModel(this, branchRef, idGenerator)
 }
 
+/**
+ * Creates a [ReplicatedModel] for the given branch with a provided scope.
+ */
 fun IModelClientV2.getReplicatedModel(branchRef: BranchReference, idGenerator: (TreeId) -> INodeIdGenerator<INodeReference>, scope: CoroutineScope): ReplicatedModel {
     return ReplicatedModel(this, branchRef, idGenerator, scope)
 }

model-client/src/jsMain/kotlin/org/modelix/model/client2/ClientJS.kt

@@ -70,6 +70,7 @@ fun loadModelsFromJsonAsBranch(json: Array<String>): MutableModelTreeJs {
  *
  * @param url URL to the V2 endpoint of the model server.
  * e.g., http://localhost:28102/v2
+ * @param bearerTokenProvider provider for the bearer token
  */
 @JsExport
 fun connectClient(url: String, bearerTokenProvider: (() -> Promise<String?>)? = null): Promise<ClientJS> {
@@ -86,13 +87,30 @@ fun connectClient(url: String, bearerTokenProvider: (() -> Promise<String?>)? =
     }
 }
 
+/**
+ * ID generation scheme for the JS client.
+ */
 @JsExport
-sealed class IdSchemeJS() {
+sealed class IdSchemeJS {
+    /**
+     * MPS ID generation scheme.
+     */
     object MPS : IdSchemeJS()
+
+    /**
+     * Modelix ID generation scheme.
+     */
     object MODELIX : IdSchemeJS()
+
+    /**
+     * Read-only ID generation scheme.
+     */
     object READONLY : IdSchemeJS()
 }
 
+/**
+ * Combines version information with a model tree.
+ */
 @JsExport
 data class VersionInformationWithModelTree(val version: VersionInformationJS, val tree: MutableModelTreeJs)
 
@@ -127,20 +145,73 @@ interface ClientJS {
      */
     fun initRepository(repositoryId: String, useRoleIds: Boolean = true): Promise<Unit>
 
+    /**
+     * Loads a specific version of the model in read-only mode.
+     *
+     * @param repositoryId ID of the repository.
+     * @param versionHash Hash of the version to load.
+     * @return A promise resolving to the version information and tree.
+     */
     fun loadReadonlyVersion(repositoryId: String, versionHash: String): Promise<VersionInformationWithModelTree>
 
+    /**
+     * Retrieves a range of version history.
+     */
     fun getHistoryRange(repositoryId: String, headVersion: String, skip: Int, limit: Int): Promise<Array<VersionInformationJS>>
+
+    /**
+     * Retrieves history sessions.
+     */
     fun getHistorySessions(repositoryId: String, headVersion: String, delaySeconds: Int, skip: Int, limit: Int): Promise<Array<HistoryIntervalJS>>
+
+    /**
+     * Retrieves history for fixed intervals.
+     */
     fun getHistoryForFixedIntervals(repositoryId: String, headVersion: String, intervalDurationSeconds: Int, skip: Int, limit: Int): Promise<Array<HistoryIntervalJS>>
+
+    /**
+     * Retrieves history for provided intervals.
+     */
     fun getHistoryForProvidedIntervals(repositoryId: String, headVersion: String, splitAt: Array<Date>): Promise<Array<HistoryIntervalJS>>
 
+    /**
+     * Retrieves history range for a branch.
+     */
     fun getHistoryRangeForBranch(repositoryId: String, branchId: String, skip: Int, limit: Int): Promise<Array<VersionInformationJS>>
+
+    /**
+     * Retrieves history sessions for a branch.
+     */
     fun getHistorySessionsForBranch(repositoryId: String, branchId: String, delaySeconds: Int, skip: Int, limit: Int): Promise<Array<HistoryIntervalJS>>
+
+    /**
+     * Retrieves history for fixed intervals for a branch.
+     */
     fun getHistoryForFixedIntervalsForBranch(repositoryId: String, branchId: String, intervalDurationSeconds: Int, skip: Int, limit: Int): Promise<Array<HistoryIntervalJS>>
+
+    /**
+     * Retrieves history for provided intervals for a branch.
+     */
     fun getHistoryForProvidedIntervalsForBranch(repositoryId: String, branchId: String, splitAt: Array<Date>): Promise<Array<HistoryIntervalJS>>
 
+    /**
+     * Reverts the branch to a specific version.
+     *
+     * @param repositoryId ID of the repository.
+     * @param branchId ID of the branch.
+     * @param targetVersionHash Hash of the version to revert to.
+     * @return A promise resolving to the new version hash.
+     */
     fun revertTo(repositoryId: String, branchId: String, targetVersionHash: String): Promise<String>
 
+    /**
+     * Computes the difference between two versions as mutation parameters.
+     *
+     * @param repositoryId ID of the repository.
+     * @param newVersion Hash of the new version.
+     * @param oldVersion Hash of the old version.
+     * @return A promise resolving to an array of mutation parameters.
+     */
     fun diffAsMutationParameters(repositoryId: String, newVersion: String, oldVersion: String): Promise<Array<MutationParametersJS>>
 
     /**
@@ -195,9 +266,15 @@ interface ClientJS {
      *
      * @param repositoryId Repository ID of the branch to replicate.
      * @param branchId ID of the branch to replicate.
+     * @param idScheme The ID scheme to use for generating node IDs.
      */
     fun startReplicatedModel(repositoryId: String, branchId: String, idScheme: IdSchemeJS): Promise<ReplicatedModelJS>
 
+    /**
+     * Starts replicated models for the given parameters.
+     *
+     * @param parameters configuration for the replicated models
+     */
     fun startReplicatedModels(parameters: Array<ReplicatedModelParameters>): Promise<ReplicatedModelJS>
 
     /**
@@ -206,6 +283,15 @@ interface ClientJS {
     fun dispose()
 }
 
+/**
+ * Configuration for a replicated model.
+ *
+ * @property repositoryId The ID of the repository.
+ * @property branchId The ID of the branch to replicate. Mutually exclusive with [versionHash].
+ * @property idScheme The ID scheme to use.
+ * @property readonly If true, the model will be read-only.
+ * @property versionHash The hash of the version to load properties from. Mutually exclusive with [branchId].
+ */
 @JsExport
 data class ReplicatedModelParameters(
     val repositoryId: String,
@@ -476,6 +562,9 @@ interface MutableModelTreeJs {
      */
     val rootNode: INodeJS
 
+    /**
+     * Get all root nodes in the branch.
+     */
     fun getRootNodes(): Array<INodeJS>
 
     /**