@cuple/server

Functions

apiResponse()

apiResponse<Result, StatusCode, Others>(result, statusCode, others): ApiResponse<Result, StatusCode, Others>

Defined in: responses.ts:11

Type Parameters

Result

Result extends string

StatusCode

StatusCode extends number

Others

Others extends object

Parameters

result

Result

statusCode

StatusCode

others

Others

Returns

ApiResponse<Result, StatusCode, Others>

buffer()

buffer(options?): RawBodyParser<Buffer, Buffer>

Defined in: body-parsers.ts:9

Parameters

options?

Options

Returns

RawBodyParser<Buffer, Buffer>

createBuilder()

createBuilder(app, options?): Builder<BuilderParams>

Defined in: builder.ts:785

Create endpoint builder for Express app.

Parameters

app

Express

Express application instance

options?

Pick<BuilderConfig, "errorHandler">

Optional error handler

Returns

Builder<BuilderParams>

initRpc()

initRpc(app, config): void

Defined in: rpc-handler.ts:21

Parameters

app

Express

config

InitRpcConfig

Returns

void

invalidInput()

invalidInput<TPart, TIssues>(part, issues): InvalidInput<TPart, JsonPath<TIssues[number]["path"]>>

Defined in: responses.ts:40

A request part failed validation: invalid-body, invalid-query, invalid-params or invalid-headers. Schemas return it on their own; return it from a handler for a rule a schema can't check (an email already in use), so the client handles both the same way.

Type Parameters

TPart

TPart extends InputPart

TIssues

TIssues extends readonly Pick<$ZodIssue, "code" | "message"> & object[]

Parameters

part

TPart

issues

TIssues

Returns

InvalidInput<TPart, JsonPath<TIssues[number]["path"]>>

json()

json(options?): RawBodyParser<undefined, undefined>

Defined in: body-parsers.ts:17

Parameters

options?

OptionsJson

Returns

RawBodyParser<undefined, undefined>

success()

success<Others>(others): object & Others

Defined in: responses.ts:26

Type Parameters

Others

Others

Parameters

others

Others

Returns

object & Others

unexpectedError()

unexpectedError(): ApiResponse<"unexpected-error", 500, { message: string; }>

Defined in: responses.ts:56

Returns

ApiResponse<"unexpected-error", 500, { message: string; }>

Classes

Builder

Defined in: builder.ts:174

Type-safe Express endpoint builder. Chain methods to add validation and middleware. Finalize with get/post/put/patch/delete.

Type Parameters

TParams

TParams extends AnyBuilderParams = BuilderParams

Constructors

Constructor

new Builder<TParams>(config): Builder<TParams>

Defined in: builder.ts:177

Parameters

config

BuilderConfig

Returns

Builder<TParams>

Methods

bodySchema()

bodySchema<TParser>(parser): Builder<{ tData: TParams["tData"] & object; tDependencyData: TParams["tDependencyData"]; tInput: TParams["tInput"] & object; tMeta: TParams["tMeta"]; tMethod: TParams["tMethod"]; tResponses: TParams["tResponses"] | InvalidInput<"body", InputPath<input<TParser>>>; }>

Defined in: builder.ts:263

Validate request body with Zod schema. Parsed data available in handler as data.body.

Type Parameters

TParser

TParser extends ZodType<any, any, $ZodTypeInternals<any, any>>

Parameters

parser

TParser

Returns

Builder<{ tData: TParams["tData"] & object; tDependencyData: TParams["tDependencyData"]; tInput: TParams["tInput"] & object; tMeta: TParams["tMeta"]; tMethod: TParams["tMethod"]; tResponses: TParams["tResponses"] | InvalidInput<"body", InputPath<input<TParser>>>; }>

chain()

chain<TLinkInput, TLinkData, TLinkResponses, TLinkDependencyData>(link): AssertedBuilderType

Defined in: builder.ts:388

Add a reusable chain link to the current chain. Chain links are created with buildLink(). Validates that required dependencies are satisfied.

Type Parameters

TLinkInput

TLinkInput

TLinkData

TLinkData

TLinkResponses

TLinkResponses

TLinkDependencyData

TLinkDependencyData

Parameters

link

