feat(experimental): standalone ref transform

packages/ref-transform/README.md

@@ -0,0 +1,84 @@
+# @vue/ref-transform
+
+> ⚠️ This is experimental and currently only provided for testing and feedback. It may break during patches or even be removed. Use at your own risk!
+>
+> Follow https://github.com/vuejs/rfcs/discussions/369 for details and updates.
+
+## Basic Rules
+
+- `$()` to turn refs into reative variables
+- `$$()` to access the original refs from reative variables
+
+```js
+import { ref, watch } from 'vue'
+
+// bind ref as a variable
+let count = $(ref(0))
+
+// no need for .value
+console.log(count)
+
+// get the actual ref
+watch($$(count), c => console.log(`count changed to ${c}`))
+
+// assignments are reactive
+count++
+```
+
+### Shorthands
+
+A few commonly used APIs have shorthands (which also removes the need to import them):
+
+- `$(ref(0))` -> `$ref(0)`
+- `$(computed(() => 123))` -> `$computed(() => 123)`
+- `$(shallowRef({}))` -> `$shallowRef({})`
+
+## API
+
+This package is the lower-level transform that can be used standalone. Higher-level tooling (e.g. `@vitejs/plugin-vue` and `vue-loader`) will provide integration via options.
+
+### `transform`
+
+```js
+import { transform } from '@vue/ref-transform'
+
+const src = `let a = $ref(0); a++`
+const {
+  code, // import { ref as _ref } from 'vue'; let a = (ref(0)); a.value++"
+  map
+} = transform(src, {
+  filename: 'foo.ts',
+  sourceMap: true,
+  parserPlugins: ['typescript']
+})
+```
+
+**Options**
+
+```ts
+interface RefTransformOptions {
+  filename?: string
+  sourceMap?: boolean // default: false
+  parserPlugins?: ParserPlugin[]
+  importHelpersFrom?: string // default: "vue"
+}
+```
+
+### `transformAST`
+
+```js
+import { transformAST } from '@vue/ref-transform'
+import { parse } from '@babel/parser'
+import MagicString from 'magic-string'
+
+const src = `let a = $ref(0); a++`
+const ast = parse(src, { sourceType: 'module' })
+const s = new MagicString(src)
+
+const {
+  rootVars, // ['a']
+  importedHelpers // ['ref']
+} = transformAST(ast, s)
+
+console.log(s.toString()) // let a = _ref(0); a.value++
+```

packages/ref-transform/__tests__/__snapshots__/refTransform.spec.ts.snap

