inertia-sails 1.3.2 → 1.4.0

package/lib/props/merge-targets.js

@@ -0,0 +1,114 @@
+/**
+ * Utilities for describing how mergeable props should be merged by the client.
+ *
+ * @typedef {import('../types').MergeOperation} MergeOperation
+ * @typedef {import('../types').MergeOptions} MergeOptions
+ * @typedef {string|string[]|Record<string, string|null>|null} MergeTargetInput
+ */
+
+/**
+ * @returns {MergeOperation}
+ */
+function createDefaultMergeOperation() {
+  return {
+    direction: 'append',
+    path: null,
+    matchOn: null,
+    isDefault: true
+  }
+}
+
+/**
+ * @param {MergeOptions|string|null|undefined} options
+ * @returns {MergeOptions}
+ */
+function normalizeMergeOptions(options) {
+  return typeof options === 'string' ? { matchOn: options } : options || {}
+}
+
+/**
+ * @param {MergeTargetInput} paths
+ * @param {MergeOptions|string} [options]
+ * @returns {Array<{ path: string|null, matchOn: string|null }>}
+ */
+function normalizeMergeTargets(paths, options = {}) {
+  const normalizedOptions = normalizeMergeOptions(options)
+
+  if (paths === null || paths === undefined) {
+    return [
+      {
+        path: null,
+        matchOn:
+          typeof normalizedOptions.matchOn === 'string'
+            ? normalizedOptions.matchOn
+            : null
+      }
+    ]
+  }
+
+  if (Array.isArray(paths)) {
+    return paths.map((path) => ({
+      path: normalizePath(path),
+      matchOn: resolveTargetMatchOn(path, normalizedOptions)
+    }))
+  }
+
+  if (typeof paths === 'object') {
+    return Object.entries(paths).map(([path, matchOn]) => ({
+      path: normalizePath(path),
+      matchOn: matchOn || null
+    }))
+  }
+
+  return [
+    {
+      path: normalizePath(paths),
+      matchOn: resolveTargetMatchOn(paths, normalizedOptions)
+    }
+  ]
+}
+
+/**
+ * @param {string} path
+ * @returns {string|null}
+ */
+function normalizePath(path) {
+  return path === '' ? null : path
+}
+
+/**
+ * @param {string} path
+ * @param {MergeOptions} options
+ * @returns {string|null}
+ */
+function resolveTargetMatchOn(path, options) {
+  if (!options.matchOn) return null
+  if (typeof options.matchOn === 'object') return options.matchOn[path] || null
+  return options.matchOn
+}
+
+/**
+ * @param {string} key
+ * @param {string|null} path
+ * @returns {string}
+ */
+function resolvePropPath(key, path) {
+  return path ? `${key}.${path}` : key
+}
+
+/**
+ * @template T
+ * @param {T[]} values
+ * @returns {T[]}
+ */
+function unique(values) {
+  return [...new Set(values)]
+}
+
+module.exports = {
+  createDefaultMergeOperation,
+  normalizeMergeOptions,
+  normalizeMergeTargets,
+  resolvePropPath,
+  unique
+}

package/lib/props/mergeable-prop.js

@@ -1,3 +1,15 @@
+const {
+  createDefaultMergeOperation,
+  normalizeMergeOptions,
+  normalizeMergeTargets
+} = require('./merge-targets')
+
+/**
+ * @typedef {import('../types').MergeOperation} MergeOperation
+ * @typedef {import('../types').MergeOptions} MergeOptions
+ * @typedef {string|string[]|Record<string, string|null>|null} MergeTargetInput
+ */
+
 /**
  * MergeableProp - Base class for props that can be merged during partial reloads.
  *
@@ -12,6 +24,10 @@ module.exports = class MergeableProp {
     this.shouldMerge = false
     /** @type {boolean} - Whether to deep merge this prop */
     this.shouldDeepMerge = false
