@api-ts/typed-express-router - npm Package Compare versions

Comparing version 1.1.9 to 1.1.10

dist/src/index.d.ts

@@ -5,4 +5,19 @@ import { ApiSpec } from '@api-ts/io-ts-http';
 export type { AfterEncodedResponseSentFn, OnDecodeErrorFn, OnEncodeErrorFn, TypedRequestHandler, UncheckedRequestHandler, WrappedRouter, WrappedRouteOptions, WrappedRouterOptions, WrappedRequest, WrappedResponse, } from './types';
+/**
+ * Creates a new Express router and wraps it with the specified api-ts spec
+ *
+ * @param spec {ApiSpec} the api-ts spec to associate with the router
+ * @param options {WrappedRouterOptions} Express router options as well as default error handlers and hooks to use for routes
+ * @returns {WrappedRouter} the wrapped Express router
+ */
 export declare function createRouter<Spec extends ApiSpec>(spec: Spec, { onDecodeError, onEncodeError, afterEncodedResponseSent, ...options }?: WrappedRouterOptions): WrappedRouter<Spec>;
+/**
+ * Wraps an existing Express router
+ *
+ * @param router {express.Router} the Express router to wrap
+ * @param spec {ApiSpec} the api-ts spec to associate with the router
+ * @param options {WrappedRouteOptions} default error handlers and hooks to use for routes
+ * @returns {WrappedRouter} the wrapped Express router
+ */
 export declare function wrapRouter<Spec extends ApiSpec>(router: express.Router, spec: Spec, { onDecodeError, onEncodeError, afterEncodedResponseSent, }: WrappedRouteOptions): WrappedRouter<Spec>;
 //# sourceMappingURL=index.d.ts.map

dist/src/index.js

 "use strict";
+/*
+ * @api-ts/typed-express-router
+ */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
@@ -36,2 +39,9 @@ if (k2 === undefined) k2 = k;
 const path_1 = require("./path");
