Skip to content

Commit

Permalink
wrapNative: Update docs
Browse files Browse the repository at this point in the history
  • Loading branch information
akheron committed Feb 15, 2021
1 parent 761eb18 commit 5f5dc3a
Showing 1 changed file with 17 additions and 22 deletions.
39 changes: 17 additions & 22 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -741,38 +741,33 @@ const myBody = <T>(
#### Using express middleware

_This is an experimental feature, and is currently available only for
`typera-express`._
`typera-express`. It can change without a corresponding semver bump._

Express middleware is inherently incompatible with typera middleware, not the
least because Express middleware cannot communicate typing information outside
to the next middleware/handler.
Express middleware is inherently incompatible with typera middleware, because
typera runs its middlewares independently of the Express middleware. This makes
it possible to pass typed data to the next middleware and the route handler.

However, lots of useful Express middleware already exists out there.
`typera-express` has a function that helps you wrap existing Express middleware
in a way that it works (mostly) like typera middleware does:

#### `Middleware.wrapNative<Request, Result>(middleware, options?: WrapNativeOptions<Request, Result>): Middleware<Request, never>`
##### `Middleware.wrapNative<Result>(middleware, result?: (request: RequestBase) => Result): Middleware<Result, never>`

Given Express middleware function `middleware`, return the corresponding typera
middleware.

Optional options:

- `timeout: number`: The time the middleware is waited for, in milliseconds. If
it doesn't call `next()` or send the response during that time, an error is
thrown. Defaults to 100.

- `result(request: Request): Result`: Return an object to be added to be merged
to the typera request object. Use this function to take any data the wrapped
middleware adds to `req` and make it consumable by other typera middleware or
the route handler function.

An Express middleware may either pass the control to the next middleware (or
route handler) in the chain by calling `next()` (the third parameter of the
middleware function), or send the response and end the middleware chain. Some
middleware also use various tricks to hook to the point where the response is
eventually sent, to e.g. log info about it. `wrapNative` tries to make all of
this possible, but there might be corner cases which don't work yet.
If the `result` function is given, its called after the middleware has run, and
its return value is merged to the typera request object. Use this function to
take any data the wrapped middleware produces and make it consumable by other
typera middleware or the route handler function.

The wrapped Express middleware may either pass the control to the next
middleware (or route handler) in the chain by calling `next()`, the third
parameter of the middleware function, or send the response and end the
middleware chain. Some middleware use various tricks to hook to the point where
the response is eventually sent, to e.g. log info about it. `wrapNative` tries
to make all of this possible, but there might be corner cases which don't work
yet.

### Routes

Expand Down

0 comments on commit 5f5dc3a

Please sign in to comment.