@adonisjs/inertia 4.2.0 → 5.0.0-next.1

package/build/providers/inertia_provider.js

@@ -1,21 +1,86 @@
-import { t as InertiaManager } from "../inertia_manager-BGHA4cDP.js";
-import "../headers-DafWEpBh.js";
-import "../debug-CBMTuPUm.js";
+import { t as InertiaManager } from "../inertia_manager-BeqpMsuN.js";
 import { BriskRoute } from "@adonisjs/core/http";
+//#region providers/inertia_provider.ts
+/**
+* AdonisJS service provider for Inertia.js integration
+*
+* This provider handles the registration and configuration of Inertia.js
+* within an AdonisJS application. It sets up the middleware, Edge.js plugin,
+* and route macros needed for Inertia functionality.
+*
+* @example
+* ```js
+* // Automatically registered when package is installed
+* // Configuration in config/inertia.ts:
+*
+* import { defineConfig } from '@adonisjs/inertia'
+*
+* export default defineConfig({
+*   rootView: 'inertia_layout',
+*   ssr: { enabled: true }
+* })
+* ```
+*/
 var InertiaProvider = class {
+	app;
+	/**
+	* Creates a new InertiaProvider instance
+	*
+	* @param app - The AdonisJS application service instance
+	*/
 	constructor(app) {
 		this.app = app;
 	}
+	/**
+	* Registers the Inertia Edge.js plugin when Edge.js is available
+	*
+	* This method conditionally registers the Edge plugin that provides
+	* @inertia and @inertiaHead tags for rendering Inertia pages.
+	*
+	* @example
+	* ```edge
+	* {{-- Templates can then use --}}
+	* @inertia(page)
+	* @inertiaHead(page)
+	* ```
+	*/
 	async registerEdgePlugin() {
 		const edgeExports = await import("edge.js");
 		const { edgePluginInertia } = await import("../src/plugins/edge/plugin.js");
 		edgeExports.default.use(edgePluginInertia());
 	}
+	/**
+	* Registers the InertiaManager as a singleton in the IoC container
+	*
+	* This method sets up the core Inertia manager with the application's
+	* configuration and Vite integration. The manager handles page rendering,
+	* asset management, and SSR functionality.
+	*
+	* @example
+	* ```js
+	* // The manager is automatically available for injection:
+	* const inertiaManager = await app.container.make(InertiaManager)
+	* ```
+	*/
 	async register() {
 		this.app.container.singleton(InertiaManager, async (resolver) => {
 			return new InertiaManager(this.app.config.get("inertia", {}), await resolver.make("vite"));
 		});
 	}
+	/**
+	* Boot the provider by registering Edge plugin and route macros
+	*
+	* This method completes the Inertia setup by registering the Edge plugin
+	* and adding the renderInertia macro to BriskRoute for convenient route definitions.
+	*
+	* @example
+	* ```js
+	* // Routes can now use the renderInertia macro
+	* router.get('/dashboard', []).renderInertia('Dashboard', {
+	*   user: getCurrentUser()
+	* })
+	* ```
+	*/
 	async boot() {
 		await this.registerEdgePlugin();
 		BriskRoute.macro("renderInertia", function(template, props, viewProps) {
@@ -25,4 +90,5 @@ var InertiaProvider = class {
 		});
 	}
 };
+//#endregion
 export { InertiaProvider as default };

package/build/src/client/helpers.js

@@ -1,3 +1,30 @@
+//#region src/client/helpers.ts
+/**
+* Resolves a page component from a given path or array of paths by looking up
+* the component in the provided pages registry. Supports both direct promises
+* and lazy-loaded functions that return promises.
+*
+* @param path - The page path(s) to resolve. Can be a single string or array of strings
+* @param pages - Registry of page components where keys are paths and values are either promises or functions returning promises
+* @param layout - Optional layout component to assign to the resolved page
+* @returns Promise resolving to the page component
+*
+* @example
+* ```js
+* // Single path resolution
+* const component = await resolvePageComponent('Home', {
+*   'Home': () => import('./pages/Home.vue'),
+*   'About': () => import('./pages/About.vue')
+* })
+*
+* // Multiple path resolution (fallback)
+* const component = await resolvePageComponent(['Dashboard/Admin', 'Dashboard'], {
+*   'Dashboard': () => import('./pages/Dashboard.vue')
+* })
+* ```
+*
+* @throws Error When none of the provided paths can be resolved in the pages registry
+*/
 async function resolvePageComponent(path, pages, layout) {
 	for (const p of Array.isArray(path) ? path : [path]) {
 		const page = pages[p];
@@ -10,4 +37,5 @@ async function resolvePageComponent(path, pages, layout) {
 	}
 	throw new Error(`Page not found: "${path}"`);
 }
+//#endregion
 export { resolvePageComponent };

package/build/src/client/react/context.d.ts

@@ -11,7 +11,7 @@ import type { TuyauRegistry } from '@tuyau/core/types';
 export declare function TuyauProvider<R extends TuyauRegistry>(props: {
     children: React.ReactNode;
     client: Tuyau<R>;
-}): import("react/jsx-runtime").JSX.Element;
+}): React.JSX.Element;
 /**
  * Hook to access the Tuyau client from any component within a TuyauProvider.
  *

package/build/src/client/react/form.d.ts

@@ -27,7 +27,7 @@ export type FormProps<Route extends keyof Routes = keyof Routes> = FormRouteProp
  * for Inertia form submission when using route-based navigation.
  * Falls back to standard InertiaForm when action is provided directly.
  */
