@teleporthq/teleport-plugin-next-data-source 0.43.66 → 0.43.68

package/src/product-filter-fields.ts

@@ -0,0 +1,173 @@
+/**
+ * Filtering a products list on things that are not a plain column.
+ *
+ * The storefront's product filters ask questions the `teleport_products` row
+ * cannot answer with a single column comparison: "what does it cost right now"
+ * (`price` net of a live markdown), "how many stars" (an aggregate over the
+ * reviews table), "is it on sale", and "does it come in size XL" (a value
+ * inside the `variant_options` JSON). Like the discount-aware sort in
+ * `product-price-sort.ts`, these have to be answered by the DATABASE — the list
+ * is paginated, so filtering the fetched page would only filter 20 of N rows.
+ *
+ * The editor emits such a filter as an ordinary condition whose `source` is
+ * one of the VIRTUAL field names below. Every SQL builder that can receive a
+ * products filter rewrites them into the expressions here:
+ *
+ *   - this file → the generated store's `teleport_products` API route
+ *     (`fetchers/teleport.ts`, `fetchers/postgresql.ts`);
+ *   - `database-provider-worker/src/lib/product-filter-fields.ts` → the editor
+ *     canvas. ⛔ A byte-for-byte mirror of the SQL below; both repos pin the
+ *     strings with a test, because a clause the canvas cannot build is an HTTP
+ *     500 the canvas draws as an EMPTY grid.
+ *
+ * ## The expressions cannot raise
+ *
+ * Same discipline as the sort: the JSON column is cast only when its text
+ * already looks like an array, the axis key is validated against a slug pattern
+ * before it is bound, and an unknown key filters to no rows instead of erroring
+ * — a filter that the database rejects would empty the whole products page.
+ */
+
+import {
+  PRODUCTS_TABLE_NAME,
+  PRODUCT_PRICE_SORT_FIELD,
+  buildProductEffectivePriceSql,
+  supportsProductPriceSort,
+} from './product-price-sort'
+
+/** The reviews table the star-rating aggregate reads. Exists once reviews were enabled. */
+export const PRODUCT_REVIEWS_TABLE_NAME = 'teleport_product_reviews'
+
+/** Virtual field: the product's star bucket — `ROUND(AVG(approved rating))`, 1..5, NULL when unreviewed. */
+export const PRODUCT_RATING_FILTER_FIELD = 'rating'
+
+/** Virtual field: `'true'` while a markdown is live, else `'false'`. */
+export const PRODUCT_ON_SALE_FILTER_FIELD = 'on_sale'
+
+/**
+ * Virtual field family: `variant_options.<axisKey>` — the product offers the
+ * axis (e.g. `size`) in one of the given values (e.g. `xl`).
+ */
+export const PRODUCT_VARIANT_AXIS_FILTER_PREFIX = 'variant_options.'
+
+/**
+ * What an axis key may look like. Keys are produced by the editor's slug
+ * helper (`deriveOptionKey`), so this is what every real key matches; anything
+ * else is refused before it can reach the database.
+ */
+export const PRODUCT_VARIANT_AXIS_KEY_PATTERN = '^[a-z0-9][a-z0-9_-]{0,63}$'
+
+/** Generic multi-value operand: the column equals ANY of the destination values. */
+export const IN_OPERAND = 'in'
+
+/**
+ * `ROUND(AVG(rating))` over the product's APPROVED reviews. Only approved rows
+ * count — moderation is the merchant's veto — and the outer row is the
+ * unaliased `teleport_products` the fetchers select from.
+ */
+export const buildProductRatingBucketSql = (): string =>
+  `(SELECT ROUND(AVG(r.rating)) FROM ${PRODUCT_REVIEWS_TABLE_NAME} r WHERE r.product_id = ${PRODUCTS_TABLE_NAME}.id AND r.status = 'approved' AND r.rating IS NOT NULL)`
+
+/** `'true'` when the price paid today is below the list price, i.e. a markdown is live. */
+export const buildProductOnSaleSql = (): string =>
+  `(CASE WHEN ${buildProductEffectivePriceSql()} < "price"::numeric THEN 'true' ELSE 'false' END)`
+
+/**
+ * Only text that already looks like a JSON array is cast; NULL, empty or a
+ * hand-edited scalar reads as "no variant axes".
+ */
+export const SAFE_VARIANT_OPTIONS_JSONB = `CASE
+        WHEN "variant_options" IS NULL OR btrim("variant_options") NOT LIKE '[%' THEN '[]'::jsonb
+        ELSE "variant_options"::jsonb
+      END`
+
+/**
+ * True when the product declares the axis bound to `keyParam` with at least one
+ * of the values bound to `valuesParam` (a `text[]`). Both are PARAMETERS, never
+ * interpolated text.
+ */
+export const buildProductVariantAxisExistsSql = (keyParam: string, valuesParam: string): string =>
+  `EXISTS (SELECT 1 FROM jsonb_array_elements(${SAFE_VARIANT_OPTIONS_JSONB}) AS ax, jsonb_array_elements(CASE WHEN jsonb_typeof(ax->'values') = 'array' THEN ax->'values' ELSE '[]'::jsonb END) AS v WHERE ax->>'key' = ${keyParam} AND v->>'value' = ANY(${valuesParam}::text[]))`
+
+/**
+ * The complete `productFilterClause(field, operand, value, pushParam)` helper a
+ * SQL fetcher embeds in its generated route.
+ *
+ * Returns a finished WHERE clause for a virtual (or rewritten) products field,
+ * or `null` for anything else so the fetcher's ordinary branches run. `pushParam`
+ * binds a value and answers its `$n` placeholder. By the time it is called an
+ * `in` filter has been normalised to `=` with an ARRAY value (see
+ * `normalizeInOperand` in `utils.ts`), which reads as "any of". A virtual field
+ * never answers `null` once matched — an operand it cannot express filters to
+ * no rows rather than falling into a branch that would name a column the table
+ * does not have.
+ *
+ * Emitted through `JSON.stringify` and string concatenation only — no backtick
+ * and no `${` may appear in the output, which is interpolated into a fetcher's
+ * template literal. On a table that is not the products table the helper still
+ * exists and always answers `null`, so a fetcher can embed it unconditionally.
+ */
+export const generateProductFilterClauseHelper = (tableName: string): string => {
+  if (!supportsProductPriceSort(tableName)) {
+    return [
+      '// Virtual products-table filter fields. This table has none, so every',
+      "// condition takes the fetcher's ordinary branches.",
+      'function productFilterClause() {',
+      '  return null',
+      '}',
+    ].join('\n')
+  }
+
+  const lines = [
+    "// Rewrites the products table's virtual filter fields - the price paid",
+    '// today, the star-rating bucket, the on-sale flag and a variant axis - into',
+    '// SQL. Answers null for a plain column so the ordinary branches run. An',
+    '// "in" filter arrives here already normalised to "=" with an ARRAY value.',
+    'function productFilterClause(field, operand, value, pushParam) {',
+    "  var scalarOps = ['=', '!=', '>', '<', '>=', '<=']",
+    "  var equalityOps = ['=', '!=']",
+    '  var compare = function (expression, allowedOps, virtual) {',
+    '    if (Array.isArray(value)) {',
+    "      if (operand === '=') {",
+    "        return expression + '::text = ANY(' + pushParam(value.map(String)) + '::text[])'",
+    '      }',
+    "      if (operand === '!=') {",
+    "        return expression + '::text <> ALL(' + pushParam(value.map(String)) + '::text[])'",
+    '      }',
+    "      return virtual ? 'FALSE' : null",
+    '    }',
+    "    if (allowedOps.indexOf(operand) === -1) return virtual ? 'FALSE' : null",
+    "    return expression + ' ' + operand + ' ' + pushParam(value)",
+    '  }',
+    `  if (field === ${JSON.stringify(PRODUCT_PRICE_SORT_FIELD)}) {`,
+    `    return compare(${JSON.stringify(
+      '(' + buildProductEffectivePriceSql() + ')'
+    )}, scalarOps, false)`,
+    '  }',
+    `  if (field === ${JSON.stringify(PRODUCT_RATING_FILTER_FIELD)}) {`,
+    `    return compare(${JSON.stringify(buildProductRatingBucketSql())}, scalarOps, true)`,
+    '  }',
+    `  if (field === ${JSON.stringify(PRODUCT_ON_SALE_FILTER_FIELD)}) {`,
+    `    return compare(${JSON.stringify(buildProductOnSaleSql())}, equalityOps, true)`,
+    '  }',
+    `  if (field.indexOf(${JSON.stringify(PRODUCT_VARIANT_AXIS_FILTER_PREFIX)}) === 0) {`,
+    `    var axisKey = field.slice(${PRODUCT_VARIANT_AXIS_FILTER_PREFIX.length})`,
+    `    if (!new RegExp(${JSON.stringify(PRODUCT_VARIANT_AXIS_KEY_PATTERN)}).test(axisKey)) {`,
+    '      // Not a key the editor could have written: no rows, never an error.',
+    "      return 'FALSE'",
+    '    }',
+    "    if (operand !== '=') return 'FALSE'",
+    '    var values = (Array.isArray(value) ? value : [value]).map(String)',
+    '    var keyParam = pushParam(axisKey)',
+    '    var valuesParam = pushParam(values)',
+    `    return ${JSON.stringify(buildProductVariantAxisExistsSql('__KEY__', '__VALUES__'))}`,
+    // Function replacements: a "$1" inside a replacement STRING is a special
+    // pattern, so the placeholders are swapped by callback.
+    "      .replace('__KEY__', function () { return keyParam })",
+    "      .replace('__VALUES__', function () { return valuesParam })",
+    '  }',
+    '  return null',
+    '}',
+  ]
+  return lines.join('\n')
+}