Middleware<TLinkInput, TLinkData, TLinkResponses, TLinkDependencyData>

Returns

AssertedBuilderType

expectChain()

expectChain<TChain>(): Builder<{ tData: TParams["tData"] & TDataIncoming; tDependencyData: TParams["tDependencyData"] & TDataIncoming; tInput: TParams["tInput"] & TInputIncoming; tMeta: TParams["tMeta"]; tMethod: TParams["tMethod"]; tResponses: TParams["tResponses"] | TResponsesIncoming; }>

Defined in: builder.ts:363

Declare dependency on another chain link's data. Use when building a chain link that requires data from another link (e.g., role check needs auth data).

Type Parameters

TChain

TChain extends Middleware<any, any, any, any>

Returns

Builder<{ tData: TParams["tData"] & TDataIncoming; tDependencyData: TParams["tDependencyData"] & TDataIncoming; tInput: TParams["tInput"] & TInputIncoming; tMeta: TParams["tMeta"]; tMethod: TParams["tMethod"]; tResponses: TParams["tResponses"] | TResponsesIncoming; }>

headersSchema()

headersSchema<TParser>(parser): Builder<{ tData: TParams["tData"] & object; tDependencyData: TParams["tDependencyData"]; tInput: TParams["tInput"] & object; tMeta: TParams["tMeta"]; tMethod: TParams["tMethod"]; tResponses: TParams["tResponses"] | InvalidInput<"headers", InputPath<input<TParser>>>; }>

Defined in: builder.ts:331

Validate request headers with Zod schema. Parsed data available in handler as data.headers. Note: Express lowercases header names (e.g., "Authorization" -> "authorization").

Type Parameters

TParser

TParser extends ZodType<any, any, $ZodTypeInternals<any, any>>

Parameters

parser

TParser

Returns

meta()

meta<T>(meta): Builder<{ tData: TParams["tData"]; tDependencyData: TParams["tDependencyData"]; tInput: TParams["tInput"]; tMeta: T; tMethod: TParams["tMethod"]; tResponses: TParams["tResponses"]; }>

Defined in: builder.ts:185

Add custom metadata to the endpoint, e.g. OpenAPI description

Type Parameters

T

T extends object

Parameters

Returns

Builder<{ tData: TParams["tData"]; tDependencyData: TParams["tDependencyData"]; tInput: TParams["tInput"]; tMeta: T; tMethod: TParams["tMethod"]; tResponses: TParams["tResponses"]; }>

middleware()

middleware<TResult>(mw): Builder<{ tData: TParams["tData"] & TResult & object; tDependencyData: TParams["tDependencyData"]; tInput: TParams["tInput"]; tMeta: TParams["tMeta"]; tMethod: TParams["tMethod"]; tResponses: TParams["tResponses"] | TResult extends object ? TResult : never; }>

Defined in: builder.ts:237

Add middleware to transform data or return early. next: true passes data to next handler. next: false ends chain and returns response.

Type Parameters

TResult

TResult extends ValidMiddlewareReturnType

Parameters

mw

Middleware<any, TParams["tData"], TResult>

Returns

Builder<{ tData: TParams["tData"] & TResult & object; tDependencyData: TParams["tDependencyData"]; tInput: TParams["tInput"]; tMeta: TParams["tMeta"]; tMethod: TParams["tMethod"]; tResponses: TParams["tResponses"] | TResult extends object ? TResult : never; }>

paramsSchema()

paramsSchema<TParser>(parser): Builder<{ tData: TParams["tData"] & object; tDependencyData: TParams["tDependencyData"]; tInput: TParams["tInput"] & object; tMeta: TParams["tMeta"]; tMethod: TParams["tMethod"]; tResponses: TParams["tResponses"] | InvalidInput<"params", InputPath<input<TParser>>>; }>

Defined in: builder.ts:307

Validate route parameters with Zod schema. Parsed data available in handler as data.params.

Type Parameters

TParser

TParser extends ZodType<any, any, $ZodTypeInternals<any, any>>

Parameters

parser

TParser

Returns

path()

path(path): Builder<TParams>

Defined in: builder.ts:351

Set route path (e.g., "/users/:id").

Parameters

