@teleporthq/teleport-plugin-common 0.43.14 → 0.43.22

package/dist/esm/utils/url-search-param-sync.js

@@ -0,0 +1,177 @@
+import * as types from '@babel/types';
+// Shared builders for two-way `<state> ⇄ ?key=` URL search-param syncing.
+//
+// Used by BOTH:
+//   • `createNextUrlSearchParamsPlugin` (teleport-project-generator-next) for
+//     page/component state defs that declare `urlSearchParamBinding` — e.g.
+//     the products-list `selectedCategory` / `sortBy` dropdowns.
+//   • `createNextArrayMapperPaginationPlugin` (teleport-plugin-next-data-source)
+//     for the products-list search input, whose query lives in a
+//     pagination-managed state (`ds_N_searchQuery` / `ds_N_state.debouncedQuery`)
+//     rather than a UIDL state def, so it cannot ride the plugin above.
+//
+// Both emit the SAME loop-free read-back / write-back effect shapes, so the
+// builders live here to keep the two call sites byte-identical and the
+// loop-prevention reasoning in one place.
+// Strict JS identifier (Latin only is fine: UIDL URL keys are limited to the
+// subset Next.js supports as a query param key, which the GUI guarantees to
+// be at minimum URL-safe; but the *generated* code must be valid JS, and
+// `__nextQuery.foo-bar` parses as a subtraction). Anything off-pattern goes
+// through bracket notation: `__nextQuery['foo-bar']`.
+var VALID_JS_IDENTIFIER = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/;
+// `object.<paramKey>` for identifier-safe keys, `object['param-key']` otherwise,
+// so the emitted code is always valid JS regardless of the URL key shape.
+var accessKeyOf = function (object, paramKey) {
+    if (VALID_JS_IDENTIFIER.test(paramKey)) {
+        return types.memberExpression(object, types.identifier(paramKey));
+    }
+    return types.memberExpression(object, types.stringLiteral(paramKey), true);
+};
+var routerQueryAccess = function (paramKey) {
+    return accessKeyOf(types.memberExpression(types.identifier('router'), types.identifier('query')), paramKey);
+};
+// Clones an expression so it can be slotted into multiple positions of the
+// emitted AST — Babel does not support sharing the same node reference across
+// the tree, and callers pass arbitrary value/dependency expressions.
+var clone = function (expr) {
+    return types.cloneNode(expr, /* deep */ true);
+};
+// Builds the state→URL write-back useEffect. Emitted shape (for a value of
+// `selectedCategory` bound to URL key `categoryFilter`):
+//
+//   useEffect(() => {
+//     if (typeof window === 'undefined') return
+//     if (!router.isReady) return
+//     const __nextQuery = { ...router.query }
+//     if (selectedCategory === '' || selectedCategory == null) {
+//       delete __nextQuery.categoryFilter
+//     } else {
+//       __nextQuery.categoryFilter = String(selectedCategory)
+//     }
+//     if (__nextQuery.categoryFilter === router.query.categoryFilter) return
+//     router.replace(
+//       { pathname: router.pathname, query: __nextQuery },
+//       undefined,
+//       { shallow: true }
+//     )
+//   }, [selectedCategory, router.isReady])
+//
+// `valueExpr` is the expression read each render and pushed to the URL (a bare
+// state identifier for dropdowns, `ds_N_state.debouncedQuery` for the search
+// input). `depExpr` is the effect dependency that re-triggers the write-back
+// when that value changes — usually the same expression as `valueExpr`.
+//
+// Notes:
+// 1. `router.isReady` gate: on the very first SSG render `router.query` is
+//    empty, so without this gate any value initialized from
+//    `window.location.search` would immediately `router.replace` itself with
+//    the same value, racing with Next's own hydration. `router.isReady` is
+//    also in the deps array — once it flips to true, the effect re-runs with
+//    the now-hydrated `router.query` and decides correctly whether to replace.
+// 2. The equality check after building `__nextQuery` short-circuits replaces
+//    that would not change the URL — important when the user re-enters the
+//    same value, when the value mounts equal to the URL, and when the
+//    read-back effect fires its setter with the value just pushed.
+// 3. `shallow: true` keeps `getStaticProps` from re-running just because the
+//    URL bar changed; the data-source `useMemo` reacts to the state, not the
+//    URL.
+// 4. Empty / null value deletes the key entirely so the URL never keeps a
+//    sticky `?key=` empty param.
+export var buildUrlWriteBackEffect = function (paramKey, valueExpr, depExpr) {
+    var effectBody = types.blockStatement([
+        // if (typeof window === 'undefined') return
+        types.ifStatement(types.binaryExpression('===', types.unaryExpression('typeof', types.identifier('window')), types.stringLiteral('undefined')), types.returnStatement(null)),
+        // if (!router.isReady) return
+        types.ifStatement(types.unaryExpression('!', types.memberExpression(types.identifier('router'), types.identifier('isReady'))), types.returnStatement(null)),
+        // const __nextQuery = { ...router.query }
+        types.variableDeclaration('const', [
+            types.variableDeclarator(types.identifier('__nextQuery'), types.objectExpression([
+                types.spreadElement(types.memberExpression(types.identifier('router'), types.identifier('query'))),
+            ])),
+        ]),
+        // if (value === '' || value == null) { delete __nextQuery.key }
+        // else { __nextQuery.key = String(value) }
+        types.ifStatement(types.logicalExpression('||', types.binaryExpression('===', clone(valueExpr), types.stringLiteral('')), types.binaryExpression('==', clone(valueExpr), types.nullLiteral())), types.blockStatement([
+            types.expressionStatement(types.unaryExpression('delete', accessKeyOf(types.identifier('__nextQuery'), paramKey))),
+        ]), types.blockStatement([
+            types.expressionStatement(types.assignmentExpression('=', accessKeyOf(types.identifier('__nextQuery'), paramKey), types.callExpression(types.identifier('String'), [clone(valueExpr)]))),
+        ])),
+        // if (__nextQuery.key === router.query.key) return
+        types.ifStatement(types.binaryExpression('===', accessKeyOf(types.identifier('__nextQuery'), paramKey), routerQueryAccess(paramKey)), types.returnStatement(null)),
+        // router.replace({ pathname: router.pathname, query: __nextQuery }, undefined, { shallow: true })
+        types.expressionStatement(types.callExpression(types.memberExpression(types.identifier('router'), types.identifier('replace')), [
+            types.objectExpression([
+                types.objectProperty(types.identifier('pathname'), types.memberExpression(types.identifier('router'), types.identifier('pathname'))),
+                types.objectProperty(types.identifier('query'), types.identifier('__nextQuery')),
+            ]),
+            types.identifier('undefined'),
+            types.objectExpression([
+                types.objectProperty(types.identifier('shallow'), types.booleanLiteral(true)),
+            ]),
+        ])),
+    ]);
+    return types.expressionStatement(types.callExpression(types.identifier('useEffect'), [
+        types.arrowFunctionExpression([], effectBody),
+        types.arrayExpression([
+            clone(depExpr),
+            types.memberExpression(types.identifier('router'), types.identifier('isReady')),
+        ]),
+    ]));
+};
+// Builds the URL→state read-back useEffect. Emitted shape (for setter
+// `setSelectedCategory` bound to URL key `categoryFilter`):
+//
+//   useEffect(() => {
+//     if (!router.isReady) return
+//     const __urlValue = router.query.categoryFilter
+//     const __nextValue =
+//       typeof __urlValue === 'string' ? __urlValue : Array.isArray(__urlValue) ? (__urlValue[0] || '') : ''
+//     setSelectedCategory((prev) => (prev === __nextValue ? prev : __nextValue))
+//   }, [router.query.categoryFilter, router.isReady])
+//
+// Why pair this with the write-back effect:
+// - On `<Link>` / `router.push` shallow navigations that land on the same path
+//   with a different query (or browser back/forward, which can change the query
+//   without remounting the page), `router.query` updates but the state hook does
+//   not. Without this effect, the control would be stuck on whatever the user
+//   last picked even though the URL has moved on.
+// - The functional `setState((prev) => prev === next ? prev : next)` form
+//   guarantees React bails out when the URL value matches state, which prevents
+//   an infinite write-back ↔ read-back loop: when the user picks a new value,
+//   state→URL fires once, URL→state observes the matching value and returns
+//   `prev`, so React does not re-render or fire any deps.
+// - `router.query[key]` can be either `string` (single value) or `string[]`
+//   (duplicate keys) per Next.js's typings; the helper normalizes both to a
+//   string before comparing, defaulting to `''` for the missing-key case so the
+//   comparison aligns with the write-back's `value === ''` empty-check.
+export var buildUrlReadBackEffect = function (paramKey, setterName) {
+    var normalizeArg = types.conditionalExpression(
+    // typeof __urlValue === 'string' ? __urlValue
+    types.binaryExpression('===', types.unaryExpression('typeof', types.identifier('__urlValue')), types.stringLiteral('string')), types.identifier('__urlValue'), types.conditionalExpression(
+    // Array.isArray(__urlValue) ? (__urlValue[0] || '') : ''
+    types.callExpression(types.memberExpression(types.identifier('Array'), types.identifier('isArray')), [types.identifier('__urlValue')]), types.logicalExpression('||', types.memberExpression(types.identifier('__urlValue'), types.numericLiteral(0), true), types.stringLiteral('')), types.stringLiteral('')));
+    var effectBody = types.blockStatement([
+        // if (!router.isReady) return
+        types.ifStatement(types.unaryExpression('!', types.memberExpression(types.identifier('router'), types.identifier('isReady'))), types.returnStatement(null)),
+        // const __urlValue = router.query.<paramKey>
+        types.variableDeclaration('const', [
+            types.variableDeclarator(types.identifier('__urlValue'), routerQueryAccess(paramKey)),
+        ]),
+        // const __nextValue = (normalized)
+        types.variableDeclaration('const', [
+            types.variableDeclarator(types.identifier('__nextValue'), normalizeArg),
+        ]),
+        // setState((prev) => prev === __nextValue ? prev : __nextValue)
+        types.expressionStatement(types.callExpression(types.identifier(setterName), [
+            types.arrowFunctionExpression([types.identifier('prev')], types.conditionalExpression(types.binaryExpression('===', types.identifier('prev'), types.identifier('__nextValue')), types.identifier('prev'), types.identifier('__nextValue'))),
+        ])),
+    ]);
+    return types.expressionStatement(types.callExpression(types.identifier('useEffect'), [
+        types.arrowFunctionExpression([], effectBody),
+        types.arrayExpression([
+            routerQueryAccess(paramKey),
+            types.memberExpression(types.identifier('router'), types.identifier('isReady')),
+        ]),
+    ]));
+};
+//# sourceMappingURL=url-search-param-sync.js.map

