index/functions/extractFieldWithFallbackPath.md

extractFieldWithFallbackPath<T>(obj, fieldPaths, defaultValue?): T | null

Extract field value from object using fallback path chain

Tries multiple field paths in order (both flat and nested) and returns the first one that has a non-empty value. Supports nested paths like "response.data.error" for deep object traversal.

Consolidates repeated response-handler field extraction and fallback logic.

Note: extractFieldWithCandidates() already exists in object-extractors.ts for simple field name candidates. This function extends that pattern to support nested paths (dot-notation) for deeper object traversal.

Type Parameters

Type Parameter	Default type	Description
T	unknown	Type of the default value (inferred from defaultValue parameter)

Parameters

Parameter	Type	Description
obj	unknown	Object to extract field from (can be any type, will check for object)
fieldPaths	string[]	Array of field paths to try in order (e.g., ['id', 'error.code', 'response.data.message'])
defaultValue?	T	Value to return if no field path has a value (default: null)

Returns

T | null

First non-empty value found, or defaultValue if none found

Examples

Basic field extraction

const obj = { id: '123', transactionId: null };

const id = extractFieldWithFallbackPath(obj, ['id', 'transactionId']);
// Returns: '123'

With nested paths

const response = {
  data: {
    error: {
      code: 'VALIDATION_ERROR'
    }
  }
};

const errorCode = extractFieldWithFallbackPath(
  response,
  ['error.code', 'code', 'message'],
  'UNKNOWN'
);
// Returns: 'VALIDATION_ERROR'

With default value

const obj = { name: null };

const name = extractFieldWithFallbackPath(
  obj,
  ['name', 'displayName', 'title'],
  'Unknown'
);
// Returns: 'Unknown' (all paths empty, uses default)

With type-safe default

const obj = { count: null };

const count: number = extractFieldWithFallbackPath(
  obj,
  ['count', 'total', 'size'],
  0
);
// Returns: 0 (type inferred from defaultValue)

Error case - non-object input

const value = extractFieldWithFallbackPath(null, ['field'], null);
// Returns: null (input is null, not an object)