---
title: Entité
slug: oip-next/v4/reference/headless-proxy/entity
icon: {"lucideIcon":"📘"}
createdAt: 2025-10-09T13:59:59.000Z
---

# Construction d'une entité : la fonction $\[EntityType]

La fonction `$[EntityType]` permet de manipuler l'entité de type `EntityType`.

La signature de cette fonction diffère selon si l'entité a ou n'a pas de relations ascendantes dans l'arbre des entités. Si elle en a, alors le premier paramètre de la fonction `$[EntityType]` est toujours l'entité parente.

## Création d'une entité

Sans paramètre ou avec un paramètre nul (autre que l'entité parente le cas échéant), la fonction `$[EntityType]` retourne une nouvelle instance de l'entité.

```javascript
// Create new Project entity
await $Project();
await $Project(null);
await $Project(undefined);
```

:::BlockQuote
Ces trois appels sont équivalents.
:::

La version avec un paramètre `null` ou `undefined` est nécessaire lorsque la fonction `$[EntityType]` est utilisée avec des options.

```javascript
// Create new Project entity in a transaction
await $Project(null, { transactionId: 'c53f36da-6ac1-4b19-a66d-7d756dc4fbc6' });
```

### create\[EntityType]

En supplément de la fonction `$[EntityType],` la fonction `create[EntityType]` permet de créer une entité de type `EntityType`.

```javascript
let p1 = await createProject(); // p1 is a Project entity
let p2 = await createProject({ externalId: '1'}); // p1 is a Project entity, initialized with an externalId
let c1 = await createCustomer(p1); // c1 is a Customer entity linked to p1
let c2 = await createCustomer(p1, { name: 'a' }); // c2 is a Customer entity linked to p1, initialized with a name
```

:::BlockQuote
Les données passées à `create[EntityType]` sont validées avant la création de l'entité (type et validateurs s'ils existent).
:::

## Récupération d'entités

