---
title: Breaking changes
slug: oip-next/bmKV-breaking-changes
icon: {"lucideIcon":"📘"}
createdAt: 2025-12-10T11:02:34.000Z
---

# 1. Gestion des entités et CRUD

## 1.1 Travail entité par entité

Chaque entité dispose désormais de fonctions de manipulation dédiées.

- Pour une entité `Foo` :
  - `$Foo` pour la **recherche**,
  - `updateFoo` pour l’**enregistrement**,
  - `deleteFoo` pour la **suppression**.

En v4, ces fonctions travaillent **directement sur la base de données** et non plus en mémoire.
Il n’est plus nécessaire d’appeler la méthode d’enregistrement de l’entité `Project` pour persister les sous-entités.

## 1.2 Nouvelle syntaxe

```javascript
const company = await $Company(project, 123); // Recherche d'une Company par son id
await updateCompany(company);                // Sauvegarde de l'entité Company
```

## 1.3 Évolution des méthodes CRUD

| OIP v3                         | OIP v4       |
| ------------------------------ | ------------ |
| `Entities('X').save('Y', X)`   | `updateX(x)` |
| `Entities('X').delete('Y', X)` | `deleteX(x)` |

***

# 2. Gestion des propriétés des entités (setters)

## 2.1 Comportement en v3

En OIP v3, les setters (par exemple `setProjectCode`) modifiaient directement l’objet passé en paramètre (**mutation in-place**) :

```javascript
setProjectCode('GO', project);
await Entities('Project').save(project);
```

- L’objet `project` était modifié directement.
- Il n’était pas nécessaire de réassigner la variable.

## 2.2 Comportement en v4

En OIP v4, les setters sont **purs** (immutables) :

- ils ne modifient plus l’objet d’origine,
- ils retournent une **nouvelle instance** avec la modification appliquée.

```javascript
project = setProjectCode('GO', project);
await updateProject(project);
```

## 2.3 Synthèse

Les setters :

- ne produisent plus d’effets de bord implicites,
- rendent les changements explicites (réaffectation obligatoire),
- préparent un typage plus fort et des optimisations internes (undo/redo, diff, transactions, etc.).

***

# 3. Enregistrement des entités `Project` et sous-entités

## 3.1 Comportement en v3

L’appel à la fonction `save` sur l’entité `Project` permettait d’enregistrer :

- l’entité `Project`,
- ainsi que **toutes ses sous-entités**.

```javascript
await Entities('Project').save(project);
```

## 3.2 Comportement en v4

En OIP v4 :

- `updateProject(project)` ne met à jour **que** l’entité `Project` ;
- chaque entité dispose de sa **fonction de sauvegarde dédiée**.

```javascript
await updateProject(project); // Met à jour l'entité Project
await updateCompany(company); // Met à jour l'entité Company
```

Il est nécessaire d’appeler les fonctions de mise à jour pour chaque entité concernée.

***

# 4. Gestion du contexte (`resolveContext`)

## 4.1 Comportement en v3

En v3, le contexte était passé directement par le développeur aux fonctions.

## 4.2 Comportement en v4

En v4 :

- le serveur **résout le contexte** (par défaut ou via un callback),
- il y ajoute `sessionId`,
- puis appelle la résolution de projet (`resolveProjectFromContext`) avec un seul objet `args`.

***

# 5. Contrôle de session

## 5.1 Variables de configuration

| OIP v3                      | OIP v4           |
| --------------------------- | ---------------- |
| `SESSION_CHECKING_DISABLED` | `SECURE_SESSION` |

- La variable `SECURE_SESSION` remplace le comportement de `SESSION_CHECKING_DISABLED`.

***

# 6. Migration `businessRoute` → `routes`

En v3, il était possible de définir des routes métier spécifiques via la propriété `businessRoute` dans la configuration serveur (`serverConfig`).

En v4, cette propriété est renommée `routes`.

***

# 7. Évolutions du hook `useProcess`

## 7.1 Handlers exposés

| v3         | v4         |
| ---------- | ---------- |
| `onAction` | ❌ supprimé |
| `onNext`   | ✅ conservé |
| `onPrev`   | ✅ conservé |

- `onAction`, qui combinait les comportements de `onNext` et `onPrev`, a été supprimé.
- Il faut désormais appeler explicitement la méthode correspondant à la transition souhaitée (`onNext` ou `onPrev`).

## 7.2 Nouvelle signature des handlers

### Avant (v3)

```javascript
onNext({ context });
```

### Après (v4)

```javascript
onNext({ transitionData, resolvedViewData });
```

- `transitionData?` : données utilisées pour la résolution de la transition,
- `resolvedViewData?` : données injectées dans la vue suivante.

***

# 8. Fragment `ProcessFragment` (rappel)

Comme indiqué dans la page *Conventions & outils* :

- `metadata` → `viewData`

Ce changement impacte les fragments GraphQL utilisés côté client.

***

# 9. Synthèse des principaux breaking changes

| Thème               | v3                                  | v4                                          |
| ------------------- | ----------------------------------- | ------------------------------------------- |
| Exports app         | `start, useProcess, Router, Tokens` | `start, useProcess, Router`                 |
| Fragment process    | `metadata`                          | `viewData`                                  |
| Custom handlers     | `useCustomHandlers` (hook)          | `customHandlers` (objet)                    |
| Contexte            | `ctx` + `ctxPolicy`                 | `ctx` unique                                |
| ID racine           | `rootDivId`                         | `rootElementId`                             |
| Pages d’erreur      | 5 props séparées                    | propriété unique `errorPages`               |
| Router              | `bundle`                            | `views`                                     |
| Handlers de process | `onAction`, `onNext`, `onPrev`      | `onNext`, `onPrev`                          |
| Signature handlers  | `{ context }`                       | `{ transitionData?, resolvedViewData? }`    |
| Setters entités     | mutation in-place                   | setters immutables (retour nouvelle entité) |