-declare function FormInner<Route extends keyof Routes>(props: FormProps<Route>, ref?: React.ForwardedRef<React.ElementRef<typeof InertiaForm>>): import("react/jsx-runtime").JSX.Element;
+declare function FormInner<Route extends keyof Routes>(props: FormProps<Route>, ref?: React.ForwardedRef<React.ElementRef<typeof InertiaForm>>): React.JSX.Element;
 /**
  * Type-safe Form component for Inertia.js form submissions.
  *

package/build/src/client/react/index.js

@@ -1,21 +1,80 @@
 import React from "react";
 import { jsx } from "react/jsx-runtime";
 import { Form as Form$1, Link as Link$1, router } from "@inertiajs/react";
+//#region src/client/react/context.tsx
+/**
+* React context for providing Tuyau client instance throughout the component tree
+*/
 const TuyauContext = React.createContext(null);
+/**
+* Provider component that makes the Tuyau client available to child components.
+*
+* This component should wrap your entire application or the part of your
+* application that needs access to type-safe routing functionality.
+*
+*/
 function TuyauProvider(props) {
 	return /* @__PURE__ */ jsx(TuyauContext.Provider, {
 		value: props.client,
 		children: props.children
 	});
 }
+/**
+* Hook to access the Tuyau client from any component within a TuyauProvider.
+*
+* Provides type-safe access to route generation and navigation utilities.
+* Must be used within a component tree wrapped by TuyauProvider.
+*
+* @returns The Tuyau client instance with full type safety
+* @throws Error if used outside of a TuyauProvider
+*/
 function useTuyau() {
 	const context = React.useContext(TuyauContext);
 	if (!context) throw new Error("You must wrap your app in a TuyauProvider");
 	return context;
 }