+    /** @type {MergeOperation[]} */
+    this.mergeOperations = []
+    /** @type {string[]} - Paths to use when matching merge items */
+    this.matchOnPaths = []
   }
 
   /**
@@ -21,9 +37,33 @@ module.exports = class MergeableProp {
    */
   merge() {
     this.shouldMerge = true
+    this.shouldDeepMerge = false
+    if (this.mergeOperations.length === 0) {
+      this.mergeOperations.push(createDefaultMergeOperation())
+    }
     return this
   }
 
+  /**
+   * Append this prop, or one or more nested paths, during partial reloads.
+   * @param {MergeTargetInput} [paths] - Path(s) to append, or a path-to-matchOn map
+   * @param {MergeOptions|string} [options] - Options, or a matchOn string
+   * @returns {MergeableProp} - Returns this for chaining
+   */
+  append(paths = null, options = {}) {
+    return this._addMergeOperations('append', paths, options)
+  }
+
+  /**
+   * Prepend this prop, or one or more nested paths, during partial reloads.
+   * @param {MergeTargetInput} [paths] - Path(s) to prepend, or a path-to-matchOn map
+   * @param {MergeOptions|string} [options] - Options, or a matchOn string
+   * @returns {MergeableProp} - Returns this for chaining
+   */
+  prepend(paths = null, options = {}) {
+    return this._addMergeOperations('prepend', paths, options)
+  }
+
   /**
    * Enable deep merging for this prop.
    * Recursively merges nested objects instead of replacing them.
@@ -32,6 +72,53 @@ module.exports = class MergeableProp {
   deepMerge() {
     this.shouldMerge = true
     this.shouldDeepMerge = true
+    this.mergeOperations = []
     return this
   }
+
+  /**
+   * Configure one or more match-on paths for merge operations.
+   * @param {string|string[]} paths - Path(s) ending with the field to match on
+   * @returns {MergeableProp} - Returns this for chaining
+   */
+  matchOn(paths) {
+    const normalizedPaths = Array.isArray(paths) ? paths : [paths]
+    normalizedPaths.filter(Boolean).forEach((path) => {
+      this.matchOnPaths.push(path)
+    })
+    return this
+  }
+
+  /**
+   * @param {'append'|'prepend'} direction
+   * @param {MergeTargetInput} paths
+   * @param {MergeOptions|string} options
+   * @returns {MergeableProp}
+   */
+  _addMergeOperations(direction, paths, options) {
+    const normalizedOptions = normalizeMergeOptions(options)
+
+    this.shouldMerge = true
+    this.shouldDeepMerge = false
+    this._clearDefaultMergeOperation()
+
+    normalizeMergeTargets(paths, normalizedOptions).forEach((target) => {
+      this.mergeOperations.push({
+        direction,
+        path: target.path,
+        matchOn: target.matchOn
+      })
+    })
+
+    return this
+  }
+
+  _clearDefaultMergeOperation() {
+    if (
+      this.mergeOperations.length === 1 &&
+      this.mergeOperations[0].isDefault
+    ) {
+      this.mergeOperations = []
+    }
+  }
 }

package/lib/props/once-prop.js

@@ -1,3 +1,7 @@
+/**
+ * @typedef {import('../types').PropCallback} PropCallback
+ */
+
 /**
  * OnceProp - A prop that is resolved only once and cached across navigations.
  *
@@ -33,12 +37,16 @@
 module.exports = class OnceProp {
   /**
    * Create a new OnceProp 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) {
+    /** @type {PropCallback} */
     this.callback = callback
+    /** @type {string|null} */
     this._key = null
+    /** @type {number|null} */
     this._ttl = null
+    /** @type {boolean} */
     this._refresh = false
   }
 

package/lib/props/optional-prop.js

@@ -1,5 +1,9 @@
 const ignoreFirstLoadSymbol = require('../helpers/ignore-first-load-symbol')
 
