sveltekit-enhance

@sourceregistry/sveltekit-enhance

Composable middleware, guards, and form utilities for SvelteKit

Wrap actions, loads, methods, and hooks with composable enhancers. Stack auth guards, feature flags, request tracing, and form parsing without touching SvelteKit's internals.

Docs · npm · Issues

Installation

npm install @sourceregistry/sveltekit-enhance

Peer dependency: @sveltejs/kit ^2.58.0

Overview

import { enhance, Auth, RequestCorrelation, RequestMonitor, Form } from '@sourceregistry/sveltekit-enhance';

// hooks.server.ts
export const handle = enhance.handle(
    async ({ event, resolve }) => resolve(event),
    RequestCorrelation.attach,
    RequestMonitor.trace({ logger: myLogger, record: metrics.record }),
);

// +server.ts
export const POST = enhance.method(
    async (event) => new Response(JSON.stringify(event.context)),
    Auth.Bearer,
    FeatureFlag.all('PUBLIC_API_ENABLED'),
);

// +page.server.ts
export const actions = {
    default: enhance.action(
        async (event) => {
            const name = event.context.form.string$('name');
            return success({ name });
        },
        Form.schema(myValidator),
    ),
};

Core API

Import from @sourceregistry/sveltekit-enhance.

`enhance.handle`

Wraps SvelteKit's handle hook. Enhancers run left-to-right before the handler; their return values are merged into context.

import { enhance } from '@sourceregistry/sveltekit-enhance';

// src/hooks.server.ts
export const handle = enhance.handle(
    async ({ event, resolve, context }) => resolve(event),
    enhancerA,
    enhancerB,
);

SSE / streaming responses

enhance.handle automatically detects Server-Sent Events and other streaming requests (via Accept: text/event-stream) and bypasses the main handler entirely — going straight to SvelteKit's resolve. This prevents the handler from blocking indefinitely on await resolve(event), which never settles for a streaming response.

Consequences:

The main handler does not run for SSE requests — it cannot inspect or modify the response headers.
responseHandlers (added by enhancers via contextInput.responseHandlers.push(...)) are also skipped for responses with Content-Type: text/event-stream.
Enhancers (the variadic context arguments) still run normally — they can set locals, authenticate the request, or short-circuit with an error response.

// This handler is skipped for SSE requests — no change needed on your end.
export const handle = enhance.handle(
    async ({ event, resolve }) => {
        const response = await resolve(event); // not called for SSE
        response.headers.set('x-custom', 'value');
        return response;
    },
    Auth.Bearer,       // still runs — can reject unauthorized SSE requests
    SessionGuard.hook, // still runs
);

If you need to set response headers on SSE routes, do it in the route handler itself (e.g. +server.ts) rather than in the enhance.handle main handler.

`enhance.load`

Wraps server load functions.

// +page.server.ts
export const load = enhance.load(
    async (event) => ({ user: event.context.user }),
    Auth.Bearer,
);

`enhance.action`

Wraps form actions.

// +page.server.ts
export const actions = {
    submit: enhance.action(
        async (event) => success(event.context),
        Auth.Bearer,
        Form.schema(myValidator),
    ),
};

`enhance.method`

Wraps +server.ts endpoint handlers.

// +server.ts
export const GET = enhance.method(
    async (event) => new Response(JSON.stringify(event.context)),
    Auth.Bearer,
);

Utilities

import { fail, error, success, not_good } from '@sourceregistry/sveltekit-enhance';

fail(400, { message: 'bad input' });   // throws ActionFailure — use inside actions
error(404, { message: 'not found' });  // throws HttpError
success({ id: 1 });                    // typed identity helper
not_good(input, 403);                  // delegates to fail or error based on callType

Helpers

All helpers are available from @sourceregistry/sveltekit-enhance or @sourceregistry/sveltekit-enhance/helpers.

`CSRF`

Blocks cross-site form submissions on mutating methods (POST, PUT, PATCH, DELETE) with form content types. Checks the Origin header against the request origin. Absent Origin (server-side fetch, curl) is allowed through. Returns 403 — JSON body when Accept: application/json, SvelteKit error() otherwise.

