@teleporthq/teleport-plugin-next-data-source 0.44.0 → 0.44.4

package/src/sort-utils.ts

@@ -1,6 +1,11 @@
 import * as types from '@babel/types'
 import { ASTUtils } from '@teleporthq/teleport-plugin-common'
-import { UIDLExpressionValue, UIDLStaticValue } from '@teleporthq/teleport-types'
+import { JSIdentifiers } from '@teleporthq/teleport-shared'
+import {
+  UIDLExpressionValue,
+  UIDLStateDefinition,
+  UIDLStaticValue,
+} from '@teleporthq/teleport-types'
 
 export interface DynamicSortAST {
   field: types.Expression
@@ -18,22 +23,26 @@ const SKIP_IDENTIFIERS = new Set([
   'console',
 ])
 
-const collectIdentifiers = (node: types.Node | null | undefined, acc: Set<string>): void => {
+const collectIdentifiers = (
+  node: types.Node | null | undefined,
+  acc: Set<string>,
+  skip: ReadonlySet<string> = SKIP_IDENTIFIERS
+): void => {
   if (!node || typeof node !== 'object') {
     return
   }
 
   if (node.type === 'Identifier') {
-    if (!SKIP_IDENTIFIERS.has(node.name)) {
+    if (!skip.has(node.name)) {
       acc.add(node.name)
     }
     return
   }
 
   if (node.type === 'MemberExpression') {
-    collectIdentifiers(node.object, acc)
+    collectIdentifiers(node.object, acc, skip)
     if (node.computed) {
-      collectIdentifiers(node.property, acc)
+      collectIdentifiers(node.property, acc, skip)
     }
     return
   }
@@ -43,9 +52,9 @@ const collectIdentifiers = (node: types.Node | null | undefined, acc: Set<string
     // tslint:disable-next-line:no-any
     const child = (node as any)[key]
     if (Array.isArray(child)) {
-      child.forEach((c) => collectIdentifiers(c, acc))
+      child.forEach((c) => collectIdentifiers(c, acc, skip))
     } else if (child && typeof child === 'object' && typeof child.type === 'string') {
-      collectIdentifiers(child, acc)
+      collectIdentifiers(child, acc, skip)
     }
   }
 }
@@ -111,24 +120,158 @@ export const extractDynamicSort = (
   }
 }
 
-// Build the AST for `sorts: JSON.stringify([{ field: <fieldExpr>, order: <orderExpr> }])`
-const buildDynamicSortsProperty = (dynamicSort: DynamicSortAST): types.ObjectProperty => {
-  return types.objectProperty(
-    types.identifier('sorts'),
-    types.callExpression(
-      types.memberExpression(types.identifier('JSON'), types.identifier('stringify')),
-      [
-        types.arrayExpression([
-          types.objectExpression([
-            types.objectProperty(types.identifier('field'), types.cloneNode(dynamicSort.field)),
-            types.objectProperty(types.identifier('order'), types.cloneNode(dynamicSort.order)),
-          ]),
+// `JSON.stringify([{ field: <fieldExpr>, order: <orderExpr> }])`
+const buildDynamicSortsValue = (dynamicSort: DynamicSortAST): types.CallExpression =>
+  types.callExpression(
+    types.memberExpression(types.identifier('JSON'), types.identifier('stringify')),
+    [
+      types.arrayExpression([
+        types.objectExpression([
+          types.objectProperty(types.identifier('field'), types.cloneNode(dynamicSort.field, true)),
+          types.objectProperty(types.identifier('order'), types.cloneNode(dynamicSort.order, true)),
         ]),
-      ]
-    )
+      ]),
+    ]
   )
+
+// Build the AST for `sorts: JSON.stringify([{ field: <fieldExpr>, order: <orderExpr> }])`
+const buildDynamicSortsProperty = (dynamicSort: DynamicSortAST): types.ObjectProperty =>
+  types.objectProperty(types.identifier('sorts'), buildDynamicSortsValue(dynamicSort))
+
+/**
+ * A page state a state-bound sort reads, at the value the visitor starts with.
+ */
+export interface SortStateDefault {
+  /** The state's binding in the component: the name the sort expressions read. */
+  binding: string
+  value: string | number | boolean
 }
 
+// Names a sort expression may read besides its states: they mean the same on
+// the server and in the browser.
+const CONSTANT_IDENTIFIERS: ReadonlySet<string> = new Set(['undefined', 'NaN', 'Infinity'])
+
+const isStartingValue = (value: unknown): value is SortStateDefault['value'] =>
+  typeof value === 'string' ||
+  typeof value === 'boolean' ||
+  (typeof value === 'number' && Number.isFinite(value))
+
+/**
+ * The states a state-bound sort reads, at their defaults: the sort a visitor
+ * starts with, which the build can fetch the first page by.
+ *
+ * Only when every name the column and the direction read is a state of this
+ * component starting at a fixed value. Anything else they read — a prop, the
+ * router, `window` — or a state the page seeds from its data leaves the build
+ * unable to know the starting sort: `undefined`, and the list fetches its first
+ * page in the browser. An empty list is a sort that reads nothing.
+ */
+export const readSortStateDefaults = (
+  dynamicSort: DynamicSortAST,
+  stateDefinitions: Record<string, UIDLStateDefinition> | undefined
+): SortStateDefault[] | undefined => {
+  const read = new Set<string>()
+  collectIdentifiers(dynamicSort.field, read, CONSTANT_IDENTIFIERS)
+  collectIdentifiers(dynamicSort.order, read, CONSTANT_IDENTIFIERS)
+
+  // A state's binding is its sanitised name, as the component declares it.
+  const stateByBinding = new Map<string, UIDLStateDefinition>()
+  Object.entries(stateDefinitions ?? {}).forEach(([key, definition]) => {
+    stateByBinding.set(JSIdentifiers.createSafeJSIdentifier(key), definition)
+  })
+
+  const defaults: SortStateDefault[] = []
+  for (const binding of Array.from(read)) {
+    const definition = stateByBinding.get(binding)
+    if (
+      !definition ||
+      definition.dataSourceBinding ||
+      definition.query ||
+      !isStartingValue(definition.defaultValue)
+    ) {
+      return undefined
+    }
+    defaults.push({ binding, value: definition.defaultValue })
+  }
+  return defaults
+}
+
+/**
+ * A list repeater's own sort, read the one way for every part of the plugin
+ * that fetches the list's rows — the build's fetch for a page and the
+ * browser's: a column the editor fixed (`fixed`), or one bound to state
+ * (`dynamic`) with, when the build can know them, the values a visitor starts
+ * with (`starting`, see `readSortStateDefaults`). Empty without a sort.
+ */
+export interface RepeaterSort {
+  fixed?: { field: string; order: 'asc' | 'desc' }
+  dynamic?: DynamicSortAST
+  starting?: SortStateDefault[]
+}
+
+export const readRepeaterSort = (
+  sort: UIDLStaticValue | UIDLExpressionValue | undefined,
+  sortDirection: UIDLStaticValue | UIDLExpressionValue | undefined,
+  stateDefinitions: Record<string, UIDLStateDefinition> | undefined
+): RepeaterSort => {
+  if (!sort) {
+    return {}
+  }
+  const fixed = readFixedSort(sort, sortDirection)
+  if (fixed) {
+    return { fixed }
+  }
+  const dynamic = extractDynamicSort(sort, sortDirection)
+  return dynamic ? { dynamic, starting: readSortStateDefaults(dynamic, stateDefinitions) } : {}
+}
+
+/**
+ * The `sorts` param of the build-time fetch: the browser's own expression,
+ * evaluated with every state it reads at its default —
+ *
+ *   ((sortBy) => JSON.stringify([{ field: sortBy.split("-")?.[0] || '', order: … }]))("name-asc")
+ *
+ * — so it is the very string the browser sends while the sort is untouched, and
+ * the data source orders the first page exactly as it orders every later one
+ * (the same columns, empty values last, the row's id breaking ties).
+ */
+export const buildStartingSortsValue = (
+  dynamicSort: DynamicSortAST,
+  defaults: SortStateDefault[]
+): types.Expression => {
+  const sorts = buildDynamicSortsValue(dynamicSort)
+  if (defaults.length === 0) {
+    return sorts
+  }
+  return types.callExpression(
+    types.arrowFunctionExpression(
+      defaults.map((state) => types.identifier(state.binding)),
+      sorts
+    ),
+    defaults.map((state) => types.valueToNode(state.value) as types.Expression)
+  )
+}
+
+/**
+ * `sortBy === "name-asc"`: the sort is still the one the visitor starts with,
+ * so the rows fetched at build time are its first page. `null` for a sort that
+ * reads nothing, which never moves.
+ */
+export const buildSortAtStartGuard = (defaults: SortStateDefault[]): types.Expression | null =>
+  defaults
+    .map(
+      (state): types.Expression =>
+        types.binaryExpression(
+          '===',
+          types.identifier(state.binding),
+          types.valueToNode(state.value) as types.Expression
+        )
+    )
+    .reduce<types.Expression | null>(
+      (all, guard) => (all ? types.logicalExpression('&&', all, guard) : guard),
+      null
+    )
+
 // Build the AST for the legacy static sorts array form.
 // tslint:disable-next-line:no-any
 const buildLegacySortsProperty = (sorts: any[]): types.ObjectProperty => {

package/src/utils.ts

@@ -7,6 +7,7 @@ import {
   UIDLDataSource,
   DataSourceType,
   ChunkType,
+  UIDLStateDefinition,
 } from '@teleporthq/teleport-types'
 import * as types from '@babel/types'
 import { ASTUtils } from '@teleporthq/teleport-plugin-common'
@@ -15,7 +16,7 @@ import { generateDataSourceFetcherWithCore } from './data-source-fetchers'
 import type { EntityTransformOptions } from './transformations'
 import { DATA_SOURCE_ISR_REVALIDATE_SECONDS } from './isr'
 import { buildServerLocaleParam, hasLocaleParam, buildClientLocaleParam } from './request-locale'
-import { readFixedSort } from './sort-utils'
+import { buildStartingSortsValue, readRepeaterSort, type RepeaterSort } from './sort-utils'
 
 const VALID_DATA_SOURCE_TYPES: DataSourceType[] = [
   'rest-api',
@@ -1180,16 +1181,16 @@ const isSortKeyed = (properties: types.ObjectProperty[]): boolean =>
       (property.key.type === 'Identifier' && property.key.name === 'sorts')
   )
 
-/** The fixed sort of the first list repeater inside a data-source node, if it has one. */
+/** The first list repeater inside a data-source node: the list its rows are fetched for. */
 // tslint:disable-next-line:no-any
-const findRepeaterFixedSort = (node: any): { field: string; order: 'asc' | 'desc' } | undefined => {
+const findListRepeater = (node: any): Record<string, any> | undefined => {
   // tslint:disable-next-line:no-any
-  const visit = (current: any): { field: string; order: 'asc' | 'desc' } | null | undefined => {
+  const visit = (current: any): Record<string, any> | undefined => {
     if (!current || typeof current !== 'object') {
       return undefined
     }
     if (current.type === 'cms-list-repeater') {
-      return readFixedSort(current.content?.sort, current.content?.sortDirection) ?? null
+      return current.content ?? {}
     }
     const content = current.content
     const children = [
@@ -1204,9 +1205,28 @@ const findRepeaterFixedSort = (node: any): { field: string; order: 'asc' | 'desc
     }
     return undefined
   }
-  return visit(node) ?? undefined
+  return visit(node)
 }
 
+/**
+ * The order a list's page fetch carries, in what tells it apart from another
+ * list's fetch with the same params (`claimParamsPropKey`): the column the
+ * editor fixed, or a sort the visitor picks at the values they start with.
+ */
+const prefetchOrderOf = (
+  // tslint:disable-next-line:no-any
+  repeater: Record<string, any> | undefined,
+  sort: RepeaterSort
+): unknown =>
+  sort.fixed ??
+  (sort.dynamic && sort.starting
+    ? {
+        sort: repeater?.sort,
+        sortDirection: repeater?.sortDirection ?? null,
+        starting: sort.starting,
+      }
+    : undefined)
+
 export const extractDataSourceIntoGetStaticProps = (
   node: UIDLDataSourceItemNode | UIDLDataSourceListNode,
   dataSources: Record<string, UIDLDataSource>,
@@ -1217,7 +1237,13 @@ export const extractDataSourceIntoGetStaticProps = (
   dependencies: Record<string, any>,
   dynamicRouteAttr?: string,
   folderPath?: string[],
-  transformOptions: EntityTransformOptions = {}
+  transformOptions: EntityTransformOptions = {},
+  // What the read hands the module after its params: `{ as: 'visitor' }` on
+  // every page but an admin page only trusted readers open (see
+  // `RouteUtils.pageDataReadArguments`).
+  readArguments: () => types.Expression[] = () => [],
+  // The page's states: a list sorted by one is fetched by the value it starts at.
+  stateDefinitions?: Record<string, UIDLStateDefinition>
 ): { success: boolean; chunk?: any } => {
   try {
     // Validate node content
@@ -1281,11 +1307,13 @@ export const extractDataSourceIntoGetStaticProps = (
     }
     // tslint:disable-next-line:no-any
     const nodeResource = (node.content as any).resource
+    const repeater = findListRepeater(node)
+    const repeaterSort = readRepeaterSort(repeater?.sort, repeater?.sortDirection, stateDefinitions)
     const propKey = claimParamsPropKey(
       componentChunk,
       resourcePropKey,
       nodeResource,
-      findRepeaterFixedSort(node)
+      prefetchOrderOf(repeater, repeaterSort)
     )
 
     // Find matching JSX nodes for this data source
@@ -1732,11 +1760,13 @@ export const extractDataSourceIntoGetStaticProps = (
       }
     })
 
-    // The sort the list's repeater fixed, when the resource names none — the
+    // The sort the list's repeater carries, when the resource names none — the
     // rows the page is pre-rendered with come in the order the list shows them
-    // (the browser keeps them: the provider skips its first fetch).
-    const repeaterSort = isSortKeyed(paramsProperties) ? undefined : findRepeaterFixedSort(node)
-    if (repeaterSort) {
+    // (the browser keeps them: the provider skips its first fetch). A sort the
+    // visitor picks is fetched as they start with it, by the browser's own sort
+    // expression (`buildStartingSortsValue`), and the list keeps the rows only
+    // while the sort stays there (`seedPlainListWhileSortStarts`).
+    if (!isSortKeyed(paramsProperties) && repeaterSort.fixed) {
       paramsProperties.push(
         types.objectProperty(
           types.stringLiteral('sorts'),
@@ -1747,11 +1777,11 @@ export const extractDataSourceIntoGetStaticProps = (
                 types.objectExpression([
                   types.objectProperty(
                     types.identifier('field'),
-                    types.stringLiteral(repeaterSort.field)
+                    types.stringLiteral(repeaterSort.fixed.field)
                   ),
                   types.objectProperty(
                     types.identifier('order'),
-                    types.stringLiteral(repeaterSort.order)
+                    types.stringLiteral(repeaterSort.fixed.order)
                   ),
                 ]),
               ]),
@@ -1759,6 +1789,13 @@ export const extractDataSourceIntoGetStaticProps = (
           )
         )
       )
+    } else if (!isSortKeyed(paramsProperties) && repeaterSort.dynamic && repeaterSort.starting) {
+      paramsProperties.push(
+        types.objectProperty(
+          types.stringLiteral('sorts'),
+          buildStartingSortsValue(repeaterSort.dynamic, repeaterSort.starting)
+        )
+      )
     }
 
     // getStaticProps runs once per language: the prefetch is for that language.
@@ -1768,7 +1805,7 @@ export const extractDataSourceIntoGetStaticProps = (
 
     const fetchCallExpression = types.callExpression(
       types.memberExpression(types.identifier(fetcherImportName), types.identifier('fetchData')),
-      [types.objectExpression(paramsProperties)]
+      [types.objectExpression(paramsProperties), ...readArguments()]
     )
 
     const safeFetchExpression = createSafeFetchExpression(fetchCallExpression, propKey)
@@ -1925,12 +1962,12 @@ const claimParamsPropKey = (
   componentChunk: ChunkDefinition,
   resourcePropKey: string,
   resource: { params?: Record<string, unknown> } | undefined,
-  // The list's own fixed sort rides on its prefetch too (see the params below).
-  repeaterSort?: { field: string; order: string }
+  // The list's own sort rides on its prefetch too (`prefetchOrderOf`).
+  prefetchOrder?: unknown
 ): string => {
   const meta = componentChunk.meta as { dataSourcePropKeyParams?: Record<string, string> }
   const claimed = meta.dataSourcePropKeyParams ?? (meta.dataSourcePropKeyParams = {})
-  const signature = JSON.stringify([resource?.params ?? {}, repeaterSort ?? null])
+  const signature = JSON.stringify([resource?.params ?? {}, prefetchOrder ?? null])
 
   let propKey = resourcePropKey
   for (let suffix = 2; claimed[propKey] !== undefined && claimed[propKey] !== signature; suffix++) {