inertia-sails 1.3.2 → 1.4.0

package/lib/helpers/build-page-object.js

@@ -4,23 +4,103 @@ const resolveMergeProps = require('../props/resolve-merge-props')
 const { resolveOncePropsMetadata } = require('../props/resolve-once-props')
 const resolvePageProps = require('../props/resolve-page-props')
 const resolveScrollProps = require('../props/resolve-scroll-props')
+const resolveAssetVersion = require('./resolve-asset-version')
+
+/**
+ * @typedef {Object} InertiaHookApi
+ * @property {() => Object.<string, *>} getShared
+ * @property {() => boolean} shouldClearHistory
+ * @property {() => boolean} shouldEncryptHistory
+ * @property {(req: BuildPageObjectRequest) => boolean} consumePreserveFragment
+ * @property {(req: BuildPageObjectRequest) => Object.<string, *>} consumeFlash
+ */
+
+/**
+ * @typedef {Object} SailsLike
+ * @property {Object.<string, *>} config
+ * @property {InertiaHookApi} inertia
+ */
+
+/**
+ * @typedef {Object} BuildPageObjectRequest
+ * @property {string} [url]
+ * @property {string} [originalUrl]
+ * @property {SailsLike} _sails
+ * @property {(header: string) => string|undefined} get
+ */
 
 /**
  * @typedef {Object} InertiaPageObject
  * @property {string} component - The component name to render
  * @property {string} url - The current URL
- * @property {string|number} version - Asset version for cache busting
+ * @property {string|number|null} version - Asset version for cache busting
  * @property {Object.<string, *>} props - Resolved page props
- * @property {boolean} clearHistory - Whether to clear browser history
- * @property {boolean} encryptHistory - Whether to encrypt history state
+ * @property {boolean} [clearHistory] - Whether to clear browser history
+ * @property {boolean} [encryptHistory] - Whether to encrypt history state
+ * @property {boolean} [preserveFragment] - Whether to preserve URL fragments across redirects
+ * @property {string[]} [sharedProps] - Shared prop keys included in this response
  * @property {string[]} [mergeProps] - Props that should be merged on client
+ * @property {string[]} [prependProps] - Props that should be prepended on client
  * @property {string[]} [deepMergeProps] - Props that should be deep merged
+ * @property {string[]} [matchPropsOn] - Prop paths to use for matching merge items
  * @property {Object.<string, string[]>} [deferredProps] - Deferred props by group
+ * @property {string[]} [rescuedProps] - Deferred props rescued after callback failures
  * @property {Object.<string, *>} [onceProps] - Once-prop metadata
  * @property {Object.<string, *>} [scrollProps] - Scroll props for InfiniteScroll component
  * @property {Object.<string, *>} [flash] - Flash data (not persisted in history)
  */
 
