@sourceregistry/sveltekit-enhance 1.1.1 → 1.2.0

package/README.md

@@ -1,112 +1,362 @@
+<div align="center">
+
 # @sourceregistry/sveltekit-enhance
 
-[![npm version](https://img.shields.io/npm/v/@sourceregistry/sveltekit-enhance?logo=npm)](https://www.npmjs.com/package/@sourceregistry/sveltekit-enhance)
-[![License](https://img.shields.io/npm/l/@sourceregistry/sveltekit-enhance)](https://github.com/SourceRegistry/sveltekit-enhance/blob/main/LICENSE)
-[![CI](https://github.com/SourceRegistry/sveltekit-enhance/actions/workflows/ci.yml/badge.svg)](https://github.com/SourceRegistry/sveltekit-enhance/actions/workflows/ci.yml)
+**Composable middleware, guards, and form utilities for SvelteKit**
+
+[![npm version](https://img.shields.io/npm/v/@sourceregistry/sveltekit-enhance?style=flat-square&color=f96743)](https://www.npmjs.com/package/@sourceregistry/sveltekit-enhance)
+[![npm downloads](https://img.shields.io/npm/dm/@sourceregistry/sveltekit-enhance?style=flat-square)](https://www.npmjs.com/package/@sourceregistry/sveltekit-enhance)
+[![license](https://img.shields.io/npm/l/@sourceregistry/sveltekit-enhance?style=flat-square)](./LICENSE)
+[![SvelteKit](https://img.shields.io/badge/SvelteKit-%5E2.58-FF3E00?style=flat-square&logo=svelte&logoColor=white)](https://kit.svelte.dev)
+[![issues](https://img.shields.io/github/issues/SourceRegistry/sveltekit-enhance?style=flat-square)](https://github.com/SourceRegistry/sveltekit-enhance/issues)
 
-Production-ready utilities for **SvelteKit server flows**.  
-Use `@sourceregistry/sveltekit-enhance` to build cleaner actions, loads, methods, and hooks with reusable guards for authentication, feature flags, request correlation, and form processing.
+Wrap actions, loads, methods, and hooks with composable enhancers. Stack auth guards, feature flags, request tracing, and form parsing without touching SvelteKit's internals.
 
-## Why teams use this
+[Docs](https://sourceregistry.github.io/sveltekit-enhance/) · [npm](https://www.npmjs.com/package/@sourceregistry/sveltekit-enhance) · [Issues](https://github.com/SourceRegistry/sveltekit-enhance/issues)
 
-- Standardize server-side guard logic across routes.
-- Reduce repetitive request parsing and validation code.
-- Keep middleware-like behavior explicit and composable.
-- Improve observability with correlation IDs on every response.
+</div>
+
+---
 
 ## Installation
 
-```bash
+```sh
 npm install @sourceregistry/sveltekit-enhance
 ```
 
-## Core concepts
+**Peer dependency:** `@sveltejs/kit ^2.58.0`
 
-The package provides an `enhance` wrapper for:
+---
 
-- `enhance.action(...)`
-- `enhance.load(...)`
-- `enhance.method(...)`
-- `enhance.handle(...)`
+## Overview
 
-Each wrapper accepts one or more guard functions and merges their outputs into a typed `guard` object.
+```ts
+import { enhance, Auth, RequestCorrelation, RequestMonitor, Form } from '@sourceregistry/sveltekit-enhance';
 
-## Quick start
+// hooks.server.ts
+export const handle = enhance.handle(
+    async ({ event, resolve }) => resolve(event),
+    RequestCorrelation.attach,
+    RequestMonitor.trace({ logger: myLogger, record: metrics.record }),
+);
 
-```ts
-// src/routes/account/+page.server.ts
-import {enhance} from '@sourceregistry/sveltekit-enhance';
-import {Auth, FeatureFlag, form} from '@sourceregistry/sveltekit-enhance';
+// +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 = {
-  save: enhance.action(
-    async ({request, guard}) => {
-      const data = await request.formData();
-      const email = form.string$(data, 'email');
-
-      return {
-        ok: true,
-        token: guard.token,
-        email
-      };
-    },
+    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`.
+
+```ts
+import { enhance } from '@sourceregistry/sveltekit-enhance';
+
+// src/hooks.server.ts
+export const handle = enhance.handle(
+    async ({ event, resolve, context }) => resolve(event),
+    enhancerA,
+    enhancerB,
+);
+```
+
+### `enhance.load`
+
+Wraps server `load` functions.
+
+```ts
+// +page.server.ts
+export const load = enhance.load(
+    async (event) => ({ user: event.context.user }),
     Auth.Bearer,
-    FeatureFlag.all('PUBLIC_ACCOUNT_EDIT')
-  )
+);
+```
+
+### `enhance.action`
+
+Wraps form actions.
+
+```ts
+// +page.server.ts
+export const actions = {
+    submit: enhance.action(
+        async (event) => success(event.context),
+        Auth.Bearer,
+        Form.schema(myValidator),
+    ),
 };
 ```
 
-## Included helpers
+### `enhance.method`
+
+Wraps `+server.ts` endpoint handlers.
+
+```ts
+// +server.ts
+export const GET = enhance.method(
+    async (event) => new Response(JSON.stringify(event.context)),
+    Auth.Bearer,
+);
+```
+
+### Utilities
+
+```ts
+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`.
+
+---
 
-- `Auth.Bearer`  
-  Validates `Authorization: Bearer <token>` and returns `{ token }`.
+### `Auth`
 
-- `FeatureFlag.all(...flags)` / `FeatureFlag.oneOf(...flags)`  
-  Enforces public environment-based feature flags.
+Extracts and validates `Authorization: Bearer <token>` headers.
 
-- `RequestCorrelation.attach`  
-  Reuses incoming `x-correlation-id` / `x-request-id` or generates one, stores it in `locals`, and appends it to response headers.
+```ts
+import { Auth } from '@sourceregistry/sveltekit-enhance';
 
-- `Devtools.ignore`  
-  Ignores the Chrome DevTools app-specific probe route with a `204` response.
+export const GET = enhance.method(
+    async (event) => new Response(event.context.token),
+    Auth.Bearer,
+);
+```
 
-- `Form` utilities  
-  Typed helpers for strings, numbers, booleans, dates, files, arrays, JSON, selector helpers, and schema-style validation workflows.
+Returns `{ token: string }`. Throws `401` if the header is missing or malformed.
 
-## Example: handle hook with correlation ID
+---
+
+### `Devtools`
+
+Silences Chrome DevTools probe requests (`/.well-known/appspecific/com.chrome.devtools.json`) with a `204 No Content`. Logs in `dev` mode.
 
 ```ts
-// src/hooks.server.ts
-import {enhance, RequestCorrelation} from '@sourceregistry/sveltekit-enhance';
+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.
+
+```ts
+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
+
+```ts
+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.
+
+```ts
+import { RequestMonitor } from '@sourceregistry/sveltekit-enhance';
 
 export const handle = enhance.handle(
-  async ({event, resolve}) => resolve(event),
-  RequestCorrelation.attach
+    myHandler,
+    RequestCorrelation.attach,
+    RequestMonitor.trace({
+        logger: myLogger,        // optional, defaults to console
+        record: metrics.record,  // optional
+    }),
 );
 ```
 
-## API exports
+#### `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
+
+```ts
+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 }`.
+
+---
+
+### `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.
+
+```ts
+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`
+
+```ts
+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
 
 ```ts
-import {
-  enhance,
-  action,
-  load,
-  method,
-  handle,
-  Auth,
-  FeatureFlag,
-  RequestCorrelation,
-  Devtools,
-  Form
-} from '@sourceregistry/sveltekit-enhance';
+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)
 ```
 
-## Compatibility
+#### Standalone functions
+
+All `FormContext` methods are also exported as standalone functions taking `FormData` as the first argument, plus:
+
+```ts
+arrayString(formdata, name, delimiter, mapper?)
+hasOneOf(formdata, names)
+reviver(key, value)   // JSON.parse reviver — coerces strings to typed primitives
+```
+
+---
+
+## Type Reference
+
+```ts
+// Core
+EnhanceInput<CallType>     // event passed to all enhancers
+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 }
+```
 
-- SvelteKit 2+
-- Node.js runtime (matching your SvelteKit adapter/runtime support)
+---
 
 ## License
 
-Apache-2.0
+[Apache-2.0](./LICENSE) © [A.P.A. Slaa](https://github.com/SourceRegistry)

package/dist/helpers/index.d.ts

@@ -3,3 +3,4 @@ export * from './devtools.js';
 export * from './featureflag.js';
 export * from './form.ts';
 export * from './request-correlation.ts';
+export * from './request-monitor.js';

package/dist/helpers/index.js

@@ -3,3 +3,4 @@ export * from './devtools.js';
 export * from './featureflag.js';
 export * from "./form.js";
 export * from "./request-correlation.js";
+export * from './request-monitor.js';

package/dist/helpers/request-monitor.d.ts

@@ -0,0 +1,26 @@
+import type { EnhanceFunction } from "../index.js";
+export type RequestTraceLocals = {
+    trace?: {
+        id: string;
+        started_at: bigint;
+    };
+};
+export type RecordTraceMetricEntry = {
+    method: string;
+    path: string;
+    status: number;
+    durationMs: number;
+};
+export type TraceLogger = {
+    debug: (...args: any[]) => any;
+    info: (...args: any[]) => any;
+    warn: (...args: any[]) => any;
+    error: (...args: any[]) => any;
+};
+export type TraceOptions = {
+    logger?: TraceLogger;
+    record?: (entry: RecordTraceMetricEntry) => any;
+};
+export declare const RequestMonitor: {
+    trace: (options?: TraceOptions) => EnhanceFunction<"handle">;
+};

package/dist/helpers/request-monitor.js

@@ -0,0 +1,72 @@
+const durationMs = (startedAt) => Number(process.hrtime.bigint() - startedAt) / 1_000_000;
+const resolveRoute = (event) => event.route.id ?? event.url.pathname;
+export const RequestMonitor = {
+    trace: (options = {}) => {
+        const { logger = console, record, } = options;
+        return async (event) => {
+            const locals = event.locals;
+            const requestId = locals.requestId ?? "unknown";
+            const route = resolveRoute(event);
+            locals.trace = {
+                id: requestId,
+                started_at: process.hrtime.bigint()
+            };
+            logger.debug("http.request.started", {
+                request_id: requestId,
+                method: event.request.method,
+                route,
+                client_ip: event?.getClientAddress?.()
+            });
+            try {
+                const response = await event.resolve(event.event);
+                if (!response)
+                    return response;
+                const elapsedMs = Number(durationMs(locals.trace.started_at).toFixed(2));
+                record?.({
+                    method: event.request.method,
+                    path: route,
+                    status: response.status,
+                    durationMs: elapsedMs,
+                });
+                const context = {
+                    request_id: requestId,
+                    method: event.request.method,
+                    route,
+                    status: response.status,
+                    duration_ms: elapsedMs,
+                    client_ip: event?.getClientAddress?.()
+                };
+                if (response.status >= 500) {
+                    logger.error("http.request.completed", context);
+                    return response;
+                }
+                if (response.status >= 400) {
+                    logger.warn("http.request.completed", context);
+                    return response;
+                }
+                logger.info("http.request.completed", context);
+                return response;
+            }
+            catch (error) {
+                const elapsedMs = Number(durationMs(locals.trace.started_at).toFixed(2));
+                record?.({
+                    method: event.request.method,
+                    path: route,
+                    status: 500,
+                    durationMs: elapsedMs,
+                });
+                logger.error("http.request.failed", {
+                    request_id: requestId,
+                    method: event.request.method,
+                    route,
+                    duration_ms: elapsedMs,
+                    client_ip: event?.getClientAddress?.(),
+                    error: error instanceof Error
+                        ? { name: error.name, message: error.message }
+                        : { value: String(error) }
+                });
+                throw error;
+            }
+        };
+    }
+};

package/dist/index.d.ts

@@ -18,10 +18,11 @@ export type EnhanceInput<CallType extends EnhanceCallType = EnhanceCallType, Par
     request: Request;
     callType: CallType;
     fetch: typeof fetch;
+    getClientAddress?: () => string;
     get errorHandlers(): EnhanceErrorHandler[];
 } & (CallType extends 'handle' ? {
     get responseHandlers(): EnhanceResponseHandler[];
-    resolve: (event?: RequestEvent) => never;
+    resolve: (event?: RequestEvent, opts?: ResolveOptions) => MaybePromise<Response>;
     readonly event: RequestEvent;
 } : CallType extends 'load' ? {
     parent: ServerLoadEvent<Params, ParentData, RouteId>['parent'];

package/dist/index.js

@@ -118,6 +118,7 @@ handle, ...contexts) => {
 };
 export const handle = (handle, ...contexts) => async (input) => {
     let combined = {};
+    let resolved = false;
     const contextInput = Object.assign(input.event, {
         __errorHandlers__: [],
         __responseHandler__: [],
@@ -129,24 +130,71 @@ export const handle = (handle, ...contexts) => async (input) => {
         get responseHandlers() {
             return this.__responseHandler__;
         },
-        resolve: (event = input.event) => {
-            throw input.resolve(event);
+        resolve: (event = input.event, opts) => {
+            resolved = true;
+            return apply_handle(contexts.length, event, opts);
         },
         get event() {
             return input.event;
         }
     });
-    for (const context of contexts) {
+    const merge_options = (parent_options, options) => {
+        const transformPageChunk = async ({ html, done }) => {
+            if (options?.transformPageChunk) {
+                html = (await options.transformPageChunk({ html, done })) ?? '';
+            }
+            if (parent_options?.transformPageChunk) {
+                html = (await parent_options.transformPageChunk({ html, done })) ?? '';
+            }
+            return html;
+        };
+        return {
+            transformPageChunk,
+            filterSerializedResponseHeaders: parent_options?.filterSerializedResponseHeaders ??
+                options?.filterSerializedResponseHeaders,
+            preload: parent_options?.preload ?? options?.preload
+        };
+    };
+    const apply_handle = async (i, event, parent_options) => {
+        if (i < contexts.length) {
+            const context = contexts[i];
+            const previous_resolve = contextInput.resolve;
+            contextInput.resolve = (next_event = event, options) => {
+                resolved = true;
+                return apply_handle(i + 1, next_event, merge_options(parent_options, options));
+            };
+            try {
+                resolved = false;
+                const result = await context(contextInput);
+                if (result instanceof Response)
+                    return result;
+                if (resolved) {
+                    throw new Error('enhance.handle context called resolve but did not return its response');
+                }
+                combined = Object.assign(combined, result);
+                return apply_handle(i + 1, event, parent_options);
+            }
+            catch (e) {
+                return EnhanceErrorHandle(e, contextInput);
+            }
+            finally {
+                contextInput.resolve = previous_resolve;
+            }
+        }
         try {
-            const result = await context(contextInput);
-            combined = Object.assign(combined, result);
+            return await handle({
+                ...input,
+                context: combined,
+                event,
+                resolve: (next_event, options) => input.resolve(next_event, merge_options(parent_options, options))
+            });
         }
         catch (e) {
             return EnhanceErrorHandle(e, contextInput);
         }
-    }
+    };
     try {
-        const response = await handle(Object.assign(input, { context: combined }));
+        const response = await apply_handle(0, input.event);
         if (contextInput.responseHandlers.length > 0) {
             for (const responseHandler of contextInput.responseHandlers) {
                 await responseHandler({ event: contextInput, response });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sourceregistry/sveltekit-enhance",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "description": "Composable enhance and form utilities for SvelteKit actions, loads, methods, and hooks.",
   "author": "A.P.A. Slaa (a.p.a.slaa@projectsource.nl)",
   "scripts": {
@@ -31,6 +31,10 @@
       "types": "./dist/index.d.ts",
       "svelte": "./dist/index.js",
       "default": "./dist/index.js"
+    },
+    "./helpers": {
+      "types": "./dist/helpers/index.d.ts",
+      "default": "./dist/helpers/index.js"
     }
   },
   "repository": {