@adonisjs/inertia 3.1.1 → 4.0.0-next.1

package/build/src/define_config.d.ts

@@ -0,0 +1,29 @@
+import type { InertiaConfig, InertiaConfigInput } from './types.js';
+/**
+ * Define the Inertia configuration with default values
+ *
+ * This function merges user-provided configuration with sensible defaults
+ * to create a complete Inertia configuration object.
+ *
+ * @param config - User configuration input to override defaults
+ *
+ * @example
+ * ```js
+ * const config = defineConfig({
+ *   rootView: 'layouts/app',
+ *   ssr: {
+ *     enabled: true,
+ *     bundle: 'build/ssr/ssr.js'
+ *   }
+ * })
+ * ```
+ *
+ * @example
+ * ```js
+ * // Minimal configuration
+ * const config = defineConfig({
+ *   rootView: 'app'
+ * })
+ * ```
+ */
+export declare function defineConfig(config: InertiaConfigInput): InertiaConfig;

package/build/src/headers.d.ts

@@ -0,0 +1,61 @@
+/**
+ * List of possible headers used by Inertia.js for client-server communication.
+ * These headers control various aspects of Inertia requests and responses,
+ * enabling features like partial reloads, version checking, and error handling.
+ *
+ * @example
+ * ```javascript
+ * // Check if request is an Inertia request
+ * const isInertiaRequest = request.header(InertiaHeaders.Inertia) === 'true'
+ *
+ * // Set version header in response
+ * response.header(InertiaHeaders.Version, '1.0.0')
+ *
+ * // Handle partial data requests
+ * if (request.header(InertiaHeaders.PartialOnly)) {
+ *   const onlyProps = request.header(InertiaHeaders.PartialOnly).split(',')
+ *   // Return only specified props
+ * }
+ * ```
+ */
+export declare const InertiaHeaders: {
+    /**
+     * Header to identify Inertia.js requests.
+     * Set to 'true' by Inertia.js client to indicate an Inertia request.
+     */
+    readonly Inertia: "x-inertia";
+    /**
+     * Header to drop a prop from the merge and deep merge object.
+     */
+    readonly Reset: "x-inertia-reset";
+    /**
+     * Header containing the current asset version.
+     * Used for cache busting - if versions don't match, Inertia performs a full page reload.
+     */
+    readonly Version: "x-inertia-version";
+    /**
+     * Header containing the target URL for redirects.
+     * Used when the server wants to redirect to a different URL than the current request.
+     */
+    readonly Location: "x-inertia-location";
+    /**
+     * Header specifying the error bag name for validation errors.
+     * Allows multiple forms on the same page to have separate error handling.
+     */
+    readonly ErrorBag: "x-inertia-error-bag";
+    /**
+     * Header containing comma-separated list of props to include in partial data requests.
+     * Only the specified props will be returned in the response.
+     */
+    readonly PartialOnly: "x-inertia-partial-data";
+    /**
+     * Header containing comma-separated list of props to exclude in partial data requests.
+     * All props except the specified ones will be returned in the response.
+     */
+    readonly PartialExcept: "x-inertia-partial-except";
+    /**
+     * Header specifying the component name for partial reloads.
+     * Used to identify which component is being partially reloaded.
+     */
+    readonly PartialComponent: "x-inertia-partial-component";
+};

package/build/src/index_pages.d.ts

@@ -0,0 +1,5 @@
+export declare const indexPages: (config: {
+    framework: "vue3" | "react";
+}) => {
+    run(_: import("@adonisjs/assembler").DevServer | import("@adonisjs/assembler").TestRunner | import("@adonisjs/assembler").Bundler, indexGenerator: import("@adonisjs/assembler/index_generator").IndexGenerator): void;
+};

package/build/src/inertia.d.ts