import { CSRF, CSRFChecker } from '@sourceregistry/sveltekit-enhance';

export const handle = enhance.handle(
    myHandler,
    CSRF.inspect(
        CSRFChecker.list('/api/webhooks/stripe'),  // bypass paths
        myLogger,                                   // optional, defaults to console
    ),
);

Built-in bypass checkers:

Checker	Description
`CSRFChecker.list(...paths)`	Exact pathname match
`CSRFChecker.regex(...patterns)`	RegExp match against pathname

Custom checker — any (input: EnhanceInput) => MaybePromise<boolean>:

// true = bypass CSRF check
CSRF.inspect((input) => input.url.pathname.startsWith('/api/public'))

Returns { csrf_valid: true } on pass. Locals set: none.

`Auth`

Extracts and validates Authorization: Bearer <token> headers.

import { Auth } from '@sourceregistry/sveltekit-enhance';

export const GET = enhance.method(
    async (event) => new Response(event.context.token),
    Auth.Bearer,
);

Returns { token: string }. Throws 401 if the header is missing or malformed.

`Devtools`

Silences Chrome DevTools probe requests (/.well-known/appspecific/com.chrome.devtools.json) with a 204 No Content. Logs in dev mode.

import { Devtools } from '@sourceregistry/sveltekit-enhance';

export const handle = enhance.handle(myHandler, Devtools.ignore);

`FeatureFlag`

Guards routes behind SvelteKit public env vars ($env/dynamic/public). Always passes in dev mode.

import { FeatureFlag } from '@sourceregistry/sveltekit-enhance';

// All listed flags must be enabled
FeatureFlag.all('PUBLIC_FEATURE_A', 'PUBLIC_FEATURE_B')

// At least one flag must be enabled
FeatureFlag.oneOf('PUBLIC_FEATURE_A', 'PUBLIC_FEATURE_B')

Truthy values: true, TRUE, on, ON, 1. Returns { flags } or throws 503 Feature not enabled.

`RequestCorrelation`

Propagates a correlation ID across the request/response cycle.

Reads x-correlation-id or x-request-id from incoming headers
Validates: max 128 chars, pattern [A-Za-z0-9._:-]+
Generates a UUID v4 if absent
Echoes the ID back via x-correlation-id response header

import { RequestCorrelation } from '@sourceregistry/sveltekit-enhance';

export const handle = enhance.handle(myHandler, RequestCorrelation.attach);

Local	Type	Description
`correlation_id`	`string`	Resolved correlation ID
`request_started_at`	`number`	`Date.now()` at attach time

`RequestMonitor`

Structured HTTP request logging and optional metrics collection. Instruments the full lifecycle: start, completion (log level by status), and unhandled errors — all with elapsed duration.

import { RequestMonitor } from '@sourceregistry/sveltekit-enhance';

export const handle = enhance.handle(
    myHandler,
    RequestCorrelation.attach,
    RequestMonitor.trace({
        logger: myLogger,        // optional, defaults to console
        record: metrics.record,  // optional
    }),
);

`TraceOptions`

Option	Type	Default	Description
`logger`	`TraceLogger`	`console`	Must implement `debug`, `info`, `warn`, `error`
`record`	`(entry: RecordTraceMetricEntry) => any`	—	Called after every request

Log events

Event	Level	Condition
`http.request.started`	`debug`	Before resolve
`http.request.completed`	`info`	`status < 400`
`http.request.completed`	`warn`	`status 4xx`
`http.request.completed`	`error`	`status 5xx`
`http.request.failed`	`error`	Unhandled throw

Types

type RecordTraceMetricEntry = { method: string; path: string; status: number; durationMs: number }
type TraceLogger            = { debug(...args: any[]): any; info(...args: any[]): any; warn(...args: any[]): any; error(...args: any[]): any }

Locals set: trace: { id: string; started_at: bigint }.

`CacheControl`

Sets Cache-Control response headers. Provides named directive helpers so policies are readable at a glance, and two enhancers — one for broad handle-level rules, one for per-route load-level overrides.

import { CacheControl, directive } from '@sourceregistry/sveltekit-enhance';

