@btravstack/orpc-server

---

@btravstack/orpc-server / index

index

Type Aliases

Authenticators

type Authenticators = Readonly<Record<string, Authenticator<unknown, string, unknown, unknown>>>;

Defined in: http-server/dist/http-runtime-zpGhtEZ8.d.mts:10

The authenticators an application declares, keyed by scheme name.

---

ControllerKeyOf

type ControllerKeyOf<C, P> = PathsOf<C, `${string}.${string}`, true, P>;

Defined in: orpc-server/src/controller.ts:38

Every path into the contract tree — a fragment or a procedure, at any depth — less any key carrying a literal dot. A path is joined and split on ., so a dotted key is indistinguishable from the nesting it would encode — see Unsliceable in orpc.ts for the other half of the refusal.

Type Parameters

Type Parameter	Default type
C	-
P extends string	""

---

ControllerPortOf

type ControllerPortOf<C, K, Schemes> = PortClassOf<`${typeof CONTROLLER_PREFIX}${K}`, Implementation<FragmentAt<C, K>, Schemes>>;

Defined in: orpc-server/src/controller.ts:87

The port one piece targets. Its id carries the contract path, which is what makes two slices claiming one fragment di's duplicate-provider defect rather than a silent merge, and what lets the composing form recover each piece's path by stripping the prefix rather than needing it spelled again.

Type Parameters

Type Parameter	Default type
C extends Record<string, RouterContract>	-
K extends ControllerKeyOf<C>	-
Schemes	never

---

Http

type Http<A, Units> = object;

Defined in: orpc-server/src/define-http.ts:24

Everything an application mints from one call. Held as ONE binding and never destructured: each binding of a destructured member expands to a type mentioning @btravstack/contract's inaccessible unique symbol, which is TS2527 (measured). Held whole, the inferred type collapses to Http<A>, which is nameable — so an application writes no annotation at all.

Type Parameters

Type Parameter	Default type
A extends Authenticators	-
Units extends UnitsOf<A>	Record<never, never>

Properties

Property	Modifier	Type	Description	Defined in
_units?	readonly	Units	Phantom: Units is read by the piece factories' leaf typing, never at runtime.	orpc-server/src/define-http.ts:54
authenticators	readonly	HttpAuth<A>["authenticators"]	The declarations as given, for a hand-rolled composition or a custom sugar that reads the registry off them the way defineHttp does. No in-repo example needs it — HttpModule carries the bound providers on the router.	orpc-server/src/define-http.ts:39
HtmxFragments	readonly	ReturnType<typeof htmxFragmentsFor>	-	orpc-server/src/define-http.ts:29
HtmxGet	readonly	ReturnType<typeof htmxRouteFor>["HtmxGet"]	-	orpc-server/src/define-http.ts:30
HtmxPost	readonly	ReturnType<typeof htmxRouteFor>["HtmxPost"]	-	orpc-server/src/define-http.ts:31
OrpcController	readonly	ReturnType<typeof controllerFor>	-	orpc-server/src/define-http.ts:25
OrpcRouter	readonly	ReturnType<typeof routerFor>	-	orpc-server/src/define-http.ts:26
principals	readonly	HttpAuth<A>["principals"]	One port per scheme carrying that scheme's principal.	orpc-server/src/define-http.ts:43
providers	readonly	HttpAuth<A>["providers"]	Bound scheme providers for answerers composed without HttpModule.	orpc-server/src/define-http.ts:41
units	readonly	<U>() => Http<A, U>	The second step: the SAME object, retyped by the module each kind binds. A kind the authenticators never declared is refused here — the mapped arm demands never for every key outside Kinds<A>, which a real module can never satisfy, and it names that key in the diagnostic.	orpc-server/src/define-http.ts:50

---

HttpModuleOptions

type HttpModuleOptions<Router, Fragments, Units, I, P, X, N> = Omit<OrpcHttpOptions, "unit"> & object & NeedsGate<Imports<I, Units>, Provides<P, Router, Fragments, I>, EnvAnd<N>> & ServesNothingGate<Router, Fragments> & UnboundGate<Units, Router, Fragments> & DivergentGate<Router, Fragments>;

Defined in: orpc-server/src/http-module.ts:288

Type Declaration

