@timber-js/app 0.2.0-alpha.230 → 0.2.0-alpha.232
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/agent-skill.md +13 -0
- package/dist/_chunks/{actions-DHum77eH.js → actions-CYjRMpZI.js} +3 -2
- package/dist/_chunks/{actions-DHum77eH.js.map → actions-CYjRMpZI.js.map} +1 -1
- package/dist/_chunks/{cli-check-B-JZkpBD.js → cli-check-BAKOSTkg.js} +2 -2
- package/dist/_chunks/{cli-check-B-JZkpBD.js.map → cli-check-BAKOSTkg.js.map} +1 -1
- package/dist/_chunks/codec-registry-C8hOGmZo.js +13 -0
- package/dist/_chunks/codec-registry-C8hOGmZo.js.map +1 -0
- package/dist/_chunks/{codegen-B9oWkWGf.js → codegen-vaCyFyVN.js} +67 -17
- package/dist/_chunks/codegen-vaCyFyVN.js.map +1 -0
- package/dist/_chunks/{convention-lint-CrDKERHg.js → convention-lint-D54k6uUM.js} +2 -2
- package/dist/_chunks/{convention-lint-CrDKERHg.js.map → convention-lint-D54k6uUM.js.map} +1 -1
- package/dist/_chunks/href-BtspoNc9.js +164 -0
- package/dist/_chunks/href-BtspoNc9.js.map +1 -0
- package/dist/_chunks/href-validation-DNg-zV7u.js +102 -0
- package/dist/_chunks/href-validation-DNg-zV7u.js.map +1 -0
- package/dist/_chunks/merge-search-params-7o_5yX0L.js +111 -0
- package/dist/_chunks/merge-search-params-7o_5yX0L.js.map +1 -0
- package/dist/_chunks/{use-query-states-pkDV-jSg.js → use-query-states-D3MMl-KM.js} +12 -12
- package/dist/_chunks/use-query-states-D3MMl-KM.js.map +1 -0
- package/dist/cli.js +1 -1
- package/dist/client/index.d.ts +2 -1
- package/dist/client/index.d.ts.map +1 -1
- package/dist/client/index.js +4 -122
- package/dist/client/index.js.map +1 -1
- package/dist/client/internal.js +1 -1
- package/dist/client/link.d.ts +4 -25
- package/dist/client/link.d.ts.map +1 -1
- package/dist/client/nuqs-adapter.d.ts.map +1 -1
- package/dist/client/use-query-states.d.ts +1 -1
- package/dist/client/use-query-states.d.ts.map +1 -1
- package/dist/index.d.ts +2 -0
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +57 -1
- package/dist/index.js.map +1 -1
- package/dist/params/codec-registry.d.ts +21 -11
- package/dist/params/codec-registry.d.ts.map +1 -1
- package/dist/params/index.d.ts +0 -1
- package/dist/params/index.d.ts.map +1 -1
- package/dist/params/index.js +1 -2
- package/dist/params/index.js.map +1 -1
- package/dist/plugins/node-flight-builds.d.ts +38 -0
- package/dist/plugins/node-flight-builds.d.ts.map +1 -0
- package/dist/plugins/shims.d.ts.map +1 -1
- package/dist/routes/href.d.ts +124 -0
- package/dist/routes/href.d.ts.map +1 -0
- package/dist/routes/index.d.ts +4 -0
- package/dist/routes/index.d.ts.map +1 -0
- package/dist/routes/index.js +8 -0
- package/dist/routes/index.js.map +1 -0
- package/dist/routing/codegen.d.ts.map +1 -1
- package/dist/routing/index.js +1 -1
- package/dist/routing/link-codegen.d.ts +39 -8
- package/dist/routing/link-codegen.d.ts.map +1 -1
- package/dist/search-params/define.d.ts +37 -17
- package/dist/search-params/define.d.ts.map +1 -1
- package/dist/search-params/index.d.ts +1 -0
- package/dist/search-params/index.d.ts.map +1 -1
- package/dist/search-params/index.js +3 -2
- package/dist/search-params/index.js.map +1 -1
- package/dist/server/index.js +1 -1
- package/dist/server/internal.js +4 -6
- package/dist/server/internal.js.map +1 -1
- package/dist/server/param-coercion.d.ts +0 -7
- package/dist/server/param-coercion.d.ts.map +1 -1
- package/dist/server/rsc-entry/index.d.ts.map +1 -1
- package/dist/shared/href.d.ts +88 -0
- package/dist/shared/href.d.ts.map +1 -0
- package/docs/api/31-api-client.mdx +1 -1
- package/docs/api/35-api-typescript.mdx +47 -15
- package/docs/learn/06-typed-params.mdx +33 -0
- package/docs/learn/07-typed-routes.mdx +75 -10
- package/package.json +6 -2
- package/src/client/browser-entry/index.ts +4 -4
- package/src/client/index.ts +3 -1
- package/src/client/link.tsx +5 -238
- package/src/client/nuqs-adapter.tsx +45 -2
- package/src/client/use-query-states.ts +27 -23
- package/src/index.ts +5 -0
- package/src/params/codec-registry.ts +24 -11
- package/src/params/index.ts +0 -1
- package/src/plugins/node-flight-builds.ts +94 -0
- package/src/plugins/shims.ts +10 -0
- package/src/routes/href.ts +171 -0
- package/src/routes/index.ts +10 -0
- package/src/routing/codegen.ts +8 -1
- package/src/routing/link-codegen.ts +103 -37
- package/src/search-params/define.ts +37 -17
- package/src/search-params/index.ts +10 -0
- package/src/server/param-coercion.ts +5 -23
- package/src/server/rsc-entry/index.ts +6 -3
- package/src/server/ssr-entry.ts +2 -2
- package/src/shared/href.ts +257 -0
- package/dist/_chunks/codec-registry-CPc6bjVl.js +0 -20
- package/dist/_chunks/codec-registry-CPc6bjVl.js.map +0 -1
- package/dist/_chunks/codegen-B9oWkWGf.js.map +0 -1
- package/dist/_chunks/href-validation-CEZy1V-k.js +0 -210
- package/dist/_chunks/href-validation-CEZy1V-k.js.map +0 -1
- package/dist/_chunks/use-query-states-pkDV-jSg.js.map +0 -1
|
@@ -11,7 +11,6 @@
|
|
|
11
11
|
* failure; the pipeline catches that and dispatches to the 404 page.
|
|
12
12
|
* See design/07-routing.md §"Where Coercion Runs".
|
|
13
13
|
*/
|
|
14
|
-
import type { Codec } from '../codec.ts';
|
|
15
14
|
import type { SegmentType } from '../routing/types.ts';
|
|
16
15
|
import type { RouteMatch } from './pipeline.ts';
|
|
17
16
|
import { type CoercedParams } from '../shared/param-value.ts';
|
|
@@ -30,12 +29,6 @@ export declare class ParamCoercionError extends Error {
|
|
|
30
29
|
export declare function warnParamCoercionFailure(method: string, pathname: string, segments: readonly {
|
|
31
30
|
segmentName: string;
|
|
32
31
|
}[], error: ParamCoercionError): void;
|
|
33
|
-
/**
|
|
34
|
-
* Register the global schema codecs. Called once from the RSC entry
|
|
35
|
-
* at server startup when app/schema.ts provides segment param codecs.
|
|
36
|
-
* @internal
|
|
37
|
-
*/
|
|
38
|
-
export declare function setGlobalSchemaCodecs(codecs: Record<string, Codec<unknown>> | null): void;
|
|
39
32
|
/**
|
|
40
33
|
* Coerce raw slot params through global schema codecs.
|
|
41
34
|
*
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"param-coercion.d.ts","sourceRoot":"","sources":["../../src/server/param-coercion.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,
|
|
1
|
+
{"version":3,"file":"param-coercion.d.ts","sourceRoot":"","sources":["../../src/server/param-coercion.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAIvD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAAuB,KAAK,aAAa,EAAE,MAAM,0BAA0B,CAAC;AACnF;;;GAGG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;IAC3C,YAAY,OAAO,EAAE,MAAM,EAG1B;CACF;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,SAAS;IAAE,WAAW,EAAE,MAAM,CAAA;CAAE,EAAE,EAC5C,KAAK,EAAE,kBAAkB,GACxB,IAAI,CAUN;AAGD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,gBAAgB,CAC9B,SAAS,EAAE,KAAK,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,WAAW,CAAC;IACzB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,sBAAsB,CAAC,EAAE,MAAM,CAAC;CACjC,CAAC,EACF,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,GAC3C,aAAa,CAwCf;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,wBAAsB,mBAAmB,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,aAAa,CAAC,CAsDnF"}
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/server/rsc-entry/index.ts"],"names":[],"mappings":"AA0CA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mCAAmC,CAAC;
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/server/rsc-entry/index.ts"],"names":[],"mappings":"AA0CA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mCAAmC,CAAC;AAsDlE;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,QAAQ,GAAG,IAAI,CAEjD;AA0WD,OAAO,EAAE,uBAAuB,EAAE,MAAM,0BAA0B,CAAC;AAInE,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAK1D,OAAO,EAAE,wBAAwB,EAAE,MAAM,4BAA4B,CAAC;AAItE,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEpD;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,OAAO,wBAAwB,EAAE,cAAc,GACvD,OAAO,CAAC,OAAO,wBAAwB,EAAE,cAAc,CAAC,CAE1D;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,OAAO,wBAAwB,EAAE,uBAAuB,GAChE,OAAO,CAAC,OAAO,wBAAwB,EAAE,uBAAuB,CAAC,CAQnE;8BA4CoB,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC"}
|
|
@@ -0,0 +1,88 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Route-pattern interpolation and query serialization — the runtime behind
|
|
3
|
+
* `<Link segmentParams searchParams>` and `href()` from `@timber-js/app/routes`.
|
|
4
|
+
*
|
|
5
|
+
* Directive-free and isomorphic: no `'use client'`, no React, no ALS. It
|
|
6
|
+
* lived in `client/link.tsx` until TIM-1621, where the `'use client'`
|
|
7
|
+
* directive turned every import from a server component, middleware or
|
|
8
|
+
* action into a client-reference stub — so nothing on the server could
|
|
9
|
+
* build a URL with it.
|
|
10
|
+
*
|
|
11
|
+
* Segment values serialize through the app/schema.ts codecs registered in
|
|
12
|
+
* `params/codec-registry.ts`. Every entry (RSC, SSR, browser) registers
|
|
13
|
+
* them, so a URL built here is the same in every environment.
|
|
14
|
+
*
|
|
15
|
+
* Design docs: design/09-typescript.md §"Typed Routes",
|
|
16
|
+
* design/41-global-params.md §"Link Component".
|
|
17
|
+
*/
|
|
18
|
+
import { type UrlSegment } from '../routing/segment-classify.ts';
|
|
19
|
+
export type ParamValue = string | number | string[] | {
|
|
20
|
+
toString(): string;
|
|
21
|
+
[key: string]: any;
|
|
22
|
+
};
|
|
23
|
+
/**
|
|
24
|
+
* A query, in one of two shapes discriminated by `typeof === 'string'`:
|
|
25
|
+
*
|
|
26
|
+
* 1. Codec-aware (preferred) — the string `definition.buildSearchParams()`
|
|
27
|
+
* returns. It applies each codec, honours `withUrlKey` aliases, and omits
|
|
28
|
+
* values equal to their default. Passed through untouched.
|
|
29
|
+
*
|
|
30
|
+
* 2. Plain record (escape hatch) — every value is String()-coerced, arrays
|
|
31
|
+
* repeat their key, null/undefined are skipped. No codecs, no aliases, so
|
|
32
|
+
* it must not carry keys a definition owns: `{ search: 'x' }` emits
|
|
33
|
+
* `?search=x` where the definition would emit `?q=x`.
|
|
34
|
+
*
|
|
35
|
+
* Why a STRING and not a URLSearchParams: a Link is routinely rendered by a
|
|
36
|
+
* Server Component, so this value crosses the RSC Flight boundary before the
|
|
37
|
+
* client Link runs. `URLSearchParams` is iterable, and React serializes any
|
|
38
|
+
* iterable as an array — so the prop arrived as `[['pg','2'], …]`, fell into
|
|
39
|
+
* the plain-object branch, and rendered `?0=pg&0=2`. Strings survive Flight
|
|
40
|
+
* unchanged. (Codex P1 on PR #1021; reproduced against a live dev server.)
|
|
41
|
+
*
|
|
42
|
+
* See design/23-search-params.md §"Link Integration".
|
|
43
|
+
*/
|
|
44
|
+
export type SearchParamsArg = string | Record<string, unknown>;
|
|
45
|
+
/**
|
|
46
|
+
* Parse a route pattern's path portion into classified segments.
|
|
47
|
+
* Uses the shared character-based classifier.
|
|
48
|
+
*/
|
|
49
|
+
export declare function parseSegments(pattern: string): UrlSegment[];
|
|
50
|
+
/**
|
|
51
|
+
* Interpolate dynamic segments in a route pattern with actual values.
|
|
52
|
+
* e.g. interpolateParams("/products/[id]", { id: "123" }) → "/products/123"
|
|
53
|
+
*
|
|
54
|
+
* Supports:
|
|
55
|
+
* - [param] → single segment (with optional static prefix/suffix)
|
|
56
|
+
* - [...param] → catch-all (joined with /)
|
|
57
|
+
* - [[...param]] → optional catch-all (omitted if undefined/empty)
|
|
58
|
+
*
|
|
59
|
+
* Every value is percent-encoded per segment; catch-all elements are encoded
|
|
60
|
+
* individually, so a value can never introduce a path separator of its own.
|
|
61
|
+
*/
|
|
62
|
+
export declare function interpolateParams(pattern: string, params: Record<string, ParamValue>): string;
|
|
63
|
+
/**
|
|
64
|
+
* Resolve an href from a pattern, its segment params and a query.
|
|
65
|
+
*
|
|
66
|
+
* - `params` given → the href is interpolated as a pattern
|
|
67
|
+
* - `searchParams` given → serialized and appended (an empty query appends
|
|
68
|
+
* nothing, not a bare `?`)
|
|
69
|
+
* - a query in both `href` and `searchParams` throws: they are exclusive
|
|
70
|
+
*
|
|
71
|
+
* Does not validate the result; callers that hand it to a navigation sink
|
|
72
|
+
* run `validateNavigationHref` on it.
|
|
73
|
+
*/
|
|
74
|
+
export declare function resolveHref(href: string, params?: Record<string, ParamValue>, searchParams?: SearchParamsArg): string;
|
|
75
|
+
/**
|
|
76
|
+
* The runtime of `href()` (@timber-js/app/routes), untyped: the typed
|
|
77
|
+
* surface lives in `routes/href.ts` and only narrows what may be passed.
|
|
78
|
+
*
|
|
79
|
+
* A pattern with no dynamic segment is already its URL. One with any —
|
|
80
|
+
* including a lone optional catch-all called with no params — is
|
|
81
|
+
* interpolated, or `/docs/[[...path]]` would come back verbatim. The query
|
|
82
|
+
* is appended exactly as `<Link searchParams>` appends it, and the result is
|
|
83
|
+
* validated like every navigation sink: segment values that would make a
|
|
84
|
+
* protocol-relative URL (`/[...slug]` with `['', 'evil.com']` →
|
|
85
|
+
* `//evil.com`) throw instead of returning an open redirect.
|
|
86
|
+
*/
|
|
87
|
+
export declare function buildHref(pattern: string, segmentParams?: Record<string, ParamValue>, searchParams?: SearchParamsArg): string;
|
|
88
|
+
//# sourceMappingURL=href.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"href.d.ts","sourceRoot":"","sources":["../../src/shared/href.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAsB,KAAK,UAAU,EAAE,MAAM,gCAAgC,CAAC;AAKrF,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,EAAE,GAAG;IAAE,QAAQ,IAAI,MAAM,CAAC;IAAC,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAA;CAAE,CAAC;AAEjG;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAE/D;;;GAGG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,UAAU,EAAE,CAE3D;AAgGD;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,GAAG,MAAM,CAO7F;AA8BD;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CACzB,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,EACnC,YAAY,CAAC,EAAE,eAAe,GAC7B,MAAM,CAmBR;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,SAAS,CACvB,OAAO,EAAE,MAAM,EACf,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,EAC1C,YAAY,CAAC,EAAE,eAAe,GAC7B,MAAM,CAKR"}
|
|
@@ -200,7 +200,7 @@ With the `ref` on the `<form>`, the hook can sit above the form and hold the who
|
|
|
200
200
|
|
|
201
201
|
### `interpolateParams(pattern, params)`
|
|
202
202
|
|
|
203
|
-
Fill a route pattern with param values.
|
|
203
|
+
Fill a route pattern with param values. Untyped: it accepts any string pattern. In app code, use [`href()`](/docs/api-typescript#href) from `@timber-js/app/routes` instead. It checks the pattern and params against your route map, appends search params, and works on the server too.
|
|
204
204
|
|
|
205
205
|
```ts
|
|
206
206
|
interpolateParams('/products/[id]', { id: '123' }); // "/products/123"
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
title: 'API: TypeScript'
|
|
3
|
-
description: 'Generated route types, $segment module exports, context types, and the Routes interface.'
|
|
3
|
+
description: 'Generated route types, href() URL builder, $segment module exports, context types, and the Routes interface.'
|
|
4
4
|
slug: 'api-typescript'
|
|
5
5
|
---
|
|
6
6
|
|
|
@@ -10,35 +10,67 @@ timber.js generates route types at build time. Links, params, and search params
|
|
|
10
10
|
|
|
11
11
|
## Generated Route Map
|
|
12
12
|
|
|
13
|
-
The build system scans your `app/` directory and generates `.timber/routes.d.ts`:
|
|
13
|
+
The build system scans your `app/` directory and generates `.timber/timber-routes.d.ts`, which augments the `Routes` interface on `@timber-js/app`:
|
|
14
14
|
|
|
15
15
|
```ts
|
|
16
|
-
// .timber/routes.d.ts (generated, gitignored)
|
|
16
|
+
// .timber/timber-routes.d.ts (generated, gitignored)
|
|
17
17
|
import type schema from '../app/schema';
|
|
18
18
|
import type { InferCodecType } from '@timber-js/app/params';
|
|
19
19
|
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
20
|
+
declare module '@timber-js/app' {
|
|
21
|
+
interface Routes {
|
|
22
|
+
'/': { segmentParams: {}; href: '/' };
|
|
23
|
+
'/products/[id]': {
|
|
24
|
+
segmentParams: { id: InferCodecType<typeof schema.segmentParams['[id]']> };
|
|
25
|
+
href: `/products/${string}`;
|
|
26
|
+
};
|
|
27
|
+
'/docs/[[...path]]': {
|
|
28
|
+
segmentParams: { path: string[] | undefined };
|
|
29
|
+
href: '/docs' | `/docs/${string}`;
|
|
30
|
+
};
|
|
31
|
+
}
|
|
28
32
|
}
|
|
29
|
-
|
|
30
|
-
export type AllSegmentParams = { /* union of all route params */ };
|
|
31
33
|
```
|
|
32
34
|
|
|
35
|
+
Each key is a URL pattern with route groups stripped. Route handlers (`route.ts`) are included. `segmentParams` is the route's param shape. `href` is every URL the route resolves to, and it is what [`href()`](#href) returns.
|
|
36
|
+
|
|
33
37
|
Types reference your `app/schema.ts` codecs directly, so they stay in sync automatically.
|
|
34
38
|
|
|
39
|
+
## `href()`
|
|
40
|
+
|
|
41
|
+
```ts
|
|
42
|
+
import { href } from '@timber-js/app/routes';
|
|
43
|
+
|
|
44
|
+
function href<P extends keyof Routes>(
|
|
45
|
+
pattern: P,
|
|
46
|
+
segmentParams?: HrefParams<P>, // required when the route has a required param
|
|
47
|
+
searchParams?: string | Record<string, unknown>
|
|
48
|
+
): RouteHref<P>; // RouteHref<P> | `${RouteHref<P>}?${string}` when searchParams is passed
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
Builds the URL for a route pattern. Isomorphic: it can be imported from server components, client components, middleware, server actions and plain modules. Usage is covered in [Typed Routes — Building URLs](/docs/typed-routes#building-urls).
|
|
52
|
+
|
|
53
|
+
- `pattern`: a key of `Routes`, or `ROUTE` from a page or route handler's `$segment` module.
|
|
54
|
+
- `segmentParams`: exactly the route's params, typed by your `app/schema.ts` codecs and serialized with each codec's `serialize`. Unlike `<Link segmentParams>`, a plain `string` param is not widened to accept `number`. An optional catch-all may be omitted.
|
|
55
|
+
- `searchParams`: the string returned by a definition's `buildSearchParams()`, or a plain object whose values are `String()`-coerced (arrays repeat the key, `null` and `undefined` are skipped). An empty query appends nothing.
|
|
56
|
+
|
|
57
|
+
It throws if a required param is missing, an array is passed to a single `[param]`, a catch-all is empty or its codec serializes to nothing, or the result would be a protocol-relative URL (`//host`). Codecs are the ones timber registers at app startup. Outside a running app, values fall back to `String(value)`.
|
|
58
|
+
|
|
59
|
+
| Type | Description |
|
|
60
|
+
| ------------------------ | ----------------------------------------------------------------- |
|
|
61
|
+
| `RouteHref<P>` | Every URL route `P` resolves to, e.g. `/products/${string}`. |
|
|
62
|
+
| `RouteHrefWithSearch<P>` | `RouteHref<P>` with or without a `?query` suffix. |
|
|
63
|
+
| `HrefParams<P>` | The `segmentParams` argument for route `P`. |
|
|
64
|
+
| `HrefArgs<P>` | The arguments after `pattern`. |
|
|
65
|
+
| `RoutePattern` | `keyof Routes`. |
|
|
66
|
+
|
|
35
67
|
## `$segment` Module
|
|
36
68
|
|
|
37
69
|
Each route directory gets a generated `$segment` module, resolved via TypeScript's `rootDirs` (setup and usage in [Typed Routes](/docs/typed-routes)).
|
|
38
70
|
|
|
39
71
|
| Export | Type | Description |
|
|
40
72
|
| -------------- | ------------------- | ------------------------------------------------------------- |
|
|
41
|
-
| `ROUTE` | String literal | URL route pattern, groups stripped (e.g., `'/products/[id]'`) |
|
|
73
|
+
| `ROUTE` | String literal | URL route pattern, groups stripped (e.g., `'/products/[id]'`); accepted by `href()` |
|
|
42
74
|
| `SEGMENT_PATH` | String literal | Full tree path including groups and slots |
|
|
43
75
|
|
|
44
76
|
`<Link>` `href` validation and `segmentParams`/`searchParams` typing are described in [Typed Routes](/docs/typed-routes); the param and search-param definitions they draw from are in [Typed Params](/docs/typed-params).
|
|
@@ -86,6 +118,6 @@ export default async function access() {
|
|
|
86
118
|
|
|
87
119
|
## Augmenting Routes
|
|
88
120
|
|
|
89
|
-
The `Routes` interface is generated by the build system and written to `.timber/routes.d.ts`. It's module-augmented onto `@timber-js/app` — you don't need to import it manually.
|
|
121
|
+
The `Routes` interface is generated by the build system and written to `.timber/timber-routes.d.ts`. It's module-augmented onto `@timber-js/app` — you don't need to import it manually.
|
|
90
122
|
|
|
91
123
|
Run `timber build` or `timber dev` to regenerate types after adding or renaming routes.
|
|
@@ -168,6 +168,39 @@ export function ProductFilters() {
|
|
|
168
168
|
|
|
169
169
|
By default, `.useQueryStates()` triggers an RSC navigation when params change. Set `shallow: true` to update the URL without a server roundtrip.
|
|
170
170
|
|
|
171
|
+
### Debouncing and Other Options
|
|
172
|
+
|
|
173
|
+
`.useQueryStates(options)` and `setParams(values, options)` accept every [nuqs option](https://nuqs.dev/docs/options), and timber passes them through. Options you pass to `setParams` override the ones you pass to the hook.
|
|
174
|
+
|
|
175
|
+
Without a limit, a search box asks the server for a new page on every keystroke. Debounce it, and it sends one request after the user stops typing:
|
|
176
|
+
|
|
177
|
+
```tsx title="app/products/search-box.tsx" use="search-params"
|
|
178
|
+
'use client';
|
|
179
|
+
import { debounce, defaultRateLimit } from '@timber-js/app/search-params';
|
|
180
|
+
import { searchParams } from './search-params';
|
|
181
|
+
|
|
182
|
+
const query = searchParams.pick('q');
|
|
183
|
+
|
|
184
|
+
export function SearchBox() {
|
|
185
|
+
const [{ q }, setParams] = query.useQueryStates({ limitUrlUpdates: debounce(300) });
|
|
186
|
+
|
|
187
|
+
return (
|
|
188
|
+
<input
|
|
189
|
+
value={q ?? ''}
|
|
190
|
+
onChange={(e) => setParams({ q: e.target.value || null })}
|
|
191
|
+
// Enter searches now instead of waiting for the debounce.
|
|
192
|
+
onKeyDown={(e) => {
|
|
193
|
+
if (e.key === 'Enter') setParams({ q }, { limitUrlUpdates: defaultRateLimit });
|
|
194
|
+
}}
|
|
195
|
+
/>
|
|
196
|
+
);
|
|
197
|
+
}
|
|
198
|
+
```
|
|
199
|
+
|
|
200
|
+
The input updates as the user types. Only the URL write, and the server request that follows it, waits. If the user goes to another page before a pending write lands, timber drops the write, so it can't pull them back. Use `throttle(ms)` to allow at most one write per interval. `debounce`, `throttle` and `defaultRateLimit` come from nuqs. `@timber-js/app/search-params` re-exports them, so you don't import nuqs yourself.
|
|
201
|
+
|
|
202
|
+
timber changes two nuqs defaults: `shallow: false`, so every write fetches fresh server data, and `scroll: true`. It also sets `urlKeys` from your `withUrlKey` aliases, so `urlKeys` isn't an option you can pass. Pass options to the hook or to `setParams`. Options set on a nuqs parser with `.withOptions()` are ignored. `startTransition` doesn't give you a loading state for the server request; use `usePendingNavigation()` for that.
|
|
203
|
+
|
|
171
204
|
## Cookies
|
|
172
205
|
|
|
173
206
|
Define typed cookies with `defineCookie()`:
|
|
@@ -1,26 +1,28 @@
|
|
|
1
1
|
---
|
|
2
2
|
title: 'Typed Routes'
|
|
3
|
-
description: 'Build-time route types — <Link> validates href, $segment narrows params to the current route.'
|
|
3
|
+
description: 'Build-time route types — <Link> validates href, href() builds typed URL strings, $segment narrows params to the current route.'
|
|
4
4
|
slug: 'typed-routes'
|
|
5
5
|
---
|
|
6
6
|
|
|
7
7
|
# Typed Routes
|
|
8
8
|
|
|
9
|
-
timber.js generates route types at build time. `<Link>` type-checks `href` against your actual route tree, and every route directory gets a `$segment` module that narrows params to that route. This page covers what the codegen gives you; defining and reading params is covered in [Typed Params](/docs/typed-params).
|
|
9
|
+
timber.js generates route types at build time. `<Link>` type-checks `href` against your actual route tree, `href()` builds checked URL strings for everything else, and every route directory gets a `$segment` module that narrows params to that route. This page covers what the codegen gives you; defining and reading params is covered in [Typed Params](/docs/typed-params).
|
|
10
10
|
|
|
11
11
|
## How It Works
|
|
12
12
|
|
|
13
|
-
When you run `timber dev` or `timber build`, the framework scans your `app/` directory and generates a route map in `.timber/routes.d.ts`:
|
|
13
|
+
When you run `timber dev` or `timber build`, the framework scans your `app/` directory and generates a route map in `.timber/timber-routes.d.ts`:
|
|
14
14
|
|
|
15
15
|
```ts
|
|
16
|
-
// .timber/routes.d.ts (generated, gitignored)
|
|
17
|
-
|
|
18
|
-
'/': {};
|
|
19
|
-
'/products/[id]': { id: number };
|
|
20
|
-
'/blog/[...slug]': { slug: string[] };
|
|
16
|
+
// .timber/timber-routes.d.ts (generated, gitignored)
|
|
17
|
+
interface Routes {
|
|
18
|
+
'/': { segmentParams: {}; href: '/' };
|
|
19
|
+
'/products/[id]': { segmentParams: { id: number }; href: `/products/${string}` };
|
|
20
|
+
'/blog/[...slug]': { segmentParams: { slug: string[] }; href: `/blog/${string}` };
|
|
21
21
|
}
|
|
22
22
|
```
|
|
23
23
|
|
|
24
|
+
Keys are URL patterns with route groups stripped: `app/(shop)/products/[id]/page.tsx` is `'/products/[id]'`.
|
|
25
|
+
|
|
24
26
|
Types reference your `app/schema.ts` codecs directly, so they stay in sync automatically.
|
|
25
27
|
|
|
26
28
|
## Typed `<Link>`
|
|
@@ -70,6 +72,69 @@ import { searchParams } from './search-params';
|
|
|
70
72
|
|
|
71
73
|
A plain object also works as an untyped escape hatch for one-off params with no definition — but it skips codecs and aliases, so do not use it for keys a definition owns.
|
|
72
74
|
|
|
75
|
+
## Building URLs
|
|
76
|
+
|
|
77
|
+
`<Link>` checks the hrefs you write in JSX. Everywhere else a URL is a string — `router.push`, `redirect()`, an href computed on the server and passed as a prop, metadata, `fetch`. Build those with `href()` from `@timber-js/app/routes`:
|
|
78
|
+
|
|
79
|
+
```ts
|
|
80
|
+
import { href } from '@timber-js/app/routes';
|
|
81
|
+
|
|
82
|
+
href('/venues'); // '/venues'
|
|
83
|
+
href('/products/[id]', { id: 42 }); // '/products/42'
|
|
84
|
+
href('/docs/[[...path]]'); // '/docs'
|
|
85
|
+
href('/artists/[artistSlug]', { artistSlug }, artistParams.buildSearchParams({ sort: '-rating' }));
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
The pattern must be a route that exists, and the params must be that route's params, typed by your `app/schema.ts` codecs. Rename a route directory and every `href()` that points at it stops compiling. Each value runs through its codec's `serialize` and is percent-encoded segment by segment. A `Date` codec's param comes out as `2026-04-10`, not `String(date)`.
|
|
89
|
+
|
|
90
|
+
`href()` has no directive and no React or server-only imports, so the same call works in server components, client components, middleware, server actions and plain modules. Codec serialization needs the codecs timber registers when the app starts. Called outside a running app, for example from a standalone script, `href()` falls back to `String(value)`:
|
|
91
|
+
|
|
92
|
+
```tsx
|
|
93
|
+
// server component
|
|
94
|
+
<Link href={href('/products/[id]', { id })}>Product</Link>
|
|
95
|
+
|
|
96
|
+
// client component
|
|
97
|
+
router.push(href('/products/[id]', { id }));
|
|
98
|
+
|
|
99
|
+
// server action or middleware
|
|
100
|
+
redirect(href('/products/[id]', { id }));
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
**Search params** go in the third argument. Pass the string a `defineSearchParams` definition's `buildSearchParams()` returns, so the query gets its codecs, `withUrlKey` aliases, and omission of default values. As with `<Link searchParams>`, a plain object also works as an untyped escape hatch. An empty query appends nothing.
|
|
104
|
+
|
|
105
|
+
**The result is typed as the route's URL.** `href('/products/[id]', { id })` returns `` `/products/${string}` ``, not `string`, so `<Link>` still checks it, and passing it with `segmentParams` is an error. Don't also pass `searchParams` to an href that already carries a query. `<Link>` throws on that at render. The types catch it only when the URL ends in a static part (`/venues?…`), because a template ending in a param (`` `/products/${string}` ``) also matches a query. To require a route-shaped string in a prop, use `RouteHref`:
|
|
106
|
+
|
|
107
|
+
```ts
|
|
108
|
+
import type { RouteHref } from '@timber-js/app/routes';
|
|
109
|
+
|
|
110
|
+
function ArtistRow({ rowHref }: { rowHref: RouteHref<'/artists/[artistSlug]'> }) { /* … */ }
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
`RouteHref` checks the string's shape; it isn't a brand. A hand-built `` `/artists/${slug}` `` satisfies it too, the same way `<Link>` treats literal hrefs. So does the href of any route nested under it: `` `/artists/${string}` `` also matches `/artists/phish/songs/tweezer`. It rejects routes outside that shape, like `/venues`.
|
|
114
|
+
|
|
115
|
+
**From the route itself**, pass `ROUTE` from the directory's `$segment` module (see below). That works when the directory is a page or route handler: `href(ROUTE, { id })`.
|
|
116
|
+
|
|
117
|
+
**Untrusted values are safe to pass.** `href()` validates its result like every navigation sink. If a catch-all value would produce a protocol-relative URL (`/[...slug]` with `['', 'evil.com']` → `//evil.com`), `href()` throws instead of returning an open redirect.
|
|
118
|
+
|
|
119
|
+
### Replacing URL helper modules
|
|
120
|
+
|
|
121
|
+
Hand-written URL helpers drift silently when a route moves, and hand-built query strings skip your search-param codecs:
|
|
122
|
+
|
|
123
|
+
```ts
|
|
124
|
+
// lib/urls.ts — before
|
|
125
|
+
export const songUrl = (artistSlug: string, songSlug: string) =>
|
|
126
|
+
`/artists/${artistSlug}/songs/${songSlug}`;
|
|
127
|
+
export const artistTodayUrl = (artistSlug: string, month?: number, day?: number) =>
|
|
128
|
+
`/artists/${artistSlug}/today-in-history${month && day ? `?month=${month}&day=${day}` : ''}`;
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
Call `href()` inline instead:
|
|
132
|
+
|
|
133
|
+
```ts
|
|
134
|
+
href('/artists/[artistSlug]/songs/[songSlug]', { artistSlug, songSlug });
|
|
135
|
+
href('/artists/[artistSlug]/today-in-history', { artistSlug }, todaySearchParams.buildSearchParams({ month, day }));
|
|
136
|
+
```
|
|
137
|
+
|
|
73
138
|
## `$segment` and `SEGMENT_PATH`
|
|
74
139
|
|
|
75
140
|
Each route directory gets a generated `$segment` module. It exports `SEGMENT_PATH`, a string literal typed to that directory's position in the route tree. Passing it to `getSegmentParams()` / `useSegmentParams()` narrows the result to exactly the params that exist at that depth:
|
|
@@ -87,7 +152,7 @@ export default async function ProductPage() {
|
|
|
87
152
|
|
|
88
153
|
Without `SEGMENT_PATH`, params are `Partial<AllSegmentParams>` — every param optional.
|
|
89
154
|
|
|
90
|
-
`$segment` also exports `ROUTE`, the URL pattern with route groups stripped (e.g. `'/products/[id]'`).
|
|
155
|
+
`$segment` also exports `ROUTE`, the URL pattern with route groups stripped (e.g. `'/products/[id]'`). Pass it to `href()` to build a URL to the current route.
|
|
91
156
|
|
|
92
157
|
### tsconfig.json
|
|
93
158
|
|
|
@@ -103,6 +168,6 @@ Add `rootDirs` so TypeScript can resolve `$segment` imports:
|
|
|
103
168
|
|
|
104
169
|
## Codegen
|
|
105
170
|
|
|
106
|
-
Types are generated during `timber dev` (on startup and when routes change) and `timber build`. The generated `.timber/routes.d.ts` is gitignored — it's a build artifact. Run `timber dev` once to get types for your editor.
|
|
171
|
+
Types are generated during `timber dev` (on startup and when routes change) and `timber build`. The generated `.timber/timber-routes.d.ts` is gitignored — it's a build artifact. Run `timber dev` once to get types for your editor.
|
|
107
172
|
|
|
108
173
|
For the generated type shapes and context types (`RouteContext`, `MiddlewareContext`, `AccessContext`), see the [TypeScript API Reference](/docs/api-typescript).
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@timber-js/app",
|
|
3
|
-
"version": "0.2.0-alpha.
|
|
3
|
+
"version": "0.2.0-alpha.232",
|
|
4
4
|
"description": "Vite-native React framework built for Servers and Serverless Platforms — correct HTTP semantics, real status codes, pages that work without JavaScript",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"cloudflare-workers",
|
|
@@ -109,6 +109,10 @@
|
|
|
109
109
|
"types": "./dist/cookies/index.d.ts",
|
|
110
110
|
"import": "./dist/cookies/index.js"
|
|
111
111
|
},
|
|
112
|
+
"./routes": {
|
|
113
|
+
"types": "./dist/routes/index.d.ts",
|
|
114
|
+
"import": "./dist/routes/index.js"
|
|
115
|
+
},
|
|
112
116
|
"./search-params": {
|
|
113
117
|
"types": "./dist/search-params/index.d.ts",
|
|
114
118
|
"import": "./dist/search-params/index.js"
|
|
@@ -168,7 +172,7 @@
|
|
|
168
172
|
"@typescript/native-preview": "^7.0.0-dev.0",
|
|
169
173
|
"@vitejs/plugin-react": "^6.1.0",
|
|
170
174
|
"@vitejs/plugin-rsc": "^0.5.39",
|
|
171
|
-
"nuqs": "^2.
|
|
175
|
+
"nuqs": "^2.7.0",
|
|
172
176
|
"react": "19.3.1",
|
|
173
177
|
"react-dom": "19.3.1",
|
|
174
178
|
"satteri": "^0.10.5 || ^0.11.5",
|
|
@@ -31,12 +31,12 @@
|
|
|
31
31
|
|
|
32
32
|
// @ts-expect-error — virtual module provided by timber-entries plugin
|
|
33
33
|
import config from 'virtual:timber-config';
|
|
34
|
-
// TIM-932: Populate the codec registry so Link
|
|
35
|
-
//
|
|
34
|
+
// TIM-932: Populate the codec registry so <Link> and href() use
|
|
35
|
+
// codec.serialize() for URL construction. Side-effect-only import.
|
|
36
36
|
// @ts-expect-error — virtual module provided by timber-routing plugin
|
|
37
37
|
import schemaCodecs from 'virtual:timber-schema';
|
|
38
|
-
import {
|
|
39
|
-
|
|
38
|
+
import { setSchemaCodecs } from '../../params/codec-registry.ts';
|
|
39
|
+
setSchemaCodecs(schemaCodecs);
|
|
40
40
|
|
|
41
41
|
import { setClientDeploymentId, setStaticMode, setBasePath } from '../rsc-fetch.ts';
|
|
42
42
|
import { initStaleClient } from '../stale-client.ts';
|
package/src/client/index.ts
CHANGED
|
@@ -9,7 +9,9 @@
|
|
|
9
9
|
// Re-export removed per TIM-721.
|
|
10
10
|
|
|
11
11
|
// Navigation
|
|
12
|
-
export { Link,
|
|
12
|
+
export { Link, validateLinkHref, buildLinkProps } from './link.tsx';
|
|
13
|
+
// Directive-free so `href()` (@timber-js/app/routes) can run it on the server.
|
|
14
|
+
export { interpolateParams, resolveHref } from '../shared/href.ts';
|
|
13
15
|
export { mergePreservedSearchParams } from '../shared/merge-search-params.ts';
|
|
14
16
|
export type { LinkProps, LinkPropsWithHref, LinkPropsWithParams, LinkBaseProps } from './link.tsx';
|
|
15
17
|
export type { LinkSegmentParams, OnNavigateHandler, OnNavigateEvent } from './link.tsx';
|