Entités

Une entité représente une structure de données métier, composée de plusieurs propriétés. Chaque propriété est typée via un NewType.

Exemple

INFO

En général on préfère définir une fonction create() plutôt que d'utiliser la fonction new() pour prévenir les cas de valeur par défaut.

Fonctionnement

C.createEntity(...) retourne un handler d'entité.

Ce handler vous donne deux manières de construire une entité :

• map(...) / mapOrThrow(...) : à partir de propriétés brutes (ex: payload HTTP, DB, etc.). Les valeurs passent par les DataParser de chaque NewType et les contraintes associées.

• new(...) : à partir de propriétés déjà typées (utile quand vous êtes déjà dans du code métier).

L'entité créée est ensuite identifiable avec is(...) (type guard), ce qui facilite le narrowing dans des unions.

Définir les propriétés

La définition des propriétés se fait via un callback : vous retournez un objet où chaque clé est une propriété métier, et chaque valeur est un NewTypeHandler (ou une définition avancée).

Le callback reçoit params, qui expose des helpers pour enrichir la définition :

nullable(definition)

Autorise null sur une propriété.

array(definition, { min?, max? })

Déclare une propriété sous forme de tableau, avec min/max optionnels (validation runtime + typage).

Quand max est déclaré et que vous construisez une entité avec new(...), la propriété doit déjà porter la contrainte de type MaxElements correspondante. Utilisez A.withMaxElements sur les tuples finis pour respecter ce contrat. Ce n'est pas nécessaire avec map(...) ou mapOrThrow(...), car les tableaux bruts sont validés et contraints pendant le mapping.

union(...definitions)

Déclare une union de plusieurs NewTypeHandler pour une même propriété.

structure(definition)

Déclare une propriété structurée (objet) dont chaque champ possède sa propre définition de propriété d'entité.

Pratique pour modéliser des sous-objets métier imbriqués sans créer une entité séparée.

identifier(definition)

Déclare une propriété littérale de type string (ex: "profile", "agent"), validée strictement au runtime.

Ce helper est destiné à l'identification technique (discrimination, version/tag de structure, etc.), pas à porter de la donnée métier libre. Pour une valeur métier textuelle, utilisez plutôt un NewType.

Ces helpers sont combinables (ex: nullable(array(...)), structure({ type: identifier("agent") })), et ils servent autant au runtime (validation) qu'au typage.

Méthodes et Propriétés

Un EntityHandler expose :

Méthodes

new()

Construit l'entité à partir de propriétés déjà typées.

function new(
	properties: Properties
): Entity<EntityName> & Properties

map()

Valide et transforme des propriétés brutes en propriétés typées, puis construit l'entité. Un callback optionnel peut ensuite raffiner l'entité avec des règles métier ou lui ajouter des flags.

function map(
	rawProperties: PropertiesToMapOfEntity,
	refineEntity?: (entity: Entity) => Right | Left
): Right<"hydratedEntity", Entity> | Left<"hydrateEntityError", DP.DataParserError> | RefinerResult

function map(
	refineEntity: (entity: Entity) => Right | Left
): (rawProperties: PropertiesToMapOfEntity) => Left<"hydrateEntityError", DP.DataParserError> | RefinerResult

rawProperties est volontairement permissif : certaines contraintes (par exemple array(..., { min })) sont vérifiées au moment de la validation.

Sans callback, un mapping réussi renvoie Right<"hydratedEntity", Entity>. Avec un callback, son Right ou son Left est renvoyé tel quel et son type précis est conservé. Le callback n'est pas appelé si l'hydratation échoue.

mapOrThrow()

function mapOrThrow(
	rawProperties: PropertiesToMapOfEntity,
	refineEntity?: (entity: Entity) => Right | Left
): Entity | RefinedEntity

function mapOrThrow(
	refineEntity: (entity: Entity) => Right | Left
): (rawProperties: PropertiesToMapOfEntity) => RefinedEntity

Lève C.HydrateEntityError si les propriétés brutes ne peuvent pas être hydratées. Si le callback de raffinement renvoie un Left, la méthode lève C.RefineEntityError. Sinon, elle renvoie directement la valeur déballée du Right.

Les deux méthodes acceptent le raffinement en second argument ou sous forme curryfiée, notamment pour une utilisation avec pipe :

is()

function is(
	value: unknown
): value is Entity<EntityName>

update()

Met a jour une entite existante en fusionnant des proprietes typees.

function update(
	entity: Entity<EntityName>,
	properties: Partial<Properties>
): Entity<EntityName> & Properties

Propriétés

name

Le nom unique de l'entité (ex: "User"), utilisé comme identifiant runtime.

propertiesDefinition

La définition des propriétés (telle que déclarée dans createEntity).

Récupérer le type

Pour récupérer le type de l'entité générée :

type User = C.GetEntity<typeof User>;

Voir aussi

• newType
• unwrapEntity
• flag