Name	Type	Description	Defined in
exports?	X	The application's own exports; HttpRuntime is added, since start resolves it.	orpc-server/src/http-module.ts:354
fragments?	Fragments	The application's htmx fragments — what api.HtmxFragments([…]) returns. Carries its own scheme authenticators the same way router does. Optional: a root may serve router alone. An authenticator provider the two share is deduplicated by reference before it reaches provides, so this module's own array is correct on its own terms rather than relying on di's internal module-tree flattening to absorb the duplicate.	orpc-server/src/http-module.ts:325
fragmentsLogin?	`/${string}`	htmx()'s login — the login route an unauthenticated fragment caller is sent to. Named for the fragment half like fragmentsPrefix is, and for the same reason: it is the htmx answerer's alone, and a bare login here would read as covering the oRPC half, which refuses a caller with UNAUTHORIZED and redirects nothing.	orpc-server/src/http-module.ts:341
fragmentsPrefix?	`/${string}`	Where htmx fragments are mounted, default / — htmx()'s own default. prefix (above, from HttpOptions) stays the oRPC mount, default /rpc: one field cannot carry two independent mount points with two different defaults, so a root serving both protocols gets this second, differently-named option instead of overloading the first.	orpc-server/src/http-module.ts:333
imports?	I	-	orpc-server/src/http-module.ts:351
needs?	N	What this root's OWN providers expect from outside. di's gate is re-stated over the augmented tuples below, so forgetting one is an error at THIS call. Env is added to what this gate counts as declared, so a root composing a scheme that configures itself from the environment never restates it — the same hiding the starter this sugar imports already gets, since it needs Env too and no root has ever named that either.	orpc-server/src/http-module.ts:364
openapi?	[Router] extends [undefined] ? "OPENAPI WITHOUT A ROUTER — openapi serves the router; supply one" : boolean | OpenApiRoutesOptions	Serves the router as OpenAPI routes too, beside RPC — openApiRoutes() under /api by default. cors and compression are this module's unless the record pins its own, field by field; plugins are per answerer, so the RPC answerer's are never shared. Needs a router.	orpc-server/src/http-module.ts:348
provides?	P	-	orpc-server/src/http-module.ts:352
router?	Router	The application's oRPC router — what api.OrpcRouter(contract)(…) returns. It carries the scheme authenticators defineHttp bound, which is how they reach provides without an application listing them. Optional: a root may serve fragments alone.	orpc-server/src/http-module.ts:316
unit?	Units & UnitGate<Units, Router, Fragments>	The unit module each KIND binds — anonymous for a request no leaf asked to authenticate, else the scheme that resolved the caller. Every bound module's own unmet needs join this root's, less the principal the fork seeds: a composition that binds one owes the composition root the same way any other needs does. The kinds are gated against the answerers: the ones units<…>() declared, carried by the router or the fragments alike, or — for a plain defineHttp() api — anonymous and every scheme the answerers serve. Under units<…>(), every declared kind the answerers serve must be bound.	orpc-server/src/http-module.ts:309

Type Parameters

Type Parameter
Router extends AnyRouterProvider | undefined
Fragments extends AnyFragmentsProvider | undefined
Units extends Readonly<Record<string, AnyUnitModule>> | undefined
I extends readonly AnyModule[]
P extends readonly AnyProvider[]
X extends readonly Exportable<Imports<I, Units>, Provides<P, Router, Fragments, I>>[]
N extends readonly AnyPort[]

---

OrpcHttpOptions

type OrpcHttpOptions = Omit<HttpOptions, "cors" | "compression"> & OrpcOptions;

Defined in: orpc-server/src/http.ts:17

---

OrpcOptions

type OrpcOptions = object;

Defined in: orpc-server/src/orpc.ts:73

Properties