package/src/request-locale.ts

@@ -0,0 +1,113 @@
+import * as types from '@babel/types'
+import type { UIDLDependency } from '@teleporthq/teleport-types'
+
+/**
+ * How a generated data-source fetch says which language it is for.
+ *
+ * A multi-language project stores a translatable column once per language
+ * (`name`, `es_name`, …) and the generated fetcher resolves each row against
+ * ONE of them (see `transformations/` and `localized-columns.ts`). Nothing
+ * about the API route knows the page it serves — an API route has no locale
+ * segment in its URL — so the page tells it, through this query parameter:
+ *
+ *   - a client-side fetch (`DataProvider` `params`) sends `router.locale`;
+ *   - a build-time fetch inside `getStaticProps` sends `context.locale`.
+ *
+ * Both are what Next.js resolved from the `/es/...` route, so the rows a page
+ * renders are in the language the page is in. The same name the details-page
+ * fetch (`teleport-plugin-next-static-props`) has always sent.
+ */
+export const REQUEST_LOCALE_PARAM = 'locale'
+
+/** The dependency behind the `router` every client-side locale read closes over. */
+const USE_ROUTER_DEPENDENCY: UIDLDependency = {
+  type: 'library',
+  path: 'next/router',
+  version: '^12.1.10',
+  meta: { namedImport: true },
+}
+
+/**
+ * `router?.locale` — the client's current locale. Optional-chained like every
+ * other generated `router` read: `useRouter()` answers `null` during a static
+ * export's first paint.
+ */
+export const buildClientLocaleExpression = (): types.Expression =>
+  types.optionalMemberExpression(
+    types.identifier('router'),
+    types.identifier('locale'),
+    false,
+    true
+  )
+
+/** `locale: router?.locale` — the param of a client-side fetch. */
+export const buildClientLocaleParam = (): types.ObjectProperty =>
+  types.objectProperty(types.identifier(REQUEST_LOCALE_PARAM), buildClientLocaleExpression())
+
+/** `locale: context.locale` — the param of a fetch inside getStaticProps. */
+export const buildServerLocaleParam = (): types.ObjectProperty =>
+  types.objectProperty(
+    types.identifier(REQUEST_LOCALE_PARAM),
+    types.memberExpression(types.identifier('context'), types.identifier('locale'))
+  )
+
+/** Whether an object literal already carries the locale param. */
+export const hasLocaleParam = (properties: types.ObjectExpression['properties']): boolean =>
+  properties.some(
+    (property) =>
+      property.type === 'ObjectProperty' &&
+      ((property.key.type === 'Identifier' && property.key.name === REQUEST_LOCALE_PARAM) ||
+        (property.key.type === 'StringLiteral' && property.key.value === REQUEST_LOCALE_PARAM))
+  )
+
+/**
+ * Adds the client locale to a fetch's params, once, and to the `useMemo` deps
+ * that must rebuild them: a locale switch is a client-side transition on the
+ * SAME page instance, so only a dependency change refetches the rows in the
+ * new language.
+ */
+export const appendClientLocaleParam = (
+  paramsProps: types.ObjectExpression['properties'],
+  memoDeps: types.Expression[]
+): void => {
+  if (!hasLocaleParam(paramsProps)) {
+    paramsProps.push(buildClientLocaleParam())
+  }
+  memoDeps.push(buildClientLocaleExpression())
+}
+
+/** Any declaration of `router` — a second one, however it is initialised, is a syntax error. */
+const declaresRouter = (statement: types.Statement): boolean =>
+  statement.type === 'VariableDeclaration' &&
+  statement.declarations.some(
+    (declaration) => declaration.id.type === 'Identifier' && declaration.id.name === 'router'
+  )
+
+/**
+ * Puts `const router = useRouter()` (and its import) in scope, once.
+ *
+ * Idempotent with every sibling plugin that declares the same hook — the i18n
+ * locale mapper, the URL search-params plugin and the base component plugin
+ * all guard on the same identifier, so whichever runs first wins and the rest
+ * find it in place. Unshifted to the top of the body: nothing reads it before
+ * an effect runs, and hooks must not sit below a conditional return.
+ */
+export const ensureRouterDeclaration = (
+  body: types.Statement[],
+  dependencies: Record<string, UIDLDependency>
+): void => {
+  if (!dependencies.useRouter) {
+    dependencies.useRouter = { ...USE_ROUTER_DEPENDENCY }
+  }
+  if (body.some(declaresRouter)) {
+    return
+  }
+  body.unshift(
+    types.variableDeclaration('const', [
+      types.variableDeclarator(
+        types.identifier('router'),
+        types.callExpression(types.identifier('useRouter'), [])
+      ),
+    ])
+  )
+}

