feat: add scroll helper

Author: FlorianV85

factories/inertia_factory.ts

@@ -7,18 +7,18 @@
  * file that was distributed with this source code.
  */
 
-import { type Vite } from '@adonisjs/vite'
-import { type HttpContext } from '@adonisjs/core/http'
 import { HttpContextFactory } from '@adonisjs/core/factories/http'
+import { type HttpContext } from '@adonisjs/core/http'
+import { type Vite } from '@adonisjs/vite'
 
 import { defineConfig } from '../index.js'
-import { Inertia } from '../src/inertia.js'
 import { InertiaHeaders } from '../src/headers.js'
+import { Inertia } from '../src/inertia.js'
 import { ServerRenderer } from '../src/server_renderer.js'
 import {
   type AssetsVersion,
-  type InertiaConfig,
   type ComponentProps,
+  type InertiaConfig,
   type InertiaConfigInput,
 } from '../src/types.js'
 
@@ -95,6 +95,11 @@ export class InertiaFactory<Pages extends Record<string, ComponentProps>> {
     return this
   }
 
+  scrollIntent(intent: 'append' | 'prepend') {
+    this.#parameters.ctx.request.request.headers[InertiaHeaders.InfiniteScrollMergeIntent] = intent
+    return this
+  }
+
   /**
    * Removes the X-Inertia header from the request headers
    *

src/headers.ts

@@ -74,4 +74,10 @@ export const InertiaHeaders = {
    * Used to identify which component is being partially reloaded.
    */
   PartialComponent: 'x-inertia-partial-component',
+
+  /**
+   * Header sent to indicate how the incoming page of data should be combined with existing client-side data.
+   * Value is "append", "prepend", or absent on initial load.
+   */
+  InfiniteScrollMergeIntent: 'x-inertia-infinite-scroll-merge-intent',
 } as const

src/inertia.ts

@@ -10,32 +10,32 @@
 /// <reference types="@adonisjs/core/providers/app_provider" />
 /// <reference types="@adonisjs/core/providers/edge_provider" />
 
-import { createHash } from 'node:crypto'
-import { type Vite } from '@adonisjs/vite'
 import type { HttpContext } from '@adonisjs/core/http'
-
+import { type Vite } from '@adonisjs/vite'
+import { type AsyncOrSync } from '@poppinss/utils/types'
+import { createHash } from 'node:crypto'
+import debug from './debug.ts'
 import { InertiaHeaders } from './headers.js'
+import {
+  always,
+  buildPartialRequestProps,
+  buildStandardVisitProps,
+  deepMerge,
+  defer,
+  merge,
+  optional,
+  scroll,
+} from './props.ts'
 import { type ServerRenderer } from './server_renderer.js'
 import type {
-  PageProps,
-  PageObject,
   AsPageProps,
-  RequestInfo,
-  InertiaConfig,
   ComponentProps,
+  InertiaConfig,
+  PageObject,
+  PageProps,
+  RequestInfo,
   SharedProps,
 } from './types.js'
-import {
-  defer,
-  merge,
-  always,
-  optional,
-  deepMerge,
-  buildStandardVisitProps,
-  buildPartialRequestProps,
-} from './props.ts'
-import debug from './debug.ts'
-import { type AsyncOrSync } from '@poppinss/utils/types'
 
 /**
  * Main class used to interact with Inertia
@@ -146,6 +146,18 @@ export class Inertia<Pages> {
    */
   deepMerge = deepMerge
 
