Add lazy to watch function

[lhajman]

This pull request introduces a new utility function, lazyWatch, to our reactivity library. This function enables the creation of watchers that can be initialized lazily, allowing for deferred setup until the watcher is explicitly triggered. This enhancement provides greater flexibility in managing the initialization of watchers, potentially optimizing performance in scenarios where immediate setup is not necessary.

Changes

• Added lazyWatch Function:
  • A utility function that facilitates lazy initialization of watchers.
  • Accepts source, callback, and options to configure lazy behavior.
  • Returns a function to initialize the watcher if lazy is true, or sets up the watcher immediately if lazy is false.

Function Signature:

export const lazyWatch = (
  source: any,
  callback: (newVal: any, oldVal: any) => void,
  options: { lazy?: boolean } = { lazy: true },
): LazyWatchReturn | void => {
  if (options.lazy) {
    let initialized = false

    // Return a function that initializes the watcher when invoked
    return () => {
      if (!initialized) {
        initialized = true // Set initialized to true after first call
        watch(source, callback) // Set up the watcher
      }
    }
  } else {
    // If lazy is false, initialize the watcher immediately
    watch(source, callback)
  }
}

Motivation

The lazyWatch function addresses the need for deferred initialization of watchers, which can be beneficial in scenarios where immediate setup of watchers is not desirable. By supporting lazy initialization, developers can have more control over when the watcher setup occurs, which can lead to performance optimizations and more efficient resource usage.

Testing

Unit tests have been created to verify the functionality of the lazyWatch function:

• Lazy Initialization: Ensures that the watcher is not initialized until the returned function is called.
• Immediate Initialization: Validates that watchers are set up immediately when the lazy option is set to false.

Checklist

• [x] The code adheres to the project's coding standards and guidelines.
• [x] Comprehensive tests have been written and successfully passed.
• [x] Documentation has been updated to reflect the new lazyWatch function and its usage.

Additional Notes

Feedback on this enhancement is welcome. The lazyWatch function is designed to improve the flexibility and performance of our reactivity system by allowing deferred initialization of watchers. This feature is expected to benefit scenarios where controlling the timing of watcher activation is critical.

[github-actions[bot]]

Size Report

Bundles

File	Size	Gzip	Brotli
runtime-dom.global.prod.js	101 kB (+121 B)	38.1 kB (+39 B)	34.2 kB (-9 B)
vue.global.prod.js	160 kB (+121 B)	58 kB (+33 B)	51.5 kB (-7 B)

Usages

Name	Size	Gzip	Brotli
createApp (CAPI only)	49 kB	18.9 kB	17.2 kB
createApp	55.8 kB (+131 B)	21.4 kB (+39 B)	19.6 kB (-50 B)
createSSRApp	59.8 kB (+131 B)	23.2 kB (+40 B)	21.1 kB (+42 B)
defineCustomElement	60.5 kB (+131 B)	23 kB (+42 B)	20.9 kB (+32 B)
overall	69.5 kB (+131 B)	26.5 kB (+45 B)	24.1 kB (+44 B)

[edison1105]

• Implementing a new API needs to be discussed through an RFC.
• If lazy is necessary, I prefer the following approach

const { start } = watch(source, callback, { lazy: true })

// start() 

[pkg-pr-new[bot]]

Open in Stackblitz

@vue/compiler-dom

pnpm add https://pkg.pr.new/@vue/compiler-dom@11946

@vue/compiler-core

pnpm add https://pkg.pr.new/@vue/compiler-core@11946

@vue/compiler-sfc

pnpm add https://pkg.pr.new/@vue/compiler-sfc@11946

@vue/compiler-ssr

pnpm add https://pkg.pr.new/@vue/compiler-ssr@11946

@vue/runtime-core

pnpm add https://pkg.pr.new/@vue/runtime-core@11946

@vue/reactivity

pnpm add https://pkg.pr.new/@vue/reactivity@11946

@vue/server-renderer

pnpm add https://pkg.pr.new/@vue/server-renderer@11946

@vue/runtime-dom

pnpm add https://pkg.pr.new/@vue/runtime-dom@11946

@vue/shared

pnpm add https://pkg.pr.new/@vue/shared@11946

vue

pnpm add https://pkg.pr.new/vue@11946

@vue/compat

pnpm add https://pkg.pr.new/@vue/compat@11946

commit: 715201e