path

string

Returns

Builder<TParams>

querySchema()

querySchema<TParser>(parser): Builder<{ tData: TParams["tData"] & object; tDependencyData: TParams["tDependencyData"]; tInput: TParams["tInput"] & object; tMeta: TParams["tMeta"]; tMethod: TParams["tMethod"]; tResponses: TParams["tResponses"] | InvalidInput<"query", InputPath<input<TParser>>>; }>

Defined in: builder.ts:284

Validate query parameters with Zod schema. Parsed data available in handler as data.query.

Type Parameters

TParser

TParser extends ZodType<any, any, $ZodTypeInternals<any, any>>

Parameters

parser

TParser

Returns

rawBody()

Call Signature

rawBody(): Builder<{ tData: TParams["tData"]; tDependencyData: TParams["tDependencyData"]; tInput: TParams["tInput"] & object; tMeta: TParams["tMeta"]; tMethod: TParams["tMethod"]; tResponses: TParams["tResponses"]; }>

Defined in: builder.ts:196

Returns

Builder<{ tData: TParams["tData"]; tDependencyData: TParams["tDependencyData"]; tInput: TParams["tInput"] & object; tMeta: TParams["tMeta"]; tMethod: TParams["tMethod"]; tResponses: TParams["tResponses"]; }>

Call Signature

rawBody<TData, TInput>(parser): Builder<{ tData: TParams["tData"] & undefined extends TData ? object : object; tDependencyData: TParams["tDependencyData"]; tInput: TParams["tInput"] & undefined extends TInput ? object : object; tMeta: TParams["tMeta"]; tMethod: TParams["tMethod"]; tResponses: TParams["tResponses"]; }>

Defined in: builder.ts:204

Type Parameters

TData

TData

TInput

TInput

Parameters

parser

RawBodyParser<TData, TInput>

Returns

Builder<{ tData: TParams["tData"] & undefined extends TData ? object : object; tDependencyData: TParams["tDependencyData"]; tInput: TParams["tInput"] & undefined extends TInput ? object : object; tMeta: TParams["tMeta"]; tMethod: TParams["tMethod"]; tResponses: TParams["tResponses"]; }>

Properties

buildLink

buildLink: () => Middleware<TParams["tInput"], TParams["tData"], TParams["tResponses"], TParams["tDependencyData"]>

Defined in: builder.ts:411

Build as reusable chain link. Chain links can be added to other chains with chain().

Returns

Middleware<TParams["tInput"], TParams["tData"], TParams["tResponses"], TParams["tDependencyData"]>

delete

delete: <TFinalResponses>(mw) => BuiltEndpoint<TParams["tInput"], UnexpectedError | TParams["tResponses"] | TFinalResponses, "delete", TParams["tMeta"]>

Defined in: builder.ts:476

Finalize as DELETE. Handler returns JSON response.

Type Parameters

TFinalResponses

TFinalResponses extends ValidJsonObject

Parameters

mw

Finalware<TParams["tData"], TParams["tResponses"] | TFinalResponses>

Returns

BuiltEndpoint<TParams["tInput"], UnexpectedError | TParams["tResponses"] | TFinalResponses, "delete", TParams["tMeta"]>

deleteRaw

deleteRaw: (mw) => BuiltEndpoint<TParams["tInput"], any, TParams["tMethod"], TParams["tMeta"]>

Defined in: builder.ts:514

Finalize as DELETE with raw handler. For streaming, downloads, custom responses. Not compatible with @cuple/client, use fetch.

Parameters

mw

Finalware<object & TParams["tData"] | object & TParams["tResponses"], any>

Returns

BuiltEndpoint<TParams["tInput"], any, TParams["tMethod"], TParams["tMeta"]>

deleteSSE

deleteSSE: <TEvent>(mw, options?) => object & object & object

Defined in: builder.ts:489

Finalize as DELETE with SSE stream.

Type Parameters

TEvent

TEvent extends ValidJsonObject

Parameters

mw

(props) => AsyncGenerator<TEvent>

options?

SSEOptions

Returns

object & object & object

get

get: <TFinalResponses>(mw) => BuiltEndpoint<TParams["tInput"], UnexpectedError | TParams["tResponses"] | TFinalResponses, "get", TParams["tMeta"]>

