[PM-4345] Ps/provide migration helpers for key definitions (#7050)

* Provide helpers to build keys from KeyDefinitions

* Move usage comments to the helper class

* `npm run prettier` 🤖

* Prefer setters and getters to key builders

* Add documentation to migration helper methods

* Fix migration helper tests

* Prefer defined types to ad hoc

* `npm run prettier` 🤖

libs/common/src/state-migrations/migration-helper.spec.ts

@@ -18,6 +18,8 @@ const exampleJSON = {
   "23e61a5f-2ece-4f5e-b499-f0bc489482a9": {
     otherStuff: "otherStuff2",
   },
+  global_serviceName_key: "global_serviceName_key",
+  user_userId_serviceName_key: "user_userId_serviceName_key",
 };
 
 describe("RemoveLegacyEtmKeyMigrator", () => {
@@ -64,6 +66,79 @@ describe("RemoveLegacyEtmKeyMigrator", () => {
       expect(accounts).toEqual([]);
     });
   });
+
+  describe("getFromGlobal", () => {
+    it("should return the correct value", async () => {
+      sut.currentVersion = 10;
+      const value = await sut.getFromGlobal({
+        stateDefinition: { name: "serviceName" },
+        key: "key",
+      });
+      expect(value).toEqual("global_serviceName_key");
+    });
+
+    it("should throw if the current version is less than 10", () => {
+      expect(() =>
+        sut.getFromGlobal({ stateDefinition: { name: "serviceName" }, key: "key" }),
+      ).toThrowError("No key builder should be used for versions prior to 10.");
+    });
+  });
+
+  describe("setToGlobal", () => {
+    it("should set the correct value", async () => {
+      sut.currentVersion = 10;
+      await sut.setToGlobal({ stateDefinition: { name: "serviceName" }, key: "key" }, "new_value");
+      expect(storage.save).toHaveBeenCalledWith("global_serviceName_key", "new_value");
+    });
+
+    it("should throw if the current version is less than 10", () => {
+      expect(() =>
+        sut.setToGlobal(
+          { stateDefinition: { name: "serviceName" }, key: "key" },
+          "global_serviceName_key",
+        ),
+      ).toThrowError("No key builder should be used for versions prior to 10.");
+    });
+  });
+
+  describe("getFromUser", () => {
+    it("should return the correct value", async () => {
+      sut.currentVersion = 10;
+      const value = await sut.getFromUser("userId", {
+        stateDefinition: { name: "serviceName" },
+        key: "key",
+      });
+      expect(value).toEqual("user_userId_serviceName_key");
+    });
+
+    it("should throw if the current version is less than 10", () => {
+      expect(() =>
+        sut.getFromUser("userId", { stateDefinition: { name: "serviceName" }, key: "key" }),
+      ).toThrowError("No key builder should be used for versions prior to 10.");
+    });
+  });
+
+  describe("setToUser", () => {
+    it("should set the correct value", async () => {
+      sut.currentVersion = 10;
+      await sut.setToUser(
+        "userId",
+        { stateDefinition: { name: "serviceName" }, key: "key" },
+        "new_value",
+      );
+      expect(storage.save).toHaveBeenCalledWith("user_userId_serviceName_key", "new_value");
+    });
+
+    it("should throw if the current version is less than 10", () => {
+      expect(() =>
+        sut.setToUser(
+          "userId",
+          { stateDefinition: { name: "serviceName" }, key: "key" },
+          "new_value",
+        ),
+      ).toThrowError("No key builder should be used for versions prior to 10.");
+    });
+  });
 });
 
 /** Helper to create well-mocked migration helpers in migration tests */