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 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 as little of its own as it can: the server side of Inertia's protocol, file routes, typed pages and
13
- URLs, the document and error pages. Everything else is Hono's, Vite's and Inertia's.
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 writes a small
24
- app: a route, its page, the error page, Tailwind CSS, editor snippets and an `AGENTS.md` for coding agents.
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.
@@ -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 asks for it
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(value)` / `deepMerge(value)`: partial reloads merge into what the client holds
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 type PropSpec = {
25
- [PROP]: 'optional';
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
- strategy: 'append' | 'prepend' | 'deep';
39
- matchOn: string[];
40
- } | {
41
- [PROP]: 'once';
42
- value: Lazy<unknown>;
43
- key?: string;
44
- ttl?: number;
45
- fresh?: boolean;
46
- } | {
47
- [PROP]: 'scroll';
48
- value: Lazy<unknown>;
49
- pageName: string;
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 [PROP]?: never;
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 {};
@@ -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 asks for it
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(value)` / `deepMerge(value)`: partial reloads merge into what the client holds
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 make = (spec) => spec;
17
- export const optional = (value) => make({ [PROP]: 'optional', value });
18
- export const always = (value) => make({ [PROP]: 'always', value });
19
- export const defer = (value, { group = 'default', rescue = false } = {}) => make({ [PROP]: 'defer', value, group, rescue });
20
- export const once = (value, options = {}) => make({ [PROP]: 'once', value, ...options });
21
- export const scroll = (value, { pageName = 'page' } = {}) => make({ [PROP]: 'scroll', value, pageName });
22
- const merger = (strategy) => (value, options = {}) => make({ [PROP]: 'merge', value, strategy, matchOn: [options.matchOn ?? []].flat() });
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 = merger('deep');
26
- export const propSpec = (value) => typeof value === 'object' && value !== null && PROP in value ? value : null;
27
- export const kindOf = (spec) => spec[PROP];
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;
@@ -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 { kindOf, propSpec, resolve } from './props.js';
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
- const kind = spec && kindOf(spec);
78
- const asked = only ? only.has(key) : true;
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 (kind === 'optional' && !only?.has(key))
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
- if (!sent)
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 (kind === 'scroll' && !reset.has(key)) {
102
- // <InfiniteScroll> says which side it loads: the previous page goes before what the client holds
103
- lists[c.req.header('x-inertia-infinite-scroll-merge-intent') === 'prepend' ? 'prependProps' : 'mergeProps'].push(`${key}.data`);
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 (!(spec && kindOf(spec) === 'defer' && spec.rescue))
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 && kindOf(spec) === 'scroll' && key in page.props) {
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
- if (!isInertia(c) || c.res.status < 300 || c.res.status > 399)
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');
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "fondu",
3
- "version": "0.5.1",
3
+ "version": "0.6.0",
4
4
  "description": "A small meta-framework for full-stack React apps, built on Hono, Vite and Inertia. It runs on Bun, Cloudflare Workers and Node.",
5
5
  "keywords": [
6
6
  "bun",