package/src/search-clear.ts

@@ -0,0 +1,102 @@
+import * as types from '@babel/types'
+import { setJSXExpressionAttribute } from './pagination-controls'
+
+/**
+ * The "clear search" button a listing's search field carries — marked
+ * `data-tq-search-clear` by the editor (`listing-search-field.ts`), the same
+ * marker the canvas renderer acts on. The search keyword is the mapper's own
+ * React state, which no authored workflow can reach, so the generator wires
+ * the button here: a click empties the query, and the button renders only
+ * while the query is non-empty.
+ *
+ * A button belongs to the search input it shares a parent with — the field
+ * wrapper — never to "the next search-enabled mapper": a page with two lists
+ * and one clear button would otherwise wire it to the wrong list.
+ */
+
+export const SEARCH_CLEAR_ATTR = 'data-tq-search-clear'
+
+// tslint:disable:no-any
+
+export interface SearchClearButton {
+  node: any
+  parent: any
+  index: number
+}
+
+function hasSearchClearMarker(node: any): boolean {
+  return !!node?.openingElement?.attributes?.some(
+    (attr: any) => attr.type === 'JSXAttribute' && attr.name?.name === SEARCH_CLEAR_ATTR
+  )
+}
+
+/** Every marked button under `root`, with the JSX parent and child index it sits at. */
+export function findAllSearchClearButtonsInJSX(root: any): SearchClearButton[] {
+  const results: SearchClearButton[] = []
+  const traverse = (node: any): void => {
+    if (!node) {
+      return
+    }
+    if (node.type === 'JSXElement' && Array.isArray(node.children)) {
+      node.children.forEach((child: any, index: number) => {
+        if (child?.type === 'JSXElement' && hasSearchClearMarker(child)) {
+          results.push({ node: child, parent: node, index })
+        }
+        traverse(child)
+      })
+      return
+    }
+    if (node.body) {
+      if (Array.isArray(node.body)) {
+        node.body.forEach((statement: any) => traverse(statement))
+      } else {
+        traverse(node.body)
+      }
+    }
+    if (node.consequent) {
+      traverse(node.consequent)
+    }
+    if (node.alternate) {
+      traverse(node.alternate)
+    }
+    if (node.expression) {
+      traverse(node.expression)
+    }
+    if (node.argument) {
+      traverse(node.argument)
+    }
+  }
+  traverse(root)
+  return results
+}
+
+/** The search input the button shares its parent with, or null. */
+export function findSiblingSearchInput(button: SearchClearButton, searchInputs: any[]): any | null {
+  const siblings: any[] = button.parent.children ?? []
+  return siblings.find((sibling) => searchInputs.includes(sibling)) ?? null
+}
+
+/**
+ * Wires one button: `onClick` empties the query, and the element is replaced
+ * in its parent by `{query ? <button…/> : null}`.
+ */
+export function wireSearchClearButton(
+  button: SearchClearButton,
+  vars: { searchQueryVar: string; setSearchQueryVar: string }
+): void {
+  setJSXExpressionAttribute(
+    button.node,
+    'onClick',
+    types.arrowFunctionExpression(
+      [],
+      types.callExpression(types.identifier(vars.setSearchQueryVar), [types.stringLiteral('')])
+    )
+  )
+  button.parent.children[button.index] = types.jsxExpressionContainer(
+    types.conditionalExpression(
+      types.identifier(vars.searchQueryVar),
+      button.node,
+      types.nullLiteral()
+    )
+  )
+}

