BREAKING change noPreserveState to preserveLocalState (default false), & add variable level preservation of state

Author: rixo

README.md

@@ -29,32 +29,66 @@ By default, `svelte-hmr` will trigger a full browser reload when it detects an e
 
 #### noPreserveState
 
+**Deprecated: removed and default changed from version 0.12. Use `preserveState` instead.**
+
+#### preserveState
+
 Type: `bool`<br>
 Default: `false`
 
-Prevent preserving the state of the component (i.e. value of props and `let` variables) across HMR updates.
-
-Note that, independently of this option, the state of child components of a component that is impacted by a HMR update will never be preserved beyond what is re-injected by props, and the state of parent / sibling components will always be preserved (more accurately: parent and siblings are not affected by HMR updates). Read the HMR explanation bellow if you want to understand why.
+Enable [preservation of local state](#preservation-of-local-state) for all variables in all components.
 
 #### noPreserveStateKey
 
 Type: `string`<br>
-Default: `'@!hmr'`
+Default: `'@hmr:reset'` (also accepts legacy `'@!hmr'`)
 
-Escape hatch from preservation of local state. There are some situation where preservation of state gets in the way, typically when you want to change the initial / default value of a prop or local variable. If this string appears anywhere in the component's code, then state won't be preserved for this update.
+Force disable preservation of local state for this component.
 
-You'd generally use it with a quick comment right where you are currently editing the code, and remove it just after saving the file:
+This flag has priority over all other settings of state preservation. If it is present, all the state of the component will be reset on the next update, regardless of the value of all the other state preservation settings.
 
-```js
-let answer = 42 // @!hmr
+```svelte
+<!-- @hmr:reset -->
+
+<script>
+  '@hmr:reset'
+
+  // @hmr:reset
+</script>
 ```
 
-But you can also make it more permanent if you find that some of your components don't play with state preservation. Maybe use a noop string to clearly manifest your intention?
+#### preserveAllLocalStateKey
+
+Type: `string`<br>
+Default: `'@hmr:keep-all'`
+
+Force preservation of all local variables of this component.
 
 ```svelte
+<!-- @hmr:keep-all -->
+
 <script>
-  '@!hmr'
-  ...
+  '@hmr:keep-all'
+
+  // @hmr:keep-all
+</script>
+```
+
+#### preserveLocalStateKey
+
+Type: `string`<br>
+Default: `'@hmr:keep'`
+
+Force preservation of a given local variable in this component.
+
+```svelte
+<script>
+  // @hmr:keep
+  let x = 0
+
+  let y = 0 // @hmr:keep
+
+  x = 1 // @hmr:keep
 </script>
 ```
 
@@ -118,7 +152,9 @@ Now, the best way to see what it can do for you is probably to checkout the temp
 
 ### Preservation of local state
 
-Local state is preserved by Svelte HMR, that is any state that Svelte itself tracks as reactive (basically any root scope `let` vars, exported or not).
+**From version 0.12** this behaviour has been deemed too confusing and hard to anticipate, so preservation of state is now disabled by default, and some escape hatches to preserve the state of some given variables have been added.
+
+Local state can be preserved by Svelte HMR, that is any state that Svelte itself tracks as reactive (basically any root scope `let` vars, exported or not).
 
 This means that in code like this:
 
@@ -133,9 +169,25 @@ This means that in code like this:
 
 If you replace `let x = 1` by `let x = 10` and save, the previous value of `x` will be preserved. That is, `x` will be 2 and not 10. The restoration of previous state happens _after_ the init code of the component has run, so the value will not be 11 either, despite the `x++` that is still here.
 
-If you find this behaviour inconvenient, you can disable it by setting `noPreserveState` option of your HMR-enabled bundler plugin.
+If you want this behaviour for all the state of all your components, you can enable it by setting the `preserveLocalState` option to `true`.
+
+If you then want to disable it for just one particular file, or just temporarily, you can turn it off by adding a `// @hmr:reset` comment somewhere in your component.
 
-If you want to disable it for just one particular file, or just temporarily, you can turn it off by adding a `// @!hmr` comment somewhere in your component.
+On the contrary, if you keep the default `preserveLocalState` to `false`, you can enable preservation of all the local state of a given component by adding the following comment: `// @hmr:keep-all`. You can also preserve only the state of some specific variables, by annotating them with: `// @hmr:keep`.
+
+For example:
+
+```svelte
+<script>
+  let x = 0 // @hmr:keep
+
+  // or:
+
+  // @hmr:keep
+  let y = 1,
+      z = 2
+</script>
+```
 
 ## Svelte HMR tools
 

lib/make-hot.js

@@ -4,11 +4,19 @@ const globalName = '___SVELTE_HMR_HOT_API'
 const globalAdapterName = '___SVELTE_HMR_HOT_API_PROXY_ADAPTER'
 
 const defaultHotOptions = {
-  // don't preserve local state
-  noPreserveState: false,
-  // escape hatch from preserve local state -- if this string appears anywhere
-  // in the component's code, then state won't be preserved for this update
-  noPreserveStateKey: '@!hmr',
+  // preserve all local state
+  preserveLocalState: false,
+
+  // escape hatchs from preservation of local state
+  //
+  // disable preservation of state for this component
+  noPreserveStateKey: ['@hmr:reset', '@!hmr'],
+  // enable preservation of state for all variables in this component
+  preserveAllLocalStateKey: '@hmr:keep-all',
+  // enable preservation of state for a given variable (must be inline or
+  // above the target variable or variables; can be repeated)
+  preserveLocalStateKey: '@hmr:keep',
+
   // don't reload on fatal error
   noReload: false,
   // try to recover after runtime errors during component init
@@ -183,6 +191,116 @@ const isProp = v => v.export_name && !v.module
 // meta can be 'import.meta' or 'module'
 // const createMakeHot = (hotApi = defaultHotApi, options) => {
 const createMakeHot = ({ walk, meta = 'import.meta', hotApi, adapter }) => {
+  const resolvePreserveLocalStateKey = ({
+    preserveLocalStateKey,
+    compiled,
+  }) => {
+    const containsKey = comments =>
+      comments &&
+      comments.some(({ value }) => value.includes(preserveLocalStateKey))
+
+    const variables = new Set()
+
+    const addReference = node => {
+      if (!node.name) {
+        // eslint-disable-next-line no-console
+        console.warn('Incorrect identifier for preserveLocalStateKey')
+      }
+      variables.add(node.name)
+    }
+
+    const processNodes = targets => targets.forEach(processNode)
+
+    const processNode = node => {
+      switch (node.type) {
+        case 'Identifier':
+          variables.add(node.name)
+          return true
+        case 'UpdateExpression':
+          addReference(node.argument)
+          return true
+        case 'VariableDeclarator':
+          addReference(node.id)
+          return true
+        case 'AssignmentExpression':
+          processNode(node.left)
+          return true
+        case 'ExpressionStatement':
+          processNode(node.expression)
+          return true
+
+        case 'VariableDeclaration':
+          processNodes(node.declarations)
+          return true
+        case 'SequenceExpression': // ++, --
+          processNodes(node.expressions)
+          return true
+      }
+      return false
+    }
+
+    const stack = []
+
+    if (compiled.ast.instance) {
+      walk(compiled.ast.instance, {
+        leave() {
+          stack.shift()
+        },
+        enter(node) {
+          stack.unshift(node)
+          if (
+            containsKey(node.leadingComments) ||
+            containsKey(node.trailingComments)
+          ) {
+            stack
+              .slice(0, 3)
+              .reverse()
+              .some(processNode)
+          }
+        },
+      })
+    }
+
+    return [...variables]
+  }
+
+  const resolvePreserveLocalState = ({
+    hotOptions,
+    originalCode,
+    compiled,
+  }) => {
+    const {
+      preserveLocalState,
+      noPreserveStateKey,
+      preserveLocalStateKey,
+      preserveAllLocalStateKey,
+    } = hotOptions
+    if (originalCode) {
+      const hasKey = key => {
+        const test = k => originalCode.indexOf(k) !== -1
+        return Array.isArray(key) ? key.some(test) : test(key)
+      }
+      // noPreserveStateKey
+      if (noPreserveStateKey && hasKey(noPreserveStateKey)) {
+        return false
+      }
+      // preserveAllLocalStateKey
+      if (preserveAllLocalStateKey && hasKey(preserveAllLocalStateKey)) {
+        return true
+      }
+      // preserveLocalStateKey
+      if (preserveLocalStateKey && hasKey(preserveLocalStateKey)) {
+        // returns an array of variable names to preserve
+        return resolvePreserveLocalStateKey({ preserveLocalStateKey, compiled })
+      }
+    }
+    // preserveLocalState
+    if (preserveLocalState) {
+      return true
+    }
+    return false
+  }
+
   const hasAccessorsOption = compiled => {
     if (!compiled.ast || !compiled.ast.html) return
     let accessors = false
@@ -276,13 +394,13 @@ const createMakeHot = ({ walk, meta = 'import.meta', hotApi, adapter }) => {
 
     const { importAdapterName } = hotOptions
 
-    const noPreserveState =
-      hotOptions.noPreserveState ||
-      (hotOptions.noPreserveStateKey &&
-        originalCode &&
-        originalCode.indexOf(hotOptions.noPreserveStateKey) !== -1)
+    const preserveLocalState = resolvePreserveLocalState({
+      hotOptions,
+      originalCode,
+      compiled,
+    })
 
-    const options = JSON.stringify({ ...hotOptions, noPreserveState })
+    const options = JSON.stringify({ ...hotOptions, preserveLocalState })
 
     const adapterImport = adapter || resolveAdapterImport(hotOptions)
 

runtime/proxy.js

@@ -126,7 +126,7 @@ class ProxyComponent {
       Adapter,
       id,
       debugName,
-      current, // { Component, hotOptions: { noPreserveState, ... } }
+      current, // { Component, hotOptions: { preserveLocalState, ... } }
       register,
     },
     options // { target, anchor, ... }
@@ -158,8 +158,8 @@ class ProxyComponent {
         adapter.rerender()
       } else {
         try {
-          const noPreserveState = current.hotOptions.noPreserveState
-          const replaceOptions = { target, anchor, noPreserveState }
+          const preserveLocalState = current.hotOptions.preserveLocalState
+          const replaceOptions = { target, anchor, preserveLocalState }
           if (conservativeDestroy) {
             replaceOptions.conservativeDestroy = true
           }

runtime/svelte-hooks.js

@@ -81,10 +81,18 @@ export const createProxiedComponent = (
 
   const isCurrent = _cmp => cmp === _cmp
 
-  const assignOptions = (target, anchor, restore, noPreserveState) => {
+  const assignOptions = (target, anchor, restore, preserveLocalState) => {
     const props = Object.assign({}, options.props)
-    if (!noPreserveState && restore.state) {
-      props.$$inject = restore.state
+    if (preserveLocalState && restore.state) {
+      if (Array.isArray(preserveLocalState)) {
+        // form ['a', 'b'] => preserve only 'a' and 'b'
+        props.$$inject = {}
+        for (const key of preserveLocalState) {
+          props.$$inject[key] = restore.state[key]
+        }
+      } else {
+        props.$$inject = restore.state
+      }
     } else {
       delete props.$$inject
     }
@@ -116,12 +124,12 @@ export const createProxiedComponent = (
       {
         target = options.target,
         anchor = options.anchor,
-        noPreserveState,
+        preserveLocalState,
         conservative = false,
       }
     ) => {
       const restore = captureState(targetCmp)
-      assignOptions(target, anchor, restore, noPreserveState)
+      assignOptions(target, anchor, restore, preserveLocalState)
       const previous = cmp
       if (conservative) {
         try {