@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 +68 -1
- package/dist/helpers/cache.d.ts +90 -0
- package/dist/helpers/cache.js +65 -0
- package/dist/helpers/index.d.ts +1 -0
- package/dist/helpers/index.js +1 -0
- package/dist/index.d.ts +26 -0
- package/package.json +1 -1
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;
|
package/dist/helpers/index.d.ts
CHANGED
package/dist/helpers/index.js
CHANGED
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
|
+
"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": {
|