@dsivd/prestations-ng 19.0.5-beta.4 → 19.0.5-beta.6

package/ANGULAR_SIGNALS.md

@@ -47,11 +47,16 @@ increment(): void {
 }
 ```
 
-| Method        | Description                       |
-| ------------- | --------------------------------- |
-| `.set(value)` | Replace the value                 |
-| `.update(fn)` | Derive next value from current    |
-| `.mutate(fn)` | Mutate in place (arrays, objects) |
+| Method        | Description                    |
+| ------------- | ------------------------------ |
+| `.set(value)` | Replace the value              |
+| `.update(fn)` | Derive next value from current |
+
+> ⚠️ `.mutate()` is **not** part of the public API. It was part of the
+> original signals proposal but was removed from `WritableSignal` before
+> the stable release — mutating an object without a `.set()`/`.update()`
+> call is invisible to the signal graph. Always produce a new reference
+> via `.update()` (see [pitfall #8](angular-signals#common_pitfalls)).
 
 ---
 
@@ -302,8 +307,10 @@ readonly selectedOption = linkedSignal<string[], string>({
 });
 ```
 
-`previous` contains `{ value: T }` — the last value of the linked signal
-before the source changed, or `undefined` on first run.
+`previous` contains `{ source: S; value: D }` — the previous value of the
+`source` signal **and** the previous value of the linked signal itself, or
+`undefined` on first run. Explicit generic type arguments (`<S, D>`) are
+required as soon as you use `previous`.
 
 ---
 
@@ -393,12 +400,15 @@ Usage in a parent template:
 <!-- two-way -->
 <my-component [(isVisible)]="open" />
 
-<!-- one-way — will cause a compiler error with model() -->
+<!-- one-way binding — compiles fine, but changes made by the -->
+<!-- component are not propagated back to `open` -->
 <my-component [isVisible]="open" />
 ```
 
-> ⚠️ `model()` does not accept one-way `[binding]` alone.
-> Use `input()` if the child never needs to write back to the parent.
+> ⚠️ A one-way `[binding]` on a `model()` input is valid and compiles —
+> it's up to the consumer to decide whether they use the input, the
+> output, or both. It's just pointless if the component never needs to
+> write back: use `input()` instead to communicate intent clearly.
 
 > ⚠️ `model()` holds object values by reference. Mutating a nested property
 > of a `model()`'s value (e.g. `this.address().locality.name = 'x'`) does
@@ -828,15 +838,24 @@ effect(() => {
 });
 ```
 
-### 8. Mutating a `model()`'s nested object instead of reassigning
+### 8. Mutating a signal's value instead of reassigning
 
 This is the signals-era version of "mutating `@Input()` used to work."
 Pre-signals, Zone.js-driven change detection re-read template expressions
-on virtually every async event, so mutating a nested property and letting
-CD "catch it eventually" appeared to work. Signals only propagate on
-`.set()`/`.update()` — mutating `this.address().locality.name = 'x'` is
-invisible to the signal, the template, and any `effect()`/`computed()`
-depending on it.
+on virtually every async event, so mutating a nested property or an array
+in place and letting CD "catch it eventually" appeared to work. Signals
+only notify subscribers on `.set()`/`.update()` — any in-place mutation of
+the value returned by `signal()`/`model()`/`input()` is invisible to the
+signal, the template, and any `effect()`/`computed()` depending on it,
+because the object/array reference never changes and signals compare by
+reference by default.
+
+The fix is always the same shape: read the current value, produce a
+**new top-level reference** with the change applied, and pass that to
+`.set()` or `.update()`. Never call a mutating method or assign a nested
+property directly on `signalOrModel()`.
+
+#### 8a. Nested object property
 
 ```ts
 // 🔴 Silent no-op from the signal's perspective
@@ -848,3 +867,142 @@ this.address.update((current) => ({
     locality: { ...current.locality, name: 'newName' },
 }));
 ```
