@adonisjs/inertia 4.0.0-next.0 → 4.0.0-next.10

package/build/providers/inertia_provider.d.ts

@@ -1,33 +1,106 @@
-import { Route } from '@adonisjs/core/http';
-import { ApplicationService } from '@adonisjs/core/types';
-
+import { type Route } from '@adonisjs/core/http';
+import type { ApplicationService } from '@adonisjs/core/types';
+import type { AsPageProps, ComponentProps, InertiaPages, SharedProps } from '../src/types.js';
 declare module '@adonisjs/core/http' {
     interface BriskRoute {
         /**
-         * Render an inertia page without defining an
-         * explicit route handler
+         * Render an inertia page without defining an explicit route handler
+         *
+         * This method allows you to render Inertia pages directly from route definitions
+         * without creating separate controller methods.
+         *
+         * @param component - The name of the Inertia component to render
+         * @param props - Props to pass to the component
+         * @param viewProps - Additional props to pass to the root view template
+         * @returns The route instance for method chaining
+         *
+         * @example
+         * ```js
+         * // Basic usage
+         * router.get('/dashboard', []).renderInertia('Dashboard', {
+         *   user: auth.user
+         * })
+         *
+         * // With view props
+         * router.get('/home', []).renderInertia('Home', {
+         *   posts: posts
+         * }, {
+         *   title: 'Welcome Home'
+         * })
+         * ```
          */
-        renderInertia(component: string, props?: Record<string, any>, viewProps?: Record<string, any>): Route;
+        renderInertia<Page extends keyof InertiaPages>(component: Page, props: InertiaPages[Page] extends ComponentProps ? AsPageProps<Omit<InertiaPages[Page], keyof SharedProps>> : never, viewProps?: Record<string, any>): Route;
     }
 }
 /**
- * Inertia provider
+ * 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 }
+ * })
+ * ```
  */
-declare class InertiaProvider {
+export default class InertiaProvider {
     protected app: ApplicationService;
+    /**
+     * Creates a new InertiaProvider instance
+     *
+     * @param app - The AdonisJS application service instance
+     */
     constructor(app: ApplicationService);
     /**
-     * Registers edge plugin when edge is installed
+     * 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)
+     * ```
      */
     protected registerEdgePlugin(): Promise<void>;
     /**
-     * Register inertia middleware
+     * 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)
+     * ```
      */
     register(): Promise<void>;
     /**
-     * Register edge plugin and brisk route macro
+     * 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()
+     * })
+     * ```
      */
     boot(): Promise<void>;
 }
-
-export { InertiaProvider as default };

package/build/providers/inertia_provider.js

@@ -1,42 +1,72 @@
 import {
-  InertiaMiddleware
-} from "../chunk-AWCR2NAY.js";
+  InertiaManager
+} from "../chunk-YQ72YL64.js";
+import "../chunk-4EZ2J6OA.js";
+import "../chunk-DISC5OYC.js";
+import "../chunk-MLKGABMK.js";
 
 // providers/inertia_provider.ts
