百科.dev
全部条目在线工具AI 编程趋势榜开源项目技术资讯提交条目
登录
< 返回工具列表
H

hyper-ts

> 编程语言
开源

适用于 HTTP 服务器的类型安全中间件架构

391 stars0 点赞1 次浏览
访问官网GitHub

工具介绍

适用于 HTTP 服务器的类型安全中间件架构

A partial porting of https://github.com/owickstrom/hyper to TypeScript

hyper-ts is an experimental middleware architecture for HTTP servers written in TypeScript.

Its main focus is correctness and type-safety, using type-level information to enforce correct composition and abstraction for web servers.

Goals

The goal of hyper-ts is to make use of type system features in TypeScript to enforce correctly stacked middleware in HTTP server applications. All effects of middleware should be reflected in the types to ensure that common mistakes cannot be made. A few examples of such mistakes could be:

  • Incorrect ordering of header and body writing
  • Writing incomplete responses
  • Writing multiple responses
  • Trying to consume a non-parsed request body
  • Consuming a request body parsed as the wrong type
  • Incorrect ordering of, or missing, error handling middleware
  • Incorrect ordering of middleware for sessions, authentication, authorization
  • Missing authentication and/or authorization checks

TypeScript compatibility

hyper-ts version fp-ts version typescript version express version
0.8.x+ 2.10.5+ 5.4+ 5.x
0.7.x+ 2.10.5+ 4.3+ 4.x
0.5.x+ 2.0.5+ 3.5+ 4.x
0.4.x+ 1.15.0+ 3.0.1+ 4.x

Hello world

…

Sending a JSON

typescript
const hello = pipe(
  M.status(H.Status.OK),
  M.iflatMap(() => M.json({ a: 1 }, () => 'error'))
)

Core API

Connection

A Connection models the entirety of a connection between the HTTP server and the user agent, both request and response.

State changes are tracked by the phantom type S.

…

By default hyper-ts manages the following states:

  • StatusOpen: Type indicating that the status-line is ready to be sent
  • HeadersOpen: Type indicating that headers are ready to be sent, i.e. the body streaming has not been started
  • BodyOpen: Type indicating that headers have already been sent, and that the body is currently streaming
  • ResponseEnded: Type indicating that headers have already been sent, and that the body stream, and thus the response, is finished

During the connection lifecycle the following flow is statically enforced

StatusOpen -> HeadersOpen -> BodyOpen -> ResponseEnded

Note. hyper-ts supports express 5.x by default by exporting a Connection instance from the hyper-ts/express module.

Middleware

A middleware is an indexed monadic action transforming one Connection to another Connection. It operates in the TaskEither monad, and is indexed by I and O, the input and output Connection types of the middleware action.

typescript
interface Middleware {
  (c: Connection): TaskEither]>
}

The input and output type parameters are used to ensure that a Connection is transformed, and that side-effects are performed, correctly, throughout the middleware chain.

Middlewares are composed using flatMap and iflatMap, the indexed monadic version of flatMap.

Type safety

Invalid operations are prevented statically

typescript
import { Status, status } from 'hyper-ts'

pipe(
  M.status(H.Status.OK),
  M.iflatMap(() => M.header('name', 'value')),
  M.iflatMap(() => M.closeHeaders()),
  M.iflatMap(() => M.send('Hello hyper-ts on express!')),
  // try to write a header after sending the body
  M.iflatMap(() => M.header('name', 'value')) // static error
)

No more "Can't set headers after they are sent." errors.

Decoding params, query and body

Input validation/decoding is done by defining a decoding function with the following signature

typescript
(input: unknown) => Either

Example (decoding a param)

typescript
import * as H from 'hyper-ts'
import * as M from 'hyper-ts/Middleware'
import * as E from 'fp-ts/Either'

const isUnknownRecord = (u: unknown): u is Record => typeof u === 'object' && u !== null

// returns a middleware validating `req.param.user_id`
export const middleware: M.Middleware = M.decodeParam('user_id', u =>
  isUnknownRecord(u) && typeof u.user_id === 'string' ? E.right(u.user_id) : E.left('cannot read param user_id')
)

You can also use io-ts decoders.

typescript
import * as H from 'hyper-ts'
import * as M from 'hyper-ts/Middleware'
import * as t from 'io-ts'

// returns a middleware validating `req.param.user_id`
export const middleware2: M.Middleware = M.decodeParam(
  'user_id',
  t.string.decode
)

Here I'm using t.string but you can pass any io-ts runtime type

typescript
import * as H from 'hyper-ts'
import * as M from 'hyper-ts/Middleware'
import { IntFromString } from 'io-ts-types/IntFromString'

// validation succeeds only if `req.param.user_id` can be parsed to an integer
export const middleware3: M.Middleware
> = M.decodeParam('user_id', IntFromString.decode)

Multiple params

typescript
import * as H from 'hyper-ts'
import * as M from 'hyper-ts/Middleware'
import * as t from 'io-ts'

// returns a middleware validating both `req.param.user_id` and `req.param.user_name`
export const middleware = M.decodeParams(
  t.strict({
    user_id: t.string,
    user_name: t.string
  }).decode
)

Query

typescript
import * as H from 'hyper-ts'
import * as M from 'hyper-ts/Middleware'
import * as t from 'io-ts'

// return a middleware validating the query "order=desc&shoe[color]=blue&shoe[type]=converse"
export const middleware = M.decodeQuery(
  t.strict({
    order: t.string,
    shoe: t.strict({
      color: t.string,
      type: t.string
    })
  }).decode
)

Body

typescript
import * as H from 'hyper-ts'
import * as M from 'hyper-ts/Middleware'
import * as t from 'io-ts'

// return a middleware validating `req.body`
export const middleware = M.decodeBody(t.string.decode)

Here's an example using the standard express.json middleware

Documentation

  • API Reference

Ecosystem

  • hyper-ts-connect - adapter for connect
  • hyper-ts-fastify - adapter for fastify

Issues· 0 开放

查看全部 Issues在 GitHub 打开

暂无开放 Issues,或尚未同步最近议题。

> 标签

TypeScript

暂无评论,来聊聊你的看法吧

> 工具信息

发布日期2026年8月1日
最后更新2026年9月17日
分类编程语言
定价开源

> 相关工具

T
TypeScript
JavaScript 的超集,为前端与全栈提供静态类型
P
Python
通用编程语言,广泛用于 Web、数据与 AI
G
Go
Google 推出的简洁高效系统语言