normalize-args.ts

Overview

The normalize-args.ts file provides a utility function named normalize that standardizes the input arguments for a data fetching hook or function. This normalization process ensures that the arguments — which can vary in number and type — are transformed into a consistent tuple format with three elements: a key, a fetcher function (or null), and a partial configuration object.

This utility is typically used in libraries or modules that implement data fetching patterns, such as SWR (stale-while-revalidate), where the user can supply different combinations of parameters to customize fetching behavior. By normalizing the arguments, downstream code can operate on a predictable input structure, improving maintainability and simplifying internal logic.

Detailed Explanation

Imports

isFunction (from './shared'): A helper function to check if a given variable is a function.
Types imported from '../types':
- Key: Represents the type of the key used to identify the resource to fetch.
- Fetcher<Data>: Represents a function responsible for fetching data.
- SWRConfiguration: Configuration options for the data fetching behavior.

Function: `normalize`

export const normalize = <KeyType = Key, Data = any>(
  args:
    | [KeyType]
    | [KeyType, Fetcher<Data> | null]
    | [KeyType, SWRConfiguration | undefined]
    | [KeyType, Fetcher<Data> | null, SWRConfiguration | undefined]
): [KeyType, Fetcher<Data> | null, Partial<SWRConfiguration<Data>>]

Purpose

The normalize function processes a variable number and type of arguments related to data fetching, and returns a normalized tuple containing:

Key: The identifier of the resource.
Fetcher: The function that fetches the data or null if none is provided.
Configuration: A partial configuration object that customizes fetching behavior.

Parameters

args: A tuple that can be one of the following shapes:
- [KeyType]
  Only the key is provided.
- [KeyType, Fetcher<Data> | null]
  Key plus a fetcher function or explicit null (disables fetching).
- [KeyType, SWRConfiguration | undefined]
  Key plus configuration options, but no fetcher function.
- [KeyType, Fetcher<Data> | null, SWRConfiguration | undefined]
  Key, fetcher function or null, and configuration options.

Returns

A tuple: [KeyType, Fetcher<Data> | null, Partial<SWRConfiguration<Data>>]
- The key is returned as-is.
- The fetcher is either the provided function or null.
- The configuration is merged as a partial object; if not provided, an empty object {} is returned.

Implementation Details

The function uses a type guard to check if the second argument (args[1]) is a function:

If it is a function:
- The arguments are interpreted as [key, fetcher, config?].
- Returns [key, fetcher, config || {}].
If it is not a function:
- The arguments are interpreted as [key, configOrNull, configOrUndefined].
- If args[1] === null, fetcher is null, and config is args[2] or {}.
- Otherwise, fetcher is null, and config is args[1] or {}.

This logic covers all possible input shapes and ensures the output is consistently structured.

Usage Example

import { normalize } from './normalize-args'
import type { Fetcher, SWRConfiguration } from '../types'

const key = '/api/user'

// Case 1: Only key
const [key1, fetcher1, config1] = normalize([key])
// fetcher1 === null, config1 === {}

// Case 2: Key and fetcher
const fetcher: Fetcher<User> = url => fetch(url).then(res => res.json())
const [key2, fetcher2, config2] = normalize([key, fetcher])
// fetcher2 === fetcher, config2 === {}

// Case 3: Key and config
const config: SWRConfiguration = { refreshInterval: 5000 }
const [key3, fetcher3, config3] = normalize([key, config])
// fetcher3 === null, config3 === config

// Case 4: Key, fetcher, and config
const [key4, fetcher4, config4] = normalize([key, fetcher, config])
// fetcher4 === fetcher, config4 === config

Interaction with Other Parts of the System

This file depends on:
- isFunction from './shared' for type checking.
- Type definitions from '../types' for strong typing of keys, fetcher functions, and configuration.
It is typically used internally by hooks or utility functions in the data fetching layer of the application or library.
Helps unify and simplify argument handling in components or functions that support flexible parameter inputs, reducing boilerplate and improving code clarity.

Summary

Aspect	Description
File Purpose	Normalize variable input arguments into a standard tuple for data fetching operations.
Core Function	`normalize` — transforms input tuples into `[key, fetcher
Inputs Supported	Single key, key + fetcher, key + config, key + fetcher + config.
Outputs	Tuple with consistent structure for downstream processing.
Key Benefits	Simplifies argument parsing, improves type safety, and standardizes configuration handling.

Mermaid Flowchart Diagram

flowchart TD
    A[normalize(args)] --> B{Is args[1] a function?}
    B -- Yes --> C[Return [args[0], args[1], args[2] || {}]]
    B -- No --> D{Is args[1] === null?}
    D -- Yes --> E[Return [args[0], null, args[2] || {}]]
    D -- No --> F[Return [args[0], null, args[1] || {}]]

This documentation provides a complete understanding of the normalize-args.ts file, its purpose, usage, and how it fits within the larger data fetching architecture.