+/**
+ * @typedef {import('../types').PropCallback} PropCallback
+ */
+
 /**
  * OptionalProp - A prop that is only evaluated when explicitly requested.
  *
@@ -20,12 +24,16 @@ const ignoreFirstLoadSymbol = require('../helpers/ignore-first-load-symbol')
 module.exports = class OptionalProp {
   /**
    * Create a new OptionalProp 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) {
-    /** @type {Function} */
+    /** @type {PropCallback} */
     this.callback = callback
-    /** @type {boolean} */
-    this[ignoreFirstLoadSymbol] = true
+    Object.defineProperty(this, ignoreFirstLoadSymbol, {
+      value: true,
+      enumerable: true,
+      configurable: true,
+      writable: true
+    })
   }
 }

package/lib/props/pick-props-to-resolve.js

@@ -7,6 +7,17 @@ const resolveExceptProps = require('./resolve-except-props')
 const { filterOnceProps } = require('./resolve-once-props')
 const AlwaysProp = require('./always-prop')
 
+/**
+ * @typedef {import('../types').InertiaRequest} InertiaRequest
+ * @typedef {import('../types').InertiaProps} InertiaProps
+ */
+
+/**
+ * @param {InertiaRequest} req
+ * @param {string} component
+ * @param {InertiaProps} [props]
+ * @returns {InertiaProps}
+ */
 module.exports = function pickPropsToResolve(req, component, props = {}) {
   const isPartial = isInertiaPartialRequest(req, component)
   const isInertia = isInertiaRequest(req)
@@ -15,7 +26,9 @@ module.exports = function pickPropsToResolve(req, component, props = {}) {
   if (!isPartial) {
     newProps = Object.fromEntries(
       Object.entries(props).filter(([_, value]) => {
-        if (value && value[ignoreFirstLoadSymbol]) return false
+        if (value && /** @type {any} */ (value)[ignoreFirstLoadSymbol]) {
+          return false
+        }
         return true
       })
     )

package/lib/props/resolve-deferred-props.js

@@ -1,7 +1,23 @@
 const isInertiaPartialRequest = require('../helpers/is-inertia-partial-request')
 const DeferProp = require('./defer-prop')
+
+/**
+ * @typedef {import('../types').InertiaRequest} InertiaRequest
+ * @typedef {import('../types').InertiaProps} InertiaProps
+ *
+ * @typedef {Object} DeferredPropsMetadata
+ * @property {Record<string, string[]>} [deferredProps]
+ */
+
+/**
+ * @param {InertiaRequest} req
+ * @param {string} component
+ * @param {InertiaProps} pageProps
+ * @returns {DeferredPropsMetadata}
+ */
 module.exports = function resolveDeferredProps(req, component, pageProps) {
   if (isInertiaPartialRequest(req, component)) return {}
+  /** @type {Record<string, string[]>} */
   const deferredProps = Object.entries(pageProps || {})
     .filter(([_, value]) => value instanceof DeferProp)
     .map(([key, value]) => ({ key, group: value.getGroup() }))
@@ -9,7 +25,7 @@ module.exports = function resolveDeferredProps(req, component, pageProps) {
       if (!groups[group]) groups[group] = []
       groups[group].push(key)
       return groups
-    }, {})
+    }, /** @type {Record<string, string[]>} */ ({}))
 
   return Object.keys(deferredProps).length ? { deferredProps } : {}
 }

package/lib/props/resolve-except-props.js

@@ -1,4 +1,15 @@
 const { PARTIAL_EXCEPT } = require('../helpers/inertia-headers')