Defined in: builder.ts:470

Finalize as GET. Handler returns JSON response.

Type Parameters

TFinalResponses

TFinalResponses extends ValidJsonObject

Parameters

mw

Finalware<TParams["tData"], TParams["tResponses"] | TFinalResponses>

Returns

BuiltEndpoint<TParams["tInput"], UnexpectedError | TParams["tResponses"] | TFinalResponses, "get", TParams["tMeta"]>

getRaw

getRaw: (mw) => BuiltEndpoint<TParams["tInput"], any, TParams["tMethod"], TParams["tMeta"]>

Defined in: builder.ts:496

Finalize as GET with raw handler. For streaming, downloads, custom responses. Not compatible with @cuple/client, use fetch.

Parameters

mw

Finalware<object & TParams["tData"] | object & TParams["tResponses"], any>

Returns

BuiltEndpoint<TParams["tInput"], any, TParams["tMethod"], TParams["tMeta"]>

getSSE

getSSE: <TEvent>(mw, options?) => object & object & object

Defined in: builder.ts:481

Finalize as GET with SSE stream.

Type Parameters

TEvent

TEvent extends ValidJsonObject

Parameters

mw

(props) => AsyncGenerator<TEvent>

options?

SSEOptions

Returns

object & object & object

patch

patch: <TFinalResponses>(mw) => BuiltEndpoint<TParams["tInput"], UnexpectedError | TParams["tResponses"] | TFinalResponses, "patch", TParams["tMeta"]>

Defined in: builder.ts:474

Finalize as PATCH. Handler returns JSON response.

Type Parameters

TFinalResponses

TFinalResponses extends ValidJsonObject

Parameters

mw

Finalware<TParams["tData"], TParams["tResponses"] | TFinalResponses>

Returns

BuiltEndpoint<TParams["tInput"], UnexpectedError | TParams["tResponses"] | TFinalResponses, "patch", TParams["tMeta"]>

patchRaw

patchRaw: (mw) => BuiltEndpoint<TParams["tInput"], any, TParams["tMethod"], TParams["tMeta"]>

Defined in: builder.ts:508

Finalize as PATCH with raw handler. For streaming, downloads, custom responses. Not compatible with @cuple/client, use fetch.

Parameters

mw

Finalware<object & TParams["tData"] | object & TParams["tResponses"], any>

Returns

BuiltEndpoint<TParams["tInput"], any, TParams["tMethod"], TParams["tMeta"]>

patchSSE

patchSSE: <TEvent>(mw, options?) => object & object & object

Defined in: builder.ts:487

Finalize as PATCH with SSE stream.

Type Parameters

TEvent

TEvent extends ValidJsonObject

Parameters

mw

(props) => AsyncGenerator<TEvent>

options?

SSEOptions

Returns

object & object & object

post

post: <TFinalResponses>(mw) => BuiltEndpoint<TParams["tInput"], UnexpectedError | TParams["tResponses"] | TFinalResponses, "post", TParams["tMeta"]>

Defined in: builder.ts:472

Finalize as POST. Handler returns JSON response.

Type Parameters

TFinalResponses

TFinalResponses extends ValidJsonObject

Parameters

mw

Finalware<TParams["tData"], TParams["tResponses"] | TFinalResponses>

Returns

BuiltEndpoint<TParams["tInput"], UnexpectedError | TParams["tResponses"] | TFinalResponses, "post", TParams["tMeta"]>

postRaw

postRaw: (mw) => BuiltEndpoint<TParams["tInput"], any, TParams["tMethod"], TParams["tMeta"]>

Defined in: builder.ts:502

Finalize as POST with raw handler. For streaming, downloads, custom responses. Not compatible with @cuple/client, use fetch.

Parameters

mw

Finalware<object & TParams["tData"] | object & TParams["tResponses"], any>

Returns

BuiltEndpoint<TParams["tInput"], any, TParams["tMethod"], TParams["tMeta"]>

postSSE

postSSE: <TEvent>(mw, options?) => object & object & object

Defined in: builder.ts:483

Finalize as POST with SSE stream.

Type Parameters

TEvent

