feat(rsc): allow proxy export filter by node ast

packages/plugin-rsc/e2e/use-cache-callable.test.ts

@@ -103,7 +103,7 @@ function defineTests(f: Fixture) {
     await page.getByRole('button', { name: 'Reset' }).click()
     await expect(submissionCount).toHaveText('0')
     await expect(executionCount).toHaveText('0')
-    await expect(ordinaryExports).toHaveText('cached metadata: cache')
+    await expect(ordinaryExports).toHaveText('object: array')
     await expect(result).toHaveText('not called')
 
     // The wrapped export is passed from a Server Component to a Client Component.

packages/plugin-rsc/examples/use-cache-callable/callable-cache-plugin.ts

@@ -74,6 +74,9 @@ export function callableCachePlugin(): Plugin {
       const result = transformDirectiveProxyExport(ast, {
         code,
         directive,
+        filter: (_name, meta) =>
+          meta.valueNode?.type !== 'ObjectExpression' &&
+          meta.valueNode?.type !== 'ArrayExpression',
         rejectNonAsyncFunction: true,
         runtime: (name) =>
           `$$ReactClient.createServerReference(` +

packages/plugin-rsc/examples/use-cache-callable/src/features/file-directive-from-client/action.ts

@@ -2,6 +2,11 @@
 
 import { state } from './state'
 
+// Next.js excludes statically known object and array exports from "use cache"
+// server-reference handling. The transform filter mirrors that narrow case.
+export const objectValue = { text: 'object' }
+export const arrayValue = ['array']
+
 export async function cachedFromClient(formData: FormData) {
   const argument = String(formData.get('argument'))
   state.executionCount++

packages/plugin-rsc/examples/use-cache-callable/src/features/file-directive-from-server/action.ts

@@ -2,10 +2,10 @@
 
 import { state } from './state'
 
-// Ordinary values remain available from "use cache" modules without becoming
-// callable server references.
-export const metadata = { title: 'cached metadata' }
-export const tags = ['cache']
+// Next.js excludes statically known object and array exports from "use cache"
+// server-reference handling. The transform filter mirrors that narrow case.
+export const objectValue = { text: 'object' }
+export const arrayValue = ['array']
 
 export async function cachedFromServer(formData: FormData) {
   const argument = String(formData.get('argument'))

packages/plugin-rsc/examples/use-cache-callable/src/features/file-directive-from-server/server.tsx

@@ -1,4 +1,4 @@
-import { cachedFromServer, metadata, tags } from './action'
+import { arrayValue, cachedFromServer, objectValue } from './action'
 import { FileDirectiveFromServerClient } from './client'
 import { resetAction } from './reset'
 import { state } from './state'
@@ -8,7 +8,7 @@ export function FileDirectiveFromServer() {
     <FileDirectiveFromServerClient
       action={cachedFromServer}
       executionCount={state.executionCount}
-      ordinaryExports={`${metadata.title}: ${tags.join(', ')}`}
+      ordinaryExports={`${objectValue.text}: ${arrayValue.join(', ')}`}
       resetAction={resetAction}
       result={state.result}
     />

packages/plugin-rsc/src/transforms/fixtures/source-map/proxy-export/filter-value-node.js

@@ -0,0 +1,7 @@
+'use cache'
+
+export const cached = async () => {},
+  objectValue = {},
+  arrayValue = []
+export const unknown = createCached()
+export const primitive = 0

packages/plugin-rsc/src/transforms/fixtures/source-map/proxy-export/filter-value-node.js.map.snap.md

@@ -0,0 +1,7 @@
+## proxy-export-filtered
+
+```txt
+(2:0) "export const cached = async () => {},\n" --> (2:0) "export const cached = /* #__PURE__ */ createServerReference(\"cached\");\n"
+(5:0) "export const unknown = createCached()\n" --> (4:0) "export const unknown = /* #__PURE__ */ createServerReference(\"unknown\");\n"
+(6:0) "export const primitive = 0\n" --> (6:0) "export const primitive = /* #__PURE__ */ createServerReference(\"primitive\");\n"
+```

packages/plugin-rsc/src/transforms/fixtures/source-map/proxy-export/filter-value-node.js.snap.md

@@ -0,0 +1,30 @@
+## Input
+
+```js
+'use cache'
+
+export const cached = async () => {},
+  objectValue = {},
+  arrayValue = []
+export const unknown = createCached()
+export const primitive = 0
+```
+
+## proxy-export-filtered
+
+**Status:** transformed
+
+**References:** cached, unknown, primitive
+
+[Source map visualization](https://evanw.github.io/source-map-visualization/#MjI2AAoKZXhwb3J0IGNvbnN0IGNhY2hlZCA9IC8qICNfX1BVUkVfXyAqLyBjcmVhdGVTZXJ2ZXJSZWZlcmVuY2UoImNhY2hlZCIpOwoKZXhwb3J0IGNvbnN0IHVua25vd24gPSAvKiAjX19QVVJFX18gKi8gY3JlYXRlU2VydmVyUmVmZXJlbmNlKCJ1bmtub3duIik7CgpleHBvcnQgY29uc3QgcHJpbWl0aXZlID0gLyogI19fUFVSRV9fICovIGNyZWF0ZVNlcnZlclJlZmVyZW5jZSgicHJpbWl0aXZlIik7CgoyNTYAeyJ2ZXJzaW9uIjozLCJzb3VyY2VzIjpbIiJdLCJzb3VyY2VzQ29udGVudCI6WyIndXNlIGNhY2hlJ1xuXG5leHBvcnQgY29uc3QgY2FjaGVkID0gYXN5bmMgKCkgPT4ge30sXG4gIG9iamVjdFZhbHVlID0ge30sXG4gIGFycmF5VmFsdWUgPSBbXVxuZXhwb3J0IGNvbnN0IHVua25vd24gPSBjcmVhdGVDYWNoZWQoKVxuZXhwb3J0IGNvbnN0IHByaW1pdGl2ZSA9IDBcbiJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiOztBQUVBOztBQUdBOztBQUNBOzsifQ==)
+
+```js
+
+
+export const cached = /* #__PURE__ */ createServerReference("cached");
+
+export const unknown = /* #__PURE__ */ createServerReference("unknown");
+
+export const primitive = /* #__PURE__ */ createServerReference("primitive");
+
+```

packages/plugin-rsc/src/transforms/module-export-scan.ts

@@ -150,6 +150,11 @@ export function scanModuleExports(
                 // uniformly handle destructured exports such as
                 //   export const { foo, bar } = ...
                 // even though associated `meta` doesn't make sense anymore
+                // TODO: Treat destructured bindings as unknown for both
+                // "use server" and "use cache" instead of using the container
+                // initializer as each binding's `valueNode`.
+                // See the destructured-binding proxy export regression test.
+                // https://github.com/vercel/next.js/blob/aae4179ac628e55483b62cd023a7e1827dcef122/crates/next-custom-transforms/src/transforms/server_actions.rs#L1787-L1815
                 exports: extractNames(declarator.id).map((name) => ({
                   localName: name,
                   exportName: name,

packages/plugin-rsc/src/transforms/proxy-export.test.ts

@@ -1,17 +1,72 @@
 import { parseAstAsync } from 'vite'
 import { describe, expect, test } from 'vitest'
-import { transformProxyExport } from './proxy-export'
+import {
+  transformProxyExport,
+  type TransformProxyExportOptions,
+} from './proxy-export'
 
-async function testTransform(input: string) {
+async function testTransform(
+  input: string,
+  options?: Partial<TransformProxyExportOptions>,
+) {
   const ast = await parseAstAsync(input)
   const result = transformProxyExport(ast, {
     code: input,
     runtime: (name) => `$$proxy("<id>", ${JSON.stringify(name)})`,
+    ...options,
   })
   return { ...result, output: result.output.toString() }
 }
 
 describe(transformProxyExport, () => {
+  test('filter runs before validation', async () => {
+    const input = `export const cached = async () => {}, objectValue = {}`
+    const ast = await parseAstAsync(input)
+    const options: TransformProxyExportOptions = {
+      code: input,
+      runtime: (name) => `$$proxy(${JSON.stringify(name)})`,
+      rejectNonAsyncFunction: true,
+      filter: (_name, meta) => meta.valueNode?.type !== 'ObjectExpression',
+    }
+
+    expect(() => transformProxyExport(ast, options)).not.toThrow()
+
+    const invalidInput = `${input}, primitive = 0`
+    const invalidAst = await parseAstAsync(invalidInput)
+    expect(() =>
+      transformProxyExport(invalidAst, { ...options, code: invalidInput }),
+    ).toThrow('unsupported non async function')
+  })
+
+  test('filter classifies destructured bindings from their container', async () => {
+    const input = `export const { cached } = { cached: async () => {} }`
+    const result = await testTransform(input, {
+      rejectNonAsyncFunction: true,
+      filter: (_name, meta) => meta.valueNode?.type !== 'ObjectExpression',
+    })
+
+    // TODO: A destructured binding should have no `valueNode` because the
+    // container is not its value. The filter should therefore conservatively
+    // select `cached` without validating the object initializer, resulting in
+    // `exportNames: ['cached']`.
+    // https://github.com/vercel/next.js/tree/aae4179ac628e55483b62cd023a7e1827dcef122/crates/next-custom-transforms/tests/fixture/server-actions/client-graph/14
+    expect(result.exportNames).toEqual([])
+  })
+
+  test.each([
+    ['{}', undefined],
+    ['[]', undefined],
+    ['{}', () => true],
+    ['[]', () => true],
+  ])('validates empty binding %s with filter %s', async (id, filter) => {
+    await expect(
+      testTransform(`export const ${id} = ${id}`, {
+        rejectNonAsyncFunction: true,
+        filter,
+      }),
+    ).rejects.toThrow('unsupported non async function')
+  })
+
   test('export string name throws', async () => {
     const input = `
 const x = 0;
@@ -27,4 +82,13 @@ export { x as "my thing" }
       'unsupported ExportAllDeclaration',
     )
   })
+
+  test('filter with keep throws', async () => {
+    await expect(
+      testTransform(`export const action = () => {}`, {
+        keep: true,
+        filter: () => true,
+      }),
+    ).rejects.toThrow('`filter` option is not supported with `keep`')
+  })
 })