Avec un paramètre (autre que l'entité parente le cas échéant), la fonction `$[EntityType]` retourne la ou les entités correspondant au paramètre qui est traité comme un filtre. Un second paramètre peut être ajouté pour modifier le comportement de cette fonction de recherche :

- `create: boolean` : définit le traitement à effectuer quand la recherche ne produit aucun résultat ;
  - `true` : si aucune entité ne correspond au filtre de recherche, alors une nouvelle entité est créée et retournée ;
  - `false` : si aucune entité ne correspond au filtre de recherche, aucun traitement particulier n'est effectué. Valeur par défaut ;
- `list: boolean` : définit le type de retour de la fonction de recherche :
  - `true` : le résultat de la recherche est une liste ;
  - `false` : le résultat de la recherche est une liste uniquement si le nombre de résultats est strictement supérieur à 1. Ainsi, selon le nombre de résultats, le type de retour avec cette option est : `null | T | T[]`. Valeur par défaut ;
- `orderBy: [string, string]` : définit le tri à appliquer aux résultats de recherche :
  - Une liste de deux éléments : le premier est le nom d'une propriété de l'entité et le second est `asc` ou `desc` ;
- `limit: number` : définit le nombre maximum de résultats de recherche à retourner :
  - Un entier naturel ;
- `offset: number` : définit le nombre d'éléments à ignorer avant la récupération :
  - Un entier naturel.

:::BlockQuote
Une liste d'entités est toujours triée : soit par la propriété définie via l'option `orderBy` si elle est présente, soit par la propriété `__createdAt`.
:::

:::hint{type="info"}
**Le filtre peut être un objet ou une chaîne de caractères.**
Si le filtre est une chaîne de caractères, il est traité comme un identifiant.

Si le filtre est un objet, il est traité comme la conjonction de critères de recherche. Par exemple, l'objet `{ key1: value1, key2: value2 }` correspond à la recherche `key1 === value1 && key2 === value2`.
:::

```javascript
// Find all Project entities,
// with externalId=1234
await $Project({ externalId: '1234' });

// Find a Project entity,
// with __id=415d422e-54de-4c4e-a7e0-1873ba6410e4
await $Project('415d422e-54de-4c4e-a7e0-1873ba6410e4');

// Find all Customer entities linked to given Project entity,
// with firstName=foo and lastName=bar,
// create a new Customer entity if it does not exist,
// and set firstName to foo and lastName to bar
await $Customer(project, { firstName: 'foo', lastName: 'bar' }, { create: true });

// Find a Customer entity linked to given Project entity,
// with __id=e1e15b78-5ff9-46eb-889e-9d7426188e13
await $Customer(project, 'e1e15b78-5ff9-46eb-889e-9d7426188e13');

// Get a subset (1 element) of all Project entities
// ordered by external id
await $Project({}, { orderBy: ['externalId', 'asc'], limit: 1, offset: 0 });

// Get a subset (1 element) of all Customer entities linked to given Project entity,
// omitting the first customer ordered by first name
await $Customer(project, {}, { orderBy: ['firstName', 'asc'], limit: 1, offset: 1 });
```

### list\[EntityType]

En supplément de la fonction `$[EntityType],` la fonction `list[EntityType]` permet de rechercher des entités de type `EntityType`.

```javascript
// Find all Project entities
await listProject();
await listProject(null);
await listProject(undefined);
await listProject({});

// Find all Project entities,
// with externalId=1234
await listProject({ externalId: '1234' });

// Find all Customer entities linked to given Project entity
await listCustomer(project);
await listCustomer(project, null);
await listCustomer(project, undefined);
await listCustomer(project, {});

// Find all Customer entities linked to given Project entity,
// with firstName=foo and lastName=bar,
// create a new Customer entity if it does not exist,
// and set firstName to foo and lastName to bar
await listCustomer(project, { firstName: 'foo', lastName: 'bar' }, { create: true });
```

:::BlockQuote
Le type de retour de la fonction `list[EntityType]` est toujours une liste.
:::

:::BlockQuote
La fonction `list[EntityType]` accepte les mêmes options que la fonction `$[EntityType]`, à l'exception de l'option `list`.
:::

### get\[EntityType]

En supplément de la fonction `$[EntityType],` la fonction `get[EntityType]` permet de rechercher une entité de type `EntityType`.

```javascript
// Find a Project entity
await getProject();
await getProject(null);
await getProject(undefined);
await getProject({});

// Find a Project entity,
// with externalId=1234
await getProject({ externalId: '1234' });

// Find a Customer entity linked to given Project entity
await getCustomer(project);
await getCustomer(project, null);
await getCustomer(project, undefined);
await getCustomer(project, {});

// Find a Customer entity linked to given Project entity,
// with firstName=foo and lastName=bar,
// create a new Customer entity if it does not exist,
// and set firstName to foo and lastName to bar
await getCustomer(project, { firstName: 'foo', lastName: 'bar' }, { create: true });
```

:::BlockQuote
Le type de retour de la fonction `get[EntityType]` est `T | null`.
:::

:::BlockQuote
Si plusieurs entités correspondent aux critères de recherche passés à la fonction `get[EntityType]`, alors le résultat de cette dernière est `null`. Une valeur de retour `null` signifie donc 0 ou plus de 1 résultat.
:::

### Filtrage avancé

Une syntaxe étendue est disponible pour utiliser davantage d'opérateurs pour le filtrage. Pour cela, il faut passer un objet de la forme `{ $search: { from: [QUERY] }}` ; `QUERY` est défini par `[op, key, value] | ['&&', QUERY] | ['||', QUERY]`, où `op` est l'un des opérateurs de comparaison disponibles.

Les opérateurs de comparaison disponibles sont :

- `==` ;
- `!=` ;
- `<` ;
- `<=` ;
- `>` ;
- `>=` ;
- `~~` : teste une expression régulière ;
- `~~*` : teste une expression régulière (casse ignorée) ;
- `!~~` : teste la négation d'une expression régulière ;
- `!~~*` : teste une expression régulière (casse ignorée) ;
- `in` : teste l'appartenance à une liste.

```javascript
// Find all Project entities,
// with externalId=1
$Project({ $search: { from: ['==', 'externalId', '1'] } })

// Find all Project entities,
// with externalId matching the regular expression /^1/
$Project({ $search: { from: ['~~', 'externalId', '^1'] } })

// Find all Project entities,
// with externalId=1
// or __updatedAt>2025-05-21T09:48:23.398Z
$Project({ $search: { from: ['||', ['==', 'externalId', '1'], ['>', '__updatedAt', '2025-05-21T09:48:23.398Z']] } })
```

### Filtrage avancé pour l'entité racine Project

:::BlockQuote
Ce filtrage avancé est uniquement disponible pour la recherche d'entités de type Project.
:::

Une extension du filtrage est disponible pour l'entité `Project` permettant de rechercher en fonction de critères sur des entités enfants. Pour cela, il faut passer un objet `{ $search: { with: [QUERY] }}`.

```javascript
// Find all Project entities,
// having a Company entity with name=c1 and siret=1234
$Project({
  $search: {
    with: [
      [['Company'], [["&&", ["==", "name", "c1"], ["==", "siret", "1234"]]]]
    ]
  }
})

// Find all Project entities,
// having a Company entity with name=c1 and siret=1234
//   having a Address entity with street=foo
$Project({
  $search: {
    with: [
      [['Company', 'Address'], [["&&", ["==", "name", "c1"], ["==", "siret", "1234"]], ["==", "street", "foo"]]]
    ]
  }
})
```

Il est possible de combiner les clés `from` et `with` pour la recherche d'entités `Project`. Par exemple :

```javascript
// Find all Project entities,
// with externalId=1
// having a Company entity with name=c1 and siret=1234
$Project({
  $search: {
    from: ['==', 'externalId', '1'],
    with: [
      [['Company'], [["&&", ["==", "name", "c1"], ["==", "siret", "1234"]]]]
    ]
  }
})
```

## Gestion des erreurs

Si le service OIP Headless envoie une réponse avec un statut dont la valeur est égale à 401 ou supérieure ou égale à 422, alors une exception sera levée.

# Mise à jour d'une entité

La fonction `update[EntityType]` permet de mettre à jour une entité de type `EntityType`.

```javascript
let project; // A valid Project entity
project = await updateProject(project);
```

:::BlockQuote
**Info**
Seules les propriétés passées en paramètre sont mises à jour. Les autres propriétés restent inchangées.
:::

## Gestion des erreurs

- Cette fonction lève une erreur si l'entité passée en paramètre n'a pas le bon type.
- Si le service OIP Headless envoie une réponse avec un statut dont la valeur est égale à 401 ou supérieure ou égale à 422, alors une erreur sera levée.

# Suppression d'une entité

La fonction `delete[EntityType]` permet de supprimer une entité de type `EntityType`.

```javascript
let project; // A valid Project entity
project = await deleteProject(project);
```

## Gestion des erreurs

- Cette fonction lève une erreur si l'entité passée en paramètre n'a pas le bon type.
- Si le service OIP Headless envoie une réponse avec un statut dont la valeur est égale à 401 ou supérieure ou égale à 422, alors une erreur sera levée.

# Création d'entités en masse

La fonction `import[EntityType]List` permet de créer plusieurs entités du même type et de les rattacher à une entité parente ; le nombre d'entités créées est retourné.

```javascript
let project; // A valid Project entity

const count = await importCustomerList(project, [
  { firstName: 'a0', lastName: 'b0' },
  { firstName: 'a1', lastName: 'b1' },
  { firstName: 'a2', lastName: 'b2' }
]);
```

:::BlockQuote
Cette fonction doit être réservée à la création simultanée d'un grand nombre d'entités du même type.
:::

## Gestion des erreurs

Si le service OIP Headless envoie une réponse avec un statut dont la valeur est égale à 401 ou supérieure ou égale à 422, alors une erreur sera levée.

# Manipulation des propriétés d'une entité : les accesseurs

Pour chaque propriété, deux fonctions sont générées (une seule si la propriété est en lecture seule).

## Lecture

Le nom de la fonction de lecture de la propriété est : `get[EntityType][PropertyName]`.

Cette fonction prend en paramètre une entité.

## Ecriture

Le nom de la fonction d'écriture de la propriété est : `set[EntityType][PropertyName]`.

Cette fonction est currifiée ; elle prend en premier paramètre une valeur et en second paramètre une entité.

## Gestion des erreurs

Ces fonctions lèvent une erreur si l'entité passée en paramètre n'a pas le bon type.

## Exemple

```javascript
let grantee; // A valid Grantee entity
const granteeFirstName = getGranteeFirstName(grantee);
grantee = setGranteeFirstName('foo', grantee);
```

# Annulation d'opérations

La fonction `rollbackTransaction` permet d'annuler toutes les opérations d'écriture sur une ou plusieurs entités.

## Gestion des erreurs

Si le service OIP Headless envoie une réponse avec un statut dont la valeur est égale à 401 ou supérieure ou égale à 422, alors une erreur sera levée.

## Exemple

```javascript
import { rollbackTransaction } from '@fasstech/oip-core/transactions';

const transactionId = 'da2d6905-8ff1-4949-acce-aeb39d83a591';
let project = await $Project();
project = setProjectExternalId('1234', project);
project = await updateProject(project, { transactionId });
await rollbackTransaction(transactionId);
// Here, project.externalId is no longer equals to '1234'.
```