@@ -0,0 +1,211 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`$ unwrapping 1`] = `
+"
+    import { ref, shallowRef } from 'vue'
+    let foo = (ref())
+    let a = (ref(1))
+    let b = (shallowRef({
+      count: 0
+    }))
+    let c = () => {}
+    let d
+    "
+`;
+
+exports[`$$ 1`] = `
+"import { ref as _ref } from 'vue'
+
+    let a = _ref(1)
+    const b = (a)
+    const c = ({ a })
+    callExternal((a))
+    "
+`;
+
+exports[`$computed declaration 1`] = `
+"import { computed as _computed } from 'vue'
+
+    let a = _computed(() => 1)
+    "
+`;
+
+exports[`$ref & $shallowRef declarations 1`] = `
+"import { ref as _ref, shallowRef as _shallowRef } from 'vue'
+
+    let foo = _ref()
+    let a = _ref(1)
+    let b = _shallowRef({
+      count: 0
+    })
+    let c = () => {}
+    let d
+    "
+`;
+
+exports[`accessing ref binding 1`] = `
+"import { ref as _ref } from 'vue'
+
+    let a = _ref(1)
+    console.log(a.value)
+    function get() {
+      return a.value + 1
+    }
+    "
+`;
+
+exports[`array destructure 1`] = `
+"import { ref as _ref } from 'vue'
+
+    let n = _ref(1), [__a, __b = 1, ...__c] = (useFoo())
+const a = _ref(__a);
+const b = _ref(__b);
+const c = _ref(__c);
+    console.log(n.value, a.value, b.value, c.value)
+    "
+`;
+
+exports[`handle TS casting syntax 1`] = `
+"import { ref as _ref } from 'vue'
+
+      let a = _ref(1)
+      console.log(a.value!)
+      console.log(a.value! + 1)
+      console.log(a.value as number)
+      console.log((a.value as number) + 1)
+      console.log(<number>a.value)
+      console.log(<number>a.value + 1)
+      console.log(a.value! + (a.value as number))
+      console.log(a.value! + <number>a.value)
+      console.log((a.value as number) + <number>a.value)
+      "
+`;
+
+exports[`mixing $ref & $computed declarations 1`] = `
+"import { ref as _ref, computed as _computed } from 'vue'
+
+    let a = _ref(1), b = _computed(() => a.value + 1)
+    "
+`;
+
+exports[`multi $ref declarations 1`] = `
+"import { ref as _ref } from 'vue'
+
+    let a = _ref(1), b = _ref(2), c = _ref({
+      count: 0
+    })
+    "
+`;
+
+exports[`mutating ref binding 1`] = `
+"import { ref as _ref } from 'vue'
+
+    let a = _ref(1)
+    let b = _ref({ count: 0 })
+    function inc() {
+      a.value++
+      a.value = a.value + 1
+      b.value.count++
+      b.value.count = b.value.count + 1
+      ;({ a: a.value } = { a: 2 })
+      ;[a.value] = [1]
+    }
+    "
+`;
+
+exports[`nested destructure 1`] = `
+"import { ref as _ref } from 'vue'
+
+    let [{ a: { b: __b }}] = (useFoo())
+const b = _ref(__b);
+    let { c: [__d, __e] } = (useBar())
+const d = _ref(__d);
+const e = _ref(__e);
+    console.log(b.value, d.value, e.value)
+    "
+`;
+
+exports[`nested scopes 1`] = `
+"import { ref as _ref } from 'vue'
+
+    let a = _ref(0)
+    let b = _ref(0)
+    let c = 0
+
+    a.value++ // outer a
+    b.value++ // outer b
+    c++ // outer c
+
+    function foo({ a }) {
+      a++ // inner a
+      b.value++ // inner b
+      let c = _ref(0)
+      c.value++ // inner c
+      let d = _ref(0)
+
+      const bar = (c) => {
+        c++ // nested c
+        d.value++ // nested d
+      }
+
+      if (true) {
+        let a = _ref(0)
+        a.value++ // if block a
+      }
+
+      return ({ a, b, c, d })
+    }
+    "
+`;
+
+exports[`object destructure 1`] = `
+"import { ref as _ref } from 'vue'
+
+    let n = _ref(1), { a: __a, b: __c, d: __d = 1, e: __f = 2, ...__g } = (useFoo())
+const a = _ref(__a);
+const c = _ref(__c);
+const d = _ref(__d);
+const f = _ref(__f);
+const g = _ref(__g);
+    let { foo: __foo } = (useSomthing(() => 1));
+const foo = _ref(__foo);
+    console.log(n.value, a.value, c.value, d.value, f.value, g.value, foo.value)
+    "
+`;
+
+exports[`should not rewrite scope variable 1`] = `
+"import { ref as _ref } from 'vue'
+
+
+      let a = _ref(1)
+      let b = _ref(1)
+      let d = _ref(1)
+      const e = 1
+      function test() {
+        const a = 2
+        console.log(a)
+        console.log(b.value)
+        let c = { c: 3 }
+        console.log(c)
+        console.log(d.value)
+        console.log(e)
+      }
+    "
+`;
+
+exports[`should not rewrite type identifiers 1`] = `
+"import { ref as _ref } from 'vue'
+const props = defineProps<{msg: string; ids?: string[]}>()
+        let ids = _ref([])"
+`;
+
+exports[`using ref binding in property shorthand 1`] = `
+"import { ref as _ref } from 'vue'
+
+    let a = _ref(1)
+    const b = { a: a.value }
+    function test() {
+      const { a } = b
+    }
+    "
+`;

packages/ref-transform/__tests__/refTransform.spec.ts

