@gravito/ion 3.0.1 → 3.1.0

package/dist/index.cjs

@@ -20,133 +20,364 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  InertiaConfigError: () => InertiaConfigError,
+  InertiaDataError: () => InertiaDataError,
+  InertiaError: () => InertiaError,
   InertiaService: () => InertiaService,
+  InertiaTemplateError: () => InertiaTemplateError,
   OrbitIon: () => OrbitIon,
   default: () => index_default
 });
 module.exports = __toCommonJS(index_exports);
 
+// src/errors.ts
+var InertiaError = class extends Error {
+  constructor(code, httpStatus = 500, details) {
+    super(code);
+    this.code = code;
+    this.httpStatus = httpStatus;
+    this.details = details;
+    this.name = "InertiaError";
+    Object.setPrototypeOf(this, new.target.prototype);
+    Error.captureStackTrace?.(this, this.constructor);
+  }
+  toJSON() {
+    return {
+      name: this.name,
+      code: this.code,
+      httpStatus: this.httpStatus,
+      message: this.message,
+      details: this.details
+    };
+  }
+};
+var InertiaConfigError = class extends InertiaError {
+  constructor(message, details) {
+    super("CONFIG_ERROR", 500, {
+      ...details,
+      message,
+      hint: details?.hint ?? "Check your OrbitIon configuration and ensure dependencies are loaded."
+    });
+    this.name = "InertiaConfigError";
+  }
+};
+var InertiaDataError = class extends InertiaError {
+  constructor(message, details) {
+    super("DATA_ERROR", 500, {
+      ...details,
+      message,
+      hint: details?.hint ?? "Ensure all props are JSON-serializable (no circular refs, BigInt, or functions)."
+    });
+    this.name = "InertiaDataError";
+  }
+};
+var InertiaTemplateError = class extends InertiaError {
+  constructor(message, details) {
+    super("TEMPLATE_ERROR", 500, {
+      ...details,
+      message,
+      hint: details?.hint ?? "Check if the root view template exists and is properly configured."
+    });
+    this.name = "InertiaTemplateError";
+  }
+};
+
 // src/InertiaService.ts
 var InertiaService = class {
   /**
-   * 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, config = {}) {
     this.context = context;
     this.config = config;
+    this.logLevel = config.logLevel ?? "info";
+    this.onRenderCallback = config.onRender;
   }
   sharedProps = {};
+  logLevel;
+  onRenderCallback;
   /**
-   * Escape a string for safe use in HTML attributes
+   * Internal logging helper that respects the configured log level.
+   *
+   * Routes logs to the Gravito context logger if available.
    *
-   * 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.
+   * @param level - Log severity level.
+   * @param message - Descriptive message.
+   * @param data - Optional metadata for the log.
+   */
+  log(level, message, data) {
+    const levels = ["debug", "info", "warn", "error", "silent"];
+    const currentLevelIndex = levels.indexOf(this.logLevel);
+    const messageLevelIndex = levels.indexOf(level);
+    if (this.logLevel === "silent" || messageLevelIndex < currentLevelIndex) {
+      return;
+    }
+    const logger = typeof this.context.get === "function" ? this.context.get("logger") : void 0;
+    if (logger && typeof logger[level] === "function") {
+      logger[level](message, data);
+    }
+  }
+  /**
+   * Escapes a string for safe embedding into a single-quoted HTML attribute.
    *
-   * 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).
+   * 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 - The string to escape.
-   * @returns The escaped string.
+   * @param value - Raw JSON or text string.
+   * @returns Safely escaped HTML attribute value.
    */
   escapeForSingleQuotedHtmlAttribute(value) {
     return value.replace(/&/g, "&amp;").replace(/\\"/g, "\\&quot;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/'/g, "&#039;");
   }
   /**
-   * 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, props = {}, rootVars = {}) {
-    let pageUrl;
+  async render(component, props, rootVars = {}, status) {
+    const startTime = performance.now();
+    const isInertiaRequest = Boolean(this.context.req.header("X-Inertia"));
     try {
-      const reqUrl = new URL(this.context.req.url, "http://localhost");
-      pageUrl = reqUrl.pathname + reqUrl.search;
-    } catch {
-      pageUrl = this.context.req.url;
-    }
-    const resolveProps = (p) => {
-      const resolved = {};
-      for (const [key, value] of Object.entries(p)) {
-        resolved[key] = typeof value === "function" ? value() : value;
+      this.log("debug", "[InertiaService] Starting render", {
+        component,
+        isInertiaRequest,
+        propsCount: props ? Object.keys(props).length : 0
+      });
+      let pageUrl;
+      try {
+        const reqUrl = new URL(this.context.req.url, "http://localhost");
+        pageUrl = reqUrl.pathname + reqUrl.search;
+      } catch {
+        pageUrl = this.context.req.url;
       }
-      return resolved;
-    };
-    const page = {
-      component,
-      props: resolveProps({ ...this.sharedProps, ...props }),
-      url: pageUrl,
-      version: this.config.version
-    };
-    if (this.context.req.header("X-Inertia")) {
-      this.context.header("X-Inertia", "true");
-      this.context.header("Vary", "Accept");
-      return this.context.json(page);
-    }
-    const view = this.context.get("view");
-    const rootView = this.config.rootView ?? "app";
-    if (!view) {
-      throw new Error("OrbitPrism is required for the initial page load in OrbitIon");
+      const resolveProps = async (p) => {
+        const partialData = this.context.req.header("X-Inertia-Partial-Data");
+        const partialExcept = this.context.req.header("X-Inertia-Partial-Except");
+        const partialComponent = this.context.req.header("X-Inertia-Partial-Component");
+        const isPartial = partialComponent === component;
+        const only = partialData && isPartial ? partialData.split(",") : [];
+        const except = partialExcept && isPartial ? partialExcept.split(",") : [];
+        const resolved = {};
+        for (const [key, value] of Object.entries(p)) {
+          if (only.length > 0 && !only.includes(key)) {
+            continue;
+          }
+          if (except.length > 0 && except.includes(key)) {
+            continue;
+          }
+          if (typeof value === "function") {
+            const propStart = performance.now();
+            try {
+              resolved[key] = await value();
+              this.log("debug", `[InertiaService] Resolved lazy prop: ${key}`, {
+                duration: `${(performance.now() - propStart).toFixed(2)}ms`
+              });
+            } catch (err) {
+              this.log("error", `[InertiaService] Failed to resolve lazy prop: ${key}`, { err });
+              throw new InertiaDataError(`Failed to resolve lazy prop: ${key}`, { cause: err });
+            }
+          } else {
+            resolved[key] = value;
+          }
+        }
+        return resolved;
+      };
+      const resolveVersion = async () => {
+        if (typeof this.config.version === "function") {
+          return await this.config.version();
+        }
+        return this.config.version;
+      };
+      const version = await resolveVersion();
+      const getMergedProps = () => {
+        const propsToMerge = props ?? {};
+        if (Object.keys(propsToMerge).length === 0) {
+          return this.sharedProps;
+        }
+        return { ...this.sharedProps, ...propsToMerge };
+      };
+      const page = {
+        component,
+        props: await resolveProps(getMergedProps()),
+        url: pageUrl,
+        version
+      };
+      let pageJson;
+      try {
+        pageJson = JSON.stringify(page);
+      } catch (error) {
+        throw new InertiaDataError(
+          `Inertia page serialization failed for component: ${component}`,
+          {
+            cause: error
+          }
+        );
+      }
+      let response;
+      if (isInertiaRequest) {
+        const clientVersion = this.context.req.header("X-Inertia-Version");
+        if (version && clientVersion && clientVersion !== version) {
+          this.context.header("X-Inertia-Location", pageUrl);
+          return new Response("", { status: 409 });
+        }
+        this.context.header("X-Inertia", "true");
+        this.context.header("Vary", "Accept");
+        response = this.context.json(page, status);
+      } else {
+        const view = this.context.get("view");
+        const rootView = this.config.rootView ?? "app";
+        if (!view) {
+          throw new InertiaConfigError(
+            "ViewService (OrbitPrism) is required for initial page load but was not found in context.",
+            { hint: "Ensure OrbitPrism is loaded before OrbitIon in your orbit configuration" }
+          );
+        }
+        const isDev = process.env.NODE_ENV !== "production";
+        let ssrData = { head: [], body: "" };
+        if (this.config.ssr?.enabled && this.config.ssr.render) {
+          try {
+            ssrData = await this.config.ssr.render(page);
+          } catch (error) {
+            this.log("error", "[InertiaService] SSR rendering failed", { error });
+          }
+        }
+        response = this.context.html(
+          view.render(
+            rootView,
+            {
+              ...rootVars,
+              page: this.escapeForSingleQuotedHtmlAttribute(pageJson),
+              isDev,
+              ssrHead: ssrData.head.join("\n"),
+              ssrBody: ssrData.body
+            },
+            { layout: "" }
+          ),
+          status
+        );
+      }
+      const duration = performance.now() - startTime;
+      this.log("info", "[InertiaService] Render complete", {
+        component,
+        duration: `${duration.toFixed(2)}ms`,
+        isInertiaRequest,
+        status: status ?? 200
+      });
+      if (this.onRenderCallback) {
+        this.onRenderCallback({
+          component,
+          duration,
+          isInertiaRequest,
+          propsCount: props ? Object.keys(props).length : 0,
+          timestamp: Date.now(),
+          status
+        });
+      }
+      return response;
+    } catch (error) {
+      const duration = performance.now() - startTime;
+      if (error instanceof InertiaError) {
+        this.log("error", "[InertiaService] Render failed", {
+          component,
+          duration: `${duration.toFixed(2)}ms`,
+          errorCode: error.code,
+          errorDetails: error.details
+        });
+        throw error;
+      }
+      this.log("error", "[InertiaService] Unexpected render error", {
+        component,
+        duration: `${duration.toFixed(2)}ms`,
+        error
+      });
+      return new Response("Inertia Render Error", { status: 500 });
     }
-    const isDev = process.env.NODE_ENV !== "production";
-    return this.context.html(
-      view.render(
-        rootView,
-        {
-          ...rootVars,
-          page: this.escapeForSingleQuotedHtmlAttribute(JSON.stringify(page)),
-          isDev
-        },
-        { layout: "" }
-      )
-    );
   }
-  // ...
   /**
-   * 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, value) {
     this.sharedProps[key] = value;
   }
   /**
-   * 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) {
     Object.assign(this.sharedProps, props);
   }
   /**
-   * 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 shallow copy of the shared props object.
+   * @returns A dictionary containing all currently registered shared props.
+   *
+   * @example
+   * ```typescript
+   * const shared = inertia.getSharedProps();
+   * if (!shared.auth) {
+   *   console.warn('Authentication data is missing from shared props');
+   * }
+   * ```
    */
   getSharedProps() {
     return { ...this.sharedProps };
@@ -155,11 +386,28 @@ var InertiaService = class {
 
 // src/index.ts
 var OrbitIon = class {
+  /**
+   * Initializes the Orbit with custom configuration.
+   *
+   * @param options - Configuration overrides for the Inertia service.
+   */
   constructor(options = {}) {
     this.options = options;
   }
   /**
-   * 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) {
     core.logger.info("\u{1F6F0}\uFE0F Orbit Inertia installed (Callable Interface)");
@@ -167,20 +415,19 @@ var OrbitIon = class {
     const rootView = this.options.rootView ?? "app";
     core.adapter.use("*", async (c, next) => {
       const service = new InertiaService(c, {
-        version: String(appVersion),
-        rootView
+        version: appVersion,
+        rootView,
+        ssr: this.options.ssr
       });
-      const inertiaProxy = (component, props = {}, rootVars = {}) => {
-        return service.render(component, props, rootVars);
+      const inertiaProxy = async (component, props = {}, rootVars = {}, status) => {
+        return await service.render(component, props, rootVars, status);
       };
       Object.assign(inertiaProxy, {
         share: service.share.bind(service),
         shareAll: service.shareAll.bind(service),
         getSharedProps: service.getSharedProps.bind(service),
         render: service.render.bind(service),
-        // Also allow .render()
         service
-        // Access to the raw service instance
       });
       c.set("inertia", inertiaProxy);
       return await next();
@@ -190,6 +437,10 @@ var OrbitIon = class {
 var index_default = OrbitIon;
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  InertiaConfigError,
+  InertiaDataError,
+  InertiaError,
   InertiaService,
+  InertiaTemplateError,
   OrbitIon
 });