Vamos mergulhar no recurso menos frequente do Typescript - sobrecarga de funções com um exemplo realista.

Introdução

Tenha um gancho personalizado

export function useUrlState(
  defaultState: T,
  searchParams?: object,
)

Em algum momento preciso adicionar mais argumentos, possivelmente mais no futuro. É difícil lembrar o que é o enésimo argumento, e chamar uma função como useUrlState(firstArg, null, null, fourArg) é ridículo. Será muito mais fácil passar argumentos dentro de um objeto como este:

export function useUrlState({
  defaultState,
  searchParams,
  replace
}: { defaultState: T, searchParams?: object, replace?: boolean })

Converterei a função para um novo formato e a manterei compatível com versões anteriores da implementação existente.

Implementação

Primeiro, é necessário adicionar assinaturas de sobrecarga logo acima da função implementação. Assinaturas de sobrecarga são todas as maneiras possíveis de chamar uma função, com diferentes tipos e quantidades de argumentos.

/**
 * @deprecated Pass arguments in a object `useUrlState({ defaultState: form, searchParams })`
 *
 *  * Github {@link https://github.com/asmyshlyaev177/state-in-url/tree/main/packages/urlstate/next/useUrlState#api}
 */
export function useUrlState(defaultState: T, searchParams?: object): {
  state: DeepReadonly,
  updateState: (value: Partial>,
  updateUrl: (value?: Partial>) => void,
  getState: () => DeepReadonly
}
/**
 * NextJS hook. Returns `state`, `updateState`, and `updateUrl` functions
 *
 * @param {JSONCompatible} [defaultState] Fallback (default) values for state
 * @param {?SearchParams} [searchParams] searchParams from Next server component
 */
export function useUrlState({ defaultState, searchParams }: {
  defaultState: T, searchParams?: object, replace?: boolean
}): {
  state: DeepReadonly,
  updateState: (value: Partial>) => void,
  updateUrl: (value?: Partial>) => void,
  getState: () => DeepReadonly
} // (
  defaultState: T | { defaultState: T, searchParams?: object, replace?: boolean },
  searchParams?: object,
) {

A parte complicada é que as assinaturas devem ser compatíveis com a implementação, então tenha este defaultState: T | { defaultState: T, searchParams?: objeto, substituir?: booleano }

Presumo que se o primeiro argumento tiver uma chave específica, é um novo formato de objeto.

  const _defaultState = ('defaultState' in defaultState ? defaultState.defaultState : defaultState) as T
  const _searchParams = ('defaultState' in defaultState ? defaultState.searchParams : searchParams) as object | undefined
  const _replace = ('defaultState' in defaultState ? defaultState.replace ?? true : false) as boolean

Além disso, pode-se notar que o argumento de substituição tem o valor padrão verdadeiro para um novo formato, mas para o antigo é falso.

Vamos ver como funciona.

Observe que temos comentários JSDoc diferentes para cada assinatura, o antigo marcado com a tag @deprecated.

Documentos oficiais https://www.typescriptlang.org/docs/handbook/2/functions.html#function-overloads

Tnx pela leitura :)

Deixe um comentário sobre sua experiência, ou se você tem ideias de como fazer isso com mais elegância.