-import { configProvider } from "@adonisjs/core";
-import { RuntimeException } from "@poppinss/utils";
 import { BriskRoute } from "@adonisjs/core/http";
 var InertiaProvider = class {
+  /**
+   * Creates a new InertiaProvider instance
+   *
+   * @param app - The AdonisJS application service instance
+   */
   constructor(app) {
     this.app = app;
   }
   /**
-   * Registers edge plugin when edge is installed
+   * 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() {
-    if (!this.app.usingEdgeJS) return;
     const edgeExports = await import("edge.js");
     const { edgePluginInertia } = await import("../src/plugins/edge/plugin.js");
     edgeExports.default.use(edgePluginInertia());
   }
   /**
-   * Register inertia middleware
+   * 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(InertiaMiddleware, async () => {
-      const inertiaConfigProvider = this.app.config.get("inertia");
-      const config = await configProvider.resolve(this.app, inertiaConfigProvider);
-      const vite = await this.app.container.make("vite");
-      if (!config) {
-        throw new RuntimeException(
-          'Invalid "config/inertia.ts" file. Make sure you are using the "defineConfig" method'
-        );
-      }
-      return new InertiaMiddleware(config, vite);
+    this.app.container.singleton(InertiaManager, async (resolver) => {
+      const config = this.app.config.get("inertia", {});
+      const vite = await resolver.make("vite");
+      return new InertiaManager(config, vite);
     });
   }
   /**
-   * Register edge plugin and brisk route macro
+   * 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();

package/build/src/client/helpers.d.ts

@@ -0,0 +1,27 @@
+/**
+ * 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
+ */
+export declare function resolvePageComponent<T>(path: string | string[], pages: Record<string, Promise<T> | (() => Promise<T>) | T>, layout?: any): Promise<T>;

package/build/src/client/helpers.js

@@ -0,0 +1,30 @@
+import "../../chunk-MLKGABMK.js";
+
+// src/client/helpers.ts
+async function resolvePageComponent(path, pages, layout) {
+  for (const p of Array.isArray(path) ? path : [path]) {
+    const page = pages[p];
+    if (typeof page === "undefined") {
+      continue;
+    }
+    const resolvedPage = await (typeof page === "function" ? page() : page);
+    if (!resolvedPage) {
+      throw new Error(
+        `Invalid page exported from "${path}". Make sure to default export a function`
+      );
+    }
+    if ("default" in resolvedPage === false) {
+      throw new Error(
+        `Invalid page exported from "${path}". Make sure to default export a function`
+      );
+    }
+    if (layout && !resolvedPage.default.layout) {
+      resolvedPage.default.layout = layout;
+    }
+    return resolvedPage;
+  }
+  throw new Error(`Page not found: "${path}"`);
+}
+export {
+  resolvePageComponent
+};

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

@@ -0,0 +1,24 @@
+import React from 'react';
+import type { Tuyau } from '@tuyau/core/client';
+import type { AdonisRegistry } from '@tuyau/core/types';
+/**
+ * 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.
+ *
+ */
+export declare function TuyauProvider<R extends AdonisRegistry>(props: {
+    children: React.ReactNode;
+    client: Tuyau<R>;
+}): React.JSX.Element;
+/**
+ * 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
+ */
+export declare function useTuyau(): Tuyau<any>;

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

@@ -0,0 +1,3 @@
+export * from './context.tsx';
+export * from './router.ts';
+export * from './link.tsx';

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

@@ -0,0 +1,72 @@
+import "../../../chunk-MLKGABMK.js";
+
+// src/client/react/context.tsx
+import React from "react";
+var TuyauContext = React.createContext(null);
+function TuyauProvider(props) {
+  return /* @__PURE__ */ React.createElement(TuyauContext.Provider, { value: props.client }, props.children);
+}
+function useTuyau() {
+  const context = React.useContext(TuyauContext);
+  if (!context) throw new Error("You must wrap your app in a TuyauProvider");
+  return context;
+}
+
+// src/client/react/router.ts
+import { router as InertiaRouter } from "@inertiajs/react";
+function useRouter() {
+  const tuyau = useTuyau();
+  return {
+    /**
+     * Navigate to a route with type-safe parameters and options.
+     *
+     * Automatically resolves the route URL and HTTP method based on the
+     * route definition, then performs the navigation using Inertia's router.
+     *
+     * @param props - Route navigation parameters including route name and params
+     * @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', params: { id: userId } })
+     * ```
+     */
+    visit: (props, options) => {
+      const routeInfo = tuyau.getRoute(props.route, { params: props.params });
+      const url = routeInfo.url;
+      return InertiaRouter.visit(url, {
+        ...options,
+        method: routeInfo.methods[0].toLowerCase()
+      });
+    }
+  };
+}
+
+// src/client/react/link.tsx
+import React2 from "react";
+import { Link as InertiaLink } from "@inertiajs/react";
+function LinkInner(props, ref) {
+  const { route, params, ...linkProps } = props;
+  const tuyau = useTuyau();
+  const routeInfo = tuyau.getRoute(props.route, { params });
+  return /* @__PURE__ */ React2.createElement(
+    InertiaLink,
+    {
+      ...linkProps,
+      href: routeInfo.url,
+      method: routeInfo.methods[0].toLowerCase(),
+      ref
+    }
+  );
+}
+var Link = React2.forwardRef(LinkInner);
+export {
+  Link,
+  TuyauProvider,
+  useRouter,
+  useTuyau
+};

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

@@ -0,0 +1,64 @@
+import React from 'react';
+import type { UserRegistry } from '@tuyau/core/types';
+import { Link as InertiaLink } from '@inertiajs/react';
+import { AreAllOptional } from '@poppinss/utils/types';
+/**
+ * Get parameter tuple type for a route
+ */
+type ExtractParamsTuple<Route extends keyof UserRegistry> = UserRegistry[Route]['types']['paramsTuple'];
+/**
+ * Get parameter object type for a route
+ */
+type ExtractParamsObject<Route extends keyof UserRegistry> = UserRegistry[Route]['types']['params'];
+/**
+ * Get params format for a route
+ */
+type RouteParamsFormats<Route extends keyof UserRegistry> = ExtractParamsObject<Route> extends Record<string, never> ? never : ExtractParamsTuple<Route> | ExtractParamsObject<Route>;
+/**
+ * Parameters required for route navigation with proper type safety.
+ */
+export type LinkParams<Route extends keyof UserRegistry> = {
+    route: Route;
+} & (RouteParamsFormats<Route> extends never ? {
+    params?: never;
+} : AreAllOptional<ExtractParamsObject<Route>> extends true ? {
+    params?: RouteParamsFormats<Route>;
+} : {
+    params: RouteParamsFormats<Route>;
+});
+/**
+ * Props for the Link component extending InertiaLink props
+ * with route-specific type safety and parameter validation.
+ */
+type LinkProps<Route extends keyof UserRegistry> = Omit<React.ComponentPropsWithoutRef<typeof InertiaLink>, 'href' | 'method'> & LinkParams<Route>;
+/**
+ * Internal Link component implementation with forward ref support.
+ * Resolves route parameters and generates the appropriate URL and HTTP method
+ * for Inertia navigation.
+ *
+ * @param props - Link properties including route and parameters
+ * @param ref - Forward ref for the underlying InertiaLink component
+ */
+declare function LinkInner<Route extends keyof UserRegistry>(props: LinkProps<Route>, ref?: React.ForwardedRef<React.ElementRef<typeof InertiaLink>>): React.JSX.Element;
+/**
+ * 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.
+ *
+ * @example
+ * ```tsx
+ * // Link to a route without parameters
+ * <Link route="home">Home</Link>
+ *
+ * // Link to a route with required parameters
+ * <Link route="user.show" params={{ id: 1 }}>
+ *   View User
+ * </Link>
+ * ```
+ */
+export declare const Link: <Route extends keyof UserRegistry>(props: LinkProps<Route> & {
+    ref?: React.Ref<React.ElementRef<typeof InertiaLink>>;
+}) => ReturnType<typeof LinkInner>;
+export {};

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

@@ -0,0 +1,33 @@
+import type { UserRegistry } from '@tuyau/core/types';
+import { router as InertiaRouter } from '@inertiajs/react';
+import type { LinkParams } from './link.tsx';
+/**
+ * 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.
+ *
+ * @returns Router object with type-safe navigation methods
+ */
+export declare function useRouter(): {
+    /**
+     * Navigate to a route with type-safe parameters and options.
+     *
+     * Automatically resolves the route URL and HTTP method based on the
+     * route definition, then performs the navigation using Inertia's router.
+     *
+     * @param props - Route navigation parameters including route name and params
+     * @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', params: { id: userId } })
+     * ```
+     */
+    visit: <Route extends keyof UserRegistry>(props: LinkParams<Route>, options?: Parameters<typeof InertiaRouter.visit>[1]) => any;
+};

package/build/src/client/vite.d.ts

@@ -0,0 +1,65 @@
+import type { PluginOption } from 'vite';
+/**
+ * Configuration options for the Inertia Vite plugin
+ */
+export type InertiaPluginOptions = {
+    /**
+     * Server-side rendering configuration
+     */
+    ssr?: {
+        /**
+         * Whether or not to enable server-side rendering
+         */
+        enabled: true;
+        /**
+         * The entrypoint for the server-side rendering
+         */
+        entrypoint: string;
+        /**
+         * The output directory for the server-side rendering bundle
+         */
+        output?: string;
+    } | {
+        enabled: false;
+        entrypoint?: string;
+        output?: string;
+    };
+};
+/**
+ * Inertia plugin for Vite that is tailored for AdonisJS
+ *
+ * Configures Vite for Inertia.js development with proper build settings,
+ * SSR support, and AdonisJS-specific optimizations.
+ *
+ * @param options - Configuration options for the plugin
+ * @returns Vite plugin configuration object
+ *
+ * @example
+ * ```js
+ * // Basic configuration
+ * import inertia from '@adonisjs/inertia/plugins/vite'
+ *
+ * export default defineConfig({
+ *   plugins: [inertia()]
+ * })
+ * ```
+ *
+ * @example
+ * ```js
+ * // With SSR enabled
+ * import inertia from '@adonisjs/inertia/plugins/vite'
+ *
+ * export default defineConfig({
+ *   plugins: [
+ *     inertia({
+ *       ssr: {
+ *         enabled: true,
+ *         entrypoint: 'inertia/ssr.tsx',
+ *         output: 'build/ssr'
+ *       }
+ *     })
+ *   ]
+ * })
+ * ```
+ */
+export default function inertia(options?: InertiaPluginOptions): PluginOption;

package/build/src/{plugins → client}/vite.js

@@ -1,9 +1,13 @@
-// src/plugins/vite.ts
+import "../../chunk-MLKGABMK.js";
+
+// src/client/vite.ts
 function inertia(options) {
   return {
     name: "vite-plugin-inertia",
     config: (_, { command }) => {
-      if (command === "build") process.env.NODE_ENV = "production";
+      if (command === "build") {
+        process.env.NODE_ENV = "production";
+      }
       return {
         builder: {},
         build: { outDir: "build/public/assets" },

package/build/src/debug.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Debug logger for Inertia.js package
+ *
+ * Provides debugging functionality using Node.js built-in debuglog.
+ * Enable debugging by setting the NODE_DEBUG environment variable to 'adonisjs:inertia'.
+ *
+ * @example
+ * ```js
+ * import debug from './debug.js'
+ *
+ * debug('Processing Inertia request')
+ * debug('Component: %s, Props: %o', componentName, props)
+ * ```
+ *
+ * @example
+ * ```bash
+ * # Enable debugging
+ * NODE_DEBUG=adonisjs:inertia node server.js
+ * ```
+ */
+declare const _default: import("util").DebugLogger;
+export default _default;

package/build/src/define_config.d.ts

@@ -0,0 +1,30 @@
+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
+ * @returns Complete Inertia configuration object with defaults applied
+ *
+ * @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";
+};