@teleporthq/teleport-plugin-next-data-source 0.43.55 → 0.43.57

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@teleporthq/teleport-plugin-next-data-source",
-  "version": "0.43.55",
+  "version": "0.43.57",
   "description": "A plugin for managing data sources for Next.js projects.",
   "author": "teleportHQ",
   "license": "MIT",
@@ -26,9 +26,9 @@
   "dependencies": {
     "@babel/parser": "^7.26.10",
     "@babel/types": "^7.5.5",
-    "@teleporthq/teleport-plugin-common": "^0.43.54",
-    "@teleporthq/teleport-shared": "^0.43.54",
-    "@teleporthq/teleport-types": "^0.43.54"
+    "@teleporthq/teleport-plugin-common": "^0.43.57",
+    "@teleporthq/teleport-shared": "^0.43.57",
+    "@teleporthq/teleport-types": "^0.43.57"
   },
-  "gitHead": "eedc7b3e2518265eb876f900e69bc9c9304a26ee"
+  "gitHead": "1aaae3dc987920579371e068d33d000e92cfc218"
 }

package/src/cache/ast.ts

@@ -0,0 +1,265 @@
+import * as types from '@babel/types'
+import { UIDLDependency } from '@teleporthq/teleport-types'
+import { ResolvedDataSourceCache } from './types'
+
+/** Identifiers the emitted page imports from `utils/tq-cache/client`. */
+export const CACHE_CLIENT_IMPORTS = [
+  'tqCacheKey',
+  'tqCacheGet',
+  'tqCacheSet',
+  'tqCacheSetVersion',
+  'tqMarkHydrated',
+  'tqCacheRevalidate',
+]
+
+/** Local identifiers used inside the generated `fetchData` body. */
+const KEY_VAR = '__tqKey'
+const HIT_VAR = '__tqHit'
+
+export const cachedValueVarFor = (index: number): string => `ds_${index}_cached`
+
+/**
+ * Registers the client runtime's named imports on the page.
+ *
+ * Each identifier is its own dependency entry because that is how the
+ * import-statements plugin keys them; they share one path, so they collapse
+ * into a single `import { … } from '…/utils/tq-cache/client'`.
+ */
+export const registerCacheClientImports = (
+  dependencies: Record<string, UIDLDependency>,
+  folderPath: string[] | undefined
+): void => {
+  const depth = (folderPath ? folderPath.length : 0) + 1
+  const path = `${'../'.repeat(depth)}utils/tq-cache/client`
+
+  CACHE_CLIENT_IMPORTS.forEach((identifier) => {
+    if (!dependencies[identifier]) {
+      dependencies[identifier] = {
+        type: 'local',
+        path,
+        meta: { namedImport: true },
+      }
+    }
+  })
+}
+
+/**
+ * `const __tqKey = tqCacheKey(params)` +
+ * `const __tqHit = tqCacheGet(SCOPE, __tqKey)` +
+ * `if (__tqHit !== undefined) return Promise.resolve(__tqHit)`
+ *
+ * The early return is what keeps a hit from ever touching the network — and,
+ * just as importantly, from raising the in-flight flag that would paint the
+ * loading slot. `loading-state` deliberately attaches its bookkeeping to the
+ * network chain BELOW this, never to the `Promise.resolve`.
+ */
+const buildCachePeekPreamble = (scope: string): types.Statement[] => [
+  types.variableDeclaration('const', [
+    types.variableDeclarator(
+      types.identifier(KEY_VAR),
+      types.callExpression(types.identifier('tqCacheKey'), [types.identifier('params')])
+    ),
+  ]),
+  types.variableDeclaration('const', [
+    types.variableDeclarator(
+      types.identifier(HIT_VAR),
+      types.callExpression(types.identifier('tqCacheGet'), [
+        types.stringLiteral(scope),
+        types.identifier(KEY_VAR),
+      ])
+    ),
+  ]),
+  types.ifStatement(
+    types.binaryExpression('!==', types.identifier(HIT_VAR), types.identifier('undefined')),
+    types.blockStatement([
+      types.returnStatement(
+        types.callExpression(
+          types.memberExpression(types.identifier('Promise'), types.identifier('resolve')),
+          [types.identifier(HIT_VAR)]
+        )
+      ),
+    ])
+  ),
+]
+
+/**
+ * The terminal `.then` of a cached fetch: record the version the server
+ * answered with (which purges the scope if it moved) and store the rows.
+ *
+ * `tqCacheSet` returns the value it was given, so the promise still resolves to
+ * exactly what the uncached chain resolved to — `response?.data`.
+ */
+export const buildCacheStoreThen = (
+  cache: ResolvedDataSourceCache
+): types.ArrowFunctionExpression => {
+  const responseData = types.optionalMemberExpression(
+    types.identifier('response'),
+    types.identifier('data'),
+    false,
+    true
+  )
+  const responseVersion = types.optionalMemberExpression(
+    types.identifier('response'),
+    types.identifier('version'),
+    false,
+    true
+  )
+
+  return types.arrowFunctionExpression(
+    [types.identifier('response')],
+    types.blockStatement([
+      types.expressionStatement(
+        types.callExpression(types.identifier('tqCacheSetVersion'), [
+          types.stringLiteral(cache.scope),
+          types.cloneNode(responseVersion, true),
+        ])
+      ),
+      types.returnStatement(
+        types.callExpression(types.identifier('tqCacheSet'), [
+          types.stringLiteral(cache.scope),
+          types.identifier(KEY_VAR),
+          responseData,
+          types.numericLiteral(cache.ttlSeconds),
+          types.cloneNode(responseVersion, true),
+        ])
+      ),
+    ])
+  )
+}
+
+/** Wraps a network chain in the peek preamble, producing the cached body. */
+export const buildCachedFetchBody = (
+  networkChain: types.Expression,
+  cache: ResolvedDataSourceCache
+): types.BlockStatement =>
+  types.blockStatement([
+    ...buildCachePeekPreamble(cache.scope),
+    types.returnStatement(networkChain),
+  ])
+
+/**
+ * Finds the `return <fetch(...)…>` statement inside a cached `fetchData` body.
+ *
+ * Shared with `loading-state` so both modules agree on what "the network chain"
+ * means: the body also contains an early `return Promise.resolve(hit)`, and
+ * attaching in-flight bookkeeping to THAT would flip the loading flag on every
+ * cache hit — the exact flash this feature exists to remove.
+ */
+export const findCachedFetchNetworkChain = (
+  body: types.BlockStatement
+): { statement: types.ReturnStatement; index: number } | undefined => {
+  for (let index = body.body.length - 1; index >= 0; index--) {
+    const statement = body.body[index]
+    if (statement.type !== 'ReturnStatement' || !statement.argument) {
+      continue
+    }
+    if (
+      statement.argument.type === 'CallExpression' &&
+      callChainStartsWithFetch(statement.argument)
+    ) {
+      return { statement, index }
+    }
+  }
+  return undefined
+}
+
+const callChainStartsWithFetch = (expression: types.Expression): boolean => {
+  let current: types.Expression = expression
+  while (current.type === 'CallExpression') {
+    const { callee } = current
+    if (callee.type === 'Identifier' && callee.name === 'fetch') {
+      return true
+    }
+    if (callee.type === 'MemberExpression') {
+      current = callee.object as types.Expression
+      continue
+    }
+    return false
+  }
+  return false
+}
+
+/**
+ * Hoists a cached provider's `params` into a component const and adds the
+ * synchronous cache peek beside it.
+ *
+ * The peek is what removes the loading flash on a page or search change: those
+ * change the provider's `key`, so it REMOUNTS with `data: undefined` and paints
+ * `renderLoading()` before any promise — even an already-resolved one — can
+ * resume. Feeding a hit into `initialData` makes the provider skip its first
+ * fetch entirely and paint the cached rows on the very first frame.
+ *
+ * `sticky` is set because this value is handed to a mounted provider: once it
+ * has been, TTL expiry must not flip it back to `undefined`, or the list would
+ * blank out without refetching (its `params` never changed).
+ *
+ * Reference identity comes from the runtime's own map, not from this `useMemo`
+ * — the memo only keeps the peek from re-running on unrelated renders.
+ */
+export const buildCachedParamsDeclarations = (params: {
+  index: number
+  paramsMemo: types.Expression
+  cache: ResolvedDataSourceCache
+}): {
+  declarations: types.Statement[]
+  paramsIdentifier: string
+  cachedIdentifier: string
+} => {
+  const paramsIdentifier = `ds_${params.index}_params`
+  const cachedIdentifier = cachedValueVarFor(params.index)
+
+  return {
+    paramsIdentifier,
+    cachedIdentifier,
+    declarations: [
+      types.variableDeclaration('const', [
+        types.variableDeclarator(types.identifier(paramsIdentifier), params.paramsMemo),
+      ]),
+      types.variableDeclaration('const', [
+        types.variableDeclarator(
+          types.identifier(cachedIdentifier),
+          types.callExpression(types.identifier('useMemo'), [
+            types.arrowFunctionExpression(
+              [],
+              types.callExpression(types.identifier('tqCacheGet'), [
+                types.stringLiteral(params.cache.scope),
+                types.callExpression(types.identifier('tqCacheKey'), [
+                  types.identifier(paramsIdentifier),
+                ]),
+                types.objectExpression([
+                  types.objectProperty(types.identifier('sticky'), types.booleanLiteral(true)),
+                ]),
+              ])
+            ),
+            types.arrayExpression([types.identifier(paramsIdentifier)]),
+          ])
+        ),
+      ]),
+    ],
+  }
+}
+
+/**
+ * `useEffect(() => { tqMarkHydrated(); tqCacheRevalidate([...]) }, [])`
+ *
+ * One effect per page, covering every scope on it in a single request. Flipping
+ * the hydration latch here rather than at import time is what keeps the first
+ * client render byte-identical to the server render.
+ */
+export const buildCacheHydrationEffect = (scopes: string[]): types.Statement =>
+  types.expressionStatement(
+    types.callExpression(types.identifier('useEffect'), [
+      types.arrowFunctionExpression(
+        [],
+        types.blockStatement([
+          types.expressionStatement(types.callExpression(types.identifier('tqMarkHydrated'), [])),
+          types.expressionStatement(
+            types.callExpression(types.identifier('tqCacheRevalidate'), [
+              types.arrayExpression(scopes.map((scope) => types.stringLiteral(scope))),
+            ])
+          ),
+        ])
+      ),
+      types.arrayExpression([]),
+    ])
+  )

