Entité
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);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 nameRé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.
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 });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 });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
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);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' }
]);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'.