@btravstack/htmx-server

---

@btravstack/htmx-server

Classes

HtmxFragmentsPort

Defined in: htmx-server/src/htmx-route.ts:241

Every route a fragment declares, composed into one port — the answerer's own reads it through routes and calls resolvePrincipal itself, which is why requirements and authenticators ride the port rather than staying in this closure.

Extends

• PortInstance<"HtmxFragments", { authenticators: Readonly<Record<string, AuthenticatorService<unknown>>>; principals: Readonly<Record<string, AnyPort>>; routes: readonly FragmentAnswer[]; }>

Constructors

Constructor

new HtmxFragmentsPort(): HtmxFragmentsPort;

Defined in: di/dist/index.d.mts:16

Returns

HtmxFragmentsPort

Inherited from

Port("HtmxFragments")<{
  readonly routes: readonly FragmentAnswer[];
  readonly authenticators: Readonly<Record<string, AuthenticatorService<unknown>>>;
  / One port per scheme, so htmx() can seed the fork it opens for the caller. /
  readonly principals: Readonly<Record<string, AnyPort>>;
}>.constructor

Properties

Property	Modifier	Type	Description	Inherited from	Defined in
[ID]	readonly	"HtmxFragments"	-	Port("HtmxFragments").[ID]	di/dist/index.d.mts:12
[SERVICE]	readonly	object	-	Port("HtmxFragments").[SERVICE]	di/dist/index.d.mts:13
[SERVICE].authenticators	readonly	Readonly<Record<string, AuthenticatorService<unknown>>>	-	-	htmx-server/src/htmx-route.ts:243
[SERVICE].principals	readonly	Readonly<Record<string, AnyPort>>	One port per scheme, so htmx() can seed the fork it opens for the caller.	-	htmx-server/src/htmx-route.ts:245
[SERVICE].routes	readonly	readonly FragmentAnswer[]	-	-	htmx-server/src/htmx-route.ts:242
portId	readonly	"HtmxFragments"	-	Port("HtmxFragments").portId	di/dist/index.d.mts:17

Type Aliases

FragmentAnswer

type FragmentAnswer = object;

Defined in: htmx-server/src/htmx-route.ts:218

What the answerer reads back for one route, principal and body erased to unknown.

Properties

Property	Modifier	Type	Description	Defined in
handle	readonly	(context, params, input) => AsyncResult<Html, never>	-	htmx-server/src/htmx-route.ts:225
input	readonly	FragmentInputSchema | undefined	-	htmx-server/src/htmx-route.ts:221
method	readonly	"GET" | "POST"	-	htmx-server/src/htmx-route.ts:219
path	readonly	string	-	htmx-server/src/htmx-route.ts:220
requirements	readonly	Requirements | undefined	-	htmx-server/src/htmx-route.ts:222
unit	readonly	Readonly<Record<string, AnyPort>>	The declared unit: record, which the answerer resolves out of the fork it opens.	htmx-server/src/htmx-route.ts:224

---

Html

type Html = object;

Defined in: htmx-server/src/html.ts:13

A rendered HTML fragment — the output of html or raw, and nothing else.

An object rather than a string, so that what this package escaped is known by the value rather than by a registry, and so a fragment handler returning a bare template literal is a compile error rather than a stored-XSS bug.

Properties

Property	Modifier	Type	Defined in
[HTML]	readonly	true	htmx-server/src/html.ts:13
value	readonly	string	htmx-server/src/html.ts:13

---

HtmxOptions

type HtmxOptions = object;

Defined in: htmx-server/src/htmx.ts:15

Properties

Property	Modifier	Type	Description	Defined in
login?	readonly	`/${string}`	The login ROUTE — the path the login answerer serves, /auth/login for an oidc()({ prefix: "/auth" }), not the prefix it is mounted under. Set it and a route whose requires resolves Unauthenticated sends the caller there carrying ?return= — 303 Location for a navigating browser, 401 HX-Redirect for a request htmx made. Unset, that route answers a bare 401, and an under-scoped caller answers 403 either way.	htmx-server/src/htmx.ts:26
prefix?	readonly	`/${string}`	Where fragments are mounted. Default /.	htmx-server/src/htmx.ts:17

---

ParamsOf

type ParamsOf<P> = { readonly [K in ParamNames<P>]: string };

Defined in: htmx-server/src/fragments.ts:22

The parameters a path template names. "/orders/:id/row" is { readonly id: string }; a template naming none is an empty record.

Type Parameters

Type Parameter
P extends string

Functions

html()

function html(strings, ...values): Html;

Defined in: htmx-server/src/html.ts:51

An HTML fragment, with every interpolation escaped.

html`<tr id="order-${order.id}"><td>${order.customerName}</td></tr>`

A nested Html is spliced as it is, and an array of them is concatenated — so a list of rows needs no join. Anything else is stringified and escaped.

The escaping is context-blind: it protects element text and a quoted attribute value, and nothing else. An unquoted attribute, an attribute name, a URL scheme (href="${url}" does not vet javascript:), and <script>/<style> contents are the caller's own responsibility.

Parameters

Parameter	Type
strings	TemplateStringsArray
...values	readonly unknown[]

Returns

Html

---

htmx()

function htmx(options?): Provider<HttpHandler, never, HtmxFragmentsPort | HttpConfig | HttpUnit> & object;

Defined in: htmx-server/src/htmx.ts:45

The htmx starter: fragments, as ONE answerer under the HTTP runtime. A request no route claims — outside every path, or on a path whose only route names a different method — resolves unwritten and the runtime answers its own 404.

routes is matched in the ORDER the composition root's piece array gave them, first match wins — and that ordering is a SECURITY property, not only a routing one. A public route declared BEFORE a requires-carrying route whose path can also match the same request answers it itself, and no authentication ever runs: two routes are two port ids, minted from their own method and path, so di has nothing to see collide, and a specificity rule is deliberately not provided (the ordering is the composition root's, on purpose). Declare a route that requires authentication before any public route whose path could also match its requests.

Parameters

Parameter	Type
options	HtmxOptions

Returns

Provider<HttpHandler, never, HtmxFragmentsPort | HttpConfig | HttpUnit> & object

---

raw()

function raw(markup): Html;

Defined in: htmx-server/src/html.ts:63

Markup admitted whole, unescaped. The only way past html's escaping, and a visible act at the call site — which is the point.

Parameters

Parameter	Type
markup	string

Returns

Html