feat(state): introduce rxState asReadOnly API

AdrianRomanski · web-flow · commit baa678fe264b · 2024-05-04T00:14:31.000+02:00
`RxState.asReadOnly` allows to only expose the readable parts of a given `RxState` instance. This enables more fine grained access control to the state you are exposing.

* feat: rx state as read only

* feat: review fixes

* feat: review fix, building docs fix

* feat: review fix, building docs fix
diff --git a/apps/docs/docs/state/api/rx-state.md b/apps/docs/docs/state/api/rx-state.md
@@ -65,6 +65,33 @@ Use the `$` property if you want to read the state without having applied [state
 
 ---
 
+## asReadOnly
+
+##### typeof: Pick&#60;RxState&#60;State&#62;, 'get' | 'select' | 'computed' | 'signal'&#62;
+
+Return RxState in ReadOnly mode that is exposing
+get(), select(), computed() and signal() methods.
+This can be helpful when you don't want others to write in your state.
+
+```typescript
+const readOnlyState = state.asReadOnly();
+const getNum = readOnlyState.get('num');
+const selectNum$ = readOnlyState.select('num');
+```
+
+Trying to call any method that is not exposed in readOnlyState will throw an appropriate error
+
+```typescript
+const readOnlyState = state.asReadOnly();
+readOnlyState['set']('num', (state) => state.num + 1);
+```
+
+```language: none
+throwing -> readOnlyState.set is not a function
+```
+
+---
+
 ## connect
 
 ### Signature
diff --git a/libs/state/spec/rx-state.service.spec.ts b/libs/state/spec/rx-state.service.spec.ts
@@ -8,11 +8,15 @@ import {
   PrimitiveState,
 } from '@test-helpers/rx-angular';
 import { of, scheduled, Subject } from 'rxjs';
+import { ColdObservable } from 'rxjs/internal/testing/ColdObservable';
 import { map, switchMap, take, takeUntil } from 'rxjs/operators';
 import { TestScheduler } from 'rxjs/testing';
 import { RxState } from '../src/lib/rx-state.service';
+import { ReadOnly } from '../src/lib/rx-state.service';
 import { createStateChecker } from './fixtures';
 
+type ReadOnlyPrimitiveState = Pick<RxState<PrimitiveState>, ReadOnly>;
+
 function setupState<T extends object>(cfg: { initialState?: T } = {}) {
   const { initialState } = { ...cfg };
   const state = TestBed.inject(RxState);
@@ -139,25 +143,33 @@ describe('RxStateService', () => {
     it('should return undefined as initial value', () => {
       const state = setupState({ initialState: undefined });
       const val = state.get();
+      const readOnlyVal = state.asReadOnly().get();
       expect(val).toEqual(undefined);
+      expect(readOnlyVal).toEqual(undefined);
     });
 
     it('should return undefined for an undefined property', () => {
       const state = setupState<{ num: number }>({ initialState: undefined });
       const val = state.get('num');
+      const readOnlyVal = state.asReadOnly().get('num');
       expect(val).toEqual(undefined);
+      expect(readOnlyVal).toEqual(undefined);
     });
 
     it('should return value when keys are provided as params', () => {
       const state = setupState({ initialState: initialPrimitiveState });
       const val = state.get('num');
+      const readOnlyVal = state.asReadOnly().get('num');
       expect(val).toEqual(initialPrimitiveState.num);
+      expect(readOnlyVal).toEqual(initialPrimitiveState.num);
     });
 
     it('should return whole state object when no keys provided', () => {
       const state = setupState({ initialState: initialPrimitiveState });
       const val = state.get();
+      const readOnlyVal = state.asReadOnly().get();
       expect(val.num).toEqual(initialPrimitiveState.num);
+      expect(readOnlyVal.num).toEqual(initialPrimitiveState.num);
     });
   });
 
@@ -166,6 +178,7 @@ describe('RxStateService', () => {
       testScheduler.run(({ expectObservable }) => {
         const state = setupState({ initialState: undefined });
         expectObservable(state.select()).toBe('-');
+        expectObservable(state.asReadOnly().select()).toBe('-');
       });
     });
 
@@ -175,14 +188,18 @@ describe('RxStateService', () => {
         expectObservable(state.select()).toBe('s', {
           s: initialPrimitiveState,
         });
+        expectObservable(state.asReadOnly().select()).toBe('s', {
+          s: initialPrimitiveState,
+        });
       });
     });
 
     it('should throw with wrong params', () => {
       const state = setupState({ initialState: initialPrimitiveState });
-
-      expect(() => state.select(true as any)).toThrowError(
-        'wrong params passed to select'
+      const errorMessage = 'wrong params passed to select';
+      expect(() => state.select(true as any)).toThrowError(errorMessage);
+      expect(() => state.asReadOnly().select(true as any)).toThrowError(
+        errorMessage
       );
     });
 
@@ -191,6 +208,7 @@ describe('RxStateService', () => {
         testScheduler.run(({ expectObservable }) => {
           const state = setupState({});
           expectObservable(state.select()).toBe('');
+          expectObservable(state.asReadOnly().select()).toBe('');
         });
       });
 
@@ -202,6 +220,9 @@ describe('RxStateService', () => {
 
             state.set({ num: 42 });
             expectObservable(state.select('num')).toBe('s', { s: 42 });
+            expectObservable(state.asReadOnly().select('num')).toBe('s', {
+              s: 42,
+            });
           });
         });
       });
