fondu 0.5.0 → 0.6.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 +7 -4
- package/dist/server/props.d.ts +40 -36
- package/dist/server/props.js +31 -12
- package/dist/server/protocol.js +58 -32
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -9,8 +9,10 @@ Routes are Hono handlers in `app/routes/`; pages are React components in `app/pa
|
|
|
9
9
|
props, and Inertia does the rest in the browser: visits without full reloads, forms with validation, deferred and
|
|
10
10
|
merged props, all without an API to write or a client-side router to keep in sync.
|
|
11
11
|
|
|
12
|
-
Fondu writes
|
|
13
|
-
URLs, the document and error pages. Everything else is Hono's, Vite's and
|
|
12
|
+
Fondu writes only what none of them does: Inertia's server side for Hono (the protocol, forms' errors and flash
|
|
13
|
+
data), file routes, typed pages and URLs, the document and error pages. Everything else is Hono's, Vite's and
|
|
14
|
+
Inertia's. [Fondu and @hono/inertia](https://fondu.dev/docs#fondu-and-honoinertia) says how it compares with Hono's
|
|
15
|
+
own middleware.
|
|
14
16
|
|
|
15
17
|
## Quick start
|
|
16
18
|
|
|
@@ -20,8 +22,9 @@ cd my-app
|
|
|
20
22
|
bun dev
|
|
21
23
|
```
|
|
22
24
|
|
|
23
|
-
It asks where the app runs (Bun, Cloudflare Workers or Node; or `--target bun|cloudflare|node`) and
|
|
24
|
-
|
|
25
|
+
It asks where the app runs (Bun, Cloudflare Workers or Node; or `--target bun|cloudflare|node`) and whether to add
|
|
26
|
+
code checks (oxfmt, oxlint, lefthook, commitlint; or `--checks`), and writes a small app: a route, its page, the error
|
|
27
|
+
page, Tailwind CSS, editor snippets and an `AGENTS.md` for coding agents.
|
|
25
28
|
|
|
26
29
|
[demo.fondu.dev](https://demo.fondu.dev) ([apps/demo](https://github.com/fondujs/fondu/tree/main/apps/demo)) shows every Inertia feature, one page each, on
|
|
27
30
|
Cloudflare Workers with D1 and Better Auth.
|
package/dist/server/props.d.ts
CHANGED
|
@@ -2,17 +2,24 @@
|
|
|
2
2
|
* Inertia's prop types (the names are Inertia's: what the client docs call them). A plain value is always sent;
|
|
3
3
|
* a function is called only when its prop is sent.
|
|
4
4
|
*
|
|
5
|
-
* - `optional(fn)`: never on a full visit, only when a partial reload
|
|
5
|
+
* - `optional(fn)`: never on a full visit, only when a partial reload names it (`only`)
|
|
6
6
|
* - `always(value)`: sent on partial reloads too, even when not asked for
|
|
7
7
|
* - `defer(fn, { group?, rescue? })`: left out of the page, fetched by the client right after it renders (one
|
|
8
8
|
* request per group); `rescue`: if it throws, the page still loads and `<Deferred>` shows its `rescue` slot
|
|
9
|
-
* - `merge(value)` / `prepend(
|
|
9
|
+
* - `merge(value, { path?, matchOn? })` / `prepend(…)` / `deepMerge(value, { matchOn? })`: partial reloads merge into
|
|
10
|
+
* what the client holds; `path`: the list to merge, inside the prop (`'data'`); `matchOn`: the field, from the
|
|
11
|
+
* prop, that finds an item to replace (`'id'`, `'data.id'`)
|
|
10
12
|
* - `once(fn, { key?, ttl?, fresh? })`: computed once; later requests say the client holds it and it is skipped
|
|
11
13
|
* (`fresh`: send it anyway)
|
|
12
14
|
* - `scroll(fn, { pageName? })`: a page of a list for `<InfiniteScroll>`; `fn` returns `{ data, currentPage,
|
|
13
15
|
* previousPage, nextPage }` for the page in the query (`?page=`)
|
|
16
|
+
*
|
|
17
|
+
* They combine as Inertia's do (Laravel's `->once()`, `->merge()`, `->defer()`), by wrapping one in another:
|
|
18
|
+
* `once(defer(fn))`, `once(optional(fn))`, `once(merge(fn))`, `merge(defer(fn))` (and `deepMerge`, `prepend`),
|
|
19
|
+
* `defer(scroll(fn))`.
|
|
14
20
|
*/
|
|
15
21
|
declare const PROP: unique symbol;
|
|
22
|
+
declare const BRAND: unique symbol;
|
|
16
23
|
type Resolver<T> = () => T | Promise<T>;
|
|
17
24
|
export type Lazy<T> = T | Resolver<T>;
|
|
18
25
|
export interface Paginated<T> {
|
|
@@ -21,44 +28,41 @@ export interface Paginated<T> {
|
|
|
21
28
|
previousPage: number | string | null;
|
|
22
29
|
nextPage: number | string | null;
|
|
23
30
|
}
|
|
24
|
-
export
|
|
25
|
-
[PROP]:
|
|
26
|
-
value: Lazy<unknown>;
|
|
27
|
-
} | {
|
|
28
|
-
[PROP]: 'always';
|
|
29
|
-
value: Lazy<unknown>;
|
|
30
|
-
} | {
|
|
31
|
-
[PROP]: 'defer';
|
|
32
|
-
value: Lazy<unknown>;
|
|
33
|
-
group: string;
|
|
34
|
-
rescue: boolean;
|
|
35
|
-
} | {
|
|
36
|
-
[PROP]: 'merge';
|
|
31
|
+
export interface PropSpec {
|
|
32
|
+
[PROP]: true;
|
|
37
33
|
value: Lazy<unknown>;
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
34
|
+
optional?: true;
|
|
35
|
+
always?: true;
|
|
36
|
+
defer?: {
|
|
37
|
+
group: string;
|
|
38
|
+
rescue: boolean;
|
|
39
|
+
};
|
|
40
|
+
once?: {
|
|
41
|
+
key?: string;
|
|
42
|
+
ttl?: number;
|
|
43
|
+
fresh?: boolean;
|
|
44
|
+
};
|
|
45
|
+
merge?: {
|
|
46
|
+
strategy: 'append' | 'prepend' | 'deep';
|
|
47
|
+
paths: string[];
|
|
48
|
+
matchOn: string[];
|
|
49
|
+
};
|
|
50
|
+
scroll?: {
|
|
51
|
+
pageName: string;
|
|
52
|
+
};
|
|
53
|
+
}
|
|
51
54
|
/** A prop with an Inertia behaviour; at the type level it stands for the value it resolves to. */
|
|
52
55
|
export type Prop<T> = T & {
|
|
53
|
-
readonly [
|
|
56
|
+
readonly [BRAND]: true;
|
|
54
57
|
};
|
|
58
|
+
export declare const propSpec: (value: unknown) => PropSpec | null;
|
|
55
59
|
export declare const optional: <T>(value: Resolver<T>) => Prop<T>;
|
|
56
60
|
export declare const always: <T>(value: Lazy<T>) => Prop<T>;
|
|
57
|
-
export declare const defer: <T>(value: Resolver<T>, { group, rescue }?: {
|
|
61
|
+
export declare const defer: <T>(value: Resolver<T> | Prop<T>, { group, rescue }?: {
|
|
58
62
|
group?: string;
|
|
59
63
|
rescue?: boolean;
|
|
60
64
|
}) => Prop<T>;
|
|
61
|
-
export declare const once: <T>(value: Resolver<T>, options?: {
|
|
65
|
+
export declare const once: <T>(value: Resolver<T> | Prop<T>, options?: {
|
|
62
66
|
key?: string;
|
|
63
67
|
ttl?: number;
|
|
64
68
|
fresh?: boolean;
|
|
@@ -66,16 +70,16 @@ export declare const once: <T>(value: Resolver<T>, options?: {
|
|
|
66
70
|
export declare const scroll: <T>(value: Resolver<Paginated<T>>, { pageName }?: {
|
|
67
71
|
pageName?: string;
|
|
68
72
|
}) => Prop<Paginated<T>>;
|
|
69
|
-
export declare const merge: <T>(value: Lazy<T>, options?: {
|
|
73
|
+
export declare const merge: <T>(value: Lazy<T> | Prop<T>, options?: {
|
|
74
|
+
path?: string | string[];
|
|
70
75
|
matchOn?: string | string[];
|
|
71
76
|
}) => Prop<T>;
|
|
72
|
-
export declare const prepend: <T>(value: Lazy<T>, options?: {
|
|
77
|
+
export declare const prepend: <T>(value: Lazy<T> | Prop<T>, options?: {
|
|
78
|
+
path?: string | string[];
|
|
73
79
|
matchOn?: string | string[];
|
|
74
80
|
}) => Prop<T>;
|
|
75
|
-
export declare const deepMerge: <T>(value: Lazy<T>, options?: {
|
|
81
|
+
export declare const deepMerge: <T>(value: Lazy<T> | Prop<T>, options?: {
|
|
76
82
|
matchOn?: string | string[];
|
|
77
83
|
}) => Prop<T>;
|
|
78
|
-
export declare const propSpec: (value: unknown) => PropSpec | null;
|
|
79
|
-
export declare const kindOf: (spec: PropSpec) => "always" | "defer" | "merge" | "once" | "optional" | "scroll";
|
|
80
84
|
export declare const resolve: (value: Lazy<unknown>) => Promise<unknown>;
|
|
81
85
|
export {};
|
package/dist/server/props.js
CHANGED
|
@@ -2,27 +2,46 @@
|
|
|
2
2
|
* Inertia's prop types (the names are Inertia's: what the client docs call them). A plain value is always sent;
|
|
3
3
|
* a function is called only when its prop is sent.
|
|
4
4
|
*
|
|
5
|
-
* - `optional(fn)`: never on a full visit, only when a partial reload
|
|
5
|
+
* - `optional(fn)`: never on a full visit, only when a partial reload names it (`only`)
|
|
6
6
|
* - `always(value)`: sent on partial reloads too, even when not asked for
|
|
7
7
|
* - `defer(fn, { group?, rescue? })`: left out of the page, fetched by the client right after it renders (one
|
|
8
8
|
* request per group); `rescue`: if it throws, the page still loads and `<Deferred>` shows its `rescue` slot
|
|
9
|
-
* - `merge(value)` / `prepend(
|
|
9
|
+
* - `merge(value, { path?, matchOn? })` / `prepend(…)` / `deepMerge(value, { matchOn? })`: partial reloads merge into
|
|
10
|
+
* what the client holds; `path`: the list to merge, inside the prop (`'data'`); `matchOn`: the field, from the
|
|
11
|
+
* prop, that finds an item to replace (`'id'`, `'data.id'`)
|
|
10
12
|
* - `once(fn, { key?, ttl?, fresh? })`: computed once; later requests say the client holds it and it is skipped
|
|
11
13
|
* (`fresh`: send it anyway)
|
|
12
14
|
* - `scroll(fn, { pageName? })`: a page of a list for `<InfiniteScroll>`; `fn` returns `{ data, currentPage,
|
|
13
15
|
* previousPage, nextPage }` for the page in the query (`?page=`)
|
|
16
|
+
*
|
|
17
|
+
* They combine as Inertia's do (Laravel's `->once()`, `->merge()`, `->defer()`), by wrapping one in another:
|
|
18
|
+
* `once(defer(fn))`, `once(optional(fn))`, `once(merge(fn))`, `merge(defer(fn))` (and `deepMerge`, `prepend`),
|
|
19
|
+
* `defer(scroll(fn))`.
|
|
14
20
|
*/
|
|
15
21
|
const PROP = Symbol.for('fondu.prop');
|
|
16
|
-
const
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
const
|
|
22
|
+
export const propSpec = (value) => typeof value === 'object' && value !== null && PROP in value ? value : null;
|
|
23
|
+
/** a new prop, or `kind` added to the one it wraps when Inertia combines them (`can`: the kinds it may wrap) */
|
|
24
|
+
function make(name, value, add, can) {
|
|
25
|
+
const inner = propSpec(value);
|
|
26
|
+
if (!inner)
|
|
27
|
+
return { [PROP]: true, value, ...add };
|
|
28
|
+
const kinds = Object.keys(inner).filter((k) => k !== 'value');
|
|
29
|
+
const other = kinds.find((k) => !can.includes(k));
|
|
30
|
+
if (other)
|
|
31
|
+
throw new Error(`fondu: ${name}() can't wrap ${other}()`);
|
|
32
|
+
return { ...inner, ...add };
|
|
33
|
+
}
|
|
34
|
+
export const optional = (value) => make('optional', value, { optional: true }, []);
|
|
35
|
+
export const always = (value) => make('always', value, { always: true }, []);
|
|
36
|
+
export const defer = (value, { group = 'default', rescue = false } = {}) => make('defer', value, { defer: { group, rescue } }, ['scroll']);
|
|
37
|
+
export const once = (value, options = {}) => make('once', value, { once: options }, ['defer', 'optional', 'merge']);
|
|
38
|
+
export const scroll = (value, { pageName = 'page' } = {}) => make('scroll', value, { scroll: { pageName } }, []);
|
|
39
|
+
const list = (value) => [value ?? []].flat();
|
|
40
|
+
const merger = (strategy) => (value, options = {}) => make(strategy === 'append' ? 'merge' : 'prepend', value, { merge: { strategy, paths: list(options.path), matchOn: list(options.matchOn) } }, ['defer', 'once']);
|
|
23
41
|
export const merge = merger('append');
|
|
24
42
|
export const prepend = merger('prepend');
|
|
25
|
-
export const deepMerge =
|
|
26
|
-
|
|
27
|
-
|
|
43
|
+
export const deepMerge = (value, options = {}) => make('deepMerge', value, { merge: { strategy: 'deep', paths: [], matchOn: list(options.matchOn) } }, [
|
|
44
|
+
'defer',
|
|
45
|
+
'once',
|
|
46
|
+
]);
|
|
28
47
|
export const resolve = async (value) => typeof value === 'function' ? value() : value;
|
package/dist/server/protocol.js
CHANGED
|
@@ -2,8 +2,8 @@ import { pages, version } from 'virtual:fondu/assets';
|
|
|
2
2
|
import { isPageFile } from '../paths.js';
|
|
3
3
|
import { renderDocument } from './document.js';
|
|
4
4
|
import { flashCookie, takeCarried } from './flash.js';
|
|
5
|
-
import { isInertia, sameOrigin } from './http.js';
|
|
6
|
-
import {
|
|
5
|
+
import { back, isInertia, sameOrigin } from './http.js';
|
|
6
|
+
import { propSpec, resolve } from './props.js';
|
|
7
7
|
const shared = new WeakMap();
|
|
8
8
|
/** Props every page of this request gets (a middleware calls it: the signed-in user…). */
|
|
9
9
|
export function share(c, props) {
|
|
@@ -52,7 +52,8 @@ export async function render(c, component, ...[props = {}, options = {}]) {
|
|
|
52
52
|
const except = partial ? headerSet(c, 'x-inertia-partial-except') : null;
|
|
53
53
|
const reset = headerSet(c, 'x-inertia-reset') ?? new Set();
|
|
54
54
|
const heldOnce = headerSet(c, 'x-inertia-except-once-props') ?? new Set();
|
|
55
|
-
|
|
55
|
+
// shown by the next page, a partial reload too (a form with `only`), as Laravel's session does; not a prefetch
|
|
56
|
+
const carried = takeCarried(c, !isPrefetch(c));
|
|
56
57
|
const sharedProps = shared.get(c) ?? {};
|
|
57
58
|
const all = { ...sharedProps, ...props };
|
|
58
59
|
const page = {
|
|
@@ -71,36 +72,53 @@ export async function render(c, component, ...[props = {}, options = {}]) {
|
|
|
71
72
|
const deferred = {};
|
|
72
73
|
const onceProps = {};
|
|
73
74
|
const pending = [];
|
|
75
|
+
const listOnce = (key, once) => {
|
|
76
|
+
onceProps[once.key ?? key] = { prop: key, expiresAt: once.ttl ? Date.now() + once.ttl * 1000 : null };
|
|
77
|
+
};
|
|
78
|
+
const listMerge = (key, spec) => {
|
|
79
|
+
if (reset.has(key))
|
|
80
|
+
return;
|
|
81
|
+
if (spec.scroll) {
|
|
82
|
+
// <InfiniteScroll> says which side it loads: the previous page goes before what the client holds
|
|
83
|
+
const intent = c.req.header('x-inertia-infinite-scroll-merge-intent') === 'prepend' ? 'prependProps' : 'mergeProps';
|
|
84
|
+
lists[intent].push(`${key}.data`);
|
|
85
|
+
return;
|
|
86
|
+
}
|
|
87
|
+
const { strategy, paths, matchOn } = spec.merge;
|
|
88
|
+
const into = strategy === 'append' ? 'mergeProps' : strategy === 'prepend' ? 'prependProps' : 'deepMergeProps';
|
|
89
|
+
lists[into].push(...(paths.length ? paths.map((path) => `${key}.${path}`) : [key]));
|
|
90
|
+
lists.matchPropsOn.push(...matchOn.map((field) => `${key}.${field}`));
|
|
91
|
+
};
|
|
74
92
|
for (const [key, value] of Object.entries(all)) {
|
|
75
93
|
const spec = propSpec(value);
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
const sent = kind === 'always' || (asked && !except?.has(key));
|
|
79
|
-
if (kind === 'defer' && !partial) {
|
|
80
|
-
;
|
|
81
|
-
(deferred[spec.group] ??= []).push(key);
|
|
94
|
+
// a partial reload: the props it names (`only`) or keeps (`except`), and the `always` ones
|
|
95
|
+
if (!spec?.always && ((only && !only.has(key)) || except?.has(key)))
|
|
82
96
|
continue;
|
|
83
|
-
|
|
84
|
-
if (
|
|
97
|
+
// only when named (Inertia's docs: `only`), not with `except`, though inertia-laravel's code sends it then
|
|
98
|
+
if (spec?.optional && !only?.has(key)) {
|
|
99
|
+
if (!partial && spec.once)
|
|
100
|
+
listOnce(key, spec.once);
|
|
85
101
|
continue;
|
|
86
|
-
if (kind === 'once') {
|
|
87
|
-
const once = spec;
|
|
88
|
-
const name = once.key ?? key;
|
|
89
|
-
onceProps[name] = { prop: key, expiresAt: once.ttl ? Date.now() + once.ttl * 1000 : null };
|
|
90
|
-
if (heldOnce.has(name) && !only?.has(key) && !once.fresh)
|
|
91
|
-
continue;
|
|
92
102
|
}
|
|
93
|
-
|
|
103
|
+
// held by the client: not sent again on a visit (a partial reload sends what it asks for), still listed
|
|
104
|
+
const held = !partial && spec?.once && heldOnce.has(spec.once.key ?? key) && !spec.once.fresh;
|
|
105
|
+
if (spec?.defer && !partial) {
|
|
106
|
+
if (!held)
|
|
107
|
+
(deferred[spec.defer.group] ??= []).push(key);
|
|
108
|
+
if (spec.once)
|
|
109
|
+
listOnce(key, spec.once);
|
|
110
|
+
if (spec.merge || spec.scroll)
|
|
111
|
+
listMerge(key, spec);
|
|
94
112
|
continue;
|
|
95
|
-
if (kind === 'merge' && !reset.has(key)) {
|
|
96
|
-
const m = spec;
|
|
97
|
-
lists[m.strategy === 'append' ? 'mergeProps' : m.strategy === 'prepend' ? 'prependProps' : 'deepMergeProps'].push(key);
|
|
98
|
-
lists.matchPropsOn.push(...m.matchOn.map((field) => `${key}.${field}`));
|
|
99
113
|
}
|
|
100
|
-
if (
|
|
101
|
-
|
|
102
|
-
|
|
114
|
+
if (held) {
|
|
115
|
+
listOnce(key, spec.once);
|
|
116
|
+
continue;
|
|
103
117
|
}
|
|
118
|
+
if (spec?.once)
|
|
119
|
+
listOnce(key, spec.once);
|
|
120
|
+
if (spec?.merge || spec?.scroll)
|
|
121
|
+
listMerge(key, spec);
|
|
104
122
|
pending.push([key, value]);
|
|
105
123
|
}
|
|
106
124
|
const rescued = [];
|
|
@@ -110,7 +128,7 @@ export async function render(c, component, ...[props = {}, options = {}]) {
|
|
|
110
128
|
return [[key, await resolve(spec ? spec.value : value)]];
|
|
111
129
|
}
|
|
112
130
|
catch (error) {
|
|
113
|
-
if (!
|
|
131
|
+
if (!spec?.defer?.rescue)
|
|
114
132
|
throw error;
|
|
115
133
|
console.error(`[fondu] deferred prop "${key}" failed (rescued):`, error);
|
|
116
134
|
rescued.push(key);
|
|
@@ -123,10 +141,10 @@ export async function render(c, component, ...[props = {}, options = {}]) {
|
|
|
123
141
|
const scrollProps = {};
|
|
124
142
|
for (const [key, value] of pending) {
|
|
125
143
|
const spec = propSpec(value);
|
|
126
|
-
if (spec
|
|
144
|
+
if (spec?.scroll && key in page.props) {
|
|
127
145
|
const { currentPage, previousPage, nextPage } = page.props[key];
|
|
128
146
|
scrollProps[key] = {
|
|
129
|
-
pageName: spec.pageName,
|
|
147
|
+
pageName: spec.scroll.pageName,
|
|
130
148
|
currentPage,
|
|
131
149
|
previousPage,
|
|
132
150
|
nextPage,
|
|
@@ -152,7 +170,6 @@ export async function render(c, component, ...[props = {}, options = {}]) {
|
|
|
152
170
|
page.clearHistory = true;
|
|
153
171
|
if (options.preserveFragment)
|
|
154
172
|
page.preserveFragment = true;
|
|
155
|
-
c.header('Vary', 'X-Inertia', { append: true });
|
|
156
173
|
// a page is this visitor's: not stored by shared caches, revalidated by the browser (unless the route said otherwise)
|
|
157
174
|
if (!c.res.headers.has('Cache-Control'))
|
|
158
175
|
c.header('Cache-Control', 'private, no-cache');
|
|
@@ -166,13 +183,22 @@ export async function render(c, component, ...[props = {}, options = {}]) {
|
|
|
166
183
|
const versionCheck = async (c, next) => {
|
|
167
184
|
// an Inertia visit made by a client built from other assets: reload the page as a document
|
|
168
185
|
if (version && c.req.method === 'GET' && isInertia(c) && c.req.header('x-inertia-version') !== version) {
|
|
169
|
-
return c.body(null, 409, { 'X-Inertia-Location': c.req.url, 'X-Inertia-Version': version });
|
|
186
|
+
return c.body(null, 409, { 'X-Inertia-Location': c.req.url, 'X-Inertia-Version': version, Vary: 'X-Inertia' });
|
|
170
187
|
}
|
|
171
188
|
await next();
|
|
172
|
-
|
|
189
|
+
// a URL answers a visit and a document differently: caches keep them apart
|
|
190
|
+
c.header('Vary', 'X-Inertia', { append: true });
|
|
191
|
+
if (!isInertia(c))
|
|
192
|
+
return;
|
|
193
|
+
// an empty answer to a visit (an action that returns nothing to show): back to the page, as inertia-laravel does
|
|
194
|
+
if (c.res.status === 200 && !c.res.headers.has('x-inertia') && (await c.res.clone().text()) === '') {
|
|
195
|
+
c.res = back(c);
|
|
196
|
+
return;
|
|
197
|
+
}
|
|
198
|
+
if (c.res.status < 300 || c.res.status > 399)
|
|
173
199
|
return;
|
|
174
200
|
const to = c.res.headers.get('location') ?? '';
|
|
175
|
-
if (to.includes('#')) {
|
|
201
|
+
if (to.includes('#') && !isPrefetch(c)) {
|
|
176
202
|
// the browser's fetch would follow the redirect and drop the #fragment: the client visits it itself
|
|
177
203
|
const headers = new Headers(c.res.headers);
|
|
178
204
|
headers.delete('location');
|