Entité

26 min

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é.

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

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.

// 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.

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

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.

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.

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.

// 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.

// 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 });

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

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.

// 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 });

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

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.

// 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

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] }}.

// 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 :

// 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.

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

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.

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é.

let project; // A valid Project entity

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

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

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

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'.