npm - inertia-sails - Versions diffs - 1.4.0 → 1.5.0 - Mend

inertia-sails 1.4.0 → 1.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (18) hide show

package/README.md +177 -1
package/index.js +92 -0
package/lib/handle-bad-request.js +51 -45
package/lib/helpers/humanize-validation-errors.js +590 -0
package/lib/helpers/inertia-headers.js +10 -1
package/lib/helpers/precognition.js +150 -0
package/lib/helpers/vary-header.js +26 -0
package/lib/render.js +13 -1
package/lib/responses/server-error.js +422 -288
package/lib/ssr.js +200 -0
package/lib/types.js +3 -1
package/package.json +4 -2
package/tests/handle-bad-request.test.js +318 -0
package/tests/helpers/precognition.test.js +172 -0
package/tests/helpers/preserve-fragment.test.js +21 -0
package/tests/props/resolve-page-props.test.js +29 -0
package/tests/render.test.js +121 -2
package/tests/server-error.test.js +280 -0

package/README.md CHANGED Viewed

@@ -90,6 +90,11 @@ Return a URL string to redirect:
 return '/dashboard'
 ```
+`inertiaRedirect` performs an Inertia location visit. It does not return a
+page object, so `sails.inertia.preserveFragment()` does not apply to this
+response type. If you already know the fragment you want, include it in the
+returned URL.
 #### Preserving URL fragments
 When a standard Inertia redirect should carry the current hash to the next
@@ -189,6 +194,154 @@ sails.inertia.flash({ error: 'Failed', field: 'email' })
 Access in your frontend via `page.props.flash`.
+### Error Pages
+In development, 500-level HTML responses render a rich Youch error page with
+the stack trace and sanitized request metadata. For Inertia visits, the client
+will show that HTML in its development error modal.
+In production, `inertia-sails` renders the configured Inertia error page for
+`403`, `404`, `500`, and `503` responses by default. The page receives
+`status`, `title`, and `message` props:
+```vue
+<!-- assets/js/pages/error.vue -->
+<script setup>
+import { Head, Link } from '@inertiajs/vue3'
+defineProps({
+  status: Number,
+  title: String,
+  message: String
+})
+</script>
+<template>
+  <Head :title="`${status} ${title}`" />
+  <main>
+    <p>Status {{ status }}</p>
+    <h1>{{ title }}</h1>
+    <p>{{ message }}</p>
+    <Link href="/">Go home</Link>
+  </main>
+</template>
+```
+Wire Sails' standard responses through the hook so framework-level 403/404/500
+responses use the same policy:
+```js
+// api/responses/serverError.js
+module.exports = function serverError(error) {
+  return this.req._sails.inertia.handleServerError(this.req, this.res, error)
+}
+// api/responses/notFound.js
+module.exports = function notFound(error) {
+  return this.req._sails.inertia.handleErrorPage(this.req, this.res, {
+    statusCode: 404,
+    error
+  })
+}
+// api/responses/forbidden.js
+module.exports = function forbidden(error) {
+  return this.req._sails.inertia.handleErrorPage(this.req, this.res, {
+    statusCode: 403,
+    error
+  })
+}
+```
+Hybrid apps can keep classic Sails EJS error views by disabling the Inertia
+error page:
+```js
+// config/inertia.js
+module.exports.inertia = {
+  errorPage: false
+}
+```
+### Precognition
+Inertia v3 forms can validate against server-owned Sails rules before the real
+submit runs. `inertia-sails` handles the Precognition response headers and
+returns validation failures as `422` JSON instead of redirecting through the
+normal session-backed Inertia error flow.
+Use `withPrecognition()` on the client:
+```js
+const form = useForm({
+  email: null
+}).withPrecognition('post', '/forgot-password')
+```
+Then validate a field when the user leaves it:
+```vue
+<InputEmail v-model="form.email" @blur="form.validate('email')" />
+```
+On the server, add a small custom response so successful Precognition checks
+can exit before side effects without going through the action's normal
+`success` response type:
+```js
+// api/responses/precognitionSuccess.js
+module.exports = function precognitionSuccess() {
+  return this.req._sails.inertia.handlePrecognitionSuccess(this.req, this.res)
+}
+```
+Then use a named exit in the action:
+```js
+exits: {
+  success: {
+    responseType: 'redirect'
+  },
+  precognitionSuccess: {
+    responseType: 'precognitionSuccess'
+  }
+},
+fn: async function ({ email }, exits) {
+  if (sails.inertia.isPrecognitive(this.req)) {
+    return exits.precognitionSuccess()
+  }
+  await sendPasswordResetEmail(email)
+  return '/check-email'
+}
+```
+For custom database-backed checks, use `shouldValidate()` so expensive rules
+only run when the client asked for that field:
+```js
+if (sails.inertia.shouldValidate('email', this.req)) {
+  const existingUser = await User.findOne({ email })
+  if (existingUser) {
+    throw {
+      badSignupRequest: {
+        problems: [{ email: 'An account with this email already exists.' }]
+      }
+    }
+  }
+}
+```
+Available helpers:
+- `sails.inertia.isPrecognitive(req?)`
+- `sails.inertia.validateOnly(req?)`
+- `sails.inertia.shouldValidate(field, req?)`
+- `sails.inertia.handlePrecognitionSuccess(req, res)` for custom responses
 ### Deferred Props
 Load props after initial page render:
@@ -222,6 +375,22 @@ return {
 }
 ```
