@sourceregistry/sveltekit-enhance 1.3.3 → 1.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -309,6 +309,63 @@ Locals set: `trace: { id: string; started_at: bigint }`.
309
309
 
310
310
  ---
311
311
 
312
+ ### `CacheControl`
313
+
314
+ 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.
315
+
316
+ ```ts
317
+ import { CacheControl, directive } from '@sourceregistry/sveltekit-enhance';
318
+
319
+ // hooks.server.ts — apply rules globally
320
+ export const handle = enhance.handle(
321
+ myHandler,
322
+ CacheControl.global(
323
+ { match: /^\/api\//, directive: directive.noStore },
324
+ { match: /^\/blog\//, directive: directive.public(300, 60) },
325
+ ),
326
+ );
327
+
328
+ // +page.server.ts — override for a specific route
329
+ export const load = enhance.load(
330
+ async (event) => event.context,
331
+ CacheControl.local(directive.public(3600)),
332
+ );
333
+ ```
334
+
335
+ `directive` is also exported as a standalone named export — shorthand for `CacheControl.directive` when you only need to reference directives without the enhancers.
336
+
337
+ #### `CacheControl.global(...rules)`
338
+
339
+ 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.
340
+
341
+ | Param | Type | Description |
342
+ |-------|------|-------------|
343
+ | `...rules` | `CacheRule[]` | Ordered list of `{ match, directive }` pairs. First match wins. |
344
+
345
+ > Runs in `handle` context only. Add a catch-all rule (`match: () => true`) if you want a guaranteed fallback.
346
+
347
+ #### `CacheControl.local(directive)`
348
+
349
+ Load-level enhancer. Sets `Cache-Control` for the current route via `setHeaders()`. Use this to override a global rule for a specific page.
350
+
351
+ | Param | Type | Description |
352
+ |-------|------|-------------|
353
+ | `directive` | `CacheDirective` | The directive string to apply. |
354
+
355
+ #### `CacheControl.directive`
356
+
357
+ Named helpers that produce correctly-formatted `Cache-Control` strings.
358
+
359
+ | Helper | Directive | When to use |
360
+ |--------|-----------|-------------|
361
+ | `noStore` | `no-store` | Sensitive data — never cache (user dashboards, auth responses) |
362
+ | `noCache` | `no-cache` | Changes frequently but supports conditional GETs (ETags / Last-Modified) |
363
+ | `noCacheNoStore` | `no-cache, no-store, must-revalidate` | Belt-and-suspenders; also covers legacy HTTP/1.0 proxies |
364
+ | `public(maxAge, swr?)` | `public, max-age=N[, stale-while-revalidate=N]` | Publicly cacheable content; `swr` serves stale while revalidating in the background |
365
+ | `private(maxAge)` | `private, max-age=N` | Personalised content — browser cache only, not CDNs or shared proxies |
366
+
367
+ ---
368
+
312
369
  ### `Form`
313
370
 
314
371
  Typed, ergonomic FormData extraction. Works standalone or as an enhancer.
@@ -389,7 +446,15 @@ reviver(key, value) // JSON.parse reviver — coerces strings to typed primiti
389
446
 