@@ -0,0 +1,253 @@
+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 } from './types.js';
+import { defer, merge, always, optional, deepMerge } from './props.ts';
+/**
+ * Main class used to interact with Inertia
+ *
+ * Provides a complete interface for handling Inertia.js requests, rendering pages,
+ * managing props, and controlling page navigation behavior.
+ *
+ * @example
+ * ```js
+ * const inertia = new Inertia(ctx, config, vite, serverRenderer)
+ *
+ * // Render a page
+ * const result = await inertia.render('Home', { user: { name: 'John' } })
+ *
+ * // Clear browser history
+ * inertia.clearHistory()
+ *
+ * // Redirect to a different location
+ * inertia.location('/dashboard')
+ * ```
+ */
+export declare class Inertia<Pages extends Record<string, ComponentProps>> {
+    #private;
+    protected ctx: HttpContext;
+    protected config: InertiaConfig;
+    /**
+     * Defer prop evaluation until client-side rendering
+     *
+     * @example
+     * ```js
+     * {
+     *   expensiveData: inertia.defer(() => computeExpensiveData())
+     * }
+     * ```
+     */
+    defer: typeof defer;
+    /**
+     * Always include prop in both server and client renders
+     *
+     * @example
+     * ```js
+     * {
+     *   currentUser: inertia.always(() => getCurrentUser())
+     * }
+     * ```
+     */
+    always: typeof always;
+    /**
+     * Merge prop with existing client-side data
+     *
+     * @example
+     * ```js
+     * {
+     *   posts: inertia.merge(() => getPosts())
+     * }
+     * ```
+     */
+    merge: typeof merge;
+    /**
+     * Include prop only when specifically requested
+     *
+     * @example
+     * ```js
+     * {
+     *   optionalData: inertia.optional(() => getOptionalData())
+     * }
+     * ```
+     */
+    optional: typeof optional;
+    /**
+     * Deep merge prop with existing client-side data
+     *
+     * @example
+     * ```js
+     * {
+     *   settings: inertia.deepMerge(() => getSettings())
+     * }
+     * ```
+     */
+    deepMerge: typeof deepMerge;
+    /**
+     * Creates a new Inertia instance
+     *
+     * @param ctx - HTTP context for the current request
+     * @param config - Inertia configuration object
+     * @param vite - Vite instance for asset management
+     * @param serverRenderer - Optional server renderer for SSR
+     *
+     * @example
+     * ```js
+     * const inertia = new Inertia(ctx, {
+     *   rootView: 'app',
+     *   ssr: { enabled: true }
+     * }, vite, serverRenderer)
+     * ```
+     */
+    constructor(ctx: HttpContext, config: InertiaConfig, vite?: Vite, serverRenderer?: ServerRenderer);
+    /**
+     * Extract Inertia-specific information from request headers
+     *
+     * Parses various Inertia headers to determine request type and props filtering.
+     *
+     * @example
+     * ```js
+     * const info = inertia.requestInfo()
+     * if (info.isInertiaRequest) {
+     *   // Handle as Inertia request
+     * }
+     * ```
+     */
+    requestInfo(reCompute?: boolean): RequestInfo;
+    /**
+     * Compute and cache the assets version
+     *
+     * Uses Vite manifest hash when available, otherwise defaults to '1'.
+     */
+    getVersion(): string;
+    /**
+     * Determine if server-side rendering is enabled for a specific component
+     *
+     * Checks global SSR settings and component-specific configuration.
+     *
+     * @param component - The component name to check
+     *
+     * @example
+     * ```js
+     * const shouldSSR = await inertia.ssrEnabled('UserProfile')
+     * if (shouldSSR) {
+     *   // Render on server
+     * }
+     * ```
+     */
+    ssrEnabled<Page extends keyof Pages & string>(component: Page): Promise<boolean>;
+    /**
+     * Share props across all pages
+     *
+     * Merges the provided props with existing shared state, making them available
+     * to all pages rendered by this Inertia instance. Shared props are included
+     * in every page render alongside page-specific props.
+     *
+     * @param sharedState - Props to share across all pages
+     *
+     * @example
+     * ```js
+     * // Share user data across all pages
+     * inertia.share({
+     *   user: getCurrentUser(),
+     *   flash: getFlashMessages()
+     * })
+     *
+     * // Chain multiple shares
+     * inertia
+     *   .share({ currentUser: user })
+     *   .share({ permissions: userPermissions })
+     * ```
+     */
+    share(sharedState: PageProps): this;
+    /**
+     * Build a page object with processed props and metadata
+     *
+     * Creates the complete page object that will be sent to the client or used for SSR.
+     *
+     * @param page - The page component name
+     * @param pageProps - Props to pass to the page component
+     *
+     * @example
+     * ```js
+     * const pageObject = await inertia.page('Dashboard', {
+     *   user: { name: 'John' },
+     *   posts: defer(() => getPosts())
+     * })
+     * ```
+     */
+    page<Page extends keyof Pages & string>(page: Page, pageProps: AsPageProps<Pages[Page]>): Promise<PageObject<Pages[Page]>>;
+    /**
+     * Render a page using Inertia
+     *
+     * This method handles three distinct rendering scenarios:
+     * 1. Inertia requests - Returns JSON page object for client-side navigation
+     * 2. Initial page loads with SSR - Returns HTML with server-rendered content
+     * 3. Initial page loads without SSR - Returns HTML for client-side hydration
+     *
+     * @param page - The page component name to render
+     * @param pageProps - Props to pass to the page component
+     * @param viewProps - Additional props to pass to the root view template
+     *
+     * @returns PageObject for Inertia requests, HTML string for initial page loads
+     *
+     * @example
+     * ```js
+     * // For Inertia requests, returns PageObject
+     * const result = await inertia.render('Profile', {
+     *   user: getCurrentUser(),
+     *   posts: defer(() => getUserPosts())
+     * })
+     *
+     * // For initial page loads, returns HTML string
+     * const html = await inertia.render('Home', { welcome: 'Hello World' })
+     * ```
+     */
+    render<Page extends keyof Pages & string>(page: Page, pageProps: AsPageProps<Pages[Page]>, viewProps?: Record<string, any>): Promise<string | PageObject<Pages[Page]>>;
+    /**
+     * Clear the browser history on the next navigation
+     *
+     * Instructs the client to clear the browser history stack when navigating.
+     *
+     * @example
+     * ```js
+     * inertia.clearHistory()
+     * return inertia.render('Dashboard', props)
+     * ```
+     */
+    clearHistory(): void;
+    /**
+     * Control whether browser history should be encrypted
+     *
+     * Enables or disables encryption of sensitive data in browser history.
+     *
+     * @param encrypt - Whether to encrypt history (defaults to true)
+     *
+     * @example
+     * ```js
+     * // Enable encryption for sensitive pages
+     * inertia.encryptHistory(true)
+     *
+     * // Disable encryption for public pages
+     * inertia.encryptHistory(false)
+     * ```
+     */
+    encryptHistory(encrypt?: boolean): void;
+    /**
+     * Redirect to a different location
+     *
+     * Sets the appropriate headers to redirect the client to a new URL.
+     * Uses a 409 status code which Inertia.js interprets as a redirect instruction.
+     *
+     * @param url - The URL to redirect to
+     *
+     * @example
+     * ```js
+     * // Redirect after login
+     * inertia.location('/dashboard')
+     *
+     * // Redirect with full URL
+     * inertia.location('https://example.com/external')
+     * ```
+     */
+    location(url: string): void;
+}