package/src/transformations/blog-adjacent-posts.ts

@@ -0,0 +1,74 @@
+/**
+ * How many posts each direction is read, so a neighbour that only REDIRECTS
+ * elsewhere can be stepped over without a second query.
+ */
+const ADJACENT_POST_CANDIDATES = 5
+
+/**
+ * Generates the code that finds a post's neighbours for its "previous / next"
+ * navigation: the published posts right before and after it in the order the
+ * blog listing shows them (`created_at`, then `id`, newest first). "Previous"
+ * is the older one.
+ *
+ * Only a post DETAILS fetch (a single record) asks. A neighbour whose row
+ * carries a redirect is skipped — linking to it would only bounce the reader
+ * somewhere else — which is read off the row in code rather than in SQL, so a
+ * table provisioned before the SEO columns still works.
+ *
+ * MUST mirror `findAdjacentBlogPosts` in teleport-gui
+ * `packages/renderer/src/utils/blog-adjacent-posts.ts` (the canvas).
+ */
+export const generateAdjacentPostsCode = (): string => `
+var BLOG_ADJACENT_CANDIDATES = ${ADJACENT_POST_CANDIDATES}
+
+function blogAdjacentPostsSql(comparison, direction) {
+  return (
+    'SELECT p.* FROM teleport_blog_posts p,' +
+    ' (SELECT created_at, id FROM teleport_blog_posts WHERE id = $1) cur' +
+    " WHERE p.status = 'published' AND (p.created_at, p.id) " + comparison + ' (cur.created_at, cur.id)' +
+    ' ORDER BY p.created_at ' + direction + ', p.id ' + direction +
+    ' LIMIT ' + BLOG_ADJACENT_CANDIDATES
+  )
+}
+
+function firstLinkableBlogPost(result) {
+  var rows = result && Array.isArray(result.rows) ? result.rows : []
+  for (var i = 0; i < rows.length; i++) {
+    var row = rows[i]
+    if (!row) continue
+    var redirect = pickFirst(row.redirect_url, row.redirectUrl)
+    if (typeof redirect === 'string' && redirect.trim() !== '') continue
+    // Through JSON, like the rows the fetcher itself hands the transform.
+    return JSON.parse(JSON.stringify(row))
+  }
+  return null
+}
+
+// { [postId]: { previous, next } } — raw rows or null — for a single-record
+// fetch; {} otherwise and on any failure (the navigation then hides).
+async function getAdjacentPostsMap(getClientFn, records) {
+  var map = {}
+  if (!Array.isArray(records) || records.length !== 1) return map
+  var postId = records[0] && records[0].id
+  if (postId === null || postId === undefined) return map
+
+  var client
+  try {
+    client = getClientFn()
+    await client.connect()
+    var older = await client.query(blogAdjacentPostsSql('<', 'DESC'), [String(postId)])
+    var newer = await client.query(blogAdjacentPostsSql('>', 'ASC'), [String(postId)])
+    map[String(postId)] = {
+      previous: firstLinkableBlogPost(older),
+      next: firstLinkableBlogPost(newer),
+    }
+  } catch (e) {
+    // Leaves the navigation hidden.
+  } finally {
+    if (client) {
+      try { await client.end() } catch (e) { /* ignore */ }
+    }
+  }
+  return map
+}
+`