Property	Modifier	Type	Description	Defined in
bodyLimit?	readonly	number | false	Pins HttpConfig.bodyLimit instead of reading HTTP_BODY_LIMIT (default DEFAULT_BODY_LIMIT) — the largest request body a procedure will read, in bytes; false pins the unbounded 0. Over the limit is oRPC's PAYLOAD_TOO_LARGE, decided on content-length when one is sent and while streaming otherwise.	orpc-server/src/orpc.ts:94
compression?	readonly	| boolean | ResponseCompressionHandlerPluginOptions<DefaultInitialContext>	Response compression, off unless this or HTTP_COMPRESSION turns it on. true takes oRPC's own defaults (gzip then deflate, above 1 KB); a record is ResponseCompressionHandlerPluginOptions verbatim and turns it on. Request DEcompression is not this option — it is RequestCompressionHandlerPlugin through plugins.	orpc-server/src/orpc.ts:102
cors?	readonly	boolean | CORSHandlerPluginOptions<DefaultInitialContext>	The CORS policy, off unless this or HTTP_CORS_ORIGIN turns it on. The origin is decided per field, like every other pin: a record naming origin wins, HTTP_CORS_ORIGIN next, and oRPC's own default — reflect the request's origin — last. So cors: true turns CORS on and still takes the deployment's HTTP_CORS_ORIGIN when one is set; cors: false is off whatever the deployment says. Everything else in a CORSHandlerPluginOptions record is verbatim.	orpc-server/src/orpc.ts:86
csrf?	readonly	boolean	Cross-site state change, refused before dispatch. Defaults to on when any composed scheme reads a cookie — sessionAuthenticator is the one that ships — and off otherwise, since a caller presenting a header credential is not a CSRF target. false turns it off whatever is composed; true turns it on whatever is composed. Not a config field: a deployment that can silently turn it off is the footgun securityHeaders is not allowed to be either.	orpc-server/src/orpc.ts:113
plugins?	readonly	readonly NodeHttpHandlerPlugin<DefaultInitialContext>[]	Any other oRPC handler plugin. Transport policy configuring the transport; not a middleware slot for application logic, which the package still declines.	orpc-server/src/orpc.ts:119
prefix?	readonly	`/${string}`	Where the RPC endpoint is mounted. Default /rpc.	orpc-server/src/orpc.ts:75

---

SchemesFrom

type SchemesFrom<A> = { readonly [K in keyof A]: A[K]["principal"] };

Defined in: http-server/dist/http-runtime-zpGhtEZ8.d.mts:11

Type Parameters

Type Parameter
A extends Authenticators

Functions

defineHttp()

function defineHttp<A>(options?): Http<A>;

Defined in: orpc-server/src/define-http.ts:74

The one door to the marker-typed entities. Declaring a scheme and implementing it are the same act, so a scheme without an authenticator is not a state this can reach — there is no coverage gate because there is nothing to forget.

export const api = defineHttp({ authenticators: { user: userAuth } });
export const api = defineHttp();   // a public API: `principal` is `never`

The default registry is Record<never, never>, not Record<string, never>: an index signature over string would make EVERY scheme's port look available to di, so a marked contract composed under defineHttp() would type-check and then fail at build. Empty, the port stays unmet and the composition is refused.

Type Parameters

Type Parameter	Default type
A extends Readonly<Record<string, Authenticator<unknown, string, unknown, unknown>>>	Record<never, never>

Parameters

Parameter	Type
options?	{ authenticators: A; }
options.authenticators?	A

Returns

Http<A>

---

http()

function http<Units>(options?): Module<HttpRuntime | HttpConfig | HttpHandler | Observers, ConfigInvalid, HttpServerEnv | OrpcRouterPort | UnitsNeedsOf<Units>>;

Defined in: orpc-server/src/http.ts:20

One oRPC answerer over the shared HTTP listener.

Type Parameters

Type Parameter	Default type
Units extends Readonly<Record<string, AnyUnitModule>> | undefined	undefined

Parameters

Parameter	Type
options	Omit<OrpcHttpOptions, "unit"> & object

Returns

Module<HttpRuntime | HttpConfig | HttpHandler | Observers, ConfigInvalid, HttpServerEnv | OrpcRouterPort | UnitsNeedsOf<Units>>

---

HttpModule()

