constructor

new PreparedAction

action

urlResolveOptions

options

PreparedAction

Endpoint

EndpointExecuteOptions

UrlResolveOptions

execute

init

Promise

Constructors

Properties

Methods

currentState

State

internalState

InternalState

responseIsSet

boolean

setCurrentState

__type

__call

setInternalState

first

void

firstState

getRequestInit

PaginatorRequestOptions

hasNextPage

nextState

previousState

replaceStateControllers

currentStatePair

internalStatePair

setResponse

response

CursorPaginator

InferredPaginator

LimitOffsetPaginator

PageNumberPaginator

Paginator

PaginatorInterface

null

Record

new Paginator

PaginatorInterface.currentState

PaginatorInterface.internalState

PaginatorInterface.setCurrentState

PaginatorInterface.setInternalState

True once setResponse has been called and pagination state is known.

__get

PaginatorInterface.responseIsSet

PaginatorInterface.first

PaginatorInterface.firstState

Does not transition state. To transition state call `first` instead.


PaginatorInterface.getRequestInit

Return the options to use with `Endpoint.execute` or `Endpoint.prepare`. Usually
this just involves setting `query` to the query string parameters for the paginator
but can also provide custom headers or different URL resolve arguments.

PaginatorInterface.hasNextPage

Returns true if there's more results after the current page

PaginatorInterface.next

PaginatorInterface.nextState

Does not transition state. To transition state call `next` instead.


PaginatorInterface.previous

PaginatorInterface.previousState

Does not transition state. To transition state call `previous` instead.


PaginatorInterface.replaceStateControllers

Paginator receives 2 tuples of a state and state setter pair. This is expected to
match the same interface as `useState` in React. The following is a valid simple usage:

```js
const paginator = new Paginator(useState(), useState());
```

Note that we can also pass the state controllers in via `replaceStateControllers` rather
than in the constructor. This is so we can memoize the `Paginator` instance which is desirable
when using the paginator as a dependency to React hooks.

As state is passed in and managed external to the class be aware that any data stored
on the class instance will be lost unless written with `setCurrentState` or `setInternalState`.
This design is a compromise between allowing a clear interface for how paginators should
be defined and allowing the state to be managed externally (eg. using React state).


PaginatorInterface.setResponse

This is called when an `Endpoint` has resolved and is passed the response from the
endpoint. This is used to update the relevant paginator state  - eg. the total
number of records, next & previous cursors etc.

Accessors

Variables

The state object and setter (eg. from `useState`) that is used to store
and transition pagination state. Using this you can do things like easily store state in the URL
(eg. using `useUrlQueryState`) or other data sources.

The state object and setter that is used for internal state. Internal state
is stored separately as it does not need to be restored (eg. if you refresh the page). It is used
to store things like the total number of results or the current cursor. Passing `useState` here is
fine.


The response as returned by the endpoint this paginator is used with.


Omit

RequestInit

headers

query

urlArgs