+  /**
+   * Wrap a paginated value for the infinite scroll
+   *
+   * @example
+   * ```js
+   * {
+   *   posts: inertia.scroll(() => PostTransformer.paginate(posts.all(), posts.getMeta()))
+   * }
+   * ```
+   */
+  scroll = scroll
+
   /**
    * Creates a new Inertia instance
    *
@@ -241,6 +253,7 @@ export class Inertia<Pages> {
       finalProps = { ...pageProps }
     }
 
+    let result
     if (requestInfo.partialComponent === component) {
       const only = requestInfo.onlyProps
       const except = requestInfo.exceptProps ?? []
@@ -254,11 +267,30 @@ export class Inertia<Pages> {
       debug('building props for a partial reload %O', requestInfo)
       debug('cherry picking props %s', cherryPickProps)
 
-      return buildPartialRequestProps(finalProps, cherryPickProps, this.ctx.containerResolver)
+      result = await buildPartialRequestProps(
+        finalProps,
+        cherryPickProps,
+        this.ctx.containerResolver
+      )
+    } else {
+      debug('building props for a standard visit %O', requestInfo)
+      result = await buildStandardVisitProps(finalProps, this.ctx.containerResolver)
+    }
+
+    const prependProps: string[] = []
+    const mergeProps: string[] = [...(result.mergeProps || [])]
+    const scrollProps = result.scrollProps ?? {}
+    for (const [key, propInfo] of Object.entries(scrollProps)) {
+      const scrolPropPath = `${key}.${propInfo.wrapper}`
+
+      if (requestInfo.scrollMergeIntent === 'prepend') {
+        prependProps.push(scrolPropPath)
+      } else if (requestInfo.scrollMergeIntent === 'append') {
+        mergeProps.push(scrolPropPath)
+      }
     }
 
-    debug('building props for a standard visit %O', requestInfo)
-    return buildStandardVisitProps(finalProps, this.ctx.containerResolver)
+    return { ...result, mergeProps, prependProps }
   }
 
   /**
@@ -350,6 +382,7 @@ export class Inertia<Pages> {
       exceptProps: this.ctx.request.header(InertiaHeaders.PartialExcept)?.split(','),
       resetProps: this.ctx.request.header(InertiaHeaders.Reset)?.split(','),
       errorBag: this.ctx.request.header(InertiaHeaders.ErrorBag),
+      scrollMergeIntent: this.ctx.request.header(InertiaHeaders.InfiniteScrollMergeIntent),
     }
 
     return this.#cachedRequestInfo
@@ -466,11 +499,8 @@ export class Inertia<Pages> {
       : never
   ): Promise<PageObject<Pages[Page]>> {
     const requestInfo = this.requestInfo()
-    const { props, mergeProps, deferredProps, deepMergeProps } = await this.#buildPageProps(
-      page,
-      requestInfo,
-      pageProps
-    )
+    const { props, mergeProps, deferredProps, deepMergeProps, prependProps, scrollProps } =
+      await this.#buildPageProps(page, requestInfo, pageProps)
 
     return {
       component: page,
@@ -482,6 +512,8 @@ export class Inertia<Pages> {
       deferredProps,
       mergeProps,
       deepMergeProps,
+      prependProps,
+      scrollProps,
     } satisfies PageObject<Pages[Page]>
   }
 

src/props.ts

@@ -11,17 +11,26 @@ import { BaseSerializer } from '@adonisjs/core/transformers'
 import { type AsyncOrSync } from '@adonisjs/core/types/common'
 import { type JSONDataTypes } from '@adonisjs/core/types/transformers'
 
-import { ALWAYS_PROP, DEEP_MERGE, DEFERRED_PROP, OPTIONAL_PROP, TO_BE_MERGED } from './symbols.ts'
+import { type ContainerResolver } from '@adonisjs/core/container'
+import {
+  ALWAYS_PROP,
+  DEEP_MERGE,
+  DEFERRED_PROP,
+  OPTIONAL_PROP,
+  SCROLL_PROP,
+  TO_BE_MERGED,
+} from './symbols.ts'
 import {
-  type DeferProp,
-  type PageProps,
   type AlwaysProp,
-  type OptionalProp,
-  type MergeableProp,
   type ComponentProps,
+  type DeferProp,
+  type MergeableProp,
+  type OptionalProp,
+  type PageProps,
+  type ScrollMetadata,
+  type ScrollProp,
   type UnPackedPageProps,
 } from './types.ts'
-import { type ContainerResolver } from '@adonisjs/core/container'
 
 class InertiaSerializer extends BaseSerializer {
   wrap: undefined = undefined
@@ -215,6 +224,39 @@ export function deepMerge<T extends UnPackedPageProps | DeferProp<UnPackedPagePr
   }
 }
 
+/**
+ * Wraps a paginated value for infinite scrolling.
+ *
+ * Pagination metadata is automatically extracted and emitted in scrollProps.
+ * Merge/prepend behavior is wired based on the X-Inertia-Infinite-Scroll-Merge-Intent
+ * request header: "append" adds propKey.data to mergeProps, "prepend" to prependProps,
+ * absent means initial load and no merge is declared.
+ *
+ * @example
+ * ```js
+ * { posts: inertia.scroll(() => PostTransformer.paginate(posts.all(), posts.getMeta())) }
+ * ```
+ *
+ * @example Custom page query parameter
+ * ```js
+ * {
+ *   users:  inertia.scroll(() => UserTransformer.paginate(users.all(), users.getMeta()), { pageName: 'usersPage' }),
+ *   orders: inertia.scroll(() => OrderTransformer.paginate(orders.all(), orders.getMeta()), { pageName: 'ordersPage' }),
+ * }
+ * ```
+ */
+export function scroll<T extends UnPackedPageProps>(
+  value: T | (() => AsyncOrSync<T>),
+  options: { pageName?: string; wrapper?: string } = {}
+): ScrollProp<T> {
+  return {
+    value,
+    pageName: options.pageName ?? 'page',
+    wrapper: options.wrapper ?? 'data',
+    [SCROLL_PROP]: true,
+  }
+}
+
 /**
  * Type guard that checks if a prop value is a deferred prop.
  *
@@ -315,6 +357,50 @@ export function isOptionalProp<T extends UnPackedPageProps>(
   return OPTIONAL_PROP in propValue
 }
 
+/**
+ * Type guard that checks if a prop value is a scroll prop.
+ *
+ * Scroll props contain the SCROLL_PROP symbol and wrap a paginated value
+ * for the infinite scroll.
+ *
+ * @param propValue - The object to check for scroll prop characteristics
+ * @returns True if the prop value is a scroll prop
+ *
+ * @example
+ * ```js
+ * const prop = scroll(() => PostTransformer.paginate(posts.all(), posts.getMeta()))
+ *
+ * if (isScrollProp(prop)) {
+ *   // prop is now typed as ScrollProp<T>
+ *   const result = await prop.compute()
+ * }
+ * ```
+ */
+export function isScrollProp<T extends UnPackedPageProps>(
+  propValue: Object
+): propValue is ScrollProp<T> {
+  return SCROLL_PROP in propValue
+}
+
+/**
+ * Extracts scroll metadata from a serialized paginator value.
+ * Reads from the "metadata" key produced by AdonisJS transformers
+ * rather than inspecting the raw paginator instance.
+ */
+function resolveScrollMetadata(serialized: any, pageName: string, wrapper: string): ScrollMetadata {
+  const meta = serialized?.metadata ?? {}
+  const currentPage: number | null = meta.currentPage ?? null
+  const lastPage: number | null = meta.lastPage ?? null
+  return {
+    pageName,
+    wrapper,
+    currentPage,
+    nextPage:
+      currentPage !== null && lastPage !== null && currentPage < lastPage ? currentPage + 1 : null,
+    previousPage: currentPage !== null && currentPage > 1 ? currentPage - 1 : null,
+  }
+}
+
 /**
  * Helper function to unpack prop values using the transformer serialize function.
  *
@@ -361,6 +447,7 @@ export async function buildStandardVisitProps(
   const deepMergeProps: string[] = []
   const newProps: ComponentProps = {}
   const deferredProps: { [group: string]: string[] } = {}
+  const scrollProps: { [key: string]: ScrollMetadata } = {}
   const unpackedValues: Array<{
     key: string
     value: UnPackedPageProps | (() => AsyncOrSync<UnPackedPageProps>)
@@ -393,6 +480,15 @@ export async function buildStandardVisitProps(
         continue
       }
 
+      /**
+       * Scroll props are serialized like standard props. The pageName is tracked
+       * so that scrollProps metadata can be derived after serialization.
+       */
+      if (isScrollProp(value)) {
+        unpackedValues.push({ key, value: value.value })
+        continue
+      }
+
       /**
        * Inform the client about the mergeable prop and use its
        * value
@@ -464,11 +560,18 @@ export async function buildStandardVisitProps(
     })
   )
 
+  for (const [key, value] of Object.entries(pageProps)) {
+    if (isObject(value) && isScrollProp(value)) {
+      scrollProps[key] = resolveScrollMetadata(newProps[key], value.pageName, value.wrapper)
+    }
+  }
+
   return {
     props: newProps,
     mergeProps,
     deepMergeProps,
     deferredProps,
+    scrollProps,
   }
 }
 
@@ -503,6 +606,7 @@ export async function buildPartialRequestProps(
 ) {
   const mergeProps: string[] = []
   const deepMergeProps: string[] = []
+  const scrollProps: { [key: string]: ScrollMetadata } = {}
   const newProps: ComponentProps = {}
   const unpackedValues: Array<{
     key: string
@@ -543,6 +647,14 @@ export async function buildPartialRequestProps(
         continue
       }
 
+      /**
+       * Unpack scroll prop value and track pageName for metadata derivation
+       */
+      if (isScrollProp(value)) {
+        unpackedValues.push({ key, value: value.value })
+        continue
+      }
+
       /**
        * Inform the client about the mergeable prop
        */
@@ -605,10 +717,17 @@ export async function buildPartialRequestProps(
     })
   )
 
+  for (const [key, value] of Object.entries(pageProps)) {
+    if (isObject(value) && isScrollProp(value)) {
+      scrollProps[key] = resolveScrollMetadata(newProps[key], value.pageName, value.wrapper)
+    }
+  }
+
   return {
     props: newProps,
     mergeProps,
     deepMergeProps,
     deferredProps: {},
+    scrollProps,
   }
 }