function HttpModule<Name>(name): <Router, Fragments, Units, I, P, X, N>(options) => Module<ResolvedExports<readonly [typeof HttpRuntime, typeof HttpHandler, 
  | Logger extends Available<readonly [I, HttpStarter<Units>], Provides<P, Router, Fragments, I>> ? typeof Logger : never
  | HealthChecks extends Available<readonly [I, HttpStarter<Units>], Provides<P, Router, Fragments, I>> ? typeof HealthChecks : never, X]>, 
  | ErrOf<
  | [Router] extends [undefined] ? never : 
  | Provider<HttpHandler, never, HttpConfig | Observers | CookieSchemes | PortInstance<..., ...>> & object
  | Exclude<Router, undefined>
  | [Fragments] extends [undefined] ? never : 
  | Provider<HttpHandler, never, HttpConfig | HtmxFragmentsPort | HttpUnit> & object
  | Exclude<Fragments, undefined>
  | AuthOf<Router>
  | AuthOf<Fragments>
  | PiecesOf<Router, I>
  | PiecesOf<Fragments, I>
  | P[number]>
  | ErrOfModule<readonly [I, HttpStarter<Units>][number]>, 
  | Exclude<NeedOf<
  | [Router] extends [undefined] ? never : 
  | Provider<HttpHandler, never, ... | ... | ... | ...> & object
  | Exclude<Router, undefined>
  | [Fragments] extends [undefined] ? never : 
  | Provider<HttpHandler, never, ... | ... | ...> & object
  | Exclude<Fragments, undefined>
  | AuthOf<Router>
  | AuthOf<Fragments>
  | PiecesOf<Router, I>
  | PiecesOf<Fragments, I>
  | P[number]>, Available<readonly [I, HttpStarter<Units>], Provides<P, Router, Fragments, I>>>
  | Exclude<NeedsOfModule<readonly [I, HttpStarter<Units>][number]>, Available<readonly [I, HttpStarter<Units>], Provides<P, Router, Fragments, I>>>>;

Defined in: orpc-server/src/http-module.ts:399

Module(name)({...}) for an HTTP deployment: everything a di module takes, plus a router, fragments, or both. The sugar imports the socket half (httpServer), provides whichever answerer(s) the options name and exports HttpRuntime, handing back exactly the module Module(...) would have declared over the augmented tuples.

export const OrderApi = HttpModule("OrderApi")({
  router: orderRouter,
  imports: [OrderApplicationModule, OrderPersistenceModule],
  exports: [Logger],
});
await runMain(OrderApi);

A fragments-only root drops router and supplies fragments instead; a root serving both supplies both, and prefix/fragmentsPrefix mount them independently. Supplying neither is refused at this call.

Type Parameters

Type Parameter
Name extends string

Parameters

Parameter	Type
name	Name

Returns

<Router, Fragments, Units, I, P, X, N>(options) => Module<ResolvedExports<readonly [typeof HttpRuntime, typeof HttpHandler, | Logger extends Available<readonly [I, HttpStarter<Units>], Provides<P, Router, Fragments, I>> ? typeof Logger : never | HealthChecks extends Available<readonly [I, HttpStarter<Units>], Provides<P, Router, Fragments, I>> ? typeof HealthChecks : never, X]>, | ErrOf< | [Router] extends [undefined] ? never : | Provider<HttpHandler, never, HttpConfig | Observers | CookieSchemes | PortInstance<..., ...>> & object | Exclude<Router, undefined> | [Fragments] extends [undefined] ? never : | Provider<HttpHandler, never, HttpConfig | HtmxFragmentsPort | HttpUnit> & object | Exclude<Fragments, undefined> | AuthOf<Router> | AuthOf<Fragments> | PiecesOf<Router, I> | PiecesOf<Fragments, I> | P[number]> | ErrOfModule<readonly [I, HttpStarter<Units>][number]>, | Exclude<NeedOf< | [Router] extends [undefined] ? never : | Provider<HttpHandler, never, ... | ... | ... | ...> & object | Exclude<Router, undefined> | [Fragments] extends [undefined] ? never : | Provider<HttpHandler, never, ... | ... | ...> & object | Exclude<Fragments, undefined> | AuthOf<Router> | AuthOf<Fragments> | PiecesOf<Router, I> | PiecesOf<Fragments, I> | P[number]>, Available<readonly [I, HttpStarter<Units>], Provides<P, Router, Fragments, I>>> | Exclude<NeedsOfModule<readonly [I, HttpStarter<Units>][number]>, Available<readonly [I, HttpStarter<Units>], Provides<P, Router, Fragments, I>>>>

---

orpc()

function orpc(options?): Provider<HttpHandler, never, 
  | HttpConfig
  | Observers
  | CookieSchemes
  | PortInstance<"OrpcRouter", Router<Record<never, never>>>> & object;

Defined in: orpc-server/src/orpc.ts:221

The oRPC starter: a provider of HttpHandler built from the router port, mounted under prefix. A request oRPC does not match resolves unwritten and the runtime answers its 404. Nothing here maps a Result to a status.

Parameters

Parameter	Type
options	OrpcOptions

Returns

Provider<HttpHandler, never, | HttpConfig | Observers | CookieSchemes | PortInstance<"OrpcRouter", Router<Record<never, never>>>> & object