@trifrost/core

import { type TriFrostCache } from './modules/Cache'; import { Cookies } from './modules/Cookies'; import { type TriFrostLogger, type TriFrostRootLogger } from './modules/Logger'; import { type HttpMethod, type HttpStatusCode, type MimeType } from './types/constants'; import { type TriFrostRouteMatch } from './types/routing'; import { type TriFrostContextFileOptions, type TriFrostContextRedirectOptions, type TriFrostContextResponseOptions, type TriFrostContext, type TriFrostContextConfig, type TriFrostContextKind, type TriFrostContextRenderOptions } from './types/context'; import { type TriFrostBodyParserOptions, type ParsedBody } from './utils/BodyParser/types'; type RequestConfig = { method: HttpMethod; path: string; headers: Record<string, string>; query: string; }; /** * Used to get ip from headers under a trusted proxy, take note that this array will * be re-ordered automatically. */ export declare const IP_HEADER_CANDIDATES: string[]; export declare abstract class Context<Env extends Record<string, any> = {}, State extends Record<string, unknown> = {}> implements TriFrostContext<Env, State> { #private; /** * MARK: Protected */ protected ctx_config: Readonly<TriFrostContextConfig<Env>>; protected req_config: Readonly<RequestConfig>; protected req_id: string | null; protected req_body: Readonly<ParsedBody> | null; protected is_initialized: boolean; protected is_done: boolean; protected is_aborted: boolean; protected res_headers: Record<string, string>; protected res_code: HttpStatusCode; protected res_body: string | null; protected $cookies: Cookies | null; /** * MARK: Constructor */ constructor(logger: TriFrostRootLogger, cfg: TriFrostContextConfig<Env>, req: RequestConfig); /** * MARK: Getters */ /** * Whether or not the context was initialized */ get isInitialized(): boolean; /** * Whether or not the response was finished */ get isDone(): boolean; /** * Whether or not the request was aborted */ get isAborted(): boolean; /** * Whether or not the request is in a locked state and can not be written to anymore */ get isLocked(): boolean; /** * Returns the TriFrost environment */ get env(): Readonly<Env>; /** * Returns the method for the context */ get method(): HttpMethod; /** * Returns the name of the route the context is for (defaults to registration path) */ get name(): string; /** * Kind of context: This denotes the purpose of the context. * - 'notfound': This context is being run for a notfound catchall * - 'health': This context is being run on a route specifically meant for health checks * - 'std': General context, run everything :) * - 'options': Options run */ get kind(): TriFrostContextKind; /** * Returns the path for the context */ get path(): string; /** * Returns the host of the context. */ get host(): string; /** * Returns the domain of the context (extracted from host) */ get domain(): string | null; /** * Returns the ip address of the request for the context */ get ip(): string | null; /** * Request ID */ get requestId(): string; /** * Request Query parameters */ get query(): Readonly<URLSearchParams>; /** * Cache Instance */ get cache(): TriFrostCache; /** * Cookies for context */ get cookies(): Cookies; /** * Logger */ get logger(): TriFrostLogger; /** * Request Headers */ get headers(): Readonly<Record<string, string>>; /** * Current set response headers */ get resHeaders(): Readonly<Record<string, string>>; /** * Request Body */ get body(): Readonly<NonNullable<ParsedBody>>; /** * Security nonce */ get nonce(): string; /** * Internal State */ get state(): State; /** * Returns the response code for the context */ get statusCode(): HttpStatusCode; /** * Returns the currently configured timeout value */ get timeout(): number | null; /** * Returns the currently registered after hooks */ get afterHooks(): (<S extends {}>(ctx: TriFrostContext<Env, S>) => Promise<void>)[]; /** * MARK: State Mgmt */ /** * Expands the state and sets values */ setState<Patch extends Record<string, unknown>>(patch: Patch): TriFrostContext<Env, State & Patch>; /** * Remove a set of keys from the state */ delState<K extends keyof State>(keys: K[]): TriFrostContext<Env, Omit<State, K>>; /** * MARK: Timeouts */ /** * Sets the timeout */ setTimeout(val: number | null): void; /** * Clears the existing timeout */ clearTimeout(): void; /** * MARK: Headers */ /** * Set a header as part of the response to be returned to the callee * * Example: * ctx.setHeader('Content-Type', 'application/json'); */ setHeader(key: string, val: string | number): void; /** * Sets multiple headers at once as part of the response to be returned to the callee * * Example: * ctx.setHeader('Content-Type', 'application/json'); */ setHeaders(obj: Record<string, string | number>): void; /** * Remove a header that was previously set as part of the response to be returned to the callee * * Example: * ctx.delHeader('Content-Type'); */ delHeader(key: string): void; /** * Remove multiple headers from the response * * Example: * ctx.delHeader('Content-Type'); */ delHeaders(keys: string[]): void; /** * Alias for setHeader('Content-Type', ...) with built-in safety for internally known mime types * * Example: * ctx.setType('text/html') */ setType(val: MimeType): void; /** * MARK: Status */ /** * Sets the response status code to a known HTTP status code */ setStatus(status: HttpStatusCode): void; /** * MARK: Body */ /** * Sets the body of the response to be returned to the callee */ setBody(value: string | null): void; /** * MARK: LifeCycle */ /** * Initializes the request body and parses it into Json or FormData depending on its type */ init(match: TriFrostRouteMatch<Env>, handler?: (config: TriFrostBodyParserOptions | null) => Promise<ParsedBody | null>): Promise<void>; /** * Runs a fetch request and automatically appends the request id as well as spans. * * @param {string|URL} input * @param {RequestInit} init */ fetch(input: string | URL, init?: RequestInit): Promise<Response>; /** * Abort the request * * @param {HttpStatusCode?} status - Status to abort with (defaults to 503) */ abort(status?: HttpStatusCode): void; /** * End the request and respond to callee */ end(): void | Response; /** * Register an after hook */ addAfter<S extends {}>(fn: (ctx: TriFrostContext<Env, S>) => Promise<void>): void; /** * MARK: Response */ /** * Render a JSX body to a string */ render(body: JSX.Element, opts?: TriFrostContextRenderOptions): Promise<string>; /** * Respond with a file */ file(input: string | { stream: unknown; size?: number | null; name: string; }, opts?: TriFrostContextFileOptions): Promise<void>; /** * Respond with HTML */ html(body?: string | JSX.Element, opts?: TriFrostContextResponseOptions): Promise<void>; /** * Respond with JSON */ json(body?: Record<string, unknown> | unknown[], opts?: TriFrostContextResponseOptions): void; /** * Respond with a status and no body */ status(status: HttpStatusCode): void; /** * Respond with plain text */ text(body: string, opts?: TriFrostContextResponseOptions): void; /** * Respond by redirecting * * @note Default status is 303 See Other * @note Default keep_query is true */ redirect(to: string, opts?: TriFrostContextRedirectOptions): void; /** * MARK: Protected */ /** * If trustProxy is true tries to compute the IP from well-known headers */ protected getIPFromHeaders(): string | null; /** * If trustProxy is true tries to compute the Host from well-known headers */ protected getHostFromHeaders(): string | null; /** * Stream a response from a streamlike value */ protected stream(stream: unknown, size: number | null): void; /** * MARK: Abstract */ /** * Retrieve a streamable */ abstract getStream(path: string): Promise<{ stream: unknown; size: number | null; } | null>; /** * Runs our after hooks */ abstract runAfter(): void; /** * Abstract function to be implemented by Context classes which computes the IP address * for a request on that runtime */ protected abstract getIP(): string | null; } export {};