refactor(journey-client): use Either for response parsing in start and next

Author: vatsalparikh

packages/journey-client/api-report/journey-client.api.md

@@ -229,7 +229,7 @@ export type JourneyLoginSuccess = AuthResponse & {
     getSuccessUrl: () => string | undefined;
 };
 
-// @public
+// @public (undocumented)
 export type JourneyResult = JourneyStep | JourneyLoginSuccess | JourneyLoginFailure | GenericError;
 
 // @public

packages/journey-client/api-report/journey-client.types.api.md

@@ -216,7 +216,7 @@ export type JourneyLoginSuccess = AuthResponse & {
     getSuccessUrl: () => string | undefined;
 };
 
-// @public
+// @public (undocumented)
 export type JourneyResult = JourneyStep | JourneyLoginSuccess | JourneyLoginFailure | GenericError;
 
 // @public

packages/journey-client/package.json

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

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

@@ -21,18 +21,15 @@ import { createJourneyStore } from './client.store.utils.js';
 import { configSlice } from './config.slice.js';
 import { journeyApi } from './journey.api.js';
 import { createStorage } from '@forgerock/storage';
-import { createJourneyObject, handleJourneyResponse } from './journey.utils.js';
+import { match } from 'effect/Either';
+import { createJourneyObject, parseJourneyResponse } from './journey.utils.js';
+import type { JourneyResult } from './journey.utils.js';
 import { wellknownApi } from './wellknown.api.js';
 
 import type { JourneyStep } from './step.utils.js';
 import type { JourneyClientConfig } from './config.types.js';
 import type { RedirectCallback } from './callbacks/redirect-callback.js';
 import type { NextOptions, StartParam, ResumeOptions } from './interfaces.js';