package/build/src/inertia_manager.d.ts

@@ -0,0 +1,46 @@
+import { type Vite } from '@adonisjs/vite';
+import { type HttpContext } from '@adonisjs/core/http';
+import { Inertia } from './inertia.ts';
+import { type ComponentProps, type InertiaConfig } from './types.ts';
+/**
+ * Manager class for managing Inertia instances
+ *
+ * Acts as a factory for creating Inertia instances with shared configuration
+ * and Vite integration.
+ *
+ * @example
+ * ```js
+ * const manager = new InertiaManager(config, vite)
+ * const inertia = manager.createForRequest(ctx)
+ * ```
+ */
+export declare class InertiaManager {
+    #private;
+    /**
+     * Creates a new InertiaManager instance
+     *
+     * @param config - Inertia configuration object
+     * @param vite - Optional Vite instance for development mode and SSR
+     *
+     * @example
+     * ```js
+     * const manager = new InertiaManager({
+     *   rootView: 'app',
+     *   ssr: { enabled: true }
+     * }, vite)
+     * ```
+     */
+    constructor(config: InertiaConfig, vite?: Vite);
+    /**
+     * Creates a new Inertia instance for a specific HTTP request
+     *
+     * @param ctx - HTTP context for the current request
+     *
+     * @example
+     * ```js
+     * const inertia = manager.createForRequest(ctx)
+     * await inertia.render('Home', { user: ctx.auth.user })
+     * ```
+     */
+    createForRequest<Pages extends Record<string, ComponentProps>>(ctx: HttpContext): Inertia<Pages>;
+}

package/build/src/inertia_middleware.d.ts

@@ -1,108 +1,95 @@
-import { Vite } from '@adonisjs/vite';
-import { HttpContext } from '@adonisjs/core/http';
-import { NextFn } from '@adonisjs/core/types/http';
-import { R as ResolvedConfig, D as Data, P as PageObject, M as MaybePromise, O as OptionalProp, a as MergeProp, A as AlwaysProp, b as DeferProp } from '../types-DVqEHBD1.js';
-import '@adonisjs/core/types';
-import '@tuyau/utils/types';
-
+import type { HttpContext } from '@adonisjs/core/http';
+import { type Inertia } from './inertia.js';
+import type { ComponentProps, InertiaPages, PageProps } from './types.js';
+declare module '@adonisjs/core/http' {
+    interface HttpContext {
+        inertia: Inertia<InertiaPages extends Record<string, ComponentProps> ? InertiaPages : never>;
+    }
+}
 /**
- * Main class used to interact with Inertia
+ * 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
+ *     }
+ *   }
+ * }
+ * ```
  */
