@bbc/http-transport - npm Package Compare versions

Comparing version 3.5.4 to 3.5.5

index.d.ts

 import * as request from "request";
 
-export declare function createBuilder(transport?: Transport): HttpTransportBuilder;
+export declare function createBuilder(
+  transport?: Transport
+): HttpTransportBuilder;
 export declare function createClient(): HttpTransportClient;
 
-declare type callbackFunction<T> = (err: any, value?: T) => void
-export declare type Plugin = (ctx: Context, next: Plugin) => any;
+declare type callbackFunction<T> = (err: any, value?: T) => void;
+export declare type Plugin<
+  ContextExtra = {},
+  ContextCurrent extends Context = Context
+> = (
+  ctx: ContextCurrent & ContextExtra,
+  next: () => void | Promise<void>
+) => any;
 export declare type Header = Object;
@@ -13,28 +21,28 @@ export declare type Querystring = Object;
 export declare type ErrorObject = {
-  message: string
-}
+  message: string;
+};
 
 export declare type JsonResponse = {
-  body: string
-  elapsedTime: number
-  url: string
-  headers: Object
-  statusCode: number
-}
+  body: string;
+  elapsedTime: number;
+  url: string;
+  headers: Object;
+  statusCode: number;
+};
 
 declare type RetryAttempt = {
-  reason: string,
-  statusCode: number
-}
+  reason: string;
+  statusCode: number;
+};
 
 declare type contextDefaults = {
-  userAgent?: string
-  retries?: number
-  retryDelay?: number
-}
+  userAgent?: string;
+  retries?: number;
+  retryDelay?: number;
+};
 
 declare type ToJsonOpts = {
-  throwOnConflict?: boolean,
-  force?: boolean
-}
+  throwOnConflict?: boolean;
+  force?: boolean;
+};
 