390
447
  ```ts
391
448
  // Core
392
- EnhanceInput<CallType> // event passed to all enhancers
449
+ EnhanceInput<CallType> // event passed to all enhancers — includes all RequestEvent properties:
450
+ // cookies, fetch, locals, params, request, route, url
451
+ // setHeaders(headers) — set response headers (no set-cookie; use cookies API)
452
+ // isDataRequest — true when client fetches +page/layout.server.js data
453
+ // isSubRequest — true for same-origin server-side fetch (no HTTP round-trip)
454
+ // isRemoteRequest — true when request comes from a remote function
455
+ // tracing — OpenTelemetry spans (no-ops when tracing disabled; since SK 2.31)
456
+ // + handle: resolve, event, responseHandlers
457
+ // + load: parent, depends, untrack
393
458
  EnhanceFunction<CallType> // (event: EnhanceInput) => MaybePromise<object | Response>
394
459
  EnhanceHandle // final handle fn — ({ event, resolve, context }) => MaybePromise<Response>
395
460
  EnhanceLoad // final load fn
@@ -411,6 +476,8 @@ RecordTraceMetricEntry // { method: string; path: string; status: number; du
411
476
  RequestTraceLocals // { trace?: { id: string; started_at: bigint } }
412
477
  RequestCorrelationLocals // { correlation_id?: string; request_started_at?: number }
413
478
  CSRFChecker // { regex(...patterns): checker; list(...paths): checker }
479
+ CacheDirective // union of valid Cache-Control strings (+ open string & {})
480
+ CacheRule // { match: RegExp | ((pathname) => boolean); directive: CacheDirective }
414
481
  ```
415
482
 
416
483
  ---