package/dist/esm/utils/url-search-param-sync.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"url-search-param-sync.js","sourceRoot":"","sources":["../../../src/utils/url-search-param-sync.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@teleporthq/teleport-plugin-common",
-  "version": "0.43.14",
+  "version": "0.43.22",
   "description": "Common building and modelating functions for ASTs and HASTs",
   "author": "teleportHQ",
   "license": "MIT",
@@ -27,10 +27,10 @@
     "@babel/core": "^7.5.5",
     "@babel/preset-react": "^7.22.5",
     "@babel/types": "^7.5.5",
-    "@teleporthq/teleport-shared": "^0.43.14",
-    "@teleporthq/teleport-types": "^0.43.14",
+    "@teleporthq/teleport-shared": "^0.43.22",
+    "@teleporthq/teleport-types": "^0.43.22",
     "jss": "^10.0.0",
     "jss-preset-default": "^10.0.0"
   },
-  "gitHead": "dab51af409fb5b93dbee9c54ddcadfd87bf8f41e"
+  "gitHead": "4bac1ec64c3c7e9f14a84a260331206d5797b773"
 }

package/src/index.ts

@@ -5,6 +5,7 @@ import * as HASTBuilders from './builders/hast-builders'
 import * as ASTUtils from './utils/ast-utils'
 import * as StyleUtils from './utils/style-utils'
 import * as HASTUtils from './utils/hast-utils'