@@ -0,0 +1,390 @@
+import { parse } from '@babel/parser'
+import { babelParserDefaultPlugins } from '@vue/shared'
+import { transform } from '../src'
+
+function assertCode(code: string) {
+  // parse the generated code to make sure it is valid
+  try {
+    parse(code, {
+      sourceType: 'module',
+      plugins: [...babelParserDefaultPlugins, 'typescript']
+    })
+  } catch (e) {
+    console.log(code)
+    throw e
+  }
+  expect(code).toMatchSnapshot()
+}
+
+test('$ unwrapping', () => {
+  const { code, rootVars } = transform(`
+    import { ref, shallowRef } from 'vue'
+    let foo = $(ref())
+    let a = $(ref(1))
+    let b = $(shallowRef({
+      count: 0
+    }))
+    let c = () => {}
+    let d
+    `)
+  expect(code).not.toMatch(`$(ref())`)
+  expect(code).not.toMatch(`$(ref(1))`)
+  expect(code).not.toMatch(`$(shallowRef({`)
+  expect(code).toMatch(`let foo = (ref())`)
+  expect(code).toMatch(`let a = (ref(1))`)
+  expect(code).toMatch(`
+    let b = (shallowRef({
+      count: 0
+    }))
+    `)
+  // normal declarations left untouched
+  expect(code).toMatch(`let c = () => {}`)
+  expect(code).toMatch(`let d`)
+  expect(rootVars).toStrictEqual(['foo', 'a', 'b'])
+  assertCode(code)
+})
+
+test('$ref & $shallowRef declarations', () => {
+  const { code, rootVars, importedHelpers } = transform(`
+    let foo = $ref()
+    let a = $ref(1)
+    let b = $shallowRef({
+      count: 0
+    })
+    let c = () => {}
+    let d
+    `)
+  expect(code).toMatch(
+    `import { ref as _ref, shallowRef as _shallowRef } from 'vue'`
+  )
+  expect(code).not.toMatch(`$ref()`)
+  expect(code).not.toMatch(`$ref(1)`)
+  expect(code).not.toMatch(`$shallowRef({`)
+  expect(code).toMatch(`let foo = _ref()`)
+  expect(code).toMatch(`let a = _ref(1)`)
+  expect(code).toMatch(`
+    let b = _shallowRef({
+      count: 0
+    })
+    `)
+  // normal declarations left untouched
+  expect(code).toMatch(`let c = () => {}`)
+  expect(code).toMatch(`let d`)
+  expect(rootVars).toStrictEqual(['foo', 'a', 'b'])
+  expect(importedHelpers).toStrictEqual(['ref', 'shallowRef'])
+  assertCode(code)
+})
+
+test('multi $ref declarations', () => {
+  const { code, rootVars, importedHelpers } = transform(`
+    let a = $ref(1), b = $ref(2), c = $ref({
+      count: 0
+    })
+    `)
+  expect(code).toMatch(`
+    let a = _ref(1), b = _ref(2), c = _ref({
+      count: 0
+    })
+    `)
+  expect(rootVars).toStrictEqual(['a', 'b', 'c'])
+  expect(importedHelpers).toStrictEqual(['ref'])
+  assertCode(code)
+})
+
+test('$computed declaration', () => {
+  const { code, rootVars, importedHelpers } = transform(`
+    let a = $computed(() => 1)
+    `)
+  expect(code).toMatch(`
+    let a = _computed(() => 1)
+    `)
+  expect(rootVars).toStrictEqual(['a'])
+  expect(importedHelpers).toStrictEqual(['computed'])
+  assertCode(code)
+})
+
+test('mixing $ref & $computed declarations', () => {
+  const { code, rootVars, importedHelpers } = transform(`
+    let a = $ref(1), b = $computed(() => a + 1)
+    `)
+  expect(code).toMatch(`
+    let a = _ref(1), b = _computed(() => a.value + 1)
+    `)
+  expect(rootVars).toStrictEqual(['a', 'b'])
+  expect(importedHelpers).toStrictEqual(['ref', 'computed'])
+  assertCode(code)
+})
+
+test('accessing ref binding', () => {
+  const { code } = transform(`
+    let a = $ref(1)
+    console.log(a)
+    function get() {
+      return a + 1
+    }
+    `)
+  expect(code).toMatch(`console.log(a.value)`)
+  expect(code).toMatch(`return a.value + 1`)
+  assertCode(code)
+})
+
+test('cases that should not append .value', () => {
+  const { code } = transform(`
+    let a = $ref(1)
+    console.log(b.a)
+    function get(a) {
+      return a + 1
+    }
+    `)
+  expect(code).not.toMatch(`a.value`)
+})
+
+test('mutating ref binding', () => {
+  const { code } = transform(`
+    let a = $ref(1)
+    let b = $ref({ count: 0 })
+    function inc() {
+      a++
+      a = a + 1
+      b.count++
+      b.count = b.count + 1
+      ;({ a } = { a: 2 })
+      ;[a] = [1]
+    }
+    `)
+  expect(code).toMatch(`a.value++`)
+  expect(code).toMatch(`a.value = a.value + 1`)
+  expect(code).toMatch(`b.value.count++`)
+  expect(code).toMatch(`b.value.count = b.value.count + 1`)
+  expect(code).toMatch(`;({ a: a.value } = { a: 2 })`)
+  expect(code).toMatch(`;[a.value] = [1]`)
+  assertCode(code)
+})
+
+test('using ref binding in property shorthand', () => {
+  const { code } = transform(`
+    let a = $ref(1)
+    const b = { a }
+    function test() {
+      const { a } = b
+    }
+    `)
+  expect(code).toMatch(`const b = { a: a.value }`)
+  // should not convert destructure
+  expect(code).toMatch(`const { a } = b`)
+  assertCode(code)
+})
+
+test('should not rewrite scope variable', () => {
+  const { code } = transform(`
+
+      let a = $ref(1)
+      let b = $ref(1)
+      let d = $ref(1)
+      const e = 1
+      function test() {
+        const a = 2
+        console.log(a)
+        console.log(b)
+        let c = { c: 3 }
+        console.log(c)
+        console.log(d)
+        console.log(e)
+      }
+    `)
+  expect(code).toMatch('console.log(a)')
+  expect(code).toMatch('console.log(b.value)')
+  expect(code).toMatch('console.log(c)')
+  expect(code).toMatch('console.log(d.value)')
+  expect(code).toMatch('console.log(e)')
+  assertCode(code)
+})
+
+test('object destructure', () => {
+  const { code, rootVars } = transform(`
+    let n = $ref(1), { a, b: c, d = 1, e: f = 2, ...g } = $(useFoo())
+    let { foo } = $(useSomthing(() => 1));
+    console.log(n, a, c, d, f, g, foo)
+    `)
+  expect(code).toMatch(
+    `let n = _ref(1), { a: __a, b: __c, d: __d = 1, e: __f = 2, ...__g } = (useFoo())`
+  )
+  expect(code).toMatch(`let { foo: __foo } = (useSomthing(() => 1))`)
+  expect(code).toMatch(`\nconst a = _ref(__a);`)
+  expect(code).not.toMatch(`\nconst b = _ref(__b);`)
+  expect(code).toMatch(`\nconst c = _ref(__c);`)
+  expect(code).toMatch(`\nconst d = _ref(__d);`)
+  expect(code).not.toMatch(`\nconst e = _ref(__e);`)
+  expect(code).toMatch(`\nconst f = _ref(__f);`)
+  expect(code).toMatch(`\nconst g = _ref(__g);`)
+  expect(code).toMatch(`\nconst foo = _ref(__foo);`)
+  expect(code).toMatch(
+    `console.log(n.value, a.value, c.value, d.value, f.value, g.value, foo.value)`
+  )
+  expect(rootVars).toStrictEqual(['n', 'a', 'c', 'd', 'f', 'g', 'foo'])
+  assertCode(code)
+})
+
+test('array destructure', () => {
+  const { code, rootVars } = transform(`
+    let n = $ref(1), [a, b = 1, ...c] = $(useFoo())
+    console.log(n, a, b, c)
+    `)
+  expect(code).toMatch(`let n = _ref(1), [__a, __b = 1, ...__c] = (useFoo())`)
+  expect(code).toMatch(`\nconst a = _ref(__a);`)
+  expect(code).toMatch(`\nconst b = _ref(__b);`)
+  expect(code).toMatch(`\nconst c = _ref(__c);`)
+  expect(code).toMatch(`console.log(n.value, a.value, b.value, c.value)`)
+  expect(rootVars).toStrictEqual(['n', 'a', 'b', 'c'])
+  assertCode(code)
+})
+
+test('nested destructure', () => {
+  const { code, rootVars } = transform(`
+    let [{ a: { b }}] = $(useFoo())
+    let { c: [d, e] } = $(useBar())
+    console.log(b, d, e)
+    `)
+  expect(code).toMatch(`let [{ a: { b: __b }}] = (useFoo())`)
+  expect(code).toMatch(`let { c: [__d, __e] } = (useBar())`)
+  expect(code).not.toMatch(`\nconst a = _ref(__a);`)
+  expect(code).not.toMatch(`\nconst c = _ref(__c);`)
+  expect(code).toMatch(`\nconst b = _ref(__b);`)
+  expect(code).toMatch(`\nconst d = _ref(__d);`)
+  expect(code).toMatch(`\nconst e = _ref(__e);`)
+  expect(rootVars).toStrictEqual(['b', 'd', 'e'])
+  assertCode(code)
+})
+
+test('$$', () => {
+  const { code } = transform(`
+    let a = $ref(1)
+    const b = $$(a)
+    const c = $$({ a })
+    callExternal($$(a))
+    `)
+  expect(code).toMatch(`const b = (a)`)
+  expect(code).toMatch(`const c = ({ a })`)
+  expect(code).toMatch(`callExternal((a))`)
+  assertCode(code)
+})
+
+test('nested scopes', () => {
+  const { code, rootVars } = transform(`
+    let a = $ref(0)
+    let b = $ref(0)
+    let c = 0
+
+    a++ // outer a
+    b++ // outer b
+    c++ // outer c
+
+    function foo({ a }) {
+      a++ // inner a
+      b++ // inner b
+      let c = $ref(0)
+      c++ // inner c
+      let d = $ref(0)
+
+      const bar = (c) => {
+        c++ // nested c
+        d++ // nested d
+      }
+
+      if (true) {
+        let a = $ref(0)
+        a++ // if block a
+      }
+
+      return $$({ a, b, c, d })
+    }
+    `)
+  expect(rootVars).toStrictEqual(['a', 'b'])
+
+  expect(code).toMatch('a.value++ // outer a')
+  expect(code).toMatch('b.value++ // outer b')
+  expect(code).toMatch('c++ // outer c')
+
+  expect(code).toMatch('a++ // inner a') // shadowed by function arg
+  expect(code).toMatch('b.value++ // inner b')
+  expect(code).toMatch('c.value++ // inner c') // shadowed by local ref binding
+
+  expect(code).toMatch('c++ // nested c') // shadowed by inline fn arg
+  expect(code).toMatch(`d.value++ // nested d`)
+
+  expect(code).toMatch(`a.value++ // if block a`) // if block
+
+  expect(code).toMatch(`return ({ a, b, c, d })`)
+  assertCode(code)
+})
+
+//#4062
+test('should not rewrite type identifiers', () => {
+  const { code } = transform(
+    `const props = defineProps<{msg: string; ids?: string[]}>()
+        let ids = $ref([])`,
+    {
+      parserPlugins: ['typescript']
+    }
+  )
+  expect(code).not.toMatch('.value')
+  assertCode(code)
+})
+
+// #4254
+test('handle TS casting syntax', () => {
+  const { code } = transform(
+    `
+      let a = $ref(1)
+      console.log(a!)
+      console.log(a! + 1)
+      console.log(a as number)
+      console.log((a as number) + 1)
+      console.log(<number>a)
+      console.log(<number>a + 1)
+      console.log(a! + (a as number))
+      console.log(a! + <number>a)
+      console.log((a as number) + <number>a)
+      `,
+    {
+      parserPlugins: ['typescript']
+    }
+  )
+  expect(code).toMatch('console.log(a.value!)')
+  expect(code).toMatch('console.log(a.value as number)')
+  expect(code).toMatch('console.log(<number>a.value)')
+  assertCode(code)
+})
+
+describe('errors', () => {
+  test('non-let $ref declaration', () => {
+    expect(() => transform(`const a = $ref(1)`)).toThrow(
+      `$ref() bindings can only be declared with let`
+    )
+  })
+
+  test('$ref w/ destructure', () => {
+    expect(() => transform(`let { a } = $ref(1)`)).toThrow(
+      `cannot be used with destructure`
+    )
+  })
+
+  test('$computed w/ destructure', () => {
+    expect(() => transform(`let { a } = $computed(() => 1)`)).toThrow(
+      `cannot be used with destructure`
+    )
+  })
+
+  test('warn usage in non-init positions', () => {
+    expect(() =>
+      transform(
+        `let bar = $ref(1)
+          bar = $ref(2)`
+      )
+    ).toThrow(`$ref can only be used as the initializer`)
+
+    expect(() => transform(`let bar = { foo: $computed(1) }`)).toThrow(
+      `$computed can only be used as the initializer`
+    )
+  })
+})

