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

package/build/commands/make_page.js

@@ -1,18 +1,28 @@
 import { readdir } from "node:fs/promises";
 import { BaseCommand, args, flags } from "@adonisjs/core/ace";
 import { join } from "node:path";
+//#region \0@oxc-project+runtime@0.139.0/helpers/esm/decorate.js
 function __decorate(decorators, target, key, desc) {
 	var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
 	if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
 	else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
 	return c > 3 && r && Object.defineProperty(target, key, r), r;
 }
+//#endregion
+//#region commands/make_page.ts
 const stubsRoot = join(import.meta.dirname, "../stubs");
 var MakePage = class extends BaseCommand {
 	static commandName = "make:page";
 	static description = "Create a new Inertia page component";
 	static options = { allowUnknownFlags: true };
+	/**
+	* Directory under which the inertia pages are stored
+	*/
 	pagesDir = "inertia/pages";
+	/**
+	* Detect the framework by scanning existing files in the
+	* inertia/pages directory.
+	*/
 	async #detectFramework() {
 		try {
 			const files = await readdir(this.app.makePath(this.pagesDir), { recursive: true });
@@ -25,6 +35,10 @@ var MakePage = class extends BaseCommand {
 			return null;
 		}
 	}
+	/**
+	* Resolve which framework to use. Flags take priority,
+	* then auto-detection, and finally prompt the user.
+	*/
 	async #resolveFramework() {
 		if (this.vue) return "vue";
 		if (this.react) return "react";
@@ -51,4 +65,5 @@ __decorate([flags.boolean({
 	description: "Forcefully overwrite existing files",
 	alias: "f"
 })], MakePage.prototype, "force", void 0);
+//#endregion
 export { MakePage as default };

package/build/debug-Ca0ekg3M.js

@@ -0,0 +1,25 @@
+import { debuglog } from "node:util";
+//#region src/debug.ts
+/**
+* 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
+* ```
+*/
+var debug_default = debuglog("adonisjs:inertia");
+//#endregion
+export { debug_default as t };

package/build/factories/inertia_factory.d.ts

@@ -97,6 +97,31 @@ export declare class InertiaFactory<Pages extends Record<string, ComponentProps>
          */
         create(): Inertia<Pages>;
     };
+    /**
+     * Simulates a client that already holds fresh, cached values for the given
+     * once-keys by setting the `X-Inertia-Except-Once-Props` request header.
+     *
+     * @param keys - The once-keys the client reports as cached
+     *
+     * @example
+     * ```typescript
+     * const inertia = factory.withExceptOnceProps(['lookups']).create()
+     * ```
+     */
+    withExceptOnceProps(keys: string[]): this;
+    /**
+     * Simulates the infinite-scroll merge intent the client sends on follow-up
+     * scroll requests by setting the `X-Inertia-Infinite-Scroll-Merge-Intent`
+     * header. Absence is treated as `append`.
+     *
+     * @param intent - The merge direction the client requests
+     *
+     * @example
+     * ```typescript
+     * const inertia = factory.withMergeIntent('prepend').create()
+     * ```
+     */
+    withMergeIntent(intent: 'append' | 'prepend'): this;
     /**
      * Sets the assets version for cache busting
      *

package/build/factories/main.js

@@ -1,50 +1,167 @@
-import { n as ServerRenderer, r as Inertia } from "../inertia_manager-BdcjpKFf.js";
-import { t as InertiaHeaders } from "../headers-DafWEpBh.js";
-import "../debug-CBMTuPUm.js";
-import { t as defineConfig } from "../define_config-Dv9Dx2Yq.js";
-import "../index.js";
+import { n as ServerRenderer, r as Inertia } from "../inertia_manager-BeqpMsuN.js";
+import { t as InertiaHeaders } from "../headers-B-5pLwyD.js";
+import { t as defineConfig } from "../inertia-ZqLiRJME.js";
 import { HttpContextFactory } from "@adonisjs/core/factories/http";
+//#region factories/inertia_factory.ts
+/**
+* Inertia factory to quickly create a new instance of Inertia
+* for testing purposes
+*
+* @example
+* ```typescript
+* const factory = new InertiaFactory()
+* const inertia = factory
+*   .merge({ config: { ssr: { enabled: true } } })
+*   .withVersion('1.0.0')
+*   .create()
+* ```
+*/
 var InertiaFactory = class {
+	/** Optional Vite instance for asset handling */
 	#vite;
+	/** Internal parameters for factory configuration */
 	#parameters = {
 		ctx: new HttpContextFactory().create(),
 		config: defineConfig({})
 	};
