---
title: Gérer les entités
slug: oip-next/v3/gerer-entites
icon: {"lucideIcon":"📘"}
createdAt: 2025-10-13T12:57:03.000Z
---

# Créer une entité Project

```javascript
// Crée en base de données une entité Project
await Entities('Project').create();

// Crée en base de données une entité Project
// avec `externalId == '1234'`
await Entities('Project').create({ externalId: '1234' });
```

***

# Créer et rattacher une entité à son parent

La méthode `save` rattache une entité enfant à son entité parente et enregistre son état en mémoire. Elle renvoie l'entité parente mise à jour avec la nouvelle version de l'entité enfant.

Pour connaître les relations des entités, il faut :

- Consulter leur documentation [ici](https://doc.fasst.tech/oip-core/PH68-liste).
- Consulter le fichier `oip.config.mjs` de l'OAV.

```javascript
// Crée une entité Project
let project = await Entities('Project').create();
// Crée une entité Company
const company = await Entities('Company').create();
// Rattache l'entité Company à l'entité Project
project = await Entities('Company').save(project, company);
```

***

# Récupérer une entité Project

La fonction `get` récupère une entité `Project` à partir de sa propriété `id` ou `externalId`.

```javascript
await Entities('Project').get({ externalId: '1234' });
```

***

# Récupérer une liste d'entités

La fonction `findAll` récupère un tableau d'entités.

```javascript
Entities('Email').findAll(company);
// Le résultat est un tableau de toutes les entités de type 'Email'
// rattachées à l'entité `company`
```

## Filtre

```javascript
Entities('Email').findAll(
  company,
  { filter: ({ value }) => value === 'foo@fasst.io' }
);
// Le résultat est un tableau filtré
// contenant uniquement des éléments
// dont la propriété 'value' est égale à 'foo@fasst.io'
```

## Tri

```javascript
Entities('Email').findAll(
  company,
  { sort: [['type', -1], ['value', 1]]}
);
// Le résultat est un tableau trié
// d'abord par la propriété 'type' (descendant)
// puis par la propriété 'value' (ascendant)
```

## Variantes

### findAllOrCreate

`findAllOrCreate` a la même sémantique et les mêmes options que `findAll`. L'unique différence est que si aucune correspondance n'est trouvée, `findAllOrCreate` crée une nouvelle entité et retourne un tableau la contenant.

***

# Récupérer une entité

La fonction `get` récupère une entité. Si plusieurs entités correspondent, la première est retournée. Si aucune entité ne correspond, la valeur `null` est retournée.

```javascript
Entities('Aml').get(company);
```

## Filtre

```javascript
Entities('Aml').get(
  company,
  { filter: ({ id }) => id === '1234' }
);
```

## Variantes

### getOrCreate

`getOrCreate` a la même sémantique et les mêmes options que `get`. L'unique différence est que si aucune correspondance n'est trouvée, `getOrCreate` crée une nouvelle entité et la retourne.

***

# Enregistrer en base de données l'arbre des entités

La méthode `Project#save` enregistre en base de données l'arbre des entités. Elle renvoie la nouvelle version de l'entité `Project`, avec le statut et l'historique mis à jour.

La valeur `null` est retournée si l'entité `Project` n'existe pas en base de données.&#x20;

```javascript
// Crée une entité Project
let project = await Entities('Project').create();
// Crée une entité Company
const company = await Entities('Company').create();
// Rattache l'entité Company à l'entité Project
project = await Entities('Company').save(project, company);

// Sauvegarde en base de données les entités Project et Company
project = await Entities('Project').save(project);
```

***

# Supprimer une entité de son parent

La méthode `delete` détache une entité de son entité parente.

```javascript
// Crée une entité Project
let project = await Entities('Project').create();
// Crée une entité Company
const company = await Entities('Company').create();
// Rattache l'entité Company à l'entité Project
project = await Entities('Company').save(project, company);

// Détache l'entité `company` de l'entité `project`
const company = await Entities('Company').delete(project, company);
```

***

# Supprimer une entité Project

Trois modes de suppression sont disponibles : `soft`, `hard` et `full`.

Avec le mode `soft` :

- Le statut du projet est positionné à `DELETED`.

Avec le mode `hard` :

- Le statut du projet est positionné à `DELETED`.
- Les liens vers toutes les entités liées sont supprimés.
- Les seules informations de l'entité `Project` conservées sont :
  - `id`
  - `createdAt`
  - `projectNumber`
  - `status`
  - `updatedAt`

Avec le mode full, l'entité `Project` est complètement effacé de la base de données.

```javascript
// Supprime de la base de données l'entité Project
// avec les critères :
// `id === '1234'`
// `mode === 'soft`
await Entities('Project').delete({ id: '1234', mode: 'soft' });
```

```javascript
// Supprime de la base de données l'entité Project
// avec les critères :
// `id === '1234'`
// `mode === 'hard`
await Entities('Project').delete({ id: '1234', mode: 'hard' });
```

```javascript
// Supprime de la base de données l'entité Project
// avec les critères :
// `id === '1234'`
// `mode === 'full`
await Entities('Project').delete({ id: '1234', mode: 'full' });
```

***

# Purger une entité Project

```javascript
await Entities('Project').purge(project, {
  Project: {
    keep: ['externalId'],
    Customer: {
      keep: ['externalId']
    },
    Offer: {
      delete: ['price'],
      Pack: {
        keep: ['externalId'],
        Pricing: {
          Price: {
            delete: ['beneficiary']
          }
        }
      }
    }
  }
});
```
