"},{"ID":3801,"user_firstname":"Andy","user_lastname":"Gup","nickname":"andygup","user_nicename":"andygup","display_name":"Andy Gup","user_email":"agup@esri.com","user_url":"http:\/\/www.andygup.net","user_registered":"2018-03-02 00:15:25","user_description":"I spend a ton of time outdoors and when not on a mountain somewhere I'm a Sr. Product Engineer for the ArcGIS Maps SDK for JavaScript. I work on ES modules, 3rd party JavaScript frameworks, and other cool mapping-related goodies.","user_avatar":"
"},{"ID":293472,"user_firstname":"Lauren","user_lastname":"Boyd","nickname":"Lauren Boyd","user_nicename":"lauren-boyd","display_name":"Lauren Boyd","user_email":"LBoyd@esri.com","user_url":"https:\/\/github.com\/lboyd93","user_registered":"2021-11-20 01:01:42","user_description":"Lauren is a Senior Product Engineer on the ArcGIS Maps SDK for JavaScript team in Redlands, CA with her work focusing primarily on popups and security. She has worked at Esri for over 8 years and enjoys helping\/supporting geo-developers utilize the JavaScript Maps SDK into their awesome applications.","user_avatar":"
"}],"short_description":"Information on the benefits of using reactiveUtils over watchUtils with the ArcGIS Maps SDK for JavaScript.","flexible_content":[{"acf_fc_layout":"content","content":"Observing for changes is one of the most important aspects of managing application life-cycle. At version 4.23 (March 2022) we introduced a new module to the ArcGIS Maps SDK for JavaScript (JavaScript Maps SDK) called reactiveUtils<\/a> to provide developers with significantly improved watch tooling. This module contains utilities for observing changes in the state of properties using reactivity<\/a>, which is based on the concepts of reactive programming. It is meant to replace the deprecated watchUtils module, and its utilities have a wider range of capabilities, such as the ability to watch almost anything, being TypeScript safe and more scalable. In this blog post, we will highlight some of the differences between the two modules and explain why you should migrate your app to these new utilities.<\/p>\n <\/p>\n The watchUtils module has been removed at version 4.28.<\/p>\n","image_reference":false,"layout":"standard","image_reference_figure":"","snippet":"","spotlight_name":"","section_title":"","position":"Center","spotlight_image":false},{"acf_fc_layout":"content","content":" When we originally introduced Accessor<\/a> and reactive properties, we didn\u2019t have support for reactivity. Accessor is the parent class for many of the SDKs classes. Developers had to manually specify dependencies between properties. For example, you could use the watchUtils module as follows using a string to set the property name:<\/p>\n The watchUtils pattern is always similar: provide the object to be tracked, one or several of its properties as strings, and a callback which is called when a property changes or when a condition is met.<\/p>\n Let\u2019s see how to implement the same examples with the new reactiveUtils:<\/p>\n As you can see, the pattern is slightly different, you don\u2019t need to specify which properties are to be observed. Instead, we provide a reactive expression as the first argument to the watch() and when() functions. An expression is code that resolves to a value. This expression is evaluated and, when its result changes (in the case of watch) or becomes truthy (in the case of when), the callback is called.<\/p>\n One way to think about it is to compare it to Excel spreadsheet. In an Excel spreadsheet, you can create formulas that reference other cells (properties) and compute a result. The formula is like a reactive expression, and the cell containing the formula (where the result is displayed) is like a reactiveUtils callback, which receives the result of evaluating the reactive expression.<\/p>\n As we can see in the previous examples, we can also provide some options to control how a watch behaves, such as the ReactiveWatchOptions<\/a> properties once<\/em>, sync<\/em>, initial<\/em> and equals<\/em>:<\/p>\n So far, we\u2019ve only seen how we can replicate things which was also possible with watchUtils. However, reactiveUtils are significantly more advanced. We\u2019ll now look at some of the benefits of using the reactiveUtils.<\/p>\n Since we can pass any expression to the reactiveUtils, we can observe almost anything. For example, let\u2019s observe changes in a Collection<\/a>.<\/p>\n With this watch, the callback will be called anytime the list of visible layers changes. If a layer is added\/removed\/moved, the callback will be called with an updated list. And if any of the layers in the Collection has their visible property changed, the callback will also be called with an updated list of layers.<\/p>\n Note, currently reactiveUtils doesn\u2019t support observing native arrays, Map<\/a> or Set<\/a>.<\/p>\n One of the key benefits of using reactiveUtils<\/a> is that it automatically tracks and manages dependencies between different Accessor properties and your application. With reactiveUtils, you never reference properties by name like you do with watchUtils. Instead, any property accessed in a reactive expression is automatically tracked and depended on by the watch<\/strong>. This means that you don’t have to worry about forgetting to include a dependency in your watch, because reactiveUtils will automatically track all dependencies for you.<\/p>\n Moreover, reactiveUtils automatically manages dependencies in a dynamic and efficient way. If you modify a reactive expression and it no longer depends on a certain property, that property will no longer be observed, which can save computation time and improve performance. For example, consider the following code:<\/p>\n In this case, the reactive expression contains a conditional operator that depends on the view.stationary<\/a> Boolean property. This means that the watch will always depend on view.stationary, because the conditional is always accessed in the reactive expression. However, the watch will only observe the view.map.layers<\/a> Collection while view.stationary evaluates as true.<\/p>\n Having properties accessed directly in an expression also means that code refactoring tools, such as Typescript, will work out-of-the-box. If you use Typescript to refactor an Accessor property in your code, the change will be automatically propagated throughout your codebase and all reactive watches will continue to work correctly.<\/p>\n In contrast, when using watchUtils, you need to manually update every single watch that specifies a dependency on a property that you are refactoring. This can be error-prone and time-consuming, and it’s easy to forget to update some watches.<\/p>\n Furthermore, reactiveUtils allows Typescript to automatically infer the types of properties in your reactive expression. This means that you don’t have to manually specify the types of the callback arguments, which can save time, reduce or eliminate errors as well as make your code easier to read. For example, consider the following code:<\/p>\n In the first example, we are using watchUtils and we need to manually specify the type of the callback argument. If we modify the type of the fullName property in the User class, we also need to manually update the type in the watch callback. In contrast, the second example is using reactiveUtils and Typescript automatically infers the type of the fullName property based on the return value of the reactive expression. This means that you don’t have to manually specify the type, and if you modify the type in the User class, it will be automatically updated in the watch.<\/p>\n In the reactiveUtils<\/a> API reference page, there are hints as to which reactiveUtils method is recommended as a replacement for each watchUtils method. There is also additional information in the Overview<\/a> section of the reactiveUtils<\/a> API reference.<\/p>\n As we\u2019ve seen, the reactiveUtils provide valuable tools and greater flexibility for responding to changes in API objects and your own Accessor-based objects. They offer enhanced safety and bug prevention, and when used with Typescript, facilitate efficient refactoring. Compared to the now removed watchUtils, the reactiveUtils offer a superior solution for managing property and state changes in a wide range of contexts.<\/p>\n"},{"acf_fc_layout":"content","content":" If you want to continue learning about reactivity, here are some recommended readings:<\/p>\nFrom watchUtils to reactiveUtils<\/h2>\n"},{"acf_fc_layout":"sidebar","content":"
\/\/ Call the callback when view.stationary changes.<\/span>\r\nwatchUtils.watch(view, 'stationary'<\/span>, (stationary) => {\r\n \/\/ Do something with the new value<\/span>\r\n});\r\n\/\/ Call the callback when view.interacting or view.navigating change.<\/span>\r\nwatchUtils.watch(view, ['interacting'<\/span>, 'navigating'<\/span>], () => {\r\n \/\/ Do something<\/span>\r\n});\r\n\/\/ Call the callback when the view becomes stationary.<\/span>\r\nwatchUtils.when(view, 'stationary'<\/span>, () => {\r\n \/\/ Do something when the view becomes stationary.<\/span>\r\n});\r\n\/\/ Call the callback when the state is equal to \u201cready\u201d<\/span>\r\nwatchUtils.whenEqualOnce(widget, 'state'<\/span>, 'ready'<\/span>, () => {\r\n \/\/ Do something when the state is \u201cready\u201d.<\/span>\r\n});\r\n<\/code><\/pre>\n\/\/ Call the callback when a property changes.<\/span>\r\nreactiveUtils.watch(\r\n () => view.stationary, \r\n (stationary) => {\r\n \/\/ Do something with the new value<\/span>\r\n});\r\n\/\/ Call the callback when view.interacting or view.navigating change.<\/span>\r\nreactiveUtils.watch(\r\n () => [view.interacting, view.navigating], \r\n ([interacting, navigating]) => {\r\n \/\/ Do something<\/span>\r\n});\r\n\/\/ Call the callback when the view becomes stationary.<\/span>\r\nreactiveUtils.when(\r\n () => view.stationary, \r\n () => {\r\n \/\/ Do something when the view becomes stationary.<\/span>\r\n});\r\n\/\/ Call the callback when the state is equal to \u201cready\u201d<\/span>\r\nreactiveUtils.when(\r\n () => widget.state === 'ready'<\/span>, \r\n () => {\r\n \/\/ Do something when the state is \u201cready\u201d one time.<\/span>\r\n}, \r\n{ once: true<\/span> });\r\n<\/code><\/pre>\n\/\/ Evaluate the reactive expression and, when it changes, call the callback with the result.<\/span>\r\nreactiveUtils.watch(\r\n reactiveExpression, \r\n (result) => {\r\n \/\/ Do something\r\n }, options);\r\n<\/code><\/pre>\n\/\/ Run synchronously, in the same tick, as soon as a property changes.<\/span>\r\nreactiveUtils.watch(\r\n () => {}, \r\n callback, \r\n { sync: true<\/span> });\r\n\r\n\/\/ Run right away with the initial result of the expression.<\/span>\r\nreactiveUtils.watch(\r\n () => {}, \r\n callback, \r\n { initial: true<\/span> });\r\n\r\n\/\/ Provide a custom equality function. The callback will only be called if<\/span>\r\n\/\/ two consecutive results are not the same.<\/span>\r\nreactiveUtils.watch(\r\n () => {}, \r\n callback, \r\n { equals: (a, b) => a === b});\r\n<\/code><\/pre>\n"},{"acf_fc_layout":"content","content":"Other features and benefits<\/h2>\n
You can observe (almost) anything<\/h3>\n
reactiveUtils.watch(\r\n () => view.map.layers.filter((layer) => layer.visible).toArray(),\r\n (visibleLayers) => {\r\n \/\/ Do something with the visibleLayers Collection\r\n }\r\n);\r\n<\/code><\/pre>\nAutomatic dependencies<\/h3>\n
reactiveUtils.watch(\r\n () => view.stationary ? view.map.layers.toArray() : [],\r\n (layers) => {\r\n \/\/ Do something with the layers\r\n }\r\n);\r\n<\/code><\/pre>\nMuch better refactoring and TypeScript support<\/h3>\n
\/\/ Typescript doesn\u2019t know that fullName is a string, so we need to specify it.<\/span>\r\n\/\/ If you modify the type in the User class, you need to manually update it here.<\/span>\r\nwatchUtils.watch(user, 'fullName'<\/span> ,(fullName: string) => {\r\n \/\/ Do something\r\n});\r\n\r\n\/\/ Typescript automatically infers the type of the return value of the reactive expression.<\/span>\r\nreactiveUtils.watch(\r\n () => user.fullName,\r\n (fullName) => { \/\/ Type inferred as string!\r\n<\/span> \/\/ Do something\r\n }\r\n);\r\n<\/code><\/pre>\nA note about refactoring from watchUtils to reactiveUtils<\/h2>\n
Conclusion<\/h2>\n
\n