package/src/transformations/blog-comments.ts

@@ -0,0 +1,132 @@
+/**
+ * How many TOP-LEVEL comments a post page carries: the newest ones, shown
+ * oldest-first, each with all of its replies. The count in the section's
+ * heading still counts every approved comment.
+ *
+ * ⛔ PAIRED with `BLOG_COMMENTS_RENDER_LIMIT` in teleport-gui
+ * `features/blog/constants/blog-comments.ts` (the canvas mirror).
+ */
+export const BLOG_COMMENTS_RENDER_LIMIT = 200
+
+/**
+ * Generates the code that loads and shapes a post's approved comments.
+ *
+ * Read server-side, with the post: only a post DETAILS fetch (a single record)
+ * asks, so a listing never pays for it, and the comments arrive in the page's
+ * HTML — rendered by SSR/ISR, carried along a client-side navigation to another
+ * post, no request of their own.
+ *
+ * Public columns only. `teleport_blog_comments` holds the commenters' email
+ * addresses and the comments still waiting for approval, which is why it is a
+ * customer-record table no browser may read (see teleport-shared's
+ * `table-access.ts`); nothing here selects either.
+ *
+ * Replies are one level deep: a reply whose parent is not among the rows (not
+ * approved, deleted) is dropped rather than promoted to the top level.
+ *
+ * MUST mirror `buildBlogComments` in teleport-gui
+ * `packages/renderer/src/utils/blog-comments.ts` (the canvas).
+ */
+export const generateBlogCommentsCode = (): string => `
+var BLOG_COMMENTS_RENDER_LIMIT = ${BLOG_COMMENTS_RENDER_LIMIT}
+
+var BLOG_COMMENTS_SQL =
+  'WITH top AS (' +
+  ' SELECT id FROM teleport_blog_comments' +
+  " WHERE post_id = $1 AND parent_id IS NULL AND status = 'approved'" +
+  ' ORDER BY created_at DESC, id DESC LIMIT ' + BLOG_COMMENTS_RENDER_LIMIT +
+  ')' +
+  ' SELECT c.id, c.parent_id, c.author_name, c.content, c.is_author_reply, c.created_at' +
+  ' FROM teleport_blog_comments c' +
+  " WHERE c.post_id = $1 AND c.status = 'approved'" +
+  ' AND (c.id IN (SELECT id FROM top) OR c.parent_id IN (SELECT id FROM top))' +
+  ' ORDER BY c.created_at ASC, c.id ASC'
+
+// Every approved comment the page could show — a reply counts only while the
+// comment it answers is approved too.
+var BLOG_COMMENTS_COUNT_SQL =
+  'SELECT COUNT(*) AS n FROM teleport_blog_comments c' +
+  " WHERE c.post_id = $1 AND c.status = 'approved'" +
+  ' AND (c.parent_id IS NULL OR EXISTS (' +
+  ' SELECT 1 FROM teleport_blog_comments p' +
+  " WHERE p.id = c.parent_id AND p.status = 'approved'))"
+
+function blogAuthorInitials(name) {
+  if (typeof name !== 'string') return ''
+  var words = name.trim().split(' ').filter(function(word) { return word !== '' })
+  if (words.length === 0) return ''
+  // Code points, not UTF-16 units: an initial may be an emoji or a letter
+  // outside the BMP, and half of a surrogate pair renders as a box.
+  var first = Array.from(words[0])[0] || ''
+  var last = words.length > 1 ? Array.from(words[words.length - 1])[0] || '' : ''
+  return (first + last).toUpperCase()
+}
+
+function buildBlogComment(row) {
+  var name = typeof row.author_name === 'string' ? row.author_name.trim() : ''
+  var authorName = name || 'Reader'
+  return {
+    id: String(row.id),
+    authorName: authorName,
+    authorInitials: blogAuthorInitials(authorName),
+    content: typeof row.content === 'string' ? row.content : '',
+    createdAt: normalizeTimestamp(row.created_at),
+    isAuthorReply: coerceBoolean(row.is_author_reply, false),
+  }
+}
+
+function isTopLevelComment(row) {
+  return row.parent_id === null || row.parent_id === undefined || row.parent_id === ''
+}
+
+function buildBlogComments(rows) {
+  var comments = []
+  if (!Array.isArray(rows)) return comments
+  var byId = {}
+  for (var i = 0; i < rows.length; i++) {
+    var row = rows[i]
+    if (!row || row.id == null || !isTopLevelComment(row)) continue
+    var comment = buildBlogComment(row)
+    comment.replies = []
+    byId[comment.id] = comment
+    comments.push(comment)
+  }
+  for (var j = 0; j < rows.length; j++) {
+    var reply = rows[j]
+    if (!reply || reply.id == null || isTopLevelComment(reply)) continue
+    var parent = byId[String(reply.parent_id)]
+    if (parent) parent.replies.push(buildBlogComment(reply))
+  }
+  return comments
+}
+
+// { [postId]: { rows, count } } for a single-record (details) fetch; {} for
+// anything else, and on any failure — a blog whose comments table does not
+// exist yet renders its posts without comments rather than failing the page.
+async function getBlogCommentsMap(getClientFn, records) {
+  var map = {}
+  if (!Array.isArray(records) || records.length !== 1) return map
+  var postId = records[0] && records[0].id
+  if (postId === null || postId === undefined) return map
+
+  var client
+  try {
+    client = getClientFn()
+    await client.connect()
+    var listed = await client.query(BLOG_COMMENTS_SQL, [String(postId)])
+    var counted = await client.query(BLOG_COMMENTS_COUNT_SQL, [String(postId)])
+    // Through JSON, like every other row the fetcher hands the transform: the
+    // driver returns timestamps as Date objects.
+    var rows = listed && Array.isArray(listed.rows) ? JSON.parse(JSON.stringify(listed.rows)) : []
+    var count = counted && counted.rows && counted.rows[0] ? Number(counted.rows[0].n) : NaN
+    map[String(postId)] = { rows: rows, count: isNaN(count) ? rows.length : count }
+  } catch (e) {
+    // Leaves the post without comments.
+  } finally {
+    if (client) {
+      try { await client.end() } catch (e) { /* ignore */ }
+    }
+  }
+  return map
+}
+`