Add BaseControllerV2 state metadata

State metadata has been added to the new BaseController constructor as
a required constructor parameter. The metadata describes how to derive
the state that should be persisted, and how to derive an 'anonymized'
representation of the controller state.

The metadata describes top-level properties only, but it allows you to
define a function to derive the anonymized or persistent state for each
property. The only requirement of this derivation function is that the
output is also valid JSON.

This is part of the controller redesign (#337).

Author: Gudahtt

src/BaseControllerV2.test.ts

@@ -1,12 +1,19 @@
 import type { Draft } from 'immer';
 import * as sinon from 'sinon';
 
-import { BaseController } from './BaseControllerV2';
+import { BaseController, getAnonymizedState, getPersistentState } from './BaseControllerV2';
 
 type MockControllerState = {
   count: number;
 };
 
+const mockControllerStateMetadata = {
+  count: {
+    persist: true,
+    anonymous: true,
+  },
+};
+
 class MockController extends BaseController<MockControllerState> {
   update(callback: (state: Draft<MockControllerState>) => void | MockControllerState) {
     super.update(callback);
@@ -19,21 +26,27 @@ class MockController extends BaseController<MockControllerState> {
 
 describe('BaseController', () => {
   it('should set initial state', () => {
-    const controller = new MockController({ count: 0 });
+    const controller = new MockController({ count: 0 }, mockControllerStateMetadata);
 
     expect(controller.state).toEqual({ count: 0 });
   });
 
+  it('should set initial schema', () => {
+    const controller = new MockController({ count: 0 }, mockControllerStateMetadata);
+
+    expect(controller.metadata).toEqual(mockControllerStateMetadata);
+  });
+
   it('should not allow mutating state directly', () => {
-    const controller = new MockController({ count: 0 });
+    const controller = new MockController({ count: 0 }, mockControllerStateMetadata);
 
     expect(() => {
       controller.state = { count: 1 };
     }).toThrow();
   });
 
   it('should allow updating state by modifying draft', () => {
-    const controller = new MockController({ count: 0 });
+    const controller = new MockController({ count: 0 }, mockControllerStateMetadata);
 
     controller.update((draft) => {
       draft.count += 1;
@@ -43,7 +56,7 @@ describe('BaseController', () => {
   });
 
   it('should allow updating state by return a value', () => {
-    const controller = new MockController({ count: 0 });
+    const controller = new MockController({ count: 0 }, mockControllerStateMetadata);
 
     controller.update(() => {
       return { count: 1 };
@@ -53,7 +66,7 @@ describe('BaseController', () => {
   });
 
   it('should throw an error if update callback modifies draft and returns value', () => {
-    const controller = new MockController({ count: 0 });
+    const controller = new MockController({ count: 0 }, mockControllerStateMetadata);
 
     expect(() => {
       controller.update((draft) => {
@@ -64,7 +77,7 @@ describe('BaseController', () => {
   });
 
   it('should inform subscribers of state changes', () => {
-    const controller = new MockController({ count: 0 });
+    const controller = new MockController({ count: 0 }, mockControllerStateMetadata);
     const listener1 = sinon.stub();
     const listener2 = sinon.stub();
 
@@ -81,7 +94,7 @@ describe('BaseController', () => {
   });
 
   it('should inform a subscriber of each state change once even after multiple subscriptions', () => {
-    const controller = new MockController({ count: 0 });
+    const controller = new MockController({ count: 0 }, mockControllerStateMetadata);
     const listener1 = sinon.stub();
 
     controller.subscribe(listener1);
@@ -95,7 +108,7 @@ describe('BaseController', () => {
   });
 
   it('should no longer inform a subscriber about state changes after unsubscribing', () => {
-    const controller = new MockController({ count: 0 });
+    const controller = new MockController({ count: 0 }, mockControllerStateMetadata);
     const listener1 = sinon.stub();
 
     controller.subscribe(listener1);
@@ -108,7 +121,7 @@ describe('BaseController', () => {
   });
 
   it('should no longer inform a subscriber about state changes after unsubscribing once, even if they subscribed many times', () => {
-    const controller = new MockController({ count: 0 });
+    const controller = new MockController({ count: 0 }, mockControllerStateMetadata);
     const listener1 = sinon.stub();
 
     controller.subscribe(listener1);
@@ -122,7 +135,7 @@ describe('BaseController', () => {
   });
 
   it('should allow unsubscribing listeners who were never subscribed', () => {
-    const controller = new MockController({ count: 0 });
+    const controller = new MockController({ count: 0 }, mockControllerStateMetadata);
     const listener1 = sinon.stub();
 
     expect(() => {
@@ -131,7 +144,7 @@ describe('BaseController', () => {
   });
 
   it('should no longer update subscribers after being destroyed', () => {
-    const controller = new MockController({ count: 0 });
+    const controller = new MockController({ count: 0 }, mockControllerStateMetadata);
     const listener1 = sinon.stub();
     const listener2 = sinon.stub();
 
@@ -146,3 +159,275 @@ describe('BaseController', () => {
     expect(listener2.callCount).toEqual(0);
   });
 });
+
+describe('getAnonymizedState', () => {
+  it('should return empty state', () => {
+    expect(getAnonymizedState({}, {})).toEqual({});
+  });
+
+  it('should return empty state when no properties are anonymized', () => {
+    const anonymizedState = getAnonymizedState({ count: 1 }, { count: { anonymous: false, persist: false } });
+    expect(anonymizedState).toEqual({});
+  });
+
+  it('should return state that is already anonymized', () => {
+    const anonymizedState = getAnonymizedState(
+      {
+        password: 'secret password',
+        privateKey: '123',
+        network: 'mainnet',
+        tokens: ['DAI', 'USDC'],
+      },
+      {
+        password: {
+          anonymous: false,
+          persist: false,
+        },
+        privateKey: {
+          anonymous: false,
+          persist: false,
+        },
+        network: {
+          anonymous: true,
+          persist: false,
+        },
+        tokens: {
+          anonymous: true,
+          persist: false,
+        },
+      },
+    );
+    expect(anonymizedState).toEqual({ network: 'mainnet', tokens: ['DAI', 'USDC'] });
+  });
+
+  it('should use anonymizing function to anonymize state', () => {
+    const anonymizeTransactionHash = (hash: string) => {
+      return hash.split('').reverse().join('');
+    };
+
+    const anonymizedState = getAnonymizedState(
+      {
+        transactionHash: '0x1234',
+      },
+      {
+        transactionHash: {
+          anonymous: anonymizeTransactionHash,
+          persist: false,
+        },
+      },
+    );
+
+    expect(anonymizedState).toEqual({ transactionHash: '4321x0' });
+  });
+
+  it('should allow returning a partial object from an anonymizing function', () => {
+    const anonymizeTxMeta = (txMeta: { hash: string; value: number }) => {
+      return { value: txMeta.value };
+    };
+
+    const anonymizedState = getAnonymizedState(
+      {
+        txMeta: {
+          hash: '0x123',
+          value: 10,
+        },
+      },
+      {
+        txMeta: {
+          anonymous: anonymizeTxMeta,
+          persist: false,
+        },
+      },
+    );
+
+    expect(anonymizedState).toEqual({ txMeta: { value: 10 } });
+  });
+
+  it('should allow returning a nested partial object from an anonymizing function', () => {
+    const anonymizeTxMeta = (txMeta: { hash: string; value: number; history: { hash: string; value: number }[] }) => {
+      return {
+        history: txMeta.history.map((entry) => {
+          return { value: entry.value };
+        }),
+        value: txMeta.value,
+      };
+    };
+
+    const anonymizedState = getAnonymizedState(
+      {
+        txMeta: {
+          hash: '0x123',
+          history: [
+            {
+              hash: '0x123',
+              value: 9,
+            },
+          ],
+          value: 10,
+        },
+      },
+      {
+        txMeta: {
+          anonymous: anonymizeTxMeta,
+          persist: false,
+        },
+      },
+    );
+
+    expect(anonymizedState).toEqual({ txMeta: { history: [{ value: 9 }], value: 10 } });
+  });
+
+  it('should allow transforming types in an anonymizing function', () => {
+    const anonymizedState = getAnonymizedState(
+      {
+        count: '1',
+      },
+      {
+        count: {
+          anonymous: (count) => Number(count),
+          persist: false,
+        },
+      },
+    );
+
+    expect(anonymizedState).toEqual({ count: 1 });
+  });
+});
+
+describe('getPersistentState', () => {
+  it('should return empty state', () => {
+    expect(getPersistentState({}, {})).toEqual({});
+  });
+
+  it('should return empty state when no properties are persistent', () => {
+    const persistentState = getPersistentState({ count: 1 }, { count: { anonymous: false, persist: false } });
+    expect(persistentState).toEqual({});
+  });
+
+  it('should return persistent state', () => {
+    const persistentState = getPersistentState(
+      {
+        password: 'secret password',
+        privateKey: '123',
+        network: 'mainnet',
+        tokens: ['DAI', 'USDC'],
+      },
+      {
+        password: {
+          anonymous: false,
+          persist: true,
+        },
+        privateKey: {
+          anonymous: false,
+          persist: true,
+        },
+        network: {
+          anonymous: false,
+          persist: false,
+        },
+        tokens: {
+          anonymous: false,
+          persist: false,
+        },
+      },
+    );
+    expect(persistentState).toEqual({ password: 'secret password', privateKey: '123' });
+  });
+
+  it('should use function to derive persistent state', () => {
+    const normalizeTransacitonHash = (hash: string) => {
+      return hash.toLowerCase();
+    };
+
+    const persistentState = getPersistentState(
+      {
+        transactionHash: '0X1234',
+      },
+      {
+        transactionHash: {
+          anonymous: false,
+          persist: normalizeTransacitonHash,
+        },
+      },
+    );
+
+    expect(persistentState).toEqual({ transactionHash: '0x1234' });
+  });
+
+  it('should allow returning a partial object from a persist function', () => {
+    const getPersistentTxMeta = (txMeta: { hash: string; value: number }) => {
+      return { value: txMeta.value };
+    };
+
+    const persistentState = getPersistentState(
+      {
+        txMeta: {
+          hash: '0x123',
+          value: 10,
+        },
+      },
+      {
+        txMeta: {
+          anonymous: false,
+          persist: getPersistentTxMeta,
+        },
+      },
+    );
+
+    expect(persistentState).toEqual({ txMeta: { value: 10 } });
+  });
+
+  it('should allow returning a nested partial object from a persist function', () => {
+    const getPersistentTxMeta = (txMeta: {
+      hash: string;
+      value: number;
+      history: { hash: string; value: number }[];
+    }) => {
+      return {
+        history: txMeta.history.map((entry) => {
+          return { value: entry.value };
+        }),
+        value: txMeta.value,
+      };
+    };
+
+    const persistentState = getPersistentState(
+      {
+        txMeta: {
+          hash: '0x123',
+          history: [
+            {
+              hash: '0x123',
+              value: 9,
+            },
+          ],
+          value: 10,
+        },
+      },
+      {
+        txMeta: {
+          anonymous: false,
+          persist: getPersistentTxMeta,
+        },
+      },
+    );
+
+    expect(persistentState).toEqual({ txMeta: { history: [{ value: 9 }], value: 10 } });
+  });
+
+  it('should allow transforming types in a persist function', () => {
+    const persistentState = getPersistentState(
+      {
+        count: '1',
+      },
+      {
+        count: {
+          anonymous: false,
+          persist: (count) => Number(count),
+        },
+      },
+    );
+
+    expect(persistentState).toEqual({ count: 1 });
+  });
+});