+import * as URLSearchParamSync from './utils/url-search-param-sync'
 import ParsedASTNode from './utils/parsed-ast'
 
 import { createBinaryExpression } from './node-handlers/node-to-jsx/utils'
@@ -16,6 +17,7 @@ export {
   ASTUtils,
   StyleUtils,
   HASTUtils,
+  URLSearchParamSync,
   ParsedASTNode,
   createBinaryExpression,
 }

package/src/utils/ast-utils.ts

@@ -1381,16 +1381,21 @@ const generateParamsAST = (
 }
 
 const generateRESTHeadersAST = (headers: UIDLResourceItem['headers']): types.ObjectProperty[] => {
-  return Object.keys(headers)
-    .filter((header) => header !== 'authToken')
-    .map((header) => {
-      const headerResolved = resolveResourceValue(headers[header])
-      const value =
-        headers[header].type === 'static'
-          ? types.stringLiteral(String(headerResolved))
-          : types.identifier(String(headerResolved))
-      return types.objectProperty(types.stringLiteral(header), value)
-    })
+  return (
+    Object.keys(headers)
+      // `authToken` is rendered as the `Authorization` header; `authScheme` is a
+      // generator-only directive for that header's prefix — neither is emitted as
+      // its own literal HTTP header.
+      .filter((header) => header !== 'authToken' && header !== 'authScheme')
+      .map((header) => {
+        const headerResolved = resolveResourceValue(headers[header])
+        const value =
+          headers[header].type === 'static'
+            ? types.stringLiteral(String(headerResolved))
+            : types.identifier(String(headerResolved))
+        return types.objectProperty(types.stringLiteral(header), value)
+      })
+  )
 }
 
 export const generateMemberExpressionASTFromBase = (
@@ -1529,14 +1534,28 @@ const computeAuthorizationHeaderAST = (headers: UIDLResourceItem['headers']) =>
 
   const authTokenType = headers.authToken?.type
 
+  // The auth scheme prefix defaults to `Bearer ` (back-compatible with every CMS
+  // and data-source that stores a bare bearer token). A resource may override it
+  // via a `headers.authScheme` static value — e.g. WordPress Basic / Application
+  // Password auth sets `Basic ` so the rendered header is `Basic <base64>`
+  // instead of the wrong `Bearer <base64>`. `authScheme` is consumed here and
+  // filtered out of the emitted REST headers (see generateRESTHeadersAST).
+  const authSchemeValue = headers.authScheme
+  const schemePrefix =
+    authSchemeValue &&
+    authSchemeValue.type === 'static' &&
+    typeof authSchemeValue.content === 'string'
+      ? authSchemeValue.content
+      : 'Bearer '
+
   return types.objectProperty(
     types.identifier('Authorization'),
     types.templateLiteral(
       [
         types.templateElement(
           {
-            cooked: authTokenType === 'static' ? `Bearer ${authToken}` : 'Bearer ',
-            raw: authTokenType === 'static' ? `Bearer ${authToken}` : 'Bearer ',
+            cooked: authTokenType === 'static' ? `${schemePrefix}${authToken}` : schemePrefix,
+            raw: authTokenType === 'static' ? `${schemePrefix}${authToken}` : schemePrefix,
           },
           false
         ),

package/src/utils/url-search-param-sync.ts

@@ -0,0 +1,286 @@
+import * as types from '@babel/types'
+
+// Shared builders for two-way `<state> ⇄ ?key=` URL search-param syncing.
+//
+// Used by BOTH:
+//   • `createNextUrlSearchParamsPlugin` (teleport-project-generator-next) for
+//     page/component state defs that declare `urlSearchParamBinding` — e.g.
+//     the products-list `selectedCategory` / `sortBy` dropdowns.
+//   • `createNextArrayMapperPaginationPlugin` (teleport-plugin-next-data-source)
+//     for the products-list search input, whose query lives in a
+//     pagination-managed state (`ds_N_searchQuery` / `ds_N_state.debouncedQuery`)
+//     rather than a UIDL state def, so it cannot ride the plugin above.
+//
+// Both emit the SAME loop-free read-back / write-back effect shapes, so the
+// builders live here to keep the two call sites byte-identical and the
+// loop-prevention reasoning in one place.
+
+// Strict JS identifier (Latin only is fine: UIDL URL keys are limited to the
+// subset Next.js supports as a query param key, which the GUI guarantees to
+// be at minimum URL-safe; but the *generated* code must be valid JS, and
+// `__nextQuery.foo-bar` parses as a subtraction). Anything off-pattern goes
+// through bracket notation: `__nextQuery['foo-bar']`.
+const VALID_JS_IDENTIFIER = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/
+
+// `object.<paramKey>` for identifier-safe keys, `object['param-key']` otherwise,
+// so the emitted code is always valid JS regardless of the URL key shape.
+const accessKeyOf = (object: types.Expression, paramKey: string): types.MemberExpression => {
+  if (VALID_JS_IDENTIFIER.test(paramKey)) {
+    return types.memberExpression(object, types.identifier(paramKey))
+  }
+  return types.memberExpression(object, types.stringLiteral(paramKey), true)
+}
+
+const routerQueryAccess = (paramKey: string): types.MemberExpression =>
+  accessKeyOf(
+    types.memberExpression(types.identifier('router'), types.identifier('query')),
+    paramKey
+  )
+
+// Clones an expression so it can be slotted into multiple positions of the
+// emitted AST — Babel does not support sharing the same node reference across
+// the tree, and callers pass arbitrary value/dependency expressions.
+const clone = (expr: types.Expression): types.Expression =>
+  types.cloneNode(expr, /* deep */ true) as types.Expression
+
+// Builds the state→URL write-back useEffect. Emitted shape (for a value of
+// `selectedCategory` bound to URL key `categoryFilter`):
+//
+//   useEffect(() => {
+//     if (typeof window === 'undefined') return
+//     if (!router.isReady) return
+//     const __nextQuery = { ...router.query }
+//     if (selectedCategory === '' || selectedCategory == null) {
+//       delete __nextQuery.categoryFilter
+//     } else {
+//       __nextQuery.categoryFilter = String(selectedCategory)
+//     }
+//     if (__nextQuery.categoryFilter === router.query.categoryFilter) return
+//     router.replace(
+//       { pathname: router.pathname, query: __nextQuery },
+//       undefined,
+//       { shallow: true }
+//     )
+//   }, [selectedCategory, router.isReady])
+//
+// `valueExpr` is the expression read each render and pushed to the URL (a bare
+// state identifier for dropdowns, `ds_N_state.debouncedQuery` for the search
+// input). `depExpr` is the effect dependency that re-triggers the write-back
+// when that value changes — usually the same expression as `valueExpr`.
+//
+// Notes:
+// 1. `router.isReady` gate: on the very first SSG render `router.query` is
+//    empty, so without this gate any value initialized from
+//    `window.location.search` would immediately `router.replace` itself with
+//    the same value, racing with Next's own hydration. `router.isReady` is
+//    also in the deps array — once it flips to true, the effect re-runs with
+//    the now-hydrated `router.query` and decides correctly whether to replace.
+// 2. The equality check after building `__nextQuery` short-circuits replaces
+//    that would not change the URL — important when the user re-enters the
+//    same value, when the value mounts equal to the URL, and when the
+//    read-back effect fires its setter with the value just pushed.
+// 3. `shallow: true` keeps `getStaticProps` from re-running just because the
+//    URL bar changed; the data-source `useMemo` reacts to the state, not the
+//    URL.
+// 4. Empty / null value deletes the key entirely so the URL never keeps a
+//    sticky `?key=` empty param.
+export const buildUrlWriteBackEffect = (
+  paramKey: string,
+  valueExpr: types.Expression,
+  depExpr: types.Expression
+): types.ExpressionStatement => {
+  const effectBody = types.blockStatement([
+    // if (typeof window === 'undefined') return
+    types.ifStatement(
+      types.binaryExpression(
+        '===',
+        types.unaryExpression('typeof', types.identifier('window')),
+        types.stringLiteral('undefined')
+      ),
+      types.returnStatement(null)
+    ),
+    // if (!router.isReady) return
+    types.ifStatement(
+      types.unaryExpression(
+        '!',
+        types.memberExpression(types.identifier('router'), types.identifier('isReady'))
+      ),
+      types.returnStatement(null)
+    ),
+    // const __nextQuery = { ...router.query }
+    types.variableDeclaration('const', [
+      types.variableDeclarator(
+        types.identifier('__nextQuery'),
+        types.objectExpression([
+          types.spreadElement(
+            types.memberExpression(types.identifier('router'), types.identifier('query'))
+          ),
+        ])
+      ),
+    ]),
+    // if (value === '' || value == null) { delete __nextQuery.key }
+    // else { __nextQuery.key = String(value) }
+    types.ifStatement(
+      types.logicalExpression(
+        '||',
+        types.binaryExpression('===', clone(valueExpr), types.stringLiteral('')),
+        types.binaryExpression('==', clone(valueExpr), types.nullLiteral())
+      ),
+      types.blockStatement([
+        types.expressionStatement(
+          types.unaryExpression(
+            'delete',
+            accessKeyOf(types.identifier('__nextQuery'), paramKey)
+          ) as unknown as types.Expression
+        ),
+      ]),
+      types.blockStatement([
+        types.expressionStatement(
+          types.assignmentExpression(
+            '=',
+            accessKeyOf(types.identifier('__nextQuery'), paramKey),
+            types.callExpression(types.identifier('String'), [clone(valueExpr)])
+          )
+        ),
+      ])
+    ),
+    // if (__nextQuery.key === router.query.key) return
+    types.ifStatement(
+      types.binaryExpression(
+        '===',
+        accessKeyOf(types.identifier('__nextQuery'), paramKey),
+        routerQueryAccess(paramKey)
+      ),
+      types.returnStatement(null)
+    ),
+    // router.replace({ pathname: router.pathname, query: __nextQuery }, undefined, { shallow: true })
+    types.expressionStatement(
+      types.callExpression(
+        types.memberExpression(types.identifier('router'), types.identifier('replace')),
+        [
+          types.objectExpression([
+            types.objectProperty(
+              types.identifier('pathname'),
+              types.memberExpression(types.identifier('router'), types.identifier('pathname'))
+            ),
+            types.objectProperty(types.identifier('query'), types.identifier('__nextQuery')),
+          ]),
+          types.identifier('undefined'),
+          types.objectExpression([
+            types.objectProperty(types.identifier('shallow'), types.booleanLiteral(true)),
+          ]),
+        ]
+      )
+    ),
+  ])
+
+  return types.expressionStatement(
+    types.callExpression(types.identifier('useEffect'), [
+      types.arrowFunctionExpression([], effectBody),
+      types.arrayExpression([
+        clone(depExpr),
+        types.memberExpression(types.identifier('router'), types.identifier('isReady')),
+      ]),
+    ])
+  )
+}
+
+// Builds the URL→state read-back useEffect. Emitted shape (for setter
+// `setSelectedCategory` bound to URL key `categoryFilter`):
+//
+//   useEffect(() => {
+//     if (!router.isReady) return
+//     const __urlValue = router.query.categoryFilter
+//     const __nextValue =
+//       typeof __urlValue === 'string' ? __urlValue : Array.isArray(__urlValue) ? (__urlValue[0] || '') : ''
+//     setSelectedCategory((prev) => (prev === __nextValue ? prev : __nextValue))
+//   }, [router.query.categoryFilter, router.isReady])
+//
+// Why pair this with the write-back effect:
+// - On `<Link>` / `router.push` shallow navigations that land on the same path
+//   with a different query (or browser back/forward, which can change the query
+//   without remounting the page), `router.query` updates but the state hook does
+//   not. Without this effect, the control would be stuck on whatever the user
+//   last picked even though the URL has moved on.
+// - The functional `setState((prev) => prev === next ? prev : next)` form
+//   guarantees React bails out when the URL value matches state, which prevents
+//   an infinite write-back ↔ read-back loop: when the user picks a new value,
+//   state→URL fires once, URL→state observes the matching value and returns
+//   `prev`, so React does not re-render or fire any deps.
+// - `router.query[key]` can be either `string` (single value) or `string[]`
+//   (duplicate keys) per Next.js's typings; the helper normalizes both to a
+//   string before comparing, defaulting to `''` for the missing-key case so the
+//   comparison aligns with the write-back's `value === ''` empty-check.
+export const buildUrlReadBackEffect = (
+  paramKey: string,
+  setterName: string
+): types.ExpressionStatement => {
+  const normalizeArg = types.conditionalExpression(
+    // typeof __urlValue === 'string' ? __urlValue
+    types.binaryExpression(
+      '===',
+      types.unaryExpression('typeof', types.identifier('__urlValue')),
+      types.stringLiteral('string')
+    ),
+    types.identifier('__urlValue'),
+    types.conditionalExpression(
+      // Array.isArray(__urlValue) ? (__urlValue[0] || '') : ''
+      types.callExpression(
+        types.memberExpression(types.identifier('Array'), types.identifier('isArray')),
+        [types.identifier('__urlValue')]
+      ),
+      types.logicalExpression(
+        '||',
+        types.memberExpression(types.identifier('__urlValue'), types.numericLiteral(0), true),
+        types.stringLiteral('')
+      ),
+      types.stringLiteral('')
+    )
+  )
+
+  const effectBody = types.blockStatement([
+    // if (!router.isReady) return
+    types.ifStatement(
+      types.unaryExpression(
+        '!',
+        types.memberExpression(types.identifier('router'), types.identifier('isReady'))
+      ),
+      types.returnStatement(null)
+    ),
+    // const __urlValue = router.query.<paramKey>
+    types.variableDeclaration('const', [
+      types.variableDeclarator(types.identifier('__urlValue'), routerQueryAccess(paramKey)),
+    ]),
+    // const __nextValue = (normalized)
+    types.variableDeclaration('const', [
+      types.variableDeclarator(types.identifier('__nextValue'), normalizeArg),
+    ]),
+    // setState((prev) => prev === __nextValue ? prev : __nextValue)
+    types.expressionStatement(
+      types.callExpression(types.identifier(setterName), [
+        types.arrowFunctionExpression(
+          [types.identifier('prev')],
+          types.conditionalExpression(
+            types.binaryExpression(
+              '===',
+              types.identifier('prev'),
+              types.identifier('__nextValue')
+            ),
+            types.identifier('prev'),
+            types.identifier('__nextValue')
+          )
+        ),
+      ])
+    ),
+  ])
+
+  return types.expressionStatement(
+    types.callExpression(types.identifier('useEffect'), [
+      types.arrowFunctionExpression([], effectBody),
+      types.arrayExpression([
+        routerQueryAccess(paramKey),
+        types.memberExpression(types.identifier('router'), types.identifier('isReady')),
+      ]),
+    ])
+  )
+}