// hooks.server.ts — apply rules globally
export const handle = enhance.handle(
    myHandler,
    CacheControl.global(
        { match: /^\/api\//, directive: directive.noStore },
        { match: /^\/blog\//, directive: directive.public(300, 60) },
    ),
);

// +page.server.ts — override for a specific route
export const load = enhance.load(
    async (event) => event.context,
    CacheControl.local(directive.public(3600)),
);

directive is also exported as a standalone named export — shorthand for CacheControl.directive when you only need to reference directives without the enhancers.

`CacheControl.global(...rules)`

Handle-level enhancer. Iterates the rule list and sets Cache-Control via setHeaders() for the first matching pathname. When no rule matches, the header is left unset.

Param	Type	Description
`...rules`	`CacheRule[]`	Ordered list of `{ match, directive }` pairs. First match wins.

Runs in handle context only. Add a catch-all rule (match: () => true) if you want a guaranteed fallback.

`CacheControl.local(directive)`

Load-level enhancer. Sets Cache-Control for the current route via setHeaders(). Use this to override a global rule for a specific page.

Param	Type	Description
`directive`	`CacheDirective`	The directive string to apply.

`CacheControl.directive`

Named helpers that produce correctly-formatted Cache-Control strings.

Helper	Directive	When to use
`noStore`	`no-store`	Sensitive data — never cache (user dashboards, auth responses)
`noCache`	`no-cache`	Changes frequently but supports conditional GETs (ETags / Last-Modified)
`noCacheNoStore`	`no-cache, no-store, must-revalidate`	Belt-and-suspenders; also covers legacy HTTP/1.0 proxies
`public(maxAge, swr?)`	`public, max-age=N[, stale-while-revalidate=N]`	Publicly cacheable content; `swr` serves stale while revalidating in the background
`private(maxAge)`	`private, max-age=N`	Personalised content — browser cache only, not CDNs or shared proxies

`Form`

Typed, ergonomic FormData extraction. Works standalone or as an enhancer.

As an enhancer — `Form.schema`

Validates and deserializes form data via a Validator<T> before the handler runs.

import { Form, enhance, success } from '@sourceregistry/sveltekit-enhance';

export const actions = {
    default: enhance.action(
        async (event) => success(event.context.form.result),
        Form.schema(myValidator),
    ),
};

Standalone — `Form.handle`

import { Form } from '@sourceregistry/sveltekit-enhance';

await Form.handle(request, ({ form }) => {
    const name = form.string$('name');
    const age  = form.number('age');
    return { name, age };
});

Field extractors

Optional variants return undefined when the field is absent. Required variants ($ suffix) throw fail(400).

Method	Returns	Notes
`string(name)` / `string$(name)`	`string \| null \| undefined`
`pattern$(name, pattern)`	`string`	`RegExp` or pattern string
`number(name)` / `number$(name)`	`number \| undefined`
`boolean(name)` / `boolean$(name)`	`boolean \| undefined`	Accepts `true/false`, `1/0`, `on/off`
`date(name, parser?)` / `date$(name, parser)`	`Date \| undefined`	Custom parser supported
`json<T>(name, transformer?)` / `json$(name)`	`T \| undefined`	Optional transform fn
`jsond(options)`	`any`	All FormData → nested object via dot-notation keys
`file(name)` / `file$(name)`	`File \| null \| undefined`
`files(name)`	`File[]`	Non-empty, named files only
`fileRecord(prefix, removePrefix?)`	`Record<string, File[]>`	Groups files by key prefix
`array<T>(name, mapper?)` / `array$(name)`	`T[] \| undefined`
`enum(name, Enum)` / `enum$(name, Enum)`	`keyof E \| undefined`
`record(options?)`	`Record<string, any>`	All entries; optional `filter` / `transformer`
`validate(schema, options?)`	`T`	Runs `Validator<T>`, throws `fail(400)` on failure

Conditional helpers

form.onlyIf(condition, trueVal, falseVal?)
form.onlyIfPresent(key, (entry) => ..., fallback?)
form.onlyIfArrayPresent(key, (entries) => ..., fallback)
form.selector({ fieldName: (entry, key) => ..., $default?, $error? })
form.selector$({ ... })    // throws fail(400) if no case matches
form.basedOn(val, processor)
form.process(name, parser, processor)

Standalone functions

All FormContext methods are also exported as standalone functions taking FormData as the first argument, plus:

arrayString(formdata, name, delimiter, mapper?)
hasOneOf(formdata, names)
reviver(key, value)   // JSON.parse reviver — coerces strings to typed primitives

Type Reference

// Core
EnhanceInput<CallType>     // event passed to all enhancers — includes all RequestEvent properties:
                           //   cookies, fetch, locals, params, request, route, url
                           //   setHeaders(headers)      — set response headers (no set-cookie; use cookies API)
                           //   isDataRequest            — true when client fetches +page/layout.server.js data
                           //   isSubRequest             — true for same-origin server-side fetch (no HTTP round-trip)
                           //   isRemoteRequest          — true when request comes from a remote function
                           //   tracing                  — OpenTelemetry spans (no-ops when tracing disabled; since SK 2.31)
                           //   + handle: resolve, event, responseHandlers
                           //   + load:   parent, depends, untrack
EnhanceFunction<CallType>  // (event: EnhanceInput) => MaybePromise<object | Response>
EnhanceHandle              // final handle fn — ({ event, resolve, context }) => MaybePromise<Response>
EnhanceLoad                // final load fn
EnhanceAction              // final action fn
EnhanceMethod              // final method fn
MaybePromise<T>            // T | Promise<T>

// Form
Validator<T>               // (value: unknown, path?: ValidationPath) => ValidationResult<T>
ValidationResult<T>        // { success: true; data: T } | { success: false; errors: ValidationIssue[] }
ValidationIssue            // { path: string; message: string; code?: string }
FormContext                // fluent API returned by Form.enhance / Form.handle
InferValidator<V>          // infers T from Validator<T>

// Helpers
TraceLogger                // { debug, info, warn, error }
TraceOptions               // { logger?: TraceLogger; record?: (entry) => any }
RecordTraceMetricEntry     // { method: string; path: string; status: number; durationMs: number }
RequestTraceLocals         // { trace?: { id: string; started_at: bigint } }
RequestCorrelationLocals   // { correlation_id?: string; request_started_at?: number }
CSRFChecker                // { regex(...patterns): checker; list(...paths): checker }
CacheDirective             // union of valid Cache-Control strings (+ open string & {})
CacheRule                  // { match: RegExp | ((pathname) => boolean); directive: CacheDirective }

sveltekit-enhance

@sourceregistry/sveltekit-enhance

Installation

Overview

Core API

`enhance.handle`

SSE / streaming responses

`enhance.load`

`enhance.action`

`enhance.method`

Utilities

Helpers

`CSRF`

`Auth`

`Devtools`

`FeatureFlag`

`RequestCorrelation`

`RequestMonitor`

`TraceOptions`

Log events

Types

`CacheControl`

`CacheControl.global(...rules)`

`CacheControl.local(directive)`

`CacheControl.directive`

`Form`

As an enhancer — `Form.schema`

Standalone — `Form.handle`

Field extractors

Conditional helpers

Standalone functions

Type Reference

License

Settings

On This Page

sveltekit-enhance

@sourceregistry/sveltekit-enhance

Installation

Overview

Core API

enhance.handle

SSE / streaming responses

enhance.load

enhance.action

enhance.method

Utilities

Helpers

CSRF

Auth

Devtools

FeatureFlag

RequestCorrelation

RequestMonitor

TraceOptions

Log events

Types

CacheControl

CacheControl.global(...rules)

CacheControl.local(directive)

CacheControl.directive

Form

As an enhancer — Form.schema

Standalone — Form.handle

Field extractors

Conditional helpers

Standalone functions

Type Reference

License

Settings

On This Page

`enhance.handle`

`enhance.load`

`enhance.action`

`enhance.method`

`CSRF`

`Auth`

`Devtools`

`FeatureFlag`

`RequestCorrelation`

`RequestMonitor`

`TraceOptions`

`CacheControl`

`CacheControl.global(...rules)`

`CacheControl.local(directive)`

`CacheControl.directive`

`Form`

As an enhancer — `Form.schema`

Standalone — `Form.handle`