package/src/cache/config.ts

@@ -0,0 +1,79 @@
+import { DataCache } from '@teleporthq/teleport-shared'
+import { UIDLDataCacheConfig } from '@teleporthq/teleport-types'
+import { DataSourceServerCacheOptions, ResolvedDataSourceCache } from './types'
+
+/**
+ * Reads the `cache` block off a `cms-list-repeater`.
+ *
+ * Returns `undefined` — meaning "emit exactly what this generator emitted
+ * before caching existed" — for anything that is off, incomplete, or caches
+ * into neither layer.
+ */
+export const resolveCacheFromRepeaterContent = (
+  cache: UIDLDataCacheConfig | undefined,
+  resourceDefinition: { dataSourceId?: string; tableName?: string } | undefined
+): ResolvedDataSourceCache | undefined => {
+  if (!cache || cache.enabled !== true) {
+    return undefined
+  }
+
+  const client = cache.client === true
+  const server = cache.server === true
+  if (!client && !server) {
+    return undefined
+  }
+
+  const scope =
+    cache.versionScope ||
+    (resourceDefinition?.dataSourceId && resourceDefinition?.tableName
+      ? DataCache.cacheScopeFor(resourceDefinition.dataSourceId, resourceDefinition.tableName)
+      : '')
+  if (!scope) {
+    return undefined
+  }
+
+  const ttlSeconds =
+    typeof cache.ttlSeconds === 'number' && cache.ttlSeconds > 0
+      ? Math.trunc(cache.ttlSeconds)
+      : DataCache.DEFAULT_CACHE_TTL_SECONDS
+
+  return {
+    scope,
+    ttlSeconds,
+    client,
+    server,
+    sMaxAge: typeof cache.cdnSMaxAge === 'number' && cache.cdnSMaxAge > 0 ? cache.cdnSMaxAge : 0,
+    staleWhileRevalidate:
+      typeof cache.cdnStaleWhileRevalidate === 'number' && cache.cdnStaleWhileRevalidate > 0
+        ? cache.cdnStaleWhileRevalidate
+        : undefined,
+  }
+}
+
+/**
+ * Folds several mappers' requests for the same generated file into one.
+ *
+ * Enabled if ANY mapper wants it, but with the SHORTEST requested TTL and the
+ * shortest shared-cache window — a mapper that asked for fresher data must
+ * never be made staler by a sibling that asked for less.
+ */
+export const mergeServerCacheOptions = (
+  entries: DataSourceServerCacheOptions[]
+): DataSourceServerCacheOptions | undefined => {
+  const enabled = entries.filter((entry) => entry.ttlSeconds > 0 || (entry.sMaxAge || 0) > 0)
+  if (!enabled.length) {
+    return undefined
+  }
+
+  const positive = (values: number[]) => values.filter((value) => value > 0)
+  const ttls = positive(enabled.map((entry) => entry.ttlSeconds))
+  const sMaxAges = positive(enabled.map((entry) => entry.sMaxAge || 0))
+  const swrs = positive(enabled.map((entry) => entry.staleWhileRevalidate || 0))
+
+  return {
+    scope: enabled[0].scope,
+    ttlSeconds: ttls.length ? Math.min(...ttls) : 0,
+    sMaxAge: sMaxAges.length ? Math.min(...sMaxAges) : 0,
+    staleWhileRevalidate: swrs.length ? Math.min(...swrs) : undefined,
+  }
+}

