module@warp-drive/core

Class RequestManager

Defined in: warp-drive-packages/core/src/request/-private/manager.ts:149

Import

import { RequestManager } from '@warp-drive/core';

For a complete usage guide see Making Requests, and Handlers for writing the handlers it runs.

How It Works

interface RequestManager {
  request<T>(req: RequestInfo): Future<T>;
}

A RequestManager provides a request/response flow in which configured handlers are successively given the opportunity to handle, modify, or pass-along a request.

For example:

Setup.ts

import { RequestManager, Fetch } from '@warp-drive/core';
import { AutoCompress } from '@warp-drive/utilities/handlers';
import { AuthHandler } from './auth-handler';

// ... create manager
const manager = new RequestManager()
   .use([AuthHandler, new AutoCompress(), Fetch]); 

auth-handler.ts

import type { Handler, NextFn } from '@warp-drive/core/request';
import type { RequestContext } from '@warp-drive/core/types/request';

const token = '<token>';

// adds a bearer token to every request, then passes it along
export const AuthHandler: Handler = {
  request<T>(context: RequestContext, next: NextFn<T>) {
    const headers = new Headers(context.request.headers);
    headers.append('Authorization', `Bearer ${token}`);

    return next(Object.assign({}, context.request, { headers }));
  },
};

Usage.ts

import Config from './config';

const { apiUrl } = Config;

// ... execute a request
const response = await manager.request({
  url: `${apiUrl}/users`
});

RequestManager vs Store.request

A bare RequestManager is the low-level primitive: it runs a request through the configured handler chain and settles with the raw StructuredDocument. It has no cache and does not hydrate ReactiveDocuments unless you register a cache handler yourself via RequestManager.useCache and the request opts in.

Store.request issues requests through this same RequestManager, but with the Store's cache handler and hydration already wired up — inserting the response into the Store's cache and resolving with a ReactiveDocument instead. Use store.request for anything the Store's cache should own, which is nearly all app code. Reach for requestManager.request directly only when there is no Store involved, or you specifically want the unprocessed StructuredDocument.

Futures

The return value of manager.request is a Future, which allows access to limited information about the request while it is still pending and fulfills with the final state when the request completes.

A Future is cancellable via abort.

Handlers may optionally expose a ReadableStream to the Future for streaming data; however, when doing so the future should not resolve until the response stream is fully read.

interface Future<T> extends Promise<StructuredDocument<T>> {
  abort(): void;

  async getStream(): ReadableStream | null;
}

StructuredDocuments

A Future resolves with a StructuredDataDocument or rejects with a StructuredErrorDocument.

interface StructuredDataDocument<T> {
  request: ImmutableRequestInfo;
  response: ImmutableResponseInfo;
  content: T;
}
interface StructuredErrorDocument extends Error {
  request: ImmutableRequestInfo;
  response: ImmutableResponseInfo;
  error: string | object;
}
type StructuredDocument<T> = StructuredDataDocument<T> | StructuredErrorDocument;

Constructors

Constructor

new RequestManager(options?: GenericCreateArgs): RequestManager;

Defined in: warp-drive-packages/core/src/request/-private/manager.ts:166

Parameters

options?

GenericCreateArgs

Returns

RequestManager

Methods

request()

request<RT>(request: RequestInfo<RT>): Future<RT>;

Defined in: warp-drive-packages/core/src/request/-private/manager.ts:258

Issue a Request.

Runs request through the configured handler chain and settles with the StructuredDocument the chain produces — a plain { request, response, content } object, not a ReactiveDocument. Caching and hydration only happen if a cache handler has been registered via RequestManager.useCache and the request opts in; a RequestManager created on its own has neither.

Most app code should use Store.request instead, which calls this same method with the Store's cache handler and hydration already configured. Reach for requestManager.request directly when there is no Store involved, or when you want the unprocessed StructuredDocument. The <RT> generic can be set explicitly or inferred from a request built with withResponseType or withReactiveResponse — see Typing Requests.

Type Parameters

RT

RT

Parameters

request

RequestInfo<RT>

Returns

Future<RT>

Example

const { content } = await requestManager.request({ url: '/users' });

---

use()

use(newHandlers: Handler[]): this;

Defined in: warp-drive-packages/core/src/request/-private/manager.ts:208

Register handler(s) to use when a request is issued.

Handlers will be invoked in the order they are registered. Each Handler is given the opportunity to handle the request, curry the request, or pass along a modified request.

Parameters

newHandlers

Handler[]

Returns

this

---

useCache()

useCache(cacheHandler: CacheHandler & {
  ___(unique) Symbol(IS_CACHE_HANDLER)?: true;
}): this;

Defined in: warp-drive-packages/core/src/request/-private/manager.ts:182

Register a handler to use for primary cache intercept.

Only one such handler may exist. If using the same RequestManager as the Store instance the Store registers itself as a Cache handler.

Parameters

cacheHandler

CacheHandler & { ___(unique) Symbol(IS_CACHE_HANDLER)?: true; }

Returns

this