Parameter binding

Parameter decorators bind arguments by index, not by their declared TypeScript type. Explicit names survive minification and are the reliable choice for path/query/header fields.

Binding matrix

parameter(type: ParameterType, name = '') returns a legacy method-parameter decorator. ParameterMetadata stores type, optional name, and index; PARAMETER_METADATA_KEY is the Symbol used on the target/property.

Factory / ParameterType	Scalar argument	Object argument	Nullish behavior
`path(name = '')` / PATH	Bind named path field	Merge enumerable entries, ignoring provided name	Skip null/undefined
`query(name = '')` / QUERY	Bind named query field	Merge entries	Skip null/undefined
`header(name = '')` / HEADER	Set named header	Merge entries case-insensitively	Skip entire null/undefined argument; an undefined object value deletes a header
`body()` / BODY	Whole request body	Whole request body	Assigned as supplied before request merging
`request()` / REQUEST	Expect `ParameterRequest`	Merge into resolved request last	Falsy argument becomes empty request
`attribute(name = '')` / ATTRIBUTE	Named Map entry, skip undefined	Merge record/Map entries; null adds nothing	Null is ignored by record merge

Arguments are processed left-to-right; later bindings win. Body and request bindings are single selected values, so the last such parameter wins rather than merging multiple request arguments. Unannotated ordinary arguments are ignored.

ParameterRequest<BODY> extends FetchRequestInit<BODY> and PathCapable. Its path changes the endpoint path; use urlParams.path for replacement values. It can override method, headers, body, timeout, signal, and native Fetch fields, following mergeRequest, including its nullish fallback rules. An empty-string parameter path does not override a nonempty endpoint path.

The replacement method receives only the actual argument list; default parameter expressions in the original placeholder method do not execute. Pass defaults explicitly or configure urlParams metadata.

Names and reflection

getParameterNames(func): string[] parses Function.toString(), caches by function in a WeakMap, and returns an empty array on parsing failure; non-functions throw TypeError before parsing. It uses simple comma splitting and annotation/default stripping, so complex syntax or minification is not a stable naming contract.

getParameterName(target, propertyKey, index, providedName?) returns a truthy explicit name first, then an inferred name, otherwise undefined. Bound scalars without a resolved name fall back to param${index}. Missing path bindings can issue a diagnostic warning; the underlying URL resolver may subsequently throw for missing values, so do not rely on a warning as successful execution.

Cancellation and inherited metadata

An AbortSignal or AbortController argument is recognized before decorator metadata, even without a decorator. If multiple are supplied the last of each kind wins; a request parameter can override them. A signal bypasses the Fetcher timeout as described in cancellation.

Parameter metadata uses copy-on-write when inherited, so decorating an override does not mutate the parent's Map. Class binding walks inherited string-named methods. Symbol-named methods and static methods are not part of that binding traversal. Keep explicit parameter names on inherited/overridden endpoints too.

Complete example

import {
  api,
  post,
  path,
  query,
  body,
  request,
  autoGeneratedError,
  type ParameterRequest,
} from '@ahoo-wang/fetcher-decorator';

type User = { id: string; name: string };
@api('/users')
class Users {
  @post('/{id}')
  update(
    @path('id') id: string,
    @query('notify') notify: boolean,
    @body() value: { name: string },
    @request() options?: ParameterRequest,
    signal?: AbortSignal,
  ): Promise<User> {
    throw autoGeneratedError(id, notify, value, options, signal);
  }
}
const users = new Users();
async function updateUser() {
  const controller = new AbortController();
  return users.update(
    '1',
    true,
    { name: 'Ada' },
    { headers: { 'X-Trace-Id': 'demo' } },
    controller.signal,
  );
}
void updateUser;

Public symbols and source

Symbol	Implementation
`ParameterType`	parameterDecorator.ts:19
`ParameterMetadata`	parameterDecorator.ts:136
`PARAMETER_METADATA_KEY`	parameterDecorator.ts:161
`parameter`	parameterDecorator.ts:199
`path`	parameterDecorator.ts:265
`query`	parameterDecorator.ts:297
`header`	parameterDecorator.ts:329
`body`	parameterDecorator.ts:347
`ParameterRequest`	parameterDecorator.ts:359
`request`	parameterDecorator.ts:379
`attribute`	parameterDecorator.ts:415
`getParameterNames`	reflection.ts:46
`getParameterName`	reflection.ts:92

Package index

Parameter binding ​

Binding matrix ​

Names and reflection ​

Cancellation and inherited metadata ​

Complete example ​