+	/**
+	* Creates a new InertiaFactory instance with default Inertia headers
+	*
+	* @example
+	* ```typescript
+	* const factory = new InertiaFactory()
+	* ```
+	*/
 	constructor() {
 		this.#parameters.ctx.request.request.headers[InertiaHeaders.Inertia] = "true";
 	}
+	/**
+	* Merges additional parameters into the factory configuration
+	*
+	* @param parameters - Partial factory parameters to merge
+	*
+	* @example
+	* ```typescript
+	* factory.merge({
+	*   config: { ssr: { enabled: true } },
+	*   ctx: customContext
+	* })
+	* ```
+	*/
 	merge(parameters) {
 		if (parameters.ctx) this.#parameters.ctx = parameters.ctx;
 		if (parameters.config) this.#parameters.config = defineConfig(parameters.config);
 		this.#parameters.ctx.request.request.headers[InertiaHeaders.Inertia] = "true";
 		return this;
 	}
+	/**
+	* Removes the X-Inertia header from the request headers
+	*
+	* @example
+	* ```typescript
+	* const inertia = factory.withoutInertia().create()
+	* ```
+	*/
 	withoutInertia() {
 		delete this.#parameters.ctx.request.request.headers[InertiaHeaders.Inertia];
 		return this;
 	}
+	/**
+	* Configures the factory for partial reloads of a specific component
+	*
+	* @param component - Name of the component to partially reload
+	*
+	* @example
+	* ```typescript
+	* const inertia = factory
+	*   .partialReload('UserProfile')
+	*   .only(['name', 'email'])
+	*   .create()
+	* ```
+	*/
 	partialReload(component) {
 		const self = this;
 		const request = this.#parameters.ctx.request;
 		request.request.headers[InertiaHeaders.PartialComponent] = component;
 		return {
+			/**
+			* Specifies which props to include in the partial reload
+			*
+			* @param props - Array of property names to include
+			*/
 			only(props) {
 				request.request.headers[InertiaHeaders.PartialOnly] = props.join(",");
 				return this;
 			},
+			/**
+			* Specifies which props to exclude from the partial reload
+			*
+			* @param props - Array of property names to exclude
+			*/
 			except(props) {
 				request.request.headers[InertiaHeaders.PartialExcept] = props.join(",");
 				return this;
 			},
+			/**
+			* Specifies which props should be reset during the partial reload
+			*
+			* @param props - Array of property names to reset
+			*/
 			reset(props) {
 				request.request.headers[InertiaHeaders.Reset] = props.join(",");
 				return this;
 			},
+			/**
+			* Creates the Inertia instance with partial reload configuration
+			*/
 			create() {
 				return self.create();
 			}
 		};
 	}
+	/**
+	* Simulates a client that already holds fresh, cached values for the given
+	* once-keys by setting the `X-Inertia-Except-Once-Props` request header.
+	*
+	* @param keys - The once-keys the client reports as cached
+	*
+	* @example
+	* ```typescript
+	* const inertia = factory.withExceptOnceProps(['lookups']).create()
+	* ```
+	*/
+	withExceptOnceProps(keys) {
+		this.#parameters.ctx.request.request.headers[InertiaHeaders.ExceptOnceProps] = keys.join(",");
+		return this;
+	}
+	/**
+	* Simulates the infinite-scroll merge intent the client sends on follow-up
+	* scroll requests by setting the `X-Inertia-Infinite-Scroll-Merge-Intent`
+	* header. Absence is treated as `append`.
+	*
+	* @param intent - The merge direction the client requests
+	*
+	* @example
+	* ```typescript
+	* const inertia = factory.withMergeIntent('prepend').create()
+	* ```
+	*/
+	withMergeIntent(intent) {
+		this.#parameters.ctx.request.request.headers[InertiaHeaders.InfiniteScrollMergeIntent] = intent;
+		return this;
+	}
+	/**
+	* Sets the assets version for cache busting
+	*
+	* @param version - Version string or function for asset versioning
+	*
+	* @example
+	* ```typescript
+	* factory.withVersion('1.0.0')
+	* // or
+	* factory.withVersion(() => Date.now().toString())
+	* ```
+	*/
 	withVersion(version) {
 		this.#parameters.config = {
 			...this.#parameters.config,
@@ -52,12 +169,34 @@ var InertiaFactory = class {
 		};
 		return this;
 	}
