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

inertia-sails 1.3.2 → 1.4.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 (41) hide show

package/README.md +55 -2
package/index.js +133 -81
package/lib/handle-bad-request.js +20 -6
package/lib/helpers/build-page-object.js +117 -12
package/lib/helpers/inertia-headers.js +4 -1
package/lib/helpers/is-inertia-partial-request.js +10 -0
package/lib/helpers/is-inertia-request.js +9 -0
package/lib/helpers/request-context.js +49 -8
package/lib/helpers/resolve-asset-version.js +12 -0
package/lib/helpers/resolve-validation-errors.js +12 -5
package/lib/location.js +11 -0
package/lib/middleware/inertia-middleware.js +7 -2
package/lib/props/always-prop.js +6 -2
package/lib/props/defer-prop.js +46 -6
package/lib/props/get-partial-data.js +9 -0
package/lib/props/merge-prop.js +7 -4
package/lib/props/merge-targets.js +114 -0
package/lib/props/mergeable-prop.js +87 -0
package/lib/props/once-prop.js +9 -1
package/lib/props/optional-prop.js +12 -4
package/lib/props/pick-props-to-resolve.js +14 -1
package/lib/props/resolve-deferred-props.js +17 -1
package/lib/props/resolve-except-props.js +11 -0
package/lib/props/resolve-merge-props.js +81 -20
package/lib/props/resolve-once-props.js +17 -7
package/lib/props/resolve-only-props.js +10 -3
package/lib/props/resolve-page-props.js +72 -13
package/lib/props/resolve-scroll-props.js +17 -3
package/lib/props/scroll-prop.js +30 -8
package/lib/render.js +68 -9
package/lib/responses/server-error.js +23 -6
package/lib/types.js +68 -0
package/package.json +3 -2
package/test.js +53 -12
package/tests/helpers/build-page-object.test.js +183 -0
package/tests/helpers/preserve-fragment.test.js +97 -0
package/tests/props/merge-targets.test.js +74 -0
package/tests/props/resolve-merge-props.test.js +151 -0
package/tests/props/resolve-page-props.test.js +70 -0
package/tests/props/resolve-scroll-props.test.js +51 -0
package/tests/render.test.js +197 -0

package/README.md CHANGED Viewed