+
+#### 8b. Two-way binding directly on an array element inside `@for`
+
+Binding `[(model)]` straight to an indexed read of a signal
+(`model()[i]`) is a variant of the same mistake: the "write" side of the
+banana-in-a-box syntax tries to assign into `model()[i]`, which mutates
+the array in place instead of going through `.set()`/`.update()`, so
+nothing propagates and Angular may also warn about an unsupported
+two-way expression.
+
+```html
+<!-- 🔴 Tries to write through model()[i] — mutates in place, breaks reactivity -->
+@for (item of model(); track item.id; let i = $index) {
+<app-address-row [(model)]="model()[i]" />
+}
+
+<!-- 🟢 One-way in, explicit handler out -->
+@for (item of model(); track item.id; let i = $index) {
+<app-address-row [model]="model()[i]" (modelChange)="updateItem(i, $event)" />
+}
+```
+
+```ts
+updateItem(index: number, newValue: NomAdresse): void {
+    this.model.update((current) =>
+        current.map((item, i) => (i === index ? newValue : item)),
+    );
+}
+```
+
+#### 8c. Array mutating methods (`push`, `splice`, `pop`, `shift`, `unshift`, `sort`, `reverse`)
+
+All of these mutate the array in place and return either the mutated
+array, the removed element(s), or nothing — never a new reference. Since
+they operate on `this.model()` (the _value_, not the signal), Angular has
+no way to know the array changed.
+
+```ts
+// 🔴 Adds an item, but the signal reference is untouched — no re-render
+this.model().push({ name: null, address: null });
+
+// 🟢 New array reference via spread
+this.model.update((current) => [...current, { name: null, address: null }]);
+```
+
+```ts
+// 🔴 Removes an item in place — invisible to the signal
+this.model().splice(index, 1);
+
+// 🟢 filter() naturally returns a new array
+this.model.update((current) => current.filter((_, i) => i !== index));
+```
+
+```ts
+// 🔴 Same problem with pop() / shift() / unshift()
+this.model().pop();
+this.model().shift();
+this.model().unshift(newItem);
+
+// 🟢 Equivalent immutable forms
+this.model.update((current) => current.slice(0, -1)); // pop
+this.model.update((current) => current.slice(1)); // shift
+this.model.update((current) => [newItem, ...current]); // unshift
+```
+
+```ts
+// 🔴 sort() / reverse() mutate AND return the same array reference —
+// even risky to combine with spread if you forget it: [...current].sort()
+// mutates the *new* array in place, which is fine, but sorting
+// `this.model()` directly still mutates the one held by the signal
+this.model().sort((a, b) => a.name.localeCompare(b.name));
+
+// 🟢 Copy first, then sort/reverse the copy
+this.model.update((current) =>
+    [...current].sort((a, b) => a.name.localeCompare(b.name)),
+);
+```
+
+#### 8d. Direct index assignment
+
+```ts
+// 🔴 Mutates the array element in place
+this.model()[index] = newValue;
+
+// 🟢 map() to swap out just that index
+this.model.update((current) =>
+    current.map((item, i) => (i === index ? newValue : item)),
+);
+```
+
+#### 8e. `Object.assign()` on the current value
+
+`Object.assign(target, ...)` mutates and returns `target`. Passing
+`this.model()` as the target mutates the value in place, even though the
+call "looks" like it's producing something.
+
+```ts
+// 🔴 target is this.model() itself — mutated in place
+Object.assign(this.model(), { name: 'newName' });
+
+// 🟢 target is a fresh object — this is what Object.assign() is for
+this.model.update((current) => Object.assign({}, current, { name: 'newName' }));
+// or, more idiomatically:
+this.model.update((current) => ({ ...current, name: 'newName' }));
+```
+
+#### 8f. `Map` / `Set` values
+
+`Map` and `Set` are reference types too, and their mutating methods
+(`.set()` on a `Map`, `.add()`/`.delete()` on a `Set`) don't return a new
+`Map`/`Set` — they mutate and return `this`, which is easy to miss since
+`Map.prototype.set` shares a name with `WritableSignal.set`.
+
+```ts
+// 🔴 This is Map.prototype.set, not the signal's — mutates the same Map instance
+this.cache().set(key, value);
+
+// 🟢 Build a new Map from the old one
+this.cache.update((current) => new Map(current).set(key, value));
+```
+
+```ts
+// 🔴 Set.prototype.delete mutates in place
+this.selectedIds().delete(id);
+
+// 🟢 Copy into a new Set, then mutate the copy
+this.selectedIds.update((current) => {
+    const next = new Set(current);
+    next.delete(id);
+    return next;
+});
+```
+
+> 💡 General rule of thumb: if a method's name suggests it changes
+> something "in place" and doesn't hand you back a brand-new
+> object/array/Map/Set, assume it mutates and wrap it in a copy first.
+> When unsure, check the return type — a genuinely immutable operation
+> (`map`, `filter`, `concat`, `slice`, spread) always returns a fresh
+> reference you can pass straight to `.set()`/`.update()`.

package/UPGRADING_V19.md

@@ -1092,7 +1092,7 @@ import rxjs from '@smarttools/eslint-plugin-rxjs';
 import simpleImportSort from 'eslint-plugin-simple-import-sort';
 import prettier from 'eslint-config-prettier';
 import importX from 'eslint-plugin-import-x';
