fondu 0.5.1 → 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 +56 -31
- 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) {
|
|
@@ -72,36 +72,53 @@ export async function render(c, component, ...[props = {}, options = {}]) {
|
|
|
72
72
|
const deferred = {};
|
|
73
73
|
const onceProps = {};
|
|
74
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
|
+
};
|
|
75
92
|
for (const [key, value] of Object.entries(all)) {
|
|
76
93
|
const spec = propSpec(value);
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
const sent = kind === 'always' || (asked && !except?.has(key));
|
|
80
|
-
if (kind === 'defer' && !partial) {
|
|
81
|
-
;
|
|
82
|
-
(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)))
|
|
83
96
|
continue;
|
|
84
|
-
|
|
85
|
-
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);
|
|
86
101
|
continue;
|
|
87
|
-
if (kind === 'once') {
|
|
88
|
-
const once = spec;
|
|
89
|
-
const name = once.key ?? key;
|
|
90
|
-
onceProps[name] = { prop: key, expiresAt: once.ttl ? Date.now() + once.ttl * 1000 : null };
|
|
91
|
-
if (heldOnce.has(name) && !only?.has(key) && !once.fresh)
|
|
92
|
-
continue;
|
|
93
102
|
}
|
|
94
|
-
|
|
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);
|
|
95
112
|
continue;
|
|
96
|
-
if (kind === 'merge' && !reset.has(key)) {
|
|
97
|
-
const m = spec;
|
|
98
|
-
lists[m.strategy === 'append' ? 'mergeProps' : m.strategy === 'prepend' ? 'prependProps' : 'deepMergeProps'].push(key);
|
|
99
|
-
lists.matchPropsOn.push(...m.matchOn.map((field) => `${key}.${field}`));
|
|
100
113
|
}
|
|
101
|
-
if (
|
|
102
|
-
|
|
103
|
-
|
|
114
|
+
if (held) {
|
|
115
|
+
listOnce(key, spec.once);
|
|
116
|
+
continue;
|
|
104
117
|
}
|
|
118
|
+
if (spec?.once)
|
|
119
|
+
listOnce(key, spec.once);
|
|
120
|
+
if (spec?.merge || spec?.scroll)
|
|
121
|
+
listMerge(key, spec);
|
|
105
122
|
pending.push([key, value]);
|
|
106
123
|
}
|
|
107
124
|
const rescued = [];
|
|
@@ -111,7 +128,7 @@ export async function render(c, component, ...[props = {}, options = {}]) {
|
|
|
111
128
|
return [[key, await resolve(spec ? spec.value : value)]];
|
|
112
129
|
}
|
|
113
130
|
catch (error) {
|
|
114
|
-
if (!
|
|
131
|
+
if (!spec?.defer?.rescue)
|
|
115
132
|
throw error;
|
|
116
133
|
console.error(`[fondu] deferred prop "${key}" failed (rescued):`, error);
|
|
117
134
|
rescued.push(key);
|
|
@@ -124,10 +141,10 @@ export async function render(c, component, ...[props = {}, options = {}]) {
|
|
|
124
141
|
const scrollProps = {};
|
|
125
142
|
for (const [key, value] of pending) {
|
|
126
143
|
const spec = propSpec(value);
|
|
127
|
-
if (spec
|
|
144
|
+
if (spec?.scroll && key in page.props) {
|
|
128
145
|
const { currentPage, previousPage, nextPage } = page.props[key];
|
|
129
146
|
scrollProps[key] = {
|
|
130
|
-
pageName: spec.pageName,
|
|
147
|
+
pageName: spec.scroll.pageName,
|
|
131
148
|
currentPage,
|
|
132
149
|
previousPage,
|
|
133
150
|
nextPage,
|
|
@@ -153,7 +170,6 @@ export async function render(c, component, ...[props = {}, options = {}]) {
|
|
|
153
170
|
page.clearHistory = true;
|
|
154
171
|
if (options.preserveFragment)
|
|
155
172
|
page.preserveFragment = true;
|
|
156
|
-
c.header('Vary', 'X-Inertia', { append: true });
|
|
157
173
|
// a page is this visitor's: not stored by shared caches, revalidated by the browser (unless the route said otherwise)
|
|
158
174
|
if (!c.res.headers.has('Cache-Control'))
|
|
159
175
|
c.header('Cache-Control', 'private, no-cache');
|
|
@@ -167,13 +183,22 @@ export async function render(c, component, ...[props = {}, options = {}]) {
|
|
|
167
183
|
const versionCheck = async (c, next) => {
|
|
168
184
|
// an Inertia visit made by a client built from other assets: reload the page as a document
|
|
169
185
|
if (version && c.req.method === 'GET' && isInertia(c) && c.req.header('x-inertia-version') !== version) {
|
|
170
|
-
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' });
|
|
171
187
|
}
|
|
172
188
|
await next();
|
|
173
|
-
|
|
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)
|
|
174
199
|
return;
|
|
175
200
|
const to = c.res.headers.get('location') ?? '';
|
|
176
|
-
if (to.includes('#')) {
|
|
201
|
+
if (to.includes('#') && !isPrefetch(c)) {
|
|
177
202
|
// the browser's fetch would follow the redirect and drop the #fragment: the client visits it itself
|
|
178
203
|
const headers = new Headers(c.res.headers);
|
|
179
204
|
headers.delete('location');
|