@gravito/ion 3.0.1 → 3.1.0

package/dist/index.d.cts

@@ -1,201 +1,448 @@
 import { GravitoContext, GravitoVariables, GravitoOrbit, PlanetCore } from '@gravito/core';
 
 /**
- * @fileoverview Inertia.js Service for Gravito
+ * @fileoverview Inertia.js Service for Gravito.
  *
- * Provides server-side Inertia.js integration for building modern
- * single-page applications with server-side routing.
+ * This service implements the Inertia.js server-side protocol, enabling
+ * seamless page transitions and data synchronization for monolith SPAs.
  *
  * @module @gravito/ion
- * @since 1.0.0
  */
 
 /**
- * Configuration options for InertiaService
+ * Configuration options for the InertiaService instance.
+ *
+ * Defines how the service interacts with the root template, manages asset versioning,
+ * and handles Server-Side Rendering (SSR).
  */
 interface InertiaConfig {
     /**
-     * The root view template name
-     * @default 'app'
+     * The name of the root view template used for the initial page load.
+     *
+     * This template must contain the `{{{ page }}}` placeholder to inject the
+     * Inertia page object.
+     *
+     * @defaultValue 'app'
      */
     rootView?: string;
     /**
-     * Asset version for cache busting
+     * Asset version string or resolver.
+     *
+     * Used by Inertia to detect if the client-side assets are out of sync with the server.
+     * If the version sent by the client (X-Inertia-Version) doesn't match, the server
+     * triggers a full page reload via a 409 Conflict response.
+     */
+    version?: string | (() => string | Promise<string>);
+    /**
+     * Minimum logging level for internal operations.
+     *
+     * @defaultValue 'info'
+     */
+    logLevel?: 'debug' | 'info' | 'warn' | 'error' | 'silent';
+    /**
+     * Performance monitoring callback triggered after each render.
+     *
+     * Useful for tracking rendering latency and prop payload sizes in production.
      */
-    version?: string;
+    onRender?: (metrics: RenderMetrics) => void;
+    /**
+     * SSR configuration options.
+     *
+     * Enables pre-rendering of components on the server to improve SEO and
+     * initial load performance.
+     */
+    ssr?: {
+        /** Whether SSR is enabled for the current environment. */
+        enabled: boolean;
+        /**
+         * Function to handle SSR rendering.
+         *
+         * Should interface with your frontend framework's SSR renderer (e.g., React's `renderToString`).
+         */
+        render?: (page: any) => Promise<{
+            head: string[];
+            body: string;
+        }>;
+    };
+}
+/**
+ * Encapsulates performance and status metrics for a single render operation.
+ *
+ * Provides insights into the rendering lifecycle, including component name,
+ * execution time, and payload complexity.
+ */
+interface RenderMetrics {
+    /** Name of the frontend component rendered. */
+    component: string;
+    /** Time taken in milliseconds for the entire render lifecycle. */
+    duration: number;
+    /** Indicates if the request was an Inertia AJAX request (true) or a full page load (false). */
+    isInertiaRequest: boolean;
+    /** Number of top-level props passed to the component after resolution. */
+    propsCount: number;
+    /** Epoch timestamp of when the operation completed. */
+    timestamp: number;
+    /** Resulting HTTP status code of the response. */
+    status?: number;
 }
 /**
- * InertiaService - Server-side Inertia.js adapter
+ * Server-side adapter for the Inertia.js protocol.
  *
- * This service handles the Inertia.js protocol for seamless
- * SPA-like navigation with server-side routing.
+ * The `InertiaService` is responsible for:
+ * 1. Resolving component props (including lazy/async props).
+ * 2. Handling partial reloads (filtering props based on `X-Inertia-Partial-Data`).
+ * 3. Managing asset versioning to ensure client-server synchronization.
+ * 4. Orchestrating SSR pre-rendering when enabled.
+ * 5. Generating the final HTTP response (JSON for AJAX, HTML for initial load).
  *
  * @example
  * ```typescript
- * // In a controller
- * async index(ctx: GravitoContext) {
- *   const inertia = ctx.get('inertia') as InertiaService
- *   return inertia.render('Home', { users: await User.all() })
- * }
+ * const inertia = new InertiaService(ctx, {
+ *   version: () => getGitHash(),
+ *   rootView: 'main'
+ * });
+ *
+ * // Share global data
+ * inertia.share('user', ctx.get('user'));
+ *
+ * // Render a component
+ * return await inertia.render('Dashboard/Index', {
+ *   stats: async () => await fetchStats() // Lazy prop
+ * });
  * ```
  */
 declare class InertiaService {
     private context;
     private config;
     private sharedProps;
+    private readonly logLevel;
+    private readonly onRenderCallback?;
     /**
-     * Create a new InertiaService instance
+     * Initializes a new instance of the Inertia service.
      *
-     * @param context - The Gravito request context
-     * @param config - Optional configuration
+     * @param context - The current Gravito request context.
+     * @param config - Instance configuration options.
      */
     constructor(context: GravitoContext<GravitoVariables>, config?: InertiaConfig);
     /**
-     * Escape a string for safe use in HTML attributes
+     * Internal logging helper that respects the configured log level.
      *
-     * Strategy: JSON.stringify already escapes special characters including
-     * quotes as \". We need to escape these for HTML attributes, but we must
-     * be careful not to break JSON escape sequences.
+     * Routes logs to the Gravito context logger if available.
      *
-     * The solution: Escape backslash-quote sequences (\" from JSON.stringify)
-     * as \\&quot; so they become \\&quot; in HTML, which the browser decodes
-     * to \\" (valid JSON), not \&quot; (invalid JSON).
+     * @param level - Log severity level.
+     * @param message - Descriptive message.
+     * @param data - Optional metadata for the log.
+     */
+    private log;
+    /**
+     * Escapes a string for safe embedding into a single-quoted HTML attribute.
      *
-     * @param value - The string to escape.
-     * @returns The escaped string.
+     * This ensures that JSON strings can be safely passed to the frontend
+     * via the `data-page` attribute without breaking the HTML structure or
+     * introducing XSS vulnerabilities.
+     *
+     * @param value - Raw JSON or text string.
+     * @returns Safely escaped HTML attribute value.
      */
     private escapeForSingleQuotedHtmlAttribute;
     /**
-     * Render an Inertia component
+     * Renders an Inertia component and returns the appropriate HTTP response.
+     *
+     * This method handles the entire Inertia lifecycle:
+     * - Detects if the request is an Inertia AJAX request.
+     * - Validates asset versions.
+     * - Resolves props (executes functions, handles partial reloads).
+     * - Performs SSR if configured.
+     * - Wraps the result in a JSON response or the root HTML template.
      *
-     * @param component - The component name to render
-     * @param props - Props to pass to the component
-     * @param rootVars - Additional variables for the root template
-     * @returns HTTP Response
+     * @param component - Frontend component name (e.g., 'Users/Profile').
+     * @param props - Data passed to the component. Can include functions for lazy evaluation.
+     * @param rootVars - Variables passed to the root HTML template (only used on initial load).
+     * @param status - Optional HTTP status code.
+     * @returns A promise that resolves to a Gravito HTTP Response.
+     *
+     * @throws {@link InertiaError}
+     * Thrown if:
+     * - The `ViewService` is missing from the context (required for initial load).
+     * - Prop serialization fails due to circular references or non-serializable data.
      *
      * @example
      * ```typescript
-     * return inertia.render('Users/Index', {
-     *   users: await User.all(),
-     *   filters: { search: ctx.req.query('search') }
-     * })
+     * // Standard render
+     * return await inertia.render('Welcome', { name: 'Guest' });
+     *
+     * // Partial reload support (only 'stats' will be resolved if requested)
+     * return await inertia.render('Dashboard', {
+     *   user: auth.user,
+     *   stats: () => db.getStats()
+     * });
      * ```
      */
-    render(component: string, props?: Record<string, unknown>, rootVars?: Record<string, unknown>): Response;
+    render<T extends Record<string, unknown> = Record<string, unknown>>(component: string, props?: T, rootVars?: Record<string, unknown>, status?: number): Promise<Response>;
     /**
-     * Share data with all Inertia responses
+     * Registers a piece of data to be shared with all Inertia responses for the current request.
      *
-     * Shared props are merged with component-specific props on every render.
+     * Shared props are automatically merged with component-specific props during the render phase.
+     * This is the primary mechanism for providing global state like authentication details,
+     * flash messages, or configuration to the frontend.
      *
-     * @param key - The prop key
-     * @param value - The prop value
+     * @param key - Identifier for the shared prop.
+     * @param value - Value to share. Must be JSON serializable.
      *
      * @example
      * ```typescript
-     * // In middleware
-     * inertia.share('auth', { user: ctx.get('auth')?.user() })
-     * inertia.share('flash', ctx.get('session')?.getFlash('message'))
+     * inertia.share('appName', 'Gravito Store');
+     * inertia.share('auth', { user: ctx.get('user') });
      * ```
      */
     share(key: string, value: unknown): void;
     /**
-     * Share multiple props at once
+     * Shares multiple props in a single operation.
+     *
+     * Merges the provided object into the existing shared props state. Existing keys
+     * with the same name will be overwritten.
      *
-     * @param props - Object of props to share
+     * @param props - Object containing key-value pairs to merge into the shared state.
+     *
+     * @example
+     * ```typescript
+     * inertia.shareAll({
+     *   version: '1.2.0',
+     *   environment: 'production',
+     *   features: ['chat', 'search']
+     * });
+     * ```
      */
     shareAll(props: Record<string, unknown>): void;
     /**
-     * Get all shared props
+     * Returns a shallow copy of the current shared props.
+     *
+     * Useful for inspecting the shared state or for manual prop merging in advanced scenarios.
+     *
+     * @returns A dictionary containing all currently registered shared props.
      *
-     * @returns A shallow copy of the shared props object.
+     * @example
+     * ```typescript
+     * const shared = inertia.getSharedProps();
+     * if (!shared.auth) {
+     *   console.warn('Authentication data is missing from shared props');
+     * }
+     * ```
      */
     getSharedProps(): Record<string, unknown>;
 }
 
 /**
- * @fileoverview Orbit Inertia - Inertia.js integration for Gravito
+ * Base error class for all Inertia-related operations in Gravito.
+ */
+declare class InertiaError extends Error {
+    readonly code: string;
+    readonly httpStatus: number;
+    readonly details?: Record<string, any> | undefined;
+    constructor(code: string, httpStatus?: number, details?: Record<string, any> | undefined);
+    toJSON(): {
+        name: string;
+        code: string;
+        httpStatus: number;
+        message: string;
+        details: Record<string, any> | undefined;
+    };
+}
+/**
+ * Configuration errors - e.g., missing services.
+ */
+declare class InertiaConfigError extends InertiaError {
+    constructor(message: string, details?: Record<string, any>);
+}
+/**
+ * Data/Serialization errors - e.g., circular references or resolution failure.
+ */
+declare class InertiaDataError extends InertiaError {
+    constructor(message: string, details?: Record<string, any>);
+}
+/**
+ * Template/Rendering errors.
+ */
+declare class InertiaTemplateError extends InertiaError {
+    constructor(message: string, details?: Record<string, any>);
+}
+
+/**
+ * @fileoverview Orbit Inertia - Inertia.js integration for Gravito.
  *
- * Provides server-side Inertia.js integration for building modern
- * single-page applications with server-side routing.
+ * This module provides the core Orbit definition and helper interfaces for
+ * building modern single-page applications using server-side routing.
  *
  * @module @gravito/ion
- * @since 1.0.0
  */
 
 /**
- * InertiaHelper is a callable function and service suite injected into the Gravito context.
- * It allows you to render Inertia components directly or manage shared data.
+ * Enhanced helper interface for Inertia operations within the Gravito context.
+ *
+ * This interface is both a callable function for quick rendering and a
+ * service container for managing shared data and accessing the underlying service.
+ * It is typically accessed via `ctx.get('inertia')`.
  *
  * @example
  * ```typescript
- * // Direct call rendering
- * return ctx.get('inertia')('Welcome', { user });
+ * // 1. Direct rendering (Callable)
+ * export const index = async (ctx: Context) => {
+ *   return await ctx.get('inertia')('Home', { title: 'Welcome' });
+ * };
  *
- * // Using shared data
- * ctx.get('inertia').share('appName', 'Gravito App');
+ * // 2. Sharing global data
+ * ctx.get('inertia').share('app_name', 'My Project');
+ *
+ * // 3. Accessing the underlying service
+ * const service = ctx.get('inertia').service;
  * ```
- * @public
  */
 interface InertiaHelper {
     /**
-     * Render an Inertia component.
-     * Shortcut for context.get('inertia').render()
+     * Renders an Inertia component.
+     *
+     * This is a shortcut for calling `render()` on the underlying service.
+     *
+     * @param component - Frontend component name (e.g., 'Pages/Dashboard').
+     * @param props - Data object passed to the component. Supports lazy/async props.
+     * @param rootVars - Variables passed to the root HTML template (initial load only).
+     * @param status - Optional HTTP status code (defaults to 200).
+     * @returns A promise resolving to a Gravito-compatible HTTP Response.
+     *
+     * @throws {@link InertiaError}
+     * Thrown if serialization fails or the ViewService is missing during initial load.
+     */
+    <T extends Record<string, unknown> = Record<string, unknown>>(component: string, props?: T, rootVars?: Record<string, unknown>, status?: number): Promise<Response>;
+    /**
+     * Shares a single piece of data with all subsequent Inertia responses for this request.
      *
-     * @param component - The name of the frontend component (e.g., 'Pages/Home')
-     * @param props - Data to pass to the component
-     * @param rootVars - Variables for the root HTML template (e.g., meta tags)
+     * @param key - Unique identifier for the shared prop.
+     * @param value - Data value. Must be JSON serializable.
      */
-    (component: string, props?: Record<string, unknown>, rootVars?: Record<string, unknown>): Response;
-    /** Share data with all Inertia responses for the remainder of the request */
     share(key: string, value: unknown): void;
-    /** Share multiple props at once */
+    /**
+     * Shares multiple props simultaneously by merging them into the shared state.
+     *
+     * @param props - Key-value pairs to merge into shared props.
+     */
     shareAll(props: Record<string, unknown>): void;
-    /** Get all currently shared props */
+    /**
+     * Retrieves a copy of all currently shared props for the current request.
+     *
+     * @returns Current shared props dictionary.
+     */
     getSharedProps(): Record<string, unknown>;
-    /** Explicitly render an Inertia component */
-    render(component: string, props?: Record<string, unknown>, rootVars?: Record<string, unknown>): Response;
-    /** Direct access to the low-level Inertia service instance */
+    /**
+     * Explicitly renders an Inertia component.
+     *
+     * Identical to the callable interface but provided for semantic clarity.
+     *
+     * @param component - Frontend component name.
+     * @param props - Component data.
+     * @param rootVars - Template variables.
+     * @param status - HTTP status code.
+     * @returns A promise resolving to an HTTP Response.
+     *
+     * @throws {@link InertiaError}
+     * Thrown if the rendering lifecycle encounters a fatal error.
+     */
+    render<T extends Record<string, unknown> = Record<string, unknown>>(component: string, props?: T, rootVars?: Record<string, unknown>, status?: number): Promise<Response>;
+    /**
+     * Direct access to the low-level `InertiaService` instance.
+     *
+     * Use this for advanced operations not exposed by the helper interface.
+     */
     service: InertiaService;
 }
 /**
- * Options for configuring OrbitIon.
- * @public
+ * Configuration options for the OrbitIon extension.
+ *
+ * Controls how the Inertia protocol is integrated into the Gravito ecosystem.
  */
 interface OrbitIonOptions {
-    /** Current asset version to detect staleness (X-Inertia-Version) */
-    version?: string;
-    /** The root HTML template view (default: 'app') */
+    /**
+     * Asset version string or resolver used for cache busting.
+     *
+     * If not provided, it defaults to the `APP_VERSION` defined in the core configuration.
+     *
+     * @defaultValue '1.0.0'
+     */
+    version?: string | (() => string | Promise<string>);
+    /**
+     * The name of the root HTML template file (without extension).
+     *
+     * This template is used for the initial page load.
+     *
+     * @defaultValue 'app'
+     */
     rootView?: string;
+    /**
+     * SSR configuration options.
+     *
+     * Enables server-side pre-rendering of components.
+     */
+    ssr?: {
+        /** Whether SSR is enabled for this application. */
+        enabled: boolean;
+        /**
+         * Function to handle SSR rendering.
+         *
+         * Receives the Inertia page object and should return the rendered HTML.
+         */
+        render?: (page: any) => Promise<{
+            head: string[];
+            body: string;
+        }>;
+    };
 }
 /**
  * OrbitIon provides official Inertia.js integration for Gravito.
  *
- * It handles Inertia requests, partial reloads, asset versioning, and seamless
- * data sharing between the server and your frontend application (React, Vue, etc.).
- *
- * It injects an `InertiaHelper` into the context, allowing you to render
- * components with a simple function call: `c.get('inertia')('Page', { props })`.
+ * As an infrastructure extension (Orbit), it:
+ * 1. Registers a global middleware to handle the Inertia protocol.
+ * 2. Manages asset version synchronization (X-Inertia-Version).
+ * 3. Injects the `InertiaHelper` into the request context for easy access in controllers.
+ * 4. Supports partial reloads and SSR out of the box.
  *
  * @example
  * ```typescript
  * import { OrbitIon } from '@gravito/ion';
  *
+ * // In your application bootstrap
  * core.addOrbit(new OrbitIon({
- *   version: '1.0.0',
- *   rootView: 'app'
+ *   version: 'v2.1.0',
+ *   rootView: 'layouts/app',
+ *   ssr: {
+ *     enabled: process.env.SSR === 'true',
+ *     render: async (page) => await mySsrRenderer(page)
+ *   }
  * }));
  * ```
- *
- * @public
- * @since 3.0.0
  */
 declare class OrbitIon implements GravitoOrbit {
     private options;
+    /**
+     * Initializes the Orbit with custom configuration.
+     *
+     * @param options - Configuration overrides for the Inertia service.
+     */
     constructor(options?: OrbitIonOptions);
     /**
-     * Install the inertia orbit into PlanetCore
+     * Registers the Inertia middleware and service factory into PlanetCore.
+     *
+     * This method is called automatically by Gravito during the boot process.
+     * It sets up the `InertiaService` for each request and attaches
+     * the `InertiaHelper` proxy to the context.
+     *
+     * @param core - The Gravito micro-kernel instance.
+     *
+     * @example
+     * ```typescript
+     * const ion = new OrbitIon({ version: '1.0' });
+     * ion.install(core);
+     * ```
      */
     install(core: PlanetCore): void;
 }
 
-export { type InertiaConfig, type InertiaHelper, InertiaService, OrbitIon, type OrbitIonOptions, OrbitIon as default };
+export { type InertiaConfig, InertiaConfigError, InertiaDataError, InertiaError, type InertiaHelper, InertiaService, InertiaTemplateError, OrbitIon, type OrbitIonOptions, type RenderMetrics, OrbitIon as default };