-import type { JourneyLoginFailure } from './login-failure.utils.js';
-import type { JourneyLoginSuccess } from './login-success.utils.js';
-
-/** Result type for journey client methods. */
-export type JourneyResult = JourneyStep | JourneyLoginSuccess | JourneyLoginFailure | GenericError;
 
 /** The journey client instance returned by the `journey()` function. */
 export interface JourneyClient {
@@ -158,28 +155,22 @@ export async function journey<ActionType extends ActionTypes = ActionTypes>({
     subscribe: store.subscribe,
 
     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);
+      const response = await store.dispatch(journeyApi.endpoints.start.initiate(options));
+      return match(parseJourneyResponse(response), {
+        onLeft: (err): JourneyResult => err,
+        onRight: (step): JourneyResult => createJourneyObject(step),
+      });
     },
 
     /**
      * Submits the current Step payload to the authentication API and retrieves the next JourneyStep in the journey.
      */
     next: async (step: JourneyStep, options?: NextOptions) => {
-      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);
+      const response = await store.dispatch(journeyApi.endpoints.next.initiate({ step, options }));
+      return match(parseJourneyResponse(response), {
+        onLeft: (err): JourneyResult => err,
+        onRight: (step): JourneyResult => 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

@@ -10,7 +10,7 @@ import { describe, expect, it } from 'vitest';
 import { StepType } from '../types.js';
 import { type Step } from '../index.js';
 
-import { createJourneyObject, handleJourneyResponse } from './journey.utils.js';
+import { createJourneyObject, parseJourneyResponse } from './journey.utils.js';
 import type { JourneyLoginFailure } from './login-failure.utils.js';
 
 describe('createJourneyObject', () => {
@@ -63,85 +63,99 @@ describe('createJourneyObject', () => {
   });
 });
 
-describe('handleJourneyResponse', () => {
-  it('returns Step data when FetchBaseQueryError has numeric status and object body', () => {
+describe('parseJourneyResponse', () => {
+  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);
+    const result = parseJourneyResponse({ data: undefined, error });
 
-    expect(result).toBe(body);
+    expect(result._tag).toBe('Right');
+    expect((result as { right: unknown }).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);
+    const result = parseJourneyResponse({ data: undefined, error });
 
-    expect(result).toMatchObject({ error: 'request_failed', type: 'unknown_error' });
+    expect(result._tag).toBe('Left');
+    expect((result as { left: unknown }).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);
+    const result = parseJourneyResponse({ data: undefined, error });
 
-    expect(result).toMatchObject({ error: 'request_failed', type: 'unknown_error' });
-    expect((result as { message: string }).message).toContain('Network error');
+    expect(result._tag).toBe('Left');
+    expect((result as { left: { message: string } }).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,
       data: '<html>Not JSON</html>',
       error: 'JSON parse error',
     };
 
-    const result = handleJourneyResponse(undefined, error);
+    const result = parseJourneyResponse({ data: undefined, error });
 
-    expect(result).toMatchObject({ error: 'request_failed', type: 'unknown_error' });
-    expect((result as { message: string }).message).toContain('JSON parse error');
+    expect(result._tag).toBe('Left');
+    expect((result as { left: { message: string } }).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);
+    const result = parseJourneyResponse({ data: undefined, error });
 
-    expect(result).toMatchObject({ error: 'request_failed', type: 'unknown_error' });
-    expect((result as { message: string }).message).toContain('Request timed out');
+    expect(result._tag).toBe('Left');
+    expect((result as { left: { message: string } }).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);
+    const result = parseJourneyResponse({ data: undefined, error });
 
-    expect(result).toMatchObject({ error: 'request_failed', type: 'unknown_error' });
-    expect((result as { message: string }).message).toContain('Custom error occurred');
+    expect(result._tag).toBe('Left');
+    expect((result as { left: { message: string } }).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);
+    const result = parseJourneyResponse({ data: undefined, error });
 
-    expect(result).toMatchObject({ error: 'request_failed', type: 'unknown_error' });
-    expect((result as { message: string }).message).toContain('Something went wrong');
+    expect(result._tag).toBe('Left');
+    expect((result as { left: { message: string } }).left.message).toContain(
+      'Something went wrong',
+    );
   });
 
-  it('returns GenericError when no data and no error', () => {
-    const result = handleJourneyResponse(undefined, undefined);
+  it('returns left(GenericError) when no data and no error', () => {
+    const result = parseJourneyResponse({ data: undefined, error: undefined });
 
-    expect(result).toMatchObject({ error: 'no_response_data', type: 'unknown_error' });
+    expect(result._tag).toBe('Left');
+    expect((result as { left: unknown }).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);
+    const result = parseJourneyResponse({ data, error: undefined });
 
-    expect(result).toBe(data);
+    expect(result._tag).toBe('Right');
+    expect((result as { right: unknown }).right).toBe(data);
   });
 });

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

@@ -5,6 +5,8 @@
  * of the MIT license. See the LICENSE file for details.
  */
 
+import { left, right, type Either } from 'effect/Either';
+
 import { StepType } from '@forgerock/sdk-types';
 
 import type { GenericError, Step } from '@forgerock/sdk-types';
@@ -19,6 +21,8 @@ import type { JourneyStep } from './step.utils.js';
 import type { JourneyLoginFailure } from './login-failure.utils.js';
 import type { JourneyLoginSuccess } from './login-success.utils.js';
 
+export type JourneyResult = JourneyStep | JourneyLoginSuccess | JourneyLoginFailure | GenericError;
+
 /**
  * Creates a journey object from a raw Step response.
  * Determines the step type based on the presence of authId or successUrl properties
@@ -56,53 +60,51 @@ export function createJourneyObject(
 }
 
 /**
- * Resolves an RTK Query response to a Step or GenericError.
- *
- * @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
+ * Parses a resolved RTK Query journey response into Either<Step, GenericError>.
+ * Right = valid Step to classify; Left = infrastructure failure.
  */
-export function handleJourneyResponse(
-  data: Step | undefined,
-  error: FetchBaseQueryError | SerializedError | undefined,
-): 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.
-   * Only this variant can carry an AM failure payload — FETCH_ERROR, PARSING_ERROR, TIMEOUT_ERROR,
-   * and CUSTOM_ERROR either have no body or a non-object body (raw string for PARSING_ERROR).
-   */
-  if (
-    error &&
-    'status' in error &&
-    typeof error.status === 'number' &&
-    typeof error.data === 'object' &&
-    error.data !== null
-  ) {
-    return error.data as Step;
+export function parseJourneyResponse(res: {
+  data?: Step;
+  error?: FetchBaseQueryError | SerializedError;
+}): Either<Step, GenericError> {
+  // https://redux-toolkit.js.org/rtk-query/usage-with-typescript#type-safe-error-handling
+  // FetchBaseQueryError non-HTTP variants expose `error` string
+  if (res.error && 'error' in res.error) {
+    return left({
+      error: 'request_failed',
+      message: `Request failed: ${res.error.error}`,
+      type: 'unknown_error',
+    });
   }
 
-  /**
-   * https://redux-toolkit.js.org/rtk-query/usage-with-typescript#type-safe-error-handling
-   * All other FetchBaseQueryError variants expose an `error` string; SerializedError exposes `message`.
-   * Both represent infrastructure failures with no usable AM response body.
-   */
-  if (error) {
-    const msg = 'error' in error ? error.error : 'message' in error ? error.message : undefined;
-    return {
+  // SerializedError exposes `message`
+  if (res.error && 'message' in res.error) {
+    return left({
       error: 'request_failed',
-      message: `Request failed: ${msg ?? 'Unknown error'}`,
+      message: `Request failed: ${res.error.message ?? 'Unknown error'}`,
       type: 'unknown_error',
-    };
+    });
   }
 
-  if (!data) {
-    return {
+  if (!res.data) {
+    return left({
       error: 'no_response_data',
       message: 'No data received from server',
       type: 'unknown_error',
-    };
+    });
+  }
+
+  // https://redux-toolkit.js.org/rtk-query/api/fetchBaseQuery#signature
+  // FetchBaseQueryError with numeric status + object body = AM failure step over HTTP error
+  if (
+    res.error &&
+    'status' in res.error &&
+    typeof res.error.status === 'number' &&
+    typeof res.error.data === 'object' &&
+    res.error.data !== null
+  ) {
+    return right(res.error.data);
   }
 
-  return data;
+  return right(res.data);
 }

packages/journey-client/src/types.ts

@@ -61,7 +61,7 @@ export * from './lib/callbacks/validated-create-username-callback.js';
 
 // Re-export types used in public API signatures that aren't covered above
 export type { DeviceProfileData, Geolocation } from './lib/device/interfaces.js';
-export type { JourneyResult } from './lib/client.store.js';
+export type { JourneyResult } from './lib/journey.utils.js';
 export type { ResolvedServerConfig } from './lib/wellknown.utils.js';
 export type { JourneyLoginSuccess } from './lib/login-success.utils.js';
 export type { JourneyLoginFailure } from './lib/login-failure.utils.js';