@adonisjs/inertia 5.0.0-next.0 → 5.0.0-next.1

package/build/src/inertia_middleware.js

@@ -1,38 +1,104 @@
-import { t as InertiaManager } from "../inertia_manager-BdcjpKFf.js";
-import { t as InertiaHeaders } from "../headers-DafWEpBh.js";
-import { t as debug_default } from "../debug-CBMTuPUm.js";
+import { t as InertiaManager } from "../inertia_manager-BeqpMsuN.js";
+import { t as InertiaHeaders } from "../headers-B-5pLwyD.js";
+import { t as debug_default } from "../debug-Ca0ekg3M.js";
+//#region src/inertia_middleware.ts
+/**
+* HTTP methods that require special redirect handling
+* These methods should use 303 status code for redirects
+*/
 const MUTATION_METHODS = [
 	"PUT",
 	"PATCH",
 	"DELETE"
 ];
+/**
+* Base middleware class for handling Inertia.js requests
+*
+* This middleware handles the initialization of the Inertia instance,
+* manages request headers, handles redirects for mutation methods,
+* and implements asset versioning.
+*
+* @example
+* ```ts
+* export default class InertiaMiddleware extends BaseInertiaMiddleware {
+*   async share() {
+*     return {
+*       user: ctx.auth?.user
+*     }
+*   }
+* }
+* ```
+*/
 var BaseInertiaMiddleware = class {
-	getValidationErrors(ctx) {
+	getValidationErrors(ctx, options) {
 		if (!ctx.session) return {};
+		const allMessages = options?.allMessages === true;
 		const inputErrors = ctx.session.flashMessages.get("inputErrorsBag", {});
 		const errors = Object.entries(inputErrors).reduce((result, [field, messages]) => {
-			result[field] = Array.isArray(messages) ? messages[0] : messages;
+			if (allMessages) result[field] = Array.isArray(messages) ? messages : [messages];
+			else result[field] = Array.isArray(messages) ? messages[0] : messages;
 			return result;
 		}, {});
 		const errorBag = ctx.request.header(InertiaHeaders.ErrorBag);
 		if (errorBag) return { [errorBag]: errors };
 		return errors;
 	}
+	/**
+	* Initialize the Inertia instance for the current request
+	*
+	* This method creates an Inertia instance and attaches it to the
+	* HTTP context, making it available throughout the request lifecycle.
+	*
+	* @param ctx - The HTTP context object
+	*
+	* @example
+	* ```ts
+	* await middleware.init(ctx)
+	* ```
+	*/
 	async init(ctx) {
 		debug_default("initiating inertia");
 		ctx.inertia = (await ctx.containerResolver.make(InertiaManager)).createForRequest(ctx);
 		if (this.share) ctx.inertia.share(() => this.share(ctx));
+		if (this.flash) ctx.inertia.flash(() => this.flash(ctx));
 	}
+	/**
+	* Clean up and finalize the Inertia response
+	*
+	* This method handles the final processing of Inertia requests including:
+	* - Setting appropriate response headers
+	* - Handling redirects for mutation methods (PUT/PATCH/DELETE)
+	* - Managing asset versioning conflicts
+	*
+	* @param ctx - The HTTP context object
+	*
+	* @example
+	* ```ts
+	* await middleware.dispose(ctx)
+	* ```
+	*/
 	dispose(ctx) {
 		const requestInfo = ctx.inertia.requestInfo();
 		if (!requestInfo.isInertiaRequest) return;
 		debug_default("disposing as inertia request");
 		ctx.response.header("Vary", InertiaHeaders.Inertia);
+		/**
+		* When redirecting a PUT/PATCH/DELETE request, we must use a 303
+		* status code instead of a 302 to force the browser to use a GET
+		* request after redirecting.
+		*
+		* See https://inertiajs.com/redirects
+		*/
 		const method = ctx.request.method();
 		if (ctx.response.getStatus() === 302 && MUTATION_METHODS.includes(method)) {
 			debug_default("upgrading response status from 302 to 303");
 			ctx.response.status(303);
 		}
+		/**
+		* Handle version change
+		*
+		* See https://inertiajs.com/the-protocol#asset-versioning
+		*/
 		const version = ctx.inertia.getVersion();
 		const clientVersion = requestInfo.version ?? "";
 		if (method === "GET" && clientVersion !== version) {
@@ -44,4 +110,5 @@ var BaseInertiaMiddleware = class {
 		}
 	}
 };
+//#endregion
 export { BaseInertiaMiddleware as default };

package/build/src/plugins/edge/plugin.js

@@ -1,17 +1,72 @@
-import { t as debug_default } from "../../../debug-CBMTuPUm.js";
+import { t as debug_default } from "../../../debug-Ca0ekg3M.js";
 import { EdgeError } from "edge-error";
+//#region src/plugins/edge/utils.ts
+/**
+* Validates that an AST expression is one of the allowed expression types
+*
+* This utility function is used during Edge template compilation to ensure
+* that only specific expression types are allowed in certain contexts.
+*
+* @param expression - The AST expression to validate
+* @param expressions - Array of allowed expression type names
+* @param errorCallback - Function to call when validation fails
+*
+* @example
+* ```js
+* // Ensure expression is either a literal or identifier
+* isSubsetOf(astNode, ['Literal', 'Identifier'], () => {
+*   throw new Error('Invalid expression type')
+* })
+*
+* // Allow only object expressions
+* isSubsetOf(astNode, ['ObjectExpression'], () => {
+*   throw new EdgeError('Expected object expression')
+* })
+* ```
+*/
 function isSubsetOf(expression, expressions, errorCallback) {
 	if (!expressions.includes(expression.type)) errorCallback();
 }
+//#endregion
+//#region src/plugins/edge/tags.ts
+/**
+* Edge tag that generates the root element for Inertia.js applications
+*
+* The @inertia tag creates a container element with encoded page data that Inertia.js
+* uses to hydrate the client-side application. Supports customization through attributes.
+*
+* @example
+* ```edge
+* {{-- Basic usage with default div element and id="app" --}}
+* @inertia()
+*
+* {{-- Custom element and attributes --}}
+* @inertia({ as: 'main', id: 'app-root', class: 'min-h-screen' })
+*
+* {{-- Results in: --}}
+* {{-- <main id="app-root" class="min-h-screen" data-page="{...encoded page data...}"></main> --}}
+* ```
+*
+* Supported attributes:
+* - `as`: HTML tag name for the root element (defaults to 'div')
+* - `id`: Element ID (defaults to 'app')
+* - `class`: CSS class names for the element
+*/
 const inertiaTag = {
 	block: false,
 	tagName: "inertia",
 	seekable: true,
 	compile(parser, buffer, { filename, loc, properties }) {
+		/**
+		* Handle case where no arguments are passed to the tag
+		*/
 		if (properties.jsArg.trim() === "") {
 			buffer.writeExpression(`out += state.inertia(state.page)`, filename, loc.start.line);
 			return;
 		}
+		/**
+		* Get AST for the arguments and ensure it is a valid object expression
+		*/
 		properties.jsArg = `(${properties.jsArg})`;
 		const parsed = parser.utils.transformAst(parser.utils.generateAST(properties.jsArg, loc, filename), filename, parser);
 		isSubsetOf(parsed, ["ObjectExpression"], () => {
@@ -22,10 +77,34 @@ const inertiaTag = {
 				filename
 			});
 		});
+		/**
+		* Stringify the object expression and pass it to the `inertia` helper
+		*/
 		const attributes = parser.utils.stringify(parsed);
 		buffer.outputExpression(`state.inertia(state.page, ${attributes})`, filename, loc.start.line, false);
 	}
 };
+/**
+* Edge tag that renders server-side rendered head content for Inertia.js
+*
+* The @inertiaHead tag outputs head tags (title, meta, etc.) that were generated
+* during server-side rendering. Only relevant when SSR is enabled.
+*
+* @example
+* ```edge
+* <!DOCTYPE html>
+* <html>
+* <head>
+*   <meta charset="utf-8">
+*   <meta name="viewport" content="width=device-width, initial-scale=1">
+*   @inertiaHead()
+* </head>
+* <body>
+*   @inertia()
+* </body>
+* </html>
+* ```
+*/
 const inertiaHeadTag = {
 	block: false,
 	tagName: "inertiaHead",
@@ -34,9 +113,44 @@ const inertiaHeadTag = {
 		buffer.outputExpression("state.inertiaHead(state.page)", filename, loc.start.line, false);
 	}
 };
+//#endregion
+//#region src/plugins/edge/plugin.ts
+/**
+* Edge.js plugin that registers Inertia.js tags and global functions
+*
+* This plugin adds the @inertia and @inertiaHead tags to Edge templates,
+* along with global helper functions for rendering Inertia pages.
+*
+* @returns Edge plugin function that registers Inertia functionality
+*
+* @example
+* ```js
+* // Configure in config/edge.ts
+* import { edgePluginInertia } from '@adonisjs/inertia/plugins/edge'
+*
+* edge.use(edgePluginInertia())
+* ```
+*
+* @example
+* ```edge
+* {{-- Use in Edge templates --}}
+* <!DOCTYPE html>
+* <html>
+* <head>
+*   @inertiaHead()
+* </head>
+* <body>
+*   @inertia({ id: 'app', class: 'min-h-screen' })
+* </body>
+* </html>
+* ```
+*/
 const edgePluginInertia = () => {
 	return (edge) => {
 		debug_default("sharing globals and inertia tags with edge");
+		/**
+		* Register the `inertia` global used by the `@inertia` tag
+		*/
 		edge.global("inertia", (page = {}, attributes = {}) => {
 			if (page.ssrBody) return page.ssrBody;
 			const className = attributes?.class ? ` class="${attributes.class}"` : "";
@@ -44,12 +158,19 @@ const edgePluginInertia = () => {
 			const tag = attributes?.as || "div";
 			return `<script data-page="${id}" type="application/json">${JSON.stringify(page).replace(/\//g, "\\/")}<\/script><${tag} id="${id}"${className}></${tag}>`;
 		});
+		/**
+		* Register the `inertiaHead` global used by the `@inertiaHead` tag
+		*/
 		edge.global("inertiaHead", (page) => {
 			const { ssrHead = [] } = page || {};
 			return ssrHead.join("\n");
 		});
+		/**
+		* Register tags
+		*/
 		edge.registerTag(inertiaHeadTag);
 		edge.registerTag(inertiaTag);
 	};
 };
+//#endregion
 export { edgePluginInertia };

package/build/src/plugins/japa/api_client.js

@@ -1,11 +1,53 @@
-import { t as InertiaHeaders } from "../../../headers-DafWEpBh.js";
+import { t as InertiaHeaders } from "../../../headers-B-5pLwyD.js";
 import { ApiRequest, ApiResponse } from "@japa/api-client";
+//#region src/plugins/japa/api_client.ts
+/**
+* Ensure the response is an inertia response, otherwise throw an error
+*
+* @throws Error when the response is not an Inertia response
+*/
 function ensureIsInertiaResponse() {
 	if (!this.header("x-inertia")) throw new Error("Not an Inertia response. Make sure to use \"withInertia()\" method when making the request");
 }
 function ensureHasAssert(assertLib) {
 	if (!assertLib) throw new Error("Response assertions are not available. Make sure to install the @japa/assert plugin");
 }
+/**
+* Japa plugin that extends the API client with Inertia.js testing capabilities
+*
+* This plugin adds methods to ApiRequest and ApiResponse classes to support
+* testing Inertia applications, including partial reloads and response assertions.
+*
+* @param app - The AdonisJS application service instance
+* @returns Japa plugin function
+*
+* @example
+* ```js
+* // Configure in tests/bootstrap.ts
+* import { inertiaApiClient } from '@adonisjs/inertia/plugins/japa/api_client'
+*
+* export const plugins: Config['plugins'] = [
+*   assert(),
+*   apiClient(app),
+*   inertiaApiClient(app)
+* ]
+* ```
+*
+* @example
+* ```js
+* // Use in tests
+* test('renders dashboard page', async ({ client }) => {
+*   const response = await client
+*     .get('/dashboard')
+*     .withInertia()
+*
+*   response.assertInertiaComponent('Dashboard')
+*   response.assertInertiaPropsContains({
+*     user: { name: 'John' }
+*   })
+* })
+* ```
+*/
 function inertiaApiClient(app) {
 	return async () => {
 		const inertiaConfig = app.config.get("inertia");
@@ -20,6 +62,9 @@ function inertiaApiClient(app) {
 			this.header(InertiaHeaders.PartialOnly, data.join(","));
 			return this;
 		});
+		/**
+		* Response getters
+		*/
 		ApiResponse.getter("inertiaComponent", function() {
 			ensureIsInertiaResponse.call(this);
 			return this.body().component;
@@ -28,6 +73,9 @@ function inertiaApiClient(app) {
 			ensureIsInertiaResponse.call(this);
 			return this.body().props;
 		});
+		/**
+		* Response assertions
+		*/
 		ApiResponse.macro("assertInertiaComponent", function(component) {
 			ensureIsInertiaResponse.call(this);
 			ensureHasAssert(this.assert);
@@ -48,4 +96,5 @@ function inertiaApiClient(app) {
 		});
 	};
 }
+//#endregion
 export { inertiaApiClient };

package/build/src/props.d.ts

@@ -1,5 +1,5 @@
 import { type AsyncOrSync } from '@adonisjs/core/types/common';
-import { type DeferProp, type PageProps, type AlwaysProp, type OptionalProp, type MergeableProp, type ComponentProps, type UnPackedPageProps } from './types.ts';
+import { type DeferProp, type DeferOptions, type OnceProp, type PageProps, type AlwaysProp, type ScrollProp, type ScrollValue, type OnceContext, type OnceOptions, type OncePropsMap, type OptionalProp, type MergeableProp, type ComponentProps, type ScrollMetaData, type UnPackedPageProps, type ScrollPropsProvider, type ScrollResolvedValue } from './types.ts';
 import { type ContainerResolver } from '@adonisjs/core/container';
 /**
  * Creates a deferred prop that is never included in standard visits but must be shared with
@@ -9,6 +9,9 @@ import { type ContainerResolver } from '@adonisjs/core/container';
  * specifically requested by the client.
  *
  * @param fn - Function that computes the prop value when requested
+ * @param options - A group name string, or `{ group, rescue }`. Pass
+ *   `{ rescue: true }` to catch resolution errors, omit the prop, and report its
+ *   path via `rescuedProps` so the client can render the `<Deferred>` rescue slot.
  * @returns A deferred prop object with compute and merge capabilities
  *
  * @example
@@ -23,9 +26,12 @@ import { type ContainerResolver } from '@adonisjs/core/container';
  *   user: user,
  *   stats: userStats // Only loaded when explicitly requested
  * })
+ *
+ * // Rescue resolution failures instead of erroring the whole reload
+ * const permissions = defer(() => Permission.all(), { rescue: true })
  * ```
  */
-export declare function defer<T extends UnPackedPageProps>(fn: () => AsyncOrSync<T>, group?: string): DeferProp<T>;
+export declare function defer<T extends UnPackedPageProps>(fn: () => AsyncOrSync<T>, groupOrOptions?: string | DeferOptions): DeferProp<T>;
 /**
  * Creates an optional prop that is never included in standard visits and can only be
  * explicitly requested by the client. Unlike deferred props, optional props are not
@@ -132,6 +138,81 @@ export declare function merge<T extends UnPackedPageProps | DeferProp<UnPackedPa
  * ```
  */
 export declare function deepMerge<T extends UnPackedPageProps | DeferProp<UnPackedPageProps>>(value: T): MergeableProp<T>;
+/**
+ * Creates a once prop: a prop the server computes, the client caches across
+ * visits, and the server skips re-resolving on later visits where the client
+ * reports it already holds a fresh value.
+ *
+ * Use the `.once()` chaining method to compose with `defer`/`optional`/`merge`;
+ * use this standalone form for plain values and lazy callbacks.
+ *
+ * @param inner - The value, callback, or inner prop wrapper to remember
+ * @param options - Custom key, expiry, and force-fresh options
+ * @returns A once prop wrapper carrying caching metadata
+ *
+ * @example
+ * ```js
+ * // Plain value, no expiry
+ * return inertia.render('dashboard', {
+ *   lookups: inertia.once(() => loadLookupTables())
+ * })
+ *
+ * // Custom key + expiry, composed with a deferred prop
+ * return inertia.render('dashboard', {
+ *   stats: inertia.defer(() => heavyStats()).once({ key: 'stats', expiresIn: '1h' })
+ * })
+ * ```
+ */
+export declare function once<T>(value: T, options?: OnceOptions): OnceProp<T>;
+/**
+ * Creates an infinite-scroll prop: a mergeable, paginated value the client keeps
+ * extending as the user scrolls. The server labels the value's `data` array for
+ * keyed/directional merging (driven by the client's merge-intent header) and
+ * emits a pagination cursor under the page object's `scrollProps`.
+ *
+ * The value is a transformer paginator (cursor auto-derived from its metadata)
+ * or any `{ data, ... }`-shaped value, given directly or via a callback. For a
+ * non-paginator value, pass a `scrollProps` provider that computes the cursor
+ * from the resolved value. Chain `.deferred()` to skip the first page on the
+ * initial load, and `.matchOn()` to dedupe overlapping pages by a key.
+ *
+ * @param value - A transformer paginator or `{ data }` value (or a callback resolving to one)
+ * @param provider - Computes the cursor from the resolved value; omit for transformer paginators
+ * @returns A scroll prop wrapper carrying merge + pagination metadata
+ *
+ * @example
+ * ```js
+ * // Transformer paginator — cursor auto-derived from its metadata
+ * return inertia.render('users/index', {
+ *   users: inertia.scroll(() => UserTransformer.paginate(rows, paginator.getMeta()))
+ * })
+ *
+ * // Custom / cursor source — cursor computed by a provider
+ * return inertia.render('feed', {
+ *   posts: inertia.scroll(() => feed, (value) => ({
+ *     pageName: 'cursor',
+ *     currentPage: value.cursor,
+ *     nextPage: value.next,
+ *     previousPage: null,
+ *   }))
+ * })
+ * ```
+ */
+export declare function scroll<Item>(value: ScrollValue<Item> | (() => AsyncOrSync<ScrollValue<Item>>), provider?: ScrollPropsProvider<ScrollResolvedValue<Item>>): ScrollProp<Item>;
+/**
+ * Type guard that checks if a prop value is a scroll prop.
+ *
+ * @param propValue - The object to check for scroll prop characteristics
+ * @returns True if the prop value is a scroll prop
+ */
+export declare function isScrollProp(propValue: Object): propValue is ScrollProp<any, boolean>;
+/**
+ * Type guard that checks if a prop value is a once prop.
+ *
+ * @param propValue - The object to check for once prop characteristics
+ * @returns True if the prop value is a once prop
+ */
+export declare function isOnceProp(propValue: Object): propValue is OnceProp<any>;
 /**
  * Type guard that checks if a prop value is a deferred prop.
  *
@@ -212,37 +293,29 @@ export declare function isAlwaysProp<T extends UnPackedPageProps>(propValue: Obj
  * ```
  */
 export declare function isOptionalProp<T extends UnPackedPageProps>(propValue: Object): propValue is OptionalProp<T>;
-/**
- * Builds props for standard (non-partial) Inertia visits.
- *
- * This function processes page props and categorizes them based on their type:
- * - Deferred props: Skipped but communicated to client
- * - Optional props: Skipped entirely
- * - Always props: Always included
- * - Mergeable props: Included and marked for merging
- * - Regular props: Included normally
- *
- * @param pageProps - The page props to process
- * @param containerResolver - Container resolver for dependency injection
- * @returns Promise resolving to object containing processed props, deferred props list, and merge props list
- *
- * @example
- * ```js
- * const result = await buildStandardVisitProps({
- *   user: { name: 'John' },
- *   posts: defer(() => getPosts()),
- *   settings: merge({ theme: 'dark' })
- * })
- * // Returns: { props: { user: {...} }, deferredProps: { default: ['posts'] }, mergeProps: ['settings'] }
- * ```
- */
-export declare function buildStandardVisitProps(pageProps: PageProps, containerResolver: ContainerResolver<any>): Promise<{
+export declare function buildStandardVisitProps(pageProps: PageProps, containerResolver: ContainerResolver<any>, onceContext?: OnceContext, resetProps?: Set<string>, mergeIntent?: 'append' | 'prepend'): Promise<{
     props: ComponentProps;
     mergeProps: string[];
     deepMergeProps: string[];
+    prependProps: string[];
+    matchPropsOn: string[];
     deferredProps: {
         [group: string]: string[];
     };
+    onceProps: OncePropsMap;
+    scrollProps: {
+        [prop: string]: ScrollMetaData;
+    };
+    /**
+     * Deferred props are never computed on a standard visit, so nothing can be
+     * rescued here. Emitted for a uniform shape with the partial-reload builder
+     * and to match the always-present v3 `rescuedProps` wire field.
+     */
+    rescuedProps: string[];
+    rescuedErrors: {
+        prop: string;
+        error: unknown;
+    }[];
 }>;
 /**
  * Builds props for partial (cherry-picked) Inertia requests.
@@ -268,9 +341,26 @@ export declare function buildStandardVisitProps(pageProps: PageProps, containerR
  * // Returns: { props: { posts: [...], stats: [...] }, mergeProps: [], deferredProps: {} }
  * ```
  */
-export declare function buildPartialRequestProps(pageProps: PageProps, cherryPickProps: string[], containerResolver: ContainerResolver<any>): Promise<{
+export declare function buildPartialRequestProps(pageProps: PageProps, cherryPickProps: string[], containerResolver: ContainerResolver<any>, 
+/**
+ * Partial reloads ignore the client's once cache entirely (see the once
+ * branch below), so this builder takes only the reference clock for expiry —
+ * not the full once context.
+ */
+now?: number, resetProps?: Set<string>, mergeIntent?: 'append' | 'prepend'): Promise<{
     props: ComponentProps;
     mergeProps: string[];
     deepMergeProps: string[];
+    prependProps: string[];
+    matchPropsOn: string[];
     deferredProps: {};
+    onceProps: OncePropsMap;
+    scrollProps: {
+        [prop: string]: ScrollMetaData;
+    };
+    rescuedProps: string[];
+    rescuedErrors: {
+        prop: string;
+        error: unknown;
+    }[];
 }>;

package/build/src/symbols.d.ts

@@ -23,3 +23,36 @@ export declare const DEFERRED_PROP: unique symbol;
  * Deep merging recursively merges nested objects and arrays.
  */
 export declare const DEEP_MERGE: unique symbol;
+/**
+ * Symbol carrying the direction of a shallow array merge. When `true` the client
+ * prepends the incoming items (`prependProps`); when `false` it appends them
+ * (`mergeProps`). Ignored for deep merges — the client deep-merge path has no
+ * direction.
+ */
+export declare const MERGE_PREPEND: unique symbol;
+/**
+ * Symbol carrying the match path (relative to the prop) used for keyed merges.
+ * When set, the client dedupes/replaces array items by this field rather than
+ * concatenating. Emitted on the wire as `"<propPath>.<matchOn>"` in `matchPropsOn`.
+ */
+export declare const MERGE_MATCH_ON: unique symbol;
+/**
+ * Symbol used to mark props that are remembered by the client across visits.
+ * The server skips re-resolving a once prop when the client reports it already
+ * holds the value, and always emits the prop's caching metadata.
+ */
+export declare const ONCE_PROP: unique symbol;
+/**
+ * Symbol used to mark an infinite-scroll prop. Scroll props layer pagination
+ * metadata (emitted under the page object's `scrollProps`) on top of the keyed
+ * and directional merge primitive, so the client can continuously load pages as
+ * the user scrolls.
+ */
+export declare const SCROLL_PROP: unique symbol;
+/**
+ * Type-only discriminant carrying whether a scroll prop has been deferred via
+ * `.deferred()`. A deferred scroll prop is absent on the initial load, so this
+ * flag lets the type system treat it as optional — rejecting it on a required
+ * client prop, exactly like `defer()`. It is never set at runtime.
+ */
+export declare const SCROLL_DEFERRED: unique symbol;