flowingts / Context

Classe: Context<S>

Definido em: src/core/context.ts:161

Parâmetros de tipo

S

S extends RouteSchemas | string = RouteSchemas

Construtores

Construtor

new Context<S>(req, res, opts?, id?): Context<S>

Definido em: src/core/context.ts:404

Parâmetros

req

IncomingMessage

res

ServerResponse

opts?

ContextOptions = {}

configuração; o app passa o mesmo objeto para todas as requisições (Flyweight), e o que muda por requisição (id) vem à parte.

id?

string

Retorna

Context<S>

Propriedades

body

body: InferSchema<SchemasOf<S>["body"]>

Definido em: src/core/context.ts:282

Body; tipado pelo schema body.

---

id

readonly id: string

Definido em: src/core/context.ts:167

Id da requisição, também enviado no header X-Request-Id (F-06).

---

method

readonly method: string

Definido em: src/core/context.ts:164

---

path

readonly path: string

Definido em: src/core/context.ts:165

---

req

readonly req: IncomingMessage

Definido em: src/core/context.ts:162

---

res

readonly res: ServerResponse

Definido em: src/core/context.ts:163

---

sentType

sentType: string | undefined

Definido em: src/core/context.ts:397

Content-Type da resposta enviada, junto com sentBody.

---

statusExplicit

statusExplicit: boolean = false

Definido em: src/core/context.ts:294

true quando o handler chamou ctx.status(). Usado para escolher o schema de resposta (B-05).

Acessores

abortReason

Assinatura do getter

get abortReason(): AbortCode | undefined

Definido em: src/core/context.ts:327

Por que esta requisição foi cancelada (CLIENT_DISCONNECTED, SHUTDOWN), ou undefined se não foi. Atalho tipado para ctx.signal.reason.code (F-38).

Retorna

AbortCode | undefined

---

cookies

Assinatura do getter

get cookies(): Readonly<Record<string, string>>

Definido em: src/core/context.ts:484

Cookies da requisição (objeto sem protótipo; em nomes repetidos vale o primeiro).

Retorna

Readonly<Record<string, string>>

---

host

Assinatura do getter

get host(): string

Definido em: src/core/context.ts:428

Host da requisição (api.exemplo.com:8080), validado: um valor inválido vira ''. Com trustProxy, vem do X-Forwarded-Host. Para links absolutos, prefira uma URL base configurada em vez do host pedido pelo cliente (S-09).

Retorna

string

---

hostname

Assinatura do getter

get hostname(): string

Definido em: src/core/context.ts:438

host sem a porta.

Retorna

string

---

ip

Assinatura do getter

get ip(): string

Definido em: src/core/context.ts:419

IP do cliente. Por padrão, o do socket. Com trustProxy, vem do X-Forwarded-For, que só deve ser ligado atrás de um proxy que reescreve esse header (S-09).

Retorna

string

---

log

Assinatura do getter

get log(): Logger

Definido em: src/core/context.ts:231

Logger da requisição, já com reqId (F-06). Criado no primeiro acesso.

Retorna

Logger

---

params

Assinatura do getter

get params(): ParamsFor<S>

Definido em: src/core/context.ts:170

Parâmetros de rota; tipados pelo schema params quando informado em Context<S>.

Retorna

ParamsFor<S>

Assinatura do setter

set params(value): void

Definido em: src/core/context.ts:174

Parâmetros

value

ParamsFor<S>

Retorna

void

---

protocol

Assinatura do getter

get protocol(): "http" | "https"

Definido em: src/core/context.ts:444

https se a conexão for TLS ou, com trustProxy, se o X-Forwarded-Proto disser; senão http.

Retorna

"http" | "https"

---

query

Assinatura do getter

get query(): InferQuery<SchemasOf<S>>

Definido em: src/core/context.ts:204

Query string; tipada pelo schema query (já com coerção e defaults aplicados). Lida no primeiro acesso.

Retorna

InferQuery<SchemasOf<S>>

Assinatura do setter

set query(value): void

Definido em: src/core/context.ts:220

Parâmetros

value

InferQuery<SchemasOf<S>>

Retorna

void

---

route

Assinatura do getter

get route(): RouteInfo | undefined

Definido em: src/core/context.ts:183

A rota que atende esta requisição (F-38): template com o prefixo, classe, método e a regra de host que venceu. undefined antes do roteamento e quando nenhuma rota atende (404, 405, healthcheck, OpenAPI). Use ctx.route.path como rótulo de métrica, nunca ctx.path.

Retorna

RouteInfo | undefined

---

sent

Assinatura do getter

get sent(): boolean

Definido em: src/core/context.ts:471

true quando a resposta já foi enviada (ou está sendo, no caso de streams). Depois disso o framework não escreve mais nada na resposta.

Retorna

boolean

---

sentBody

Assinatura do getter

get sentBody(): Buffer<ArrayBufferLike> | undefined

Definido em: src/core/context.ts:383

Corpo exatamente como foi escrito (F-04), depois do envio. Fica undefined em streams e em respostas sem corpo. Útil para cache: await next(); store.set(key, ctx.sentBody).

Retorna

Buffer<ArrayBufferLike> | undefined

Assinatura do setter

set sentBody(value): void

Definido em: src/core/context.ts:390

Parâmetros

value

Buffer<ArrayBufferLike> | undefined

Retorna

void

---

signal

Assinatura do getter

get signal(): AbortSignal

Definido em: src/core/context.ts:303

