fix(journey-client): use Effect Either to handle journey response in start and next

Author: vatsalparikh

lefthook.yml

@@ -3,7 +3,7 @@ pre-commit:
     nx-sync:
       run: pnpm nx sync
     nx-check:
-      run: pnpm nx affected -t typecheck lint build api-report --tui=false
+      run: env -u GIT_DIR pnpm nx affected -t typecheck lint build api-report --tui=false
       stage_fixed: true
     format:
       run: pnpm nx format:write

packages/journey-client/package.json

@@ -39,6 +39,7 @@
     "@forgerock/sdk-utilities": "workspace:*",
     "@forgerock/storage": "workspace:*",
     "@reduxjs/toolkit": "catalog:",
+    "effect": "catalog:effect",
     "tslib": "^2.3.0"
   },
   "devDependencies": {

packages/journey-client/src/lib/client.store.ts

@@ -5,6 +5,7 @@
  * of the MIT license. See the LICENSE file for details.
  */
 
+import { Either } from 'effect';
 import { logger as loggerFn, LogLevel, CustomLogger } from '@forgerock/sdk-logger';
 import { callbackType } from '@forgerock/sdk-types';
 import {
@@ -156,12 +157,10 @@ export async function journey<ActionType extends ActionTypes = ActionTypes>({
   const self: JourneyClient = {
     start: async (options?: StartParam) => {
       const { data, error } = await store.dispatch(journeyApi.endpoints.start.initiate(options));
-      const result = handleJourneyResponse(data, error);
-      if ('error' in result) {
-        return result;
-      }
-
-      return createJourneyObject(result);
+      return Either.match(handleJourneyResponse(data, error), {
+        onLeft: (err) => err,
+        onRight: (step) => createJourneyObject(step),
+      });
     },
 
     /**
@@ -171,12 +170,10 @@ export async function journey<ActionType extends ActionTypes = ActionTypes>({
       const { data, error } = await store.dispatch(
         journeyApi.endpoints.next.initiate({ step, options }),
       );
-      const result = handleJourneyResponse(data, error);
-      if ('error' in result) {
-        return result;
-      }
-
-      return createJourneyObject(result);
+      return Either.match(handleJourneyResponse(data, error), {
+        onLeft: (err) => err,
+        onRight: (step) => createJourneyObject(step),
+      });
     },
 
     // TODO: Remove the actual redirect from this method and just return the URL to the caller

packages/journey-client/src/lib/journey.utils.test.ts

@@ -5,6 +5,7 @@
  * of the MIT license. See the LICENSE file for details.
  */
 
+import { Either } from 'effect';
 import { describe, expect, it } from 'vitest';
 
 import { StepType } from '../types.js';
@@ -64,33 +65,42 @@ describe('createJourneyObject', () => {
 });
 
 describe('handleJourneyResponse', () => {
-  it('returns Step data when FetchBaseQueryError has numeric status and object body', () => {
+  it('returns Right(Step) when FetchBaseQueryError has numeric status and object body', () => {
     const body = { code: 401, message: 'Access Denied', reason: 'Unauthorized' };
     const error = { status: 401, data: body };
 
     const result = handleJourneyResponse(undefined, error);
 
-    expect(result).toBe(body);
+    expect(Either.isRight(result)).toBe(true);
+    if (Either.isRight(result)) {
+      expect(result.right).toBe(body);
+    }
   });
 
-  it('returns GenericError when FetchBaseQueryError has numeric status but non-object body', () => {
+  it('returns Left(GenericError) when FetchBaseQueryError has numeric status but non-object body', () => {
     const error = { status: 500, data: 'Internal Server Error' };
 
     const result = handleJourneyResponse(undefined, error);
 
-    expect(result).toMatchObject({ error: 'request_failed', type: 'unknown_error' });
+    expect(Either.isLeft(result)).toBe(true);
+    if (Either.isLeft(result)) {
+      expect(result.left).toMatchObject({ error: 'request_failed', type: 'unknown_error' });
+    }
   });
 
-  it('returns GenericError for FETCH_ERROR', () => {
+  it('returns Left(GenericError) for FETCH_ERROR', () => {
     const error = { status: 'FETCH_ERROR' as const, error: 'Network error' };
 
     const result = handleJourneyResponse(undefined, error);
 
-    expect(result).toMatchObject({ error: 'request_failed', type: 'unknown_error' });
-    expect((result as { message: string }).message).toContain('Network error');
+    expect(Either.isLeft(result)).toBe(true);
+    if (Either.isLeft(result)) {
+      expect(result.left).toMatchObject({ error: 'request_failed', type: 'unknown_error' });
+      expect(result.left.message).toContain('Network error');
+    }
   });
 
-  it('returns GenericError for PARSING_ERROR', () => {
+  it('returns Left(GenericError) for PARSING_ERROR', () => {
     const error = {
       status: 'PARSING_ERROR' as const,
       originalStatus: 200,
@@ -100,48 +110,66 @@ describe('handleJourneyResponse', () => {
 
     const result = handleJourneyResponse(undefined, error);
 
-    expect(result).toMatchObject({ error: 'request_failed', type: 'unknown_error' });
-    expect((result as { message: string }).message).toContain('JSON parse error');
+    expect(Either.isLeft(result)).toBe(true);
+    if (Either.isLeft(result)) {
+      expect(result.left).toMatchObject({ error: 'request_failed', type: 'unknown_error' });
+      expect(result.left.message).toContain('JSON parse error');
+    }
   });
 
-  it('returns GenericError for TIMEOUT_ERROR', () => {
+  it('returns Left(GenericError) for TIMEOUT_ERROR', () => {
     const error = { status: 'TIMEOUT_ERROR' as const, error: 'Request timed out' };
 
     const result = handleJourneyResponse(undefined, error);
 
-    expect(result).toMatchObject({ error: 'request_failed', type: 'unknown_error' });
-    expect((result as { message: string }).message).toContain('Request timed out');
+    expect(Either.isLeft(result)).toBe(true);
+    if (Either.isLeft(result)) {
+      expect(result.left).toMatchObject({ error: 'request_failed', type: 'unknown_error' });
+      expect(result.left.message).toContain('Request timed out');
+    }
   });
 
-  it('returns GenericError for CUSTOM_ERROR', () => {
+  it('returns Left(GenericError) for CUSTOM_ERROR', () => {
     const error = { status: 'CUSTOM_ERROR' as const, error: 'Custom error occurred' };
 
     const result = handleJourneyResponse(undefined, error);
 
-    expect(result).toMatchObject({ error: 'request_failed', type: 'unknown_error' });
-    expect((result as { message: string }).message).toContain('Custom error occurred');
+    expect(Either.isLeft(result)).toBe(true);
+    if (Either.isLeft(result)) {
+      expect(result.left).toMatchObject({ error: 'request_failed', type: 'unknown_error' });
+      expect(result.left.message).toContain('Custom error occurred');
+    }
   });
 
-  it('returns GenericError for SerializedError', () => {
+  it('returns Left(GenericError) for SerializedError', () => {
     const error = { name: 'Error', message: 'Something went wrong', stack: '...' };
 
     const result = handleJourneyResponse(undefined, error);
 
-    expect(result).toMatchObject({ error: 'request_failed', type: 'unknown_error' });
-    expect((result as { message: string }).message).toContain('Something went wrong');
+    expect(Either.isLeft(result)).toBe(true);
+    if (Either.isLeft(result)) {
+      expect(result.left).toMatchObject({ error: 'request_failed', type: 'unknown_error' });
+      expect(result.left.message).toContain('Something went wrong');
+    }
   });
 
-  it('returns GenericError when no data and no error', () => {
+  it('returns Left(GenericError) when no data and no error', () => {
     const result = handleJourneyResponse(undefined, undefined);
 
-    expect(result).toMatchObject({ error: 'no_response_data', type: 'unknown_error' });
+    expect(Either.isLeft(result)).toBe(true);
+    if (Either.isLeft(result)) {
+      expect(result.left).toMatchObject({ error: 'no_response_data', type: 'unknown_error' });
+    }
   });
 
-  it('returns data when no error and data is present', () => {
+  it('returns Right(Step) when no error and data is present', () => {
     const data: Step = { authId: 'test-auth-id', callbacks: [] };
 
     const result = handleJourneyResponse(data, undefined);
 
-    expect(result).toBe(data);
+    expect(Either.isRight(result)).toBe(true);
+    if (Either.isRight(result)) {
+      expect(result.right).toBe(data);
+    }
   });
 });

packages/journey-client/src/lib/journey.utils.ts

@@ -5,6 +5,7 @@
  * of the MIT license. See the LICENSE file for details.
  */
 
+import { Either } from 'effect';
 import { StepType } from '@forgerock/sdk-types';
 
 import type { GenericError, Step } from '@forgerock/sdk-types';
@@ -56,16 +57,19 @@ export function createJourneyObject(
 }
 
 /**
- * Resolves an RTK Query response to a Step or GenericError.
+ * Resolves an RTK Query response to an Either of Step or GenericError.
+ *
+ * Right(Step) carries either a successful response or an HTTP failure body
+ * that the caller will narrow via createJourneyObject.
+ * Left(GenericError) represents infrastructure failures with no usable AM body.
  *
  * @param data - The Step data returned by the RTK Query endpoint, if any
  * @param error - The error returned by the RTK Query endpoint, if any
- * @returns Step on success, GenericError on failure
  */
 export function handleJourneyResponse(
   data: Step | undefined,
   error: FetchBaseQueryError | SerializedError | undefined,
-): Step | GenericError {
+): Either.Either<Step, GenericError> {
   /**
    * https://redux-toolkit.js.org/rtk-query/api/fetchBaseQuery#signature
    * FetchBaseQueryError with status: number means AM returned an HTTP response with a JSON body.
@@ -79,7 +83,7 @@ export function handleJourneyResponse(
     typeof error.data === 'object' &&
     error.data !== null
   ) {
-    return error.data as Step;
+    return Either.right(error.data as Step);
   }
 
   /**
@@ -89,20 +93,20 @@ export function handleJourneyResponse(
    */
   if (error) {
     const msg = 'error' in error ? error.error : 'message' in error ? error.message : undefined;
-    return {
+    return Either.left({
       error: 'request_failed',
       message: `Request failed: ${msg ?? 'Unknown error'}`,
       type: 'unknown_error',
-    };
+    });
   }
 
   if (!data) {
-    return {
+    return Either.left({
       error: 'no_response_data',
       message: 'No data received from server',
       type: 'unknown_error',
-    };
+    });
   }
 
-  return data;
+  return Either.right(data);
 }