@@ -0,0 +1,90 @@
1
+ import type { EnhanceFunction, EnhanceInput } from '../index.js';
2
+ export type CacheDirective = 'no-store' | 'no-cache' | 'no-cache, no-store, must-revalidate' | `public, max-age=${number}` | `private, max-age=${number}` | `public, max-age=${number}, stale-while-revalidate=${number}` | (string & {});
3
+ export type CacheRule = {
4
+ match: RegExp | ((pathname: string) => boolean);
5
+ directive: CacheDirective;
6
+ };
7
+ export declare const CacheControl: {
8
+ directive: {
9
+ /**
10
+ * `no-store` — Response must never be stored. Bypasses all caches (browser, CDN, proxy).
11
+ * Use for sensitive data (user dashboards, auth responses, banking pages).
12
+ */
13
+ noStore: CacheDirective;
14
+ /**
15
+ * `no-cache` — Response may be stored but must be revalidated with the origin before reuse.
16
+ * Useful when content changes frequently but you still want conditional GET support (ETags / Last-Modified).
17
+ */
18
+ noCache: CacheDirective;
19
+ /**
20
+ * `no-cache, no-store, must-revalidate` — Belt-and-suspenders: disables storage and forces
21
+ * revalidation. Maximally prevents caching across all cache layers including legacy HTTP/1.0 proxies.
22
+ */
23
+ noCacheNoStore: CacheDirective;
24
+ /**
25
+ * `public, max-age=<seconds>` — Cacheable by any cache (CDN, proxy, browser).
26
+ * Optionally add `stale-while-revalidate` to serve stale content while revalidating in the background.
27
+ *
28
+ * @param maxAge - Seconds the response is considered fresh.
29
+ * @param staleWhileRevalidate - Seconds past max-age where stale content may still be served while a fresh fetch happens in the background.
30
+ */
31
+ public: (maxAge: number, staleWhileRevalidate?: number) => CacheDirective;
32
+ /**
33
+ * `private, max-age=<seconds>` — Cacheable only by the end-user's browser, not by shared caches (CDNs, proxies).
34
+ * Use for personalised content that must not be stored on shared infrastructure.
35
+ *
36
+ * @param maxAge - Seconds the response is considered fresh in the browser cache.
37
+ */
38
+ private: (maxAge: number) => CacheDirective;
39
+ };
40
+ /**
41
+ * Handle-level enforcer. Matches pathname against rules and sets Cache-Control
42
+ * via setHeaders(). Only sets the header when a rule matches.
43
+ *
44
+ * Usage:
45
+ * export const handle = enhance(handler, CacheControl.global(
46
+ * { match: /^\/api\//, directive: CacheControl.noStore },
47
+ * { match: /^\/blog\//, directive: CacheControl.public(300) },
48
+ * ));
49
+ */
50
+ global: (...rules: CacheRule[]) => (input: EnhanceInput<"handle">) => void;
51
+ /**
52
+ * Load-level policy. Sets Cache-Control for this specific route via setHeaders().
53
+ *
54
+ * Usage:
55
+ * export const load = load(fn, CacheControl.local(CacheControl.public(300)));
56
+ */
57
+ local: (directive: CacheDirective) => EnhanceFunction<"load">;
58
+ };
59
+ export declare const directive: {
60
+ /**
61
+ * `no-store` — Response must never be stored. Bypasses all caches (browser, CDN, proxy).
62
+ * Use for sensitive data (user dashboards, auth responses, banking pages).
63
+ */
64
+ noStore: CacheDirective;
65
+ /**
66
+ * `no-cache` — Response may be stored but must be revalidated with the origin before reuse.
67
+ * Useful when content changes frequently but you still want conditional GET support (ETags / Last-Modified).
68
+ */
69
+ noCache: CacheDirective;
70
+ /**
71
+ * `no-cache, no-store, must-revalidate` — Belt-and-suspenders: disables storage and forces
72
+ * revalidation. Maximally prevents caching across all cache layers including legacy HTTP/1.0 proxies.
73
+ */
74
+ noCacheNoStore: CacheDirective;
75
+ /**
76
+ * `public, max-age=<seconds>` — Cacheable by any cache (CDN, proxy, browser).
77
+ * Optionally add `stale-while-revalidate` to serve stale content while revalidating in the background.
78
+ *
79
+ * @param maxAge - Seconds the response is considered fresh.
80
+ * @param staleWhileRevalidate - Seconds past max-age where stale content may still be served while a fresh fetch happens in the background.
81
+ */
82
+ public: (maxAge: number, staleWhileRevalidate?: number) => CacheDirective;
83
+ /**
84
+ * `private, max-age=<seconds>` — Cacheable only by the end-user's browser, not by shared caches (CDNs, proxies).
85
+ * Use for personalised content that must not be stored on shared infrastructure.
86
+ *
87
+ * @param maxAge - Seconds the response is considered fresh in the browser cache.
88
+ */
89
+ private: (maxAge: number) => CacheDirective;
90
+ };
@@ -0,0 +1,65 @@
1
+ const matches = (rule, pathname) => rule.match instanceof RegExp ? rule.match.test(pathname) : rule.match(pathname);
2
+ export const CacheControl = {
3
+ // ── Directive helpers ──────────────────────────────────────────────────────
4
+ directive: {
5
+ /**
6
+ * `no-store` — Response must never be stored. Bypasses all caches (browser, CDN, proxy).
7
+ * Use for sensitive data (user dashboards, auth responses, banking pages).
8
+ */
9
+ noStore: 'no-store',
10
+ /**
11
+ * `no-cache` — Response may be stored but must be revalidated with the origin before reuse.
12
+ * Useful when content changes frequently but you still want conditional GET support (ETags / Last-Modified).
13
+ */
14
+ noCache: 'no-cache',
15
+ /**
16
+ * `no-cache, no-store, must-revalidate` — Belt-and-suspenders: disables storage and forces
17
+ * revalidation. Maximally prevents caching across all cache layers including legacy HTTP/1.0 proxies.
18
+ */
19
+ noCacheNoStore: 'no-cache, no-store, must-revalidate',
20
+ /**
21
+ * `public, max-age=<seconds>` — Cacheable by any cache (CDN, proxy, browser).
22
+ * Optionally add `stale-while-revalidate` to serve stale content while revalidating in the background.
23
+ *
24
+ * @param maxAge - Seconds the response is considered fresh.
25
+ * @param staleWhileRevalidate - Seconds past max-age where stale content may still be served while a fresh fetch happens in the background.
26
+ */
27
+ public: (maxAge, staleWhileRevalidate) => staleWhileRevalidate !== undefined
28
+ ? `public, max-age=${maxAge}, stale-while-revalidate=${staleWhileRevalidate}`
29
+ : `public, max-age=${maxAge}`,
30
+ /**
31
+ * `private, max-age=<seconds>` — Cacheable only by the end-user's browser, not by shared caches (CDNs, proxies).
32
+ * Use for personalised content that must not be stored on shared infrastructure.
33
+ *
34
+ * @param maxAge - Seconds the response is considered fresh in the browser cache.
35
+ */
36
+ private: (maxAge) => `private, max-age=${maxAge}`,
37
+ },
38
+ // ── Enhancers ──────────────────────────────────────────────────────────────
39
+ /**
40
+ * Handle-level enforcer. Matches pathname against rules and sets Cache-Control
41
+ * via setHeaders(). Only sets the header when a rule matches.
42
+ *
43
+ * Usage:
44
+ * export const handle = enhance(handler, CacheControl.global(
45
+ * { match: /^\/api\//, directive: CacheControl.noStore },
46
+ * { match: /^\/blog\//, directive: CacheControl.public(300) },
47
+ * ));
48
+ */
49
+ global: (...rules) => (input) => {
50
+ const rule = rules.find((r) => matches(r, input.url.pathname));
51
+ if (rule)
52
+ input.setHeaders({ 'cache-control': rule.directive });
53
+ },
54
+ /**
55
+ * Load-level policy. Sets Cache-Control for this specific route via setHeaders().
56
+ *
57
+ * Usage:
58
+ * export const load = load(fn, CacheControl.local(CacheControl.public(300)));
59
+ */
60
+ local: (directive) => (input) => {
61
+ input.setHeaders({ 'cache-control': directive });
62
+ return {};
63
+ },
64
+ };
65
+ export const directive = CacheControl.directive;
@@ -1,4 +1,5 @@
1
1
  export * from './auth.js';