@@ -356,6 +377,16 @@ describe('RxStateService', () => {
         state.select().subscribe((s) => expect(s).toBe({ num: 43 }));
       });
     });
+    describe('with read only state', () => {
+      it('should throw error when trying to call set from readOnlyState', () => {
+        const readOnlyState: ReadOnlyPrimitiveState = setupState({
+          initialState: initialPrimitiveState,
+        }).asReadOnly();
+        expect((): void => {
+          readOnlyState['set']('num', (state: PrimitiveState) => state.num + 1);
+        }).toThrowError('readOnlyState.set is not a function');
+      });
+    });
   });
 
   describe('connect', () => {
@@ -580,6 +611,24 @@ describe('RxStateService', () => {
         state.ngOnDestroy();
       });
     });
+
+    it('should throw error when trying to call connect from readOnlyState', () => {
+      testScheduler.run(() => {
+        const s: { num: number | undefined } = { num: 0 };
+        const readOnlyState: ReadOnlyPrimitiveState = setupState({
+          initialState: s,
+        }).asReadOnly();
+        expect((): void => {
+          readOnlyState['connect'](
+            scheduled(
+              [{ num: undefined }, { num: 43 }, { num: undefined }],
+              testScheduler
+            ),
+            (o, n) => n
+          );
+        }).toThrowError('readOnlyState.connect is not a function');
+      });
+    });
   });
 
   describe('setAccumulator', () => {
@@ -640,6 +689,22 @@ describe('RxStateService', () => {
       expect(numAcc1Calls).toBe(1);
       expect(numAcc2Calls).toBe(1);
     });
+    it('should throw error when trying to call setAccumulator from readOnlyState', () => {
+      let numAccCalls = 0;
+      const customAcc = <T>(s: T, sl: Partial<T>) => {
+        ++numAccCalls;
+        return {
+          ...s,
+          ...sl,
+        };
+      };
+      const readOnlyState: ReadOnlyPrimitiveState = setupState({
+        initialState: initialPrimitiveState,
+      }).asReadOnly();
+      expect((): void => {
+        readOnlyState['setAccumulator'](customAcc);
+      }).toThrowError('readOnlyState.setAccumulator is not a function');
+    });
   });
 
   describe('hold', () => {
@@ -665,5 +730,22 @@ describe('RxStateService', () => {
       state.hold(of(1, 2, 3), effect);
       expect(calls).toBe(3);
     }));
+
+    it('should throw error when trying to call hold from readOnlyState', () => {
+      testScheduler.run(({ cold, expectSubscriptions }) => {
+        const readOnlyState: ReadOnlyPrimitiveState = setupState({
+          initialState: initialPrimitiveState,
+        }).asReadOnly();
+        const test$: ColdObservable<number> = cold('(abc)', {
+          a: 1,
+          b: 2,
+          c: 3,
+        });
+        const stop: Subject<void> = new Subject();
+        expect((): void => {
+          readOnlyState['hold'](test$.pipe(takeUntil(stop)));
+        }).toThrowError('readOnlyState.hold is not a function');
+      });
+    });
   });
 });
diff --git a/libs/state/src/lib/rx-state.service.ts b/libs/state/src/lib/rx-state.service.ts
@@ -46,6 +46,8 @@ export type ProjectValueReducer<Type, Key extends keyof Type, Value> = (
   value: Value
 ) => Type[Key];
 
+export type ReadOnly = 'get' | 'select' | 'computed' | 'signal';
+
 /**
  * @description
  * RxState is a light-weight reactive state management service for managing local state in angular.
@@ -99,6 +101,31 @@ export class RxState<State extends object>
     this.subscription.unsubscribe();
   }
 
+  /**
+   * @description
+   *
+   * Return RxState in ReadOnly mode exposing only methods for reading state
+   * get(), select(), computed() and signal() methods.
+   * This can be helpful when you don't want others to write in your state.
+   *
+   * @example
+   * ```typescript
+   * const readOnlyState = state.asReadOnly();
+   * const getNum = state.get('num');
+   * const selectNum$ = state.select('num');
+   * ```
+   *
+   * @return Pick<RxState<State>, ReadOnly>
+   */
+  asReadOnly(): Pick<RxState<State>, ReadOnly> {
+    return {
+      get: this.get.bind(this),
+      select: this.select.bind(this),
+      computed: this.computed.bind(this),
+      signal: this.signal.bind(this),
+    };
+  }
+
   /**
    * @description
    *