TEvent extends ValidJsonObject

Parameters

mw

(props) => AsyncGenerator<TEvent>

options?

SSEOptions

Returns

object & object & object

put

put: <TFinalResponses>(mw) => BuiltEndpoint<TParams["tInput"], UnexpectedError | TParams["tResponses"] | TFinalResponses, "put", TParams["tMeta"]>

Defined in: builder.ts:478

Finalize as PUT. Handler returns JSON response.

Type Parameters

TFinalResponses

TFinalResponses extends ValidJsonObject

Parameters

mw

Finalware<TParams["tData"], TParams["tResponses"] | TFinalResponses>

Returns

BuiltEndpoint<TParams["tInput"], UnexpectedError | TParams["tResponses"] | TFinalResponses, "put", TParams["tMeta"]>

putRaw

putRaw: (mw) => BuiltEndpoint<TParams["tInput"], any, TParams["tMethod"], TParams["tMeta"]>

Defined in: builder.ts:520

Finalize as PUT with raw handler. For streaming, downloads, custom responses. Not compatible with @cuple/client, use fetch.

Parameters

mw

Finalware<object & TParams["tData"] | object & TParams["tResponses"], any>

Returns

BuiltEndpoint<TParams["tInput"], any, TParams["tMethod"], TParams["tMeta"]>

putSSE

putSSE: <TEvent>(mw, options?) => object & object & object

Defined in: builder.ts:485

Finalize as PUT with SSE stream.

Type Parameters

TEvent

TEvent extends ValidJsonObject

Parameters

mw

(props) => AsyncGenerator<TEvent>

options?

SSEOptions

Returns

object & object & object

Variables

conflict

const conflict: <Result, Others>(options?) => StatusResponse<Result, 409, Others>

Defined in: responses.ts:115

409: the request clashes with the current state. The result is conflict unless you name it (email-taken).

Type Parameters

Result

Result extends string = "conflict"

Others

Others extends StatusResponseOptions<Result> = { }

Parameters

options?

Others & object & Record<string, unknown>

Returns

StatusResponse<Result, 409, Others>

forbidden

const forbidden: <Result, Others>(options?) => StatusResponse<Result, 403, Others>

Defined in: responses.ts:108

403: the user is known but not allowed. The result is forbidden unless you name it.

Type Parameters

Result

Result extends string = "forbidden"

Others

Others extends StatusResponseOptions<Result> = { }

Parameters

options?

Others & object & Record<string, unknown>

Returns

StatusResponse<Result, 403, Others>

notFound

const notFound: <Result, Others>(options?) => StatusResponse<Result, 404, Others>

Defined in: responses.ts:102

The result is not-found unless you name it: when a route can miss more than one thing, name each (post-not-found, author-not-found) so the client can tell them apart.

Type Parameters

Result

Result extends string = "not-found"

Others

Others extends StatusResponseOptions<Result> = { }

Parameters

options?

Others & object & Record<string, unknown>

Returns

StatusResponse<Result, 404, Others>

unauthorized

const unauthorized: <Result, Others>(options?) => StatusResponse<Result, 401, Others>

Defined in: responses.ts:105

401: the request has no valid credentials. The result is unauthorized unless you name it.

Type Parameters

Result

Result extends string = "unauthorized"

Others

Others extends StatusResponseOptions<Result> = { }

Parameters

options?

Others & object & Record<string, unknown>

Returns

StatusResponse<Result, 401, Others>

Type Aliases

InitRpcConfig

InitRpcConfig = object

Defined in: rpc-handler.ts:4

Properties

path

path: string

Defined in: rpc-handler.ts:5

routes

routes: RecursiveApi

Defined in: rpc-handler.ts:6

InputPart

InputPart = "body" | "query" | "params" | "headers"

Defined in: responses.ts:32

The part of a request a schema validates.

InputPath

InputPath<T> = [] | FieldPath<T, []>

Defined in: responses.ts:143

The paths into a value of type T: InputPath<{ a: { b: string[] } }> is [] | ["a"] | ["a", "b"] | ["a", "b", number].

Type Parameters

T

T

InvalidInput

InvalidInput<TPart, TPath> = ApiResponse<`invalid-${TPart}`, 422, { issues: object[]; message: string; }>