packages/ref-transform/api-extractor.json

@@ -0,0 +1,7 @@
+{
+  "extends": "../../api-extractor.json",
+  "mainEntryPointFilePath": "./dist/packages/<unscopedPackageName>/src/index.d.ts",
+  "dtsRollup": {
+    "publicTrimmedFilePath": "./dist/<unscopedPackageName>.d.ts"
+  }
+}

packages/ref-transform/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@vue/ref-transform",
+  "version": "3.2.4",
+  "description": "@vue/ref-transform",
+  "main": "dist/ref-transform.cjs.js",
+  "files": [
+    "dist"
+  ],
+  "buildOptions": {
+    "formats": [
+      "cjs"
+    ],
+    "prod": false
+  },
+  "types": "dist/ref-transform.d.ts",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vuejs/vue-next.git",
+    "directory": "packages/ref-transform"
+  },
+  "keywords": [
+    "vue"
+  ],
+  "author": "Evan You",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/vuejs/vue-next/issues"
+  },
+  "homepage": "https://github.com/vuejs/vue-next/tree/dev/packages/ref-transform#readme",
+  "dependencies": {
+    "@vue/compiler-core": "3.2.4",
+    "@vue/shared": "3.2.4",
+    "@babel/parser": "^7.15.0",
+    "estree-walker": "^2.0.2"
+  },
+  "devDependencies": {
+    "@babel/core": "^7.15.0"
+  }
+}