2
+ export * from './cache.js';
2
3
  export * from './devtools.js';
3
4
  export * from './featureflag.js';
4
5
  export * from './form.ts';
@@ -1,4 +1,5 @@
1
1
  export * from './auth.js';
2
+ export * from './cache.js';
2
3
  export * from './devtools.js';
3
4
  export * from './featureflag.js';
4
5
  export * from "./form.js";
package/dist/index.d.ts CHANGED
@@ -19,6 +19,32 @@ export type EnhanceInput<CallType extends EnhanceCallType = EnhanceCallType, Par
19
19
  callType: CallType;
20
20
  fetch: typeof fetch;
21
21
  getClientAddress?: () => string;
22
+ /**
23
+ * Set response headers. Available in all contexts (handle, load, action, method).
24
+ * Cannot set `set-cookie` — use the `cookies` API instead.
25
+ */
26
+ setHeaders: (headers: Record<string, string>) => void;
27
+ /**
28
+ * `true` if the request comes from the client asking for `+page/layout.server.js` data.
29
+ * Available in all contexts (handle, load, action, method).
30
+ */
31
+ isDataRequest: boolean;
32
+ /**
33
+ * `true` for `+server.js` calls made via same-origin `fetch` on the server (no HTTP overhead).
34
+ * Available in all contexts (handle, load, action, method).
35
+ */
36
+ isSubRequest: boolean;
37
+ /**
38
+ * Access to OpenTelemetry spans. Spans are no-ops when tracing is disabled.
39
+ * Available in all contexts (handle, load, action, method).
40
+ * @since SvelteKit 2.31.0
41
+ */
42
+ tracing: RequestEvent['tracing'];
43
+ /**
44
+ * `true` if the request comes from the client via a remote function.
45
+ * Available in all contexts (handle, load, action, method).
46
+ */
47
+ isRemoteRequest: boolean;
22
48
  get errorHandlers(): EnhanceErrorHandler[];
23
49
  } & (CallType extends 'handle' ? {
24
50
  get responseHandlers(): EnhanceResponseHandler[];
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@sourceregistry/sveltekit-enhance",
3
- "version": "1.3.3",
3
+ "version": "1.4.0",
4
4
  "description": "Composable enhance and form utilities for SvelteKit actions, loads, methods, and hooks.",
5
5
  "author": "A.P.A. Slaa (a.p.a.slaa@projectsource.nl)",
6
6
  "scripts": {