inertia-sails 1.3.2 → 1.4.0

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

@@ -1,12 +1,25 @@
 const ScrollProp = require('./scroll-prop')
 
+/**
+ * @typedef {import('../types').InertiaProps} InertiaProps
+ *
+ * @typedef {Object} ScrollPropsMetadata
+ * @property {Record<string, {
+ *   pageName: string,
+ *   currentPage: number,
+ *   previousPage: number|null,
+ *   nextPage: number|null,
+ *   reset: boolean
+ * }>} [scrollProps]
+ */
+
 /**
  * Resolve scroll props metadata for the page response.
  * Extracts ScrollProp instances and builds the scrollProps object
- * expected by Inertia.js v2's <InfiniteScroll> component.
+ * expected by Inertia's <InfiniteScroll> component.
  *
- * @param {Object} pageProps - The page props
- * @returns {Object} - Object with scrollProps if any exist
+ * @param {InertiaProps} pageProps - The page props
+ * @returns {ScrollPropsMetadata} - Object with scrollProps if any exist
  *
  * @example
  * // Input props with ScrollProp instance:
@@ -26,6 +39,7 @@ const ScrollProp = require('./scroll-prop')
  * }
  */
 module.exports = function resolveScrollProps(pageProps) {
+  /** @type {NonNullable<ScrollPropsMetadata['scrollProps']>} */
   const scrollProps = {}
 
   for (const [key, value] of Object.entries(pageProps || {})) {

package/lib/props/scroll-prop.js

@@ -1,5 +1,17 @@
 const MergeProp = require('./merge-prop')
 
+/**
+ * @typedef {import('../types').PropCallback} PropCallback
+ *
+ * @typedef {Object} ScrollPropOptions
+ * @property {number} [page=0] - Current page index (0-based for Waterline)
+ * @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
+ */
+
 /**
  * ScrollProp - Configures paginated data for infinite scrolling.
  *
@@ -20,13 +32,8 @@ const MergeProp = require('./merge-prop')
  */
 class ScrollProp extends MergeProp {
   /**
-   * @param {Function} callback - Callback returning the paginated data array
-   * @param {Object} [options] - Pagination options
-   * @param {number} [options.page=0] - Current page index (0-based for Waterline)
-   * @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 {ScrollPropOptions} [options] - Pagination options
    */
   constructor(callback, options = {}) {
     const {
@@ -34,7 +41,8 @@ class ScrollProp extends MergeProp {
       perPage = 10,
       total = 0,
       pageName = 'page',
-      wrapper = 'data'
+      wrapper = 'data',
+      matchOn = null
     } = options
 
     // Calculate pagination metadata
@@ -45,6 +53,7 @@ class ScrollProp extends MergeProp {
     const hasPreviousPage = currentPage > 1
 
     // Wrap the callback to return structured data with metadata
+    /** @type {() => Promise<any>} */
     const wrappedCallback = async () => {
       const data = typeof callback === 'function' ? await callback() : callback
 
@@ -66,13 +75,26 @@ class ScrollProp extends MergeProp {
 
     super(wrappedCallback)
 
+    // InfiniteScroll uses request headers to decide append vs prepend.
+    /** @type {import('../types').MergeOperation[]} */
+    this.mergeOperations = []
+
     // Store metadata for potential access
+    /** @type {number} */
     this.page = page
+    /** @type {number} */
     this.perPage = perPage
+    /** @type {number} */
     this.total = total
+    /** @type {string} */
     this.pageName = pageName
+    /** @type {string} */
     this.wrapper = wrapper
+    /** @type {string|null} */
+    this.matchOnPath = matchOn
+    /** @type {number} */
     this.totalPages = totalPages
+    /** @type {number} */
     this.currentPage = currentPage
   }
 }

package/lib/render.js

@@ -2,7 +2,60 @@ const { encode } = require('querystring')
 const inertiaHeaders = require('./helpers/inertia-headers')
 const buildPageObject = require('./helpers/build-page-object')
 const requestContext = require('./helpers/request-context')
+const resolveAssetVersion = require('./helpers/resolve-asset-version')
 
+/**
+ * @typedef {import('./types').InertiaRequest} InertiaRequest
+ * @typedef {import('./types').InertiaResponse} InertiaResponse
+ * @typedef {import('./types').InertiaProps} InertiaProps
+ *
+ * @typedef {Object} RenderData
+ * @property {string} page
+ * @property {InertiaProps} [props]
+ * @property {InertiaProps} [locals]
+ */
+
+/**
+ * @param {InertiaRequest} req
+ * @returns {string}
+ */
+function getRequestUrl(req) {
+  let url = req.url || req.originalUrl || '/'
+  const queryParams = req.query || {}
+
+  if (req.method === 'GET' && Object.keys(queryParams).length) {
+    // Only append query params if the URL doesn't already contain them
+    // This prevents duplication when redirecting with query parameters
+    if (!url.includes('?')) {
+      url += `?${encode(queryParams)}`
+    }
+  }
+
+  return url
+}
+
+/**
+ * @param {InertiaRequest} req
+ * @param {any} currentVersion
+ * @returns {boolean}
+ */
+function hasAssetVersionMismatch(req, currentVersion) {
+  const requestVersion = req.get(inertiaHeaders.VERSION)
+
+  if (req.method !== 'GET') return false
+  if (!req.get(inertiaHeaders.INERTIA)) return false
+  if (requestVersion === undefined || requestVersion === null) return false
+  if (currentVersion === undefined || currentVersion === null) return false
+
+  return String(requestVersion) !== String(currentVersion)
+}
+
+/**
+ * @param {InertiaRequest} req
+ * @param {InertiaResponse} res
+ * @param {RenderData} data
+ * @returns {Promise<any>}
+ */
 module.exports = async function render(req, res, data) {
   const sails = req._sails
   // Use request-scoped rootView if set, otherwise fall back to config
@@ -15,20 +68,26 @@ module.exports = async function render(req, res, data) {
     ...data.locals
   }
 
-  let page = await buildPageObject(req, data.page, data.props)
+  const currentVersion = resolveAssetVersion(sails)
+  const requestUrl = getRequestUrl(req)
 
-  const queryParams = req.query
-  if (req.method === 'GET' && Object.keys(queryParams).length) {
-    // Only append query params if the URL doesn't already contain them
-    // This prevents duplication when redirecting with query parameters
-    if (!page.url.includes('?')) {
-      page.url += `?${encode(queryParams)}`
-    }
+  if (hasAssetVersionMismatch(req, currentVersion)) {
+    res.set('Vary', 'X-Inertia')
+    res.set(inertiaHeaders.LOCATION, requestUrl)
+    return res.status(409).end()
   }
 
+  let page = await buildPageObject(
+    /** @type {any} */ (req),
+    data.page,
+    data.props
+  )
+
+  page.url = requestUrl
+
   if (req.get(inertiaHeaders.INERTIA)) {
     res.set(inertiaHeaders.INERTIA, true)
-    res.set('Vary', 'Accept')
+    res.set('Vary', 'X-Inertia')
     return res.json(page)
   } else {
     // Implements full page reload

package/lib/responses/server-error.js

@@ -1,3 +1,10 @@
+/**
+ * @typedef {import('../types').InertiaRequest} InertiaRequest
+ * @typedef {import('../types').InertiaResponse} InertiaResponse
+ * @typedef {import('../types').ErrorHtmlData} ErrorHtmlData
+ * @typedef {{ message?: string, stack?: string, name?: string }} ErrorLike
+ */
+
 /**
  * Server Error Response for Inertia.js
  *
@@ -9,9 +16,9 @@
  * in a modal overlay during development, allowing developers to see stack traces
  * without losing their page state.
  *
- * @param {Object} req - Express/Sails request object
- * @param {Object} res - Express/Sails response object
- * @param {Object|Error} [error] - Optional error data or Error object
+ * @param {InertiaRequest} req - Express/Sails request object
+ * @param {InertiaResponse} res - Express/Sails response object
+ * @param {ErrorLike} [error] - Optional error data or Error object
  * @returns {*} - Response
  *
  * @example
@@ -29,7 +36,7 @@
 module.exports = function handleServerError(req, res, error) {
   const sails = req._sails
   const statusCode = 500
-  const isInertiaRequest = req.header('X-Inertia')
+  const isInertiaRequest = req.header?.('X-Inertia')
   const isDevelopment = process.env.NODE_ENV !== 'production'
 
   // Log the error
@@ -49,8 +56,8 @@ module.exports = function handleServerError(req, res, error) {
       errorName,
       errorMessage,
       errorStack,
-      url: req.url,
-      method: req.method
+      url: req.url || '/',
+      method: req.method || 'GET'
     })
 
     res.status(statusCode)
@@ -76,6 +83,10 @@ module.exports = function handleServerError(req, res, error) {
     {
       error: isDevelopment ? error : null
     },
+    /**
+     * @param {Error|null} err
+     * @param {string} html
+     */
     (err, html) => {
       if (err) {
         // If view doesn't exist, send a basic response
@@ -91,6 +102,8 @@ module.exports = function handleServerError(req, res, error) {
 
 /**
  * Build an HTML error page for the Inertia modal
+ * @param {ErrorHtmlData} data
+ * @returns {string}
  */
 function buildErrorHtml({
   statusCode,
@@ -270,6 +283,8 @@ function buildErrorHtml({
 
 /**
  * Format stack trace with syntax highlighting
+ * @param {string} stack
+ * @returns {string}
  */
 function formatStackTrace(stack) {
   return stack
@@ -294,6 +309,8 @@ function formatStackTrace(stack) {
 
 /**
  * Escape HTML special characters
+ * @param {any} str
+ * @returns {string}
  */
 function escapeHtml(str) {
   if (!str) return ''

package/lib/types.js

@@ -0,0 +1,68 @@
+/**
+ * Shared JSDoc typedefs for inertia-sails.
+ *
+ * These keep editor type-checking useful without turning the package into
+ * TypeScript. The shapes intentionally stay permissive because Sails request,
+ * response, and hook objects are extended by applications and other hooks.
+ *
+ * @typedef {Record<string, any>} InertiaProps
+ *
+ * @typedef {Object} SailsLike
+ * @property {Record<string, any>} config
+ * @property {{ info?: (...args: any[]) => void, warn?: (...args: any[]) => void, error?: (...args: any[]) => void }} [log]
+ * @property {Record<string, any>} [inertia]
+ * @property {{ bind?: (...args: any[]) => any }} [router]
+ * @property {(event: string, callback: (...args: any[]) => any) => any} [on]
+ *
+ * @typedef {Object} InertiaRequest
+ * @property {SailsLike} _sails
+ * @property {string} [method]
+ * @property {string} [url]
+ * @property {string} [originalUrl]
+ * @property {Record<string, any>} [query]
+ * @property {Record<string, any>} [headers]
+ * @property {Record<string, any>} [session]
+ * @property {boolean} [isSocket]
+ * @property {(name: string) => any} get
+ * @property {(name: string) => any} [header]
+ * @property {(key: string, value?: any) => any[]} [flash]
+ *
+ * @typedef {Object} InertiaResponse
+ * @property {(name: string, value: any) => InertiaResponse} [set]
+ * @property {(code: number) => InertiaResponse} [status]
+ * @property {(code: number) => any} [sendStatus]
+ * @property {(body?: any) => any} [send]
+ * @property {(body: any) => any} [json]
+ * @property {(...args: any[]) => any} [redirect]
+ * @property {(view: string, data?: any, callback?: (err: Error | null, html: string) => any) => any} [view]
+ * @property {(type: string) => InertiaResponse} [type]
+ * @property {() => any} [end]
+ *
+ * @typedef {() => any | Promise<any>} PropCallback
+ *
+ * @typedef {Object} MergeOperation
+ * @property {'append'|'prepend'|string} direction
+ * @property {string|null} path
+ * @property {string|null} matchOn
+ * @property {boolean} [isDefault]
+ *
+ * @typedef {Object} MergeOptions
+ * @property {string|Record<string, string|null>} [matchOn]
+ *
+ * @typedef {Object} ResolvedPageProps
+ * @property {InertiaProps} props
+ * @property {string[]} rescuedProps
+ *
+ * @typedef {Object} BadRequestData
+ * @property {Array<string|Record<string, string>>} [problems]
+ *
+ * @typedef {Object} ErrorHtmlData
+ * @property {number} statusCode
+ * @property {string} errorName
+ * @property {string} errorMessage
+ * @property {string} errorStack
+ * @property {string} url
+ * @property {string} method
+ */
+
+module.exports = {}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "inertia-sails",
-  "version": "1.3.2",
+  "version": "1.4.0",
   "description": "The Sails adapter for Inertia.",
   "main": "index.js",
   "sails": {
@@ -8,7 +8,8 @@
     "hookName": "inertia"
   },
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "check:js": "tsc --allowJs --checkJs --noEmit --skipLibCheck --target ES2022 --module commonjs --noImplicitAny index.js test.js lib/**/*.js tests/**/*.js",
+    "test": "npm run check:js && node --test tests/*.test.js tests/**/*.test.js"
   },
   "repository": {
     "type": "git",

package/test.js

@@ -24,11 +24,13 @@ const { INERTIA, VERSION } = require('./lib/helpers/inertia-headers')
  * @typedef {Object} InertiaPage
  * @property {string} component - The component name
  * @property {string} url - The current URL
- * @property {Object} props - The page props
- * @property {Object} [flash] - Flash data
+ * @property {Record<string, any>} props - The page props
+ * @property {Record<string, any>} [flash] - Flash data
+ * @property {boolean} [preserveFragment] - Whether URL fragments are preserved after redirects
  * @property {string[]} [mergeProps] - Props to merge
  * @property {string[]} [deepMergeProps] - Props to deep merge
- * @property {Object} [deferredProps] - Deferred props by group
+ * @property {Record<string, string[]>} [deferredProps] - Deferred props by group
+ * @property {string[]} [rescuedProps] - Deferred props rescued after callback failures
  */
 
 /**
@@ -37,6 +39,19 @@ const { INERTIA, VERSION } = require('./lib/helpers/inertia-headers')
  * @property {number} statusCode - HTTP status code
  */
 
+/**
+ * @typedef {Object} SailsRequestOptions
+ * @property {string} url - Request URL or verb/path pair
+ * @property {Record<string, any>} [data] - Request data
+ * @property {Record<string, any>} [headers] - Request headers
+ */
+
+/**
+ * @typedef {Object} SailsTestApp
+ * @property {{ inertia?: { version?: any } }} config
+ * @property {(options: SailsRequestOptions, callback: (err: Error|null, response: SailsResponse, body: InertiaPage) => void) => void} request
+ */
+
 /**
  * InertiaTestResponse - Fluent assertions for Inertia page responses
  */
@@ -115,7 +130,7 @@ class InertiaTestResponse {
 
   /**
    * Assert props match expected values
-   * @param {Object} expected - Object with expected key-value pairs
+   * @param {Record<string, any>} expected - Object with expected key-value pairs
    * @returns {InertiaTestResponse} - For chaining
    */
   assertProps(expected) {
@@ -135,7 +150,7 @@ class InertiaTestResponse {
   /**
    * Assert a prop value using a callback
    * @param {string} key - Prop key
-   * @param {Function} callback - Callback receiving the value, should throw if invalid
+   * @param {(value: any) => void} callback - Callback receiving the value, should throw if invalid
    * @returns {InertiaTestResponse} - For chaining
    */
   assertProp(key, callback) {
@@ -233,9 +248,35 @@ class InertiaTestResponse {
     return this
   }
 
+  /**
+   * Assert rescuedProps contains specific keys
+   * @param {string[]} keys - Expected rescued prop keys
+   * @returns {InertiaTestResponse} - For chaining
+   */
+  assertRescuedProps(keys) {
+    const rescuedProps = this.page.rescuedProps || []
+    for (const key of keys) {
+      if (!rescuedProps.includes(key)) {
+        throw new Error(`Expected "${key}" in rescuedProps`)
+      }
+    }
+    return this
+  }
+
+  /**
+   * Assert preserveFragment metadata is enabled
+   * @returns {InertiaTestResponse} - For chaining
+   */
+  assertPreserveFragment() {
+    if (this.page.preserveFragment !== true) {
+      throw new Error('Expected preserveFragment to be true')
+    }
+    return this
+  }
+
   /**
    * Get the raw page object for custom assertions
-   * @returns {Object} - The Inertia page object
+   * @returns {InertiaPage} - The Inertia page object
    */
   getPage() {
     return this.page
@@ -243,7 +284,7 @@ class InertiaTestResponse {
 
   /**
    * Get the raw props for custom assertions
-   * @returns {Object} - The props object
+   * @returns {Record<string, any>} - The props object
    */
   getProps() {
     return this.page.props
@@ -252,14 +293,14 @@ class InertiaTestResponse {
   /**
    * Helper to get nested values using dot notation
    * @private
-   * @param {Object} obj - The object to search
+   * @param {Record<string, any>} obj - The object to search
    * @param {string} path - Dot-notation path
    * @returns {*} - The value at the path
    */
   _getNestedValue(obj, path) {
     return path.split('.').reduce(
       /**
-       * @param {Object} current
+       * @param {any} current
        * @param {string} key
        */
       (current, key) => {
@@ -289,14 +330,14 @@ class InertiaTestResponse {
 
 /**
  * Create Inertia testing utilities for a Sails instance
- * @param {Object} sails - The Sails application instance
- * @returns {Object} - Testing utilities
+ * @param {SailsTestApp} sails - The Sails application instance
+ * @returns {Record<string, any>} - Testing utilities
  */
 module.exports = function createInertiaTestUtils(sails) {
   return {
     /**
      * Make an Inertia request and return a test response
-     * @param {string|Object} urlOrOptions - URL string or request options
+     * @param {string|SailsRequestOptions} urlOrOptions - URL string or request options
      * @returns {Promise<InertiaTestResponse>} - Test response with assertions
      * @example
      * // Simple GET

package/tests/helpers/build-page-object.test.js

@@ -0,0 +1,183 @@
+const { describe, it } = require('node:test')
+const assert = require('node:assert/strict')
+const buildPageObject = require('../../lib/helpers/build-page-object')
+const DeferProp = require('../../lib/props/defer-prop')
+const {
+  INERTIA,
+  PARTIAL_COMPONENT,
+  PARTIAL_DATA
+} = require('../../lib/helpers/inertia-headers')
+
+/**
+ * @param {Record<string, any>} object
+ * @param {string} key
+ * @returns {boolean}
+ */
+function hasOwn(object, key) {
+  return Object.prototype.hasOwnProperty.call(object, key)
+}
+
+function createRequest({
+  sharedProps = {},
+  pageProps = {},
+  clearHistory = false,
+  encryptHistory = false,
+  preserveFragment = false,
+  flash = {},
+  headers = {},
+  version = 'test-version',
+  url = '/dashboard'
+} = {}) {
+  const normalizedHeaders = Object.fromEntries(
+    Object.entries(headers).map(([key, value]) => [key.toLowerCase(), value])
+  )
+
+  return {
+    url,
+    /**
+     * @param {string} header
+     * @returns {any}
+     */
+    get(header) {
+      return normalizedHeaders[header.toLowerCase()]
+    },
+    _sails: {
+      config: {
+        inertia: {
+          version
+        }
+      },
+      inertia: {
+        getShared() {
+          return sharedProps
+        },
+        shouldClearHistory() {
+          return clearHistory
+        },
+        shouldEncryptHistory() {
+          return encryptHistory
+        },
+        consumePreserveFragment() {
+          return preserveFragment
+        },
+        consumeFlash() {
+          return flash
+        }
+      }
+    },
+    pageProps
+  }
+}
+
+describe('buildPageObject', function () {
+  it('omits false history flags from the page object', async function () {
+    const req = createRequest()
+    const page = await buildPageObject(req, 'dashboard/index', {})
+
+    assert.equal(hasOwn(page, 'clearHistory'), false)
+    assert.equal(hasOwn(page, 'encryptHistory'), false)
+  })
+
+  it('includes true history flags in the page object', async function () {
+    const req = createRequest({
+      clearHistory: true,
+      encryptHistory: true
+    })
+    const page = await buildPageObject(req, 'dashboard/index', {})
+
+    assert.equal(page.clearHistory, true)
+    assert.equal(page.encryptHistory, true)
+  })
+
+  it('omits false preserveFragment from the page object', async function () {
+    const req = createRequest()
+    const page = await buildPageObject(req, 'dashboard/index', {})
+
+    assert.equal(hasOwn(page, 'preserveFragment'), false)
+  })
+
+  it('includes true preserveFragment in the page object', async function () {
+    const req = createRequest({
+      preserveFragment: true
+    })
+    const page = await buildPageObject(req, 'dashboard/index', {})
+
+    assert.equal(page.preserveFragment, true)
+  })
+
+  it('adds sharedProps metadata for shared prop keys', async function () {
+    const req = createRequest({
+      sharedProps: {
+        auth: { user: { id: 1 } },
+        app: { name: 'Boring Stack' }
+      }
+    })
+    const page = await buildPageObject(req, 'dashboard/index', {
+      stats: { users: 10 }
+    })
+
+    assert.deepEqual(page.sharedProps, ['auth', 'app'])
+    assert.deepEqual(page.props.auth, { user: { id: 1 } })
+    assert.deepEqual(page.props.stats, { users: 10 })
+  })
+
+  it('keeps sharedProps metadata when page props override a shared key', async function () {
+    const req = createRequest({
+      sharedProps: {
+        auth: { user: { id: 1 } }
+      }
+    })
+    const page = await buildPageObject(req, 'dashboard/index', {
+      auth: { user: { id: 2 } }
+    })
+
+    assert.deepEqual(page.sharedProps, ['auth'])
+    assert.deepEqual(page.props.auth, { user: { id: 2 } })
+  })
+
+  it('omits sharedProps when no shared props are present', async function () {
+    const req = createRequest()
+    const page = await buildPageObject(req, 'dashboard/index', {})
+
+    assert.equal(hasOwn(page, 'sharedProps'), false)
+  })
+
+  it('includes rescuedProps when a rescuable deferred prop fails', async function () {
+    const req = createRequest({
+      headers: {
+        [INERTIA]: 'true',
+        [PARTIAL_COMPONENT]: 'dashboard/index',
+        [PARTIAL_DATA]: 'analytics'
+      }
+    })
+    const page = await buildPageObject(req, 'dashboard/index', {
+      analytics: new DeferProp(async () => {
+        throw new Error('Analytics service unavailable')
+      }).rescue()
+    })
+
+    assert.deepEqual(page.props, {})
+    assert.deepEqual(page.rescuedProps, ['analytics'])
+  })
+
+  it('omits merge metadata for rescued deferred props', async function () {
+    const req = createRequest({
+      headers: {
+        [INERTIA]: 'true',
+        [PARTIAL_COMPONENT]: 'dashboard/index',
+        [PARTIAL_DATA]: 'analytics'
+      }
+    })
+    const analytics = new DeferProp(async () => {
+      throw new Error('Analytics service unavailable')
+    })
+    analytics.append('data', 'id')
+    analytics.rescue()
+
+    const page = await buildPageObject(req, 'dashboard/index', { analytics })
+
+    assert.deepEqual(page.rescuedProps, ['analytics'])
+    assert.equal(hasOwn(page, 'mergeProps'), false)
+    assert.equal(hasOwn(page, 'matchPropsOn'), false)
+  })
+})