feat(vue-model-api): expose replicated model

The replicated model can be used to subscribe to changes on the branch or get information about the current version.

Author: Oleksandr Dzhychko

vue-model-api/package-lock.json

@@ -1,3 +1,3 @@
 export { useModelsFromJson } from "./useModelsFromJson";
 export { useModelClient } from "./useModelClient";
-export { useRootNode } from "./useRootNode";
+export { useReplicatedModel } from "./useReplicatedModel";

vue-model-api/src/index.ts

@@ -2,7 +2,7 @@ import { org } from "@modelix/model-client";
 import { INodeJS } from "@modelix/ts-model-api";
 import { watchEffect } from "vue";
 import { useModelClient } from "./useModelClient";
-import { useRootNode } from "./useRootNode";
+import { useReplicatedModel } from "./useReplicatedModel";
 
 type BranchJS = org.modelix.model.client2.BranchJS;
 type ReplicatedModelJS = org.modelix.model.client2.ReplicatedModelJS;
@@ -53,11 +53,13 @@ test("test branch connects", (done) => {
   const { client } = useModelClient("anURL", () =>
     Promise.resolve(new SuccessfulClientJS() as unknown as ClientJS),
   );
-
-  const { rootNode } = useRootNode(client, "aRepository", "aBranch");
-
+  const { rootNode, replicatedModel } = useReplicatedModel(
+    client,
+    "aRepository",
+    "aBranch",
+  );
   watchEffect(() => {
-    if (rootNode.value !== null) {
+    if (rootNode.value !== null && replicatedModel.value !== null) {
       expect(rootNode.value.getPropertyValue("branchId")).toBe("aBranch");
       done();
     }
@@ -78,7 +80,7 @@ test("test branch connection error is exposed", (done) => {
     Promise.resolve(new FailingClientJS() as unknown as ClientJS),
   );
 
-  const { error } = useRootNode(client, "aRepository", "aBranch");
+  const { error } = useReplicatedModel(client, "aRepository", "aBranch");
 
   watchEffect(() => {
     if (error.value !== null) {

vue-model-api/src/useRootNode.test.ts renamed to vue-model-api/src/useReplicatedModel.test.ts

@@ -11,42 +11,51 @@ type ReplicatedModelJS = org.modelix.model.client2.ReplicatedModelJS;
 type ChangeJS = org.modelix.model.client2.ChangeJS;
 
 /**
- * Creates a reactive root node from a client for a given repository and branch.
+ * Creates a replicated model for a given repository and branch.
+ * A replicated model exposes a branch that can be used to read and write model data.
+ * The written model data is automatically synced to the model server.
+ * Changed from the model server are automatically synced to the branch in the replicated model
  *
- * The returned root node uses Vues reactivity and can be used in Vue like an reactive object.
- * Changes to the returned node or its descendants are synced to the branch on the model server.
+ * Also creates root node that uses Vues reactivity and can be used in Vue like a reactive object.
+ * Changes to model data trigger recalculation of computed properties or re-rendering of components using that data.
  *
- * Calling the returned dispose function stops syncing the root node to the underlying branch on the serever.
+ * Calling the returned dispose function stops syncing the root node to the underlying branch on the server.
  *
  * @experimental This feature is expected to be finalized with https://issues.modelix.org/issue/MODELIX-500.
  *
  * @param client - Reactive reference of a client to a model server.
  * @param repositoryId - Reactive reference of a repositoryId on the model server.
  * @param branchId - Reactive reference of a branchId in the repository of the model server.
  *
- * @returns {Object} values Wrapper around diffrent returned values.
- * @returns {Ref<INodeJS | null>} values.rootNode  Reactive reference to a reactive root node.
+ * @returns {Object} values Wrapper around different returned values.
+ * @returns {Ref<ReplicatedModelJS | null>} values.rootNode  Reactive reference to the replicated model for the specified branch.
+ * @returns {Ref<INodeJS | null>} values.rootNode  Reactive reference to the root node with Vue.js reactivity for the specified branch.
  * @returns {() => void} values.dispose A function to manually dispose the root node.
  * @returns {Ref<unknown>} values.error Reactive reference to a connection error.
  */
-export function useRootNode(
+export function useReplicatedModel(
   client: MaybeRefOrGetter<ClientJS | null>,
   repositoryId: MaybeRefOrGetter<string | null>,
   branchId: MaybeRefOrGetter<string | null>,
 ): {
+  replicatedModel: Ref<ReplicatedModelJS | null>;
   rootNode: Ref<INodeJS | null>;
   dispose: () => void;
   error: Ref<unknown>;
 } {
+  // Use `replicatedModel` to access the replicated model without tracking overhead of Vue.js.
   let replicatedModel: ReplicatedModelJS | null = null;
+  const replicatedModelRef: Ref<ReplicatedModelJS | null> = shallowRef(null);
   const rootNodeRef: Ref<INodeJS | null> = shallowRef(null);
   const errorRef: Ref<unknown> = shallowRef(null);
 
   const dispose = () => {
+    // Using `replicatedModelRef.value` here would create a circular dependency.
+    // `toRaw` does not work on `Ref<>`.
     if (replicatedModel !== null) {
       replicatedModel.dispose();
     }
-    replicatedModel = null;
+    replicatedModelRef.value = null;
     rootNodeRef.value = null;
     errorRef.value = null;
   };
@@ -86,6 +95,7 @@ export function useRootNode(
         });
         const unreactiveRootNode = branch.rootNode;
         const reactiveRootNode = toReactiveINodeJS(unreactiveRootNode, cache);
+        replicatedModelRef.value = replicatedModel;
         rootNodeRef.value = reactiveRootNode;
       } else {
         connectedReplicatedModel.dispose();
@@ -99,6 +109,7 @@ export function useRootNode(
   );
 
   return {
+    replicatedModel: replicatedModelRef,
     rootNode: rootNodeRef,
     dispose,
     error: errorRef,