+
+/**
+ * @typedef {import('../types').InertiaRequest} InertiaRequest
+ * @typedef {import('../types').InertiaProps} InertiaProps
+ */
+
+/**
+ * @param {InertiaRequest} req
+ * @param {InertiaProps} props
+ * @returns {InertiaProps}
+ */
 module.exports = function resolveExceptProps(req, props) {
   const partialExceptHeader = req.get(PARTIAL_EXCEPT)
   const except = partialExceptHeader.split(',').filter(Boolean)

package/lib/props/resolve-merge-props.js

@@ -1,37 +1,98 @@
-const { RESET } = require('../helpers/inertia-headers')
+const {
+  INFINITE_SCROLL_MERGE_INTENT,
+  RESET
+} = require('../helpers/inertia-headers')
 const MergeableProp = require('./mergeable-prop')
+const { resolvePropPath, unique } = require('./merge-targets')
+const ScrollProp = require('./scroll-prop')
+
+/**
+ * @typedef {import('../types').InertiaProps} InertiaProps
+ * @typedef {{ get: (header: string) => any }} HeaderRequest
+ *
+ * @typedef {Object} MergePropsMetadata
+ * @property {string[]} [mergeProps]
+ * @property {string[]} [prependProps]
+ * @property {string[]} [deepMergeProps]
+ * @property {string[]} [matchPropsOn]
+ */
 
 /**
  * Resolve merge props metadata for the page response.
  * Returns mergeProps and deepMergeProps arrays for the client.
- * @param {Object} req - The request object
- * @param {Object} pageProps - The page props
- * @returns {Object} - Object with mergeProps and/or deepMergeProps arrays
+ * @param {HeaderRequest} req - The request object
+ * @param {InertiaProps} pageProps - The page props
+ * @returns {MergePropsMetadata} - Object with mergeProps and/or deepMergeProps arrays
  */
 module.exports = function resolveMergeProps(req, pageProps) {
   const inertiaResetHeader = req.get(RESET)
   const resetProps = new Set(inertiaResetHeader?.split(',').filter(Boolean))
+  const infiniteScrollMergeIntent = req.get(INFINITE_SCROLL_MERGE_INTENT)
+
+  /** @type {string[]} */
+  const mergeProps = []
+  /** @type {string[]} */
+  const prependProps = []
+  /** @type {string[]} */
+  const deepMergeProps = []
+  /** @type {string[]} */
+  const matchPropsOn = []
+
+  Object.entries(pageProps || {}).forEach(([key, value]) => {
+    if (!(value instanceof MergeableProp) || !value.shouldMerge) return
+    if (resetProps.has(key)) return
+
+    if (value instanceof ScrollProp) {
+      const propPath = resolvePropPath(key, value.wrapper)
+      if (resetProps.has(propPath)) return
+
+      if (infiniteScrollMergeIntent === 'prepend') {
+        prependProps.push(propPath)
+      } else {
+        mergeProps.push(propPath)
+      }
+
+      if (value.matchOnPath) {
+        matchPropsOn.push(resolvePropPath(propPath, value.matchOnPath))
+      }
+
+      return
+    }
+
+    if (value.shouldDeepMerge) {
+      deepMergeProps.push(key)
+      value.matchOnPaths.forEach((path) => {
+        matchPropsOn.push(resolvePropPath(key, path))
+      })
+      return
+    }
+
+    value.mergeOperations.forEach((operation) => {
+      const propPath = resolvePropPath(key, operation.path)
+      if (resetProps.has(propPath)) return
 
-  const mergeableEntries = Object.entries(pageProps || {}).filter(
-    ([key, value]) =>
-      value instanceof MergeableProp &&
-      value.shouldMerge &&
-      !resetProps.has(key)
-  )
+      if (operation.direction === 'prepend') {
+        prependProps.push(propPath)
+      } else {
+        mergeProps.push(propPath)
+      }
 
-  // Props that should be shallow merged (appended)
-  const mergeProps = mergeableEntries
-    .filter(([_, value]) => !value.shouldDeepMerge)
-    .map(([key]) => key)
+      if (operation.matchOn) {
+        matchPropsOn.push(resolvePropPath(propPath, operation.matchOn))
+      }
+    })
 
-  // Props that should be deep merged
-  const deepMergeProps = mergeableEntries
-    .filter(([_, value]) => value.shouldDeepMerge)
-    .map(([key]) => key)
+    value.matchOnPaths.forEach((path) => {
+      matchPropsOn.push(resolvePropPath(key, path))
+    })
+  })
 
+  /** @type {MergePropsMetadata} */
   const result = {}
-  if (mergeProps.length) result.mergeProps = mergeProps
-  if (deepMergeProps.length) result.deepMergeProps = deepMergeProps
+  if (mergeProps.length) result.mergeProps = unique(mergeProps)
+  if (prependProps.length) result.prependProps = unique(prependProps)
+  if (deepMergeProps.length) result.deepMergeProps = unique(deepMergeProps)
+  if (matchPropsOn.length) result.matchPropsOn = unique(matchPropsOn)
 
   return result
 }

package/lib/props/resolve-once-props.js

@@ -2,14 +2,22 @@ const OnceProp = require('./once-prop')
 const { EXCEPT_ONCE_PROPS } = require('../helpers/inertia-headers')
 const requestContext = require('../helpers/request-context')
 
+/**
+ * @typedef {import('../types').InertiaRequest} InertiaRequest
+ * @typedef {import('../types').InertiaProps} InertiaProps
+ *
+ * @typedef {Object} OncePropsMetadata
+ * @property {Record<string, { prop: string, expiresAt: number|null }>} [onceProps]
+ */
+
 /**
  * Get the list of once-props that the client already has cached.
  * These are sent via the X-Inertia-Except-Once-Props header.
- * @param {Object} req - The request object
+ * @param {InertiaRequest} req - The request object
  * @returns {string[]} - Array of prop keys the client already has
  */
 function getExceptOnceProps(req) {
-  const header = req.get(EXCEPT_ONCE_PROPS) || ''
+  const header = String(req.get(EXCEPT_ONCE_PROPS) || '')
   return header
     ? header
         .split(',')
@@ -28,9 +36,9 @@ function getExceptOnceProps(req) {
  * - They are marked for refresh via sails.inertia.refreshOnce()
  * - The client doesn't have them cached
  *
- * @param {Object} req - The request object
- * @param {Object} props - The props object
- * @returns {Object} - Filtered props with cached once-props removed
+ * @param {InertiaRequest} req - The request object
+ * @param {InertiaProps} props - The props object
+ * @returns {InertiaProps} - Filtered props with cached once-props removed
  */
 function filterOnceProps(req, props) {
   const exceptOnceProps = getExceptOnceProps(req)
@@ -40,6 +48,7 @@ function filterOnceProps(req, props) {
     return props
   }
 
+  /** @type {InertiaProps} */
   const filtered = {}
   for (const [key, value] of Object.entries(props)) {
     // Keep the prop if it's not a OnceProp
@@ -75,10 +84,11 @@ function filterOnceProps(req, props) {
 /**
  * Build the onceProps metadata for the page response.
  * This tells the client which props are "once" props and their expiration.
- * @param {Object} props - The props object
- * @returns {Object} - Object with onceProps key if any exist, empty object otherwise
+ * @param {InertiaProps} props - The props object
+ * @returns {OncePropsMetadata} - Object with onceProps key if any exist, empty object otherwise
  */
 function resolveOncePropsMetadata(props) {
+  /** @type {Record<string, { prop: string, expiresAt: number|null }>} */
   const onceProps = {}
 
   for (const [key, value] of Object.entries(props)) {

package/lib/props/resolve-only-props.js

@@ -1,4 +1,10 @@
 const { PARTIAL_DATA } = require('../helpers/inertia-headers')
+
+/**
+ * @typedef {import('../types').InertiaRequest} InertiaRequest
+ * @typedef {import('../types').InertiaProps} InertiaProps
+ */
+
 /**
  * Extracts only the props specified by the partial header from the given props object.
  *
@@ -6,13 +12,14 @@ const { PARTIAL_DATA } = require('../helpers/inertia-headers')
  * which should contain a comma-separated list of property keys. It then constructs and returns
  * a new object that includes only those keys from the provided props object.
  *
- * @param {Object} req - The Express-style request object. It must have a `get` method to retrieve headers.
- * @param {Object} props - The complete set of props.
- * @returns {Object} An object containing only the properties whose keys were specified in the partial header.
+ * @param {InertiaRequest} req - The Express-style request object. It must have a `get` method to retrieve headers.
+ * @param {InertiaProps} props - The complete set of props.
+ * @returns {InertiaProps} An object containing only the properties whose keys were specified in the partial header.
  */
 module.exports = function resolveOnlyProps(req, props) {
   const partialOnlyHeader = req.get(PARTIAL_DATA)
   const only = partialOnlyHeader.split(',').filter(Boolean)
+  /** @type {InertiaProps} */
   let newProps = {}
 
   for (const key of only) newProps[key] = props[key]

package/lib/props/resolve-page-props.js

@@ -1,4 +1,64 @@
+const DeferProp = require('./defer-prop')
 const resolveProp = require('./resolve-prop')
+
+/**
+ * @typedef {import('../types').InertiaProps} InertiaProps
+ * @typedef {import('../types').ResolvedPageProps} ResolvedPageProps
+ *
+ * @typedef {((props?: InertiaProps) => Promise<InertiaProps>) & {
+ *   withMetadata: (props?: InertiaProps) => Promise<ResolvedPageProps>
+ * }} ResolvePageProps
+ */
+
+/**
+ * @param {any} value
+ * @returns {boolean}
+ */
+function shouldRescueProp(value) {
+  return value instanceof DeferProp && value.shouldRescueProp()
+}
+
+/**
+ * @param {InertiaProps} [props]
+ * @returns {Promise<ResolvedPageProps>}
+ */
+async function resolvePagePropsWithMetadata(props = {}) {
+  const resolved = await Promise.all(
+    Object.entries(props).map(async ([key, value]) => {
+      try {
+        if (typeof value === 'function') {
+          const result = await value()
+          return { entry: await resolveProp(key, result) }
+        }
+        return { entry: await resolveProp(key, value) }
+      } catch (error) {
+        if (shouldRescueProp(value)) {
+          return { rescuedProp: key }
+        }
+        throw error
+      }
+    })
+  )
+
+  /** @type {Array<[string, any]>} */
+  const entries = []
+  /** @type {string[]} */
+  const rescuedProps = []
+
+  for (const result of resolved) {
+    if (result.rescuedProp) {
+      rescuedProps.push(result.rescuedProp)
+      continue
+    }
+    entries.push(result.entry)
+  }
+
+  return {
+    props: Object.fromEntries(entries),
+    rescuedProps
+  }
+}
+
 /**
  * Resolve all page props.
  *
@@ -7,18 +67,17 @@ const resolveProp = require('./resolve-prop')
  * Then, every property is passed to resolveProp() to see if it needs
  * any special handling.
  *
- * @param {Object} [props={}] - An object containing page props.
- * @returns {Promise<Object>} A promise that resolves to a new object with resolved props.
+ * @param {InertiaProps} [props={}] - An object containing page props.
+ * @returns {Promise<InertiaProps>} A promise that resolves to a new object with resolved props.
  */
-module.exports = async function resolvePageProps(props = {}) {
-  const entries = await Promise.all(
-    Object.entries(props).map(async ([key, value]) => {
-      if (typeof value === 'function') {
-        const result = await value()
-        return resolveProp(key, result)
-      }
-      return resolveProp(key, value)
-    })
-  )
-  return Object.fromEntries(entries)
+async function resolvePageProps(props = {}) {
+  const resolved = await resolvePagePropsWithMetadata(props)
+  return resolved.props
 }
+
+/** @type {ResolvePageProps} */
+const exportedResolvePageProps = Object.assign(resolvePageProps, {
+  withMetadata: resolvePagePropsWithMetadata
+})
+
+module.exports = exportedResolvePageProps