@@ -38,7 +38,10 @@ module.exports.inertia = {
   <%- shipwright.styles() %>
 </head>
 <body>
-  <div id="app" data-page="<%- JSON.stringify(page) %>"></div>
+  <div id="app"></div>
+  <script type="application/json" data-page="app">
+    <%- JSON.stringify(page).replace(/</g, '\\u003c') %>
+  </script>
   <%- shipwright.scripts() %>
 </body>
 </html>
@@ -87,6 +90,19 @@ Return a URL string to redirect:
 return '/dashboard'
 ```
+#### Preserving URL fragments
+When a standard Inertia redirect should carry the current hash to the next
+page, mark the redirect before returning the URL:
+```js
+sails.inertia.preserveFragment()
+return '/articles/new-slug'
+```
+If the user started from `/articles/old-slug#comments`, the Inertia client can
+carry `#comments` to the redirected page.
 ### Sharing Data
 #### `share(key, value)`
@@ -191,6 +207,25 @@ return {
 }
 ```
+Deferred props can also be rescued when a non-critical callback fails:
+```js
+return {
+  page: 'dashboard',
+  props: {
+    analytics: sails.inertia
+      .defer(async () => {
+        return await Analytics.getExpensiveReport()
+      })
+      .rescue()
+  }
+}
+```
+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.
 ### Merge Props
 Merge with existing client-side data (useful for infinite scroll):
@@ -199,13 +234,29 @@ Merge with existing client-side data (useful for infinite scroll):
 // Shallow merge
 messages: sails.inertia.merge(() => newMessages)
+// Prepend new items instead of appending
+notifications: sails.inertia.merge(() => newNotifications).prepend()
+// Merge a nested array inside a paginated object
+users: sails.inertia.merge(() => paginatedUsers).append('data')
+// Match existing items by ID when merging
+users: sails.inertia
+  .merge(() => paginatedUsers)
+  .append('data', {
+    matchOn: 'id'
+  })
 // Deep merge (nested objects)
 settings: sails.inertia.deepMerge(() => updatedSettings)
+// Deep merge with item matching
+chat: sails.inertia.deepMerge(() => chatState).matchOn('messages.id')
 ```
 ### Infinite Scroll
-Paginate data with automatic merge behavior. Works with Inertia.js v2's `<InfiniteScroll>` component:
+Paginate data with automatic merge behavior. Works with Inertia's `<InfiniteScroll>` component:
 ```js
 // Controller
@@ -244,6 +295,8 @@ defineProps({ invoices: Object })
 </template>
 ```
+`scroll()` targets the wrapped array for merging, such as `invoices.data`, and follows Inertia's infinite-scroll merge intent header so previous-page requests prepend while next-page requests append.
 ### History Encryption
 Encrypt sensitive data in browser history:

package/index.js CHANGED Viewed

@@ -9,32 +9,31 @@
  */
 /**
- * @typedef {import('express').Request} Request
- * @typedef {import('express').Response} Response
- */
-/**
- * @typedef {Object} InertiaConfig
- * @property {string} [rootView='app'] - The root view template to use
- * @property {string|number|Function} [version=1] - Asset version for cache busting
- * @property {Object} [history] - History encryption settings
- * @property {boolean} [history.encrypt=false] - Whether to encrypt history state
- */
-/**
- * @typedef {Object} InertiaPageProps
- * @property {Object.<string, *>} [props] - Page props to pass to the component
- */
-/**
+ * @typedef {import('./lib/types').InertiaRequest} Request
+ * @typedef {import('./lib/types').InertiaResponse} Response
+ * @typedef {import('./lib/types').InertiaProps} InertiaProps
+ * @typedef {import('./lib/types').SailsLike} SailsLike
+ * @typedef {import('./lib/types').PropCallback} PropCallback
+ * @typedef {import('./lib/types').BadRequestData} BadRequestData
+ * @typedef {(req: Request, res: Response, next: () => any) => any} Middleware
+ * @typedef {Record<string, any>} InertiaHook
+ * @typedef {{ message?: string, stack?: string, name?: string }} ErrorLike
+ *
  * @typedef {Object} InertiaRenderData
  * @property {string} page - The component name to render
- * @property {Object.<string, *>} [props] - Props to pass to the component
- * @property {Object.<string, *>} [locals] - Additional locals for the root EJS template
- */
-/**
- * @typedef {<T>() => T | Promise<T>} PropCallback
+ * @property {InertiaProps} [props] - Props to pass to the component
+ * @property {InertiaProps} [locals] - Additional locals for the root EJS template
+ *
+ * @typedef {Object} DeferOptions
+ * @property {boolean} [rescue=false] - Rescue callback failures
+ *
+ * @typedef {Object} ScrollOptions
+ * @property {number} [page=0] - Current page index (0-based)
+ * @property {number} [perPage=10] - Items per page
+ * @property {number} [total=0] - Total number of items
+ * @property {string} [pageName='page'] - Query parameter name for pagination
+ * @property {string} [wrapper='data'] - Key to wrap the data in
+ * @property {string|null} [matchOn] - Optional field used to match items when merging
  */
 const inertia = require('./lib/middleware/inertia-middleware')
@@ -51,7 +50,12 @@ const ScrollProp = require('./lib/props/scroll-prop')
 const handleBadRequest = require('./lib/handle-bad-request')
 const handleServerError = require('./lib/responses/server-error')
+/**
+ * @param {SailsLike} sails
+ * @returns {InertiaHook}
+ */
 module.exports = function defineInertiaHook(sails) {
+  /** @type {InertiaHook} */
   let hook
   const routesToBindInertiaTo = [
     'GET r|^((?![^?]*\\/[^?\\/]+\\.[^?\\/]+(\\?.*)?).)*$|',
@@ -66,6 +70,12 @@ module.exports = function defineInertiaHook(sails) {
   // Using startup timestamp ensures fresh assets on each server restart
   const startupVersion = Date.now().toString(36)
+  /** @type {Middleware} */
+  const runWithRequestContext = (req, res, next) => {
+    if (requestContext.getContext()) return next()
+    requestContext.run(req, res, next)
+  }
   /**
    * Get asset version from Shipwright manifest.
    * Automatically hashes the manifest content for cache busting.
@@ -128,16 +138,29 @@ module.exports = function defineInertiaHook(sails) {
       // the request is already wrapped in AsyncLocalStorage context.
       if (sails.config.http && sails.config.http.middleware) {
         const mw = sails.config.http.middleware
-        if (mw.order && mw.order.indexOf('inertiaContext') === -1) {
+        // When order is not explicitly configured, Sails uses a default order
+        // internally. We need to set it here so we can inject inertiaContext
+        // before the router middleware.
+        if (!mw.order) {
+          mw.order = [
+            'cookieParser',
+            'session',
+            'bodyParser',
+            'compress',
+            'poweredBy',
+            'router',
+            'www',
+            'favicon'
+          ]
+        }
+        if (mw.order.indexOf('inertiaContext') === -1) {
           const routerIdx = mw.order.indexOf('router')
           if (routerIdx !== -1) {
             mw.order.splice(routerIdx, 0, 'inertiaContext')
           }
         }
         if (!mw.inertiaContext) {
-          mw.inertiaContext = function inertiaContext(req, res, next) {
-            requestContext.run(req, res, next)
-          }
+          mw.inertiaContext = runWithRequestContext
         }
       }
     },
@@ -167,28 +190,12 @@ module.exports = function defineInertiaHook(sails) {
       before: {
         'GET /*': {
           skipAssets: true,
-          fn: (req, res, next) => {
-            // Skip if context already set up by HTTP middleware
-            if (requestContext.getContext()) return next()
-            requestContext.run(req, res, next)
-          }
-        },
-        'POST /*': (req, res, next) => {
-          if (requestContext.getContext()) return next()
-          requestContext.run(req, res, next)
+          fn: runWithRequestContext
         },
-        'PUT /*': (req, res, next) => {
-          if (requestContext.getContext()) return next()
-          requestContext.run(req, res, next)
-        },
-        'PATCH /*': (req, res, next) => {
-          if (requestContext.getContext()) return next()
-          requestContext.run(req, res, next)
-        },
-        'DELETE /*': (req, res, next) => {
-          if (requestContext.getContext()) return next()
-          requestContext.run(req, res, next)
-        }
+        'POST /*': runWithRequestContext,
+        'PUT /*': runWithRequestContext,
+        'PATCH /*': runWithRequestContext,
+        'DELETE /*': runWithRequestContext
       }
     },
@@ -310,7 +317,7 @@ module.exports = function defineInertiaHook(sails) {
      * Create an optional prop
      * This allows you to define properties that are only evaluated when accessed.
      * @docs https://docs.sailscasts.com/boring-stack/partial-reloads#lazy-data-evaluation
-     * @param {Function} callback - The callback function to execute
+     * @param {PropCallback} callback - The callback function to execute
      * @returns {OptionalProp} - The optional prop
      */
     optional(callback) {
@@ -321,7 +328,7 @@ module.exports = function defineInertiaHook(sails) {
      * Create a mergeable prop
      * This allows you to merge multiple props together.
      * @docs https://docs.sailscasts.com/boring-stack/merging-props
-     * @param {Function} callback - The callback function to execute
+     * @param {PropCallback} callback - The callback function to execute
      * @returns {MergeProp} - The mergeable prop
      */
     merge(callback) {
@@ -332,7 +339,7 @@ module.exports = function defineInertiaHook(sails) {
      * Create an always prop
      * Always props are resolved on every request, whether partial or not.
      * @docs https://docs.sailscasts.com/boring-stack/partial-reloads#lazy-data-evaluation
-     * @param {Function} callback - The callback function
+     * @param {PropCallback} callback - The callback function
      * @returns {AlwaysProp} - The always prop
      */
     always(callback) {
@@ -342,12 +349,13 @@ module.exports = function defineInertiaHook(sails) {
      * Create a deferred prop
      * This allows you to load certain page data after the initial render.
      * @docs https://docs.sailscasts.com/boring-stack/deferred-props
-     * @param {Function} cb - The callback function to execute
-     * @param {string} group - The group name
+     * @param {PropCallback} cb - The callback function to execute
+     * @param {string|DeferOptions} group - The group name, or options when no group is needed
+     * @param {DeferOptions} options - Deferred prop options
      * @returns {DeferProp} - The deferred prop
      */
-    defer(cb, group = 'default') {
-      return new DeferProp(cb, group)
+    defer(cb, group = 'default', options = {}) {
+      return new DeferProp(cb, group, options)
     },
     /**
@@ -356,7 +364,7 @@ module.exports = function defineInertiaHook(sails) {
      * The client tracks which props it has via X-Inertia-Except-Once-Props header.
      * Useful for expensive computations that don't change often.
      * @docs https://docs.sailscasts.com/boring-stack/once-props
-     * @param {Function} callback - The callback function to execute
+     * @param {PropCallback} callback - The callback function to execute
      * @returns {OnceProp} - The once prop
      * @example
      * // Basic usage
@@ -379,7 +387,7 @@ module.exports = function defineInertiaHook(sails) {
      * Combines share() and once() - the prop is shared and only resolved once.
      * @docs https://docs.sailscasts.com/boring-stack/once-props#share-once
      * @param {string} key - The key of the property
-     * @param {Function} callback - The callback function to execute
+     * @param {PropCallback} callback - The callback function to execute
      * @returns {OnceProp} - The once prop (for chaining)
      * @example
      * // In a policy or middleware
@@ -430,7 +438,7 @@ module.exports = function defineInertiaHook(sails) {
      * This prevents "phantom" toasts/notifications when users navigate back.
      * Flash data is stored in the session so it persists across redirects.
      * @docs https://docs.sailscasts.com/boring-stack/flash
-     * @param {string|Object} key - The key or an object of key-value pairs
+     * @param {string|Record<string, any>} key - The key or an object of key-value pairs
      * @param {*} [value] - The value (if key is a string)
      * @returns {Object} - The hook instance for chaining
      * @example
@@ -454,7 +462,8 @@ module.exports = function defineInertiaHook(sails) {
       if (typeof key === 'object' && key !== null) {
         req.session._inertiaFlash = { ...req.session._inertiaFlash, ...key }
       } else {
-        req.session._inertiaFlash[key] = value
+        const flashKey = /** @type {string} */ (key)
+        req.session._inertiaFlash[flashKey] = value
       }
       return this
     },
@@ -471,8 +480,8 @@ module.exports = function defineInertiaHook(sails) {
     /**
      * Consume and clear flash data from the session.
      * Called internally by build-page-object after adding to response.
-     * @param {Object} req - The request object
-     * @returns {Object} - The flash data that was consumed
+     * @param {Request} req - The request object
+     * @returns {InertiaProps} - The flash data that was consumed
      */
     consumeFlash(req) {
       const flash = req?.session?._inertiaFlash || {}
@@ -486,7 +495,7 @@ module.exports = function defineInertiaHook(sails) {
      * Create a deep merge prop
      * Like merge(), but recursively merges nested objects instead of replacing them.
      * @docs https://docs.sailscasts.com/boring-stack/merging-props#deep-merge
-     * @param {Function} callback - The callback function to execute
+     * @param {PropCallback} callback - The callback function to execute
      * @returns {MergeProp} - The mergeable prop with deep merge enabled
      * @example
      * // Deep merge nested user preferences
@@ -500,9 +509,9 @@ module.exports = function defineInertiaHook(sails) {
     /**
      * Render the response
-     * @param {Object} req - The request object
-     * @param {Object} res - The response object
-     * @param {Object} data - The data to render
+     * @param {Request} req - The request object
+     * @param {Response} res - The response object
+     * @param {InertiaRenderData} data - The data to render
      * @returns {*} - The rendered response
      */
     render(req, res, data) {
@@ -512,8 +521,8 @@ module.exports = function defineInertiaHook(sails) {
      * Handle Inertia redirects (external URLs or non-Inertia pages)
      * Forces a full page visit instead of an Inertia XHR request.
      * See https://docs.sailscasts.com/boring-stack/redirects
-     * @param {Object} req - The request object
-     * @param {Object} res - The response object
+     * @param {Request} req - The request object
+     * @param {Response} res - The response object
      * @param {string} url - The URL to redirect to
      * @returns {Object} - The response object with the redirect
      */
@@ -570,12 +579,60 @@ module.exports = function defineInertiaHook(sails) {
       return requestContext.getClearHistory()
     },
+    /**
+     * Preserve the current URL fragment across a standard Inertia redirect.
+     * The flag is stored in the session so it survives the redirect request,
+     * then it is consumed by the next Inertia page response.
+     *
+     * @docs https://docs.sailscasts.com/boring-stack/redirects#preserving-fragments
+     * @param {boolean} preserve - Whether to preserve the URL fragment
+     * @returns {Object} - The hook instance for chaining
+     * @example
+     * sails.inertia.preserveFragment()
+     * return '/article/new-slug'
+     */
+    preserveFragment(preserve = true) {
+      const context = requestContext.getContext()
+      const req = requestContext.getRequest()
+      if (context) {
+        requestContext.setPreserveFragment(preserve)
+      }
+      if (req?.session) {
+        if (preserve) {
+          req.session._inertiaPreserveFragment = true
+        } else {
+          delete req.session._inertiaPreserveFragment
+        }
+      }
+      return this
+    },
+    /**
+     * Consume the preserve fragment flag for the current request.
+     * @param {Request} req - The request object
+     * @returns {boolean} - Whether to preserve the URL fragment
+     */
+    consumePreserveFragment(req) {
+      const preserve =
+        requestContext.getPreserveFragment() ||
+        Boolean(req?.session?._inertiaPreserveFragment)
+      if (req?.session) {
+        delete req.session._inertiaPreserveFragment
+      }
+      return preserve
+    },
     /**
      * Handle bad request responses for Inertia.js
      * For Inertia requests with validation errors, redirects back with errors in session.
-     * @param {Object} req - The request object
-     * @param {Object} res - The response object
-     * @param {Object|Error} [optionalData] - Optional error data or Error object
+     * @param {Request} req - The request object
+     * @param {Response} res - The response object
+     * @param {BadRequestData|Error|Record<string, any>} [optionalData] - Optional error data or Error object
      * @returns {*} - Response (redirect for Inertia, status code for non-Inertia)
      */
     handleBadRequest(req, res, optionalData) {
@@ -587,9 +644,9 @@ module.exports = function defineInertiaHook(sails) {
      * For Inertia requests in development, displays a styled error modal with stack trace.
      * In production, redirects back with a flash error message.
      * @docs https://docs.sailscasts.com/boring-stack/error-handling
-     * @param {Object} req - The request object
-     * @param {Object} res - The response object
-     * @param {Object|Error} [error] - Optional error data or Error object
+     * @param {Request} req - The request object
+     * @param {Response} res - The response object
+     * @param {ErrorLike} [error] - Optional error data or Error object
      * @returns {*} - Response (HTML modal for dev Inertia, redirect for prod)
      */
     handleServerError(req, res, error) {
@@ -605,13 +662,8 @@ module.exports = function defineInertiaHook(sails) {
      * to 1-based for the Inertia client.
      *
      * @docs https://docs.sailscasts.com/boring-stack/infinite-scroll
-     * @param {Function} callback - Callback returning the paginated data array
-     * @param {Object} [options] - Pagination options
-     * @param {number} [options.page=0] - Current page index (0-based)
-     * @param {number} [options.perPage=10] - Items per page
-     * @param {number} [options.total=0] - Total number of items
-     * @param {string} [options.pageName='page'] - Query parameter name for pagination
-     * @param {string} [options.wrapper='data'] - Key to wrap the data in
+     * @param {PropCallback} callback - Callback returning the paginated data array
+     * @param {ScrollOptions} [options] - Pagination options
      * @returns {ScrollProp} - The scroll prop
      * @example
      * // Basic usage

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

@@ -1,3 +1,9 @@
+/**
+ * @typedef {import('./types').InertiaRequest} InertiaRequest
+ * @typedef {import('./types').InertiaResponse} InertiaResponse
+ * @typedef {import('./types').BadRequestData} BadRequestData
+ */
 /**
  * Handle bad request responses for Inertia.js
  *
@@ -5,9 +11,9 @@
  * previous page with errors stored in the session. For non-Inertia requests,
  * it returns a standard 400 response.
  *
- * @param {Object} req - Express/Sails request object
- * @param {Object} res - Express/Sails response object
- * @param {Object|Error} [optionalData] - Optional error data or Error object
+ * @param {InertiaRequest} req - Express/Sails request object
+ * @param {InertiaResponse} res - Express/Sails response object
+ * @param {BadRequestData|Error|Record<string, any>} [optionalData] - Optional error data or Error object
  * @returns {*} - Response (redirect for Inertia, status code for non-Inertia)
  *
  * @example
@@ -22,13 +28,21 @@ module.exports = function handleBadRequest(req, res, optionalData) {
   const statusCodeToSet = 400
   // Check if it's an Inertia request
-  if (req.header('X-Inertia')) {
-    if (optionalData && optionalData.problems) {
+  if (req.header?.('X-Inertia')) {
+    if (
+      optionalData &&
+      !(optionalData instanceof Error) &&
+      Array.isArray(optionalData.problems)
+    ) {
+      /** @type {Record<string, string[]>} */
       const errors = {}
       optionalData.problems.forEach((problem) => {
         if (typeof problem === 'object') {
           Object.keys(problem).forEach((propertyName) => {
-            const sanitizedProblem = problem[propertyName].replace(/\.$/, '') // Trim trailing dot
+            const sanitizedProblem = String(problem[propertyName]).replace(
+              /\.$/,
+              ''
+            ) // Trim trailing dot
             if (!errors[propertyName]) {
               errors[propertyName] = [sanitizedProblem]
             } else {