+Or pass the rescue option inline:
+```js
+return {
+  page: 'dashboard',
+  props: {
+    analytics: sails.inertia.defer(
+      async () => {
+        return await Analytics.getExpensiveReport()
+      },
+      { rescue: true }
+    )
+  }
+}
+```
 When a rescued deferred prop throws, it is omitted from `props` and its key is
 reported in `rescuedProps`, allowing the client `<Deferred>` component to show
 its rescue slot instead of failing the whole deferred response.
@@ -381,6 +550,8 @@ Copy these to `api/responses/`:
 - **inertiaRedirect.js** - Handle Inertia redirects
 - **badRequest.js** - Validation errors with redirect back
 - **serverError.js** - Error modal in dev, graceful redirect in prod
+- **notFound.js** - 404 status pages
+- **forbidden.js** - 403 status pages
 ## Architecture
@@ -400,7 +571,12 @@ module.exports.inertia = {
   // History encryption settings
   history: {
     encrypt: false
-  }
+  },
+  // Production status page component.
+  // Set to false to keep classic Sails EJS error views.
+  errorPage: 'error',
+  errorStatuses: [403, 404, 500, 503]
 }
 ```

package/index.js CHANGED Viewed

@@ -23,6 +23,7 @@
  * @property {string} page - The component name to render
  * @property {InertiaProps} [props] - Props to pass to the component
  * @property {InertiaProps} [locals] - Additional locals for the root EJS template
+ * @property {boolean} [ssr] - Whether to server-render this response when SSR is enabled
  *
  * @typedef {Object} DeferOptions
  * @property {boolean} [rescue=false] - Rescue callback failures
@@ -40,6 +41,12 @@ const inertia = require('./lib/middleware/inertia-middleware')
 const render = require('./lib/render')
 const location = require('./lib/location')
 const requestContext = require('./lib/helpers/request-context')
+const {
+  getValidateOnlyFields,
+  isPrecognitiveRequest,
+  sendPrecognitionSuccess,
+  shouldValidateField
+} = require('./lib/helpers/precognition')
 const DeferProp = require('./lib/props/defer-prop')
 const OptionalProp = require('./lib/props/optional-prop')
@@ -112,11 +119,19 @@ module.exports = function defineInertiaHook(sails) {
     defaults: {
       inertia: {
         rootView: 'app',
+        errorPage: 'error',
+        errorStatuses: [403, 404, 500, 503],
         // Auto-version from Shipwright manifest for cache busting
         // Override in config/inertia.js if needed
         version: () => getManifestVersion(),
         history: {
           encrypt: false
+        },
+        ssr: {
+          enabled: false,
+          bundle: '.tmp/ssr/inertia.mjs',
+          pages: false,
+          fallback: true
         }
       }
     },
@@ -639,6 +654,69 @@ module.exports = function defineInertiaHook(sails) {
       return handleBadRequest(req, res, optionalData)
     },
+    /**
+     * Determine if the current request is a Precognition validation request.
+     * @param {Request} [req] - The request object. Defaults to request context.
+     * @returns {boolean} - Whether this is a Precognition request.
+     */
+    isPrecognitive(req) {
+      return isPrecognitiveRequest(req || requestContext.getRequest())
+    },
+    /**
+     * Get the fields requested by Precognition-Validate-Only.
+     * @param {Request} [req] - The request object. Defaults to request context.
+     * @returns {string[]} - Fields requested for validation.
+     */
+    validateOnly(req) {
+      return getValidateOnlyFields(req || requestContext.getRequest())
+    },
+    /**
+     * Determine if a field should run validation for the current request.
+     * For non-Precognition requests, all fields should validate.
+     * @param {string} field - Field name, with dot notation and * wildcards supported.
+     * @param {Request} [req] - The request object. Defaults to request context.
+     * @returns {boolean} - Whether to validate this field.
+     */
+    shouldValidate(field, req) {
+      return shouldValidateField(req || requestContext.getRequest(), field)
+    },
+    /**
+     * Handle a successful Precognition validation response.
+     * This is intended for app-level custom responses such as
+     * `api/responses/precognitionSuccess.js`.
+     * @param {Request} req - The request object
+     * @param {Response} res - The response object
+     * @returns {*} - A 204 Precognition response.
+     */
+    handlePrecognitionSuccess(req, res) {
+      if (!res) {
+        throw new Error(
+          'sails.inertia.handlePrecognitionSuccess() called without a response object'
+        )
+      }
+      return sendPrecognitionSuccess(res)
+    },
+    /**
+     * Send a successful Precognition validation response.
+     * Low-level alias for custom responses and non-action callers.
+     * In actions with a responseType, prefer a named exit using a
+     * `precognitionSuccess` response file.
+     * @param {Request} [req] - The request object. Defaults to request context.
+     * @param {Response} [res] - The response object. Defaults to request context.
+     * @returns {*} - A 204 Precognition response.
+     */
+    precognitionSuccess(req, res) {
+      return this.handlePrecognitionSuccess(
+        req || requestContext.getRequest(),
+        res || requestContext.getResponse()
+      )
+    },
     /**
      * Handle server error responses for Inertia.js
      * For Inertia requests in development, displays a styled error modal with stack trace.
@@ -653,6 +731,20 @@ module.exports = function defineInertiaHook(sails) {
       return handleServerError(req, res, error)
     },
+    /**
+     * Handle application status/error pages for Inertia.js.
+     * In development, 500-level HTML responses use Youch. In production,
+     * configured Inertia apps can render an Inertia status page.
+     * @docs https://docs.sailscasts.com/boring-stack/error-handling
+     * @param {Request} req - The request object
+     * @param {Response} res - The response object
+     * @param {{ statusCode?: number, error?: ErrorLike|string|Record<string, any>|null, page?: string }} [options] - Error page options
+     * @returns {*} - Response
+     */
+    handleErrorPage(req, res, options) {
+      return handleServerError.handleErrorPage(req, res, options)
+    },
     /**
      * Configure paginated data for infinite scrolling.
      * Wraps Waterline paginated data with proper merge behavior and normalizes

package/lib/handle-bad-request.js CHANGED Viewed

@@ -3,6 +3,33 @@
  * @typedef {import('./types').InertiaResponse} InertiaResponse
  * @typedef {import('./types').BadRequestData} BadRequestData
  */
+const { INERTIA } = require('./helpers/inertia-headers')
+const humanizeValidationErrors = require('./helpers/humanize-validation-errors')
+const {
+  getValidateOnlyFields,
+  isPrecognitiveRequest,
+  sendPrecognitionErrors,
+  sendPrecognitionSuccess
+} = require('./helpers/precognition')
+/**
+ * @param {Record<string, string[]>} errors
+ * @param {string[]} fields
+ * @returns {Record<string, string[]>}
+ */
+function filterErrors(errors, fields) {
+  if (fields.length === 0) {
+    return errors
+  }
+  return fields.reduce((result, field) => {
+    if (errors[field]) {
+      result[field] = errors[field]
+    }
+    return result
+  }, /** @type {Record<string, string[]>} */ ({}))
+}
 /**
  * Handle bad request responses for Inertia.js
@@ -24,73 +51,52 @@
  */
 module.exports = function handleBadRequest(req, res, optionalData) {
   const sails = req._sails
+  const log = sails.log || {}
+  const response = /** @type {any} */ (res)
   // Define the status code to send in the response.
   const statusCodeToSet = 400
+  const errors = humanizeValidationErrors(optionalData)
+  if (isPrecognitiveRequest(req)) {
+    const filteredErrors = filterErrors(errors, getValidateOnlyFields(req))
-  // Check if it's an Inertia request
-  if (req.header?.('X-Inertia')) {
     if (
-      optionalData &&
-      !(optionalData instanceof Error) &&
-      Array.isArray(optionalData.problems)
+      Object.keys(errors).length > 0 &&
+      Object.keys(filteredErrors).length === 0
     ) {
-      /** @type {Record<string, string[]>} */
-      const errors = {}
-      optionalData.problems.forEach((problem) => {
-        if (typeof problem === 'object') {
-          Object.keys(problem).forEach((propertyName) => {
-            const sanitizedProblem = String(problem[propertyName]).replace(
-              /\.$/,
-              ''
-            ) // Trim trailing dot
-            if (!errors[propertyName]) {
-              errors[propertyName] = [sanitizedProblem]
-            } else {
-              errors[propertyName].push(sanitizedProblem)
-            }
-          })
-        } else {
-          const regex = /"(.*?)"/
-          const matches = problem.match(regex)
+      return sendPrecognitionSuccess(res)
+    }
-          if (matches && matches.length > 1) {
-            const propertyName = matches[1]
-            const sanitizedProblem = problem
-              .replace(/"([^"]+)"/, '$1')
-              .replace('\n', '')
-              .replace('·', '')
-              .trim()
-            if (!errors[propertyName]) {
-              errors[propertyName] = [sanitizedProblem]
-            } else {
-              errors[propertyName].push(sanitizedProblem)
-            }
-          }
-        }
-      })
+    return sendPrecognitionErrors(res, filteredErrors)
+  }
+  // Check if it's an Inertia request
+  if (req.header?.(INERTIA)) {
+    if (Object.keys(errors).length > 0) {
+      req.session = req.session || {}
       req.session.errors = errors
-      return res.redirect(303, req.get('Referrer') || '/')
+      return response.redirect(303, req.get('Referrer') || '/')
     }
   }
   // If not an Inertia request, perform the normal badRequest response
   if (optionalData === undefined) {
-    sails.log.info('Ran custom response: res.badRequest()')
-    return res.sendStatus(statusCodeToSet)
+    log.info?.('Ran custom response: res.badRequest()')
+    return response.sendStatus(statusCodeToSet)
   } else if (optionalData instanceof Error) {
-    sails.log.info(
+    log.info?.(
       'Custom response `res.badRequest()` called with an Error:',
       optionalData
     )
     if (typeof (/** @type {*} */ (optionalData).toJSON) !== 'function') {
       if (process.env.NODE_ENV === 'production') {
-        return res.sendStatus(statusCodeToSet)
+        return response.sendStatus(statusCodeToSet)
       } else {
-        return res.status(statusCodeToSet).send(optionalData.stack)
+        return response.status(statusCodeToSet).send(optionalData.stack)
       }
     }
   } else {
-    return res.status(statusCodeToSet).send(optionalData)
+    return response.status(statusCodeToSet).send(optionalData)
   }
 }