eg. the return value from [Endpoint.execute](doc:Endpoint#method-execute)

PaginationRequestDetails

The value returned by `decodedBody`. See [Endpoint.execute](doc:Endpoint#method-execute).

This may be a sub-key of the data returned by `Endpoint.execute`, eg. if the `path` option is used in
[paginationMiddleware](doc:paginationMiddleware). eg. If `decodedBody` from the `Endpoint` was

```json
{
    users: {
        count: 10,
        results: [...],
    }
    extraDetails: {...}
}
```

and `paginationMiddleware` was used with `path: 'users'` then `decodedBody` would be:

```json
{
    count: 10,
    results: [...]
}
```


decodedBody

Response

string

new UrlPattern

pattern

UrlPattern

keys

requiredArgNames

toPath

PathFunction

validArgNames

resolve

kwargs

__namedParameters

Allows definition of URL as a pattern with ability to resolve it to a URL by performing argument replacement

Patterns are defined using the [path-to-regexp](https://github.com/pillarjs/path-to-regexp) library

Usage:

```js
const url = new UrlPattern('/users/:id/'),
url.resolve({ id: 5 });
// /users/5/
url.resolve({ id: 5 }, { query: { showAddresses: true }});
// /users/5/?showAddresses=true
```


__index

Query

new SkipToResponse

promise

SkipToResponse

This can be passed to `next` in middleware to skip all subsequent middleware in the chain, the call
to `fetch` and resolve instead to the `promise` passed in.

This is useful for middleware like [dedupeInFlightRequestsMiddleware](doc:dedupeInFlightRequestsMiddleware) where
if a duplicate request is detected it just needs to wait for the original request to finish and return the
same Response object.

It can also be used to change how `fetch` is performed (`batchMiddleware` uses this).

For example this just calls a completely different URL and uses the response object from that:

```js
function customFetchMiddleware(next, urlConfig, requestInit, context) {
  return next(new SkipToResponse(
      return fetch('/somewhere-else/');
  ));
}
```

Note that this completely bypasses any subsequent middleware in the chain (including response handling) so any
security-related middleware should come before this.


Should not be instantiated manually. This is created by `Endpoint` as part of processing a request.

new MiddlewareContext

MiddlewareContext

_fetchStartCallbacks

The endpoint the middleware is executing within.

endpoint

Function to re-execute the Endpoint. Accepts no arguments - it replays the request with identical arguments
as the first time. This will go through the full middleware cycle again. This is useful for middleware
that may replay a request after an initial failure, eg. if user isn't authenticated on initial attempt.

The original options passed to [execute](doc:Endpoint#method-execute)

executeOptions

The state as of when the last middleware in the chain was processed.

This contains the `url`, `response`, `decodedBody` and `result`.


lastState

MiddlewareNextReturn

The options used to execute the endpoint with

requestInit

EndpointRequestInit

addFetchStartListener

Listen for the start of the call to `fetch`. The callback will be called immediately
after `fetch` is called and is passed the `Promise` returned by `fetch`.

This is useful for middleware like [dedupeInFlightRequestsMiddleware](doc:dedupeInFlightRequestsMiddleware)
that need access to the `fetch` `Promise` directly. It can then cache the promise and subsequently pass it to
[SkipToResponse](doc:SkipToResponse) to make other calls to an `Endpoint` use the same `fetch` `Response`.


callback

markResponseDecoded

You likely don't need this; use `decodeBody` on `Endpoint` instead. This is useful in cases
where you want to bypass the normal `Endpoint` `decodeBody` functionality (for example in
`batchMiddleware`).


notifyFetchStart

Called internally by `Endpoint` to notify when `fetch` has started.

fetchPromise

An instance of this is passed as the fourth parameter to middleware functions.

undefined

prepare

process

MiddlewareFunction

Object form of middleware. This allows more control over what the middleware can do. Specifically allows middleware
to define how it interacts with `Endpoint.prepare` and allows modifications to the `Endpoint` via `init`.

MiddlewareObject

new Endpoint

urlPattern

_baseUrl

decodeBody

middleware

Middleware

ReturnT

ExecuteInitOptions

resolveUrl

urlCache

The [UrlPattern](doc:UrlPattern) this endpoint hits when executed.

This defines the default settings to use on an endpoint globally.

All these options can be customised on individual Endpoints.


defaultConfig

DefaultConfig

The base URL to use for this endpoint. This is prepended to the URL returned from `urlPattern.resolve`.

If not specified then it defaults to [Endpoint.defaultConfig.baseUrl](doc:Endpoint#static-var-defaultConfig).

Note that middleware can override this as well.


baseUrl

This can be called directly or indirectly via `prepare`.

If the fetch call itself fails due to a network error then a `TypeError` will be thrown.

If the fetch call is aborted due to a call to [AbortController.abort](https://developer.mozilla.org/en-US/docs/Web/API/AbortController/abort)
an `AbortError` is thrown.

If the response is a non-2XX response an `ApiError` will be thrown.

If the call is successful the body will be decoded using `decodeBody`. The default implementation
will decode JSON to an object or return text based on the content type. If the content type is
not JSON or text the raw `Response` will be returned.

```js
// Via prepare
const preparedAction = action.prepare({ urlArgs: { id: '1' }});
preparedAction.execute();

// Directly
action.execute({ urlArgs: { id: '1' }});
```


fetch

Calls [fetch](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API)

You can extend `Endpoint` and override this if you need to customise something that isn't
possible with middleware.


Prepare an action for execution. Given the same parameters returns the same object. This is useful
when using libraries like `useSWR` that accept a parameter that identifies a request and is used
for caching but execution is handled by a separate function.

For example to use with `useSWR` you can do:

```js
const { data } = useSWR([action.prepare()], (preparedAction) => preparedAction.execute());
```

If you just want to call the action directly then you can bypass `prepare` and just call `execute`
directly.


Describe an REST API endpoint that can then be executed.

* Accepts a [UrlPattern](doc:UrlPattern) to define the URL used. Any arguments & query parameters can be passed at execution time
* Accepts a `decodeBody` function that decodes the `Response` body as returned from [fetch](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API). The
  default `decodeBody` will interpret the response based on the content type
  * If type includes 'json' (eg. application/json) returns decoded json
  * If type includes 'text (eg. text/plain, text/html) returns text
  * If status is 204 or 205 will return null
* [middleware](#Middleware) can be passed to transform the request before it is passed to `fetch` and/or the response after
  it has passed through `decodeBody`.
* All options accepted by `fetch` and these will be used as defaults to any call to `execute` or `prepare`.

Usage:

```js
const userList = new Action(new UrlPattern('/api/users/'));
const users = await userList.execute();
```

You can pass `urlArgs` and `query` to resolve the URL:

```js
const userDetail = new Action(new UrlPattern('/api/user/:id/'));
// Resolves to /api/user/1/?showAddresses=true
const user = await userDetail.execute({ urlArgs: { id: 1 }, query: 'showAddresses': true });
```

You can also pass through any `fetch` options to both the constructor and calls to `execute` and `prepare`

```js
// Always pass through Content-Type header to all calls to userDetail
const userDetail = new Action(new UrlPattern('/api/user/:id/'), {
    'Content-Type': 'application/json'
});
// Set other fetch options at execution time
userDetail.execute({ urlArgs: { id: 1 }, method: 'PATCH', body: JSON.stringify({ name: 'Dave' }) });
```

Often you have some global options you want to apply everywhere. This can be set on `Endpoint`
directly:

```js
// Set default options to pass through to the request init option of `fetch`
Endpoint.defaultConfig.requestInit = {
  headers: {
    'X-CSRFToken': getCsrfToken(),
  },
};

// All actions will now use the default headers specified
userDetail.execute({ urlArgs: { id: 1 } });
```

You can also "prepare" an action for execution by calling the `prepare` method. Each call to prepare will
return the same object (ie. it passes strict equality checks) given the same parameters. This is useful when
you need to have a stable cache key for an action. For example you may have a React hook that executes
your action when things change:

```js
import useSWR from 'swr';

...

// prepare the action and pass it to useSWR. useSWR will then call the second parameter (the "fetcher")
// which executes the prepared action.
const { data } = useSWR([action.prepare()], (preparedAction) => preparedAction.execute());
```

You can wrap this up in a custom hook to make usage more ergonomic:

```js
import { useCallback } from 'react';
import useSWR from 'swr';

// Wrapper around useSWR for use with `Endpoint`
// @param action Endpoint to execute. Can be null if not yet ready to execute
// @param args Any args to pass through to `prepare`
// @return Object Same values as returned by useSWR with the addition of `execute` which
// can be used to execute the action directly, optionally with new arguments.
export default function useEndpoint(action, args) {
  const preparedAction = action ? action.prepare(args) : null;
  const execute = useCallback(init => preparedAction.execute(init), [preparedAction]);
  return {
    execute,
    ...useSWR(preparedAction && [preparedAction], act => act.execute()),
  };
}
```

## Pagination

Pagination for an endpoint is handled by [paginationMiddleware](doc:paginationMiddleware). This middleware
will add a `getPaginatorClass` method to the `Endpoint` which makes it compatible with [usePaginator](doc:usePaginator).
The default implementation chooses a paginator based on the shape of the response (eg. if the response looks like
cursor based paginator it will use `CursorPaginator`, if page number based `PageNumberPaginator` or if limit/offset
use `LimitOffsetPaginator` - see [InferredPaginator](doc:InferredPaginator). The pagination state as returned by the
backend is stored on the instance of the paginator:

```js
const paginator = usePaginator(endpoint);
// This returns the page of results
const results = await endpoint.execute({ paginator });
// This now has the total number of records (eg. if the paginator was PageNumberPaginator)
paginator.total
```

You can calculate the next request state by mutating the paginator:

```js
paginator.next()
// The call to endpoint here will include the modified page request data, eg. ?page=2
const results = await endpoint.execute({ paginator });
```

See [usePaginator](doc:usePaginator) for more details about how to use a paginator in React.

If your backend returns data in a different shape or uses headers instead of putting details in the response body
you can handle this by a) implementing your own paginator that extends one of the base classes and customising
the `getPaginationState` function or b) passing the `getPaginationState` method to [usePaginator](doc:usePaginator).
This function can return the data in the shape expected by the paginator.

## Middleware

Middleware functions can be provided to alter the `url` or fetch options and transform the
response in some way.

Middleware can be defined as either an object or as a function that is passed the url, the fetch options, the next
middleware function and a context object. The function can then make changes to the `url` or `requestInit` and pass
it through to the next middleware function. The call to `next` returns a `Promise` that resolves to the response of
the endpoint after it's been processed by any middleware further down the chain. You can return a modified response here.

This middleware sets a custom header on a request but does nothing with the response:

```js
function clientHeaderMiddleware(next, urlConfig, requestInit, context) {
  requestInit.headers.set('X-ClientId', 'ABC123');
  // Return response unmodified
  return next(url.toUpperCase(), requestInit)
}
```

This middleware just transforms the response - converting it to uppercase.

```js
function upperCaseResponseMiddleware(next, urlConfig, requestInit, context) {
  const { result } = await next(url.toUpperCase(), requestInit)
  return result.toUpperCase();
}
```

Note that `next` will return an object containing `url`, `response`, `decodedBody` and `result`.
As a convenience you can return this object directly when you do not need to modify the result
in any way (the first example above). `result` contains the value returned from any middleware
that handled the response before this one or otherwise `decodedBody` for the first middleware.

The [context object](doc:MiddlewareContext) can be used to retrieve the original options from the [Endpoint.execute](doc:Endpoint#method-execute)
call and re-execute the command. This is useful for middleware that may replay a request after an initial failure,
eg. if user isn't authenticated on initial attempt.

```js
// Access the original parameters passed to execute
context.executeOptions
// Re-execute the endpoint.
context.execute()
```

**NOTE:** Calling `context.execute()` will go through all the middleware again

Middleware can be set globally for all [Endpoint](doc:Endpoint)'s on the [Endpoint.defaultConfig.middleware](doc:Endpoint#static-var-defaultConfig)
option or individually for each Endpoint by passing the `middleware` as an option when creating the endpoint.

Set globally:

```js
Endpoint.defaultConfig.middleware = [
   dedupeInflightRequestsMiddleware,
];
```

Or customise it per Endpoint:

```js
new Endpoint('/users/', { middleware: [csrfTokenMiddleware] })
```

When middleware is passed to the `Endpoint` it is _appended_ to the default
middleware specified in `Endpoint.defaultConfig.middleware`.

To change how middleware is combined per `Endpoint` you can specify the
`getMiddleware` option. This is passed the middleware for the `Endpoint` and
the `Endpoint` itself and should return an array of middleware to use.

The default implementation looks like

```js
(middleware) => [
  ...Endpoint.defaultConfig.middleware,
  ...middleware,
]
```

You can change the default implementation on [Endpoint.defaultConfig.getMiddleware](doc:Endpoint#static-var-defaultConfig)

Middleware can also be defined as an object with any of the following properties:

* `init` - Called when the `Endpoint` is initialised and allows the middleware to modify the endpoint
  class or otherwise do some kind of initialisation.
* `prepare` - A function that is called in `Endpoint.prepare` to modify the options used. Specifically this allows middleware
  to apply its changes to the options used (eg. change URL etc) such that `Endpoint` correctly caches the call.
* `process` - Process the middleware. This behaves the same as the function form described above.

### Advanced

For advanced use cases there's some additional hooks available.

* [addFetchStartListener](doc:MiddlewareContext#method-addFetchStartListener) - This allows middleware to be notified
  when the call to `fetch` starts and get access to the `Promise`. [dedupeInFlightRequestsMiddleware](doc:dedupeInFlightRequestsMiddleware)
  uses this to cache an in flight request and return the same response for duplicate calls using [SkipToResponse](doc:SkipToResponse)
* [SkipToResponse](doc:SkipToResponse) - This allows middleware to skip the rest of the middleware chain and the call
  to `fetch`. Instead it is passed a promise that resolves to `Response` and this is used instead of doing the call
  to `fetch` for you.


paginator

Same as [fetch](https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/fetch#Parameters) but
guarantees `headers` is set and is a `Headers` instance, and `method` is set.

method

Any options accepted by [fetch](https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/fetch#Parameters) in addition to those described below

EndpointOptions

getMiddleware

ExecuteReturnVal

The value returned from the endpoint after it has passed through `decodeBody` and any middleware

result

The url that the endpoint was called with

Any arguments that were used to resolve the URL.

Only available in the response part of the middleware.


The final value to return from middleware. This starts as `decodedBody` but can be modified
by middleware as it passes through them.

MiddlewareReturn

MiddlewareUrlConfig

args

urlConfig

context

MiddlewareNextFunction

skipToResponse

Base to use for all urls. This can be used to change all URL's to be on a different origin.

This can also be customised by middleware by changing `urlConfig.baseUrl` (defaults to this setting) or
in each `Endpoint` by passing `baseUrl` in options.


Get the final middleware to apply to the specified endpoint. By default applies the global middleware followed
by the endpoint specific middleware.

Default middleware to use on an endpoint. It is strongly recommended to append to this rather than replace it.

Defaults to [requestDefaultsMiddleware](doc:requestDefaultsMiddleware).

See [middleware](#Middleware) for more details


PreparedAction

API

Constructor

new PreparedAction(action,urlResolveOptions,options)

Methods

execute(init)

Properties

action: Endpoint

options:
EndpointExecuteOptions

urlResolveOptions: UrlResolveOptions

Key	Type	Description
headers	HeadersInit\|Record	Any headers to add to the request. You can unset default headers that might be specified in the default `Endpoint.defaultConfig.requestInit` by setting the value to `undefined`.
paginator	PaginatorInterface\|null	The paginator instance to use. This can be provided in the constructor to use by default for all executions of this endpoint or provided for each call to the endpoint. Only applicable if paginationMiddleware has been added to the Endpoint.
query	Query
urlArgs	Record

API

Constructor

new PreparedAction(action,urlResolveOptions,options)

Methods

execute(init)

Properties

action: Endpoint

options: EndpointExecuteOptions

urlResolveOptions: UrlResolveOptions

options:
EndpointExecuteOptions