Internals: Resource Fetching & Cascading

The useResourceFetcher hook manages asynchronous data for select and combobox fields, including complex cascading dependencies.

1. Global In-Memory Session Cache

To minimize network traffic, the fetcher implements a module-level in-memory cache (a single Map) that persists for the duration of the browser session.

• Key: The full URL including query parameters.
• Persistence: Cached items persist for the duration of the browser session (resets on full page reload).
• Speed: Subsequent renders or multiple fields using the same API resource result in O(1) lookups instead of repeated fetch calls.

2. Dependency Cascading (Province -> City)

The fetcher automatically handles the "Cascading Dropdown" pattern via the dependsOn and dependsOnParam properties.

The Reset Mechanism

When a parent field (dependsOn) changes, the child field must be reset to prevent invalid states.

// Internal logic in useResourceFetcher
useEffect(() => {
  if (!isFirstMount && parentValue !== prevValue) {
    // Clear current field value when parent changes
    setValue(fieldName, "");
  }
  fetchOptions(parentValue);
}, [parentValue]);

3. Intelligent Format Normalization

Different APIs return data in different shapes. DFBE includes a normalizer that automatically detects:

• Root Wrappers: items, data, or raw array.
• Label Keys: label, name, or text.
• Value Keys: value, id, or code.

This allows most standard REST APIs to "just work" without needing explicit labelKey mapping.

4. Error Handling & Retry

The fetcher provides a granular state for the UI:

• loading: Boolean state to show spinners.
• error: Error message if the fetch fails.
• retry: A function exposed to the adapter to manually trigger a refetch (e.g. via a "Try Again" button).

5. URL Resolution

The engine supports three types of endpoint URLs:

1. Absolute: https://api.example.com/cities
2. Absolute Path: /api/cities
3. Relative Path: ./cities or cities (resolved against window.location.origin).