package/src/cache/types.ts

@@ -0,0 +1,31 @@
+/**
+ * A mapper's caching setup once the UIDL has been read and the defaults filled
+ * in. `client` and `server` are independent — both layers may run at once.
+ */
+export interface ResolvedDataSourceCache {
+  scope: string
+  ttlSeconds: number
+  client: boolean
+  server: boolean
+  /** `Cache-Control: s-maxage`. Zero unless a shared window was granted. */
+  sMaxAge: number
+  staleWhileRevalidate?: number
+}
+
+/**
+ * Cache configuration as it reaches the emitters.
+ *
+ * Resolved per generated data-source FILE, not per array mapper: the
+ * `utils/data-sources/<file>.js` module is shared by every mapper reading the
+ * same `(type, table, dataSourceId)` triple, so two mappers on two pages must
+ * agree on one server-side setup. See `mergeServerCacheOptions`.
+ */
+export interface DataSourceServerCacheOptions {
+  /** `<dataSourceId>:<tableName>` — the unit of invalidation. */
+  scope: string
+  /** In-process TTL, seconds. `0` disables the server cache. */
+  ttlSeconds: number
+  /** `Cache-Control: s-maxage`, seconds. `0` keeps the response private. */
+  sMaxAge?: number
+  staleWhileRevalidate?: number
+}