Defined in: responses.ts:124

Type Parameters

TPart

TPart extends InputPart

TPath

TPath extends (string | number)[] = (string | number)[]

RawBodyParser

RawBodyParser<TData, TInput> = object

Defined in: body-parsers.ts:3

Type Parameters

TData

TData

TInput

TInput = TData

Properties

_expressMiddleware

_expressMiddleware: (req, res, next) => void

Defined in: body-parsers.ts:4

Parameters

req

Request

res

Response

() => void

Returns

void

_phantomData?

optional _phantomData?: TData

Defined in: body-parsers.ts:5

_phantomInput?

optional _phantomInput?: TInput

Defined in: body-parsers.ts:6

SSEOptions

SSEOptions = object

Defined in: builder.ts:110

Properties

returnOnDisconnect?

optional returnOnDisconnect?: boolean

Defined in: builder.ts:126

Whether to close the handler's generator when the client disconnects. Defaults to true.

false is for a generator that ends on its own — one draining a finite job, say, that should finish its work whether or not anyone is still reading. A generator that loops forever must not opt out: nothing will stop it, and after the client is gone it keeps running at full speed, one runaway loop per disconnected request, for the life of the process.

A generator that needs to outlive the disconnect only briefly should check disconnectSignal.aborted on each pass and return once it is set. That is also the only way to end one parked on an await rather than a yield, which returnOnDisconnect cannot reach either way.

StatusResponse

StatusResponse<Result, StatusCode, Others> = ApiResponse<Result, StatusCode, Omit<Others, "result" | "message"> & object>

Defined in: responses.ts:68

What a status factory returns: the extra fields stay, message is always there.

Type Parameters

Result

Result extends string

StatusCode

StatusCode extends number

Others

Others

StatusResponseOptions

StatusResponseOptions<Result> = object & Record<string, unknown>

Defined in: responses.ts:62

What a status factory takes: a result and a message to override the defaults, and any extra fields.

Type Declaration

message?

optional message?: string

result?

optional result?: Result

Type Parameters

Result

Result extends string

Functions​

apiResponse()​

Type Parameters​

Result​

StatusCode​

Others​

Parameters​

result​

statusCode​

others​

Returns​

buffer()​

Parameters​

options?​

Returns​

createBuilder()​

Parameters​

app​

options?​

Returns​

initRpc()​

Parameters​

app​

config​

Returns​

invalidInput()​

Type Parameters​

TPart​

TIssues​

Parameters​

part​

issues​

Returns​

json()​

Parameters​

options?​

Returns​

success()​

Type Parameters​

Others​

Parameters​

others​

Returns​

unexpectedError()​

Returns​

Classes​

Builder​

Type Parameters​

TParams​

Constructors​

Constructor​

Parameters​

config​

Returns​

Methods​

bodySchema()​

Type Parameters​

TParser​

Parameters​

parser​

Returns​

chain()​

Type Parameters​

TLinkInput​

TLinkData​

TLinkResponses​

TLinkDependencyData​

Parameters​

link​

Returns​

expectChain()​

Type Parameters​

TChain​

Returns​

headersSchema()​

Type Parameters​

TParser​

Parameters​

parser​

Returns​

Functions

apiResponse()

Type Parameters

Result

StatusCode

Others

Parameters

result

statusCode

others

Returns

buffer()

Parameters

options?

Returns

createBuilder()

Parameters

app

options?

Returns

initRpc()

Parameters

app

config

Returns

invalidInput()

Type Parameters

TPart

TIssues

Parameters

part

issues

Returns

json()

Parameters

options?

Returns

success()

Type Parameters

Others

Parameters

others

Returns

unexpectedError()

Returns

Classes

Builder

Type Parameters

TParams

Constructors

Constructor

Parameters

config

Returns

Methods

bodySchema()

Type Parameters

TParser

Parameters

parser

Returns

chain()

Type Parameters

TLinkInput

TLinkData

TLinkResponses

TLinkDependencyData

Parameters

link

Returns

expectChain()

Type Parameters

TChain

Returns

headersSchema()

Type Parameters

TParser

Parameters

parser

Returns