@dokebi/template-inertia 0.4.0 → 0.4.1

package/AI.md

@@ -1,6 +1,6 @@
-# AI guide — @dokebi/template-inertia 0.4.0
+# AI guide — @dokebi/template-inertia 0.4.1
 
-An Inertia (v3) server adapter. The first request is answered with HTML (plus `script[data-page]` JSON), later `X-Inertia` requests with page JSON. It reads the Vite manifest to fill in scripts, styles and the version, and serves the build files itself. Optionally it server-renders the first HTML in the same process (SSR, D-0039). Vue and Vite are not server dependencies (they are the app's dev dependencies). Node >=24.0.0, core ^0.4.0, @dokebi/web (peer). Details are in the [README](README.md).
+An Inertia (v3) server adapter. The first request is answered with HTML (plus `script[data-page]` JSON), later `X-Inertia` requests with page JSON. It reads the Vite manifest to fill in scripts, styles and the version, and serves the build files itself. Optionally it server-renders the first HTML in the same process (SSR, D-0039). Vue and Vite are not server dependencies (they are the app's dev dependencies). Node >=24.0.0, core ^0.4.0, @dokebi/web ^0.4.1 (peer). Details are in the [README](README.md).
 
 ## 1. Install and project layout
 
@@ -46,6 +46,7 @@ route.post('/orders', async (request, reply, page) => {
 
 - `render(request, reply, component, props?, { encryptHistory?, clearHistory? }?)`: GET/HEAD only. The fifth argument sets history handling for this response (otherwise the scope setting and the session signal). Return or await it in the handler. component is `/`-separated parts matching `[A-Za-z0-9][A-Za-z0-9_-]*`.
 - props: JSON values, async lazy functions or the helpers of §3.1. A partial reload (`only`, `except`) evaluates only the selected ones; `errors` is always included. Non-JSON values (`undefined`, functions, symbols, `NaN`, `Infinity`) fail with `TypeError: Page props must be JSON serializable`, BigInt and cycles with `JSON.stringify`'s `TypeError`. Development and tests (`NODE_ENV` not `production`) check every value of the page; production checks only the top-level props and leaves the rest to `JSON.stringify` (D-0068; a 30 KB page went from 112 to 24 µs), so this mistake is caught during development.
+- Prop types in TypeScript: describe props with `type` aliases (`type Post = { id: number; title: string }`), not `interface`. An interface has no index signature, so TypeScript refuses it where `Json` is required (`npm run typecheck` fails with "Index signature for type 'string' is missing"); a `type` with the same fields is accepted (AI-M04).
 - `redirect(request, reply, localUrl)`: 302 for GET/HEAD, 303 for mutations; an Inertia `#` navigation gets 409 + `X-Inertia-Redirect`.
 - `location(request, reply, url)`: a local or external http(s) navigation. Inertia requests get 409 + `X-Inertia-Location`.
 
@@ -93,7 +94,7 @@ route.post('/orders', async (request, reply, page) => {
 
 **Refuse input with a validation error, never with your own 422.** A refused route schema (`schema.body`, `schema.querystring`) and `throw validationError({ name: 'Already taken' })` (from `@dokebi/web`) in the handler are the same 422 `VALIDATION_FAILED` with `fields` and `errors`. For an Inertia request (`X-Inertia`) this plugin answers it like Laravel does:
 
-- **With @dokebi/session**: the `errors` (`{ field: message }`) and the `old` input (the body's top-level strings, numbers and booleans, without password-, token-, secret- or card-like fields; left out above 8 KB) go into the session flash, and the answer is **303 back** to the `Referer` when it is this host (another origin is never followed), otherwise to `/` for a POST/PUT/PATCH/DELETE. The next page gets the flashed `errors` as its **`errors` prop** (under errors the handler passed itself) and `old` stays in the page `flash` (`usePage().flash.old`). The client keeps the form's own state on a non-GET visit, so `useForm().errors.name` just shows the message. A GET refused by its query schema without a usable referer (a redirect to itself would loop) gets the JSON below.
+- **With @dokebi/session**: the `errors` (`{ field: message }`) and the `old` input (the body's top-level strings, numbers and booleans, without password-, token-, secret- or card-like fields; left out above 8 KB) go into the session flash, and the answer is **303 back** to the `Referer` when it is this host (another origin is never followed), otherwise to `/` for a POST/PUT/PATCH/DELETE. The next page gets the flashed `errors` as its **`errors` prop** (under errors the handler passed itself) and `old` stays in the page `flash` (`usePage().flash.old`). The client keeps the form's own state on a non-GET visit, so `useForm().errors.name` just shows the message. A GET refused by its query schema without a usable referer (a redirect to itself would loop) gets the JSON below. The target and the old input come from @dokebi/web's form helpers (`formBackTarget`, `formOldInput`, 0.4.1), the same rules @dokebi/app uses for HTML forms.
 - **Without a session** the answer is the 422 JSON with `errors`: Inertia hands a non-page answer to `onHttpException`, so read it there: `form.post(url, { onHttpException: (response) => { form.setError(response.data.errors); return false } })`.
 - **Submit with `only`.** The GET after the 303 is a new visit, and a full visit must send every prop of the page again (Inertia replaces all props, so the server cannot trim it by itself). Pass the props the submit changes and Inertia keeps the partial headers across the redirect; `errors` always comes along:
 

package/README.md

@@ -1,4 +1,4 @@
-# @dokebi/template-inertia 0.4.0
+# @dokebi/template-inertia 0.4.1
 
 An optional package for Node >=24.0.0 and core ^0.4.0 (public on npm). Its ID is `dokebi-template-inertia` and it depends on `dokebi-web`. `@dokebi/web` is a peer dependency (not the pinned dependency it used to be). EJS, Vue and Vite are not installed as required dependencies of the server package.
 
@@ -47,7 +47,7 @@ Supported: the initial HTML, page navigation, shared/lazy/partial props, deferre
 
 ## Forms and validation
 
-Validation follows [D-0074](https://git.nyx-zone.com/dokebi/framework/-/blob/main/docs/decisions/D-0074-error-responses.md). A refused route schema and `throw validationError({ field: 'message' })` (from `@dokebi/web`) are the same 422 `VALIDATION_FAILED` answer. For an Inertia request with [@dokebi/session](https://git.nyx-zone.com/dokebi/framework/-/blob/main/plugins/dokebi-session/README.md) this plugin flashes `errors` (and `old` input without password-like fields) and answers 303 back to the same-origin `Referer`; the next page gets them in its `errors` prop, so `useForm().errors.name` shows the message. Without a session the answer is the 422 JSON with `errors` (read it in `onHttpException`).
+Validation follows [D-0074](https://git.nyx-zone.com/dokebi/framework/-/blob/main/docs/decisions/D-0074-error-responses.md). A refused route schema and `throw validationError({ field: 'message' })` (from `@dokebi/web`) are the same 422 `VALIDATION_FAILED` answer. For an Inertia request with [@dokebi/session](https://git.nyx-zone.com/dokebi/framework/-/blob/main/plugins/dokebi-session/README.md) this plugin flashes `errors` (and `old` input without password-like fields) and answers 303 back to the same-origin `Referer`; the next page gets them in its `errors` prop, so `useForm().errors.name` shows the message. Without a session the answer is the 422 JSON with `errors` (read it in `onHttpException`). The target and the old input follow @dokebi/web's form helpers (0.4.1, shared with @dokebi/app's HTML forms), so this version needs @dokebi/web ^0.4.1.
 
 Submit forms with `only` (the props the submit changes, for example `form.post('/posts', { only: ['posts'] })`): the GET after the redirect is a new visit, and a full visit must send every prop again because Inertia replaces all props, so the server cannot trim it by itself. Inertia keeps the partial headers across the redirect, and `errors` is always included. `dokebi check` warns about a submit without `only` (`inertia-form-only`).
 

package/dist/index.js

@@ -4,9 +4,9 @@ import { readFile, stat } from 'node:fs/promises';
 import { basename, dirname, extname, join, resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { types } from 'node:util';
-import { definePlugin, optionalDependency, } from '@dokebi/core';
+import { definePlugin, optionalDependency, providerDependency, } from '@dokebi/core';
 import { diagnostics } from '@dokebi/core/libraries';
-import { dependency as web } from '@dokebi/web/dependency';
+import { formBackTarget, formOldInput } from '@dokebi/web';
 import { viewEngines } from '@dokebi/web/points';
 import { InertiaError, InertiaUsageError } from './errors.js';
 import { options } from './options.js';
@@ -154,54 +154,16 @@ function hasCookie(header, name) {
     return text.split(';').some((part) => part.slice(0, part.indexOf('=')).trim() === name);
 }
 /**
- * Where a validation redirect goes (D-0074 §3): the `Referer` when it is this host (another
- * origin is never followed); otherwise `/` for a POST, PUT, PATCH or DELETE. A GET whose referer
- * is missing or is itself has no way back (a redirect to itself would fail again, forever).
+ * dokebi-web 0.4.1 or later: the validation redirect uses its form helpers (`formBackTarget`,
+ * `formOldInput`, D-0074 addendum 1), shared with @dokebi/app. A local descriptor instead of
+ * '@dokebi/web/dependency' (whose range stays ^0.4.0 for the plugins that need nothing newer).
  */
-function backTarget(request, host) {
-    const referer = request.headers.referer;
-    if (typeof referer === 'string' && referer.length <= 4096) {
-        let url;
-        if (URL.canParse(referer))
-            url = new URL(referer);
-        if (url &&
-            (url.protocol === 'http:' || url.protocol === 'https:') &&
-            url.host.toLowerCase() === host.toLowerCase()) {
-            const target = url.pathname + url.search;
-            if (!(['GET', 'HEAD'].includes(request.method) && target === request.url))
-                return target;
-        }
-    }
-    return ['GET', 'HEAD'].includes(request.method) ? undefined : '/';
-}
-/** Field names whose values never go into the session as old input. */
-const SECRET_FIELD = /pass(?:word|wd|phrase)?|secret|token|api[_-]?key|card|cvc|cvv|otp|pin$/i;
-/** Old input kept at most (as JSON text): a larger body is not flashed. */
-const OLD_MAX = 8192;
-/**
- * The old input of a refused form (D-0074 §3): the body's top-level strings, numbers, booleans
- * and nulls, without password-like fields; undefined when nothing is left or it is too large.
- */
-function oldInput(body) {
-    if (body === null || typeof body !== 'object' || Array.isArray(body))
-        return undefined;
-    const old = {};
-    let kept = 0;
-    for (const [key, value] of Object.entries(body)) {
-        if (key === '__proto__' || SECRET_FIELD.test(key))
-            continue;
-        if (value === null ||
-            typeof value === 'boolean' ||
-            (typeof value === 'number' && Number.isFinite(value)) ||
-            typeof value === 'string') {
-            old[key] = value;
-            kept++;
-        }
-    }
-    if (!kept || JSON.stringify(old).length > OLD_MAX)
-        return undefined;
-    return old;
-}
+const web = providerDependency({
+    name: 'dokebi-web',
+    version: '^0.4.1',
+    packageName: '@dokebi/web',
+    load: () => import('@dokebi/web'),
+});
 const session = optionalDependency({
     name: 'dokebi-session',
     version: '^0.4.0',
@@ -292,7 +254,7 @@ class InertiaRuntime {
                     // D-0074 §3: flash errors and old input, 303 back; the next page gets `errors`.
                     validation: async (request, reply, errors) => {
                         const current = sessionOf(request);
-                        const target = backTarget(request, server.requestHost(request));
+                        const target = formBackTarget(request, server.requestHost(request), '/');
                         if (!current?.flash || target === undefined) {
                             if (logger.isEnabled('debug'))
                                 logger.log('debug', 'Inertia validation answered as JSON', {
@@ -303,7 +265,7 @@ class InertiaRuntime {
                             return false;
                         }
                         await current.flash('errors', { ...errors });
-                        const old = oldInput(request.body);
+                        const old = formOldInput(request.body);
                         if (old)
                             await current.flash('old', old);
                         if (logger.isEnabled('debug'))
@@ -622,7 +584,7 @@ class InertiaRuntime {
 }
 export const createPlugin = definePlugin({
     name: 'dokebi-template-inertia',
-    version: '0.4.0',
+    version: '0.4.1',
     core: '^0.4.0',
     options,
     entry: parseEntry,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dokebi/template-inertia",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Inertia v3 server adapter for Dokebi: page JSON, Vite manifest assets and optional server-side rendering.",
   "keywords": [
     "dokebi",
@@ -41,7 +41,7 @@
   },
   "peerDependencies": {
     "@dokebi/core": "^0.4.0",
-    "@dokebi/web": "^0.4.0",
+    "@dokebi/web": "^0.4.1",
     "fastify": "^5.12.7"
   },
   "dokebi": {
@@ -51,7 +51,7 @@
     "dependencies": [
       {
         "name": "dokebi-web",
-        "version": "^0.4.0"
+        "version": "^0.4.1"
       },
       {
         "name": "dokebi-session",
@@ -114,7 +114,7 @@
   },
   "devDependencies": {
     "@dokebi/session": "0.4.0",
-    "@dokebi/web": "0.4.0"
+    "@dokebi/web": "0.4.1"
   },
   "publishConfig": {
     "access": "public",