packages/ref-transform/src/babelPlugin.ts

@@ -0,0 +1,3 @@
+export function plugin() {
+  // TODO
+}

packages/ref-transform/src/index.ts

@@ -0,0 +1,368 @@
+import {
+  Node,
+  Identifier,
+  VariableDeclarator,
+  BlockStatement,
+  CallExpression,
+  ObjectPattern,
+  VariableDeclaration,
+  ArrayPattern
+} from '@babel/types'
+import MagicString, { SourceMap } from 'magic-string'
+import { walk } from 'estree-walker'
+import {
+  isFunctionType,
+  isInDestructureAssignment,
+  isStaticProperty,
+  walkBlockDeclarations,
+  walkFunctionParams,
+  walkIdentifiers
+} from '@vue/compiler-core'
+import { parse, ParserPlugin } from '@babel/parser'
+import { babelParserDefaultPlugins } from '@vue/shared'
+
+const TO_VAR_SYMBOL = '$'
+const TO_REF_SYMBOL = '$$'
+const shorthands = ['ref', 'computed', 'shallowRef']
+
+export interface ReactiveDeclarator {
+  node: VariableDeclarator
+  statement: VariableDeclaration
+  ids: Identifier[]
+  isPattern: boolean
+  isRoot: boolean
+}
+
+type Scope = Record<string, boolean>
+
+export interface RefTransformOptions {
+  filename?: string
+  sourceMap?: boolean
+  parserPlugins?: ParserPlugin[]
+  importHelpersFrom?: string
+}
+
+export interface RefTransformResults {
+  code: string
+  map: SourceMap | null
+  rootVars: string[]
+  importedHelpers: string[]
+}
+
+export function transform(
+  src: string,
+  {
+    filename,
+    sourceMap,
+    parserPlugins,
+    importHelpersFrom = 'vue'
+  }: RefTransformOptions = {}
+): RefTransformResults {
+  const ast = parse(src, {
+    sourceType: 'module',
+    plugins: [...babelParserDefaultPlugins, ...(parserPlugins || [])]
+  })
+  const s = new MagicString(src)
+  const res = transformAST(ast, s)
+
+  // inject helper imports
+  if (res.importedHelpers.length) {
+    s.prepend(
+      `import { ${res.importedHelpers
+        .map(h => `${h} as _${h}`)
+        .join(', ')} } from '${importHelpersFrom}'\n`
+    )
+  }
+
+  return {
+    ...res,
+    code: s.toString(),
+    map: sourceMap
+      ? s.generateMap({
+          source: filename,
+          hires: true,
+          includeContent: true
+        })
+      : null
+  }
+}
+
+export function transformAST(
+  ast: Node,
+  s: MagicString,
+  offset = 0
+): {
+  rootVars: string[]
+  importedHelpers: string[]
+} {
+  const importedHelpers = new Set<string>()
+  const blockStack: BlockStatement[] = []
+  const rootScope: Scope = {}
+  const blockToScopeMap = new WeakMap<BlockStatement, Scope>()
+  const excludedIds = new Set<Identifier>()
+  const parentStack: Node[] = []
+
+  const error = (msg: string, node: Node) => {
+    const e = new Error(msg)
+    ;(e as any).node = node
+    throw e
+  }
+
+  const helper = (msg: string) => {
+    importedHelpers.add(msg)
+    return `_${msg}`
+  }
+
+  const registerBinding = (id: Identifier, isRef = false) => {
+    excludedIds.add(id)
+    const currentBlock = blockStack[blockStack.length - 1]
+    if (currentBlock) {
+      const currentScope = blockToScopeMap.get(currentBlock)
+      if (!currentScope) {
+        blockToScopeMap.set(currentBlock, { [id.name]: isRef })
+      } else {
+        currentScope[id.name] = isRef
+      }
+    } else {
+      rootScope[id.name] = isRef
+    }
+  }
+
+  const registerRefBinding = (id: Identifier) => registerBinding(id, true)
+
+  // 1st pass: detect macro callsites and register ref bindings
+  ;(walk as any)(ast, {
+    enter(node: Node, parent?: Node) {
+      parent && parentStack.push(parent)
+
+      if (node.type === 'BlockStatement') {
+        blockStack.push(node)
+        walkBlockDeclarations(node, registerBinding)
+        if (parent && isFunctionType(parent)) {
+          walkFunctionParams(parent, registerBinding)
+        }
+        return
+      }
+
+      const toVarCall = isToVarCall(node)
+      if (toVarCall) {
+        if (!parent || parent.type !== 'VariableDeclarator') {
+          return error(
+            `${toVarCall} can only be used as the initializer of ` +
+              `a variable declaration.`,
+            node
+          )
+        }
+        excludedIds.add((node as CallExpression).callee as Identifier)
+
+        const decl = parentStack[parentStack.length - 2] as VariableDeclaration
+        if (decl.kind !== 'let') {
+          error(`${toVarCall}() bindings can only be declared with let`, node)
+        }
+
+        if (toVarCall === TO_VAR_SYMBOL) {
+          // $
+          // remove macro
+          s.remove(
+            (node as CallExpression).callee.start! + offset,
+            (node as CallExpression).callee.end! + offset
+          )
+          if (parent.id.type === 'Identifier') {
+            // single variable
+            registerRefBinding(parent.id)
+          } else if (parent.id.type === 'ObjectPattern') {
+            processRefObjectPattern(parent.id, decl)
+          } else if (parent.id.type === 'ArrayPattern') {
+            processRefArrayPattern(parent.id, decl)
+          }
+        } else {
+          // shorthands
+          if (parent.id.type === 'Identifier') {
+            registerRefBinding(parent.id)
+            // replace call
+            s.overwrite(
+              node.start! + offset,
+              node.start! + toVarCall.length + offset,
+              helper(toVarCall.slice(1))
+            )
+          } else {
+            error(
+              `${toVarCall}() cannot be used with destructure patterns.`,
+              node
+            )
+          }
+        }
+      }
+    },
+    leave(node: Node, parent?: Node) {
+      parent && parentStack.pop()
+      if (node.type === 'BlockStatement') {
+        blockStack.pop()
+      }
+    }
+  })
+
+  function processRefObjectPattern(
+    pattern: ObjectPattern,
+    statement: VariableDeclaration
+  ) {
+    for (const p of pattern.properties) {
+      let nameId: Identifier | undefined
+      if (p.type === 'ObjectProperty') {
+        if (p.key.start! === p.value.start!) {
+          // shorthand { foo } --> { foo: __foo }
+          nameId = p.key as Identifier
+          s.appendLeft(nameId.end! + offset, `: __${nameId.name}`)
+          if (p.value.type === 'AssignmentPattern') {
+            // { foo = 1 }
+            registerRefBinding(p.value.left as Identifier)
+          }
+        } else {
+          if (p.value.type === 'Identifier') {
+            // { foo: bar } --> { foo: __bar }
+            nameId = p.value
+            s.prependRight(nameId.start! + offset, `__`)
+          } else if (p.value.type === 'ObjectPattern') {
+            processRefObjectPattern(p.value, statement)
+          } else if (p.value.type === 'ArrayPattern') {
+            processRefArrayPattern(p.value, statement)
+          } else if (p.value.type === 'AssignmentPattern') {
+            // { foo: bar = 1 } --> { foo: __bar = 1 }
+            nameId = p.value.left as Identifier
+            s.prependRight(nameId.start! + offset, `__`)
+          }
+        }
+      } else {
+        // rest element { ...foo } --> { ...__foo }
+        nameId = p.argument as Identifier
+        s.prependRight(nameId.start! + offset, `__`)
+      }
+      if (nameId) {
+        registerRefBinding(nameId)
+        // append binding declarations after the parent statement
+        s.appendLeft(
+          statement.end! + offset,
+          `\nconst ${nameId.name} = ${helper('ref')}(__${nameId.name});`
+        )
+      }
+    }
+  }
+
+  function processRefArrayPattern(
+    pattern: ArrayPattern,
+    statement: VariableDeclaration
+  ) {
+    for (const e of pattern.elements) {
+      if (!e) continue
+      let nameId: Identifier | undefined
+      if (e.type === 'Identifier') {
+        // [a] --> [__a]
+        nameId = e
+      } else if (e.type === 'AssignmentPattern') {
+        // [a = 1] --> [__a = 1]
+        nameId = e.left as Identifier
+      } else if (e.type === 'RestElement') {
+        // [...a] --> [...__a]
+        nameId = e.argument as Identifier
+      } else if (e.type === 'ObjectPattern') {
+        processRefObjectPattern(e, statement)
+      } else if (e.type === 'ArrayPattern') {
+        processRefArrayPattern(e, statement)
+      }
+      if (nameId) {
+        registerRefBinding(nameId)
+        // prefix original
+        s.prependRight(nameId.start! + offset, `__`)
+        // append binding declarations after the parent statement
+        s.appendLeft(
+          statement.end! + offset,
+          `\nconst ${nameId.name} = ${helper('ref')}(__${nameId.name});`
+        )
+      }
+    }
+  }
+
+  // 2nd pass: detect references to ref bindings and append .value
+  // also remove $$ calls
+  walkIdentifiers(
+    ast,
+    (id, parent, parentStack, isReferenced) => {
+      if (!isReferenced || excludedIds.has(id)) {
+        return false
+      }
+      // locate current scope
+      let i = parentStack.length
+      while (i--) {
+        const node = parentStack[i]
+        if (node.type === 'BlockStatement') {
+          const scope = blockToScopeMap.get(node)
+          if (scope && checkRefId(scope, id, parent, parentStack)) {
+            return
+          }
+        }
+      }
+      checkRefId(rootScope, id, parent, parentStack)
+    },
+    node => {
+      if (isToRefCall(node)) {
+        s.remove(node.callee.start! + offset, node.callee.end! + offset)
+        return false // skip walk
+      }
+    },
+    true, // invoke on ALL
+    false // skip scope analysis since we did it already
+  )
+
+  function checkRefId(
+    scope: Scope,
+    id: Identifier,
+    parent: Node,
+    parentStack: Node[]
+  ): boolean {
+    if (id.name in scope) {
+      if (scope[id.name]) {
+        if (isStaticProperty(parent) && parent.shorthand) {
+          // let binding used in a property shorthand
+          // { foo } -> { foo: foo.value }
+          // skip for destructure patterns
+          if (
+            !(parent as any).inPattern ||
+            isInDestructureAssignment(parent, parentStack)
+          ) {
+            s.appendLeft(id.end! + offset, `: ${id.name}.value`)
+          }
+        } else {
+          s.appendLeft(id.end! + offset, '.value')
+        }
+      }
+      return true
+    }
+    return false
+  }
+
+  return {
+    rootVars: Object.keys(rootScope),
+    importedHelpers: [...importedHelpers]
+  }
+}
+
+function isToVarCall(node: Node): string | false {
+  if (node.type !== 'CallExpression' || node.callee.type !== 'Identifier') {
+    return false
+  }
+  const callee = node.callee.name
+  if (callee === TO_VAR_SYMBOL) {
+    return TO_VAR_SYMBOL
+  }
+  if (callee[0] === TO_VAR_SYMBOL && shorthands.includes(callee.slice(1))) {
+    return callee
+  }
+  return false
+}
+
+function isToRefCall(node: Node): node is CallExpression {
+  return (
+    node.type === 'CallExpression' &&
+    (node.callee as Identifier).name === TO_REF_SYMBOL
+  )
+}