package/src/data-source-fetchers.ts

@@ -1,4 +1,4 @@
-import { DataSourceType, UIDLDataSource, UIDLEcommerceCategory } from '@teleporthq/teleport-types'
+import { DataSourceType, UIDLDataSource } from '@teleporthq/teleport-types'
 import {
   generatePostgreSQLFetcher,
   generateMySQLFetcher,
@@ -33,6 +33,9 @@ import {
 } from './fetchers'
 import { validateDatabaseConfig } from './validation'
 import { generateCountFetcher } from './count-fetchers'
+import type { EcommerceProductTransformOptions } from './transformations'
+import { DataCache } from '@teleporthq/teleport-shared'
+import type { DataSourceServerCacheOptions } from './cache/types'
 
 export { generateRawQueryFetcher, parseQueryTemplateVariables }
 
@@ -81,7 +84,7 @@ export const getDataSourceDependencies = (
 export function generateDataSourceFetcher(
   dataSource: UIDLDataSource,
   tableName: string,
-  categories?: UIDLEcommerceCategory[]
+  transformOptions: EcommerceProductTransformOptions = {}
 ): string {
   if (!dataSource || typeof dataSource !== 'object') {
     throw new Error('Invalid data source: data source must be a valid object')
@@ -237,7 +240,7 @@ export function generateDataSourceFetcher(
         if (!validation.isValid) {
           throw new Error(`Teleport config validation failed: ${validation.error}`)
         }
-        return generateTeleportFetcher(config, tableName, categories)
+        return generateTeleportFetcher(config, tableName, transformOptions)
       }
 
       default:
@@ -258,9 +261,10 @@ export function generateDataSourceFetcherWithCore(
   dataSource: UIDLDataSource,
   tableName: string,
   isApiRoute: boolean = false,
-  categories?: UIDLEcommerceCategory[]
+  transformOptions: EcommerceProductTransformOptions = {},
+  cacheOptions?: DataSourceServerCacheOptions
 ): string {
-  const apiHandler = generateDataSourceFetcher(dataSource, tableName, categories)
+  const apiHandler = generateDataSourceFetcher(dataSource, tableName, transformOptions)
 
   // Extract the handler function body from the API route
   // The API route is structured as: export default async function handler(req, res) { ... }
@@ -285,14 +289,64 @@ export function generateDataSourceFetcherWithCore(
   // Combine and deduplicate imports
   const allImports = Array.from(new Set([...imports, ...countImports]))
 
+  // Caching is applied HERE rather than in the API route because four separate
+  // places emit an `api/<file>` route and a fifth path (`getStaticProps` →
+  // `fetchData` → `handler`) never goes through a route at all. Wrapping the
+  // module's exports is the one point that covers all five, and leaves every
+  // route emitter untouched.
+  //
+  // The import depth differs by destination: this module is written to
+  // `utils/data-sources/` normally, but the `isApiRoute` variant is inlined
+  // straight into `pages/api/`.
+  const cachePreamble = cacheOptions
+    ? `import { tqWithCache } from '${isApiRoute ? '../../' : '../'}tq-cache/server'`
+    : ''
+
+  const cacheWiring = cacheOptions
+    ? `
+const __tqDataCache = ${JSON.stringify({
+        scope: cacheOptions.scope,
+        ttl: cacheOptions.ttlSeconds,
+        sMaxAge: cacheOptions.sMaxAge || 0,
+        swr: cacheOptions.staleWhileRevalidate || 0,
+      })}
+const __tqCountCache = ${JSON.stringify({
+        scope: DataCache.countScopeFor(cacheOptions.scope),
+        // Its OWN keyspace, but the DATA scope's version row. A write bumps one
+        // row; if the count kept a separate version nothing would ever bump it,
+        // and the total would stay stale after every create and delete — the
+        // grid showing one more row than the pager counts.
+        versionScope: cacheOptions.scope,
+        ttl: cacheOptions.ttlSeconds,
+        sMaxAge: cacheOptions.sMaxAge || 0,
+        swr: cacheOptions.staleWhileRevalidate || 0,
+      })}
+
+const cachedHandler = tqWithCache(handler, __tqDataCache)
+const cachedGetCount = tqWithCache(getCount, __tqCountCache)
+`
+    : ''
+
+  const handlerExport = cacheOptions ? 'cachedHandler' : 'handler'
+  const countExport = cacheOptions ? 'cachedGetCount' : 'getCount'
+
   // For API routes, export just the handler function
   // For utils files, export the full object with all functions
-  const exports = isApiRoute
-    ? 'export default handler'
-    : `export { fetchData, fetchCount, handler, getCount }
+  //
+  // The uncached branch is spelled out verbatim rather than interpolated, so an
+  // uncached project keeps generating byte-identical output — `handler as
+  // handler` would be harmless at runtime and still a diff in every snapshot.
+  const exports = !cacheOptions
+    ? isApiRoute
+      ? 'export default handler'
+      : `export { fetchData, fetchCount, handler, getCount }
 export default { fetchData, fetchCount, handler, getCount }`
+    : isApiRoute
+    ? `export default ${handlerExport}`
+    : `export { fetchData, fetchCount, ${handlerExport} as handler, ${countExport} as getCount }
+export default { fetchData, fetchCount, handler: ${handlerExport}, getCount: ${countExport} }`
 
-  return `${allImports.join('\n')}
+  return `${[...allImports, cachePreamble].filter(Boolean).join('\n')}
 
 async function fetchData(params = {}) {
   const req = {
@@ -314,7 +368,7 @@ async function fetchData(params = {}) {
     },
   }
   
-  await handler(req, res)
+  await ${handlerExport}(req, res)
   
   if (statusCode !== 200 || !result || !result.success) {
     throw new Error(result?.error || 'Failed to fetch data')
@@ -343,7 +397,7 @@ async function fetchCount(params = {}) {
     },
   }
   
-  await getCount(req, res)
+  await ${countExport}(req, res)
   
   if (statusCode !== 200 || !result || !result.success) {
     throw new Error(result?.error || 'Failed to get count')
@@ -355,7 +409,7 @@ async function fetchCount(params = {}) {
 ${countFetcherWithoutImports}
 
 ${handlerWithoutImports}
-
+${cacheWiring}
 ${exports}
 `
 }

package/src/fetchers/teleport.ts

@@ -1,4 +1,3 @@
-import type { UIDLEcommerceCategory } from '@teleporthq/teleport-types'
 import {
   replaceSecretReference,
   generateDateFormatterCode,
@@ -9,6 +8,7 @@ import {
   getTransformationCode,
   getTransformExpression,
   getTransformWrapperCode,
+  type EcommerceProductTransformOptions,
 } from '../transformations'
 
 interface TeleportDBConfig {
@@ -52,7 +52,7 @@ export const validateTeleportConfig = (
 export const generateTeleportFetcher = (
   config: Record<string, unknown>,
   tableName: string,
-  categories?: UIDLEcommerceCategory[]
+  transformOptions: EcommerceProductTransformOptions = {}
 ): string => {
   const dbConfig = config as TeleportDBConfig
   const schema = dbConfig.options?.schema
@@ -142,7 +142,7 @@ const getClient = () => {
 ${generateSafeJSONParseCode()}
 
 ${generateSearchEscapeHelpersCode()}
-${getTransformationCode(tableName, categories)}
+${getTransformationCode(tableName, transformOptions)}
 ${getTransformWrapperCode(tableName)}
 const processFilters = (filters, conditions, queryParams, paramIndex) => {
   if (!filters) return paramIndex

package/src/index.ts

@@ -14,6 +14,7 @@ import {
   hasUnresolvableDynamicParams,
 } from './utils'
 import { createNextArrayMapperPaginationPlugin } from './pagination-plugin'
+import { buildProductTransformOptions } from './transformations'
 import { DATA_SOURCE_ISR_REVALIDATE_SECONDS } from './isr'
 import * as types from '@babel/types'
 
@@ -608,7 +609,7 @@ export const createNextPagesDataSourcePlugin: ComponentPluginFactory<{}> = () =>
           dependencies,
           dynamicRouteAttr,
           uidl.outputOptions?.folderPath,
-          options.ecommerceSettings?.categories
+          buildProductTransformOptions(options)
         )
 
         if (result.success && result.chunk) {
@@ -646,7 +647,7 @@ export const createNextPagesDataSourcePlugin: ComponentPluginFactory<{}> = () =>
           dataSources,
           componentChunk,
           options.extractedResources,
-          options.ecommerceSettings?.categories
+          buildProductTransformOptions(options)
         )
       }
     })
@@ -1268,7 +1269,7 @@ export const createNextComponentDataSourcePlugin: ComponentPluginFactory<{}> = (
         dataSources,
         componentChunk,
         options.extractedResources,
-        options.ecommerceSettings?.categories
+        buildProductTransformOptions(options)
       )
     })
 
@@ -1354,7 +1355,7 @@ export const createNextComponentDataSourcePlugin: ComponentPluginFactory<{}> = (
               dataSource,
               firstDataSourceInfo.tableName,
               false,
-              options.ecommerceSettings?.categories
+              buildProductTransformOptions(options)
             )
             options.extractedResources[`utils/${fileName}`] = {
               fileName,
@@ -1398,3 +1399,8 @@ export * from './utils'
 export * from './array-mapper-pagination'
 export * from './pagination-plugin'
 export * from './count-fetchers'
+// The product transform's build-time options (category taxonomy + storefront
+// tax rate) — every package that emits a data-source fetcher has to derive
+// them the same way.
+export { buildProductTransformOptions } from './transformations'
+export type { EcommerceProductTransformOptions } from './transformations'