@gravito/ion 3.0.0 → 3.1.0

package/dist/index.js

@@ -1,124 +1,351 @@
+// 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.
    *
-   * 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 \\" so they become \\" in HTML, which the browser decodes
-   * to \\" (valid JSON), not \" (invalid JSON).
+   * @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.
+   *
+   * 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.
    *
-   * @param props - Object of props to share
+   * Merges the provided object into the existing shared props state. Existing keys
+   * with the same name will be overwritten.
+   *
+   * @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 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() {
     return { ...this.sharedProps };
@@ -127,31 +354,61 @@ 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");
+    core.logger.info("\u{1F6F0}\uFE0F Orbit Inertia installed (Callable Interface)");
     const appVersion = this.options.version ?? core.config.get("APP_VERSION", "1.0.0");
     const rootView = this.options.rootView ?? "app";
     core.adapter.use("*", async (c, next) => {
-      const gravitoCtx = c;
-      const inertia = new InertiaService(gravitoCtx, {
-        version: String(appVersion),
-        rootView
+      const service = new InertiaService(c, {
+        version: appVersion,
+        rootView,
+        ssr: this.options.ssr
+      });
+      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),
+        service
       });
-      c.set("inertia", inertia);
-      await next();
-      return void 0;
+      c.set("inertia", inertiaProxy);
+      return await next();
     });
   }
 };
 var index_default = OrbitIon;
 export {
+  InertiaConfigError,
+  InertiaDataError,
+  InertiaError,
   InertiaService,
+  InertiaTemplateError,
   OrbitIon,
   index_default as default
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gravito/ion",
-  "version": "3.0.0",
+  "version": "3.1.0",
   "description": "Inertia.js adapter for Gravito",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
@@ -20,10 +20,12 @@
   ],
   "scripts": {
     "build": "bun run build.ts",
-    "test": "bun test",
+    "test": "bun test --timeout=10000",
     "typecheck": "bun tsc -p tsconfig.json --noEmit --skipLibCheck",
-    "test:coverage": "bun test --coverage --coverage-threshold=80",
-    "test:ci": "bun test --coverage --coverage-threshold=80"
+    "test:coverage": "bun test --timeout=10000 --coverage --coverage-reporter=lcov --coverage-dir coverage && bun run --bun scripts/check-coverage.ts",
+    "test:ci": "bun test --timeout=10000 --coverage --coverage-reporter=lcov --coverage-dir coverage && bun run --bun scripts/check-coverage.ts",
+    "test:unit": "bun test tests/ --timeout=10000",
+    "test:integration": "test $(find tests -name '*.integration.test.ts' 2>/dev/null | wc -l) -gt 0 && find tests -name '*.integration.test.ts' -print0 | xargs -0 bun test --timeout=10000 || echo 'No integration tests found'"
   },
   "peerDependencies": {
     "@gravito/core": "workspace:*",
@@ -55,4 +57,4 @@
     "url": "git+https://github.com/gravito-framework/gravito.git",
     "directory": "packages/ion"
   }
-}
+}