perf: replace deep watches with $watchCollection by default (#728)

Author: jtblin

GEMINI.md

@@ -43,6 +43,9 @@ This is a legacy AngularJS 1.x wrapper for Chart.js. It has recently been modern
   - **Scale Configuration**: All examples have been updated to the v4 object-based scale syntax.
   - **Mixed Chart Transparency**: When creating mixed-type charts (e.g., Bar + Line), ensure that bar transparency is explicitly set in the `chart-dataset-override` using `backgroundColor` with an alpha channel (e.g., `rgba(69, 183, 205, 0.2)`). This prevents the library's default color logic from potentially applying a solid color over the intended transparent bar.
 - **Test-Driven Refactoring**: The `ChartJs` service is returned as a fresh object from `$get` instead of an object with getters. This ensures compatibility with mocking libraries like **Sinon**, which can have issues spying on or stubbing getter properties.
+- **Performance Optimization (Shallow Watches)**:
+  - By default, directives now use `$watchCollection` (shallow) for data attributes to avoid the high overhead of recursive deep-equality checks on large datasets.
+  - **Opt-in Deep Watch**: If deep mutations are required, users can set `chart-dataset-watch-deep="true"` on the directive or `datasetWatchDeep: true` globally via `ChartJsProvider`.
 
 ## Deployment & Versioning
 - **Trunk-Based**: Work happens on `main`. Current modernization is stabilized on `release/v3.0.0-rc.1`.

README.md

@@ -73,6 +73,7 @@ Here are the options for all directives:
 - `chart-plugins`: (default: `[]`): array of [Chart.js plugins](http://www.chartjs.org/docs/latest/developers/plugins.html)
 - `chart-display-when-no-data`: (default: `false`): whether to create the chart even if data is empty or undefined
 - `chart-force-update`: (default: `false`): whether to force a chart update even if data references have not changed
+- `chart-dataset-watch-deep`: (default: `false`): whether to use recursive deep watching ($watch with objectEquality: true) for data. By default, the library uses $watchCollection for better performance with large datasets.
 
 There is another directive `chart-base` that takes an extra attribute `chart-type` to define the type
 dynamically. 
@@ -101,6 +102,8 @@ angular.module("app", ["chart.js"])
     ChartJsProvider.setOptions({
       chartColors: ['#FF5252', '#FF8A80'],
       responsive: false,
+      // Enable deep watching for all charts (performance cost on large datasets)
+      datasetWatchDeep: false,
     });
     // Configure all line charts
     ChartJsProvider.setOptions('line', {

docs/MIGRATION.md

@@ -96,3 +96,7 @@ If you are using TypeScript, `angular-chart.js` now provides built-in types. Not
 - **Global `Chart`**: The library no longer attempts to auto-inject Chart.js; it expects the `Chart` class to be available in the environment.
 - **Encapsulated Defaults**: The library no longer mutates `Chart.defaults`. Opinionated defaults are now internal to `ChartJsProvider`. If you relied on `angular-chart.js` to configure other non-Angular charts globally, you must now configure them manually in `Chart.defaults`.
 - **Events**: Event arguments (like `points` in `chart-click`) now match the Chart.js 4.x `ActiveElement` structure.
+- **Watch Strategy (Performance)**:
+  - **Default**: The library now uses `$watchCollection` (shallow watch) for `chart-data`, `chart-labels`, etc. This significantly improves performance for large datasets.
+  - **Action Required**: If you were mutating nested arrays/objects *without* changing the top-level reference, the chart will no longer update automatically.
+  - **Workaround**: Either update the array reference (preferred) or enable deep watching via `chart-dataset-watch-deep="true"` or `ChartJsProvider.setOptions({datasetWatchDeep: true})`.

src/angular-chart.ts

@@ -13,6 +13,7 @@ export interface ChartColor {
 export interface ChartJsProviderOptions extends Partial<ChartOptions> {
   chartAlpha?: number;
   chartFillAlpha?: number;
+  datasetWatchDeep?: boolean;
   [key: string]: unknown;
 }
 
@@ -41,6 +42,7 @@ export interface DirectiveScope extends angular.IScope {
   chartDatasetOverride?: Partial<ChartDataset> | Partial<ChartDataset>[];
   chartPlugins?: Plugin[];
   chartForceUpdate?: boolean;
+  chartDatasetWatchDeep?: boolean;
   chartDisplayWhenNoData?: boolean;
   chart?: Chart;
 }
@@ -172,17 +174,22 @@ function ChartJsFactory(ChartJs: ChartJsService, $timeout: angular.ITimeoutServi
         chartPlugins: '=?',
         chartForceUpdate: '=?',
         chartDisplayWhenNoData: '=?',
+        chartDatasetWatchDeep: '=?',
       },
       link: function(scope: DirectiveScope, elem: angular.IAugmentedJQuery/* , attrs */) {
+        const deepWatch = scope.chartDatasetWatchDeep ?? ChartJs.getOptions().datasetWatchDeep ?? false;
+        const watchFn = deepWatch ? '$watch' : '$watchCollection';
+        const watchEquality = deepWatch ? true : undefined;
+
         // Order of setting "watch" matter
-        scope.$watch('chartData', watchDataUpdate, true);
-        scope.$watch('chartSeries', watchRecreation, true);
-        scope.$watch('chartLabels', watchRecreation, true);
-        scope.$watch('chartOptions', watchOptions, true);
-        scope.$watch('chartColors', watchRecreation, true);
-        scope.$watch('chartDatasetOverride', watchRecreation, true);
+        (scope as any)[watchFn]('chartData', watchDataUpdate, watchEquality);
+        (scope as any)[watchFn]('chartSeries', watchRecreation, watchEquality);
+        (scope as any)[watchFn]('chartLabels', watchRecreation, watchEquality);
+        (scope as any)[watchFn]('chartOptions', watchOptions, watchEquality);
+        (scope as any)[watchFn]('chartColors', watchRecreation, watchEquality);
+        (scope as any)[watchFn]('chartDatasetOverride', watchRecreation, watchEquality);
         scope.$watch('chartType', watchType, false);
-        scope.$watch('chartPlugins', watchRecreation, true);
+        (scope as any)[watchFn]('chartPlugins', watchRecreation, watchEquality);
         scope.$watch('chartDisplayWhenNoData', (newVal, oldVal) => {
           if (newVal === oldVal) {
             return;

test/test.unit.ts

@@ -659,6 +659,74 @@ describe('Unit testing', function() {
             expect(updated).to.be.true;
           });
         });
+
+        describe('chart-dataset-watch-deep (#728)', function() {
+          it('does not update chart on deep data mutations by default', function() {
+            const markup = '<canvas class="chart chart-line" chart-data="data" ' +
+              'chart-labels="labels"></canvas>';
+            scope.labels = ['Monday'];
+            scope.data = [[1]];
+
+            $compile(markup)(scope);
+            scope.$digest();
+
+            let updated = false;
+            scope.$on('chart-update', function() {
+              updated = true;
+            });
+
+            // Deep mutation
+            (scope.data as number[][])[0][0] = 2;
+            scope.$digest();
+
+            expect(updated).to.be.false;
+          });
+
+          it('updates chart on deep data mutations when chart-dataset-watch-deep is true', function() {
+            const markup = '<canvas class="chart chart-line" chart-data="data" ' +
+              'chart-labels="labels" chart-dataset-watch-deep="true"></canvas>';
+            scope.labels = ['Monday'];
+            scope.data = [[1]];
+
+            $compile(markup)(scope);
+            scope.$digest();
+
+            let updated = false;
+            scope.$on('chart-update', function() {
+              updated = true;
+            });
+
+            // Deep mutation
+            (scope.data as number[][])[0][0] = 2;
+            scope.$digest();
+
+            expect(updated).to.be.true;
+          });
+
+          it('updates chart on deep data mutations when datasetWatchDeep is true globally', function() {
+            ChartJsProvider.setOptions({datasetWatchDeep: true});
+            const markup = '<canvas class="chart chart-line" chart-data="data" ' +
+              'chart-labels="labels"></canvas>';
+            scope.labels = ['Monday'];
+            scope.data = [[1]];
+
+            $compile(markup)(scope);
+            scope.$digest();
+
+            let updated = false;
+            scope.$on('chart-update', function() {
+              updated = true;
+            });
+
+            // Deep mutation
+            (scope.data as number[][])[0][0] = 2;
+            scope.$digest();
+
+            expect(updated).to.be.true;
+            // Reset global option for other tests
+            ChartJsProvider.setOptions({datasetWatchDeep: false});
+          });
+        });
       });
     });
   });