-declare class Inertia {
-    #private;
-    protected ctx: HttpContext;
-    protected config: ResolvedConfig;
-    protected vite?: Vite | undefined;
-    constructor(ctx: HttpContext, config: ResolvedConfig, vite?: Vite | undefined);
-    /**
-     * Share data for the current request.
-     * This data will override any shared data defined in the config.
-     */
-    share(data: Record<string, Data>): void;
-    /**
-     * Render a page using Inertia
-     */
-    render<TPageProps extends Record<string, any> = {}, TViewProps extends Record<string, any> = {}>(component: string, pageProps?: TPageProps, viewProps?: TViewProps): Promise<string | PageObject<TPageProps>>;
-    /**
-     * Clear history state.
-     *
-     * See https://v2.inertiajs.com/history-encryption#clearing-history
-     */
-    clearHistory(): void;
-    /**
-     * Encrypt history
-     *
-     * See https://v2.inertiajs.com/history-encryption
-     */
-    encryptHistory(encrypt?: boolean): void;
+export default abstract class BaseInertiaMiddleware {
     /**
-     * Create a lazy prop
+     * Extract validation errors from the session and format them for Inertia
      *
-     * Lazy props are never resolved on first visit, but only when the client
-     * request a partial reload explicitely with this value.
+     * Retrieves validation errors from the session flash messages and formats
+     * them according to Inertia's error bag conventions. Supports both simple
+     * error objects and error bags for multi-form scenarios.
      *
-     * See https://inertiajs.com/partial-reloads#lazy-data-evaluation
+     * @param ctx - The HTTP context containing session data
+     * @returns Formatted validation errors, either as a simple object or error bags
      *
-     * @deprecated use `optional` instead
+     * @example
+     * ```js
+     * const errors = middleware.getValidationErrors(ctx)
+     * // Returns: { email: 'Email is required', password: 'Password too short' }
+     * // Or with error bags: { login: { email: 'Email is required' } }
+     * ```
      */
-    lazy<T>(callback: () => MaybePromise<T>): OptionalProp<() => MaybePromise<T>>;
+    getValidationErrors(ctx: HttpContext): Record<string, string> | {
+        [errorBag: string]: Record<string, string>;
+    };
     /**
-     * Create an optional prop
+     * Share data with all Inertia pages
      *
-     * See https://inertiajs.com/partial-reloads#lazy-data-evaluation
-     */
-    optional<T>(callback: () => MaybePromise<T>): OptionalProp<() => MaybePromise<T>>;
-    /**
-     * Create a mergeable prop
+     * This method should return an object containing data that will be
+     * available to all Inertia pages as props.
      *
-     * See https://v2.inertiajs.com/merging-props
+     * @example
+     * ```ts
+     * async share() {
+     *   return {
+     *     user: ctx.auth?.user,
+     *     flash: ctx.session?.flashMessages.all()
+     *   }
+     * }
+     * ```
      */
-    merge<T>(callback: () => MaybePromise<T>): MergeProp<() => MaybePromise<T>>;
+    abstract share?(ctx: HttpContext): PageProps | Promise<PageProps>;
     /**
-     * Create an always prop
+     * Initialize the Inertia instance for the current request
      *
-     * Always props are resolved on every request, no matter if it's a partial
-     * request or not.
+     * This method creates an Inertia instance and attaches it to the
+     * HTTP context, making it available throughout the request lifecycle.
      *
-     * See https://inertiajs.com/partial-reloads#lazy-data-evaluation
+     * @param ctx - The HTTP context object
+     *
+     * @example
+     * ```ts
+     * await middleware.init(ctx)
+     * ```
      */
-    always<T>(callback: () => MaybePromise<T>): AlwaysProp<() => MaybePromise<T>>;
+    init(ctx: HttpContext): Promise<void>;
     /**
-     * Create a deferred prop
+     * Clean up and finalize the Inertia response
      *
-     * Deferred props feature allows you to defer the loading of certain
-     * page data until after the initial page render.
+     * 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
      *
-     * See https://v2.inertiajs.com/deferred-props
-     */
-    defer<T>(callback: () => MaybePromise<T>, group?: string): DeferProp<() => MaybePromise<T>>;
-    /**
-     * This method can be used to redirect the user to an external website
-     * or even a non-inertia route of your application.
+     * @param ctx - The HTTP context object
      *
-     * See https://inertiajs.com/redirects#external-redirects
+     * @example
+     * ```ts
+     * await middleware.dispose(ctx)
+     * ```
      */
-    location(url: string): Promise<void>;
-}
-
-/**
- * HttpContext augmentations
- */
-declare module '@adonisjs/core/http' {
-    interface HttpContext {
-        inertia: Inertia;
-    }
-}
-/**
- * Inertia middleware to handle the Inertia requests and
- * set appropriate headers/status
- */
-declare class InertiaMiddleware {
-    #private;
-    protected config: ResolvedConfig;
-    protected vite?: Vite | undefined;
-    constructor(config: ResolvedConfig, vite?: Vite | undefined);
-    handle(ctx: HttpContext, next: NextFn): Promise<void>;
+    dispose(ctx: HttpContext): void;
 }
-
-export { InertiaMiddleware as default };