+/**
+ * @typedef {'mergeProps'|'prependProps'|'deepMergeProps'|'matchPropsOn'} PathMetadataKey
+ */
+
+/**
+ * @param {InertiaPageObject} page
+ * @param {PathMetadataKey} key
+ */
+function removeEmptyArrayMetadata(page, key) {
+  if (Array.isArray(page[key]) && page[key].length === 0) {
+    delete page[key]
+  }
+}
+
+/**
+ * @param {InertiaPageObject} page
+ * @param {string[]} rescuedProps
+ */
+function removeRescuedPropMetadata(page, rescuedProps) {
+  if (rescuedProps.length === 0) return
+
+  const rescuedRootProps = new Set(rescuedProps)
+  /** @param {string} path */
+  const isNotRescuedPath = (path) => !rescuedRootProps.has(path.split('.')[0])
+  /** @type {PathMetadataKey[]} */
+  const pathMetadataKeys = [
+    'mergeProps',
+    'prependProps',
+    'deepMergeProps',
+    'matchPropsOn'
+  ]
+
+  pathMetadataKeys.forEach((key) => {
+    if (Array.isArray(page[key])) {
+      page[key] = page[key].filter(isNotRescuedPath)
+      removeEmptyArrayMetadata(page, key)
+    }
+  })
+
+  const scrollProps = page.scrollProps
+  if (scrollProps) {
+    rescuedProps.forEach((key) => {
+      delete scrollProps[key]
+    })
+
+    if (Object.keys(scrollProps).length === 0) {
+      delete page.scrollProps
+    }
+  }
+}
+
 /**
  * Build the Inertia page object for a response.
  *
@@ -30,42 +110,67 @@ const resolveScrollProps = require('../props/resolve-scroll-props')
  * Uses request-scoped shared props (via AsyncLocalStorage) merged with
  * global shared props to prevent data leaking between concurrent requests.
  *
- * @param {Object} req - Express/Sails request object
+ * @param {BuildPageObjectRequest} req - Express/Sails request object
  * @param {string} component - The component name to render
  * @param {Object.<string, *>} pageProps - Props specific to this page
  * @returns {Promise<InertiaPageObject>} - The complete page object
  */
 module.exports = async function buildPageObject(req, component, pageProps) {
   const sails = req._sails
-  let url = req.url || req.originalUrl
-  const assetVersion = sails.config.inertia.version
-  const currentVersion =
-    typeof assetVersion === 'function' ? assetVersion() : assetVersion
+  let url = req.url || req.originalUrl || '/'
+  const currentVersion = resolveAssetVersion(sails)
+
+  const sharedProps = sails.inertia.getShared()
+  const sharedPropKeys = Object.keys(sharedProps)
 
   // Merge props: global shared → request-scoped shared → page-specific
   // This ensures user-specific data (from share()) doesn't leak between requests
   const allProps = {
-    ...sails.inertia.getShared(), // Merges global + request-scoped
+    ...sharedProps, // Merges global + request-scoped
     ...pageProps
   }
 
   const propsToResolve = pickPropsToResolve(req, component, allProps)
+  const clearHistory = sails.inertia.shouldClearHistory()
+  const encryptHistory = sails.inertia.shouldEncryptHistory()
+  const preserveFragment = sails.inertia.consumePreserveFragment(req)
+  const resolvedPageProps = await resolvePageProps.withMetadata(propsToResolve)
 
   // Build the page object with all metadata
   // Use request-scoped history settings (prevents race conditions)
+  /** @type {InertiaPageObject} */
   const page = {
     component,
     url,
     version: currentVersion,
-    props: await resolvePageProps(propsToResolve),
-    clearHistory: sails.inertia.shouldClearHistory(),
-    encryptHistory: sails.inertia.shouldEncryptHistory(),
+    props: resolvedPageProps.props,
     ...resolveMergeProps(req, allProps),
     ...resolveDeferredProps(req, component, allProps),
     ...resolveOncePropsMetadata(allProps),
     ...resolveScrollProps(allProps)
   }
 
+  if (clearHistory) {
+    page.clearHistory = true
+  }
+
+  if (encryptHistory) {
+    page.encryptHistory = true
+  }
+
+  if (preserveFragment) {
+    page.preserveFragment = true
+  }
+
+  if (resolvedPageProps.rescuedProps.length > 0) {
+    page.rescuedProps = resolvedPageProps.rescuedProps
+    removeRescuedPropMetadata(page, resolvedPageProps.rescuedProps)
+  }
+
+  if (sharedPropKeys.length > 0) {
+    page.sharedProps = sharedPropKeys
+  }
+
   // Consume flash data from session and add to props
   // Flash data is included in props.flash so it's accessible via usePage().props.flash
   // Note: Unlike regular props, flash data should NOT be persisted in browser history

package/lib/helpers/inertia-headers.js

@@ -23,6 +23,8 @@ const PARTIAL_COMPONENT = 'X-Inertia-Partial-Component'
 const LOCATION = 'X-Inertia-Location'
 /** @type {string} - Comma-separated list of once-props client already has */
 const EXCEPT_ONCE_PROPS = 'X-Inertia-Except-Once-Props'
+/** @type {string} - InfiniteScroll merge direction */
+const INFINITE_SCROLL_MERGE_INTENT = 'X-Inertia-Infinite-Scroll-Merge-Intent'
 
 module.exports = {
   INERTIA,
@@ -33,5 +35,6 @@ module.exports = {
   RESET,
   PARTIAL_COMPONENT,
   LOCATION,
-  EXCEPT_ONCE_PROPS
+  EXCEPT_ONCE_PROPS,
+  INFINITE_SCROLL_MERGE_INTENT
 }

package/lib/helpers/is-inertia-partial-request.js

@@ -1,4 +1,14 @@
 const { PARTIAL_COMPONENT } = require('./inertia-headers')
+
+/**
+ * @typedef {import('../types').InertiaRequest} InertiaRequest
+ */
+
+/**
+ * @param {InertiaRequest} req
+ * @param {string} component
+ * @returns {boolean}
+ */
 module.exports = function isInertiaPartialRequest(req, component) {
   return req.get(PARTIAL_COMPONENT) === component
 }

package/lib/helpers/is-inertia-request.js

@@ -1,4 +1,13 @@
 const { INERTIA } = require('./inertia-headers')
+
+/**
+ * @typedef {import('../types').InertiaRequest} InertiaRequest
+ */
+
+/**
+ * @param {InertiaRequest} req
+ * @returns {any}
+ */
 module.exports = function isInertiaRequest(req) {
   return req.get(INERTIA)
 }

package/lib/helpers/request-context.js

@@ -14,12 +14,31 @@
  *   sharedLocals: {},     // Request-scoped locals for root EJS template
  *   encryptHistory: null, // Request-scoped history encryption (null = use default)
  *   clearHistory: false,  // Request-scoped clear history flag
+ *   preserveFragment: false, // Request-scoped fragment preservation flag
  *   refreshOnceProps: [], // Props to force-refresh for this request
  *   rootView: null        // Request-scoped root view template (null = use default)
  * }
  */
 const { AsyncLocalStorage } = require('async_hooks')
 
+/**
+ * @typedef {import('../types').InertiaRequest} InertiaRequest
+ * @typedef {import('../types').InertiaResponse} InertiaResponse
+ * @typedef {import('../types').InertiaProps} InertiaProps
+ *
+ * @typedef {Object} RequestContext
+ * @property {InertiaRequest} req
+ * @property {InertiaResponse} res
+ * @property {InertiaProps} sharedProps
+ * @property {InertiaProps} sharedLocals
+ * @property {boolean|null} encryptHistory
+ * @property {boolean} clearHistory
+ * @property {boolean} preserveFragment
+ * @property {string[]} refreshOnceProps
+ * @property {string|null} rootView
+ */
+
+/** @type {AsyncLocalStorage<RequestContext>} */
 const requestContext = new AsyncLocalStorage()
 
 module.exports = {
@@ -30,12 +49,13 @@ module.exports = {
 
   /**
    * Run a callback with request context stored
-   * @param {Object} req - The request object
-   * @param {Object} res - The response object
-   * @param {Function} callback - The callback to run
+   * @param {InertiaRequest} req - The request object
+   * @param {InertiaResponse} res - The response object
+   * @param {() => any} callback - The callback to run
    * @returns {*} - The result of the callback
    */
   run(req, res, callback) {
+    /** @type {RequestContext} */
     const context = {
       req,
       res,
@@ -43,6 +63,7 @@ module.exports = {
       sharedLocals: {},
       encryptHistory: null,
       clearHistory: false,
+      preserveFragment: false,
       refreshOnceProps: [], // Props to force-refresh for this request
       rootView: null // Request-scoped root view template
     }
@@ -51,7 +72,7 @@ module.exports = {
 
   /**
    * Get the full context object
-   * @returns {Object|undefined} - The current context or undefined if not in context
+   * @returns {RequestContext|undefined} - The current context or undefined if not in context
    */
   getContext() {
     return requestContext.getStore()
@@ -59,7 +80,7 @@ module.exports = {
 
   /**
    * Get the current request from context
-   * @returns {Object|undefined} - The current request or undefined if not in context
+   * @returns {InertiaRequest|undefined} - The current request or undefined if not in context
    */
   getRequest() {
     const context = requestContext.getStore()
@@ -68,7 +89,7 @@ module.exports = {
 
   /**
    * Get the current response from context
-   * @returns {Object|undefined} - The current response or undefined if not in context
+   * @returns {InertiaResponse|undefined} - The current response or undefined if not in context
    */
   getResponse() {
     const context = requestContext.getStore()
@@ -77,7 +98,7 @@ module.exports = {
 
   /**
    * Get request-scoped shared props
-   * @returns {Object} - The shared props for this request
+   * @returns {InertiaProps} - The shared props for this request
    */
   getSharedProps() {
     const context = requestContext.getStore()
@@ -98,7 +119,7 @@ module.exports = {
 
   /**
    * Get request-scoped shared locals
-   * @returns {Object} - The shared locals for this request
+   * @returns {InertiaProps} - The shared locals for this request
    */
   getSharedLocals() {
     const context = requestContext.getStore()
@@ -157,6 +178,26 @@ module.exports = {
     }
   },
 
+  /**
+   * Get request-scoped preserve fragment flag
+   * @returns {boolean} - Whether to preserve the URL fragment
+   */
+  getPreserveFragment() {
+    const context = requestContext.getStore()
+    return context?.preserveFragment || false
+  },
+
+  /**
+   * Set request-scoped preserve fragment flag
+   * @param {boolean} preserve - Whether to preserve the URL fragment
+   */
+  setPreserveFragment(preserve) {
+    const context = requestContext.getStore()
+    if (context) {
+      context.preserveFragment = preserve
+    }
+  },
+
   /**
    * Get the list of once props to force-refresh
    * @returns {string[]} - Array of prop keys to refresh

package/lib/helpers/resolve-asset-version.js

@@ -0,0 +1,12 @@
+/**
+ * @typedef {import('../types').SailsLike} SailsLike
+ */
+
+/**
+ * @param {SailsLike} sails
+ * @returns {any}
+ */
+module.exports = function resolveAssetVersion(sails) {
+  const assetVersion = sails.config.inertia.version
+  return typeof assetVersion === 'function' ? assetVersion() : assetVersion
+}

package/lib/helpers/resolve-validation-errors.js

@@ -1,29 +1,36 @@
-// @ts-nocheck
 const { ERROR_BAG } = require('./inertia-headers')
 
+/**
+ * @typedef {import('../types').InertiaRequest} InertiaRequest
+ * @typedef {Record<string, string|string[]>} ValidationErrors
+ */
+
 /**
  * @module resolveValidationErrors
  * @description Resolves and formats validation errors from the session for Inertia responses.
  *
- * @param {Object} req - The current HTTP request object.
- * @returns {Object} An object representing the validation errors in the desired format.
+ * @param {InertiaRequest} req - The current HTTP request object.
+ * @returns {ValidationErrors} An object representing the validation errors in the desired format.
  */
 module.exports = function resolveValidationErrors(req) {
   if (!req.session || !req.session.errors) {
     return {}
   }
 
-  const flashedErrors = req.session.errors
+  const flashedErrors = /** @type {Record<string, string[]>} */ (
+    req.session.errors
+  )
 
   const collectedErrors = Object.keys(flashedErrors).reduce((result, bag) => {
     const errorsForBag = flashedErrors[bag]
+    /** @type {string[]} */
     const mappedErrors = errorsForBag.map((error) =>
       error.replace(/"([^"]+)"/, '$1')
     )
     // Ensure that single errors are wrapped in an array
     result[bag] = mappedErrors.length > 1 ? mappedErrors : mappedErrors[0]
     return result
-  }, {})
+  }, /** @type {ValidationErrors} */ ({}))
 
   const inertiaErrorBag = req.headers[ERROR_BAG]
 

package/lib/location.js

@@ -1,5 +1,16 @@
 const { INERTIA, LOCATION } = require('./helpers/inertia-headers')
 
+/**
+ * @typedef {import('./types').InertiaRequest} InertiaRequest
+ * @typedef {import('./types').InertiaResponse} InertiaResponse
+ */
+
+/**
+ * @param {InertiaRequest} req
+ * @param {InertiaResponse} res
+ * @param {string} url
+ * @returns {any}
+ */
 module.exports = function (req, res, url) {
   if (req.get(INERTIA)) {
     // If the method is PUT, PATCH, or DELETE, force a 303 redirect (so the next request is a GET)

package/lib/middleware/inertia-middleware.js

@@ -1,6 +1,11 @@
 const resolveValidationErrors = require('../helpers/resolve-validation-errors')
 const requestContext = require('../helpers/request-context')
 
+/**
+ * @typedef {import('../types').InertiaRequest} InertiaRequest
+ * @typedef {import('../types').InertiaResponse} InertiaResponse
+ */
+
 /**
  * Inertia middleware that handles validation errors.
  *
@@ -11,8 +16,8 @@ const requestContext = require('../helpers/request-context')
  * This middleware handles:
  * - Validation errors from redirects (shared as 'errors' prop)
  *
- * @param {Object} hook - The inertia-sails hook instance
- * @returns {Function} Express/Sails middleware function
+ * @param {Record<string, any>} hook - The inertia-sails hook instance
+ * @returns {(req: InertiaRequest, res: InertiaResponse, next: () => any) => any} Express/Sails middleware function
  */
 function inertia(hook) {
   return function inertiaMiddleware(req, res, next) {

package/lib/props/always-prop.js

@@ -1,5 +1,9 @@
 const MergeableProp = require('./mergeable-prop')
 
+/**
+ * @typedef {import('../types').PropCallback} PropCallback
+ */
+
 /**
  * AlwaysProp - A prop that is always resolved, even during partial reloads.
  *
@@ -22,11 +26,11 @@ const MergeableProp = require('./mergeable-prop')
 module.exports = class AlwaysProp extends MergeableProp {
   /**
    * Create a new AlwaysProp instance
-   * @param {Function} callback - The callback function to resolve the prop value
+   * @param {PropCallback} callback - The callback function to resolve the prop value
    */
   constructor(callback) {
     super()
-    /** @type {Function} */
+    /** @type {PropCallback} */
     this.callback = callback
   }
 }

package/lib/props/defer-prop.js

@@ -1,6 +1,13 @@
 const ignoreFirstLoadSymbol = require('../helpers/ignore-first-load-symbol')
 const MergeableProp = require('./mergeable-prop')
 
+/**
+ * @typedef {import('../types').PropCallback} PropCallback
+ *
+ * @typedef {Object} DeferPropOptions
+ * @property {boolean} [rescue=false] - Whether callback failures should be rescued
+ */
+
 /**
  * DeferProp - A prop that loads after the initial page render.
  *
@@ -30,17 +37,30 @@ const MergeableProp = require('./mergeable-prop')
 module.exports = class DeferProp extends MergeableProp {
   /**
    * Create a new DeferProp instance
-   * @param {Function} callback - The callback function to resolve the prop value
-   * @param {string} [group='default'] - The group name for loading props together
+   * @param {PropCallback} callback - The callback function to resolve the prop value
+   * @param {string|DeferPropOptions} [group='default'] - The group name for loading props together, or options
+   * @param {DeferPropOptions} [options] - Deferred prop options
    */
-  constructor(callback, group) {
+  constructor(callback, group = 'default', options = {}) {
     super()
-    /** @type {Function} */
+    if (typeof group === 'object' && group !== null) {
+      options = group
+      group = 'default'
+    }
+    const groupName = typeof group === 'string' ? group : 'default'
+
+    /** @type {PropCallback} */
     this.callback = callback
     /** @type {string} */
-    this.group = group
+    this.group = groupName
     /** @type {boolean} */
-    this[ignoreFirstLoadSymbol] = true
+    this.shouldRescue = options.rescue === true
+    Object.defineProperty(this, ignoreFirstLoadSymbol, {
+      value: true,
+      enumerable: true,
+      configurable: true,
+      writable: true
+    })
   }
 
   /**
@@ -50,4 +70,24 @@ module.exports = class DeferProp extends MergeableProp {
   getGroup() {
     return this.group
   }
+
+  /**
+   * Rescue callback failures instead of failing the whole deferred response.
+   * The failed prop is omitted from props and reported in rescuedProps.
+   *
+   * @param {boolean} rescue - Whether callback failures should be rescued
+   * @returns {DeferProp} - Returns this for chaining
+   */
+  rescue(rescue = true) {
+    this.shouldRescue = rescue
+    return this
+  }
+
+  /**
+   * Get whether this deferred prop should rescue callback failures.
+   * @returns {boolean} - Whether callback failures should be rescued
+   */
+  shouldRescueProp() {
+    return this.shouldRescue
+  }
 }

package/lib/props/get-partial-data.js

@@ -1,3 +1,12 @@
+/**
+ * @typedef {import('../types').InertiaProps} InertiaProps
+ */
+
+/**
+ * @param {InertiaProps} props
+ * @param {string[]} [only]
+ * @returns {InertiaProps}
+ */
 module.exports = function getPartialData(props, only = []) {
   return Object.assign({}, ...only.map((key) => ({ [key]: props[key] })))
 }

package/lib/props/merge-prop.js

@@ -1,5 +1,9 @@
 const MergeableProp = require('./mergeable-prop')
 
+/**
+ * @typedef {import('../types').PropCallback} PropCallback
+ */
+
 /**
  * MergeProp - A prop that merges with existing data during partial reloads.
  *
@@ -22,14 +26,13 @@ const MergeableProp = require('./mergeable-prop')
 module.exports = class MergeProp extends MergeableProp {
   /**
    * Create a new MergeProp instance
-   * @param {Function} callback - The callback function to resolve the prop value
+   * @param {PropCallback} callback - The callback function to resolve the prop value
    */
   constructor(callback) {
     super()
-    /** @type {Function} */
+    /** @type {PropCallback} */
     this.callback = callback
-    /** @type {boolean} */
-    this.shouldMerge = true
+    this.merge()
   }
 
   /**