+/**
+ * Creates a new Express router and wraps it with the specified api-ts spec
+ *
+ * @param spec {ApiSpec} the api-ts spec to associate with the router
+ * @param options {WrappedRouterOptions} Express router options as well as default error handlers and hooks to use for routes
+ * @returns {WrappedRouter} the wrapped Express router
+ */
 function createRouter(spec, { onDecodeError, onEncodeError, afterEncodedResponseSent, ...options } = {}) {
@@ -46,2 +56,10 @@ const router = express_1.default.Router(options);
 exports.createRouter = createRouter;
+/**
+ * Wraps an existing Express router
+ *
+ * @param router {express.Router} the Express router to wrap
+ * @param spec {ApiSpec} the api-ts spec to associate with the router
+ * @param options {WrappedRouteOptions} default error handlers and hooks to use for routes
+ * @returns {WrappedRouter} the wrapped Express router
+ */
 function wrapRouter(router, spec, { onDecodeError = errors_1.defaultOnDecodeError, onEncodeError = errors_1.defaultOnEncodeError, afterEncodedResponseSent = () => { }, }) {
@@ -54,5 +72,10 @@ const routerMiddleware = [];
             if (route === undefined) {
+                // Should only happen with an explicit undefined property, which we can only prevent at the
+                // type level with the `exactOptionalPropertyTypes` tsconfig option
                 throw Error(`Method "${method}" at "${apiName}" must not be "undefined"'`);
             }
             const wrapReqAndRes = (req, res, next) => {
+                // Intentionally passing explicit arguments here instead of decoding
+                // req by itself because of issues that arise while using Node 16
+                // See https://github.com/BitGo/api-ts/pull/394 for more information.
                 const decoded = route.request.decode({
@@ -59,0 +82,0 @@ body: req.body,

dist/src/path.js

 "use strict";
+// Converts an io-ts-http path to an express one
+// assumes that only simple path parameters are present and the wildcard features in express
+// arent used.
 Object.defineProperty(exports, "__esModule", { value: true });
@@ -3,0 +6,0 @@ exports.apiTsPathToExpress = void 0;

dist/src/types.d.ts

@@ -30,4 +30,25 @@ import { ApiSpec, HttpRoute, Method as HttpMethod } from '@api-ts/io-ts-http';
 }[keyof Spec & string];
+/**
+ * Defines a route from one listed in an `apiSpec`. The request object will contain
+ * a `decoded` request property, and the response object will have a type-checked
+ * `sendEncoded` function with the correct types.
+ *
+ * @param apiName {string} the api name defined in the `apiSpec` assoiated with this router
+ * @param handlers {TypedRequestHandler[]} a series of Express request handlers with extra properties
+ * @param options {WrappedRouteOptions} error and response hooks for this route that override the top-level ones if provided
+ */
 export declare type AddRouteHandler<Spec extends ApiSpec, Method extends Methods> = <ApiName extends ApiNamesWithMethod<Spec, Method>>(apiName: ApiName, handlers: TypedRequestHandler<Spec, ApiName, Method>[], options?: WrappedRouteOptions) => void;
+/**
+ * Defines a route from one listed in an `apiSpec`. The request object will contain
+ * a `decoded` request property, and the response object will have a type-checked
+ * `sendEncoded` function with the correct types.
+ *
+ * @param apiName {string} the api name defined in the `apiSpec` assoiated with this router
+ * @param handlers {TypedRequestHandler[]} a series of Express request handlers with extra properties
+ * @param options {UncheckedWrappedRouteOptions} error and response hooks for this route that override the top-level ones if provided
+ */
 export declare type AddUncheckedRouteHandler<Spec extends ApiSpec, Method extends Methods> = <ApiName extends ApiNamesWithMethod<Spec, Method>>(apiName: ApiName, handlers: UncheckedRequestHandler<Spec, ApiName, Method>[], options?: UncheckedWrappedRouteOptions) => void;
+/**
+ * An Express router that is wrapped and associated with an api-ts `apiSpec`.
+ */
 export declare type WrappedRouter<Spec extends ApiSpec> = Omit<express.Router, 'get' | 'post' | 'put' | 'delete' | 'use' | 'patch'> & express.RequestHandler & {
@@ -40,6 +61,81 @@ use: (middleware: UncheckedRequestHandler<ApiSpec, string, HttpMethod>) => void;
     patch: AddRouteHandler<Spec, 'patch'>;
+    /**
+     * This function will create a GET route without validating the request, or encoding the response body.
+     * However, it will still try decode the request and set `req.decoded: Either<DecodedRequest, Error>`. To see the
+     * result of this operation, you can check `req.decoded` in your route handler like this:
+     *
+     * ```typescript
+     * import * as E from 'fp-ts/Either';
+     *
+     * if (E.isLeft(req.decoded)) {
+     *    // input validation failed
+     * } else {
+     *    // input validation succeeded
+     * }
+     * ```
+     */
     getUnchecked: AddUncheckedRouteHandler<Spec, 'get'>;
+    /**
+     * This function will create a POST route without validating the request body, or encoding the response body.
+     * However, it will still try decode the request and set `req.decoded: Either<DecodedRequest, Error>`. To see the
+     * result of this operation, you can check `req.decoded` in your route handler like this:
+     *
+     * ```typescript
+     * import * as E from 'fp-ts/Either';
+     *
+     * if (E.isLeft(req.decoded)) {
+     *    // input validation failed
+     * } else {
+     *    // input validation succeeded
+     * }
+     * ```
+     */
     postUnchecked: AddUncheckedRouteHandler<Spec, 'post'>;
+    /**
+     * This function will create a PUT route without validating the request, or encoding the response body.
+     * However, it will still try decode the request and set `req.decoded: Either<DecodedRequest, Error>`. To see the
+     * result of this operation, you can check `req.decoded` in your route handler like this:
+     *
+     * ```typescript
+     * import * as E from 'fp-ts/Either';
+     *
+     * if (E.isLeft(req.decoded)) {
+     *    // input validation failed
+     * } else {
+     *    // input validation succeeded
+     * }
+     * ```
+     */
     putUnchecked: AddUncheckedRouteHandler<Spec, 'put'>;
+    /**
+     * This function will create a DELETE route without validating the request, or encoding the response body.
+     * However, it will still try decode the request and set `req.decoded: Either<DecodedRequest, Error>`. To see the
+     * result of this operation, you can check `req.decoded` in your route handler like this:
+     *
+     * ```typescript
+     * import * as E from 'fp-ts/Either';
+     *
+     * if (E.isLeft(req.decoded)) {
+     *    // input validation failed
+     * } else {
+     *    // input validation succeeded
+     * }
+     * ```
+     */
     deleteUnchecked: AddUncheckedRouteHandler<Spec, 'delete'>;
+    /**
+     * This function will create a PATCH route without validating the request, or encoding the response body.
+     * However, it will still try decode the request and set `req.decoded: Either<DecodedRequest, Error>`. To see the
+     * result of this operation, you can check `req.decoded` in your route handler like this:
+     *
+     * ```typescript
+     * import * as E from 'fp-ts/Either';
+     *
+     * if (E.isLeft(req.decoded)) {
+     *    // input validation failed
+     * } else {
+     *    // input validation succeeded
+     * }
+     * ```
+     */
     patchUnchecked: AddUncheckedRouteHandler<Spec, 'patch'>;
@@ -46,0 +142,0 @@ };

package.json

 {
   "name": "@api-ts/typed-express-router",
-  "version": "1.1.9",
+  "version": "1.1.10",
   "description": "Implement an HTTP specification with Express",
@@ -20,3 +20,3 @@ "author": "Patrick McLaughlin <[e-mail]>",
   "dependencies": {
-    "@api-ts/io-ts-http": "3.1.1",
+    "@api-ts/io-ts-http": "3.2.0",
     "@types/express": "4.17.21",
@@ -28,3 +28,3 @@ "express": "4.19.2",
   "devDependencies": {
-    "@api-ts/superagent-wrapper": "1.2.4",
+    "@api-ts/superagent-wrapper": "1.3.0",
     "@swc-node/register": "1.10.9",
@@ -31,0 +31,0 @@ "c8": "10.1.2",

No alert changes

Improved metrics

Total package byte prevSize

35739

increased by21.45%

Lines of code

376

increased by57.32%

Dependency changes

• + Added@api-ts/io-ts-http@3.2.0(transitive)

• - Removed@api-ts/io-ts-http@3.1.1(transitive)

• Updated@api-ts/io-ts-http@3.2.0