@@ -51,91 +59,120 @@ declare enum Method {
 
-export declare function toJson(opts: ToJsonOpts): Plugin
-export declare function logger(logger?: any): Plugin
-export declare function setContextProperty(opts: any, path: string): Plugin
+export declare function toJson(opts: ToJsonOpts): Plugin;
+export declare function logger(logger?: any): Plugin;
+export declare function setContextProperty(opts: any, path: string): Plugin;
 
 export declare class Request {
-  addQuery(key: string, value: string): Request
-  addHeader(key: string, value: string): Request
-  body(content: string): Request
-  method(method: Method): Request
-  baseUrl(baseUrl: string): Request
-  timeout(timeout: number): Request
-  getMethod(): Method
-  getTimeout(): number
-  getUrl(): string
-  getRequestKey(): string
-  getHeaders(): Object
-  getQueries(): Object
-  hasQueries(): boolean
-  hasBaseQueries(): boolean
-  hasHeaders(): boolean
-  getBody(): string
-  create(): Request
+  addQuery(key: string, value: string): Request;
+  addHeader(key: string, value: string): Request;
+  body(content: string): Request;
+  method(method: Method): Request;
+  baseUrl(baseUrl: string): Request;
+  timeout(timeout: number): Request;
+  getMethod(): Method;
+  getTimeout(): number;
+  getUrl(): string;
+  getRequestKey(): string;
+  getHeaders(): Object;
+  getQueries(): Object;
+  hasQueries(): boolean;
+  hasBaseQueries(): boolean;
+  hasHeaders(): boolean;
+  getBody(): string;
+  create(): Request;
 }
 
 export declare class Response {
-  headers: Header[]
-  elapsedTime: number
-  url: string
-  statusCode: number
-  body: Body
-  httpResponse?: request.Response
-  readonly length: number
-  static create(opts?: JsonResponse): Response
-  addHeader(key: string, value: string): Request
-  getHeader(key: string): string
-  toJson(): JsonResponse
+  headers: Header[];
+  elapsedTime: number;
+  url: string;
+  statusCode: number;
+  body: Body;
+  httpResponse?: request.Response;
+  readonly length: number;
+  static create(opts?: JsonResponse): Response;
+  addHeader(key: string, value: string): Request;
+  getHeader(key: string): string;
+  toJson(): JsonResponse;
 }
 
-export declare class HttpTransportBuilder {
-  userAgent(userAgent: string): HttpTransportBuilder
-  retries(retries: number): HttpTransportBuilder
-  retryDelay(retryDelay: number): HttpTransportBuilder
-  use(fn: Plugin): HttpTransportBuilder
-  asCallback(): HttpTransportBuilder
-  createClient(): HttpTransportClient
+export declare class HttpTransportBuilder<
+  ContextCurrent extends Context = Context
+> {
+  userAgent(userAgent: string): HttpTransportBuilder<ContextCurrent>;
+  retries(retries: number): HttpTransportBuilder<ContextCurrent>;
+  retryDelay(retryDelay: number): HttpTransportBuilder<ContextCurrent>;
+  use<ContextExtra = {}>(
+    fn: Plugin<ContextExtra, ContextCurrent>
+  ): HttpTransportBuilder<ContextExtra & ContextCurrent>;
+  asCallback(): HttpTransportBuilder<ContextCurrent>;
+  createClient(): HttpTransportClient<ContextCurrent>;
 }
 
-export declare class HttpTransportClient {
-  use(fn: Plugin): HttpTransportClient
-  get(baseUrl: string): HttpTransportClient
-  post(baseUrl: string, body: string | object): HttpTransportClient
-  patch(baseUrl: string, body: string | object): HttpTransportClient
-  put(baseUrl: string, body: string | object): HttpTransportClient
-  delete(baseUrl: string): HttpTransportClient
-  head(baseUrl: string): HttpTransportClient
-  headers(headers: Header): HttpTransportClient
-  query(query: Querystring): HttpTransportClient
-  timeout(timeout: number): HttpTransportClient
-  retries(retries: number): HttpTransportClient
-  retryDelay(retryDelay: number): HttpTransportClient
-  asBody(): Promise<Body>
-  asResponse(): Promise<Response>
+export declare class HttpTransportClient<
+  ContextCurrent extends Context = Context
+> {
+  use<ContextExtra = {}>(
+    fn: Plugin<ContextExtra & ContextCurrent>
+  ): HttpTransportClient<ContextExtra & ContextCurrent>;
+  get(baseUrl: string): HttpTransportClient<ContextCurrent>;
+  post(
+    baseUrl: string,
+    body: string | object
+  ): HttpTransportClient<ContextCurrent>;
+  patch(
+    baseUrl: string,
+    body: string | object
+  ): HttpTransportClient<ContextCurrent>;
+  put(
+    baseUrl: string,
+    body: string | object
+  ): HttpTransportClient<ContextCurrent>;
+  delete(baseUrl: string): HttpTransportClient<ContextCurrent>;
+  head(baseUrl: string): HttpTransportClient<ContextCurrent>;
+  headers(headers: Header): HttpTransportClient<ContextCurrent>;
+  query(query: Querystring): HttpTransportClient<ContextCurrent>;
+  timeout(timeout: number): HttpTransportClient<ContextCurrent>;
+  retries(retries: number): HttpTransportClient<ContextCurrent>;
+  retryDelay(retryDelay: number): HttpTransportClient<ContextCurrent>;
+  asBody(): Promise<ContextCurrent["res"]["body"]>;
+  asResponse(): Promise<ContextCurrent["res"]>;
 }
 
 declare class Context {
-  plugins: Plugin[]
-  req: Request
-  res: Response
+  plugins: Plugin[];
+  req: Request;
+  res: Response;
 
-  static create(defaults: contextDefaults): any
-  retryAttempts: Array<RetryAttempt>
-  addPlugin(plugin: Plugin): Context
+  static create(defaults: contextDefaults): any;
+  retryAttempts: Array<RetryAttempt>;
+  addPlugin(plugin: Plugin): Context;
 }
 
 export declare class defaultTransport extends RequestTransport {
-  constructor(params: request.RequestAPI<request.Request, request.CoreOptions, request.RequiredUriUrl>)
+  constructor(
+    params: request.RequestAPI<
+      request.Request,
+      request.CoreOptions,
+      request.RequiredUriUrl
+    >
+  );
 }
 export declare class RequestTransport extends Transport {
-  constructor(params: request.RequestAPI<request.Request, request.CoreOptions, request.RequiredUriUrl>)
+  constructor(
+    params: request.RequestAPI<
+      request.Request,
+      request.CoreOptions,
+      request.RequiredUriUrl
+    >
+  );
 }
 
 export declare class Transport {
-  toError(err: ErrorObject, ctx: Context): Error
-  createError(err: ErrorObject, ctx: Context): Error
-  execute(ctx: Context): Promise<RequestTransport>
-  onError(ctx: Context): Function
-  toOptions(ctx: Context): RequestOptions
-  toResponse(ctx: Context, from: request.Response): Response
-  makeRequest(ctx: Context, opts: RequestOptions): Promise<Response>
+  toError(err: ErrorObject, ctx: Context): Error;
+  createError(err: ErrorObject, ctx: Context): Error;
+  execute(ctx: Context): Promise<RequestTransport>;
+  onError(ctx: Context): Function;
+  toOptions(ctx: Context): RequestOptions;
+  toResponse(ctx: Context, from: request.Response): Response;
+  makeRequest(ctx: Context, opts: RequestOptions): Promise<Response>;
 }
@@ -142,0 +179,0 @@

package.json

 {
   "name": "@bbc/http-transport",
-  "version": "3.5.4",
+  "version": "3.5.5",
   "description": "A flexible, modular REST client built for ease-of-use and resilience.",
@@ -5,0 +5,0 @@ "main": "index.js",

README.md

@@ -38,2 +38,37 @@
 
+## TypeScript
+Types are included in this project, and they also work with plugins.
+
+Just pass the types that your plugin will add to `context` as a generic. This will be overlayed on top of any types added by previous plugins in the chain.
+
+E.g.
+
+```ts
+const addSessionData: Plugin<{ session: { userId: string } } }> = (context, next) => {
+  context.session = { userId: 'some-user' };
+};
+
+const res = await client
+  .use(addSessionData)
+  .use((context, next) => {
+    if (context.session.userId === 'some-user') { // this would error if addSessionData middleware was missing
+      // do something
+    }
+  })
+  .use<{res: { random: number } }>((context, next) => {
+    context.res.random = Math.random();
+  })
+  .get(url)
+  .asResponse();
+
+console.log(res.random); // number
+```
+
+## Opting Out
+If you don't want to type your plugin, simply use `any` as the type. This is not recomemnded though as it means all plugins later in the chain will loose the types too, because they have no idea what changes were made.
+
+```ts
+const myPlugin: Plugin<any> = (context, next) => {};
+```
+
 ## Test
@@ -40,0 +75,0 @@

No alert changes

Improved metrics

Total package byte prevSize

389395

increased by0.5%

Lines of code

7007

increased by0.53%

Number of lines in readme file

84

increased by71.43%

No dependency changes