Cancelado quando o cliente desconecta antes do fim da resposta, ou quando o app está encerrando (F-13). Passe para consultas e fetch longos: db.query(sql, { signal: ctx.signal }).

Retorna

AbortSignal

---

state

Assinatura do getter

get state(): ContextState

Definido em: src/core/context.ts:284

Estado por requisição, criado no primeiro acesso (F-41).

Retorna

ContextState

Assinatura do setter

set state(value): void

Definido em: src/core/context.ts:288

Parâmetros

value

ContextState

Retorna

void

---

trace

Assinatura do getter

get trace(): TraceContext | undefined

Definido em: src/core/context.ts:248

Contexto de trace W3C recebido no traceparent (F-38), já validado: { traceId, parentSpanId, sampled, tracestate }, ou undefined se não veio ou é inválido. Os logs do ctx.log levam o traceId.

Retorna

TraceContext | undefined

---

url

Assinatura do getter

get url(): URL

Definido em: src/core/context.ts:225

URL completa da requisição, com o host validado (S-09). Criada no primeiro acesso.

Retorna

URL

Métodos

clearCookie()

clearCookie(name, opts?): this

Definido em: src/core/context.ts:498

Remove um cookie. Informe o mesmo path e domain usados ao criá-lo.

Parâmetros

name

string

opts?

Omit<CookieOptions, "maxAge" | "expires"> = {}

Retorna

this

---

file()

file<K>(name): FileOf<SchemasOf<S>, K>

Definido em: src/core/context.ts:274

Um arquivo do upload, já recebido e validado pelo contrato files (F-46). Com required: true, nunca é undefined. Para campos com maxCount maior que 1, use files().

Parâmetros de tipo

K

K extends string

Parâmetros

name

K

Retorna

FileOf<SchemasOf<S>, K>

---

files()

files<K>(name): readonly UploadedFile[]

Definido em: src/core/context.ts:278

Todos os arquivos de um campo do upload (F-46), na ordem em que chegaram; vazio se nenhum veio.

Parâmetros de tipo

K

K extends string

Parâmetros

name

K

Retorna

readonly UploadedFile[]

---

get()

get(name): string | undefined

Definido em: src/core/context.ts:476

Lê um header da requisição (case-insensitive). Headers repetidos são unidos com , .

Parâmetros

name

string

Retorna

string | undefined

---

header()

header(name, value): this

Definido em: src/core/context.ts:503

Define um header da resposta.

Parâmetros

name

string

value

OutgoingHttpHeader

Retorna

this

---

json()

json(data): this

Definido em: src/core/context.ts:512

Envia JSON. No handler, passa pelo mesmo pipeline do return: schema do status, remoção de campos não declarados e status padrão (F-32).

Parâmetros

data

unknown

Retorna

this

---

redirect()

redirect(url, status?): this

Definido em: src/core/context.ts:589

Redireciona (padrão 302). Não use url vinda do usuário sem validar: isso abre um open redirect. Prefira caminhos relativos ou uma lista de destinos permitidos.

Parâmetros

url

string

status?

301 | 302 | 303 | 307 | 308 = 302

Retorna

this

---

send()

send(body, contentType?): this

Definido em: src/core/context.ts:526

Envia o corpo pelo mesmo pipeline do return (F-32): com contentType informado, usa esse tipo; senão, a negociação do Accept ou o tipo do valor (string, Buffer, stream, objeto → JSON). Para HTML, faça o escape do conteúdo dinâmico antes: o framework não faz isso por você (S-02).

Parâmetros

body

unknown

contentType?

string

Retorna

this

---

sendFile()

sendFile(path, opts?): Promise<void>

Definido em: src/core/context.ts:368

Envia um arquivo com Content-Type, ETag/Last-Modified (304) e Range (206), em stream (F-13). Com root, o path é relativo e não pode sair dela; sem root, precisa ser absoluto. Arquivo inexistente responde 404.

Parâmetros

path

string

opts?

SendFileOptions

Retorna

Promise<void>

---

setCookie()

setCookie(name, value, opts?): this

Definido em: src/core/context.ts:492

Adiciona um Set-Cookie. Padrões: HttpOnly, Secure, SameSite=Lax e Path=/. Se usar cookies para autenticar, ative também o middleware csrf().

Parâmetros

name

string

value

string

opts?

CookieOptions

Retorna

this

---

sse()

sse(opts?): SseStream

Definido em: src/core/context.ts:359

Abre uma conexão de Server-Sent Events (F-13). A resposta fica aberta até close(), a desconexão do cliente ou o encerramento do app, que fecha estas conexões primeiro para o shutdown não esperar por elas.

const stream = ctx.sse();
const off = bus.on('order', (o) => stream.send({ event: 'order', id: o.id, data: o }));
stream.onClose(off);

Parâmetros

opts?

SseOptions = {}

Retorna

SseStream

---

status()

status<St>(code): StatusContext<S, St>

Definido em: src/core/context.ts:461

Define o status. Com schemas de resposta, aceita só os status declarados e o encadeamento tipa o corpo: ctx.status(202).json({ jobId }) (F-32).

Parâmetros de tipo

St

St extends number

Parâmetros

code

St

Retorna

StatusContext<S, St>

---

text()

text(data): this

Definido em: src/core/context.ts:517

Resposta em texto puro (text/plain; charset=utf-8), pelo mesmo pipeline do return.

Parâmetros

data

string

Retorna

this

---

throw()

throw(status, message, code?): never

Definido em: src/core/context.ts:598

Parâmetros

status

number

message

string

code?

string

Retorna

never