+//#endregion
+//#region src/client/react/router.ts
+/**
+* Custom hook providing type-safe navigation utilities for Inertia.js.
+*
+* Returns an enhanced router object with type-safe navigation methods
+* that automatically resolve route URLs and HTTP methods based on
+* your application's route definitions. Alternatively, you can use
+* direct href for navigation.
+*
+* @returns Router object with type-safe navigation methods
+*/
 function useRouter() {
 	const tuyau = useTuyau();
-	return { visit: (props, options) => {
+	return { 
+	/**
+	* Navigate to a route with type-safe parameters and options, or use
+	* direct href for navigation.
+	*
+	* When using route-based navigation, automatically resolves the route
+	* URL and HTTP method based on the route definition. When using direct
+	* href, passes through to Inertia's router.
+	*
+	* @param props - Route navigation parameters or direct href
+	* @param options - Optional Inertia visit options for controlling navigation behavior
+	*
+	* @example
+	* ```tsx
+	* // Navigate to a simple route
+	* router.visit({ route: 'dashboard' })
+	*
+	* // Navigate with parameters
+	* router.visit({ route: 'user.edit', routeParams: { id: userId } })
+	*
+	* // Navigate with direct href
+	* router.visit({ href: '/about' })
+	*
+	* // Navigate with direct href and method
+	* router.visit({ href: '/logout' }, { method: 'post' })
+	* ```
+	*/
+visit: (props, options) => {
 		if ("href" in props) return router.visit(props.href, options);
 		const routeInfo = tuyau.getRoute(props.route, { params: props.routeParams });
 		const url = routeInfo.url;
@@ -25,6 +84,17 @@ function useRouter() {
 		});
 	} };
 }
+//#endregion
+//#region src/client/react/link.tsx
+/**
+* Internal Link component implementation with forward ref support.
+* Resolves route parameters and generates the appropriate URL and HTTP method
+* for Inertia navigation when using route-based navigation.
+* Falls back to standard InertiaLink when href is provided directly.
+*
+* @param props - Link properties including route and parameters, or direct href
+* @param ref - Forward ref for the underlying InertiaLink component
+*/
 function LinkInner(props, ref) {
 	const tuyau = useTuyau();
 	if ("href" in props) return /* @__PURE__ */ jsx(Link$1, {
@@ -40,7 +110,37 @@ function LinkInner(props, ref) {
 		ref
 	});
 }
+/**
+* Type-safe Link component for Inertia.js navigation.
+*
+* Provides compile-time route validation and automatic parameter type checking
+* based on your application's route definitions. Automatically resolves the
+* correct URL and HTTP method for each route. Alternatively, you can use
+* the standard href prop for direct navigation.
+*
+* @example
+* ```tsx
+* // Link to a route without parameters
+* <Link route="home">Home</Link>
+*
+* // Link to a route with required parameters
+* <Link route="user.show" routeParams={{ id: 1 }}>
+*   View User
+* </Link>
+*
+* // Link with direct href
+* <Link href="/about">About</Link>
+* ```
+*/
 const Link = React.forwardRef(LinkInner);
+//#endregion
+//#region src/client/react/form.tsx
+/**
+* Internal Form component implementation with forward ref support.
+* Resolves route parameters and generates the appropriate URL and HTTP method
+* for Inertia form submission when using route-based navigation.
+* Falls back to standard InertiaForm when action is provided directly.
+*/
 function FormInner(props, ref) {
 	const tuyau = useTuyau();
 	if ("action" in props) return /* @__PURE__ */ jsx(Form$1, {
@@ -58,5 +158,48 @@ function FormInner(props, ref) {
 		ref
 	});
 }
+/**
+* Type-safe Form component for Inertia.js form submissions.
+*
+* Provides compile-time route validation and automatic parameter type checking
+* based on your application's route definitions. Automatically resolves the
+* correct URL and HTTP method for each route. Alternatively, you can use
+* the standard action prop for direct form submission.
+*
+* @example
+* ```tsx
+* // Form to a route without parameters
+* <Form route="users.store">
+*   {({ processing }) => (
+*     <>
+*       <input type="text" name="name" />
+*       <button type="submit" disabled={processing}>Create</button>
+*     </>
+*   )}
+* </Form>
+*
+* // Form to a route with required parameters
+* <Form route="users.update" routeParams={{ id: 1 }}>
+*   {({ errors }) => (
+*     <>
+*       <input type="text" name="name" />
+*       {errors.name && <div>{errors.name}</div>}
+*       <button type="submit">Update</button>
+*     </>
+*   )}
+* </Form>
+*
+* // Form with direct action
+* <Form action={{ url: '/users', method: 'post' }}>
+*   {({ processing }) => (
+*     <>
+*       <input type="text" name="name" />
+*       <button type="submit" disabled={processing}>Create</button>
+*     </>
+*   )}
+* </Form>
+* ```
+*/
 const Form = React.forwardRef(FormInner);
+//#endregion
 export { Form, Link, TuyauProvider, useRouter, useTuyau };

package/build/src/client/react/link.d.ts

@@ -30,7 +30,7 @@ export type LinkProps<Route extends keyof Routes = keyof Routes> = LinkRouteProp
  * @param props - Link properties including route and parameters, or direct href
  * @param ref - Forward ref for the underlying InertiaLink component
  */
-declare function LinkInner<Route extends keyof Routes>(props: LinkProps<Route>, ref?: React.ForwardedRef<React.ElementRef<typeof InertiaLink>>): import("react/jsx-runtime").JSX.Element;
+declare function LinkInner<Route extends keyof Routes>(props: LinkProps<Route>, ref?: React.ForwardedRef<React.ElementRef<typeof InertiaLink>>): React.JSX.Element;
 /**
  * Type-safe Link component for Inertia.js navigation.
  *

package/build/src/client/vue/index.js

@@ -1,6 +1,13 @@
 import { defineComponent, h, inject, provide } from "vue";
 import { Form as Form$1, Link as Link$1, router } from "@inertiajs/vue3";
+//#region src/client/vue/context.ts
+/**
+* Vue context for providing Tuyau client instance throughout the component tree
+*/
 const TuyauContext = Symbol("Tuyau");
+/**
+* Provider component that makes the Tuyau client available to child components.
+*/
 const TuyauProvider = defineComponent({
 	name: "TuyauProvider",
 	props: { client: {
@@ -12,14 +19,58 @@ const TuyauProvider = defineComponent({
 		return () => slots.default?.();
 	}
 });
+/**
+* Composable to access the Tuyau client from any component within a TuyauProvider.
+*/
 function useTuyau() {
 	const context = inject(TuyauContext, null);
 	if (!context) throw new Error("You must wrap your app in a TuyauProvider");
 	return context;
 }
+//#endregion
+//#region src/client/vue/router.ts
+/**
+* Composable providing type-safe navigation utilities for Inertia.js.
+*
+* Returns an enhanced router object with type-safe navigation methods
+* that automatically resolve route URLs and HTTP methods based on
+* your application's route definitions. Alternatively, you can use
+* direct href for navigation.
+*
+* @returns Router object with type-safe navigation methods
+*/
 function useRouter() {
 	const tuyau = useTuyau();
-	return { visit: (props, options) => {
+	return { 
+	/**
+	* Navigate to a route with type-safe parameters and options, or use
+	* direct href for navigation.
+	*
+	* When using route-based navigation, automatically resolves the route
+	* URL and HTTP method based on the route definition. When using direct
+	* href, passes through to Inertia's router.
+	*
+	* @param props - Route navigation parameters or direct href
+	* @param options - Optional Inertia visit options for controlling navigation behavior
+	*
+	* @example
+	* ```ts
+	* const router = useRouter()
+	*
+	* // Navigate to a simple route
+	* router.visit({ route: 'dashboard' })
+	*
+	* // Navigate with parameters
+	* router.visit({ route: 'user.edit', params: { id: userId } })
+	*
+	* // Navigate with direct href
+	* router.visit({ href: '/about' })
+	*
+	* // Navigate with direct href and method
+	* router.visit({ href: '/logout' }, { method: 'post' })
+	* ```
+	*/
+visit: (props, options) => {
 		if ("href" in props) return router.visit(props.href, options);
 		const routeInfo = tuyau.getRoute(props.route, { params: props.routeParams });
 		const url = routeInfo.url;
@@ -29,6 +80,25 @@ function useRouter() {
 		});
 	} };
 }
+//#endregion
+//#region src/client/vue/link.ts
+/**
+* Type-safe Link component for Inertia.js navigation.
+*
+* Supports both route-based navigation with automatic URL resolution
+* and direct href navigation for maximum flexibility.
+*
+* @example
+* ```vue
+* <!-- Route-based navigation -->
+* <Link route="users.index">Users</Link>
+* <Link route="users.show" :params="{ id: 1 }">View User</Link>
+*
+* <!-- Direct href navigation -->
+* <Link href="/about">About</Link>
+* <Link href="/logout" method="post">Logout</Link>
+* ```
+*/
 const Link = defineComponent({
 	name: "TuyauLink",
 	inheritAttrs: false,
@@ -63,6 +133,29 @@ const Link = defineComponent({
 		};
 	}
 });
+//#endregion
+//#region src/client/vue/form.ts
+/**
+* Type-safe Form component for Inertia.js form submissions.
+*
+* Supports both route-based form submission with automatic URL resolution
+* and direct action for maximum flexibility.
+*
+* @example
+* ```vue
+* <!-- Route-based form -->
+* <Form route="users.store" v-slot="{ processing }">
+*   <input type="text" name="name" />
+*   <button :disabled="processing">Create</button>
+* </Form>
+*
+* <!-- Direct action form -->
+* <Form :action="{ url: '/users', method: 'post' }" v-slot="{ processing }">
+*   <input type="text" name="name" />
+*   <button :disabled="processing">Create</button>
+* </Form>
+* ```
+*/
 const Form = defineComponent({
 	name: "TuyauForm",
 	inheritAttrs: false,
@@ -100,4 +193,5 @@ const Form = defineComponent({
 		};
 	}
 });
+//#endregion
 export { Form, Link, TuyauProvider, useRouter, useTuyau };

package/build/src/define_config.d.ts

@@ -14,7 +14,7 @@ import type { InertiaConfig, InertiaConfigInput } from './types.js';
  *   rootView: 'layouts/app',
  *   ssr: {
  *     enabled: true,
- *     bundle: 'build/ssr/ssr.js'
+ *     entrypoint: 'inertia/ssr.tsx'
  *   }
  * })
  * ```

package/build/src/headers.d.ts

@@ -58,4 +58,17 @@ export declare const InertiaHeaders: {
      * Used to identify which component is being partially reloaded.
      */
     readonly PartialComponent: "x-inertia-partial-component";
+    /**
+     * Header containing comma-separated list of once-keys the client already holds
+     * a fresh, cached value for. The server skips re-resolving those once props and
+     * omits their values from the response.
+     */
+    readonly ExceptOnceProps: "x-inertia-except-once-props";
+    /**
+     * Header sent by the client on infinite-scroll follow-up requests, declaring
+     * whether the incoming page should be appended (loading the next page) or
+     * prepended (loading the previous page) to the cached items. Absence is
+     * treated as `append`.
+     */
+    readonly InfiniteScrollMergeIntent: "x-inertia-infinite-scroll-merge-intent";
 };

package/build/src/inertia.d.ts

@@ -1,8 +1,8 @@
 import { type Vite } from '@adonisjs/vite';
 import type { HttpContext } from '@adonisjs/core/http';
 import { type ServerRenderer } from './server_renderer.js';
-import type { PageProps, PageObject, AsPageProps, RequestInfo, InertiaConfig, ComponentProps, SharedProps } from './types.js';
-import { defer, merge, always, optional, deepMerge } from './props.ts';
+import type { PageProps, FlashData, PageObject, AsPageProps, RequestInfo, InertiaConfig, ComponentProps, SharedProps, RescueListener } from './types.js';
+import { defer, once, merge, scroll, always, optional, deepMerge } from './props.ts';
 import { type AsyncOrSync } from '@poppinss/utils/types';
 /**
  * Main class used to interact with Inertia
@@ -28,6 +28,19 @@ export declare class Inertia<Pages> {
     #private;
     protected ctx: HttpContext;
     protected config: InertiaConfig;
+    /**
+     * Register a global listener for rescued deferred-prop errors. The listener
+     * receives the thrown error along with the failing prop path and the HTTP
+     * context. Call with no argument to restore the default logger-based reporter.
+     *
+     * @example
+     * ```ts
+     * Inertia.onRescue((error, { prop, ctx }) => {
+     *   ctx.logger.error({ err: error }, `deferred prop "${prop}" failed`)
+     * })
+     * ```
+     */
+    static onRescue(listener?: RescueListener): void;
     /**
      * Defer prop evaluation until client-side rendering
      *
@@ -83,6 +96,32 @@ export declare class Inertia<Pages> {
      * ```
      */
     deepMerge: typeof deepMerge;
+    /**
+     * Remember a prop on the client across visits. The server skips re-resolving
+     * it when the client reports a fresh cached value. Compose with
+     * `defer`/`optional`/`merge` via their `.once()` method.
+     *
+     * @example
+     * ```js
+     * {
+     *   lookups: inertia.once(() => loadLookupTables(), { expiresIn: '1h' })
+     * }
+     * ```
+     */
+    once: typeof once;
+    /**
+     * Create an infinite-scroll prop: a paginated value the client keeps extending
+     * as the user scrolls. The cursor is auto-derived from a transformer paginator,
+     * or supplied via a provider callback for other sources.
+     *
+     * @example
+     * ```js
+     * {
+     *   users: inertia.scroll(() => UserTransformer.paginate(rows, paginator.getMeta()))
+     * }
+     * ```
+     */
+    scroll: typeof scroll;
     /**
      * Creates a new Inertia instance
      *
@@ -167,6 +206,23 @@ export declare class Inertia<Pages> {
      * ```
      */
     share(sharedState: PageProps | (() => AsyncOrSync<PageProps>)): this;
+    /**
+     * Register the provider for the page object's top-level `flash` field.
+     *
+     * Unlike shared state, the resolved value is emitted as a sibling of `props`
+     * (not merged into them). The Inertia middleware calls this with its `flash()`
+     * method; the last registration wins. When no provider is registered, the
+     * `flash` field is omitted from the page object entirely.
+     *
+     * @param provider - Callback resolving the flash bag for this response
+     * @returns The Inertia instance for method chaining
+     *
+     * @example
+     * ```js
+     * inertia.flash(() => ctx.session.flashMessages.all())
+     * ```
+     */
+    flash(provider: () => AsyncOrSync<FlashData>): this;
     /**
      * Build a page object with processed props and metadata
      *

package/build/src/inertia_middleware.d.ts

@@ -1,6 +1,6 @@
 import type { HttpContext } from '@adonisjs/core/http';
 import { type Inertia } from './inertia.js';
-import type { InertiaPages, PageProps } from './types.js';
+import type { FlashData, InertiaPages, PageProps } from './types.js';
 declare module '@adonisjs/core/http' {
     interface HttpContext {
         inertia: Inertia<InertiaPages>;
@@ -32,7 +32,16 @@ export default abstract class BaseInertiaMiddleware {
      * them according to Inertia's error bag conventions. Supports both simple
      * error objects and error bags for multi-form scenarios.
      *
+     * By default every field collapses to its **first** message (`string`),
+     * matching Inertia's default error shape. Pass `{ allMessages: true }` to opt
+     * into the all-messages mode, where every field is emitted as a `string[]` —
+     * including single-message fields, which arrive as a one-element array. The
+     * shape is uniform across the response: never a mix of strings and arrays. An
+     * app running in all-messages mode types the client globally via
+     * `declare module '@inertiajs/core' { interface InertiaConfig { errorValueType: string[] } }`.
+     *
      * @param ctx - The HTTP context containing session data
+     * @param options - When `allMessages` is true, emit every field as `string[]`
      * @returns Formatted validation errors, either as a simple object or error bags
      *
      * @example
@@ -40,11 +49,19 @@ export default abstract class BaseInertiaMiddleware {
      * const errors = middleware.getValidationErrors(ctx)
      * // Returns: { email: 'Email is required', password: 'Password too short' }
      * // Or with error bags: { login: { email: 'Email is required' } }
+     *
+     * const allErrors = middleware.getValidationErrors(ctx, { allMessages: true })
+     * // Returns: { email: ['Email is required'], password: ['Too short', 'Needs a number'] }
      * ```
      */
     getValidationErrors(ctx: HttpContext): Record<string, string> | {
         [errorBag: string]: Record<string, string>;
     };
+    getValidationErrors(ctx: HttpContext, options: {
+        allMessages: true;
+    }): Record<string, string[]> | {
+        [errorBag: string]: Record<string, string[]>;
+    };
     /**
      * Share data with all Inertia pages
      *
@@ -65,6 +82,25 @@ export default abstract class BaseInertiaMiddleware {
      * ```
      */
     abstract share?(ctx: HttpContext): PageProps | Promise<PageProps>;
+    /**
+     * Provide the first-class flash bag sent to every Inertia page under the
+     * top-level `flash` field (a sibling of `props`, not merged into them).
+     *
+     * Typically reads the framework's session flash messages. Optional — when the
+     * method is not defined, no `flash` field is emitted. Type the return value to
+     * get end-to-end type safety via `InferFlashData`.
+     *
+     * @param ctx - The HTTP context object
+     * @returns The flash bag for the current response
+     *
+     * @example
+     * ```js
+     * flash(ctx) {
+     *   return ctx.session.flashMessages.all()
+     * }
+     * ```
+     */
+    flash?(ctx: HttpContext): FlashData | Promise<FlashData>;
     /**
      * Initialize the Inertia instance for the current request
      *