inertia-sails 0.2.1 → 0.3.0

package/index.js

@@ -4,7 +4,16 @@
  * @description :: A hook definition.  Extends Sails by adding shadow routes, implicit actions, and/or initialization logic.
  * @docs        :: https://sailsjs.com/docs/concepts/extending-sails/hooks
  */
-const inertia = require('./private/inertia-middleware')
+const inertia = require('./lib/middleware/inertia-middleware')
+const render = require('./lib/render')
+const location = require('./lib/location')
+
+const DeferProp = require('./lib/props/defer-prop')
+const OptionalProp = require('./lib/props/optional-prop')
+const MergeProp = require('./lib/props/merge-prop')
+const AlwaysProp = require('./lib/props/always-prop')
+const handleBadRequest = require('./lib/handle-bad-request')
+
 module.exports = function defineInertiaHook(sails) {
   let hook
   const routesToBindInertiaTo = [
@@ -20,7 +29,10 @@ module.exports = function defineInertiaHook(sails) {
     defaults: {
       inertia: {
         rootView: 'app',
-        version: 1
+        version: 1,
+        history: {
+          encrypt: false
+        }
       }
     },
     initialize: async function () {
@@ -28,27 +40,145 @@ module.exports = function defineInertiaHook(sails) {
       sails.inertia = hook
       sails.inertia.sharedProps = {}
       sails.inertia.sharedViewData = {}
-      sails.on('router:before', function routerBefore() {
-        routesToBindInertiaTo.forEach(function iterator(routeAddress) {
+      sails.inertia.shouldEncryptHistory = sails.config.inertia.history.encrypt
+      sails.inertia.shouldClearHistory = false
+      sails.on('router:before', function () {
+        routesToBindInertiaTo.forEach(function (routeAddress) {
           sails.router.bind(routeAddress, inertia(hook))
         })
       })
     },
 
-    share: (key, value = null) => (sails.inertia.sharedProps[key] = value),
+    /**
+     * Share a property globally
+     * @param {string} key - The key of the property
+     * @param {*} value - The value of the property
+     */
+    share(key, value = null) {
+      return (sails.inertia.sharedProps[key] = value)
+    },
 
-    getShared: (key = null) =>
-      sails.inertia.sharedProps[key] ?? sails.inertia.sharedProps,
+    /**
+     * Get shared properties
+     * @param {string|null} key - The key of the property to get, or null to get all
+     * @returns {*} - The shared property or all shared properties
+     */
+    getShared(key = null) {
+      return sails.inertia.sharedProps[key] ?? sails.inertia.sharedProps
+    },
 
-    flushShared: (key) => {
-      key
+    /**
+     * Flush shared properties
+     * @param {string|null} key - The key of the property to flush, or null to flush all
+     */
+    flushShared(key) {
+      return key
         ? delete sails.inertia.sharedProps[key]
         : (sails.inertia.sharedProps = {})
     },
 
-    viewData: (key, value) => (sails.inertia.sharedViewData[key] = value),
+    /**
+     * Add view data
+     * @param {string} key - The key of the view data
+     * @param {*} value - The value of the view data
+     */
+    viewData(key, value) {
+      return (sails.inertia.sharedViewData[key] = value)
+    },
+
+    /**
+     * Get view data
+     * @param {string} key - The key of the view data to get
+     * @returns {*} - The view data
+     */
+    getViewData(key) {
+      return sails.inertia.sharedViewData[key] ?? sails.inertia.sharedViewData
+    },
+
+    /**
+     * 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
+     * @returns {OptionalProp} - The optional prop
+     */
+    optional(callback) {
+      return new OptionalProp(callback)
+    },
+
+    /**
+     * 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
+     * @returns {MergeProp} - The mergeable prop
+     */
+    merge(callback) {
+      return new MergeProp(callback)
+    },
+
+    /**
+     * 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
+     * @returns {AlwaysProp} - The always prop
+     */
+    always(callback) {
+      return new AlwaysProp(callback)
+    },
+    /**
+     * 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
+     * @returns {DeferProp} - The deferred prop
+     */
+    defer(cb, group = 'default') {
+      return new DeferProp(cb, group)
+    },
+
+    /**
+     * Render the response
+     * @param {Object} req - The request object
+     * @param {Object} res - The response object
+     * @param {Object} data - The data to render
+     * @returns {*} - The rendered response
+     */
+    render(req, res, data) {
+      return render(req, res, data)
+    },
+    /**
+     * Handle Inertia redirects
+     * See https://docs.sailscasts.com/boring-stack/redirects
+     * @param {Object} req - The request object
+     * @param {Object} res - The response object
+     * @param {string} url - The URL to redirect to
+     * @returns {Object} - The response object with the redirect
+     */
+    location(req, res, url) {
+      return location(req, res, url)
+    },
 
-    getViewData: (key) =>
-      sails.inertia.sharedViewData[key] ?? sails.inertia.sharedViewData
+    /**
+     * Encrypt history
+     * @docs https://docs.sailscasts.com/boring-stack/history-encryption
+     * @param {boolean} encrypt - Whether to encrypt the history
+     */
+    encryptHistory(encrypt = true) {
+      sails.inertia.shouldEncryptHistory = encrypt
+    },
+
+    /**
+     * Clear history state.
+     * @docs https://docs.sailscasts.com/boring-stack/history-encryption#clearing-history
+     */
+    clearHistory() {
+      sails.inertia.shouldClearHistory = true
+    },
+    handleBadRequest(req, res, optionaLData) {
+      return handleBadRequest(req, res, optionaLData)
+    }
   }
 }

package/lib/handle-bad-request.js

@@ -0,0 +1,65 @@
+// @ts-nocheck
+module.exports = function handleBadRequest(req, res, optionalData) {
+  const sails = req._sails
+  // Define the status code to send in the response.
+  const statusCodeToSet = 400
+
+  // Check if it's an Inertia request
+  if (req.header('X-Inertia')) {
+    if (optionalData && optionalData.problems) {
+      const errors = {}
+      optionalData.problems.forEach((problem) => {
+        if (typeof problem === 'object') {
+          Object.keys(problem).forEach((propertyName) => {
+            const sanitizedProblem = 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)
+
+          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)
+            }
+          }
+        }
+      })
+      req.session.errors = errors
+      return res.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)
+  } else if (_.isError(optionalData)) {
+    sails.log.info(
+      'Custom response `res.badRequest()` called with an Error:',
+      optionalData
+    )
+
+    if (!_.isFunction(optionalData.toJSON)) {
+      if (process.env.NODE_ENV === 'production') {
+        return res.sendStatus(statusCodeToSet)
+      } else {
+        return res.status(statusCodeToSet).send(optionalData.stack)
+      }
+    }
+  } else {
+    return res.status(statusCodeToSet).send(optionalData)
+  }
+}

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

@@ -0,0 +1,27 @@
+const pickPropsToResolve = require('../props/pick-props-to-resolve')
+const resolveDeferredProps = require('../props/resolve-deferred-props')
+const resolveMergeProps = require('../props/resolve-merge-props')
+const resolvePageProps = require('../props/resolve-page-props')
+
+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
+  const propsToResolve = pickPropsToResolve(req, component, {
+    ...sails.inertia.sharedProps,
+    ...pageProps
+  })
+
+  return {
+    component,
+    url,
+    version: currentVersion,
+    props: await resolvePageProps(propsToResolve),
+    clearHistory: sails.inertia.shouldClearHistory,
+    encryptHistory: sails.inertia.shouldEncryptHistory,
+    ...resolveMergeProps(req, pageProps),
+    ...resolveDeferredProps(req, component, pageProps)
+  }
+}

package/lib/helpers/ignore-first-load-symbol.js

@@ -0,0 +1 @@
+module.exports = Symbol('ignoreFirstLoad')

package/{private → lib/helpers}/inertia-headers.js

@@ -2,6 +2,9 @@ module.exports = {
   INERTIA: 'X-Inertia',
   VERSION: 'X-Inertia-Version',
   PARTIAL_DATA: 'X-Inertia-Partial-Data',
+  PARTIAL_EXCEPT: 'X-Inertia-Partial-Except',
+  ERROR_BAG: 'X-Inertia-Error-Bag',
+  RESET: 'X-Inertia-Reset',
   PARTIAL_COMPONENT: 'X-Inertia-Partial-Component',
   LOCATION: 'X-Inertia-Location'
 }

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

@@ -0,0 +1,4 @@
+const { PARTIAL_COMPONENT } = require('./inertia-headers')
+module.exports = function isInertiaPartialRequest(req, component) {
+  return req.get(PARTIAL_COMPONENT) === component
+}

package/{private → lib/helpers}/resolve-validation-errors.js

@@ -1,3 +1,6 @@
+// @ts-nocheck
+const { ERROR_BAG } = require('./inertia-headers')
+
 /**
  * @module resolveValidationErrors
  * @description Resolves and formats validation errors from the session for Inertia responses.
@@ -22,7 +25,7 @@ module.exports = function resolveValidationErrors(req) {
     return result
   }, {})
 
-  const inertiaErrorBag = req.headers['x-inertia-error-bag']
+  const inertiaErrorBag = req.headers[ERROR_BAG]
 
   if (inertiaErrorBag && collectedErrors[inertiaErrorBag]) {
     const selectedErrors = {

package/lib/location.js

@@ -0,0 +1,19 @@
+const { INERTIA, LOCATION } = require('./helpers/inertia-headers')
+
+module.exports = function (req, res, url) {
+  // If this is an Inertia request, send a 409 Conflict response
+  // with the X-Inertia-Location header so the client performs a full window.location visit.
+  if (req.get(INERTIA)) {
+    res.set(LOCATION, url)
+    return res.status(409).end()
+  }
+
+  // For non-Inertia requests:
+  // If the method is PUT, PATCH, or DELETE, force a 303 redirect (so the next request is a GET)
+  if (['PUT', 'PATCH', 'DELETE'].includes(req.method)) {
+    return res.redirect(303, url)
+  }
+
+  // Otherwise, perform a standard redirect (default is typically a 302)
+  return res.redirect(url)
+}

package/{private → lib/middleware}/inertia-middleware.js

@@ -1,6 +1,6 @@
-const isInertiaRequest = require('./is-inertia-request')
+const isInertiaRequest = require('../helpers/is-inertia-request')
 
-const resolveValidationErrors = require('./resolve-validation-errors')
+const resolveValidationErrors = require('../helpers/resolve-validation-errors')
 function inertia(hook) {
   return function inertiaMiddleware(req, res, next) {
     if (isInertiaRequest(req)) {

package/lib/props/always-prop.js

@@ -0,0 +1,8 @@
+const MergeableProp = require('./mergeable-prop')
+
+module.exports = class AlwaysProp extends MergeableProp {
+  constructor(callback) {
+    super()
+    this.callback = callback
+  }
+}

package/lib/props/defer-prop.js

@@ -0,0 +1,15 @@
+const ignoreFirstLoadSymbol = require('../helpers/ignore-first-load-symbol')
+const MergeableProp = require('./mergeable-prop')
+
+module.exports = class DeferProp extends MergeableProp {
+  constructor(callback, group) {
+    super()
+    this.callback = callback
+    this.group = group
+    this[ignoreFirstLoadSymbol] = true
+  }
+
+  getGroup() {
+    return this.group
+  }
+}

package/lib/props/merge-prop.js

@@ -0,0 +1,9 @@
+const MergeableProp = require('./mergeable-prop')
+
+module.exports = class MergeProp extends MergeableProp {
+  constructor(callback) {
+    super()
+    this.callback = callback
+    this.shouldMerge = true
+  }
+}

package/lib/props/mergeable-prop.js

@@ -0,0 +1,10 @@
+module.exports = class MergeableProp {
+  constructor() {
+    this.shouldMerge = false
+  }
+
+  merge() {
+    this.shouldMerge = true
+    return this
+  }
+}

package/lib/props/optional-prop.js

@@ -0,0 +1,8 @@
+const ignoreFirstLoadSymbol = require('../helpers/ignore-first-load-symbol')
+
+module.exports = class OptionalProp {
+  constructor(callback) {
+    this.callback = callback
+    this[ignoreFirstLoadSymbol] = true
+  }
+}

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

@@ -0,0 +1,34 @@
+const isInertiaPartialRequest = require('../helpers/is-inertia-partial-request')
+const ignoreFirstLoadSymbol = require('../helpers/ignore-first-load-symbol')
+const { PARTIAL_DATA, PARTIAL_EXCEPT } = require('../helpers/inertia-headers')
+const resolveOnlyProps = require('./resolve-only-props')
+const resolveExceptProps = require('./resolve-except-props')
+const AlwaysProp = require('./always-prop')
+
+module.exports = function pickPropsToResolve(req, component, props = {}) {
+  const isPartial = isInertiaPartialRequest(req, component)
+  let newProps = props
+
+  if (!isPartial) {
+    newProps = Object.fromEntries(
+      Object.entries(props).filter(([_, value]) => {
+        if (value && value[ignoreFirstLoadSymbol]) return false
+        return true
+      })
+    )
+  }
+
+  if (isPartial && req.get(PARTIAL_DATA)) {
+    newProps = resolveOnlyProps(req, newProps)
+  }
+
+  if (isPartial && req.get(PARTIAL_EXCEPT)) {
+    newProps = resolveExceptProps(req, newProps)
+  }
+
+  for (const [key, value] of Object.entries(props)) {
+    if (value instanceof AlwaysProp) newProps[key] = props[key]
+  }
+
+  return newProps
+}

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

@@ -0,0 +1,15 @@
+const isInertiaPartialRequest = require('../helpers/is-inertia-partial-request')
+const DeferProp = require('./defer-prop')
+module.exports = function resolveDeferredProps(req, component, pageProps) {
+  if (isInertiaPartialRequest(req, component)) return {}
+  const deferredProps = Object.entries(pageProps || {})
+    .filter(([_, value]) => value instanceof DeferProp)
+    .map(([key, value]) => ({ key, group: value.getGroup() }))
+    .reduce((groups, { key, group }) => {
+      if (!groups[group]) groups[group] = []
+      groups[group].push(key)
+      return groups
+    }, {})
+
+  return Object.keys(deferredProps).length ? { deferredProps } : {}
+}

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

@@ -0,0 +1,9 @@
+const { PARTIAL_EXCEPT } = require('../helpers/inertia-headers')
+module.exports = function resolveExceptProps(req, props) {
+  const partialExceptHeader = req.get(PARTIAL_EXCEPT)
+  const except = partialExceptHeader.split(',').filter(Boolean)
+
+  for (const key of except) delete props[key]
+
+  return props
+}

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

@@ -0,0 +1,13 @@
+const { RESET } = require('../helpers/inertia-headers')
+const MergeableProp = require('./mergeable-prop')
+module.exports = function resolveMergeProps(req, pageProps) {
+  const inertiaResetHeader = req.get(RESET)
+  const resetProps = new Set(inertiaResetHeader?.split(',').filter(Boolean))
+
+  const mergeProps = Object.entries(pageProps || {})
+    .filter(([_, value]) => value instanceof MergeableProp && value.shouldMerge)
+    .map(([key]) => key)
+    .filter((key) => !resetProps.has(key))
+
+  return mergeProps.length ? { mergeProps } : {}
+}

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

@@ -0,0 +1,21 @@
+const { PARTIAL_DATA } = require('../helpers/inertia-headers')
+/**
+ * Extracts only the props specified by the partial header from the given props object.
+ *
+ * This function reads the header defined by the PARTIAL_DATA constant from the request,
+ * 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.
+ */
+module.exports = function resolveOnlyProps(req, props) {
+  const partialOnlyHeader = req.get(PARTIAL_DATA)
+  const only = partialOnlyHeader.split(',').filter(Boolean)
+  let newProps = {}
+
+  for (const key of only) newProps[key] = props[key]
+
+  return newProps
+}

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

@@ -0,0 +1,24 @@
+const resolveProp = require('./resolve-prop')
+/**
+ * Resolve all page props.
+ *
+ * This function iterates over each property in the given object.
+ * If a property is a function, it is invoked with the provided context.
+ * 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.
+ */
+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)
+}

package/lib/props/resolve-prop.js

@@ -0,0 +1,27 @@
+const OptionalProp = require('./optional-prop')
+const MergeProp = require('./merge-prop')
+const DeferProp = require('./defer-prop')
+const AlwaysProp = require('./always-prop')
+/**
+ * Resolve a single prop.
+ *
+ * If the value is an instance of one of our special prop types,
+ * we assume it has a "callback" property that should be executed
+ * to retrieve the final value.
+ *
+ * @param {string} key - The key for the prop.
+ * @param {any} value - The value to resolve.
+ * @returns {Promise<[string, any]>} A promise that resolves to a key-value pair.
+ */
+module.exports = async function resolveProp(key, value) {
+  if (
+    value instanceof OptionalProp ||
+    value instanceof MergeProp ||
+    value instanceof DeferProp ||
+    value instanceof AlwaysProp
+  ) {
+    return [key, await value.callback()]
+  }
+
+  return [key, value]
+}

package/lib/render.js

@@ -0,0 +1,35 @@
+const { encode } = require('querystring')
+const inertiaHeaders = require('./helpers/inertia-headers')
+const buildPageObject = require('./helpers/build-page-object')
+
+module.exports = async function render(req, res, data) {
+  const sails = req._sails
+
+  const sharedViewData = sails.inertia.sharedViewData
+  const rootView = sails.config.inertia.rootView
+
+  const allViewData = {
+    ...sharedViewData,
+    ...data.viewData
+  }
+
+  let page = await buildPageObject(req, data.page, data.props)
+
+  const queryParams = req.query
+  if (req.method === 'GET' && Object.keys(queryParams).length) {
+    // Keep original request query params
+    page.url += `?${encode(queryParams)}`
+  }
+
+  if (req.get(inertiaHeaders.INERTIA)) {
+    res.set(inertiaHeaders.INERTIA, true)
+    res.set('Vary', 'Accept')
+    return res.json(page)
+  } else {
+    // Implements full page reload
+    return res.view(rootView, {
+      page,
+      viewData: allViewData
+    })
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "inertia-sails",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "The Sails adapter for Inertia.",
   "main": "index.js",
   "sails": {
@@ -8,13 +8,12 @@
     "hookName": "inertia"
   },
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1",
-    "prepare": "cd .. && husky install"
+    "test": "echo \"Error: no test specified\" && exit 1"
   },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/sailscastshq/boring-stack.git",
-    "directory": "inertia-sails"
+    "directory": "packages/inertia-sails"
   },
   "peerDependencies": {
     "sails": ">=1",
@@ -29,5 +28,6 @@
   "bugs": {
     "url": "https://github.com/sailscastshq/boring-stack/issues"
   },
-  "homepage": "https://github.com/sailscastshq/boring-stack/inertia-sails#readme"
+  "homepage": "https://github.com/sailscastshq/boring-stack/tree/main/inertia-sails#readme",
+  "devDependencies": {}
 }