+	/**
+	* Sets the Vite instance for asset handling
+	*
+	* @param options - Vite configuration object
+	*
+	* @example
+	* ```typescript
+	* factory.withVite(viteInstance)
+	* ```
+	*/
 	withVite(options) {
 		this.#vite = options;
 		return this;
 	}
+	/**
+	* Creates a new Inertia instance with the configured parameters
+	*
+	* @example
+	* ```typescript
+	* const inertia = factory
+	*   .merge({ config: customConfig })
+	*   .withVersion('1.0.0')
+	*   .create()
+	* ```
+	*/
 	create() {
 		return new Inertia(this.#parameters.ctx, this.#parameters.config, this.#vite, this.#vite ? new ServerRenderer(this.#parameters.config, this.#vite) : void 0);
 	}
 };
+//#endregion
 export { InertiaFactory };

package/build/headers-B-5pLwyD.js

@@ -0,0 +1,77 @@
+//#region src/headers.ts
+/**
+* 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
+* }
+* ```
+*/
+const InertiaHeaders = {
+	/**
+	* Header to identify Inertia.js requests.
+	* Set to 'true' by Inertia.js client to indicate an Inertia request.
+	*/
+	Inertia: "x-inertia",
+	/**
+	* Header to drop a prop from the merge and deep merge object.
+	*/
+	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.
+	*/
+	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.
+	*/
+	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.
+	*/
+	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.
+	*/
+	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.
+	*/
+	PartialExcept: "x-inertia-partial-except",
+	/**
+	* Header specifying the component name for partial reloads.
+	* Used to identify which component is being partially reloaded.
+	*/
+	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.
+	*/
+	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`.
+	*/
+	InfiniteScrollMergeIntent: "x-inertia-infinite-scroll-merge-intent"
+};
+//#endregion
+export { InertiaHeaders as t };

package/build/index.js

@@ -1,5 +1,4 @@
-import { i as symbols_exports, n as ServerRenderer, r as Inertia, t as InertiaManager } from "./inertia_manager-BdcjpKFf.js";
-import { t as InertiaHeaders } from "./headers-DafWEpBh.js";
-import "./debug-CBMTuPUm.js";
-import { n as indexPages, t as defineConfig } from "./define_config-Dv9Dx2Yq.js";
+import { i as symbols_exports, n as ServerRenderer, r as Inertia, t as InertiaManager } from "./inertia_manager-BeqpMsuN.js";
+import { t as InertiaHeaders } from "./headers-B-5pLwyD.js";
+import { n as indexPages, t as defineConfig } from "./inertia-ZqLiRJME.js";
 export { Inertia, InertiaHeaders, InertiaManager, ServerRenderer, defineConfig, indexPages, symbols_exports as symbols };

package/build/inertia-ZqLiRJME.js

@@ -0,0 +1,141 @@
+import "./inertia_manager-BeqpMsuN.js";
+import "./headers-B-5pLwyD.js";
+import lodash from "@poppinss/utils/lodash";
+//#region src/index_pages.ts
+/**
+* File glob patterns for different frontend frameworks.
+* Defines which file extensions should be scanned for each supported framework.
+*/
+const GLOB = {
+	vue3: ["**/*.vue"],
+	react: ["**/*.ts", "**/*.tsx"]
+};
+/**
+* List of supported frontend frameworks for page type generation.
+* Extracted from the GLOB configuration object.
+*/
+const SUPPORTED_FRAMEWORKS = Object.keys(GLOB);
+/**
+* TypeScript helper code templates for extracting component props.
+* Contains framework-specific type extraction logic that gets injected
+* into the generated type definition files.
+*/
+const TYPES_EXTRACTION_HELPER = {
+	vue3: `import type { VNodeProps, AllowedComponentProps, ComponentInstance } from 'vue'
+
+type ExtractProps<T> = Omit<
+  ComponentInstance<T>['$props'],
+  keyof VNodeProps | keyof AllowedComponentProps
+>`,
+	react: `import type React from 'react'
+import type { Prettify } from '@adonisjs/core/types/common'
+
+type ExtractProps<T> =
+  T extends React.FC<infer Props>
+    ? Prettify<Omit<Props, 'children'>>
+    : T extends React.Component<infer Props>
+      ? Prettify<Omit<Props, 'children'>>
+      : never`
+};
+/**
+* Creates an AdonisJS assembler hook to automatically generate TypeScript definitions
+* for Inertia.js pages based on the specified framework.
+*
+* This function scans page components in the 'inertia/pages' directory and generates
+* type definitions that map page names to their component props.
+*
+* @param config - Configuration object specifying the frontend framework
+* @param config.framework - The frontend framework ('vue3' or 'react')
+* @param config.source - The path to Inertia pages (default: inertia/pages)
+* @returns Assembler hook object with run method for generating page types
+*
+* @example
+* ```js
+* // In your adonisrc.ts file
+* export default defineConfig({
+*   assembler: {
+*     onBuildStarting: [indexPages({ framework: 'vue3' })]
+*   }
+* })
+* ```
+*/
+const indexPages = function(config) {
+	if (!SUPPORTED_FRAMEWORKS.includes(config.framework)) throw new Error(`Unsupported framework "${config.framework}". Types generation is available only for ${SUPPORTED_FRAMEWORKS.join(",")}`);
+	return { 
+	/**
+	* Executes the page indexing process to generate TypeScript definitions.
+	*
+	* @param _ - Unused first parameter (assembler context)
+	* @param __ - Unused second parameter (hooks instance)
+	* @param indexGenerator - The index generator instance used to register the pages type generation
+	*/
+run(_, __, indexGenerator) {
+		indexGenerator.add("inertiaPages", {
+			source: config.source ?? "inertia/pages",
+			glob: GLOB[config.framework],
+			output: ".adonisjs/server/pages.d.ts",
+			/**
+			* Generates the TypeScript module declaration for Inertia pages.
+			*
+			* @param vfs - Virtual file system containing the scanned page files
+			* @param buffer - Buffer instance for writing the generated TypeScript code
+			* @param ___ - Unused third parameter
+			* @param helpers - Helper utilities for path manipulation and imports
+			*/
+			as(vfs, buffer, ___, helpers) {
+				const filesList = vfs.asList();
+				buffer.writeLine(`import '@adonisjs/inertia/types'`);
+				buffer.writeLine(TYPES_EXTRACTION_HELPER[config.framework]);
+				buffer.write(`declare module '@adonisjs/inertia/types' {`).indent();
+				buffer.write(`export interface InertiaPages {`).indent();
+				Object.keys(filesList).forEach((key) => {
+					buffer.write(`'${key}': ExtractProps<(typeof import('${helpers.toImportPath(filesList[key])}'))['default']>`);
+				});
+				buffer.dedent().write(`}`);
+				buffer.dedent().write(`}`);
+			}
+		});
+	} };
+};
+//#endregion
+//#region src/define_config.ts
+/**
+* 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,
+*     entrypoint: 'inertia/ssr.tsx'
+*   }
+* })
+* ```
+*
+* @example
+* ```js
+* // Minimal configuration
+* const config = defineConfig({
+*   rootView: 'app'
+* })
+* ```
+*/
+function defineConfig(config) {
+	return lodash.merge({
+		rootView: "inertia_layout",
+		history: { encrypt: false },
+		ssr: {
+			enabled: false,
+			entrypoint: "inertia/ssr.tsx"
+		}
+	}, config);
+}
+//#endregion
+export { indexPages as n, defineConfig as t };