-TODO LHE: publish beta + test + UPDATE EXAMPLE !!!
+import prestationsNgEslint from '@dsivd/prestations-ng/eslint';
 
 export default tseslint.config(
     {
@@ -1123,6 +1123,7 @@ export default tseslint.config(
             rxjs,
             'simple-import-sort': simpleImportSort,
             'import-x': importX,
+            '@dsivd/prestations-ng': prestationsNgEslint,
         },
         processor: angular.processInlineTemplates,
         rules: {
@@ -1143,6 +1144,9 @@ export default tseslint.config(
                     style: 'camelCase',
                 },
             ],
+            '@angular-eslint/no-uncalled-signals': ['error'],
+            '@angular-eslint/prefer-signal-model': ['error'],
+            '@angular-eslint/prefer-signals': ['error'],
 
             // ── @typescript-eslint ───────────────────────────────────────────
             '@typescript-eslint/explicit-function-return-type': [
@@ -1229,6 +1233,9 @@ export default tseslint.config(
             // ── simple-import-sort ───────────────────────────────────────────
             'simple-import-sort/imports': 'error',
             'simple-import-sort/exports': 'error',
+
+            // ── prestations-ng ──────────────────────────────────────────────
+            '@dsivd/prestations-ng/no-direct-signal-mutation': 'error',
         },
     },
 

package/eslint/index.mjs

@@ -0,0 +1,7 @@
+import { noDirectSignalMutation } from './rules/index.mjs';
+
+export default {
+  rules: {
+    'no-direct-signal-mutation': noDirectSignalMutation,
+  },
+};

package/eslint/rules/__tests__/no-direct-signal-mutation.test.mjs

@@ -0,0 +1,98 @@
+import { describe, it } from 'vitest';
+import { RuleTester } from 'eslint';
+import rule from '../no-direct-signal-mutation.mjs';
+
+describe('no-direct-signal-mutation', () => {
+  const ruleTester = new RuleTester({
+    languageOptions: {
+      ecmaVersion: 2020,
+      sourceType: 'module',
+    },
+  });
+
+  it('should validate signal mutation rule', () => {
+    ruleTester.run('no-direct-signal-mutation', rule, {
+      valid: [
+        // Using .update()
+        'model.update((current) => ({ ...current, property: value }))',
+        'this.model.update((current) => ({ ...current, property: value }))',
+        'getSignal().update((current) => ({ ...current, property: value }))',
+
+        // Using .set()
+        'model.set({ property: value })',
+        'this.model.set({ property: value })',
+        'getSignal().set({ property: value })',
+
+        // Regular property assignments
+        'this.property = value',
+        'obj.property = value',
+        'this.obj.property = value',
+
+        // Reading from function calls (no assignment)
+        'model().property',
+        'this.model().property',
+        'getSignal().property',
+
+        // Method calls on function results
+        'model().someMethod()',
+        'this.model().someMethod()',
+        'getSignal().doSomething()',
+
+        // Assignments to non-function results
+        'let x = value',
+        'const obj = { prop: value }',
+        'array[0] = value',
+        'pendingFilesByFormKey.get(formKey).files = []',
+        'this.pendingFilesByFormKey.get(formKey).url = baseUrl',
+        'const autocompleteComponent = viewChild("auto"); autocompleteComponent().inputElement().nativeElement.hidden = true',
+        'component.inputElement().nativeElement.value = ""',
+
+        // Method chaining without assignment
+        'model().update((v) => v).subscribe()',
+
+        // One-way bindings are OK
+        '[model]="model().property"',
+        '[ngModel]="model().comment"',
+      ],
+
+      invalid: [
+        {
+          code: "model().property = value",
+          errors: [{ messageId: 'directMutation' }],
+        },
+        {
+          code: "this.model().property = value",
+          errors: [{ messageId: 'directMutation' }],
+        },
+        {
+          code: "getSignal().property = value",
+          errors: [{ messageId: 'directMutation' }],
+        },
+        {
+          code: "model().nested.property = value",
+          errors: [{ messageId: 'directMutation' }],
+        },
+        {
+          code: "this.model().deeply.nested.property = value",
+          errors: [{ messageId: 'directMutation' }],
+        },
+        {
+          code: "model().property += value",
+          errors: [{ messageId: 'directMutation' }],
+        },
+        {
+          code: "model().property -= value",
+          errors: [{ messageId: 'directMutation' }],
+        },
+        {
+          code: "model().property *= value",
+          errors: [{ messageId: 'directMutation' }],
+        },
+        {
+          code: "model().array[0] = value",
+          errors: [{ messageId: 'directMutation' }],
+        },
+      ],
+    });
+  });
+});

package/eslint/rules/index.mjs

@@ -0,0 +1 @@
+export { default as noDirectSignalMutation } from './no-direct-signal-mutation.mjs';

package/eslint/rules/no-direct-signal-mutation.mjs

@@ -0,0 +1,175 @@
+/**
+ * ESLint rule to detect direct mutations of signal/getter results.
+ * Warns against patterns like: model().property = value
+ * Suggests using .update() or .set() instead.
+ */
+export default {
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Warn on direct property mutations of function call results (signals, getters, etc.)",
+      category: "Best Practices",
+      recommended: true,
+    },
+    messages: {
+      directMutation:
+        "Direct mutation of function call result detected. Use .update() or .set() instead of direct assignment.",
+    },
+  },
+
+  create(context) {
+    const sourceCode = context.sourceCode;
+    const viewQueryFactoryNames = new Set([
+      "viewChild",
+      "viewChildren",
+      "contentChild",
+      "contentChildren",
+    ]);
+    const viewQueryAccessorNames = collectViewQueryAccessorNames(sourceCode.ast);
+
+    return {
+      AssignmentExpression(node) {
+        if (node.left.type !== "MemberExpression") {
+          return;
+        }
+
+        const rootCallExpression = getFirstCallExpression(node.left.object);
+        if (rootCallExpression && isSignalLikeRootCall(rootCallExpression)) {
+          context.report({
+            node,
+            messageId: "directMutation",
+          });
+        }
+      },
+    };
+
+    function isSignalLikeRootCall(node) {
+      if (node.arguments.length !== 0) {
+        return false;
+      }
+
+      // model().prop = ... (local signal-like accessor)
+      if (node.callee.type === "Identifier") {
+        return !viewQueryAccessorNames.has(node.callee.name);
+      }
+
+      // this.model().prop = ... (component/service signal accessor)
+      // component.model().prop = ... should not be assumed to be a signal read.
+      if (node.callee.type === "MemberExpression") {
+        if (node.callee.object?.type !== "ThisExpression") {
+          return false;
+        }
+        return !isViewQueryAccessorCall(node.callee);
+      }
+
+      return false;
+    }
+
+    function isViewQueryAccessorCall(callee) {
+      const calledName = getCalledName(callee);
+      return calledName ? viewQueryAccessorNames.has(calledName) : false;
+    }
+
+    function getCalledName(callee) {
+      if (!callee) {
+        return null;
+      }
+      if (callee.type === "Identifier") {
+        return callee.name;
+      }
+      if (
+        callee.type === "MemberExpression" &&
+        !callee.computed &&
+        callee.property.type === "Identifier"
+      ) {
+        return callee.property.name;
+      }
+      return null;
+    }
+
+    /**
+     * Finds the first/root function call used as the base of a mutation chain.
+     * Examples:
+     * - model().property = x         => model()
+     * - this.model().deep.prop = x   => this.model()
+     * - this.query().el().x = y      => this.query()
+     */
+    function getFirstCallExpression(node) {
+      if (!node) {
+        return null;
+      }
+      if (node.type === "MemberExpression") {
+        return getFirstCallExpression(node.object);
+      }
+      if (node.type === "CallExpression") {
+        if (node.callee.type === "MemberExpression") {
+          const nestedCall = getFirstCallExpression(node.callee.object);
+          return nestedCall || node;
+        }
+        return node;
+      }
+      return null;
+    }
+
+    function collectViewQueryAccessorNames(ast) {
+      const names = new Set();
+
+      walkAst(ast, (node) => {
+        if (
+          node.type === "VariableDeclarator" &&
+          node.id?.type === "Identifier" &&
+          isViewQueryFactoryCall(node.init)
+        ) {
+          names.add(node.id.name);
+          return;
+        }
+
+        if (
+          (node.type === "PropertyDefinition" || node.type === "ClassProperty") &&
+          node.key?.type === "Identifier" &&
+          isViewQueryFactoryCall(node.value)
+        ) {
+          names.add(node.key.name);
+        }
+      });
+
+      return names;
+    }
+
+    function isViewQueryFactoryCall(node) {
+      return (
+        node?.type === "CallExpression" &&
+        node.callee?.type === "Identifier" &&
+        viewQueryFactoryNames.has(node.callee.name)
+      );
+    }
+
+    function walkAst(node, visitor, visited = new WeakSet()) {
+      if (!node || typeof node !== "object") {
+        return;
+      }
+      if (visited.has(node)) {
+        return;
+      }
+      visited.add(node);
+
+      visitor(node);
+
+      for (const key of Object.keys(node)) {
+        // ESLint AST nodes include cyclic parent references.
+        if (key === "parent") {
+          continue;
+        }
+        const child = node[key];
+        if (Array.isArray(child)) {
+          for (const element of child) {
+            walkAst(element, visitor, visited);
+          }
+        } else {
+          walkAst(child, visitor, visited);
+        }
+      }
+    }
+  },
+};